Create and update the location cache

This topic describes how to create and update the location cache. Updates may occur automatically, manually, or based on specific triggering conditions.

What is the location cache?

The location cache, also known as the table entry or partition entry, is a list containing the IP addresses of all servers that host the replicas of a table. Three types of location caches are available:

• The location cache of a table or partition. It contains the IP addresses of all servers that host the replicas of the table or partition.

• The location cache of a user tenant. It contains the IP addresses of all servers of the tenant.

• The location cache of the sys tenant. It contains the IP addresses of all servers in the cluster.

Create and update the location cache of a table or partition

Create the location cache

When ODP accesses a table or partition for the first time, it queries the __all_virtual_proxy_schema WHERE table_name = "xxx" table of the sys tenant to get the location cache of the table or partition. This query uses the location cache of the sys tenant.

Automatically update the location cache

If the number of servers in the cluster changes, ODP randomly deletes expired servers within one minute.

Conditions that trigger the update of the location cache

• If strong consistency read is enabled and the leader replica is not found, ODP sets the location cache status to 'dirty'.

• If rerouting takes place under the following circumstances, ODP sets the location cache status to 'dirty':

• If rerouting does not take place under the following circumstances, ODP sets the location cache status to 'dirty':

• If the server returns the LOGIN_CONNECT_ERROR or REQUEST_CONNECT_ERROR error, ODP sets the location cache status to 'dirty'.

• During the execution of an SQL statement, if the server returns tenant not in server, ODP sets the location cache status to 'dirty'.

• When weak or strong consistency read is enabled, if the location cache of a table contains a replica that is not in the location cache of the tenant, but this replica is in the same IDC or region with the tenant, ODP sets the location cache status to 'dirty'.

• When a request is routed to a new server, but the number of failed connection attempts exceeds the threshold (a different server is tried every time an attempt fails), ODP sets the location cache status to 'dirty'.

Manually update the location cache

You can manually update the location cache of a table or partition through the following methods:

• Set enable_qa_mode = true and use the location_expire_period parameter. If the location cache has existed for a period longer than location_expire_period, it is deleted by ODP.

• Use the partition_location_expire_relative_time parameter. If the location cache was created before the sum of the time when you configured the partition_location_expire_relative_time parameter and the partition_location_expire_relative_time, it is deleted by ODP.

Create and update the location cache of a user tenant

Create the location cache

When ODP accesses a user tenant for the first time, it queries the __all_virtual_proxy_schema WHERE table_name = "__all_dummy" table of the sys tenant to get the location cache of the user tenant. This query uses the location cache of the sys tenant.

Automatically update the location cache

If the number of servers in the cluster changes, ODP randomly deletes expired servers within one minute.

Conditions that trigger the update of the location cache

• The status of the tenant location cache is checked by every transaction of every session. If the check fails, ODP sets the location cache status to 'dirty', and immediately updates the location cache. The check fails when the location cache of the tenant is in one of the following conditions:

• During the execution of an SQL statement, if the server returns tenant not in server, ODP sets the location cache status to 'dirty'.

• When weak or strong consistency read is enabled, if the location cache of a table contains a replica that is not in the location cache of the tenant, but this replica is in the same IDC or region with the tenant, ODP sets the location cache status to 'dirty'.

• When a request is routed to a new server, but the number of failed connection attempts exceeds the threshold (a different server is tried every time an attempt fails), ODP sets the location cache status to 'dirty'.

• If the number of servers in the cluster changes, ODP randomly deletes expired servers within one minute.

Manually update the location cache

You can manually update the location cache of a user tenant through the following methods:

• Set enable_qa_mode = true and use the location_expire_period parameter. If the location cache has existed for a period longer than location_expire_period, it is deleted by ODP.

• Use the partition_location_expire_relative_time parameter. If the location cache was created before the sum of the current time and the partition_location_expire_relative_time, it is deleted by ODP.

Note

If you change the location cache status to 'dirty' or delete it, you must update or create the location cache the next time you access the tenant. ODP will update a dirty location cache. The update of the location cache does not impact the processing of other concurrent requests. However, the processing of concurrent requests is suspended during the creation of the location cache.

Create and update the location cache of the sys tenant

Create the location cache

When you create a cluster, ODP obtains the location cache of the sys tenant from the RootService list. At this moment, the location cache of the sys tenant is RS list [null].

Automatically update the location cache

• After you create the cluster, ODP periodically accesses the all_virtual_proxy_server_stat table to get the list of servers. If the list is changed, ODP updates the location cache of the sys tenant. The location cache of the sys tenant then changes to RS list [list of servers] .

• When ODP retrieves the RS list from the configuration server, it updates the location cache of the sys tenant. At this moment, the location cache of the sys tenant is RS list [null].

Manually update the location cache

Set enable_qa_mode = true and use the location_expire_period parameter. If the location cache has existed for a period longer than location_expire_period, it is deleted by ODP.