Tair (Redis® OSS-Compatible):Search

Item

Description

Syntax

TFT.CREATEINDEX index mappings settings

Command description

Creates an index and a mapping for the index. The syntax used to create a mapping is similar to that used to create an explicit mapping in Elasticsearch. You must create an index before you can add documents to the index.

Parameters

• index: The name of the index that you want to create.

• mappings: The mapping content. The supported syntax is as follows:

  • dynamic: The mapping mode. The strict mapping mode is supported, in which data can be written only to fields that are defined in properties. Attempts to write data to undefined fields fail. If this parameter is not specified, the non-strict mapping mode is used by default, in which the system does not check whether the fields to be written are defined in properties.

  • enabled: Specifies whether to forcefully check if the field type of a document to be written is the same as the type specified in properties. If the types are different, the write operation fails. Valid values: true (default) and false. This parameter applies only to non-indexed fields (index set to false). The field types of indexed fields are always forcefully checked.

  • _source: Specifies whether to store the original document. This parameter does not affect the creation of field indexes. Valid values:

    enabled: Specifies whether to store the original document. Valid values:

    • true (default): Stores the original document. By default, all fields are stored.

      You can specify excludes for fields that you do not want to store and includes for fields that you want to store. Wildcards are accepted. If a field is specified in both excludes and includes, excludes takes precedence over includes, which means that the field is not stored in the original document. The following is an example.

      Example 1: "_source":{"enabled":true} (default) specifies to store all fields and works like "_source":{"enabled":true,"excludes":[],"includes":[]}.

      Example 2: "_source":{"enabled":true,"excludes":[],"includes":["id","name"]} specifies to store only the id and name fields.

    • false: does not store the original document.

  • properties: a collection of mapped fields. You can set the following attributes for each field.

    • index: specifies whether to set the field as an index field. The valid values are as follows:

      • true (default): Indexed field. You can query documents only by using indexed fields.

        Tair stores the original documents of all index fields in memory. If a field is configured in _source not to be stored, it is not included in the original document returned by a query.

      • false: The field is a non-indexed field.

    • boost: the weight of the field. Default value: 1. The parameter value must be a positive floating-point number. Tair automatically calculates the estimated relative score of each field.

    • type: The data type of the field. The ARRAY data type is supported. This property has the following valid values.

      Note

      For example, the array type for keyword is keyword[], and other data types are defined similarly. Example: TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"f0":{"type":"keyword[]"}}}}'.

      • keyword: a string that cannot be split. Valid values:

        • ignore_above: The maximum string length for a keyword. The default value is 128. For example, "ignore_above":128.

        • similarity: The similarity algorithm. Valid values: classic (default, indicates the TF-IDF algorithm) and BM25 (Okapi BM25 algorithm). Example: TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"fs0":{"type":"keyword","similarity":"BM25"}}}}'. You can also customize the parameters for the BM25 algorithm in settings.

      • text: a string that can be parsed by an analyzer and then stored in an index. Valid values:

        • analyzer: Parses the text and stores the results in an index.

          • You can select a TairSearch built-in analyzer, including standard (default), jieba (a recommended Chinese analyzer that works better than chinese), stop, IK, pattern, whitespace, simple, keyword, chinese, french, dutch, and russian. For example, "analyzer":"jieba" indicates that the Jieba Chinese analyzer is used. For more information, see Built-in analyzers.

          • You can also define a custom analyzer, for example, "analyzer":"my_custom_analyzer", and then configure the analyzer by using the analysis parameter in settings.

        • search_analyzer: The analyzer that is used for search. The supported analyzer types are the same as those for the analyzer parameter. The default value is the setting of the analyzer parameter.

        • similarity: the similarity algorithm. Valid values: classic and BM25. Default value: classic. classic indicates the TF-IDF algorithm. BM25 indicates the Okapi BM25 algorithm. You can also specify custom parameters of the Okapi BM25 algorithm by using the settings parameter.

      • long: The LONG data type. You can convert a point in time to a Unix timestamp and store it in this data type.

      • integer: The INTEGER data type.

      • double: The DOUBLE data type. Special data types such as NaN, Inf, and -Inf are not supported.

