> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /alter/table

```
URL: http://<db.host>:<db.port>/alter/table
```

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

Manage a table's columns--a column can be added, removed, or have its
[type and properties](../../concepts/types/) modified, including whether
it is [dictionary encoded](../../concepts/dictionary_encoding/) or not.

External tables cannot be modified except for their refresh method.

Create or delete a [column](../../concepts/indexes/#column-index),
[low-cardinality index](../../concepts/indexes/#low-cardinality-index),
[chunk skip](../../concepts/indexes/#chunk-skip-index),
[geospatial](../../concepts/indexes/#geospatial-index),
[CAGRA](../../concepts/indexes/#cagra-index), or
[HNSW](../../concepts/indexes/#hnsw-index) index. 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](../../concepts/tables/#foreign-key) on a
particular column.

Manage a
[range-partitioned](../../concepts/tables/#partitioning-by-range) or a
[manual list-partitioned](../../concepts/tables/#partitioning-by-list-manual)
table's partitions.

Set (or reset) the [tier strategy](../../rm/concepts/#tier-strategies) of
a table or view.

Refresh and manage the refresh mode of a
[materialized view](../../concepts/materialized_views/) or an
[external table](../../concepts/external_tables/).

Set the [time-to-live (TTL)](../../concepts/ttl/). This can be applied to
tables or views.

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.

## Input Parameter Description

<ParamField body="table_name" type="string">
  Table on which the operation will be performed, in \[schema\_name.]table\_name format, using standard [name resolution rules](../../concepts/tables/#table-name-resolution). Must be an existing table or view.
</ParamField>

<ParamField body="action" type="string">
  Modification operation to be applied.

  * **create\_index**: Creates a [column (attribute) index](../../concepts/indexes/#column-index), [low-cardinality index](../../concepts/indexes/#low-cardinality-index), [chunk skip index](../../concepts/indexes/#chunk-skip-index), [geospatial index](../../concepts/indexes/#geospatial-index), [CAGRA index](../../concepts/indexes/#cagra-index), or [HNSW index](../../concepts/indexes/#hnsw-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.
  * **refresh\_index**: Refreshes an index identified by *index\_type*, on the column name specified in input parameter *value*. Currently applicable only to CAGRA indices.
  * **delete\_index**: Deletes a [column (attribute) index](../../concepts/indexes/#column-index), [low-cardinality index](../../concepts/indexes/#low-cardinality-index), [chunk skip index](../../concepts/indexes/#chunk-skip-index), [geospatial index](../../concepts/indexes/#geospatial-index), [CAGRA index](../../concepts/indexes/#cagra-index), or [HNSW index](../../concepts/indexes/#hnsw-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**: \[DEPRECATED--please use *move\_to\_schema* and use [/create/schema](/content/api/rest/create_schema_rest) to create the schema if non-existent]  Moves a table or view into a schema named input parameter *value*.  If the schema provided is non-existent, it will be automatically created.
  * **move\_to\_schema**: Moves a table or view into a schema named input parameter *value*. If the schema provided is nonexistent, an error will be thrown. If input parameter *value* is empty, then the table or view will be placed in the user's default schema.
  * **protected**: No longer used.  Previously set whether the given input parameter *table\_name* should be protected or not. The input parameter *value* would have been either 'true' or 'false'.
  * **rename\_table**: Renames a table or view to input parameter *value*. Has the same naming restrictions as [tables](../../concepts/tables/).
  * **ttl**: Sets the [time-to-live](../../concepts/ttl/) in minutes of the table or view specified in input parameter *table\_name*.
  * **add\_comment**: Adds the comment specified in input parameter *value* to the table specified in input parameter *table\_name*. Use *column\_name* to set the comment for a column.
  * **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.
  * **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](../../concepts/tables/#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](../../concepts/tables/#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](../../concepts/tables/#partitioning-by-range) or [manual list-partitioned](../../concepts/tables/#partitioning-by-list-manual) 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](../../concepts/tables/#partitioning-by-range) or [manual list-partitioned](../../concepts/tables/#partitioning-by-list-manual) table.
  * **delete\_partition**: Deletes the partition specified in input parameter *value* (and all of its data) from either a [range-partitioned](../../concepts/tables/#partitioning-by-range) or [manual list-partitioned](../../concepts/tables/#partitioning-by-list-manual) 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**: For a [materialized view](../../concepts/materialized_views/), replays all the table creation commands required to create the view.  For an [external table](../../concepts/external_tables/), reloads all data in the table from its associated source files or [data source](../../concepts/data_sources/).
  * **set\_refresh\_method**: For a [materialized view](../../concepts/materialized_views/), sets the method by which the view is refreshed to the method specified in input parameter *value* - one of 'manual', 'periodic', or 'on\_change'.  For an [external table](../../concepts/external_tables/), sets the method by which the table is refreshed to the method specified in input parameter *value* - either 'manual' or 'on\_start'.
  * **set\_refresh\_start\_time**: Sets the time to start periodic refreshes of this [materialized view](../../concepts/materialized_views/) 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\_stop\_time**: Sets the time to stop periodic refreshes of this [materialized view](../../concepts/materialized_views/) to the datetime string specified in input parameter *value* with format 'YYYY-MM-DD HH:MM:SS'.
  * **set\_refresh\_period**: Sets the time interval in seconds at which to refresh this [materialized view](../../concepts/materialized_views/) to the value specified in input parameter *value*. Also, sets the refresh method to periodic if not already set.
  * **set\_refresh\_span**: Sets the future time-offset(in seconds) for the view refresh to stop.
  * **set\_refresh\_execute\_as**: Sets the user name to refresh this [materialized view](../../concepts/materialized_views/) to the value specified in input parameter *value*.
  * **remove\_text\_search\_attributes**: Removes [text search](../../concepts/full_text_search/) attribute from all columns.
  * **remove\_shard\_keys**: Removes the shard key property from all columns, so that the table will be considered randomly sharded.  The data is not moved.  The input parameter *value* is ignored.
  * **set\_strategy\_definition**: Sets the [tier strategy](../../rm/concepts/#tier-strategies) for the table and its columns to the one specified in input parameter *value*, replacing the existing tier strategy in its entirety.
  * **cancel\_datasource\_subscription**: Permanently unsubscribe a data source that is loading continuously as a stream. The data source can be Kafka / S3 / Azure / GCS.
  * **drop\_datasource\_subscription**: Permanently delete a cancelled data source subscription.
  * **pause\_datasource\_subscription**: Temporarily unsubscribe a data source that is loading continuously as a stream. The data source can be Kafka / S3 / Azure / GCS.
  * **resume\_datasource\_subscription**: Resubscribe to a paused data source subscription. The data source can be Kafka / S3 / Azure / GCS.
  * **change\_owner**: Change the owner resource group of the table.
  * **set\_load\_vectors\_policy**: Set startup data loading scheme for the table; see description of 'load\_vectors\_policy' in [/create/table](/content/api/rest/create_table_rest) for possible values for input parameter *value*.
  * **set\_build\_pk\_index\_policy**: Set startup primary key generation scheme for the table; see description of 'build\_pk\_index\_policy' in [/create/table](/content/api/rest/create_table_rest) for possible values for input parameter *value*.
  * **set\_build\_materialized\_view\_policy**: Set startup rebuilding scheme for the materialized view; see description of 'build\_materialized\_view\_policy' in [/create/materializedview](/content/api/rest/create_materializedview_rest) for possible values for input parameter *value*.
</ParamField>

<ParamField body="value" type="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.
</ParamField>

<ParamField body="options" type="map of string to strings">
  Optional parameters.

  The default value is an empty map ( \{} ).

  <Expandable title="options">
    <ParamField body="action" />

    <ParamField body="column_name" />

    <ParamField body="table_name" />

    <ParamField body="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.
    </ParamField>

    <ParamField body="column_properties">
      When adding or changing a column, set the column properties (strings, separated by a comma: data, text\_search, char8, int8 etc).
    </ParamField>

    <ParamField body="column_type">
      When adding or changing a column, set the column type (strings, separated by a comma: int, double, string, null etc).
    </ParamField>

    <ParamField body="copy_values_from_column">
      \[DEPRECATED]  Please use *add\_column\_expression* instead.
    </ParamField>

    <ParamField body="rename_column">
      When changing a column, specify new column name.
    </ParamField>

    <ParamField body="validate_change_column">
      When changing a column, validate the change before applying it (or not).

      The default value is `true`.

      * **true**: Validate all values. A value too large (or too long) for the new type will prevent any change.
      * **false**: When a value is too large or long, it will be truncated.
    </ParamField>

    <ParamField body="update_last_access_time">
      Indicates whether the [time-to-live](../../concepts/ttl/) (TTL) expiration countdown timer should be reset to the table's TTL.

      The default value is `true`.

      * **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.
    </ParamField>

    <ParamField body="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.
    </ParamField>

    <ParamField body="strategy_definition">
      Parameter for specifying the [tier strategy](../../rm/concepts/#tier-strategies) for the table and its columns when input parameter *action* is *set\_strategy\_definition*, replacing the existing tier strategy in its entirety.
    </ParamField>

    <ParamField body="index_type">
      Type of index to create, when input parameter *action* is *create\_index*; to refresh, when input parameter *action* is *refresh\_index*; or to delete, when input parameter *action* is *delete\_index*.

      The default value is `column`.

      * **column**: Create or delete a [column (attribute) index](../../concepts/indexes/#column-index).
      * **low\_cardinality**: Create a [low-cardinality column (attribute) index](../../concepts/indexes/#low-cardinality-index).
      * **chunk\_skip**: Create or delete a [chunk skip index](../../concepts/indexes/#chunk-skip-index).
      * **geospatial**: Create or delete a [geospatial index](../../concepts/indexes/#geospatial-index).
      * **cagra**: Create or delete a [CAGRA index](../../concepts/indexes/#cagra-index) on a [vector column](../../vector_search/#vector-type).
      * **hnsw**: Create or delete an [HNSW index](../../concepts/indexes/#hnsw-index) on a [vector column](../../vector_search/#vector-type).
    </ParamField>

    <ParamField body="index_options">
      Options to use when creating an index, in the format "key: value \[, key: value \[, ...]]". Valid options vary by index type.
    </ParamField>
  </Expandable>
</ParamField>

## Output Parameter Description

The Kinetica 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:

<ResponseField name="status" type="String">
  'OK' or 'ERROR'
</ResponseField>

<ResponseField name="message" type="String">
  Empty if success or an error message
</ResponseField>

<ResponseField name="data_type" type="String">
  'alter\_table\_response' or 'none' in case of an error
</ResponseField>

<ResponseField name="data" type="String">
  Empty string
</ResponseField>

<ResponseField name="data_str" type="JSON or String">
  This embedded JSON represents the result of the /alter/table endpoint:

  <Expandable title="data_str">
    <ResponseField name="table_name" type="string">
      Table on which the operation was performed.
    </ResponseField>

    <ResponseField name="action" type="string">
      Modification operation that was performed.
    </ResponseField>

    <ResponseField name="value" type="string">
      The value of the modification that was performed.
    </ResponseField>

    <ResponseField name="type_id" type="string">
      Return the type\_id (when changing a table, a new type may be created).
    </ResponseField>

    <ResponseField name="type_definition" type="string">
      Return the type\_definition  (when changing a table, a new type may be created).
    </ResponseField>

    <ResponseField name="properties" type="map of string to arrays of strings">
      Return the type properties  (when changing a table, a new type may be created).
    </ResponseField>

    <ResponseField name="label" type="string">
      Return the type label  (when changing a table, a new type may be created).
    </ResponseField>

    <ResponseField name="info" type="map of string to strings">
      Additional information.
    </ResponseField>
  </Expandable>

  Empty string in case of an error.
</ResponseField>