Tablestore Python SDK - Tablestore - Alibaba Cloud Documentation Center

The Tablestore SDK for Python supports wide table and time series model operations.

Get started

Prepare your environment, install the SDK, and initialize a client to get started.

Prerequisites

Download and install the Python runtime environment. Run the python3 --version command to check your Python version.

Starting from version 6.0.0, the Python SDK supports only Python 3 and no longer supports Python 2. To use Python 2, you must use version 5.4.4 or earlier.

Install the SDK

Select an installation method. Use the latest SDK version to ensure code examples run correctly.

Install by using pip (recommended)

Run the following command to install the SDK.

pip3 install tablestore

Install from GitHub

Clone the SDK from GitHub using git and install it.

Clone the repository.

git clone https://github.com/aliyun/aliyun-tablestore-python-sdk.git

Navigate to the SDK directory.
```
cd aliyun-tablestore-python-sdk
```
Install the SDK.
```
python3 setup.py install
```

Install from source code

Download and install the SDK from source.

Download and decompress the Python SDK.
Navigate to the decompressed SDK directory.
Install the SDK.
```
python3 setup.py install
```

Configure access credentials

Create an AccessKey for your Alibaba Cloud account or RAM user, then configure it as an environment variable to avoid hard-coding credentials.

Restart your IDE, terminal, other desktop applications, and background services after configuration to load the updated environment variables. For more information about other types of access credentials, see Configure access credentials.

Linux

Append the environment variables to ~/.bashrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

Apply the changes:
```
source ~/.bashrc
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

macOS

Check your default shell:
```
echo $SHELL
```

Configure based on your shell type:

Zsh

Append the environment variables to ~/.zshrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

Apply the changes:
```
source ~/.zshrc
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Bash

Append the environment variables to ~/.bash_profile:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