• settings (Optional): The settings for the index. The following options are supported:

  • analysis: A custom analyzer. For more information, see Custom analyzers.

  • index: A custom similarity algorithm. You can modify the parameters of the Okapi BM25 algorithm. Example: TFT.CREATEINDEX idx:pro15 '{"mappings":{"properties":{"fs0":{"type":"keyword","similarity":"my_similarity"}}},"settings":{"index":{"similarity":{"my_similarity":{"type":"BM25","k1": 1.0,"b": 1.0}}}}}'. Parameter description:

    • k1: the relevance of the frequency of a given term in a document to the weighting of the term. The greater the value is, the more relevant the frequency is to the weighting. Default value: 1.2. You must specify a value that is greater than 0.

    • b: the relevance of the document size to the weighting of a given term. The greater the value is, the more relevant the document size is to the weighting. Default value: 0.75. Valid values: 0 to 1.

  • queries_cache: When you query documents, TairSearch supports storing query results in a query cache. By default, the cache stores a maximum of 10,000 query results without a memory limit. When the limit is reached, results are evicted based on the Least Recently Used (LRU) algorithm. You can use the queries_cache parameter to configure the maximum memory and Time to Live (TTL) for the query cache. After configuration, the maximum memory of the query cache is determined by the size parameter. The parameter has the following fields:

    • size: Data type: STRING. The maximum memory size for all query caches. If this memory limit is reached, query results are also evicted based on the LRU algorithm.

      The default unit for this parameter is bytes. For example, "size": "1000" specifies a maximum of 1000 bytes for the query cache. The units "kb" and "mb" are also supported, such as "size": "10kb" and "size": "1mb".

    • ttl: The validity period of a cached query result. The data type is INTEGER, and the default value is 10 seconds.

    Example: "settings":{"queries_cache":{"size":"100mb","ttl":3}}.

    The queries_cache parameter is a node-level parameter. After you configure this parameter for an index, other indexes in the same process are also affected. Therefore, we recommend that all indexes use the same queries_cache configuration.

  • compress_doc: Specifies whether to enable transparent document compression. If you enable this feature, it can increase CPU resource consumption and read/write latencies. Therefore, we recommend that you enable document compression only if the index is large (such as in kilobytes) and storage cost is your top concern. Valid values:

    • size: A string that specifies the compression threshold. An index is compressed only when its size reaches this threshold. The default value is "10kb".

      The default unit of this parameter is bytes. You can also use "kb" and "mb" as the units. For example, "size": "1000", "size": "10kb", and "size": "1mb".

    • enable: A Boolean parameter that specifies whether to enable the document compression feature. The valid values are false (default) and true.

    Example: "settings":{"compress_doc":{"size":"1kb","enable":true}}.

    The document compression setting takes effect only on the documents that are written or updated after you use the TFT.UPDATEINDEX command to enable or disable document compression. For example, if you run the TFT.UPDATEINDEX command to enable document compression, Tair compresses only the documents that are written or updated after document compression is enabled. It does not compress the documents that are written before document compression is enabled.

The response parameters.

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.CREATEINDEX idx:product '{"mappings":{"_source":{"enabled":true},"properties":{"product_id":{"type":"keyword","ignore_above":128},"product_name":{"type":"text"},"product_title":{"type":"text","analyzer":"jieba"},
"price":{"type":"double"}}}}'

# Specify a product ID (product_id) of the keyword type and set the length limit of the ID to 128 characters.
# Create a product name (product_name) of the text type.
# Create a product title (product_title) of the text type and set analyzer to jieba.
# Specify a price (price) of the double type.

Sample output:

OK

Category

Description

Syntax

TFT.UPDATEINDEX index mappings settings

Command description

Adds properties fields to the specified index or modifies the index settings.

Parameters

• index: the name of the index that you want to manage by running this command.

• mappings: the mapping content. You need to only specify the newly added properties field (no need to input dynamic, _source, and other information). The newly added properties field must not conflict with existing fields. Otherwise, the addition will fail.

• settings: modifies the index settings. Only the queries_cache, compress_doc, and index parameters can be modified. For the index parameter, only the k1 and b values in the BM25 algorithm can be modified.

The response parameters

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.UPDATEINDEX idx:product '{"mappings":{"properties":{"product_group":{"type":"text","analyzer":"chinese"}}}}'

Sample output:

OK

Category

Description

Syntax

TFT.GETINDEX index

Command description

Obtains the mapping content of an index.

Parameters

• index: the name of the index that you want to manage by running this command.

The response parameters.

• If the operation is successful, the JSON-formatted mapping content of the index is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.GETINDEX idx:product

Sample output:

{"idx:product0310":{"mappings":{"_source":{"enabled":true,"excludes":[],"includes":["product_id"]},"dynamic":"false","properties":{"price":{"boost":1.0,"enabled":true,"ignore_above":-1,"index":true,"similarity":"classic","type":"double"},"product_id":{"boost":1.0,"enabled":true,"ignore_above":128,"index":true,"similarity":"classic","type":"keyword"},"product_name":{"boost":1.0,"enabled":true,"ignore_above":-1,"index":true,"similarity":"classic","type":"text"},"product_title":{"analyzer":"chinese","boost":1.0,"enabled":true,"ignore_above":-1,"index":true,"similarity":"classic","type":"text"}}}}}

Item

Description

Syntax

TFT.ADDDOC index document [WITH_ID doc_id]

Command description

