All Products
Search

This Product

    Tablestore:Initialize a Tablestore client

    Document Center

    Tablestore:Initialize a Tablestore client

    Last Updated:Feb 21, 2025

    A Tablestore client is a client for Tablestore. A Tablestore client provides various methods that you can use to perform operations on tables and data in Tablestore. This topic describes how to use Tablestore SDK for Java to initialize a Tablestore client.

    Important

    In the examples in this topic, the AccessKey pair of an Alibaba Cloud account is used. You can also use the AccessKey pair of a Resource Access Management (RAM) user or temporary access credentials obtained from Security Token Service (STS) to initialize a Tablestore client. For more information, see Use the AccessKey pair of a RAM user to access Tablestore and Use temporary access credentials obtained from STS to access Tablestore.

    Preparations

    Before you initialize a Tablestore client, you must obtain information about the Tablestore instance that you want to access, install Tablestore SDK for Java, and configure access credentials.

    Obtain information about the instance that you want to access

    • Region ID: the ID of the region in which the instance resides. For example, the ID of the China (Hangzhou) region is cn-hangzhou. For more information about regions, see Regions.

    • Instance name and endpoint: Each Tablestore instance has an endpoint. You must specify an endpoint before you can perform operations on the data and tables in Tablestore. You can perform the following steps to obtain the endpoint of an instance:

      1. Log on to the Tablestore console.

      2. In the top navigation bar, select a resource group and a region.

      3. On the Overview page, click the name of the instance that you want to manage or click Manage Instance in the Actions column of the instance.

      4. On the Instance Details tab, view the name and URLs of the instance.

    Install Tablestore SDK for Java

    If you use Maven to manage Java projects, add the following dependency to the pom.xml file:

    <dependency>
    <groupId>com.aliyun.openservices</groupId>
    <artifactId>tablestore</artifactId>
    <version>5.17.2</version>
</dependency>

    For information about how to install Tablestore SDK for Java, see Install Tablestore SDK for Java.

    Configure access credentials

    To use Tablestore SDK for Java to initiate a request to access Tablestore, you must configure access credentials. Alibaba Cloud verifies your identity and access permissions based on the access credentials.

    In the examples in this topic, the AccessKey pair of an Alibaba Cloud account is used to describe how to configure access credentials. For more information, see How do I obtain an AccessKey pair?

    If you save access credentials to the code, information leaks may occur. We recommend that you save access credentials to system environment variables.

    Windows

    Run the command prompt as an administrator and run the following commands: 

    # Specify the AccessKey ID.
setx TABLESTORE_ACCESS_KEY_ID your_access_key_id /m
# Specify the AccessKey secret.
setx TABLESTORE_ACCESS_KEY_SECRET your_access_key_secret /m
    macOS/Linux/Unix
    # Specify the AccessKey ID.
export TABLESTORE_ACCESS_KEY_ID=your_access_key_id
# Specify the AccessKey secret.
export TABLESTORE_ACCESS_KEY_SECRET=your_access_key_secret

    For information about how to configure access credentials, see Configure access credentials.

    Initialize a client

    You must initialize a client and call the methods provided by the client to access Tablestore. Tablestore provides the SyncClient and AsyncClient clients for the Wide Column model and the TimeseriesClient and AsyncTimeseriesClient clients for the TimeSeries model. You can synchronously call the methods provided by the SyncClient and TimeseriesClient clients and asynchronously call the methods provided by the AsyncClient and AsyncTimeseriesClient clients.

    Note

    Multiple threads can share the same client object without causing security issues regardless of whether the client is a synchronous client or an asynchronous client. The client automatically manages the threads and connection resources. You do not need to create a client for each thread or request. We recommend that multiple threads share the same Tablestore client object.

    Wide Column model

    (Recommended) Use a V4 signature

    The following sample code provides an example on how to use a V4 signature to initialize a Tablestore client, query the list of data tables in an instance, and display the list of data tables in the Tablestore console: 

    import com.alicloud.openservices.tablestore.ClientConfiguration;
