public interface UpdateSchema extends PendingUpdate<Schema>
When committing, these changes will be applied to the current table metadata. Commit conflicts
will not be resolved and will result in a CommitFailedException
.
Modifier and Type | Method and Description |
---|---|
default UpdateSchema |
addColumn(java.lang.String parent,
java.lang.String name,
Type type)
Add a new column to a nested struct.
|
UpdateSchema |
addColumn(java.lang.String parent,
java.lang.String name,
Type type,
java.lang.String doc)
Add a new column to a nested struct.
|
default UpdateSchema |
addColumn(java.lang.String name,
Type type)
Add a new top-level column.
|
UpdateSchema |
addColumn(java.lang.String name,
Type type,
java.lang.String doc)
Add a new top-level column.
|
default UpdateSchema |
addRequiredColumn(java.lang.String parent,
java.lang.String name,
Type type)
Add a new required top-level column.
|
UpdateSchema |
addRequiredColumn(java.lang.String parent,
java.lang.String name,
Type type,
java.lang.String doc)
Add a new required top-level column.
|
default UpdateSchema |
addRequiredColumn(java.lang.String name,
Type type)
Add a new required top-level column.
|
UpdateSchema |
addRequiredColumn(java.lang.String name,
Type type,
java.lang.String doc)
Add a new required top-level column.
|
UpdateSchema |
allowIncompatibleChanges()
Allow incompatible changes to the schema.
|
default UpdateSchema |
caseSensitive(boolean caseSensitive)
Determines if the case of schema needs to be considered when comparing column names
|
UpdateSchema |
deleteColumn(java.lang.String name)
Delete a column in the schema.
|
UpdateSchema |
makeColumnOptional(java.lang.String name)
Update a column to optional.
|
UpdateSchema |
moveAfter(java.lang.String name,
java.lang.String afterName)
Move a column from its current position to directly after a reference column.
|
UpdateSchema |
moveBefore(java.lang.String name,
java.lang.String beforeName)
Move a column from its current position to directly before a reference column.
|
UpdateSchema |
moveFirst(java.lang.String name)
Move a column from its current position to the start of the schema or its parent struct.
|
UpdateSchema |
renameColumn(java.lang.String name,
java.lang.String newName)
Rename a column in the schema.
|
UpdateSchema |
requireColumn(java.lang.String name)
Update a column to required.
|
UpdateSchema |
setIdentifierFields(java.util.Collection<java.lang.String> names)
Set the identifier fields given a set of field names.
|
default UpdateSchema |
setIdentifierFields(java.lang.String... names)
Set the identifier fields given some field names.
|
UpdateSchema |
unionByNameWith(Schema newSchema)
Applies all field additions and updates from the provided new schema to the existing schema so
to create a union schema.
|
UpdateSchema |
updateColumn(java.lang.String name,
Type.PrimitiveType newType)
Update a column in the schema to a new primitive type.
|
default UpdateSchema |
updateColumn(java.lang.String name,
Type.PrimitiveType newType,
java.lang.String newDoc)
Update a column in the schema to a new primitive type.
|
UpdateSchema |
updateColumnDoc(java.lang.String name,
java.lang.String newDoc)
Update a column in the schema to a new primitive type.
|
apply, commit, updateEvent
UpdateSchema allowIncompatibleChanges()
Incompatible changes can cause failures when attempting to read older data files. For example, adding a required column and attempting to read data files without that column will cause a failure. However, if there are no data files that are not compatible with the change, it can be allowed.
This option allows incompatible changes to be made to a schema. This should be used when the
caller has validated that the change will not break. For example, if a column is added as
optional but always populated and data older than the column addition has been deleted from the
table, this can be used with requireColumn(String)
to mark the column required.
default UpdateSchema addColumn(java.lang.String name, Type type)
Because "." may be interpreted as a column path separator or may be used in field names, it
is not allowed in names passed to this method. To add to nested structures or to add fields
with names that contain ".", use addColumn(String, String, Type)
.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
name
- name for the new columntype
- type for the new columnjava.lang.IllegalArgumentException
- If name contains "."UpdateSchema addColumn(java.lang.String name, Type type, java.lang.String doc)
Because "." may be interpreted as a column path separator or may be used in field names, it
is not allowed in names passed to this method. To add to nested structures or to add fields
with names that contain ".", use addColumn(String, String, Type)
.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
name
- name for the new columntype
- type for the new columndoc
- documentation string for the new columnjava.lang.IllegalArgumentException
- If name contains "."default UpdateSchema addColumn(java.lang.String parent, java.lang.String name, Type type)
The parent name is used to find the parent using Schema.findField(String)
. If the
parent name is null, the new column will be added to the root as a top-level column. If parent
identifies a struct, a new column is added to that struct. If it identifies a list, the column
is added to the list element struct, and if it identifies a map, the new column is added to the
map's value struct.
The given name is used to name the new column and names containing "." are not handled differently.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
parent
- name of the parent struct to the column will be added toname
- name for the new columntype
- type for the new columnjava.lang.IllegalArgumentException
- If parent doesn't identify a structUpdateSchema addColumn(java.lang.String parent, java.lang.String name, Type type, java.lang.String doc)
The parent name is used to find the parent using Schema.findField(String)
. If the
parent name is null, the new column will be added to the root as a top-level column. If parent
identifies a struct, a new column is added to that struct. If it identifies a list, the column
is added to the list element struct, and if it identifies a map, the new column is added to the
map's value struct.
The given name is used to name the new column and names containing "." are not handled differently.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
parent
- name of the parent struct to the column will be added toname
- name for the new columntype
- type for the new columndoc
- documentation string for the new columnjava.lang.IllegalArgumentException
- If parent doesn't identify a structdefault UpdateSchema addRequiredColumn(java.lang.String name, Type type)
This is an incompatible change that can break reading older data. This method will result in
an exception unless allowIncompatibleChanges()
has been called.
Because "." may be interpreted as a column path separator or may be used in field names, it
is not allowed in names passed to this method. To add to nested structures or to add fields
with names that contain ".", use addRequiredColumn(String, String, Type)
.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
name
- name for the new columntype
- type for the new columnjava.lang.IllegalArgumentException
- If name contains "."UpdateSchema addRequiredColumn(java.lang.String name, Type type, java.lang.String doc)
This is an incompatible change that can break reading older data. This method will result in
an exception unless allowIncompatibleChanges()
has been called.
Because "." may be interpreted as a column path separator or may be used in field names, it
is not allowed in names passed to this method. To add to nested structures or to add fields
with names that contain ".", use addRequiredColumn(String, String, Type)
.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
name
- name for the new columntype
- type for the new columndoc
- documentation string for the new columnjava.lang.IllegalArgumentException
- If name contains "."default UpdateSchema addRequiredColumn(java.lang.String parent, java.lang.String name, Type type)
This is an incompatible change that can break reading older data. This method will result in
an exception unless allowIncompatibleChanges()
has been called.
The parent name is used to find the parent using Schema.findField(String)
. If the
parent name is null, the new column will be added to the root as a top-level column. If parent
identifies a struct, a new column is added to that struct. If it identifies a list, the column
is added to the list element struct, and if it identifies a map, the new column is added to the
map's value struct.
The given name is used to name the new column and names containing "." are not handled differently.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
parent
- name of the parent struct to the column will be added toname
- name for the new columntype
- type for the new columnjava.lang.IllegalArgumentException
- If parent doesn't identify a structUpdateSchema addRequiredColumn(java.lang.String parent, java.lang.String name, Type type, java.lang.String doc)
This is an incompatible change that can break reading older data. This method will result in
an exception unless allowIncompatibleChanges()
has been called.
The parent name is used to find the parent using Schema.findField(String)
. If the
parent name is null, the new column will be added to the root as a top-level column. If parent
identifies a struct, a new column is added to that struct. If it identifies a list, the column
is added to the list element struct, and if it identifies a map, the new column is added to the
map's value struct.
The given name is used to name the new column and names containing "." are not handled differently.
If type is a nested type, its field IDs are reassigned when added to the existing schema.
parent
- name of the parent struct to the column will be added toname
- name for the new columntype
- type for the new columndoc
- documentation string for the new columnjava.lang.IllegalArgumentException
- If parent doesn't identify a structUpdateSchema renameColumn(java.lang.String name, java.lang.String newName)
The name is used to find the column to rename using Schema.findField(String)
.
The new name may contain "." and such names are not parsed or handled differently.
Columns may be updated and renamed in the same schema update.
name
- name of the column to renamenewName
- replacement name for the columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change conflicts with other additions, renames, or updates.UpdateSchema updateColumn(java.lang.String name, Type.PrimitiveType newType)
The name is used to find the column to update using Schema.findField(String)
.
Only updates that widen types are allowed.
Columns may be updated and renamed in the same schema update.
name
- name of the column to renamenewType
- replacement type for the columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change introduces a type incompatibility or if it conflicts with other additions, renames,
or updates.default UpdateSchema updateColumn(java.lang.String name, Type.PrimitiveType newType, java.lang.String newDoc)
The name is used to find the column to update using Schema.findField(String)
.
Only updates that widen types are allowed.
Columns may be updated and renamed in the same schema update.
name
- name of the column to renamenewType
- replacement type for the columnnewDoc
- replacement documentation string for the columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change introduces a type incompatibility or if it conflicts with other additions, renames,
or updates.UpdateSchema updateColumnDoc(java.lang.String name, java.lang.String newDoc)
The name is used to find the column to update using Schema.findField(String)
.
Columns may be updated and renamed in the same schema update.
name
- name of the column to renamenewDoc
- replacement documentation string for the columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change introduces a type incompatibility or if it conflicts with other additions, renames,
or updates.UpdateSchema makeColumnOptional(java.lang.String name)
name
- name of the column to mark optionalUpdateSchema requireColumn(java.lang.String name)
This is an incompatible change that can break reading older data. This method will result in
an exception unless allowIncompatibleChanges()
has been called.
name
- name of the column to mark requiredUpdateSchema deleteColumn(java.lang.String name)
The name is used to find the column to delete using Schema.findField(String)
.
name
- name of the column to deletejava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change conflicts with other additions, renames, or updates.UpdateSchema moveFirst(java.lang.String name)
name
- name of the column to movejava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change conflicts with other changes.UpdateSchema moveBefore(java.lang.String name, java.lang.String beforeName)
The name is used to find the column to move using Schema.findField(String)
. If the
name identifies a nested column, it can only be moved within the nested struct that contains
it.
name
- name of the column to movebeforeName
- name of the reference columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change conflicts with other changes.UpdateSchema moveAfter(java.lang.String name, java.lang.String afterName)
The name is used to find the column to move using Schema.findField(String)
. If the
name identifies a nested column, it can only be moved within the nested struct that contains
it.
name
- name of the column to moveafterName
- name of the reference columnjava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change conflicts with other changes.UpdateSchema unionByNameWith(Schema newSchema)
For fields with same canonical names in both schemas it is required that the widen types is
supported using updateColumn(String, Type.PrimitiveType)
Only supports turning a previously required field into an optional one if it is marked
optional in the provided new schema using makeColumnOptional(String)
Only supports updating existing field docs with fields docs from the provided new schema
using updateColumnDoc(String, String)
newSchema
- a schema used in conjunction with the existing schema to create a union schemajava.lang.IllegalStateException
- If it encounters errors during provided schema traversaljava.lang.IllegalArgumentException
- If name doesn't identify a column in the schema or if this
change introduces a type incompatibility or if it conflicts with other additions, renames,
or updates.UpdateSchema setIdentifierFields(java.util.Collection<java.lang.String> names)
Because identifier fields are unique, duplicated names will be ignored. See Schema.identifierFieldIds()
to learn more about Iceberg identifier.
names
- names of the columns to set as identifier fieldsdefault UpdateSchema setIdentifierFields(java.lang.String... names)
setIdentifierFields(Collection)
for more details.names
- names of the columns to set as identifier fieldsdefault UpdateSchema caseSensitive(boolean caseSensitive)
caseSensitive
- when false case is not considered in column name comparisons.