Adds a document to an index. You can specify a unique ID for the document in the index by using WITH_ID. If the document ID already exists, the existing ID is overwritten. If you do not specify WITH_ID (default), a document ID is automatically generated.

Parameters

• index: the name of the index that you want to manage by running this command.

• document: the document to be inserted in the JSON format. The value must be of the data type defined for this field.

  Note

  If you specify _source with the includes parameter to retain only specific fields, only the fields specified by includes are retained when you add a document to the index or update a document added to the index.

• WITH_ID doc_id: specifies whether to configure the ID of the document. If yes, you must also enter a string as the doc_id value.

The response parameters

• If the operation is successful, the JSON-formatted document ID is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.ADDDOC idx:product '{"product_id":"product test"}' WITH_ID 00001

Sample output:

{"id":"00001"}

Sample arrays to be added:

TFT.ADDDOC idx:product '{"product_id":["an","2","3df"]}' WITH_ID 00001

Category

Description

Syntax

TFT.MADDDOC index document doc_id [document1 doc_id1] ...

Command description

Adds multiple documents to an index. Each document must have a document ID that is specified by doc_id. If a document fails to be added due to an invalid format, all documents that the command involves are not added to the index.

Parameters

• index: the name of the index that you want to manage by running this command.

• document: the document to be inserted in the JSON format. The value must be of the data type defined for this field.

  Note

  If you specify _source with the includes parameter to retain only specific fields, only the fields specified by includes are retained when you add a document to the index or update a document added to the index.

• doc_id: the ID of the document. The value must be a string.

The response parameters.

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.MADDDOC idx:product '{"product_id":"test1"}' 00011 '{"product_id":"test2"}' 00012

Sample output:

OK

Category

Description

Syntax

TFT.UPDATEDOCFIELD index doc_id document

Command description

Options

• index: the name of the index that you want to manage by running this command.

• doc_id: the ID of the document.

• document: the JSON-formatted document content that you want to update.

  Note

  If you specify _source in the includes parameter to retain only specific fields, only the fields specified by includes are retained when you add a document to the index or update a document added to the index.

The response parameters.

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.UPDATEDOCFIELD idx:product 00011 '{"product_id":"test8","product_group":"BOOK"}'

Sample output:

OK

Category

Description

Syntax

TFT.DELDOCFIELD index doc_id field [field1 field2 ...]

Command description

Options

• index: the name of the index that you want to manage by running this command.

• doc_id: the ID of the document.

• field: the field that you want to delete.

The response parameters.

• If the operation is successful, the number of deleted fields is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.DELDOCFIELD idx:product 00011 product_group

Sample output:

(integer) 1

Category

Description

Syntax

TFT.INCRLONGDOCFIELD index doc_id field increment

Command description

Options

• index: the name of the index that you want to manage by running this command.

• doc_id: the ID of the document.

• field: the field to which you want to add an increment. The data type of the field can only be LONG or INTEGER. The ARRAY data type is not supported.

• increment: the increment value that you want to add to the field. The value can be a positive or negative integer.

The response parameters.

• If the operation is successful, the updated field value is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.INCRLONGDOCFIELD idx:product 00011 stock 100

Sample output:

(integer)100

Category

Description

Syntax

TFT.INCRFLOATDOCFIELD index doc_id field increment

Command description

Options

• index: the name of the index that you want to manage by running this command.

• doc_id: the ID of the document.

• field: the field to which you want to add an increment. The data type of the field can only be DOUBLE. The ARRAY data type is not supported.

• increment: the increment value that you want to add to the field. The value can be a positive or negative floating-point number.

The response parameters.

• If the operation is successful, the updated field value is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.INCRFLOATDOCFIELD idx:product 00011 stock 299.6

Sample output:

"299.6"

Category

Description

Syntax

TFT.GETDOC index doc_id

Command description

Obtains the content of the document specified by doc_id in an index.

Options

• index: the name of the index that you want to query.

• doc_id: the ID of the document.

The response parameters.

• If the operation is successful, the ID and content of the document are returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.GETDOC idx:product 00011

Sample output:

{"_id":"00011","_source":{"product_id":"test8"}}

Category

Description

Syntax

TFT.EXISTS index doc_id

Command description

Checks whether the document specified by doc_id exists in an index.

Parameters

• index: the name of the index that you want to query.

• doc_id: the ID of the document.

The response parameters.

• If the operation is successful:

  • If the document exists, a value of 1 is returned.

  • If the index or document does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.EXISTS idx:product 00011

Sample output:

(integer) 1

Category

Description

Syntax

TFT.DOCNUM index

Command description

Obtains the number of documents in an index.

Parameters

• index: the name of the index that you want to query.

Return value

• If the operation is successful, the number of documents in the index is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.DOCNUM idx:product

Sample output:

(integer) 3

Category

Description

Syntax

TFT.SCANDOCID index cursor [MATCH *value*] [COUNT count]

