Tablestore:Create a global table

Usage notes

Choose a service mode before creating a global table:

• Active-passive mode (PRIMARY_SECONDARY): The primary region handles reads and writes. Secondary regions are read-only. Data flows from the primary region to the secondary regions. Use this mode for local reads, disaster recovery, and hot standby.

• Multi-active mode (PEER_TO_PEER): All regions handle reads and writes. Conflicts are resolved at the row or column level using last-writer-wins (LWW), keeping the version with the latest timestamp. Use this mode for low-latency reads and writes across multiple regions.

After the creation request succeeds, the system asynchronously replicates data across regions. Call DescribeGlobalTable to monitor the status. The global table is ready when its status changes to active.

Prerequisites

Before you begin, ensure that you have:

• Instances created in both the source and destination regions

• A table in the source region with the following configuration: time to live (TTL) set to -1 (data never expires), max versions set to 1, max version offset set to unlimited (Integer.MAX_VALUE), and row versioning enabled (updateFullRow set to True)

  Important

  Enabling row versioning applies the following limits:

  • A single row can contain a maximum of 256 columns

  • Version numbers are generated automatically by the system. You cannot specify them manually when writing data

  • Each Update operation reads the current row version first, resulting in a minor increase in read load

• A configured client

  Important

  If you initialize the client with a Resource Access Management (RAM) user's AccessKey, the RAM user must have permission to create global tables. For the required Action definitions, see Tablestore API operations.

Method

public CreateGlobalTableResponse createGlobalTable(CreateGlobalTableRequest createGlobalTableRequest) throws TableStoreException, ClientException

Examples

private static void createGlobalTableExample(SyncClient client){
    // Construct the request.
    CreateGlobalTableRequest req = new CreateGlobalTableRequest(
            // Configure the base table. The table must already exist.
            new GlobalTableTypes.BaseTable(
                    // The region ID of the base table.
                    "cn-hangzhou",
                    // The instance name of the base table.
                    "i-gt-test",
                    // The name of the base table. This is also the name of the global table.
                    "t-gt-test-1"
            ),
            // The synchronization mode. Only ROW (row-level synchronization) is supported.
            GlobalTableTypes.SyncMode.ROW
    );

    // Add associated tables. You can add multiple tables.
    req.addPlacement(new GlobalTableTypes.Placement(
            // The region ID of the associated table.
            "cn-shanghai",
            // The instance name of the associated table. The instance must already exist.
            // The instance cannot contain a table with the same name as the base table. The system creates the table automatically.
            "i-dest-test",
            // false = read-only secondary in active-passive mode.
            false
    ));

    // Set the service mode to active-passive (PRIMARY_SECONDARY).
    req.setServeMode(GlobalTableTypes.ServeMode.PRIMARY_SECONDARY);

    // Send the request.
    CreateGlobalTableResponse createResp = client.createGlobalTable(req);

    // Print the response.
    System.out.println("Global table creation initiated.");
    System.out.println("RequestId: " + createResp.getRequestId());
    System.out.println("GlobalTableId: " + createResp.getGlobalTableId());
}

private static void createGlobalTableExample(SyncClient client){
    // Construct the request.
    CreateGlobalTableRequest req = new CreateGlobalTableRequest(
            // Configure the base table. The table must already exist.
            new GlobalTableTypes.BaseTable(
                    // The region ID of the base table.
                    "cn-hangzhou",
                    // The instance name of the base table.
                    "i-gt-test",
                    // The name of the base table. This is also the name of the global table.
                    "t-gt-test-1"
            ),
            // The synchronization mode. Only ROW (row-level synchronization) is supported.
            GlobalTableTypes.SyncMode.ROW
    );

    // Add associated tables. You can add multiple tables.
    req.addPlacement(new GlobalTableTypes.Placement(
            // The region ID of the associated table.
            "cn-shanghai",
            // The instance name of the associated table. The instance must already exist.
            // The instance cannot contain a table with the same name as the base table. The system creates the table automatically.
            "i-dest-test",
            // true = all regions accept writes in multi-active mode.
            true
    ));

    // Set the service mode to multi-active (PEER_TO_PEER).
    req.setServeMode(GlobalTableTypes.ServeMode.PEER_TO_PEER);

    // Send the request.
    CreateGlobalTableResponse createResp = client.createGlobalTable(req);

    // Print the response.
    System.out.println("Global table creation initiated.");
    System.out.println("RequestId: " + createResp.getRequestId());
    System.out.println("GlobalTableId: " + createResp.getGlobalTableId());
}