Modify search index schema-Tablestore(Tablestore)-阿里云帮助中心

How it works

Tablestore data tables are schema-free, but a search index has a rigid schema. When you create a search index, you must define which columns to index for querying. Modifying this schema is often necessary to support business changes or performance tuning. Common scenarios include:

Add index columns: As your business evolves, you may need to query additional columns.
Update index columns: You can change properties such as column type, virtual columns, array settings, analyzers, or date formats.
Delete index columns: You can remove columns that are no longer needed for queries.
Modify the routing key: A well-defined routing key can reduce read amplification and improve query performance.
Modify presorting: If the data sorting order in a query matches the presorting configuration of the index, query speed improves.

Workflow

Important

Because its behavior is dynamic, you must not use this temporary index for queries. If this feature does not meet your needs, submit a ticket to contact us.

The following figure shows the workflow for dynamically modifying a schema. The entire process is transparent to your application, allowing you to change the schema without modifying your application code.

The following table describes the main steps for modifying the schema of a search index.

Step	Actions	Description
1	Create a canary index	Create a canary index for the source index and define its new schema by adding, modifying, or deleting columns as needed.
2	Check the index synchronization progress	Before proceeding, wait until all existing and incremental data is synchronized and the progress of the canary index matches that of the source index.
3	Set weights for A/B testing	A/B testing allows you to distribute query traffic between the source and canary indexes to validate the new schema. Gradually redirect traffic to the canary index until it handles 100% of the query traffic.
4	Swap index schemas	After all query traffic is switched to the canary index, swap the schemas of the source index and the canary index. After the swap, the source index name points to the new schema, while the canary index name points to the old one. All query traffic is then directed to the source index name, which now uses the new schema.
5	Delete the canary index	After you swap the schemas and verify that the index works as expected, wait for a stabilization period (for example, one day) before deleting the canary index.

Procedure

Go to the Indexes tab.
1. Log on to the Tablestore console.
2. In the top navigation bar, select a region and resource group.
3. On the Overview page, click the instance name, or click Manage Instance in the Actions column.
4. On the Instance Details tab, in the Tables area, click the data table name or click Indexes in the Actions column.

Create a canary index based on the source index.

On the Indexes tab, find the search index, and click Change Schema in the Actions column.
In the Reindex dialog box, add, modify, or delete index fields as needed.

To modify the routing key or presorting method, enable Advanced Settings and configure the parameters described in the following table.

Parameter

Description

Routing key

Specifies custom routing fields. You can select one or more primary key columns as routing fields.

When data is written to the index, the system uses the routing key value to determine data distribution. Records with the same routing key value are indexed into the same partition. For more information, see Use routing fields in a search index.

Presorting

The default sorting method for data in the search index. Presorting determines the default order in which query results are returned. For more information, see Index presorting.

To sort by primary key, select Default.
To sort by field values or a combination of primary key columns, select Custom and configure the settings.
1. Select a sorting type, such as Primary Key Pre-sorting or Field Pre-sorting, and click Add.
2. Select the field name and sort order.
  
  The supported sort orders are ascending and descending.
  
  Important
  You must select a field name only if you choose Field Pre-sorting.
When using custom sorting, you can configure both primary key presorting and field presorting as needed.

Click OK.
In the Index Comparison dialog box, review the comparison of the routing key, presorting, and schema between the source and canary indexes. After you confirm that the information is correct, click Yes.

Check the index synchronization information.
1. Click the icon next to the source index or click the source index name.
  
  The canary index for the source index is displayed.
2. Click Use Gray Index in the Actions column of the canary index.
  Important
  The canary index goes through a full data synchronization phase and an incremental data synchronization phase.
  - Before data synchronization is complete, if you move the pointer over the Use Gray Index button in the Actions column, a tooltip that indicates Yes, but the operation may cause security risks. appears and the switchover is disabled.
  - When the canary index has caught up with the source index, if you move the pointer over the Use Gray Index button in the Actions column, a tooltip that indicates Yes. The operation is secure. appears. You can then proceed with the next steps.
3. In the Use Gray Index dialog box, view the index synchronization information.
After synchronization is complete, perform A/B testing by setting traffic weights.

Use A/B testing to validate the new schema by distributing query traffic between the source and canary indexes. You must switch all traffic to the canary index before you can proceed to the next step.
1. In the Operations section of the Use Gray Index dialog box, drag the slider to adjust the weights of the source and canary indexes, and then click Set Weight.
2. In the Set Weight dialog box, review the weight data and schema comparison.
3. After you confirm that the information is correct, click Set Weight.
4. In the confirmation dialog box that appears, click Yes.
After all query traffic is switched to the canary index, swap the schemas of the source and canary indexes.

After the swap, the source index name points to the new schema, and the canary index name points to the old one. All query traffic is then directed to the source index name, which now uses the new schema.
1. In the Operations section of the Use Gray Index dialog box, click Switch Index.
2. In the Switch Index dialog box, review the comparison of the routing key, presorting, and schema between the source and canary indexes. After you confirm that the information is correct, click Confirm Switch.
After you swap the schemas and verify that the index works as expected, wait for a stabilization period (for example, one day) before deleting the canary index.
1. In the Use Gray Index dialog box, click Delete Canary Release.
2. In the Are you sure you have completed the canary release and want to delete the old index? dialog box, confirm that the information about the canary index to be deleted is correct. Then, in the text box, enter I have confirmed that the new index data has been synchronized and has been in canary release for a period of time.
3. Click Yes.

Safeguards

To ensure operational safety, Tablestore provides a rollback mechanism and switchover alerts to minimize risks during index modification.

Rollback mechanism
Key steps in the dynamic schema modification process support rollbacks.
- After creating a canary index, if you find that its schema is incorrect, you can delete it and create a new one.
- During A/B testing, you can gradually redirect traffic to the canary index by adjusting traffic weights. If you encounter any issues, you can redirect traffic back to the source index at any time by resetting the weights.
- After swapping the schemas, if you find any issues, you can perform a Cancel Switchover at any time to revert to the source index's schema. The Switch Index and Cancel Switchover operations are inverse operations.
Switchover alerts

Switching traffic to the canary index before it is fully synchronized with the source index can cause queries to return stale data. Tablestore determines whether it is "safe to switch" based on the synchronization status and last synchronization time of both indexes.
Tablestore determines that a switchover is Yes. The operation is secure. under the following conditions:
- The source index is in the full synchronization phase, and the canary index is in either the full or incremental phase, meaning the canary index has caught up to the source index.
- Both the source and canary indexes are in the incremental synchronization phase, and the canary index's last sync time is no more than 60 seconds behind the source index's last sync time.

Billing

You are not charged for building canary indexes or writing data to them. You are charged for the storage that both indexes consume and for any reserved read CUs provisioned for them. For more information, see Billable items of search indexes.

Dynamically modify search index schema

How it works

Workflow

Procedure

Safeguards

Billing

Related documents