Local Index

1. Function Description

A local index is an index of local data (each shard data). The local index is defined in the table definition file and created at the time the table is created.

Local indexes have the following features:

(1) It only supports to create local indexes on Key fields, and the fields of local indexes must also include splittable factors;

(2) The local index request must include all the fields of the index, and these fields are equivalent queries. On the basis of meeting this condition, the request can also carry a filter condition;

(3) It supports real-time index. When inserting or deleting data, the index data will be updated at the same time;

(4) A table can have multiple local indexes, but the maximum number is 8;

(5) Only Generic tables support local index;

(6) Once a table is created, local indexes cannot be added, modified or deleted. When a table is deleted, local indexes will be deleted as well;

2. Application Scenarios

When you need equivalent queries on partial key fields, you can consider using local indexes;

2.1. Examples

There is an activity table, defined as follows:

<struct name="UserActivityTable" version="1" primarykey="account,account_type,activity_id" splittablekey="account" >
    <entry name="account" type="uint64" desc="user account" />
    <entry name="account_type" type="string" size="64" desc="account type" />
    <entry name="activity_id" type="int32" desc="activity id" />
    <entry name="activity_info" type="ActivityInfo" desc="activity information" />
    <index name="index1" column="account" />
    <index name="index2" column="account, account_type" />
</struct>

The following two local indexes are defined in the table:

(1) Index name: index1, index field: account;

(2) Index name: index2, index fields: account, account_type;

Then, you can query as follows:

(1) Query information of all activities under a specified account through account;

(2) Query information of all activities under a specified account and account type through account + account_type;

3. Instructions

3.1. Creating An Index

Before creating a local index, it is necessary to know the relationship between local index fields and primary key fields and splittable factors: splittable factors must be a subset of local index fields, and local index fields must be a proper subset of primary key fields. This ensures that the data in the local index falls into the same data shard;

For details about how to define a local index in a table, see TDR Table and PB Table.

3.2.1. Query of partial keys

(1) First, the request must contain all the fields of a local index, and present the values of these fields, such as:

 If a local index with the fields key1 and key2 is defined, the values of key1 and key2 must be present when using this index to update part keys;

 TcaplusDB will get all records that meet key1=XXX and key2=XXX;

(2) Secondly, on the basis of meeting (1), the request can also carry a filter condition to filter the records meeting (1), and finally return the records meeting the filter condition to the user. For details, see Conditional Filter and Update.

In addition, when querying the local index, a lot of data may be returned. At this time, TcaplusDB will return in packets. If the service side packet receiving speed is lower than the speed of TcaplusDB returning response packets, it may lead to the packet loss of TcaplusDB due to the full network cache. It is recommended to use limit and offset for multiple requests when using local index queries, especially when the data volume is large;

For details about the interface for querying partial keys, see the descriptions of SDKS and API, TcaplusDB SDK & API.

3.2.2. Update of partial keys

(1) First, the request must contain all the fields of a local index, and present the values of these fields, such as:

 If a local index with the fields key1 and key2 is defined, the values of key1 and key2 must be present when using this index to update part keys;

 TcaplusDB will update all records that meet key1=XXX and key2=XXX;

(2) Secondly, on the basis of meeting (1), the request can also carry a filter condition to filter the records meeting (1), and finally update the records meeting the filter condition. For details, see Conditional Filter and Update.

For details about the interface for updating partial keys, see the descriptions of SDKS and API, TcaplusDB SDK & API.

3.2.3. Deletion of partial keys

(1) First, the request must contain all the fields of a local index, and present the values of these fields, such as:

 If a local index with the fields key1 and key2 is defined, the values of key1 and key2 must be present when using this index to delete part keys;

 TcaplusDB will delete all records that meet key1=XXX and key2=XXX;

(2) Secondly, on the basis of meeting (1), the request can also carry a filter condition to filter the records meeting (1), and finally delete the records meeting the filter condition. For details, see Conditional Filter and Update.

For details about the interface for updating partial keys, see the descriptions of SDKS and API, TcaplusDB SDK & API.

4. Notations

Assuming that the local index contains fields key1 and key2, if there are a large number of records with key1 = XXX and key2 = XXX, it is easy to have performance problems when querying the local index under this condition, which should be avoided as far as possible. Of course, TcaplusDB does not limit the number of records at present.

results matching ""

    No results matching ""