This topic describes the Tablestore Python SDK.
Notes
Tablestore Python SDK version 6.0.0 and later only supports Python 3 (Python 3.8 and later versions are recommended) and no longer supports Python 2.
ImportantIf you need to use Python 2, please choose Python SDK versions earlier than 5.4.4.
If you use the HTTPS protocol to access Tablestore resources, we recommend that you use the latest version of the Python SDK and ensure that the OpenSSL version is at least 0.9.8j (1.0.2d is recommended).
Python SDK includes the certifi package and can be used directly. If you need to update the root certificate, download the latest version from root certificate.
Preparations
Features
Tablestore Python SDK supports operations for the wide table model and TimeSeries model. For specific features, see the following table.
Wide table model
Feature type | Operation | Description |
Create a data table. | ||
Update the configurations of a data table. | ||
View the names of all data tables in an instance. | ||
Query the configurations of a data table. | ||
Delete a specified data table. | ||
After you set a primary key column that is not a partition key in a data table to an auto-increment column, you do not need to specify a specific value for the auto-increment column when you write data. Tablestore automatically generates the value for the auto-increment column.Tablestore | ||
Update data in a table only when the specified conditions are met. Otherwise, the update fails and an error is reported. | ||
After you enable local transaction for a data table, you can create a local transaction based on a partition key value. | ||
The atomic counter feature allows you to specify a column as an atomic counter and perform atomic counter operations on the column. | ||
Filter the read results on the server side to return only the rows that meet the filter conditions. | ||
Write data to the data table. | ||
Read data from the data table. | ||
Delete data from the data table. | ||
Create a search index for a data table. | ||
List search indexes that are created for a table. | ||
Update the time to live (TTL) 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 specified search index. | ||
Delete historical data or extend the retention period of data in a search index based on business requirements. | ||
Basic query types include match all query, term query, terms query, prefix query, range query, wildcard query, exists query, collapse (deduplicate), geo query, and nested query. | ||
Query conditions can contain one or more subconditions. Data is returned when the subconditions are met. | ||
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. | ||
You can perform operations such as finding minimum values, finding maximum values, summing, finding average values, counting rows, counting distinct values, grouping by field values, grouping by range, grouping by geographical location, and grouping by filter. Multiple aggregation features can be used together to meet complex query requirements. | ||
Full-text index features include match query, match phrase query, and summary and highlighting. | ||
You can use the k-nearest neighbor (KNN) vector query 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. | ||
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. | ||
Create a secondary index for a data table. | ||
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 specified secondary index from a data table. | ||
Create mapping relationships for existing tables or indexes. | ||
Add or remove attribute columns in an existing mapping table. | ||
Delete one or more mapping tables. | ||
List the mapping tables in the current database. | ||
Query the description information of a table, such as field names and field types. | ||
Query the index description information of a table. | ||
Query data in a table. |
Timeseries model
Feature type | Operation | Description |
Time series table operations | Create time series tables | Create a time series table. |
Update time series tables | Update the time series table or time series metadata configuration. | |
List time series tables | View the names and configuration information of all time series tables in an instance. | |
Query time series table description information | Query the information about a time series table, such as the TTL configuration. | |
Delete time series tables | Delete a specified time series table. | |
Time series data operations | Write time series data | Write time series data to a time series table. Batch write is supported. |
Query time series data | Query the time series data that meets the specified conditions in a specific time series. | |
Time series operations | Retrieve time series | Specify multiple conditions to retrieve time series information, such as measure names 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. | |
Create mapping relationships for existing tables or indexes. | ||
Add or remove attribute columns in an existing mapping table. | ||
Delete one or more mapping tables. | ||
List the mapping tables in the current database. | ||
Query the description information of a table, such as field names and field types. | ||
Query the index description information of a table. | ||
Query data in a table. |
Compatibility
The latest version of Tablestore Python SDK is 6.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 need to return results of the Tuple type, use theSearchResponse.v1_response()
method.The ParallelScan operation is added.
By default, the results returned for ParallelScan requests are the ParallelScanResponse object. If you need 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 exist.
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 field 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 Python SDK release notes.
References
To view the source code of the Python SDK, visit GitHub.
For information about how to handle errors in the Python SDK, see Error handling.
For API information, see API overview.