Command description

Obtains the IDs of all documents in an index.

Parameters

• index: the name of the index that you want to query.

• cursor: the cursor used for this scan.

• MATCH *value*: the pattern matching, where value is the value to be matched, for example MATCH *redis*.

• COUNT count: the maximum number of items to scan in this operation, default is 100.

The response parameters.

• If the operation is successful, an array is returned.

  • The first element: the cursor for the next query. If the key has been completely scanned, 0 is returned.

  • The second element: the doc_id of this query.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.SCANDOCID idx:product 0 COUNT 3

Sample output:

1) "0"
2) 1) "00001"
   2) "00011"
   3) "00012"

Item

Description

Syntax

TFT.DELDOC index doc_id [doc_id] ...

Command description

Deletes the documents specified by doc_id from an index. Multiple document IDs can be specified.

Parameters

• index: the name of the index that you want to query.

• doc_id: the ID of the document.

The response parameters.

• If the operation is successful, the number of deleted documents is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.DELDOC idx:product 00011 00014

Sample output:

"1"    # In this example, the document with ID "00014" does not exist, so only the document with ID "00011" is deleted, returning 1.

Category

Description

Syntax

TFT.DELALL index

Command description

Deletes all documents from an index but retains the index.

Parameters

• index: the name of the index that you want to query.

• doc_id: the ID of the document.

The response parameters.

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.DELALL idx:product

Sample output:

OK

Category

Description

Syntax

TFT.ANALYZER analyzer_name text [INDEX index_name] [SHOW_TIME]

Command description

Queries the tokenization effects of the specified analyzer.

Options

• analyzer_name: the analyzer name. You can specify a built-in or custom analyzer.

  If you specify a custom analyzer or a built-in analyzer that has the stop words or dictionaries modified, you must also specify the name of the index for which the analyzer is created (INDEX).

• text: the document that you want to split by using the analyzer. The document must be encoded in the UTF-8 format.

• INDEX (optional): the name of the index for which the analyzer is created. If you specify a custom analyzer or a built-in analyzer that has the stop words or dictionaries modified, this parameter is required.

• SHOW_TIME (optional): specifies whether to return the amount of time that is taken to split the document into tokens. Unit: microseconds (us).

  The amount of time includes the time that is taken to load the dictionary. The first time when a relatively large dictionary is loaded, such as JiebaAnalyzer or IKAnalyzer, the amount of time may increase to several seconds.

The response parameters.

• If the operation is successful, the token information is returned in the JSON format.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.ANALYZER standard "Tair is a nosql database"

Sample output:

'{
    "tokens":[
        {
            "token":"Tair",
            "start_offset":0,
            "end_offset":4,
            "position":0
        },
        {
            "token":"nosql",
            "start_offset":10,
            "end_offset":15,
            "position":3
        },
        {
            "token":"database",
            "start_offset":16,
            "end_offset":24,
            "position":4
        }
    ]
}'

Category

Description

Syntax

TFT.SEARCH index query

Command description

Searches for documents in an index based on the query statement. The query syntax is similar to Elasticsearch syntax.

Options

index is the name of the index that you want to manage by running this command; query is the Query DSL statement that is similar to the syntax used in Elasticsearch. The following fields are supported:

