All Products
Search
Document Center

Tablestore:Python SDK

Last Updated:Jul 02, 2025

Tablestore SDK for Python supports the Wide Column model and the TimeSeries model.

Features

Before you use the features provided by a Tablestore SDK, you must initialize a client. The following table describes the features provided by Tablestore SDK for Python.

Wide Column model

Feature type

Operation

Description

Operations on data tables

Create a data table

Create a data table to store data. You can specify an auto-increment primary key column when you create a data table.

Update the configurations of a table

Update the configurations of a data table.

List data tables

View the names of all data tables in an instance.

Query information of a table

Query the configurations of a data table.

Delete a data table

Delete a data table.

Auto-increment primary key column

After you set a primary key column that is not the partition key in a data table to an auto-increment primary key column, you do not need to specify a value for the auto-increment primary key column when you write data. Tablestore automatically generates the value for the auto-increment primary key column.

Configure conditional update

Update data in a table only when the specified conditions are met. Otherwise, the update fails and an error is reported.

Use the local transaction feature

After you enable local transaction for a data table, you can create a local transaction based on a partition key value.

Use the atomic counter feature

The atomic counter feature allows you to specify a column as an atomic counter and perform atomic counter operations on the column.

Filter

Filter the read results on the server side to return only the rows that meet the filter conditions.

Data operations

Write data

Write data to a data table.

Read data

Read data from a data table.

Delete data

Delete data from a data table.

Filter

Filter the read results on the server side to return only the rows that meet the filter conditions.

Configure conditional update

Update data in a table only when the specified conditions are met. Otherwise, the update fails and an error is reported.

Use the atomic counter feature

The atomic counter feature allows you to specify a column as an atomic counter and perform atomic counter operations on the column.

Use the local transaction feature

After you enable local transaction for a data table, you can create a local transaction based on a partition key value.

Search index

Create a search index

Create a search index for a data table.

List search indexes

List search indexes that are created for a table.

Update the configurations of a search index

Update the time to live (TTL) of a search index.

Query the description of a search index

Query the description of a search index, including the information about the fields in the search index and configurations of the search index.

Delete a search index

Delete a search index.

Specify the TTL of a search index

Delete historical data or extend the retention period of data in a search index based on business requirements.

Basic query

Basic query types include match all query, term query, terms query, prefix query, range query, wildcard query, exists query, collapse (distinct), geo query, and nested query.

Boolean query

Query conditions can contain one or more subconditions. Data is returned when the subconditions are met.

Sorting and paging

When you use a search index to query data, you can specify a sorting method for the returned data. When the number of returned rows is large, you can use offset-based pagination or token-based pagination to quickly locate the required data.

Aggregation

You can perform aggregation operations to obtain the minimum, maximum, sum, and average values, and the count and distinct count of rows. You can also perform aggregation operations to group results by field value, range, geographical location, or filter. You can perform multiple aggregation operations for complex queries.

Full-text search

Tablestore provides match query and match phrase query to implement full-text search. When you query data, data is matched based on tokenization. You can highlight query strings by using the highlight feature.

KNN vector query

You can use the k-nearest neighbor (KNN) vector search feature to perform an approximate nearest neighbor search based on vectors. This way, you can find data items that have the highest similarity to the vector that you want to query in a large-scale dataset.

Parallel scan

When you do not need to sort the entire result set, you can use the parallel scan feature to return all matched data at a faster speed.

Secondary index

Create a secondary index

Create a secondary index for a data table.

Use a secondary index to read data

You can query data in a secondary index by reading a single row of data or reading data whose primary key values are within a specific range. If the required attribute columns are included in the secondary index, data can be directly read from the secondary index. Otherwise, data must be read from the data table.

Delete a secondary index

Delete a secondary index that is created for a data table.

SQL query

Create a mapping table

Create a mapping table for an existing table or index.

Update attribute columns of a mapping table

Add or remove attribute columns in an existing mapping table.

Delete a mapping table

Delete one or more mapping tables.

Query the names of tables

List the mapping tables in the current database.

Query information about tables

Query the description information of a table, such as field names and field types.

Query index information about tables

Query the index description information of a table.

Query data

Query data in a table.

TimeSeries model

Feature type

Operation

Description

Operations on time series tables

Create a time series table

Create a time series table.

Update a time series table

Update the configurations of a time series table or time series metadata.

Query the names of time series tables

View the names and configuration information of all time series tables in an instance.

Query information of a time series table

Query the information about a time series table, such as the TTL configuration.

Delete a time series table

Delete a time series table.

Operations on time series data

Write time series data

Write one or more rows of time series data to a time series table at the same time.

Query time series data

Query the time series data that meets the specified conditions in a time series.

Time series operations

Retrieve time series

Specify multiple conditions to retrieve time series information, such as the metric name and data source information.

Update time series

Update time series metadata. Batch update is supported.

Delete time series

Delete time series metadata. Batch delete is supported.

SQL query

Create a mapping table

Create a mapping table for an existing table or index.

Update attribute columns of a mapping table

Add or remove attribute columns in an existing mapping table.

Delete a mapping table

Delete one or more mapping tables.

Query the names of tables

List the mapping tables in the current database.

Query information about tables

Query the description information of a table, such as field names and field types.

Query index information about tables

Query the index description information of a table.

Query data

Query data in a table.

Compatibility

The latest version of Tablestore SDK for Python is V6.x.x. The following items describe the compatibility between the latest version and previous versions:

  • Tablestore SDK for Python V5.x.x: compatible.

    Tablestore SDK for Python V5.4.X, V5.3.X, and V5.2.X: compatible. Tablestore SDK for Python V5.2.1 is incompatible with Tablestore SDK for Python V5.1.0. Specifically:

    • The type of the results returned by the Search operation is different between the two versions.

      By default, in Tablestore SDK for Python V5.1.0 or earlier, results of the Tuple type are returned. Starting from V5.2.0, the default return results are SearchResponse objects. SearchResponse has implemented the __iter__ method and supports iteration. If you want to return results of the Tuple type, use the SearchResponse.v1_response() method.

    • The ParallelScan operation is added.

      By default, the results returned for ParallelScan requests are the ParallelScanResponse object. If you want to return results of the Tuple type, use the ParallelScanResponse.v1_response() method.

  • Tablestore SDK for Python V4.x.x: compatible.

  • Tablestore SDK for Python V2.x.x: incompatible. Tablestore SDK for Python V2.x.x supports primary key columns in random order, which are no longer supported in Tablestore SDK for Python V4.0.0 or later. Tablestore SDK for Python V4.x.x and Tablestore SDK for Python V2.x.x are incompatible in the following respects:

    • The package name is changed from ots2 to tablestore.

    • The TableOptions parameter is added for the Client.create_table operation.

    • The type of the primary_key parameter is changed from dict to list for the put_row, get_row, and update_row operations to ensure the sequence of primary key columns.

    • The type of the attribute_columns parameter is changed from dict to list for the put_row and update_row operations.

    • The timestamp parameter is added to the attribute_columns parameter for the put_row and update_row operations.

    • The max_version and time_range parameters are added for the get_row and get_range operations. At least one of these parameters must be specified.

    • The return_type parameter is added for the put_row, update_row, and delete_row operations. Only RT_PK is supported to return the primary key value of the current row.

    • The return_row parameter is added to the return values of the put_row, update_row, and delete_row operations. If return_type is set to RT_PK in the request, return_row contains the primary key value of the row.

For more information about SDK version iterations, see Version history of Tablestore SDK for Python.

References

For information about how to handle errors in Tablestore SDK for Python, see Error handling.