Interface TableChange

All Known Subinterfaces:
TableChange.ColumnChange
All Known Implementing Classes:
TableChange.AddColumn, TableChange.DeleteColumn, 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
  • 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

      static TableChange updateColumnDefaultValue(String[] fieldNames, String 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 string (Spark SQL dialect).
      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