• query: the query clause. The following syntax is supported:

  • match: the basic match query. The following parameters are supported.

    In scenarios that do not require document characters to be broken into individual tokens or do not require fuzzy match, we recommend that you use commands such as term and prefix to improve query efficiency.

    • query: the documents in the index that are obtained by using the query.

      Note

      • If fuzzy match is disabled by using fuzziness, documents obtained by the query are broken into individual tokens by a tokenizer specified by analyzer. You can also specify the relationship between tokens by using operator and the minimum number of tokens that need to be matched by using minimum_should_match.

      • If fuzzy match is enabled by using fuzziness, the preceding parameters are invalid. In this case, you can specify prefix_length.

    • analyzer: the tokenizer used by the match statement. Valid values: standard (default, English tokenizer), chinese, arabic, cjk, czech, brazilian, german, greek, persian, french, dutch, russian, and jieba (Chinese tokenizer). For more information, see Search analyzers.

    • minimum_should_match: the minimum number of tokens that need to be matched. The tokenizer breaks the query statement into tokens. This parameter takes effect when fuzzy match is disabled and operator is set to OR.

    • operator: the relationship between tokens. Valid values: AND and OR. Default value: OR. For example, '{"query":{"match":{"f0":{"query":"redis cluster","operator":"OR"}}}}' specifies that the search condition is met when "redis" or "cluster" is contained in the documents for which you want to perform a query.

    • fuzziness: specifies whether to enable fuzzy match for the query. By default, fuzzy match is disabled. "fuzziness":1 specifies that fuzzy match is enabled. Example: '{"query":{"match":{"f0":{"query":"excelentl","fuzziness":1}}}}'.

    • prefix_length: the number of start characters that must be retained for a fuzzy match. Default value: 0. This parameter takes effect only when fuzzy match is enabled.

  • term: the token query. If this parameter is specified, the query statement is not split. This query type is more efficient than the match query. This parameter supports all field types. When you perform a token query, you can set the lowercase parameter to convert the token that you want to query to lowercase. The valid values of the lowercase parameter are true and false. The default value is true. Examples: '{"query":{"term":{"f0":{"value":"redis","boost": 2.0}}}}' or '{"query":{"term":{"f0":{"value":"redis","lowercase": false}}}}'.

    If the analyzer that is used when you add a document does not convert the document to lowercase, we recommend that you set the lowercase parameter to false. Otherwise, the document may not be found.

  • terms: the multi-token query. A maximum of 1024 tokens are allowed in each multi-token query. When you perform a token query, you can set the lowercase parameter to convert the token that you want to query to lowercase. The valid values of the lowercase parameter are true and false. The default value is true. Example: '{"query":{"terms":{"f0":["redis","excellent"]}}}'.

    If the analyzer that is used when you add a document does not convert the document to lowercase, we recommend that you set the lowercase parameter to false. Otherwise, the document may not be found.

  • range: the range query. This parameter supports all field types. Valid values: lt (less than), gt (greater than), lte (less than or equal to), and gte (greater than or equal to). Example: '{"query":{"range":{"f0":{"lt":"abcd","gt":"ab"}}}}'.

  • wildcard: the wildcard query. Parameter value format: "wildcard":{"field to query":{"value":"query content"}}. Supported wildcards: * and ?. Example: '{"query":{"wildcard":{"f0":{"value":"*b?Se"}}}}'.

  • prefix: the prefix query. For example, '{"query":{"prefix":{"f0":"abcd"}}' specifies to query documents whose f0 fields start with abcd.

  • bool: the compound query. A maximum of 1,024 tokens are allowed in each compound query. Valid values:

    • must: The query results must match all query clauses in the must list. For example, '{"query":{"bool":{"must":[{"match":{"DB":"redis"}},{"match":{"Architectures":"cluster"}}]}}}' specifies that the type of the database that you want to query is Redis and the architecture of the instance that contains the database is cluster.

    • must_not: The query results do not match any query clauses in the must_not list.

    • should: the should list. If bool is set to should, the query results must match one query clause in this list. You can set the minimum_should_match parameter.

    • minimum_should_match: specifies the minimum number of query clauses that must be matched. This parameter must be used together with should. If a bool statement contains only should, minimum_should_match is set to 1 by default. If the bool statement also contains must or must_not, minimum_should_match is set to 0 by default. For example, '{"query":{"bool":{"minimum_should_match":1,"should":[{"match":{"DB":"redis"}},{"match":{"Architectures":"cluster"}}]}}}' specifies that the type of the database that you want to query is Redis or the architecture of the instance that contains the database is cluster.

    Note

    A bool statement can have all types of query clauses nested within it, such as bool clauses. Example: TFT.SEARCH idx:product '{"query":{"bool":{"must":[{"term":{"product_name":"apple"}},{"bool":{"minimum_should_match":1,"should":[{"term":{"price":19.5}},{"term":{"product_id":"fruits_2"}}]}}]}}}'.

  • dis_max: the compound query for best match. By default, this parameter returns documents that match one or more query clauses. If a returned document matches multiple query clauses, the dis_max query assigns the document the highest score from the matching clauses and a tie-breaking increment to the document score if tie_breaker is specified.

    If you specify the tie_breaker parameter, the score of documents that match multiple query clauses is increased. The value of tie_breaker can range from 0 to 1, and the default value is 0. After you specify tie_breaker, the final score of a document is calculated by using the following formula: the score from the best matching clause + (the sum of the scores from all other matching clauses × the tie_breaker value). For example, if a query contains three clauses, the tie_breaker value is 0.5, and the scores of a document named doc1 for each clause are 5, 1, and 3, the final score for doc1 is 5 + ((1 + 3) × 0.5).

    Example: '{"query":{"dis_max":{"queries":[{"term":{"f0":"redis"}},{"term":{"f1":"database"}},{"match":{"title":"redis memory database"}}],"tie_breaker": 0.5}}}'.

  • constant_score: the compound query that returns a constant score. This query wraps another query and returns a constant score equal to the query boost for every document in the filter. The boost value is of the DOUBLE type, and the default boost value is 1.0. Example: '{"query":{"constant_score":{"filter":{"term":{"f0":"abc"}},"boost":1.2}}}'.

  • match_all: the match all query. This query matches all documents and gives them all a boost value. The boost value is of the DOUBLE type, and the default boost value is 1.0. Example: '{"query":{"match_all":{"boost":2.3}}}'.

  Note

  If you perform a compound query by using bool, dis_max, and constant_score, you can set boost values for term, terms, range, and wildcard. The default boost value is 1. You must specify the parameter to which the boost value is applied in query syntax. Example: '{"query":{"bool":{"must":[{"match":{"f0":"v0"}},"term":{"f0":{"value":"redis","boost":2}}]}}}'.

