Package org.apache.spark.sql.connector.catalog

Interface TableChange

All Known Subinterfaces:

TableChange.ColumnChange

All Known Implementing Classes:

TableChange.AddColumn, TableChange.AddConstraint, TableChange.ClusterBy, TableChange.DeleteColumn, TableChange.DropConstraint, TableChange.RemoveProperty, TableChange.RenameColumn, TableChange.SetProperty, TableChange.UpdateColumnComment, TableChange.UpdateColumnDefaultValue, TableChange.UpdateColumnNullability, TableChange.UpdateColumnPosition, TableChange.UpdateColumnType

@Evolving
public interface TableChange

TableChange subclasses represent requested changes to a table. These are passed to TableCatalog.alterTable(org.apache.spark.sql.connector.catalog.Identifier, org.apache.spark.sql.connector.catalog.TableChange...). For example,

   import TableChange._
   val catalog = Catalogs.load(name)
   catalog.asTableCatalog.alterTable(ident,
       addColumn("x", IntegerType),
       renameColumn("a", "b"),
       deleteColumn("c")
     )
 

Since:

3.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	TableChange.AddColumn	A TableChange to add a field.
static final class	TableChange.AddConstraint	A TableChange to alter table and add a constraint.
static final class	TableChange.After	Column position AFTER means the specified column should be put after the given `column`.
static final class	TableChange.ClusterBy	A TableChange to alter clustering columns for a table.
static interface	TableChange.ColumnChange
static interface	TableChange.ColumnPosition
static final class	TableChange.DeleteColumn	A TableChange to delete a field.
static final class	TableChange.DropConstraint	A TableChange to alter table and drop a constraint.
static final class	TableChange.First	Column position FIRST means the specified column should be the first column.
static final class	TableChange.RemoveProperty	A TableChange to remove a table property.
static final class	TableChange.RenameColumn	A TableChange to rename a field.
static final class	TableChange.SetProperty	A TableChange to set a table property.
static final class	TableChange.UpdateColumnComment	A TableChange to update the comment of a field.
static final class	TableChange.UpdateColumnDefaultValue	A TableChange to update the default value of a field.
static final class	TableChange.UpdateColumnNullability	A TableChange to update the nullability of a field.
static final class	TableChange.UpdateColumnPosition	A TableChange to update the position of a field.
static final class	TableChange.UpdateColumnType	A TableChange to update the type of a field.

Method Summary

Modifier and Type	Method	Description
static TableChange	addColumn(String[] fieldNames, DataType dataType)	Create a TableChange for adding an optional column.
static TableChange	addColumn(String[] fieldNames, DataType dataType, boolean isNullable)	Create a TableChange for adding a column.
static TableChange	addColumn(String[] fieldNames, DataType dataType, boolean isNullable, String comment)	Create a TableChange for adding a column.
static TableChange	addColumn(String[] fieldNames, DataType dataType, boolean isNullable, String comment, TableChange.ColumnPosition position, ColumnDefaultValue defaultValue)	Create a TableChange for adding a column.
static TableChange	addConstraint(Constraint constraint, String validatedTableVersion)	Create a TableChange for adding a new table constraint
static TableChange	clusterBy(NamedReference[] clusteringColumns)	Create a TableChange for changing clustering columns for a table.
static TableChange	deleteColumn(String[] fieldNames, Boolean ifExists)	Create a TableChange for deleting a field.
static TableChange	dropConstraint(String name, boolean ifExists, boolean cascade)	Create a TableChange for dropping a table constraint
static TableChange	removeProperty(String property)	Create a TableChange for removing a table property.
static TableChange	renameColumn(String[] fieldNames, String newName)	Create a TableChange for renaming a field.
static TableChange	setProperty(String property, String value)	Create a TableChange for setting a table property.
static TableChange	updateColumnComment(String[] fieldNames, String newComment)	Create a TableChange for updating the comment of a field.
static TableChange	updateColumnDefaultValue(String[] fieldNames, String newDefaultValue)	Deprecated. Please use updateColumnDefaultValue(String[], DefaultValue) instead.
static TableChange	updateColumnDefaultValue(String[] fieldNames, DefaultValue newDefaultValue)	Create a TableChange for updating the default value of a field.
static TableChange	updateColumnNullability(String[] fieldNames, boolean nullable)	Create a TableChange for updating the nullability of a field.
static TableChange	updateColumnPosition(String[] fieldNames, TableChange.ColumnPosition newPosition)	Create a TableChange for updating the position of a field.
static TableChange	updateColumnType(String[] fieldNames, DataType newDataType)	Create a TableChange for updating the type of a field that is nullable.

Method Details

setProperty

static TableChange setProperty(String property,
 String value)

Create a TableChange for setting a table property.

If the property already exists, it will be replaced with the new value.

Parameters:

property - the property name

value - the new property value

Returns:

