All Products
Search

This Product

    Tair:Search

    Document Center

    Tair:Search

    Last Updated:Jan 30, 2024

    TairSearch is an in-house full-text search data structure of Tair and uses query syntax that is similar to that of Elasticsearch.

    Overview

    TairSearch has the following features:

    • Low latency and high performance: provides millisecond-level write and full-text search capabilities based on the ultra-high computing power of Tair. For more information, see TairSearch performance whitepaper.

    • Incremental and partial updates: supports partial updates of indexes and incremental updates of documents, including adding, updating, removing, and auto-incrementing fields.

    • Flexible syntax: provides custom sorting order and supports the JSON syntax that allows bool, match, term, and paging queries. This syntax is similar to that of Elasticsearch.

    • Aggregate query: supports terms, metrics, and filter aggregations. For more information, see Aggregations.

    • Auto-complete suggestion: supports fuzzy match with prefixes and automatic completion for search operations.

    • Custom analyzers: provides built-in analyzers for major languages such as English and Chinese and meets personalized requirements for the dictionaries and stop words of analyzers. For more information, see Search analyzers.

    • Shard index query: allows you to use the TFT.MSEARCH command to search for multiple shard indexes and return an aggregated result set.

    • Document compression: supports the storage of compressed documents to reduce memory usage. By default, this feature is disabled.

    • Query caching: stores the latest query results in cache to improve the query efficiency of hot data.

    Release notes

    Redis 5.0-compatible DRAM-based instances

    1. On March 11, 2022, TairSearch was released with Tair V1.7.27.

    2. On May 24, 2022, Tair V1.8.5 was released to add support for the TairSearch aggregation feature.

    3. On September 6, 2022, Tair V5.0.15 was released to add support for the TFT.MSEARCH command.

    4. On January 13, 2023, Tair V5.0.25 was released to add support for analyzers.

    5. On March 15, 2023, Tair V5.0.28 was released to add support for query caching, document compression, and the TFT.ANALYZER command.

    6. On June 12, 2023, Tair V5.0.35 was released to add support for documents of the ARRAY data type and the similarity ranking algorithm Okapi BM25.

    Redis 6.0-compatible DRAM-based instances

    1. On February 7, 2023, Tair V6.2.4.1 was released to add support for TairSearch.

      Tair V6.2.4.1 has all the features provided by Redis 5.0-compatible DRAM-based instances of Tair V5.0.25.

    2. On March 14, 2023, Tair V6.2.5.0 was released to add support for query caching, document compression, and the TFT.ANALYZER command.

      Tair V6.2.5.0 has all the features provided by Redis 5.0-compatible DRAM-based instances of Tair V5.0.28.

    3. On June 12, 2023, Tair V6.2.7.3 was released to add support for documents of the ARRAY data type and the similarity ranking algorithm Okapi BM25.

      Tair V6.2.7.3 has all the features provided by Redis 5.0-compatible DRAM-based instances of Tair V5.0.35.

    4. On December 21, 2023, Tair V23.12.1.2 was released with support for the TFT.EXPLAINSCORE command.

    Best practices

    Prerequisites

    The instance is a Tair DRAM-based instance that meets one of the following requirements:

    Note We recommend that you update your instance to the latest minor version for more features and higher stability. For more information, see Update the minor version of an instance. If your instance is a cluster instance or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version to ensure that all commands can be run as expected. For more information about cluster instances and read/write splitting instances, see Cluster architecture and Read/write splitting architecture.

    Precautions

    • The TairSearch data that you want to manage is stored on the Tair instance.

    • To reduce memory usage, we recommend that you perform the following operations:

      • When you create indexes, set index to true for document fields that you want to specify as inverted fields. For other document fields, set index to false.

      • Specify an object containing arrays of includes and excludes patterns in the _source parameter to filter out document fields that you do not need and save fields that you need.

      • If you want to split a document into tokens, choose an appropriate analyzer to prevent unnecessary splitting and increased memory usage.

      • If a document is excessively large, use the document compression feature to automatically compress and decompress the document.

    • Do not add a large number of documents to a single index. Add the documents to multiple indexes. We recommend that you keep the number of documents per index within 5 million to prevent data skew in cluster instances, balance read and write requests, and reduce the number of large keys and hotkeys.

    Supported commands

    Table 1. Full-text search commands

    Command

    Syntax

    Description

    TFT.CREATEINDEX

    TFT.CREATEINDEX index mappings settings

    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. For more information, see Explicit mapping. You must create an index before you can add documents to the index.

    TFT.UPDATEINDEX

    TFT.UPDATEINDEX index mappings settings

    Adds the properties field to the specified index or modifies the settings of the index.

    TFT.GETINDEX

    TFT.GETINDEX index

    Obtains the mapping content of an index.

    TFT.ADDDOC

    TFT.ADDDOC index document [WITH_ID doc_id]

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

    TFT.MADDDOC

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

    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.

    TFT.UPDATEDOCFIELD

    TFT.UPDATEDOCFIELD index doc_id document

    Updates the document specified by doc_id in an index. If the document fields that you want to update are indexed in a way that is determined by the document mapping, the field data types must be the same as those specified by the mapping. If the fields that you want to update are not indexed fields, they can be of any data types.

    Note

    If the fields already exist, the document is updated. If the fields do not exist, the fields are added. If the document does not exist, the document is automatically created. In this case, the command is equivalent to TFT.ADDDOC.

    TFT.DELDOCFIELD

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

    Deletes the specified field from the document specified by doc_id in an index. If the field is an indexed field, the information of the field is also deleted from the index.

    Note

    If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    TFT.INCRLONGDOCFIELD

    TFT.INCRLONGDOCFIELD index doc_id field increment

    Adds an increment to the specified field in the document specified by doc_id in an index. The increment can be a positive or negative integer. The data type of the field can only be LONG or INTEGER.

    Note

    If the document does not exist, the document is automatically created. In this case, the existing value of the field is 0, and the updated field value is obtained by adding the increment value to the existing field value. If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    TFT.INCRFLOATDOCFIELD

    TFT.INCRFLOATDOCFIELD index doc_id field increment

    Adds an increment to the specified field in the document specified by doc_id in an index. The increment can be a positive or negative floating-point number. The data type of the field can only be DOUBLE.

    Note

    If the document does not exist, the document is automatically created. In this case, the existing value of the field is 0, and the updated field value is obtained by adding the increment value to the existing field value. If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    TFT.GETDOC

    TFT.GETDOC index doc_id

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

    TFT.EXISTS

    TFT.EXISTS index doc_id

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

    TFT.DOCNUM

    TFT.DOCNUM index

    Obtains the number of documents in an index.

    TFT.SCANDOCID

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

    Obtains the IDs of all documents in an index.

    TFT.DELDOC

    TFT.DELDOC index doc_id [doc_id] ...

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

    TFT.DELALL

    TFT.DELALL index

    Deletes all documents from an index but retains the index.

    TFT.ANALYZER

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

    Queries the tokenization effects of the specified analyzer.

    TFT.SEARCH

    TFT.SEARCH index query

    Queries the documents in an index. The query syntax is similar to the Query Domain Specific Language (DSL) syntax used in Elasticsearch. For more information, see Query DSL.

    TFT.MSEARCH

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

    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.

    TFT.EXPLAINCOST

    TFT.EXPLAINCOST index query

    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.

    TFT.EXPLAINSCORE

    TFT.EXPLAINSCORE index query [doc_id] ...

    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.

    DEL

    DEL key [key ...]

    Deletes one or more TairSearch keys.

    Table 2. Auto-complete commands

    Command

    Syntax

    Description

    TFT.ADDSUG

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

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

    TFT.DELSUG

    TFT.DELSUG index text [text] ...

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

    TFT.SUGNUM

    TFT.SUGNUM index

    Obtains the number of auto-complete text entries in the specified index.

    TFT.GETSUG

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

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

    TFT.GETALLSUGS

    TFT.GETALLSUGS index

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

    Note The following list describes the conventions for the command syntax used in this topic:
    • Uppercase keyword: indicates the command keyword.
    • Italic text: indicates variables.
    • [options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.
    • A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.
    • ...: indicates that the parameter preceding this symbol can be repeatedly specified.

    TFT.CREATEINDEX

    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. For more information, see Explicit mapping. You must create an index before you can add documents to the index.

    Note

    To prevent large keys from being generated, you can split large indexes into small indexes and devise load distribution rules to write data to different indexes. When you create indexes, make sure that these indexes have the mappings and settings parameters set to the same values. After these indexes are created, you can query them by using TFT.MSEARCH.

    Parameter

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

    • mappings: the mapping content. The following syntax is supported:

      • dynamic: the mapping mode. The strict mapping mode is supported. Only fields that have been specified in properties can be written. If you do not specify the mapping mode, non-strict mapping is used. In non-strict mode, the system does not check whether the fields to be written have been specified in properties.

      • enabled: forcefully checks whether the field types in a document to be written are the same as those specified in properties. If they are not the same, the document cannot be written. Valid values: true and false. The default value is true, which indicates that a forceful check is performed. This parameter takes effect only for non-indexed fields (index set to false). For indexed fields, a forceful check is performed.

      • _source: the source of 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: stores the original document. By default, enabled is set to true and all fields in the document are stored.

          You can set excludes to specify the fields that you do not want to store in the original document and includes to specify the fields that you want to store. Wildcards are accepted. If a field is specified by both excludes and includes, excludes takes precedence over includes and the field is not stored in the original document.

          Example 1: "_source":{"enabled":true} 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 to an index field. Default value: true. Valid values:

          • true: sets the field to an index field. In this case, you can query documents only by using index fields.

            Tair stores the original documents of all index fields in memory. If _source is set to "enabled":false for this field, the returned original documents of a query do not contain this field.

          • false: does not set the field to an index 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, to use a keyword array, you must specify keyword[] as the type parameter. Example: TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"f0":{"type":"keyword[]"}}}}'.

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

            • ignore_above: the maximum number of characters that can be contained in the keyword string. Default value: 128. Example: "ignore_above":128.

            • similarity: the similarity algorithm. Valid values: classic and BM25. Default value: classic. classic indicates the Term Frequency - Inverse Document Frequency (TF-IDF) algorithm. BM25 indicates the Okapi BM25 algorithm. Example: TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"fs0":{"type":"keyword","similarity":"BM25"}}}}'. You can also specify custom parameters of the Okapi BM25 algorithm by using the settings parameter.

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

            • analyzer: parses the string in text to store the results in an index. Default value: standard.

              • You can choose an analyzer from TairSearch built-in analyzers that include standard, jieba (recommended analyzer for Chinese that works better than chinese),stop, IK, pattern, whitespace, simple, keyword, chinese, french, dutch, and russian. For example, "analyzer":"jieba" indicates that the jieba analyzer for Chinese is used. For more information, see the "Built-in analyzers" section of the "Search analyzers" topic.

              • You can also define a custom analyzer by using syntax such as "analyzer":"my_custom_analyzer" and then configure the analyzer by setting the analysis parameter in settings.

            • search_analyzer: the tokenizer that is used in the search. The supported tokenizer types are the same as those supported by the analyzer parameter. The default value of this parameter is the same as that 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 into a UNIX timestamp and store the timestamp as a piece of LONG-typed data.

          • integer: the INTEGER data type.

          • double: the DOUBLE data type. Special data types such as NAN, INF, and -INF are not supported.

    • settings: the index settings. This parameter is optional. Fields in the parameter:

      • analysis: the custom analyzer. For more information, see the "Custom analyzers" section of the "Search analyzers" topic.

      • 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}}}}}'. Fields:

        • 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: the cache that stores query results. By default, a maximum of 10,000 query results can be cached without a limit on the memory usage. After the number of cached query results reaches 10,000, the LRU algorithm is used to evict the least recently used query results from the cache. The queries_cache parameter has the size and ttl fields. Valid values:

        • size: the maximum amount of memory that can be used for query caching. Data type: STRING. If this value is exceeded, the LRU algorithm is used to evict the least recently used query results from the cache.

          The default unit of this field is bytes. For example, "size":"1000" specifies that query caching can consume a maximum of 1,000 bytes worth of memory. You can also use KB or MB as the unit of this field. Examples: "size":"10kb" and "size":"1mb".

        • ttl: the validity period of a cached query result. Data type: INTEGER. Default value: 10. Unit: seconds.

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

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

      • compress_doc: specifies whether to enable 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: the minimum size of a document to be considered for compression in the first place. Data type: STRING. Default value: 10. Unit: KB.

          The default unit of this field is bytes. You can also use KB or MB as the unit of this field. Examples: "size":"1000", "size":"10kb", and "size":"1mb".

        • enable: specifies whether to enable document compression. Data type: BOOLEAN. Valid values: true and false. Default value: false.

        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.

    Output

    • 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. 