• sort: sorts query results by a factor. The ARRAY data type is not supported. Default value: _score. Valid values:

  • _score: sorts query results by weight in descending order. Example: "sort":"_score".

  • _doc: sorts query results by document ID in ascending order. Example: "sort":"_doc".

  • Specified field: sorts query results by specified field in ascending order. The field must be an indexed field (index set to true) or a field that is forcefully checked (enabled set to true). The field must be of the keyword, long, integer, or double type. For example, "sort":"price" specifies to sort query results by price in ascending order.

  You can also use an array to sort query results. In this case, query results are sorted by array order. You can use order to modify the default array order. Valid values of order: desc and acs. For example, '{"sort":[{"price":{"order":"desc"}},{"_doc":{"order":"desc"}}]}' specifies to sort query results by price or by document ID if the prices are the same.

• _source: the fields displayed in query results. You can use includes to specify fields that you want to retain and use excludes to specify fields that you do not want to retain. Wildcards are accepted. For example, "_source":{"includes":["f0"] specifies to return only the f0 fields in query results.

• aggs: aggregates the results of the query clause. If the field is of the ARRAY data type, only terms aggregation is supported. For more information, see Aggregations.

• track_total_hits: specifies whether to query all documents when you use the term, terms, or match query. In this case, compound query is supported. If you use the match query, fuzzy match is disabled. Valid values:

  • false: Only the top 100 documents are queried. Documents are sorted by score.

  • true: All documents are queried.

    Warning

    If track_total_hits is set to true and the number of documents to query is large, slow queries occur. Proceed with caution.

• from: the start document to return. The default value is 0, which specifies to return the first document and all subsequent documents that are queried.

• size: the number of documents that can be returned. Default value: 10. Valid values: 0 to 10000. A value of 0 specifies to return only the total number of obtained documents instead of specific documents.

  Note

  A combination of from and size works like paging. However, query performance degrades as the number of discrete pages increases.

Output

• If the operation is successful, the documents in the index are returned.

  Note

  In the following sample output, relation indicates the number of returned documents. Valid values of relation: eq (equal to the value specified by value) and gte (greater than or equal to the value specified by value).

  {
      "hits": {
          "hits": [],
          "max_score": null,
          "total": {
              "relation": "gte",
              "value": 100
          }
      }
  }

• Otherwise, an error message is returned.

Example

Sample command:

TFT.SEARCH idx:product '{"sort":[{"price":{"order":"desc"}}]}'

Sample output:

{"hits":{"hits":[{"_id":"fruits_3","_index":"idx:product","_score":1.0,"_source":{"product_id":"fruits_3","product_name":"orange","price":30.2,"stock":3000}},{"_id":"fruits_2","_index":"idx:product","_score":1.0,"_source":{"product_id":"fruits_2","product_name":"banana","price":24.0,"stock":2000}},{"_id":"fruits_1","_index":"idx:product","_score":1.0,"_source":{"product_id":"fruits_1","product_name":"apple","price":19.5,"stock":1000}}],"max_score":1.0,"total":{"relation":"eq","value":3}}}

Item

Description

Syntax

TFT.MSEARCH index_count index [index1] ... query

Command description

Queries documents in multiple indexes that have mappings and settings set to the same values by using the query clause and gathers the results from these indexes. Then, the results are rated, sorted, aggregated, and returned.

Parameters

• index_cout: the number of indexes that you want to query. Valid values: 1 to 100.

• index: the name of the index that you want to manage by running this command. These indexes must have mappings and settings set to the same values. If the mappings configurations are different for different indexes or if an index does not exist, an error is reported.

• query: the aggregation statement. The following parameters are supported:

  • query: the query clause.

  • sort: sorts query results by a factor. The ARRAY data type is not supported.

  • _source: the fields to return in the results.

  • aggs: aggregates the results of the query clause. If the field is of the ARRAY data type, only terms aggregation is supported.

  • track_total_hits: specifies whether to query all documents when you use the term, terms, or match query. In this case, compound query is supported. If you use the match query, fuzzy match is disabled.

  • size: the number of documents to return.

    Paged query can be implemented by using size, reply_with_keys_cursor, and keys_cursor. If keys_cursor is set to the default value 0, Tair retrieves a specified number of documents starting from the first document of the obtained results from the indexes. If keys_cursor is not set to 0, a specific number of documents are retrieved starting from a specific position. Then, the results from these indexes are gathered to be rated, sorted, aggregated, and returned as the output.

    For example, assume that you want to query three indexes key0, key1, and key2 at a time and that you set the size parameter to 10:

    • For the first query, set keys_cursor to 0. Tair retrieves the first 10 documents from these three indexes respectively. Then, Tair gathers, rates, sorts, and aggregates these 30 documents and returns the top 10 documents. Sample return value of keys_cursor: {"keys_cursor":{"key0":2,"key1":5,"key2":3}}.

    • For the second query, use the same query statement and add {"keys_cursor":{"key0":2,"key1":5,"key2":3}}. Tair retrieves the first 10 documents from the specified position in these indexes. For example, Tair retrieves 10 documents starting from the third one in the key0 index. Then, Tair gathers, rates, sorts, and aggregates the retrieved documents, and returns the output.

  • reply_with_keys_cursor: specifies whether to return the start position of the next query for each index. Valid values: true and false. Default value: false.

  • keys_cursor: specifies the position of the cursor in each index for the query. To implement paged query, set keys_cursor to the return value for the last query. The default value is 0, which indicates that the query starts from the first document.

The response parameters.

• If the operation is successful, the obtained documents and aux_info are returned, which is similar to the output of the TFT.SEARCH command.

  The aux_info field includes the CRC-64 value of mappings and settings (which can be ignored for business requests), the keys_cursor value (optional, indicating the cursor position for the next query in each index), and the field_type value (the data type of the field, returned only when sorting by index field). Example of aux_info:

  {
      "aux_info":{
          "index_crc64":15096806844241479487,
          "keys_cursor":{
              "key0":2,
              "key1":5,
              "key2":3
          },
          "field_type":{
              "f0":"long"
          }
      }
  }

• Otherwise, an error message is returned.

Example

TFT.CREATEINDEX key0 '{"mappings":{"properties":{"f0":{"type":"long"}}}}'
TFT.CREATEINDEX key1 '{"mappings":{"properties":{"f0":{"type":"long"}}}}'
TFT.CREATEINDEX key2 '{"mappings":{"properties":{"f0":{"type":"long"}}}}'
TFT.ADDDOC key0 '{"f0":120}'
TFT.ADDDOC key0 '{"f0":130}'
TFT.ADDDOC key1 '{"f0":140}'
TFT.ADDDOC key1 '{"f0":150}'
TFT.ADDDOC key2 '{"f0":160}'
TFT.ADDDOC key2 '{"f0":170}'

Sample command:

TFT.MSEARCH 3 key0 key1 key2 '{"size":2,"query":{"range":{"f0":{"gt":120,"lte":170}}},"sort":[{"f0":{"order":"desc"}}],"reply_with_keys_cursor":true}'

Sample response:

{"hits":{"hits":[{"_id":"16625439765504840","_index":"key2","_score":1.0,"_source":{"f0":170}},{"_id":"16625439741096630","_index":"key2","_score":1.0,"_source":{"f0":160}}],"max_score":1.0,"total":{"relation":"eq","value":5}},"aux_info":{"index_crc64":10084399559244916810,"keys_cursor":{"key0":0,"key1":0,"key2":2}}}

Sample command for querying the second page:

TFT.MSEARCH 3 key0 key1 key2 '{"size":2,"query":{"range":{"f0":{"gt":120,"lte":170}}},"sort":[{"f0":{"order":"desc"}}],"reply_with_keys_cursor":true,"keys_cursor":{"key0":0,"key1":0,"key2":2}}'
# The query statement is the same as the first query, but you need to add the keys_cursor information returned from the previous query.

Sample response:

{"hits":{"hits":[{"_id":"16625439652681160","_index":"key1","_score":1.0,"_source":{"f0":150}},{"_id":"16625439624704580","_index":"key1","_score":1.0,"_source":{"f0":140}}],"max_score":1.0,"total":{"relation":"eq","value":5}},"aux_info":{"index_crc64":10084399559244916810,"keys_cursor":{"key0":0,"key1":2,"key2":2}}}

Item

Description

Syntax

TFT.EXPLAINCOST index query

Command description

Queries the execution duration of a query statement. The output includes the number of documents that are involved in the query and the amount of time consumed by each operation in the query.

Options

• index: the name of the index that you want to query.

• query: the query statement that has the same syntax as the TFT.SEARCH command.

The response parameters.

• If the operation is successful, the output is returned in the JSON format. The output can contain the following items:

  • QUERY_COST: the execution duration of the query in microseconds (time_cost_us). It also includes the query view information (query) and the number of documents involved in the query (doc_num). If a bool query method is used, the execution time of each step in the bool query process (steps) will be displayed.

  • AGGS_COST: the time spent on aggregations during the query process, in microseconds (time_cost_us). If no aggregation query is specified in the query statement, this cost will not be included.

  • COLLECTOR_COST: the time spent on collecting and sorting query results, in microseconds (time_cost_us). It also includes the sorting type (collector_type), with return values being score sorting (ScoreCollector) and custom sorting (CustomSortCollector).

• Otherwise, an error message is returned.

Example

Sample command:

TFT.EXPLAINCOST idx:product '{"sort":[{"price":{"order":"desc"}}]}'

Sample output:

{
    "QUERY_COST": {
        "query": "MATCHALL_QUERY",
        "doc_num": 1,
        "time_cost_us": 2
    },
    "COLLECTOR_COST": {
        "collector_type": "CustomSortCollector",
        "time_cost_us": 20
    }
}

Category

Description

Syntax

TFT.EXPLAINSCORE index query [doc_id] ...

Command description

Queries the detailed score information of documents resulting from the execution of a query statement. You can use this command to gain insights into the process of how document scores are calculated. Then, you can optimize search queries to enhance the effectiveness of document retrieval.

This command is available only for DRAM-based instances that are compatible with Redis 6.0.

Parameter

• index: the name of the index that you want to manage by running this command.

• query: the query statement that has the same syntax as the TFT.SEARCH command.

• doc_id: the IDs of the documents. If this parameter is specified, only the documents specified by doc_id are returned.

The response parameters.

• If the operation is successful, the information of the queried documents is returned. The detailed score information for each document (_explanation) is an addition to the basic result set returned by the TFT.SEARCH command. The _explanation object contains the following fields:

  • score: the score of the document.

  • description: the formula used for score calculation.

  • field: the fields of the document that match the terms specified in the query.

  • term: the terms from the query that are found in the document.

  • query_boost: the scoring weight applied to the document in the query.

  • details: the metadata and scoring process for the document.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.EXPLAINSCORE today_shares '{"query":{"wildcard":{"shares_name":{"value":"*BY"}}}}'

Sample output:

{
    "hits": {
        "hits": [
            {
                "_id": "17036492095306830",
                "_index": "today_shares",
                "_score": 1.0,
                "_source": {
                    "shares_name": "YBY",
                    "logictime": 14300410,
                    "purchase_type": 1,
                    "purchase_price": 11.1,
                    "purchase_count": 100,
                    "investor": "Mila"
                },
                "_explanation": {
                    "score": 1.0,
                    "description": "score, computed as query_boost",
                    "field": "shares_name",
                    "term": "*BY",
                    "query_boost": 1.0
                }
            }
        ],
        "max_score": 1.0,
        "total": {
            "relation": "eq",
            "value": 1
        }
    }
}

Category

Description

Syntax

TFT.ADDSUG index text weight [text weight] ...

Command description

Adds one or more auto-complete texts and their weights to the specified index.

Parameters

• index: the name of the index that you want to manage by running this command.

• text: the auto-complete text entry.

• weight: the scoring weight of the corresponding text, which must be a positive integer.

The response parameters

• If the operation is successful, the number of added text entries is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.ADDSUG idx:redis 'redis is a memory database' 3 'redis cluster' 10

Sample output:

(integer) 2

Category

Description

Syntax

TFT.DELSUG index text [text] ...

Command description

Deletes one or more auto-complete text entries from the specified index.

Parameters

• index: the name of the index that you want to manage by running this command.

• text: the text entry that you want to delete from the index. The text entry must be complete and accurate.

Output

• If the operation is successful, the number of deleted text entries is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.DELSUG idx:redis 'redis is a memory database' 'redis cluster' 

Sample output:

(integer) 2

Category

Description

Syntax

TFT.SUGNUM index

Command description

Obtains the number of auto-complete texts in the specified index.

Parameters

• index: the name of the index that you want to query.

The response parameters.

• If the operation is successful, the number of texts in the index is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.SUGNUM idx:redis

Sample output:

(integer) 3

Category

Description

Syntax

TFT.GETSUG index prefix [MAX_COUNT count] [FUZZY]

Command description

Obtains the auto-complete texts that can be matched based on the specified prefix. Texts are returned in descending order of weights.

Parameters

• index: the name of the index that you want to query.

• prefix: the specified query prefix.

• MAX_COUNT count: configures the maximum number of text entries to return, with count values ranging from [0,255].

• FUZZY: whether to enable fuzzy matching.

The response parameters.

• If the operation is successful, a list of auto-complete text entries is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.GETSUG idx:redis res MAX_COUNT 2 FUZZY

Sample output:

1) "redis cluster"
2) "redis lock"

Category

Description

Syntax

TFT.GETALLSUGS index

Command description

Obtains all auto-complete text entries in the specified index.

Parameters

• index: the name of the index that you want to query.

The response parameters.

• If the operation is successful, a list of auto-complete text entries is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TFT.GETALLSUGS idx:redis

Sample output:

1) "redis cluster"
2) "redis lock"
3) "redis is a memory database"