Use table replicas

This topic describes some common modifications that you can make to table-level replicas.

For more information about tenant-level replica modifications, see Manage locality.

You can specify the locality of a table when you create the table or by using the ALTER TABLE statement. Example:

CREATE TABLE table_name (...) locality='XXX,XXX,XXX';
ALTER TABLE table_name SET locality='XXX,XXX,XXX';

Scope of locality changes

For tables whose locality is empty, changes made to the locality of the tenant also apply to tables in the tenant. For tables whose locality is not empty, you can change the locality of the table to adjust the distribution of the replicas. This means that the object of table-level locality modifications must be a table with a non-empty locality.

Change locality and query change progress

The operations for changing the table-level and tenant-level locality are the same. One locality change can only apply to one zone. The new table locality must not contradict the locality of the tenant. The processes for changing the table-level and tenant-level locality are the same, but for a table-level change, the object of the change is the locality of a single table. To view the progress of a locality change, log on to the sys tenant and execute the following statement:

obclient> SELECT gmt_create, gmt_modified, tenant_id, table_name, job_type, job_status FROM __all_rootservice_job WHERE job_type LIKE '%LOCALITY%' ORDER BY job_id DESC;

Note

You can also use the preceding statement to query the progress of a tenant-level locality change. In the returned result, tenant_id and table_name specify the value of the corresponding objects. For a table-level locality change, the returned tenant_id is NULL.

Operational notes

• The locality change of different tables can be executed at the same time if the tables all have a non-empty locality at the beginning.

• When the locality of a table is being changed and its original locality is not empty, the locality of the tenant to which the table belongs cannot be changed. If you execute the ALTER TENANT statement to try to change the tenant locality, the execution of the statement fails.

• To change the number of non-Paxos replicas in a zone or region for a table whose locality is not empty, you must change the attribute of the tenant-level locality. Non-Paxos replicas refer to replicas that do not participate in elections, such as read-only and mem-only replicas. The load-balancing thread of the RootService performs the task that increases or decreases the number of non-Paxos replicas.

• To change the number of non-Paxos replicas in a zone or region for a table whose locality is empty, you can use the ALTER TABLE statement to modify the table property. For example, suppose that a tenant has the following locality: tenant Locality=F@z1,F@z2,F@z3. The tenant has a table whose locality is empty. You can use the ALTER TABLE statement to change the locality of the table to Locality=F@z1,F@z2,R@z3. After the change, the table no longer has an empty locality. In this case, the load-balancing thread of the RootService also performs the task that increases or decreases the number of non-Paxos replicas.

• You cannot change a non-empty locality of a table to an empty value.

• The locality of the sys tenant and table in the sys tenant must be the same. This means that if the locality of a system table is empty, you cannot change it.

• To increase, decrease, or change the locality of every table in a tenant, perform the following two steps:

  1. Change the locality of the tenant.

  2. Change the locality of all the tables whose locality is not empty in the tenant.

     After you perform the first step, you must perform the second step and manually change the locality of tables. If you skip the second step, an unpredictable error will occur during the next tenant-level locality change.

Example

Suppose a cluster has three data centers in Hangzhou: hz1@Hangzhou, hz2@Hangzhou, and hz3@Hangzhou. A tenant has the following three default localities: F@hz1, F@hz2, and F@hz3.

If you want to define a table whose read-only replicas are deployed on each OBServer node in the cluster, use the following SQL statement to create it:

CREATE TABLE table_name (...) locality = 'F@hz1, F@hz2, F@hz3, R{all_server}@hz1, R{all_server}@hz2, R{all_server}@hz3';

You can execute the following ALTER TABLE statement to change its locality:

ALTER TABLE table_name set locality = 'F@hz1, F@hz2, F@hz3, R{all_server}@hz1, R{all_server}@hz2, R{all_server}@hz3';

When the status of the corresponding task record in the __all_rootservice_job table becomes SUCCESS, the table creation or locality change is completed. Notice

Table-level locality changes and tenant-level locality changes are subject to the following constraints:

• When a tenant locality change is not finished, the next tenant locality change can be executed.

• When a table with a non-empty original locality is going through a locality change, the locality of the tenant that hosts the table cannot be changed.

• If a table has a non-empty locality, a change made to this locality cannot be executed in a zone if the tenant-level locality change is not initiated in the zone.

In a word, you cannot implement more than one tenant-level locality change at the same time. Before you perform a table or tenant locality change, make sure that the previous change is completed.