# Specify a product name (product_name) of the text type. 
# Specify a product title (product_title) of the text type and set analyzer to jieba. 
# Create a price (price) of the double type.

    Sample output:

    OK

    TFT.UPDATEINDEX

    Item

    Description

    Syntax

    TFT.UPDATEINDEX index mappings settings

    Command description

    Adds the properties field to the specified index or modifies the settings of the index.

    Parameter

    • 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. Make sure that the properties field does not conflict with the existing fields. Otherwise, the field cannot be added.

    • settings: the index settings. Only the queries_cache, compress_doc, and index fields can be modified. For the index field, only the k1 and b values in the Okapi BM25 algorithm can be modified.

    Note

    For more information about the mappings and settings parameters, see TFT.CREATEINDEX.

    Output

    • 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

    TFT.GETINDEX

    Item

    Description

    Syntax

    TFT.GETINDEX index

    Command description

    Obtains the mapping content of an index.

    Parameter

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

    Output

    • 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"}}}}}

    TFT.ADDDOC

    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 doc_id. If the document ID already exists, the existing ID is overwritten. If you do not specify WITH_ID doc_id, a document ID is automatically generated. By default, WITH_ID doc_id is not specified.

    Parameter

    • 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 includes in the _source 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.

    Output

    • 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

    TFT.MADDDOC

    Item

    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.

    Parameter

    • 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 includes in the _source 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.

    Output

    • 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

    TFT.UPDATEDOCFIELD

    Item

    Description

    Syntax

    TFT.UPDATEDOCFIELD index doc_id document

    Command description

    Updates the document specified by doc_id in an index. If the document fields that you want to update are indexed in a way that is determined by the document mapping, the field data types must be the same as those specified by the mapping. If the fields that you want to update are not indexed fields, they can be of any data types.

    Note

    If the fields already exist, the document is updated. If the fields do not exist, the fields are added. If the document does not exist, the document is automatically created. In this case, the command is equivalent to TFT.ADDDOC.

    Parameter

    • 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 includes in the _source 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.

    Output

    • 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

    TFT.DELDOCFIELD

    Item

    Description

    Syntax

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

    Command description

    Deletes the specified field from the document specified by doc_id in an index. If the field is an indexed field, the information of the field is also deleted from the index.

    Note

    If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    Parameter

    • 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.

    Output

    • 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

    TFT.INCRLONGDOCFIELD

    Item

    Description

    Syntax

    TFT.INCRLONGDOCFIELD index doc_id field increment

    Command description

    Adds an increment to the specified field in the document specified by doc_id in an index. The increment can be a positive or negative integer. The data type of the field can only be LONG or INTEGER.

    Note

    If the document does not exist, the document is automatically created. In this case, the existing value of the field is 0, and the updated field value is obtained by adding the increment value to the existing field value. If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    Parameter

    • 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.

    Output

    • 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

    TFT.INCRFLOATDOCFIELD

    Item

    Description

    Syntax

    TFT.INCRFLOATDOCFIELD index doc_id field increment

    Command description

    Adds an increment to the specified field in the document specified by doc_id in an index. The increment can be a positive or negative floating-point number. The data type of the field can only be DOUBLE.

    Note

    If the document does not exist, the document is automatically created. In this case, the existing value of the field is 0, and the updated field value is obtained by adding the increment value to the existing field value. If the field does not exist, the operation cannot be performed. For example, the field may not exist because it is filtered out by using _source.

    Parameter

    • 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.

    Output

    • 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"

    TFT.GETDOC

    Item

    Description

    Syntax

    TFT.GETDOC index doc_id

    Command description

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

    Parameter

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

    • doc_id: the ID of the document.

    Output

    • 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"}}

    TFT.EXISTS

    Item

    Description

    Syntax

    TFT.EXISTS index doc_id

    Command description

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

    Parameter

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

    • doc_id: the ID of the document.

    Output

    • If the operation is successful, the return value varies based on whether the document exist.

      • 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

    TFT.DOCNUM

    Item

    Description

    Syntax

    TFT.DOCNUM index

    Command description

    Obtains the number of documents in an index.

    Parameter

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

    Output

    • 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

    TFT.SCANDOCID

    Item

    Description

    Syntax

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

    Command description

    Obtains the IDs of all documents in an index.

    Parameter

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

    • cursor: the cursor used in this scan.

    • MATCH *value*: the matching pattern. value specifies the value that you use for matching. Example: MATCH *redis*.

    • COUNT count: the maximum number of documents that can be scanned at a time. Default value: 100.

    Output

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

      • The first element of the array is the cursor used for the next scan. If the index is scanned, a value of 0 is returned.

      • The second element of the array is the IDs of the documents that are obtained in this scan.

    • 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"

    TFT.DELDOC

    Item

    Description

    Syntax

    TFT.DELDOC index doc_id [doc_id] ...

    Command description

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

    Parameter

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

    • doc_id: the ID of the document.

    Output

    • 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 an ID of 00014 does not exist. In this case, only the 00011 document is deleted and a value of 1 is returned.

    TFT.DELALL

    Item

    Description

    Syntax

    TFT.DELALL index

    Command description

    Deletes all documents from an index but retains the index.

    Parameter

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

    • doc_id: the ID of the document.

    Output

    • If the operation is successful, OK is returned.

    • Otherwise, an error message is returned.

    Example

    Sample command:

    TFT.DELALL idx:product

    Sample output:

    OK

    TFT.ANALYZER

    Item

    Description

    Syntax

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

    Command description

    Queries the tokenization effects of the specified analyzer.

    Parameter

    • 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.

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

    • INDEX: the name of the index for which the analyzer is created. This parameter is optional. 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: specifies whether to return the amount of time that is taken to split the document into tokens. This parameter is optional. Unit: microseconds.

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

    Output

    • 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
        }
    ]
}'

    TFT.SEARCH

    Item

    Description

    Syntax

    TFT.SEARCH index query

    Command description

    Queries the documents in an index. The query syntax is similar to the Query Domain Specific Language (DSL) syntax used in Elasticsearch. For more information, see Query DSL.

    Parameter

    index: the name of the index that you want to manage by running this command. query: 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, chinese, arabic, cjk, czech, brazilian, german, greek, persian, french, dutch, russian, and jieba. The default value is standard, which indicates an English tokenizer. To parse Chinese characters, you can use jieba. 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}}}}' and '{"query":{"term":{"f0":"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 1,024 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: It (less than), gt (greater than), Ite (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.

        Valid values of tie_breaker: 0 to 1. Default value: 0. After tie_breaker is specified, the document score can be calculated based on the following formula: Score from a matching clause that has the highest score + (Scores from other matching clauses × tie_breaker value). Assume that doc1 matches three query clauses whose document scores are 5, 1, and 3 and a tie_break value of 0.5 is specified. In this case, the score of doc1 can be calculated by using the following formula: Score of doc1 = 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}}}

    TFT.MSEARCH

    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.

    Note

    The output of the TFT.MSEARCH command is a result of rating, sorting, and aggregating query results from these indexes. The output is different from results generated by directly rating, sorting, and aggregating datasets in multiple indexes. TFT.MSEARCH policy:

    • Rate and sort: rates and sorts child result sets.

    • Aggregate:

      • sum, max, min, avg, or value_count: performs an aggregation operation on child result sets by using an aggregate function.

      • sum_of_squares, variance, or std_deviation: performs an averaging operation on child result sets.

      • terms aggregation or filter aggregation: performs another aggregation operation on child result sets.

    Parameter

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

    • index: the names of the indexes 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. Otherwise, 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 starting 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.

    Note

    Unlike the query statement of the TFT.SEARCH command, the query statement of the TFT.MSEARCH command does not support the from parameter, but supports paged query by using the size, reply_with_keys_cursor, and keys_cursor parameters. For more information about the syntax of other parameters, see TFT.SEARCH.

    Output

    • 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 the index mappings and settings and the value of keys_cursor. keys_cursor indicates the cursor position for the next query and is optional. For business requests, ignore the CRC-64 value. Example of aux_info:

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

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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 output:

    {"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}}'
# Use the statement that you use in the first query and include the keys_cursor information from the previous query.

    Sample output:

    {"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}}}

    TFT.EXPLAINCOST

    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.

    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.

    Output

    • 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. This parameter includes three fields: time_cost_us, query, and doc_num. time_cost_us indicates the total execution time of the query in milliseconds, query indicates the query type, and doc_num indicates the number of documents that are involved in the query. If a bool statement is used, the steps field is displayed to indicate the amount of time that is consumed to execute the bool statement.

      • AGGS_COST: the amount of time that is consumed by aggregations involved in the query. This parameter also includes the time_cost_us field. If no aggregations are specified in the query statement, this parameter is not returned.

      • COLLECTOR_COST: the amount of time that is consumed to collect and sort the results. This parameter includes two fields: time_cost_us and collector_type. collector_type indicates the type of the collector that is used to sort the collected entries. Valid values of collector_type: ScoreCollector and 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
    }
}

    TFT.EXPLAINSCORE

    Item

    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.

    Output

    • If the operation is successful, the information of the queried documents is returned. The detailed score information for each document, typically represented as an _explanation object, 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
        }
    }
}

    TFT.ADDSUG

    Item

    Description

    Syntax

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

    Command description

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

    Parameter

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

    • text: the auto-complete text entry that you want to add to the index.

    • weight: the weight of the text entry. The weight must be a positive integer.

    Output

    • 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

    TFT.DELSUG

    Item

    Description

    Syntax

    TFT.DELSUG index text [text] ...

    Command description

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

    Parameter

    • 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

    TFT.SUGNUM

    Item

    Description

    Syntax

    TFT.SUGNUM index

    Command description

    Obtains the number of auto-complete text entries in the specified index.

    Parameter

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

    Output

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

    • Otherwise, an error message is returned.

    Example

    Sample command:

    TFT.SUGNUM idx:redis

    Sample output:

    (integer) 3

    TFT.GETSUG

    Item

    Description

    Syntax

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

    Command description

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

    Parameter

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

    • prefix: the prefix that you specify.

    • MAX_COUNT count: the maximum number of text entries that can be returned. Valid values: 0 to 255.

    • FUZZY: specifies whether to enable fuzzy match.

    Output

    • 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"

    TFT.GETALLSUGS

    Item

    Description

    Syntax

    TFT.GETALLSUGS index

    Command description

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

    Parameter

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

    Output

    • 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"

    Aggregations

    You can add the aggs (aggregations) parameter to TFT.SEARCH commands to aggregate results obtained by using query clauses.

    Usage

    In most cases, you must specify the aggregation name, type, and field for the aggs parameter. Only fields of the numeric and keyword types are supported. Sample command:

    TFT.SEARCH shares '{"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Sum":{"sum":{"field":"purchase_price"}}}}'