import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.core.auth.V4Credentials;
import com.alicloud.openservices.tablestore.model.AlwaysRetryStrategy;
import com.alicloud.openservices.tablestore.model.ListTableResponse;

public class InitClientV4 {
    public static void main(String[] args) {
        // Specify the region in which the instance that you want to access resides. Example: cn-hangzhou.
        final String region = "yourRegion";
        // Specify the name of the instance.
        final String instanceName = "yourInstanceName";
        // Specify the endpoint of the instance.
        final String endpoint = "yourEndpoint";
        // Obtain the AccessKey ID and AccessKey secret from the system environment variables.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // Construct a V4 signature.
        DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
        V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
        CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

        // Initialize a Tablestore client.
        SyncClient client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

        /*
        // You can use ClientConfiguration to modify the default configurations. The following example includes specific custom configurations. 
        ClientConfiguration clientConfiguration = new ClientConfiguration();
        clientConfiguration.setConnectionTimeoutInMillisecond(5000); // Specify the timeout period for establishing a connection. Unit: milliseconds. 
        clientConfiguration.setSocketTimeoutInMillisecond(5000); // Specify the socket timeout period. Unit: milliseconds. 
        clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy()); // Specify a retry policy. If you do not specify a retry policy, the default retry policy is used. 
        SyncClient client = new SyncClient(endpoint, provider, instanceName, clientConfiguration, new ResourceManager(null, null));
         */

        // Query the list of data tables in the instance and display the list in the Tablestore console.
        ListTableResponse listTableResponse = client.listTable();
        listTableResponse.getTableNames().forEach(System.out::println);

        // Shut down the Tablestore client.
        client.shutdown();
    }
}

    Use a V2 signature

    The following sample code provides an example on how to use a V2 signature to initialize a Tablestore client, query the list of data tables in an instance, and display the list of data tables in the Tablestore console: 

    import com.alicloud.openservices.tablestore.ClientConfiguration;
import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.model.AlwaysRetryStrategy;
import com.alicloud.openservices.tablestore.model.ListTableResponse;

public class InitClientV2 {
    public static void main(String[] args) {
        // Specify the name of the instance.
        final String instanceName = "yourInstanceName";
        // Specify the endpoint of the instance.
        final String endpoint = "yourEndpoint";
        // Obtain the AccessKey ID and AccessKey secret from the system environment variables.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // Construct a V2 signature.
        DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
        CredentialsProvider provider = new DefaultCredentialProvider(credentials);

        // Initialize a Tablestore client.
        SyncClient client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

        /*
        // You can use ClientConfiguration to modify the default configurations. The following example includes specific custom configurations. 
        ClientConfiguration clientConfiguration = new ClientConfiguration();
        clientConfiguration.setConnectionTimeoutInMillisecond(5000); // Specify the timeout period for establishing a connection. Unit: milliseconds. 
        clientConfiguration.setSocketTimeoutInMillisecond(5000); // Specify the socket timeout period. Unit: milliseconds. 
        clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy()); // Specify a retry policy. If you do not specify a retry policy, the default retry policy is used. 
        SyncClient client = new SyncClient(endpoint, provider, instanceName, clientConfiguration, new ResourceManager(null, null));
         */

        // Query the list of data tables in the instance and display the list in the Tablestore console.
        ListTableResponse listTableResponse = client.listTable();
        listTableResponse.getTableNames().forEach(System.out::println);

        // Shut down the Tablestore client.
        client.shutdown();
    }
}

    TimeSeries model

    (Recommended) Use a V4 signature

    The following sample code provides an example on how to use a V4 signature to initialize a Tablestore TimeseriesClient, query the list of time series tables in an instance, and display the list of time series tables in the Tablestore console: 

    import com.alicloud.openservices.tablestore.ClientConfiguration;
import com.alicloud.openservices.tablestore.TimeseriesClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.core.auth.V4Credentials;
import com.alicloud.openservices.tablestore.model.AlwaysRetryStrategy;
import com.alicloud.openservices.tablestore.model.timeseries.ListTimeseriesTableResponse;

