/alter/table

URL: http://GPUDB_IP_ADDRESS:GPUDB_PORT/alter/table

Apply various modifications to a table, view, or collection. The available modifications include the following:

Manage a table's columns--a column can be added, removed, or have its type and properties modified, including whether it is compressed or not.

Create or delete an index on a particular column. This can speed up certain operations when using expressions containing equality or relational operators on indexed columns. This only applies to tables.

Create or delete a foreign key on a particular column.

Manage a range-partitioned or a manual list-partitioned table's partitions.

Set (or reset) the tier strategy of a table or view.

Refresh and manage the refresh mode of a materialized view.

Set the time-to-live (TTL). This can be applied to tables, views, or collections. When applied to collections, every contained table & view that is not protected will have its TTL set to the given value.

Set the global access mode (i.e. locking) for a table. This setting trumps any role-based access controls that may be in place; e.g., a user with write access to a table marked read-only will not be able to insert records into it. The mode can be set to read-only, write-only, read/write, and no access.

Change the protection mode to prevent or allow automatic expiration. This can be applied to tables, views, and collections.

Input Parameter Description

Name	Type	Description
table_name	string	Table on which the operation will be performed. Must be an existing table, view, or collection.
action	string	Modification operation to be applied Supported Values Description allow_homogeneous_tables No longer supported; action will be ignored. create_index Creates either a column (attribute) index or chunk skip index, depending on the specified index_type, on the column name specified in input parameter value. If this column already has the specified index, an error will be returned. delete_index Deletes either a column (attribute) index or chunk skip index, depending on the specified index_type, on the column name specified in input parameter value. If this column does not have the specified index, an error will be returned. move_to_collection Moves a table or view into a collection named input parameter value. If the collection provided is non-existent, the collection will be automatically created. If input parameter value is empty, then the table or view will be top-level. protected Sets whether the given input parameter table_name should be protected or not. The input parameter value must be either 'true' or 'false'. rename_table Renames a table, view or collection to input parameter value. Has the same naming restrictions as tables. ttl Sets the time-to-live in minutes of the table, view, or collection specified in input parameter table_name. add_column Adds the column specified in input parameter value to the table specified in input parameter table_name. Use column_type and column_properties in input parameter options to set the column's type and properties, respectively. change_column Changes type and properties of the column specified in input parameter value. Use column_type and column_properties in input parameter options to set the column's type and properties, respectively. Note that primary key and/or shard key columns cannot be changed. All unchanging column properties must be listed for the change to take place, e.g., to add dictionary encoding to an existing 'char4' column, both 'char4' and 'dict' must be specified in the input parameter options map. set_column_compression Modifies the compression setting on the column specified in input parameter value to the compression type specified in compression_type. delete_column Deletes the column specified in input parameter value from the table specified in input parameter table_name. create_foreign_key Creates a foreign key specified in input parameter value using the format '(source_column_name [, ...]) references target_table_name(primary_key_column_name [, ...]) [as foreign_key_name]'. delete_foreign_key Deletes a foreign key. The input parameter value should be the foreign_key_name specified when creating the key or the complete string used to define it. add_partition Adds the partition specified in input parameter value, to either a range-partitioned or manual list-partitioned table. remove_partition Removes the partition specified in input parameter value (and relocates all of its data to the default partition) from either a range-partitioned or manual list-partitioned table. delete_partition Deletes the partition specified in input parameter value (and all of its data) from either a range-partitioned or manual list-partitioned table. set_global_access_mode Sets the global access mode (i.e. locking) for the table specified in input parameter table_name. Specify the access mode in input parameter value. Valid modes are 'no_access', 'read_only', 'write_only' and 'read_write'. refresh Replays all the table creation commands required to create this materialized view. set_refresh_method Sets the method by which this materialized view is refreshed to the method specified in input parameter value - one of 'manual', 'periodic', 'on_change'. set_refresh_start_time Sets the time to start periodic refreshes of this materialized view to the datetime string specified in input parameter value with format 'YYYY-MM-DD HH:MM:SS'. Subsequent refreshes occur at the specified time + N * the refresh period. set_refresh_period Sets the time interval in seconds at which to refresh this materialized view to the value specified in input parameter value. Also, sets the refresh method to periodic if not already set. remove_text_search_attributes Removes text search attribute from all columns. set_strategy_definition Sets the tier strategy for the table and its columns to the one specified in input parameter value, replacing the existing tier strategy in its entirety. See tier strategy usage for format and tier strategy examples for examples.
value	string	The value of the modification, depending on input parameter action. For example, if input parameter action is add_column, this would be the column name; while the column's definition would be covered by the column_type, column_properties, column_default_value, and add_column_expression in input parameter options. If input parameter action is ttl, it would be the number of minutes for the new TTL. If input parameter action is refresh, this field would be blank.
options	map of string to strings	Optional parameters. The default value is an empty map ( {} ). Supported Parameters (keys) Parameter Description action   column_name   table_name   column_default_value When adding a column, set a default value for existing records. For nullable columns, the default value will be null, regardless of data type. column_properties When adding or changing a column, set the column properties (strings, separated by a comma: data, store_only, text_search, char8, int8 etc). column_type When adding or changing a column, set the column type (strings, separated by a comma: int, double, string, null etc). compression_type When setting column compression (set_column_compression for input parameter action), compression type to use: none (to use no compression) or a valid compression type. The default value is snappy. The supported values are: none snappy lz4 lz4hc copy_values_from_column Deprecated. Please use add_column_expression instead. rename_column When changing a column, specify new column name. validate_change_column When changing a column, validate the change before applying it. If true, then validate all values. A value too large (or too long) for the new type will prevent any change. If false, then when a value is too large or long, it will be truncated. The default value is true. Supported Values Description true true false false update_last_access_time Indicates whether the time-to-live (TTL) expiration countdown timer should be reset to the table's TTL. The default value is true. Supported Values Description true Reset the expiration countdown timer to the table's configured TTL. false Don't reset the timer; expiration countdown will continue from where it is, as if the table had not been accessed. add_column_expression When adding a column, an optional expression to use for the new column's values. Any valid expression may be used, including one containing references to existing columns in the same table. strategy_definition Optional parameter for specifying the tier strategy for the table and its columns when input parameter action is set_strategy_definition, replacing the existing tier strategy in its entirety. See tier strategy usage for format and tier strategy examples for examples. This option will be ignored if input parameter value is also specified. index_type Type of index to create, when input parameter action is create_index, or to delete, when input parameter action is delete_index. The default value is column. Supported Values Description column Create or delete a column (attribute) index. chunk_skip Create or delete a chunk skip index.

Output Parameter Description

The GPUdb server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query. Here is a description of the various fields of the wrapper:

Name	Type	Description
status	String	'OK' or 'ERROR'
message	String	Empty if success or an error message
data_type	String	'alter_table_request' or 'none' in case of an error
data	String	Empty string
data_str	JSON or String	This embedded JSON represents the result of the /alter/table endpoint: Name Type Description table_name string Table on which the operation was performed. action string Modification operation that was performed. value string The value of the modification that was performed. type_id string return the type_id (when changing a table, a new type may be created) type_definition string return the type_definition (when changing a table, a new type may be created) properties map of string to arrays of strings return the type properties (when changing a table, a new type may be created) label string return the type label (when changing a table, a new type may be created) info map of string to strings Additional information. Empty string in case of an error.