Tablestore Python SDK - Tablestore - Alibaba Cloud Documentation Center

The Tablestore Python software development kit (SDK) supports operations on wide table models and timeseries models.

Quick integration

This section describes how to quickly integrate the Tablestore Python SDK, from preparing the environment to authenticating the client.

Prepare the environment

Download and install the Python runtime environment. Run the python --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 based on your development environment. Use the latest version of the SDK to ensure that the code examples run correctly.

Install using pip (recommended)

Run the following command to install the Tablestore Python SDK.

pip install tablestore

Install from GitHub

Download the Tablestore SDK from GitHub using the git command and install it.

Run the following command to download the SDK.

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

Run the following command to navigate to the SDK installation package folder.
```
cd aliyun-tablestore-python-sdk
```
Run the following command to install the SDK.
```
python setup.py install
```

Install from source code

Download and install the SDK source code.

Download and decompress the Python SDK.
Navigate to the folder where you decompressed the SDK package.
Run the following command to install the SDK.
```
python setup.py install
```

Configure access credentials

Create an AccessKey for your Alibaba Cloud account or a RAM user. Then, configure the AccessKey in the environment variables as shown below. Configuring the AccessKey in environment variables improves security because it prevents you from hard-coding sensitive information in your code.

After the configuration is complete, you must restart or refresh your development environment. This includes your IDE, command-line interface, other desktop applications, and background services. This ensures that the latest system environment variables are loaded. For more information about other types of access credentials, see Configure access credentials.

Linux

Run the following commands to append the environment variable settings to the ~/.bashrc file.

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

Run the following command to apply the changes.
```
source ~/.bashrc
```
Run the following commands to verify that the environment variables are effective.
```
echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
```

macOS

Run the following command in the terminal to view your default shell type.
```
echo $SHELL
```
Perform the following operations based on your default shell type.
Zsh
1. Run the following commands to append the environment variable settings to the ~/.zshrc file.
```
echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
```
2. Run the following command to apply the changes.
```
source ~/.zshrc
```
3. Run the following commands to verify that the environment variables are effective.
```
echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
```
Bash
1. Run the following commands to append the environment variable settings to the ~/.bash_profile file.
```
echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile
```
2. Run the following command to apply the changes.
```
source ~/.bash_profile
```
3. Run the following commands to verify that the environment variables are effective.
```
echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET
```

Windows

CMD

Run the following commands in Command Prompt (CMD) to set the environment variables.

setx TABLESTORE_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx TABLESTORE_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Restart CMD and run the following commands to verify that the environment variables are effective.
```
echo %TABLESTORE_ACCESS_KEY_ID%
echo %TABLESTORE_ACCESS_KEY_SECRET%
```

PowerShell

Run the following commands 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)

Run the following commands to verify that the environment variables are effective.

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

Initialize the client

The following sample code initializes a client and then lists the data tables and timeseries tables in a Tablestore instance to authenticate the connection.

Important

Public network access is disabled by default for new instances. To access resources on an instance over the public network, you can enable public network access in the instance's Network Management settings.

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

import os
import sys
from tablestore import OTSClient

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

        # TODO: Modify the following configurations with your instance details.
        instance_name = "n01k********"  # Enter the instance name.
        endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"  # Enter the 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 timeseries tables.
        resp = client.list_timeseries_table()

        print(f"\nFound {len(resp)} timeseries 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. The following list describes its compatibility with previous versions:

Compatible with the 5.x.x series of the SDK.
Versions 5.4.x, 5.3.x, and 5.2.x are compatible. However, versions 5.2.1 and 5.1.0 have the following incompatibilities:
- The type of the return value for the Search method.
  In versions 5.1.0 and earlier, the method returns a Tuple object by default. Starting from version 5.2.0, the method returns a SearchResponse object by default. The SearchResponse object implements the __iter__ method and supports traversal. To return a Tuple object, use the SearchResponse.v1_response() method.
- The new ParallelScan method.
  By default, the method returns a ParallelScanResponse object. To return a Tuple object, use the ParallelScanResponse.v1_response() method.
Compatible with the 4.x.x series of the SDK.
Not compatible with the 2.x.x series of the SDK. This is because versions in the 2.0 series support out-of-order primary keys, but versions 4.0.0 and later do not. The incompatibilities include the following:
- The package name changed from ots2 to tablestore.
- The TableOptions parameter was added to the Client.create_table method.
- For methods such as put_row, get_row, and update_row, the type of the primary_key parameter changed from dict to list to ensure the order of primary keys.
- For methods such as put_row and update_row, the type of the attribute_columns parameter changed from dict to list.
- A timestamp was added to the attribute_columns parameter for methods such as put_row and update_row.
- Methods such as get_row and get_range now include the max_version, time_range parameters. You must specify at least one of these two parameters.
- Operations such as put_row, update_row, and delete_row now support the return_type parameter. The only supported value for this parameter is RT_PK, which specifies that the return value includes the primary key (PK) of the row.
- Operations such as put_row, update_row, and delete_row now include the return_row field in their return value. If you set the return_type parameter to RT_PK in a request, the return_row field contains the PK value of the row.

FAQ

What do I do if a "Signature mismatch" error occurs when I use the SDK?

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 specified during client initialization is incorrect.
Solution: Provide the correct AccessKey, which includes the AccessKey ID and AccessKey secret.

What do I do if a "Request denied by instance ACL policies" error occurs when I use the SDK?

The following Request denied by instance ACL policies exception occurs when you use the SDK to access resources in a Tablestore instance. An example error is shown below:

[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 network type used by the client does not meet the network access requirements of the instance. For example, the client uses the Internet, but the instance is not configured to allow access over the Internet.
Solution: By default, public network access is disabled for new instances. To access resources in an instance over the Internet, enable public network access as follows:
1. Go to the Tablestore console and click the instance alias.
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 when I use the SDK?

The following Request denied because this instance can only be accessed from the bound VPC exception occurs when you use the SDK to access resources in a Tablestore instance. An example error is shown below:

[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: If the access type of the Tablestore instance is set to Bound VPCs Only or Tablestore Console or Bound VPCs, you must attach a VPC to the instance. You must also ensure that the client is in the same VPC as the instance and accesses Tablestore using a VPC endpoint.
Solution: Change the instance access type to allow Internet access, or attach a VPC to the Tablestore instance and ensure that the client is within that VPC network. To attach a VPC:
1. Go to the Tablestore console and click the instance alias.
2. Click Network Management > Bind VPC. Select a VPC ID and a VSwitch, enter a VPC Name, and then click OK.

How do I use the HTTPS protocol to access Tablestore resources?

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 if some protobuf versions are incompatible?

Some protobuf versions are not compatible with the *pb2.py files in the current installation package. To resolve this issue, you can manually generate the *pb2.py files by following these steps:

Use your current version of protoc to generate the code for the corresponding proto files in sequence.

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 three generated files with the pb2.py extension. Then, copy the files to the tablestore/protobuf/ folder in the installation directory to replace the original *pb2.py files.

How do I use the Credentials tool to read access credentials?

Run the following command to install the alibabacloud_credentials package.
```
pip install alibabacloud_credentials
```
Configure environment variables.
Configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables. These represent the AccessKey ID and AccessKey secret of your Alibaba Cloud account.

Read the access credentials.

The following sample code shows how to use the Credentials tool to read access credentials from environment variables.

# -*- 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