org.apache.iceberg

Interface UpdateSchema

All Superinterfaces:

PendingUpdate<Schema>

public interface UpdateSchema
extends PendingUpdate<Schema>

API for schema evolution.

When committing, these changes will be applied to the current table metadata. Commit conflicts will not be resolved and will result in a CommitFailedException.

Method Summary

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.
UpdateSchema	deleteColumn(java.lang.String name) Delete a column in the schema.
UpdateSchema	renameColumn(java.lang.String name, java.lang.String newName) Rename a column in the 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.

Methods inherited from interface org.apache.iceberg.PendingUpdate

apply, commit

Method Detail

addColumn

default UpdateSchema addColumn(java.lang.String name,
                               Type type)

Add a new top-level column.

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.

Parameters:

name - name for the new column

type - type for the new column

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If name contains "."

addColumn

UpdateSchema addColumn(java.lang.String name,
                       Type type,
                       java.lang.String doc)

Add a new top-level column.

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.

Parameters:

name - name for the new column

type - type for the new column

doc - documentation string for the new column

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If name contains "."

addColumn

default UpdateSchema addColumn(java.lang.String parent,
                               java.lang.String name,
                               Type type)

Add a new column to a nested struct.

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.

Parameters:

parent - name of the parent struct to the column will be added to

name - name for the new column

type - type for the new column

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If parent doesn't identify a struct

addColumn

UpdateSchema addColumn(java.lang.String parent,
                       java.lang.String name,
                       Type type,
                       java.lang.String doc)

Add a new column to a nested struct.

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.

Parameters:

parent - name of the parent struct to the column will be added to

name - name for the new column

type - type for the new column

doc - documentation string for the new column

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If parent doesn't identify a struct

renameColumn

UpdateSchema renameColumn(java.lang.String name,
                          java.lang.String newName)

Rename a column in the schema.

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.

Parameters:

name - name of the column to rename

newName - replacement name for the column

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If name doesn't identify a column in the schema or if this change conflicts with other additions, renames, or updates.

updateColumn

UpdateSchema updateColumn(java.lang.String name,
                          Type.PrimitiveType newType)

Update a column in the schema to a new primitive type.

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.

Parameters:

name - name of the column to rename

newType - replacement type for the column

Returns:

this for method chaining

Throws:

java.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.

updateColumn

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.

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.

Parameters:

name - name of the column to rename

newType - replacement type for the column

newDoc - replacement documentation string for the column

Returns:

this for method chaining

Throws:

java.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.

updateColumnDoc

UpdateSchema updateColumnDoc(java.lang.String name,
                             java.lang.String newDoc)

Update a column in the schema to a new primitive type.

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.

Parameters:

name - name of the column to rename

newDoc - replacement documentation string for the column

Returns:

this for method chaining

Throws:

java.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.

deleteColumn

UpdateSchema deleteColumn(java.lang.String name)

Delete a column in the schema.

The name is used to find the column to delete using Schema.findField(String).

Parameters:

name - name of the column to delete

Returns:

this for method chaining

Throws:

java.lang.IllegalArgumentException - If name doesn't identify a column in the schema or if this change conflicts with other additions, renames, or updates.