All Products
Search
Document Center

Tablestore:Match query

Last Updated:Sep 28, 2026

A match query performs an approximate match on data in a table. Tablestore uses the configured tokenizer to split the values in Text columns and the search query into tokens, and then searches for these tokens. To perform high-performance fuzzy queries on Text columns that use fuzzy tokenization, use a match phrase query.

Scenarios

A match query finds data that contains a specific phrase. When used with tokenization, a match query enables full-text indexing. This is useful in scenarios such as data analytics, content search, knowledge management, social media analysis, log analysis, AI chat systems, and compliance reviews. For example, you can quickly filter products on an E-commerce platform whose titles, descriptions, or labels contain keywords entered by a user. You can also quickly locate error messages or abnormal operations in logs.

Function overview

A match query performs an approximate match on data in a table. For example, consider a row with a `title` column of the Text type that has the value "Hángzhōu Xīhú Fēngjǐngqū". If this column uses single-word tokenization and the search query is "hú fēng", the row is matched.

When you use a match query, you must specify the column to match and the search query. A row meets the query condition if any of the tokens from the search query exist in the specified column.

You can also configure parameters such as the minimum number of matches, query weight, columns to return, whether to return the total number of matched rows, and the sorting method for the result set.

API operations

The API operations for a match query are Search or ParallelScan. The specific query type is MatchQuery.

Parameters

Parameter

Description

fieldName

The column to match.

A match query can be applied to Text type columns.

text

The search query, which is the value to match.

For Text columns, the search query is split into multiple tokens based on the tokenizer type set when you created the search index. If no tokenizer was set, single-word tokenization is used by default.

For example, for a Text column that uses single-word tokenization, the search query "this is" can match "..., this is tablestore", "is this tablestore", "tablestore is cool", "this", and "is".

query

Set the query type to matchQuery.

offset

The starting position for the query.

limit

The maximum number of results to return for the query.

To get only the row count without any data, set limit to 0. This does not return any rows.

minimumShouldMatch

The minimum number of matches.

A row is returned only if the value in the `fieldName` column contains at least the minimum number of matching tokens.

Note

`minimumShouldMatch` must be used with the OR logical operator.

operator

The logical operator. The default is OR, which means a row meets the query condition if some of the tokens match.

If you set `operator` to AND, a row meets the query condition only if all tokens are present in the column value.

getTotalCount

Specifies whether to return the total number of matched rows. The default is false, which means the total count is not returned.

Returning the total number of matched rows can affect query performance.

weight

The query weight. This is used for score-based sorting in full-text index scenarios. This parameter specifies the weight for score calculation on a column. A larger value results in a higher score. The value must be a positive floating-point number.

This parameter does not affect the number of results returned, only their scores.

tableName

The name of the data table.

indexName

The name of the search index.

columnsToGet

Specifies whether to return all columns. This includes the `returnAll` and `columns` settings.

`returnAll` is false by default, which means not all columns are returned. In this case, you can use `columns` to specify which columns to return. If you do not specify columns, only the primary key columns are returned.

If you set `returnAll` to true, all columns are returned.

Notes

Search Index provides only basic BM25 relevance scoring and does not support custom relevance models.

Usage

You can perform a match query using the console, the command line interface, or a software development kit (SDK). Before you begin, complete the following preparations.

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, query the data.

    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 of the Text type and click Add.

    4. Set the query type for the index field to Match Query (MatchQuery) and enter the value to query.

    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 interface

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

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

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

    {
        "Offset": -1,
        "Limit": 10,
        "Collapse": null,
        "Sort": null,
        "GetTotalCount": true,
        "Token": null,
        "Query": {
            "Name": "MatchQuery",
            "Query": {
                "FieldName": "col_text",
                "Text": "this is",
                "MinimumShouldMatch": 1
            }
        }
    }

Use an SDK

You can perform a match query using the Java SDK, Go SDK, Python SDK, Node.js SDK, .NET SDK, or PHP SDK. This section uses the Java SDK as an example.

The following example queries rows whose description field contains the tablestore or durable token and returns up to 10 rows, the total number of matching rows, and relevance scores.

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

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("description");
matchQuery.setText("tablestore durable");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getRow());
    System.out.println(hit.getScore());
}

Billing

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

FAQ

References