a TableChange for the addition

removeProperty

static TableChange removeProperty(String property)

Create a TableChange for removing a table property.

If the property does not exist, the change will succeed.

Parameters:

property - the property name

Returns:

a TableChange for the addition

addColumn

static TableChange addColumn(String[] fieldNames,
 DataType dataType)

Create a TableChange for adding an optional column.

If the field already exists, the change will result in an IllegalArgumentException. If the new field is nested and its parent does not exist or is not a struct, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the new column

dataType - the new column's data type

Returns:

a TableChange for the addition

addColumn

static TableChange addColumn(String[] fieldNames,
 DataType dataType,
 boolean isNullable)

Create a TableChange for adding a column.

If the field already exists, the change will result in an IllegalArgumentException. If the new field is nested and its parent does not exist or is not a struct, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the new column

dataType - the new column's data type

isNullable - whether the new column can contain null

Returns:

a TableChange for the addition

addColumn

static TableChange addColumn(String[] fieldNames,
 DataType dataType,
 boolean isNullable,
 String comment)

Create a TableChange for adding a column.

If the field already exists, the change will result in an IllegalArgumentException. If the new field is nested and its parent does not exist or is not a struct, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the new column

dataType - the new column's data type

isNullable - whether the new column can contain null

comment - the new field's comment string

Returns:

a TableChange for the addition

addColumn

static TableChange addColumn(String[] fieldNames,
 DataType dataType,
 boolean isNullable,
 String comment,
 TableChange.ColumnPosition position,
 ColumnDefaultValue defaultValue)

Create a TableChange for adding a column.

If the field already exists, the change will result in an IllegalArgumentException. If the new field is nested and its parent does not exist or is not a struct, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the new column

dataType - the new column's data type

isNullable - whether the new column can contain null

comment - the new field's comment string

position - the new columns's position

defaultValue - default value to return when scanning from the new column, if any

Returns:

a TableChange for the addition

renameColumn

static TableChange renameColumn(String[] fieldNames,
 String newName)

Create a TableChange for renaming a field.

The name is used to find the field to rename. The new name will replace the leaf field name. For example, renameColumn(["a", "b", "c"], "x") should produce column a.b.x.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - the current field names

newName - the new name

Returns:

a TableChange for the rename

updateColumnType

static TableChange updateColumnType(String[] fieldNames,
 DataType newDataType)

Create a TableChange for updating the type of a field that is nullable.

The field names are used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

newDataType - the new data type

Returns:

a TableChange for the update

updateColumnNullability

static TableChange updateColumnNullability(String[] fieldNames,
 boolean nullable)

Create a TableChange for updating the nullability of a field.

The name is used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

nullable - the nullability

Returns:

a TableChange for the update

updateColumnComment

static TableChange updateColumnComment(String[] fieldNames,
 String newComment)

Create a TableChange for updating the comment of a field.

The name is used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

newComment - the new comment

Returns:

a TableChange for the update

updateColumnPosition

static TableChange updateColumnPosition(String[] fieldNames,
 TableChange.ColumnPosition newPosition)

Create a TableChange for updating the position of a field.

The name is used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

newPosition - the new position

Returns:

a TableChange for the update

updateColumnDefaultValue

@Deprecated(since="4.1.0")
static TableChange updateColumnDefaultValue(String[] fieldNames,
 String newDefaultValue)

Deprecated.

Please use updateColumnDefaultValue(String[], DefaultValue) instead.

Create a TableChange for updating the default value of a field.

The name is used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

newDefaultValue - the new default value SQL string (Spark SQL dialect).

Returns:

a TableChange for the update

updateColumnDefaultValue

static TableChange updateColumnDefaultValue(String[] fieldNames,
 DefaultValue newDefaultValue)

Create a TableChange for updating the default value of a field.

The name is used to find the field to update.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to update

newDefaultValue - the new default value SQL (Spark SQL dialect and V2 expression representation if it can be converted). Null indicates dropping column default value

Returns:

a TableChange for the update

deleteColumn

static TableChange deleteColumn(String[] fieldNames,
 Boolean ifExists)

Create a TableChange for deleting a field.

If the field does not exist, the change will result in an IllegalArgumentException.

Parameters:

fieldNames - field names of the column to delete

ifExists - silence the error if column doesn't exist during drop

Returns:

a TableChange for the delete

clusterBy

static TableChange clusterBy(NamedReference[] clusteringColumns)

Create a TableChange for changing clustering columns for a table.

Parameters:

clusteringColumns - clustering columns to change to. Each clustering column represents field names.

Returns:

a TableChange for this assignment

addConstraint

static TableChange addConstraint(Constraint constraint,
 String validatedTableVersion)

Create a TableChange for adding a new table constraint

dropConstraint

static TableChange dropConstraint(String name,
 boolean ifExists,
 boolean cascade)

Create a TableChange for dropping a table constraint