public class InitTimeseriesClientV4 {
    public static void main(String[] args) {
        // Specify the region in which the instance that you want to access resides. Example: cn-hangzhou.
        final String region = "yourRegion";
        // Specify the name of the instance.
        final String instanceName = "yourInstanceName";
        // Specify the endpoint of the instance.
        final String endpoint = "yourEndpoint";
        // Obtain the AccessKey ID and AccessKey secret from the system environment variables.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // Construct a V4 signature.
        DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
        V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
        CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

        // Initialize a Tablestore TimeSeriesClient.
        TimeseriesClient client = new TimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

        /*
        // You can use ClientConfiguration to modify the default configurations. The following example includes specific custom configurations. 
        ClientConfiguration clientConfiguration = new ClientConfiguration();
        clientConfiguration.setConnectionTimeoutInMillisecond(5000); // Specify the timeout period for establishing a connection. Unit: milliseconds. 
        clientConfiguration.setSocketTimeoutInMillisecond(5000); // Specify the socket timeout period. Unit: milliseconds. 
        clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy()); // Specify a retry policy. If you do not specify a retry policy, the default retry policy is used. 
        TimeseriesClient client = new TimeseriesClient(endpoint, provider, instanceName, clientConfiguration, new ResourceManager(null, null));
         */

        // Query the list of time series tables in the instance and display the list in the Tablestore console.
        ListTimeseriesTableResponse listTimeseriesTableResponse = client.listTimeseriesTable();
        listTimeseriesTableResponse.getTimeseriesTableNames().forEach(System.out::println);

        // Shut down the Tablestore TimeseriesClient.
        client.shutdown();
    }
}

    Use a V2 signature

    The following sample code provides an example on how to use a V2 signature to initialize a Tablestore TimeseriesClient, query the list of time series tables in an instance, and display the list of time series tables in the Tablestore console: 

    import com.alicloud.openservices.tablestore.ClientConfiguration;
import com.alicloud.openservices.tablestore.TimeseriesClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.model.AlwaysRetryStrategy;
import com.alicloud.openservices.tablestore.model.timeseries.ListTimeseriesTableResponse;

public class InitTimeseriesClientV2 {
    public static void main(String[] args) {
        // Specify the name of the instance.
        final String instanceName = "yourInstanceName";
        // Specify the endpoint of the instance.
        final String endpoint = "yourEndpoint";
        // Obtain the AccessKey ID and AccessKey secret from the system environment variables.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // Construct a V2 signature.
        DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
        CredentialsProvider provider = new DefaultCredentialProvider(credentials);

        // Initialize a Tablestore TimeSeriesClient.
        TimeseriesClient client = new TimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

        /*
        // You can use ClientConfiguration to modify the default configurations. The following example includes specific custom configurations. 
        ClientConfiguration clientConfiguration = new ClientConfiguration();
        clientConfiguration.setConnectionTimeoutInMillisecond(5000); // Specify the timeout period for establishing a connection. Unit: milliseconds. 
        clientConfiguration.setSocketTimeoutInMillisecond(5000); // Specify the socket timeout period. Unit: milliseconds. 
        clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy()); // Specify a retry policy. If you do not specify a retry policy, the default retry policy is used. 
        TimeseriesClient client = new TimeseriesClient(endpoint, provider, instanceName, clientConfiguration, new ResourceManager(null, null));
         */

        // Query the list of time series tables in the instance and display the list in the Tablestore console.
        ListTimeseriesTableResponse listTimeseriesTableResponse = client.listTimeseriesTable();
        listTimeseriesTableResponse.getTimeseriesTableNames().forEach(System.out::println);

        // Shut down the Tablestore TimeseriesClient.
        client.shutdown();
    }
}

    FAQ

    References

    • To ensure the security of your AccessKey pair, we recommend that you use a V4 signature when you initialize a client.Tablestore For more information, see AccessKey pair security.