Create, query, and manage search indexes with the Tablestore CLI-Tablestore(Tablestore)-阿里云帮助中心

Prerequisites

The Tablestore CLI with access credentials configured. For more information, see Tablestore CLI.
A data table. For more information, see Manage data tables.

Create a search index

create_search_index -n <indexName>

Parameter	Required	Description
-i, --input	No	The path to a JSON file that defines the search index schema. If not specified, the CLI uses interactive input.
-n, --name	Yes	The name of the search index.
-t, --table	No	The name of the data table. Not required if a data table is already selected with the `use` command.
--ttl	No	The time-to-live (TTL) of data, which specifies how long data is retained. Unit: seconds. Default value: -1 (data never expires). Minimum value: 86400 (one day). Data that exceeds the TTL is automatically deleted. Important To use the search index Lifecycle management feature, disable the UpdateRow operation for the data table. The search index TTL and the data table TTL are independent. The search index TTL must be less than or equal to the data table TTL.

When prompted, enter the index schema in JSON format, or use the -i parameter to specify a schema file. The schema contains the following settings:

Parameter	Required	Description
IndexSetting	No	Index settings, including RoutingFields. RoutingFields (optional): Custom routing fields. Select primary key columns as routing fields. Data with the same routing field values is distributed to the same partition during reads and writes, which improves query performance. Typically, set only one routing field. If you set multiple routing fields, Tablestore concatenates the values into one.
FieldSchemas	Yes	A list of FieldSchema objects. Each FieldSchema contains the following fields: FieldName (required): The field name for the search index (the column name). Type: String. A field in a search index can be a primary key column or an attribute column. FieldType (required): The field Data types. IsArray (optional): Specifies whether the field is an array. Type: Boolean. If set to true, the column is an array, and data must be written in JSON array format, such as `["a","b","c"]`. Because Nested is an array type, you do not need to set this parameter when FieldType is Nested. Index (optional): Specifies whether to enable indexing. Type: Boolean. Default value: true, which builds an inverted index or spatial index for the column. If set to false, no index is built for the column. Analyzer (optional): The type of Tokenization. Set this parameter when the field type is Text. If not set, the default is single-character tokenization. AnalyzerParameter: Parameters for the SingleWord analyzer, including CaseSensitive (whether matching is case-sensitive; default: false) and DelimitWord (whether to split alphabetic words and digits; default: false). EnableSortAndAgg (optional): Specifies whether to enable sorting and aggregation. Type: Boolean. Only fields with EnableSortAndAgg set to true can be used for sorting. Important Nested fields do not support sorting and aggregation. However, sub-columns within a Nested field support sorting and aggregation. Store (optional): Specifies whether to store the field value in the search index. Type: Boolean. When enabled, the field value can be read directly from the search index without querying the data table, which optimizes query performance. IsVirtualField (optional): Specifies whether the column is a Virtual columns. Type: Boolean. Default value: false. If set to true, SourceFieldNames is required. SourceFieldNames (optional): The field name in the data table. Type: String. Required when IsVirtualField is set to true.
IndexSort	No	Index pre-sorting settings. Default: sorted by primary key. Important Indexes that contain Nested fields do not support IndexSort and cannot be pre-sorted. Sorters (optional): The pre-sorting method. Supports sorting by primary key (PrimaryKeySort) and by field value (FieldSort). For more information, see Sorting and paging. Name: The sorting method. PrimaryKeySort sorts by primary key. FieldSort sorts by field value. Only indexed fields with sorting and aggregation enabled can be pre-sorted. Sorter: Contains FieldName (the field name for sorting, required for field value sorting) and Order (the sort order: ASC for ascending or DESC for descending; default: ASC).

Examples

Create a search index named search_index.

create_search_index -n search_index

Enter the index schema as prompted. Example:

{
    "IndexSetting": {
        "RoutingFields": null
    },
    "FieldSchemas": [
        {
            "FieldName": "gid",
            "FieldType": "LONG",
            "Index": true,
            "EnableSortAndAgg": true,
            "Store": true,
            "IsArray": false,
            "IsVirtualField": false
        },
        {
            "FieldName": "col3",
            "FieldType": "TEXT",
            "Index": true,
            "Analyzer": "single_word",
            "AnalyzerParameter": {
                "CaseSensitive": true,
                "DelimitWord": null
            },
            "EnableSortAndAgg": false,
            "Store": true,
            "IsArray": false,
            "IsVirtualField": false
        }
    ],
    "IndexSort": {
        "Sorters": [
            {
                "Name": "PrimaryKeySort",
                "Sorter": {
                    "Order": "ASC"
                }
            }
        ]
    }
}

