Create a search index

Create a search index for a table and configure index fields, presorting, time-to-live (TTL), virtual columns, and highlighting with Tablestore SDK for Java.

Prerequisites

Before you begin, make sure that:

You have installed the Tablestore SDK for Java and initialized the client.
The table exists and its maximum number of data versions is 1.
The table TTL is -1, or updates with UpdateRow are disabled.

Description

Call createSearchIndex to create a search index for a table. You can create multiple search indexes for the same table. In the request, specify the table name, index name, and complete index schema, and add the columns that you want to query to fieldSchemas. The data type of each index field must match the corresponding column type in the table.

public CreateSearchIndexResponse createSearchIndex(CreateSearchIndexRequest request)

Note

Search index creation is asynchronous. After the request succeeds, query the index information and wait until the index status changes to RUNNING before you query data.

The following example creates example_index for example_table with Keyword and Long fields. Without presorting or TTL settings, the index is sorted by primary key and its data does not expire.

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);

client.createSearchIndex(request);

Parameters

CreateSearchIndexRequest contains the following parameters:

Name	Type	Description
tableName (required)	`String`	The table name.
indexName (required)	`String`	The search index name.
indexSchema (required)	`IndexSchema`	The index schema.
sourceIndexName (optional)	`String`	The source index name for index rebuilding. Set this parameter only when you dynamically modify a search index schema.
timeToLive (optional)	`Integer`	The index data TTL in seconds. Default value: -1. Set this parameter to -1 or an integer of at least 86,400. A value of -1 means that data does not expire. Tablestore automatically deletes data after its retention period exceeds this value. To set a value other than -1, disable `UpdateRow` updates for the table. The index TTL cannot exceed the table TTL. After the index is created, you can call `updateSearchIndex` to change the value. To specify the TTL in days, call `setTimeToLiveInDays`. For more information, see Configure the TTL of a search index.

Index schema

indexSchema is of the IndexSchema type and contains the following parameters.

Name	Type	Description
fieldSchemas (required)	`List<FieldSchema>`	The index fields.
indexSetting (optional)	`IndexSetting`	The index settings.
indexSort (optional)	`Sort`	The index presorting settings. If this parameter is not set and the index does not contain a Nested field, Tablestore sorts by primary key. Nested indexes do not support presorting.

Index fields

Each element in indexSchema.fieldSchemas[] is of the FieldSchema type and contains the following parameters.

Name	Type	Description
fieldName (required)	`String`	The index field name. The field can map to a primary key column or an attribute column.
fieldType (required)	`FieldType`	The index field type. Use Nested for multilayer relationships, JSON for JSON-formatted data, and Geo-point for geographic data. You can also store JSON-formatted data as strings and query it with array or Nested fields.
index (optional)	`boolean`	Specifies whether to create an inverted or spatial index for the field. Default value: `true`. If set to `false`, no index is created for the field.
enableHighlighting (optional)	`boolean`	Specifies whether to enable summary and highlighting. Only Text fields support this feature. Default value: `false`.
analyzer (optional)	`String`	The analyzer for a Text field. If this parameter is not set, single-character tokenization is used.
analyzerParameter (optional)	`AnalyzerParameter`	The analyzer settings. If you set `analyzer`, you must configure the parameters required by that analyzer.
enableSortAndAgg (optional)	`boolean`	Specifies whether to enable sorting and aggregation. Default value: `true`. Text fields do not support sorting or aggregation. To sort or aggregate Text content, create a Keyword virtual column.
isArray (optional)	`boolean`	Specifies whether the field is an array. Write array values as JSON arrays. You do not need to set this parameter for Nested fields.
subFieldSchemas (optional)	`List<FieldSchema>`	The subfields of a Nested field. This parameter is required for a Nested field.
isVirtualField (optional)	`boolean`	Specifies whether the field is a virtual column. Default value: `false`.
sourceFieldNames (optional)	`List<String>`	The table fields mapped to the virtual column. This parameter is required for a virtual column.
dateFormats (optional)	`List<String>`	The date formats supported by a Date field. This parameter is required for a Date field.
vectorOptions (optional)	`VectorOptions`	The vector data type, dimension, and distance metric. This parameter is required for a Vector field.
jsonType (optional)	`JsonType`	The index type of a JSON field. Valid values: `OBJECT` and `NESTED`. This parameter is required for a JSON field.