Apply the changes:
```
source ~/.bash_profile
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Windows

CMD

Set the environment variables in CMD:

setx TABLESTORE_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx TABLESTORE_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Restart CMD and verify:

echo %TABLESTORE_ACCESS_KEY_ID%
echo %TABLESTORE_ACCESS_KEY_SECRET%

PowerShell

Run in PowerShell:

[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Verify the environment variables:

[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Initialize the client

The following code initializes a client and lists all data tables and time series tables in an instance to verify connectivity.

Important

Public network access is disabled by default for new instances. To enable it, go to Network Management for the instance.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import os
import sys
from tablestore import OTSClient

def main():
    try:
        # Get access credentials from environment variables. Ensure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET are set.
        access_key_id = os.getenv("TABLESTORE_ACCESS_KEY_ID")
        access_key_secret = os.getenv("TABLESTORE_ACCESS_KEY_SECRET")

        # TODO: Replace the following values with your instance details.
        instance_name = "n01k********"  # Instance name
        endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"  # Instance endpoint
        
        # Create a client instance.
        client = OTSClient(endpoint, access_key_id, access_key_secret, instance_name)

        # List the data tables.
        resp = client.list_table()

        print(f"Found {len(resp)} data tables in instance '{instance_name}':")
        for table_name in resp:
            print(f"{table_name}")

        # List the time series tables.
        resp = client.list_timeseries_table()

        print(f"\nFound {len(resp)} time series tables in instance '{instance_name}':")
        for tableMeta in resp:
            print(f"{tableMeta.timeseries_table_name}")
            
    except Exception as e:
        print(f"Operation failed: {str(e)}")
        sys.exit(1)


if __name__ == "__main__":
    main()

Version compatibility

The current version is 6.x.x. Compatibility with earlier versions:

Compatible with 5.x.x.

5.4.x, 5.3.x, and 5.2.x are compatible. 5.2.1 and 5.1.0 are incompatible in these cases:
- The return type of the Search method.
  
  In 5.1.0 and earlier, this method returns a Tuple by default. From 5.2.0 onward, it returns a SearchResponse object. SearchResponse implements __iter__ and supports traversal. To get a Tuple, use SearchResponse.v1_response().
- The new ParallelScan method.
  
  By default, this method returns a ParallelScanResponse object. To get a Tuple, use ParallelScanResponse.v1_response().
Compatible with 4.x.x.
Incompatible with 2.x.x. The 2.x.x series supports out-of-order primary keys, while 4.0.0 and later do not. Breaking changes:
- Package name changed from ots2 to tablestore.
- TableOptions parameter added to Client.create_table.
- For put_row, get_row, and update_row, the primary_key type changed from dict to list to preserve primary key order.
- For put_row and update_row, the attribute_columns type changed from dict to list.
- timestamp added to attribute_columns for put_row and update_row.
- get_row and get_range now require at least one of max_version and time_range.
- put_row, update_row, and delete_row now support return_type. The only supported value is RT_PK, which returns the primary key (PK) of the row.
- put_row, update_row, and delete_row now include return_row in their response. When return_type is set to RT_PK, return_row contains the PK value.

FAQ

What do I do if a "Signature mismatch" error occurs?

The following exception occurs:

Error Code: OTSAuthFailed, Message: Signature mismatch., RequestId: 0005f55a-xxxx-xxxx-xxxx-xxxxxxxxxxxx, TraceId: 10b0f0e0-xxxx-xxxx-xxxx-xxxxxxxxxxxx, HttpStatus: 403

Cause: The AccessKey ID or AccessKey secret is incorrect.
Solution: Provide the correct AccessKey ID and AccessKey secret.

What do I do if a "Request denied by instance ACL policies" error occurs?

The SDK may return a Request denied by instance ACL policies error:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied by instance ACL policies., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Cause: The client's network type does not match the instance's access policy. For example, the instance does not allow Internet access.
Solution: Public network access is disabled by default. To enable it:
1. In the Tablestore console, click the target instance.
2. Click Network Management. For Allowed Network Type, select Internet, and then click Settings.

What do I do if a "Request denied because this instance can only be accessed from the binded VPC" error occurs?

The SDK may return a Request denied because this instance can only be accessed from the bound VPC error:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied because this instance can only be accessed from the binded VPC., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Cause: The instance access type is set to Bound VPCs Only or Tablestore Console or Bound VPCs, but the client is not in an attached VPC or is not accessing Tablestore using a VPC endpoint.
Solution: Either allow Internet access, or attach a VPC and connect the client from within it:
1. In the Tablestore console, click the target instance.
2. Click Network Management > Bind VPC. Select a VPC ID and a VSwitch, enter a VPC Name, and then click OK.

How do I access Tablestore resources over HTTPS?

Use the latest version of the Python SDK. Ensure that your OpenSSL version is 0.9.8j or later. OpenSSL 1.0.2d is recommended.

What do I do if protobuf versions are incompatible?

Some protobuf versions are incompatible with the *pb2.py files in the installation package. To resolve this, regenerate the *pb2.py files:

Use your current protoc version to generate code for the proto files.

protoc --python_out=. tablestore/protobuf/search.proto
protoc --python_out=. tablestore/protobuf/table_store.proto
protoc --python_out=. tablestore/protobuf/table_store_filter.proto

Rename the generated files with the pb2.py extension and copy them to tablestore/protobuf/ in the installation directory, replacing the original *pb2.py files.

Use the Credentials tool to read access credentials

Run the following command to install the alibabacloud_credentials package.
```
pip3 install alibabacloud_credentials
```
Configure environment variables.

Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET to the AccessKey ID and AccessKey secret of your Alibaba Cloud account.

Read the access credentials.

The following code reads access credentials from environment variables using the Credentials tool.

# -*- coding: utf-8 -*-
from alibabacloud_credentials.client import Client as CredClient

# Use CredClient to get the AccessKey ID and AccessKey secret from the environment variables.
cred = CredClient()
access_key_id = cred.get_credential().access_key_id
access_key_secret = cred.get_credential().access_key_secret

References

Fault handling