jerryshao commented on code in PR #8542: URL: https://github.com/apache/gravitino/pull/8542#discussion_r2355266177
########## clients/client-python/gravitino/api/table_change.py: ########## @@ -0,0 +1,942 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from itertools import chain +from typing import Optional, final + +from dataclasses_json import config + +from gravitino.api.column import Column +from gravitino.api.expressions.expression import Expression +from gravitino.api.expressions.indexes.index import Index +from gravitino.api.types.type import Type + + +class TableChange(ABC): + """Defines the public APIs for managing tables in a schema. + + The `TableChange` interface defines the public API for managing tables in a schema. + If the catalog implementation supports tables, it must implement this interface. + """ + + @staticmethod + def rename(new_name: str) -> "RenameTable": + """Create a `TableChange` for renaming a table. + + Args: + new_name: The new table name. + + Returns: + RenameTable: A `TableChange` for the rename. + """ + return TableChange.RenameTable(new_name) + + @staticmethod + def update_comment(new_comment: str) -> "UpdateComment": + """Create a `TableChange` for updating the comment. + + Args: + new_comment: The new comment. + + Returns: + UpdateComment: A `TableChange` for the update. + """ + return TableChange.UpdateComment(new_comment) + + @staticmethod + def set_property(property_name: str, value: str) -> "SetProperty": + """Create a `TableChange` for setting a table property. + + If the property already exists, it will be replaced with the new value. + + Args: + property_name (str): The property name. + value (str): The new property value. + + Returns: + SetProperty: A `TableChange` for the addition. + """ + return TableChange.SetProperty(property_name, value) + + @staticmethod + def remove_property(property_name: str) -> "RemoveProperty": + """Create a `TableChange` for removing a table property. + + If the property does not exist, the change will succeed. + + Args: + property_name (str): The property name. + + Returns: + RemoveProperty: A `TableChange` for the addition. + """ + return TableChange.RemoveProperty(property_name) + + @staticmethod + def add_column( + field_name: list[str], + data_type: Type, + comment: Optional[str] = None, + position: Optional["TableChange.ColumnPosition"] = None, + nullable: bool = True, + auto_increment: bool = False, + default_value: Optional[Expression] = None, + ) -> "AddColumn": + """Create a `TableChange` for adding a column. + + Args: + field_name (list[str]): + Field name of the new column. + data_type (Type): + The new column's data type. + comment (Optional[str]): + The new field's comment string, defaults to `None`. + position (Optional[TableChange.ColumnPosition]): + The new column's position, defaults to `None`. + nullable (bool): + The new column's nullable. + auto_increment (bool): + The new column's autoIncrement. + default_value (Expression): + The new column's default value. + + Returns: + AddColumn: A `TableChange` for the addition. + """ + return AddColumn( + field_name, + data_type, + comment, + position, + nullable, + auto_increment, + default_value, + ) + + @staticmethod + def rename_column(field_name: list[str], new_name: str) -> "RenameColumn": + """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, `rename_column(["a", "b", "c"], "x")` should produce column **a.b.x**. + + If the field does not exist, the change will result in an `IllegalArgumentException`. + + Args: + field_name (list[str]): The current field name. + new_name (str): The new name. + + Returns: + RenameColumn: A TableChange for the rename. + """ + return RenameColumn(field_name, new_name) + + @staticmethod + def update_column_default_value( + field_name: list[str], new_default_value: Expression + ) -> "UpdateColumnDefaultValue": + """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`. + + Args: + field_name (list[str]): The field name of the column to update. + new_default_value (Expression): The new default value. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnDefaultValue(field_name, new_default_value) + + @staticmethod + def update_column_type( + field_name: list[str], new_data_type: Type + ) -> "UpdateColumnType": + """Create a `TableChange` for updating the type of a field that is nullable. + + The field name are used to find the field to update. + + If the field does not exist, the change will result in an `IllegalArgumentException`. + + Args: + field_name (list[str]): The field name of the column to update. + new_data_type (Type): The new data type. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnType(field_name, new_data_type) + + @staticmethod + def update_column_comment( + field_name: list[str], new_comment: str + ) -> "UpdateColumnComment": + """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`. + + Args: + field_name (list[str]): The field name of the column to update. + new_comment (str): The new comment. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnComment(field_name, new_comment) + + @staticmethod + def update_column_position( + field_name: list[str], new_position: "TableChange.ColumnPosition" + ) -> "UpdateColumnPosition": + """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`. + + Args: + field_name (list[str]): The field name of the column to update. + new_position (TableChange.ColumnPosition): The new position. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnPosition(field_name, new_position) + + @staticmethod + def delete_column(field_name: list[str], if_exists: bool) -> "DeleteColumn": + """Create a `TableChange` for deleting a field. + + If the field does not exist, the change will result in an `IllegalArgumentException` + unless `if_exists` is true. + + Args: + field_name (list[str]): Field name of the column to delete. + if_exists (bool): If true, silence the error if column does not exist during drop. + Otherwise, an `IllegalArgumentException` will be thrown. + + Returns: + TableChange: A `TableChange` for the delete. + """ + return DeleteColumn(field_name, if_exists) + + @staticmethod + def update_column_nullability( + field_name: list[str], nullable: bool + ) -> "UpdateColumnNullability": + """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`. + + Args: + field_name (list[str]): The field name of the column to update. + nullable (bool): The new nullability. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnNullability(field_name, nullable) + + @staticmethod + def add_index( + index_type: Index.IndexType, + name: str, + field_names: list[list[str]], + ) -> "AddIndex": + """Create a `TableChange` for adding an index. + + Args: + index_type (Index.IndexType): The type of the index. + name (str): The name of the index. + field_names (list[list[str]]): The field names of the index. + + Returns: + TableChange: A `TableChange` for the add index. + """ + return TableChange.AddIndex(index_type, name, field_names) + + @staticmethod + def delete_index(name: str, if_exists: bool) -> "DeleteIndex": + """Create a `TableChange` for deleting an index. + + Args: + name (str): The name of the index to be dropped. + if_exists (bool): If true, silence the error if column does not exist during drop. + Otherwise, an `IllegalArgumentException` will be thrown. + + Returns: + TableChange: A `TableChange` for the delete index. + """ + return TableChange.DeleteIndex(name, if_exists) + + @staticmethod + def update_column_auto_increment( + field_name: list[str], auto_increment: bool + ) -> "UpdateColumnAutoIncrement": + """Create a `TableChange` for updating the autoIncrement 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`. + + Args: + field_name (list[str]): The field name of the column to update. + auto_increment (bool): The new autoIncrement. + + Returns: + TableChange: A `TableChange` for the update. + """ + return UpdateColumnAutoIncrement(field_name, auto_increment) + + @final + @dataclass(frozen=True) + class RenameTable: + """A `TableChange` to rename a table.""" + + _new_name: str = field(metadata=config(field_name="new_name")) + + def get_new_name(self) -> str: + """Retrieves the new name for the table. + + Returns: + str: The new name of the table. + """ + return self._new_name + + def __str__(self): + return f"RENAMETABLE {self._new_name}" Review Comment: I think we should add `__eq__` and `__hash__` methods, what do you think? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