Vector options

indexSchema.fieldSchemas[].vectorOptions is of the VectorOptions type and contains the following parameters.

Name	Type	Description
dataType (required)	`VectorDataType`	The vector data type. Only `FLOAT_32` is supported.
dimension (required)	`Integer`	The vector dimension. Maximum value: 4,096.
metricType (required)	`VectorMetricType`	The distance metric. Valid values: `EUCLIDEAN`, `COSINE`, and `DOT_PRODUCT`. A higher score indicates greater similarity. `EUCLIDEAN` measures straight-line distance and omits the final square-root calculation in Tablestore. `COSINE` measures the cosine of the angle between vectors and is commonly used for text similarity. `DOT_PRODUCT` multiplies corresponding coordinates of equal-dimension vectors and sums the results. For more information, see Distance metric algorithms.

Index settings

indexSchema.indexSetting is of the IndexSetting type and contains the following parameter.

Name	Type	Description
routingFields (optional)	`List<String>`	The custom routing fields. Select one or more primary key columns. In most cases, one field is sufficient. If you specify multiple fields, Tablestore concatenates their values. Tablestore uses the routing field values to distribute index data and writes records with the same values to the same data partition.

Index presorting

indexSchema.indexSort is of the Sort type and contains the following parameter.

Name	Type	Description
sorters (optional)	`List<Sort.Sorter>`	The presorters. `PrimaryKeySort` sorts by primary key, and `FieldSort` sorts by field value. Fields used in `FieldSort` must be indexed with sorting and aggregation enabled. For more information, see Sort and paginate results.

Primary key sorting

An element of the indexSchema.indexSort.sorters[] path whose type is PrimaryKeySort presorts by primary key and contains the following parameter.

Name	Type	Description
order (optional)	`SortOrder`	The primary key sort order. Valid values: `SortOrder.ASC` and `SortOrder.DESC`. Default value: `SortOrder.ASC`.

Field sorting

An element of the indexSchema.indexSort.sorters[] path whose type is FieldSort presorts by field value and contains the following parameters.

Name	Type	Description
fieldName (required)	`String`	The field used for presorting.
order (optional)	`SortOrder`	The field sort order. Valid values: `SortOrder.ASC` and `SortOrder.DESC`. Default value: `SortOrder.ASC`.
mode (optional)	`SortMode`	The sorting method for a multivalued field.

Examples

Configure index presorting

The following example presorts index data by the created_at field in ascending order.

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("description", FieldType.TEXT),
        new FieldSchema("created_at", FieldType.LONG)
                .setEnableSortAndAgg(true)));
indexSchema.setIndexSort(new Sort(
        Collections.<Sort.Sorter>singletonList(
                new FieldSort("created_at", SortOrder.ASC))));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);

Configure an index TTL

The following example configures a seven-day TTL. Use Tablestore SDK for Java 5.12.0 or later.

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
request.setTimeToLiveInDays(7);
client.createSearchIndex(request);

Create virtual columns

The following example maps the Keyword field category to a Long virtual column and the Long field price to a Keyword virtual column.

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("category_as_long", FieldType.LONG)
                .setVirtualField(true)
                .setSourceFieldName("category"),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("price_as_keyword", FieldType.KEYWORD)
                .setVirtualField(true)
                .setSourceFieldName("price")));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);

Enable summary and highlighting

The following example enables summary and highlighting for the Text field description.

String tableName = "example_table";
String indexName = "example_index";

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("category", FieldType.KEYWORD),
        new FieldSchema("price", FieldType.LONG),
        new FieldSchema("description", FieldType.TEXT)
                .setEnableHighlighting(true)));

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(indexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);