Create a search index from a file:

create_search_index -n search_index -i /tmp/indexschema.json

List search indexes

list_search_index

Parameter	Required	Description
-a, --all	No	List search indexes for all data tables.
-d, --detail	No	Display detailed information about search indexes.
-t, --table	No	The name of the data table. Not required if a data table is already selected with the `use` command.

Examples

List search indexes for the current data table with details.

list_search_index -d

View search index details

describe_search_index -n <indexName>

Parameter	Required	Description
-n, --name	Yes	The name of the search index.
-o, --output	No	Save the output to a local JSON or TXT file.
-t, --table	No	The name of the data table. Not required if a data table is already selected with the `use` command.

Examples

View the details of the search_index index.

describe_search_index -n search_index

The Index schema field in the output contains the search index schema. TimeToLive shows the TTL of the search index.

Query data with a search index

The Tablestore CLI supports the following search index query types: Term query, Terms query, Match all query, Match query, Match phrase query, Prefix query, Range query, Wildcard query, Token-based wildcard query, Boolean query, Geo query, and Exists query. Select a query type that fits your use case.

search -n <indexName> --return_all_indexed

Parameter	Required	Description
-c, --column	No	The columns to return. Separate multiple column names with commas (,).
-n, --name	Yes	The name of the search index.
-f, --print_format	No	The output format. Default value: table.
--return_all	No	Return all columns.
--return_all_indexed	No	Return all indexed columns in the search index.
-t, --table	No	The name of the data table. Not required if a data table is already selected with the `use` command.

When prompted, enter the query conditions in JSON format. The query conditions contain the following settings:

Parameter	Required	Description
Offset	No	The position from which to start returning results.
Limit	No	The maximum number of rows to return. To get only the row count without returning data, set Limit to 0.
Collapse	No	The collapse configuration. Use this parameter to Collapse (remove duplicates) the result set by a specific column. FieldName specifies the column name. Only integer, floating-point, and Keyword columns are supported.
Sort	No	The sort order for results. For more information, see Define at query time. If not set, results are returned in the pre-sort order. If no pre-sort order is defined, results are returned in primary key order.
GetTotalCount	No	Specifies whether to return the total number of matched rows. Default value: false. Enabling this option may increase query latency.
Token	No	A pagination token for reading the remaining results. When a response does not contain all matched rows, the server returns a Token. Pass this Token in the next request to continue reading. Set Token to null for the first request.
Query	Yes	The query type. Supported types: MatchAllQuery, MatchQuery, MatchPhraseQuery, TermQuery, TermsQuery, PrefixQuery, RangeQuery, WildcardQuery, ExistsQuery, NestedQuery, KnnVectorQuery, and BoolQuery.
Aggregations	No	The Aggregation configuration. Supports minimum value, maximum value, sum, average, count, and distinct count operations. Name: The aggregation type, such as min, max, sum, avg, or count. Aggregation: The aggregation parameter configuration, including AggName (a custom aggregation name), Field (the field to aggregate), and MissingValue (the default value when the field is empty).

Examples

Query data in the current table with search_index and return all indexed columns.

search -n search_index --return_all_indexed

Enter the query conditions as prompted. The following example queries rows where uid equals 10001 and calculates the average of the pid column:

{
    "Offset": -1,
    "Limit": 10,
    "Collapse": null,
    "Sort": null,
    "GetTotalCount": true,
    "Token": null,
    "Query": {
        "Name": "TermQuery",
        "Query": {
            "FieldName": "uid",
            "Term": 10001
        }
    },
    "Aggregations": [{
        "Name": "avg",
        "Aggregation": {
            "AggName": "agg1",
            "Field": "pid"
        }
    }]
}

Delete a search index

drop_search_index -n <indexName> -y

Parameter	Required	Description
-n, --name	Yes	The name of the search index.
-t, --table	No	The name of the data table. Not required if a data table is already selected with the `use` command.
-y, --yes	Yes	Confirm the deletion. This parameter is required in the command.

Examples

Delete the search_index index.

drop_search_index -n search_index -y