Query global table information

Use the Tablestore SDK for Java to query a global table's status and the location, writability, and synchronization status of its member physical tables.

Prerequisites

Version 5.17.7 or later of the Initialize the client, with a client initialized.

Feature description

Call describeGlobalTable to query the status and member physical tables of a global table.

public DescribeGlobalTableResponse describeGlobalTable(DescribeGlobalTableRequest request) throws TableStoreException, ClientException

The following example queries a global table by global table ID.

String globalTableId = "gt-01234567-89ab-cdef-0123-456789abcdef";
String globalTableName = "example_table";
DescribeGlobalTableRequest request = new DescribeGlobalTableRequest(
        globalTableId, globalTableName);

DescribeGlobalTableResponse response = client.describeGlobalTable(request);
System.out.println("GlobalTableId: " + response.getGlobalTableId());
System.out.println("Status: " + response.getStatus());

for (GlobalTableTypes.PhyTable table : response.getPhyTables()) {
    System.out.println(
            table.getRegionId() + "/" + table.getInstanceName()
                    + " status=" + table.getStatus()
                    + " writable=" + table.isWritable());
}

Parameters

DescribeGlobalTableRequest contains the following parameters.

Name	Type	Description
globalTableName (required)	String	The global table name. The name must be the same as the base table name.
globalTableId (optional)	String	The global table ID. You must specify either `globalTableId` or `phyTable`. If you did not record the global table ID, call `DescribeTable` on a member physical table. The response contains the global table ID.
phyTable (optional)	GlobalTableTypes.PhyTable	Locates a global table by a member physical table. You must specify either `globalTableId` or `phyTable`. The SDK sets this parameter when you use the `DescribeGlobalTableRequest(String globalTableName, String regionId, String instanceName)` constructor.
returnRpo (optional)	boolean	Specifies whether to request Recovery Point Objective (RPO) information. Default value: `false`. Retrieving RPO information takes longer. Set this parameter to `true` only when you need the information.

Physical table locator

When you locate a global table by a member physical table, phyTable contains the following parameters.

Name	Type	Description
regionId (required)	String	The region ID of the member physical table.
instanceName (required)	String	The instance name of the member physical table. The name must match the instance accessed by the current client.

Response

DescribeGlobalTableResponse contains the following fields.

Field	Type	Description
globalTableId	String	Obtain the global table ID by calling `getGlobalTableId()`.
status	GlobalTableTypes.GlobalTableStatus	Obtain the global table status by calling `getStatus()`.
phyTables	`List<GlobalTableTypes.PhyTable>`	Obtain the member physical tables by calling `getPhyTables()`. A query by global table ID returns the complete list.

Global table status

status supports the following values.

Value	Description
INIT	Initializing. A global table enters this state after it is first created.
RE_CONF	Reconfiguring. One or more physical tables are being configured because a table is being created, historical data is being synchronized, or a member is being added or removed.
ACTIVE	Active.

Physical table information

Each element in phyTables[] is a GlobalTableTypes.PhyTable object that contains the following fields.

Field	Type	Description
regionId	String	Obtain the region ID of the physical table by calling `getRegionId()`.
instanceName	String	Obtain the instance name of the physical table by calling `getInstanceName()`.
tableName	String	Obtain the physical table name by calling `getTableName()`.
status	GlobalTableTypes.PhyTableStatus	Obtain the physical table status by calling `getStatus()`.
statusTimestamp	long	Obtain the timestamp of the last status update by calling `getStatusTimestamp()`. Unit: milliseconds.
writable	boolean	Determine whether the physical table is writable by calling `isWritable()`.
role	String	Obtain the role of the physical table in the serving mode by calling `getRole()`.
tableId	String	Obtain the physical table ID by calling `getTableId()`.
stage	GlobalTableTypes.SyncStage	Obtain the data synchronization stage by calling `getStage()`.
rpo	Instant	Obtain the RPO of the data in the physical table by calling `getRpo()`. Set `returnRpo` to `true` to request this information.
isFailed	boolean	Determine whether the physical table is in a failed state by calling `isFailed()`.
message	String	Obtain additional status information by calling `getMessage()`. If creating the global table or adding or removing a member fails, `isFailed` is `true` and this field contains the failure cause.

Physical table status

phyTables[].status supports the following values.

Value	Description
PENDING	Queued. Processing continues after the other physical tables are configured.
INIT	Initializing. The physical table is being created or configured.
SYNCDATA	Synchronizing. Historical data is being synchronized, and incremental data synchronization is enabled.
READY	Ready. Historical data synchronization is complete, and the incremental synchronization channel is enabled. The physical table is not yet writable.
ACTIVE	Active and synchronizing. Check `writable` to determine whether the physical table is writable.
UNBINDING	Being removed. The physical table is being removed from the global table. The physical table and its data are not deleted.
UNBOUND	Removed. The physical table has been removed from the global table. The physical table and its data were not deleted.

Examples

Locate a global table by physical table

If you did not record the global table ID, use the name, region, and instance of a known member physical table to locate the global table.

Note

When you locate a global table by physical table, phyTables in the response is empty. To obtain the complete list of member physical tables, first obtain the global table ID by calling getGlobalTableId(), and then query by global table ID.

String globalTableName = "example_table";
String regionId = "cn-hangzhou";
String instanceName = "example-instance";
DescribeGlobalTableRequest request = new DescribeGlobalTableRequest(
        globalTableName, regionId, instanceName);

DescribeGlobalTableResponse response = client.describeGlobalTable(request);
System.out.println("GlobalTableId: " + response.getGlobalTableId());
System.out.println("Status: " + response.getStatus());