All Products
Search
Document Center

Tablestore:Prefix query

Last Updated:May 07, 2026

A prefix query (PrefixQuery) finds rows in a search index where the value of a field starts with a specified string.

Overview

A PrefixQuery matches column values that start with a specified prefix. The query behavior depends on the data type of the column:

  • Keyword: A basic string data type. As the data volume increases, the query performance degrades. This type is suitable only for small datasets.

  • FuzzyKeyword: A data type optimized for fuzzy searches such as prefix queries. The query performance remains stable regardless of the data volume. This type is recommended for most prefix query scenarios.

  • Text: Column values are tokenized before being indexed. A row matches if at least one resulting token starts with the specified prefix. Due to the uncertainty of tokenization, query results can be unpredictable. This data type is supported for compatibility purposes only and should be used with caution.

How to choose a data type

The following table summarizes the suitability of each data type for prefix queries.

Type

Performance

Recommendation

Keyword

Degrades as data volume increases

For small datasets only

FuzzyKeyword

Stable regardless of data volume

Recommended for most scenarios

Text

Unpredictable results due to tokenization

Not recommended

Prefix matching examples

Assume a column contains the following values: hangzhou, beijing, shanghai, and harbin.

  • A prefix of hang matches hangzhou but does not match beijing, shanghai, or harbin.

  • A prefix of ha matches both hangzhou and harbin.

APIs

You can perform a prefix query using the Search or ParallelScan API. The query type is PrefixQuery.

Parameters

Parameter

Description

query

The query type. Set this to PrefixQuery.

fieldName

The name of the target column.

prefix

The prefix string to match against column values.

For Text columns, column values are tokenized before matching. A row matches if at least one token starts with the specified prefix.

getTotalCount

Specifies whether to return the total number of matching rows. The default value is false.

Setting this parameter to true increases query latency.

weight

The query weight must be a positive floating-point number. In full-text search scenarios, this parameter adjusts the column's contribution to the BM25 relevance score. A higher value increases the column's influence on the ranking.

This parameter does not affect the returned result set, only the BM25 score of each row in the results.

tableName

The name of the data table.

indexName

The name of the search index.

columnsToGet

Specifies the columns to return for each matching row. Configure this using the returnAll and columns parameters.

By default, returnAll is false. If columns is not set, only the primary key columns are returned. If columns is set, only the specified columns are returned.

Set returnAll to true to return all columns.

Usage

You can perform prefix queries using the Tablestore console, the command-line tool, or an SDK. Before you begin, complete the following prerequisites.

Important

PrefixQuery on FuzzyKeyword columns is currently supported only through the Tablestore SDK. The console and command-line tool support Keyword columns only.

Use the console

  1. Go to the Index Management tab.

    1. Log on to the Table Store console.

    2. In the top navigation bar, select a resource group and a region.

    3. On the Overview page, click the instance name or click Instance Management in the Actions column.

    4. On the Instance Details tab, in the Data Table List tab, click the data table name or click Index Management in the Actions column.

  2. On the Index Management tab, find the target Search Index and click Search in the Actions column.

  3. In the Search dialog box, configure the query conditions.

    1. By default, all columns are returned. To return specific columns, turn off Retrieve All Columns and enter the column names, separated by commas.

      Note

      By default, Table Store returns the primary key columns of the data table.

    2. Select a logical operator: And, Or, or Not.

      If you select And, the query returns data that meets all specified conditions. If you select Or, the query returns data that meets at least one of the specified conditions. If you select Not, the query returns data that does not meet the specified conditions.

    3. Select an index field and click Add.

    4. Set the query type to Prefix query (PrefixQuery) and enter the prefix value.

    5. By default, sorting is disabled. To sort the results by a specific field, turn on Enable Sorting, add the sort field, and configure the sort order.

    6. By default, aggregation is disabled. To perform statistical aggregation on a specific field, turn on Enable Aggregation, add the field for aggregation, and configure the aggregation settings.

  4. Click OK.

    The query results are displayed on the Index Management tab.

Use the command-line tool

Run the search command to query data using a search index. For more information, see Search index.

Important

The command-line tool supports prefix queries on Keyword columns only, not on FuzzyKeyword columns.

  1. Run the search command to query data by using the search_index search index and return all indexed columns.

    search -n search_index --return_all_indexed
  2. Enter the query conditions when prompted. The following code is an example:

    {
        "Offset": -1,
        "Limit": 10,
        "Collapse": null,
        "Sort": null,
        "GetTotalCount": true,
        "Token": null,
        "Query": {
            "Name": "PrefixQuery",
            "Query": {
                "FieldName": "col_keyword",
                "Prefix": "hangzhou"
            }
        }
    }

Use an SDK

You can perform a prefix query by using the Java SDK, Go SDK, Python SDK, Node.js SDK, .NET SDK, or PHP SDK. The following example uses the Java SDK.

Note

The query statement is the same for both Keyword and FuzzyKeyword data types. The only difference is the data type of the queried column.

The following example shows how to query for data where the value in the Col_Keyword column starts with the prefix "hangzhou".

/**
 * Query for data where the value in the Col_Keyword column starts with the prefix "hangzhou".
 * @param client
 */
private static void prefixQuery(SyncClient client) {
    SearchQuery searchQuery = new SearchQuery();
    PrefixQuery prefixQuery = new PrefixQuery(); // Set the query type to PrefixQuery.
    searchQuery.setGetTotalCount(true);
    prefixQuery.setFieldName("Col_Keyword");
    prefixQuery.setPrefix("hangzhou");
    searchQuery.setQuery(prefixQuery);
    //searchQuery.setGetTotalCount(true); // Set this parameter to return the total number of matched rows.

    SearchRequest searchRequest = new SearchRequest("<TABLE_NAME>", "<SEARCH_INDEX_NAME>", searchQuery);
    // Set the columnsToGet parameter to specify the columns to return or to return all columns. If this parameter is not set, only primary key columns are returned by default.
    //SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
    //columnsToGet.setReturnAll(true); // Set this parameter to return all columns.
    //columnsToGet.setColumns(Arrays.asList("ColName1","ColName2")); // Set this parameter to return specified columns.
    //searchRequest.setColumnsToGet(columnsToGet);

    SearchResponse resp = client.search(searchRequest);
    //System.out.println("TotalCount: " + resp.getTotalCount()); // Print the total number of matched rows, not the number of returned rows.
    System.out.println("Row: " + resp.getRows());
}

Billing

Querying data by using a Search Index consumes read throughput. For more information, see Search Index metering and billing.

FAQ

Related documents