# Specify Jay_Sum as the aggregation name, sum as the aggregation type, and purchase_price as the aggregation field.

    Query and aggregation results are returned. Example:

    {"hits":{"hits":[{"_id":"16581351808123930","_index":"today_shares0718","_score":1.0,"_source":{"shares_name":"XAX","logictime":14300210,"purchase_type":1,"purchase_price":101.1,"purchase_count":100,"investor":"Jay"}},{"_id":"16581351809626430","_index":"today_shares0718","_score":1.0,"_source":{"shares_name":"XAX","logictime":14300310,"purchase_type":1,"purchase_price":111.1,"purchase_count":100,"investor":"Jay"}}],"max_score":1.0,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Sum":{"value":212.2}}}
    Note

    You can add "size":0 to the query syntax so that only aggregation results are returned.

    Aggregation types supported by aggs

    Metrics, terms, and filter aggregations are supported by the aggs parameter.

    Item

    Description

    Metrics aggregation

    Computes metrics based on values extracted from the fields of documents that are being aggregated. These fields are typically of a numeric type, such as INTEGER or DOUBLE. Nested aggregations are not supported. Valid values:

    • sum: calculates the total value.

    • max: calculates the maximum value.

    • min: calculates the minimum value.

    • avg: calculates the average value.

    • sum_of_squares: calculates the sum of squares.

    • variance: calculates the variance.

    • std_deviation: calculates the standard deviation.

    • value_count: counts the number of values. Duplicated values are counted. Fields of numeric and keyword types are supported.

    • extended_stats: performs aggregations of all the preceding types and returns the results at once.

    Note

    All parameters except for value_count only support numeric fields.

    Output: DOUBLE-typed values obtained by using specific fields for calculation.

    Terms Aggregation

    Calculates the deduplicated number of values. Only fields of the keyword type are supported. Nested aggregations are supported. Valid values:

    • terms

      • field: the aggregation field. Only fields of the keyword type are supported.

      • size: the number of terms that can be returned. Default value: 10. Valid values: [1,65536).

      • order: the sort rule of returned terms. Default value: _count. Valid values:

        • _count: sorts terms by _count. This indicates that terms are sorted based on the number of documents associated with each term. Default value: desc. Valid values: desc and asc. Example: "order":{"_count":"desc"}.

        • _key: sorts results by _key. This indicates that terms are sorted in lexicographic order. Valid values: desc and asc. Example: "order":{"_key":"desc"}.

      • min_doc_count: the minimum number of documents that can be displayed. If the number of documents is less than the min_doc_count value, the number is not displayed.

      • include: the string to be contained or matched. If the field is a string, regular expression match is supported. If the field is an array, exact match is required.

      • exclude: the string that cannot be contained or matched. The field types supported are the same as those supported by include. If both include and exclude are specified, include takes precedence over exclude.

    Example:

    {
  "aggs": {
    "Per_Investor_Freq":{
      "terms": {
        "field": "investor"
      }
    }
  }
}

    Output: a JSON object obtained by using the key aggregation. In the object, the key aggregation uses buckets to display statistics. Each bucket contains a key (aggregation field) and a doc_count value (number of documents associated with the aggregation field). Example:

    {
  "aggregations": {
    "Per_Investor_Freq": {
      "buckets": [
        {
          "doc_count": 2,
          "key": "Jay"
        },
        {
          "doc_count": 1,
          "key": "Mila"
        }
      ]
    }
  }
 }

    Filter Aggregation

    Filters query results of a query statement. Nested aggregations are supported.

    Output: the number of documents (doc_count) that match the filter conditions.

    Aggregation examples

    1. Create an index. 

      TFT.CREATEINDEX today_shares '{"mappings":{"properties":{"shares_name":{"type":"keyword"},"logictime":{"type":"long"},"purchase_type":{"type":"integer"},"purchase_price":{"type":"double"},"purchase_count":{"type":"long"},"investor":{"type":"keyword"}}}}'
# Create an index that represents the stock trading volume of today.
# shares_name: the name of each stock.
# logictime: the time when the deal is complete.
# purchase_type: the purchase type.
# purchase_price: the purchase price.
# purchase_count: the number of purchased stock shares.
# investor: the ID of the buyer.

      Expected output:

      OK

    2. Add document data.

      Run the following commands: 

      TFT.ADDDOC today_shares '{"shares_name":"XAX","logictime":14300210, "purchase_type":1,"purchase_price":101.1, "purchase_count":100,"investor":"Jay"}'
TFT.ADDDOC today_shares '{"shares_name":"XAX","logictime":14300310, "purchase_type":1,"purchase_price":111.1, "purchase_count":100,"investor":"Jay"}'
TFT.ADDDOC today_shares '{"shares_name":"YBY","logictime":14300410, "purchase_type":1,"purchase_price":11.1, "purchase_count":100,"investor":"Mila"}'

      Expected output:

      OK

    3. Perform a query.

      Sample commands:

      sum

      # Query the total amount that Jay spent to purchase the stocks. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Sum":{"sum":{"field":"purchase_price"}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Sum":{"value":212.2}}}

      max

      # Query the largest amount that Jay spent to purchase a stock. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Max":{"max":{"field":"purchase_price"}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Max":{"value":111.1}}}

      avg

      # Query the average amount that Jay spent to purchase different stocks. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Avg":{"avg":{"field":"purchase_price"}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Avg":{"value":106.1}}}

      std_deviation

      # Query the standard deviation of the amount that Jay spent to purchase stocks. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Std_Deviation":{"std_deviation":{"field":"purchase_price"}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Std_Deviation":{"value":5.0}}}

      extended_stats

      # Query the statistics of the amount that Jay spent to purchase stocks. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"investor":"Jay"}},"aggs":{"Jay_Extended_Stats":{"extended_stats":{"field":"purchase_price"}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":2}},"aggregations":{"Jay_Extended_Stats":{"count":2,"sum":212.2,"max":111.1,"min":101.1,"avg":106.1,"sum_of_squares":10221.21,"variance":25.0,"std_deviation":5.0}}}

      terms

      # Query the buyers that have completed at least two transactions. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"purchase_type":1}},"aggs":{"Per_Investor_Freq":{"terms":{"field":"investor","min_doc_count":2,"order": {"_key":"desc"}}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":3}},"aggregations":{"Per_Investor_Freq":{"buckets":[{"key":"Jay","doc_count":2}]}}}

      nested terms aggregation

      # Query the number of transactions conducted for each stock and the average amount spent to purchase each stock. The XAX stock is excluded. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"purchase_type":1}},"aggs":{"Per_Investor_Freq":{"terms":{"field":"shares_name","include":"[A-Z]+","exclude":["XAX"]},"aggs":{"Price_Avg":{"avg":{"field":"purchase_price"}}}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":3}},"aggregations":{"Per_Investor_Freq":{"buckets":[{"key":"YBY","doc_count":1,"Price_Avg":{"value":11.1}}]}}}

      nested filter aggregation

      # Query the total number of stocks purchased by Jay and the statistics of the amount that Jay spent to purchase stocks. 
TFT.SEARCH today_shares '{"size":0,"query":{"term":{"purchase_type":1}}, "aggs":{"Jay_BuyIn_Filter": {"filter": {"term":{"investor": "Jay"}},"aggs":{"Jay_BuyIn_Quatation":{"extended_stats":{"field":"purchase_price"}}}}}}'

# Expected output:
{"hits":{"hits":[],"max_score":null,"total":{"relation":"eq","value":3}},"aggregations":{"Jay_BuyIn_Filter":{"doc_count":2,"Jay_BuyIn_Quatation":{"count":2,"sum":212.2,"max":111.1,"min":101.1,"avg":106.1,"sum_of_squares":10221.21,"variance":25.0,"std_deviation":5.0}}}}