Getting started with Tablestore HBase Client - Tablestore

This topic describes how to use Tablestore HBase Client to develop a program that can access Tablestore.

Prerequisites

HBase data is migrated to Tablestore. For more information, see Data Integration.
A RAM user is created and permissions to perform operations on Tablestore are granted to the RAM user. For more information, see Use AccessKey pairs of RAM users to initiate requests.

Procedure

Note

In this example, Tablestore HBase Client that is compatible with HBase V2.x.x is used.

Step 1: Import Tablestore HBase Client dependencies

Add the following dependency to the pom.xml file of your project:

<dependencies>
    <dependency>
        <groupId>com.aliyun.openservices</groupId>
        <artifactId>tablestore-hbase-client</artifactId>
        <version>2.0.12</version>
    </dependency>
</dependencies>

Step 2: Configure the HBase file

Add the following parameters to the hbase-site.xml file and configure the endpoint of the Tablestore instance that you want to access, the name of the Tablestore instance that you want to access, and the AccessKey pair of the RAM user based on your business requirements.

<configuration>
    <property>
        <name>hbase.client.connection.impl</name>
        <value>com.alicloud.tablestore.hbase.TablestoreConnection</value>
    </property>
    <property>
        <name>tablestore.client.endpoint</name>
        <value>endpoint</value>
    </property>
    <property>
        <name>tablestore.client.instancename</name>
        <value>instance_name</value>
    </property>
    <property>
        <name>tablestore.client.accesskeyid</name>
        <value>access_key_id</value>
    </property>
    <property>
        <name>tablestore.client.accesskeysecret</name>
        <value>access_key_secret</value>
    </property>
    <property>
        <name>hbase.client.tablestore.family</name>
        <value>f1</value>
    </property>
    <property>
        <name>hbase.client.tablestore.table</name>
        <value>ots_adaptor</value>
    </property>
</configuration>

Step 3: Connect to Tablestore

The following sample code provides an example on how to create a TableStoreConnection object to connect to Tablestore:

Configuration config = HBaseConfiguration.create();

// Create a Tablestore Connection object. 
Connection connection = ConnectionFactory.createConnection(config);

// Admin is used to create, manage, and delete tables. 
Admin admin = connection.getAdmin();

Step 4: Perform table operations

Create a table

The following sample code provides an example on how to create a table that has a specific name. In this example, the default value of the MaxVersion and TimeToLive parameters is used.

// Create an HTableDescriptor, which contains only one ColumnFamily. 
HTableDescriptor descriptor = new HTableDescriptor(TableName.valueOf(TABLE_NAME));

// Create a ColumnFamily for which the default value of the MaxVersion and TimeToLive parameters is used. The default value of the MaxVersion parameter is 1. The default value of the TimeToLive parameter is Integer.INF_MAX. 
descriptor.addFamily(new HColumnDescriptor(COLUMN_FAMILY_NAME));

// Use the createTable operation of the Admin to create a table. 
System.out.println("Create table " + descriptor.getNameAsString());
admin.createTable(descriptor);

Delete a table

The following sample code provides an example on how to use Admin API to delete a table:

System.out.println("Delete the table");
admin.disableTable(table.getName());
admin.deleteTable(table.getName());

Step 5: Perform basic data operations

Write data

The following sample code provides an example on how to write a row of data to Tablestore.

// Create a Tablestore table to perform operations such as read, write, update, and deletion operations. 
Table table = connection.getTable(TableName.valueOf(TABLE_NAME));

// Create a PUT object to write a row whose primary key value is row_1. 
System.out.println("Write one row to the table");
Put put = new Put(ROW_KEY);

// Add an attribute column of the row to Tablestore. Tablestore supports only single column families. You need to specify the family name in the hbase-site.xml configuration file. If you do not specify the family name in the hbase-site.xml configuration file, the default value f is used. Therefore, when you write data to Tablestore, the COLUMN_FAMILY_NAME parameter can be left empty. 

put.addColumn(COLUMN_FAMILY_NAME, COLUMN_NAME, COLUMN_VALUE);

// Use HBase API to call the PUT operation to write the row to Tablestore. 
table.put(put);

Read data

Read a single row of data

The following sample code provides an example on how to read the data of a row:

// Create a GET object to read the row whose primary key value is ROW_KEY. 
Result getResult = table.get(new Get(ROW_KEY));
Result result = table.get(get);

// Display the results. 
String value = Bytes.toString(getResult.getValue(COLUMN_FAMILY_NAME, COLUMN_NAME));
System.out.println("Get one row by row key");
System.out.printf("\t%s = %s\n", Bytes.toString(ROW_KEY), value);

Scan data

Read data whose primary key values are within a specific range.

// Scan data of all rows in the table.
System.out.println("Scan for all rows:");
Scan scan = new Scan();
ResultScanner scanner = table.getScanner(scan);

// Print the results cyclically.
for (Result row : scanner) {
    byte[] valueBytes = row.getValue(COLUMN_FAMILY_NAME, COLUMN_NAME);
    System.out.println('\t' + Bytes.toString(valueBytes));
}

Complete sample code

Note

The sample program in this topic uses HBase API to access Tablestore. The complete sample program is located in the src/test/java/samples/HelloWorld.java directory of the HBase project at GitHub.

package samples;
import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.hbase.HBaseConfiguration;
import org.apache.hadoop.hbase.HColumnDescriptor;
import org.apache.hadoop.hbase.HTableDescriptor;
import org.apache.hadoop.hbase.TableName;
import org.apache.hadoop.hbase.client.*;
import org.apache.hadoop.hbase.util.Bytes;
import java.io.IOException;
public class HelloWorld {
    /** Specify the name of the data table. **/
    private static final byte[] TABLE_NAME = Bytes.toBytes("HelloTablestore");
    /** Specify the primary key of the row. **/
    private static final byte[] ROW_KEY = Bytes.toBytes("row_1");
    /** Specify the column family. **/
    private static final byte[] COLUMN_FAMILY_NAME = Bytes.toBytes("f");
    /** Specify the name of the column. **/
    private static final byte[] COLUMN_NAME = Bytes.toBytes("col_1");
     /** Specify the value of the column. **/
    private static final byte[] COLUMN_VALUE = Bytes.toBytes("col_value");
    public static void main(String[] args) {
        helloWorld();
    }
    private static void helloWorld() {
        try  {
            // Connect to Tablestore. 
            Configuration config = HBaseConfiguration.create();
            Connection connection = ConnectionFactory.createConnection(config);
            Admin admin = connection.getAdmin();
            
            // Create a data table. 
            HTableDescriptor descriptor = new HTableDescriptor(TableName.valueOf(TABLE_NAME));
            descriptor.addFamily(new HColumnDescriptor(COLUMN_FAMILY_NAME));
            System.out.println("Create table " + descriptor.getNameAsString());
            admin.createTable(descriptor);
            
            // Write data to Tablestore. 
            Table table = connection.getTable(TableName.valueOf(TABLE_NAME));
            System.out.println("Write one row to the table");
            Put put = new Put(ROW_KEY);
            put.addColumn(COLUMN_FAMILY_NAME, COLUMN_NAME, COLUMN_VALUE);
            table.put(put);
            Result getResult = table.get(new Get(ROW_KEY));
            
            // Read a single row of data. 
            String value = Bytes.toString(getResult.getValue(COLUMN_FAMILY_NAME, COLUMN_NAME));
            System.out.println("Get a one row by row key");
            System.out.printf("\t%s = %s\n", Bytes.toString(ROW_KEY), value);
            
            // Scan data. 
            Scan scan = new Scan();
            System.out.println("Scan for all rows:");
            ResultScanner scanner = table.getScanner(scan);
            for (Result row : scanner) {
                byte[] valueBytes = row.getValue(COLUMN_FAMILY_NAME, COLUMN_NAME);
                System.out.println('\t' + Bytes.toString(valueBytes));
            }
            
            // Delete the data table. 
            System.out.println("Delete the table");
            admin.disableTable(table.getName());
            admin.deleteTable(table.getName());
            
            // Close the connection. 
            table.close();
            admin.close();
            connection.close();
        } catch (IOException e) {
            System.err.println("Exception while running HelloTablestore: " + e.toString());
            System.exit(1);
        }
    }
}

References

You can use HBase Client of other versions or Tablestore SDK for Java. For more information, see Overview of Tablestore HBase Client.
For information about more parameters in the HBase file, see Migrate from HBase Client to Tablestore HBase Client.