You can call the UpdateTable operation to update configurations and Stream settings of a data table, and update reserved read and write throughput of a data table in a high-performance instance.

Note For more information about the UpdateTable operation, see UpdateTable.

Prerequisites

API operations

/**
 * Update the configurations, Stream settings, and reserved read and write throughput of a table. 
 * You can call this operation to increase or decrease the reserved read and write throughput of a data table. 
 * @api
 * @param [] $request The request parameters. 
 * @return [] The response.  
 * @throws OTSClientException The exception that is returned when a parameter error occurs or the Tablestore server returns a verification error. 
 * @throws OTSServerException The exception that is returned when the Tablestore server returns an error. 
 */
public function updateTable(array $request);           

Parameters

  • Request parameters
    Parameter Description
    table_name The name of the data table.
    table_options The configuration information about the data table. For more information, see Data versions and TTL.

    The configurations contain the following items:

    • time_to_live: the period during which data in the table can be retained. This period is the validity period of data. If the retention period exceeds the TTL value, Tablestore automatically deletes expired data.

      Unit: seconds.

      Note
      • If you want to create an index table for a data table, you must set time_to_live to -1 for the data table.
      • If data is retained for a period of time that exceeds the TTL value, the data becomes invalid and you cannot read the data even if the data has not been deleted by Tablestore.
        • When you decrease the TTL value, Tablestore asynchronously deletes the data that is retained for a period of time that exceeds the most recent TTL value.
        • When you increase the TTL value, you can read the data of specific versions if Tablestore has not deleted the data and data of the versions is retained for a period of time that is within the most recent TTL value.
    • max_versions: the maximum number of versions of data that can be retained for a single attribute column. If the number of versions of data in an attribute column exceeds the value of this parameter, the system deletes data of earlier versions.
      Note
      • If you want to create an index table for a data table, you must set max_versions to 1 for the data table.
      • If the number of versions exceeds the max_versions value that you specify, the data of earlier versions becomes invalid and you cannot read the data even if the data has not been deleted by Tablestore.
        • When you decrease the value of max_versions, Tablestore asynchronously deletes data of earlier versions if the number of data versions exceeds the most recent value of max_versions.
        • When you increase the value of max_versions, you can read the data of specific versions if Tablestore has not deleted the data of the versions and the versions are within the most recent valid version range.
    • deviation_cell_version_in_sec: the max version offset, which is the maximum difference between the current system time and the timestamp of the written data. The difference between the version number and the time at which the data is written must be less than or equal to the value of deviation_cell_version_in_sec. Otherwise, an error occurs when the data is written.

      The valid version range of data in an attribute column is calculated by using the following formula: Valid version range = [max{Data written time - Max version offset, Data written time - TTL value}, Data written time + Max version offset).

      Unit: seconds.

    • allow_update: specifies whether to allow the UpdateRow operation. The default value is true, which indicates that the UpdateRow operation is allowed. If you set allow_update to false, the UpdateRow operation is prohibited.
    reserved_throughput The reserved read throughput and reserved write throughput of the data table.
    Note The interval between attempts to modify the value of ReservedThroughput is a minimum of 1 minute.

    You can set the reserved read throughput or reserved write throughput only to 0 for data tables in capacity instances. Reserved throughput does not apply to these instances.

    The default value 0 indicates that you are billed for all throughput on a pay-as-you-go basis.

    Unit: capacity unit (CU).

    • If you set the reserved read throughput or reserved write throughput to a value that is greater than 0 for a data table, Tablestore reserves resources for the data table. After you create the data table, Tablestore charges you for the reserved throughput. You are charged for additional throughput based on the pay-as-you-go billing method. For more information, see Billing overview.
    • If you set the reserved read throughput or reserved write throughput to 0, Tablestore does not reserve resources for the data table.
    stream_spec (Optional) Stream configurations.
    • enable_stream: specifies whether to enable Stream for the data table.
    • expiration_time: the expiration time of the Stream data of the table. Unit: hours. Earlier modification records are deleted.

      You can specify this parameter only when you set enable_stream to true.

  • Request format
    $result = $client->updateTable([
        'table_name' => '<string>', // Specify the name of the table. This parameter is required. 
        'reserved_throughput' => [         
            'capacity_unit' => [
                'read' => <integer>, 
                'write' => <integer>
            ]
        ],
        'table_options' => [ 
            'time_to_live' => <integer>,   
            'max_versions' => <integer>,    
            'deviation_cell_version_in_sec' => <integer>  
        ],
        'stream_spec' => [
            'enable_stream' => true || false,
            'expiration_time' => <integer>
        ]
    ]);    
  • Response parameters
    Parameter Description
    capacity_unit_details The reserved read and write throughput of the table, which includes the following items:
    • capacity_unit indicates the reserved read and write throughput settings of the table, which are related to billing.
      • read: the reserved read throughput.
      • write: the reserved write throughput.
    • last_increase_time: the time when the reserved read throughput or reserved write throughput was last increased for this table. The time is expressed in the number of seconds that have elapsed since 00:00:00, January 1, 1970 (UTC).
    • last_decrease_time: the time when the reserved read throughput or reserved write throughput was last decreased for this table. The time is expressed in the number of seconds that have elapsed since 00:00:00, January 1, 1970 (UTC).
    table_options The configuration information about the table, including time_to_live, max_versions, and deviation_cell_version_in_sec, which is consistent with the configuration information in the request.
    stream_details The Stream information about the table, which includes the following items:
    • enable_stream: indicates whether Stream is enabled for the table.
    • stream_id: the Stream ID of the table.
    • expiration_time: the expiration time of the Stream data of the table. Unit: hours. Earlier modification records are deleted.
    • last_enable_time: the time when Stream was enabled most recently.
  • Result format
    [
        'capacity_unit_details' => [
            'capacity_unit' => [
                'read' => <integer>,
                'write' => <integer>
            ],
            'last_increase_time' => <integer>,
            'last_decrease_time' => <integer>
        ],
        'table_options' => [
            'time_to_live' => <integer>,
            'max_versions' => <integer>,
            'deviation_cell_version_in_sec' => <integer>
        ],
        'stream_details' => [
            'enable_stream' => true || false,
            'stream_id' => '<string>',
            'expiration_time' => <integer>,
            'last_enable_time' => <integer>
        ]
    ]       

Examples

  • Example 1

    The following code provides an example on how to change the reserved read throughput to 1 and reserved write throughput to 2 for a table:

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'reserved_throughput' => [         
            'capacity_unit' => [
                'read' => 1, // You can separately update the reserved read throughput or reserved write throughput. 
                'write' => 2
            ]
        ]
    ]);           
  • Example 2

    The following code provides an example on how to change the TTL to 86,400 seconds (one day), max versions to 2, and max version offset to 10 seconds for a table:

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'table_options' => [ 
            'time_to_live' => 86400,   
            'max_versions' => 2,    
            'deviation_cell_version_in_sec' => 10  
        ]
    ]);            
  • Example 3

    The following code provides an example on how to enable Stream for a table and set the expiration time to 24 hours:

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'stream_spec' => [
            'enable_stream' => true,
            'expiration_time' => 24
        ]
    ]);