云数据库 Tair（兼容 Redis®）：Search

类别

说明

语法

TFT.CREATEINDEX index mappings settings

命令描述

创建索引（index）并添加映射（mappings），映射语法类似ES语法。在添加索引文档前，必须先创建索引。

选项

• index：待创建的索引名称。

• mappings：映射内容，支持的语法如下。

  • dynamic：映射模式，支持strict（严格映射），表示仅能写入在properties中已设置过的字段，无法成功写入未配置过的字段。若未指定该参数，则默认为非严格映射模式，即不会检查写入的字段是否已在properties中设置。

  • enabled：强制检查写入文档的字段类型与properties中指定的类型是否一致，若不一致则写入失败，取值为true（默认，表示会检查）和false。该参数仅对非索引字段（index为false）生效，索引字段会强制检查字段类型。

  • _source：设置存储原始文档，该参数不会影响对应字段索引的创建，取值如下。

    enabled：是否存储原始文档，取值如下。

    • true（默认）：存储原始文档，默认存储所有字段。

      可指定excludes（不需要存储的字段）和includes（需要存储的字段），支持配置通配符模式（WildCard）的字段。若某字段同时出现在excludes和includes时，则excludes的优先级大于includes，表示该字段最终不会存储在原始文档中，示例如下。

      示例一："_source":{"enabled":true}（默认），表示存储所有字段，等同于"_source":{"enabled":true,"excludes":[],"includes":[]}。

      示例二："_source":{"enabled":true,"excludes":[],"includes":["id","name"]}，表示仅存储“id”、“name”字段。

    • false：不存储原始文档。

  • properties：映射的字段集合，每个字段可设置如下属性。

    • index：是否将该字段设置为索引字段，取值如下：

      • true（默认）：索引字段，查询时仅能通过索引字段查找文档。

        Tair会在内存中存储所有索引字段的原始文档，若该字段在_source中配置不存储原始文档，则在查询时返回的原始文档中不显示该字段。

      • false：非索引字段。

    • boost：该字段的计分权重，默认为1，范围为正浮点数，Tair将自动计算出各个字段的相对计算分。

    • type：字段的数据类型，同时支持数组类型，取值如下。

      说明

      例如keyword的数组类型为keyword[]，其他数据类型类似。示例为：TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"f0":{"type":"keyword[]"}}}}'。

      • keyword：不可被拆分字符串。取值如下：

        • ignore_above：指定keyword的字符串长度上限，默认为128，例如"ignore_above":128。

        • similarity：相似度算法，取值为classic（默认，表示使用TF-IDF算法）、BM25（Okapi BM25算法），示例为：TFT.CREATEINDEX idx:pro '{"mappings":{"properties":{"fs0":{"type":"keyword","similarity":"BM25"}}}}'，您也可以在settings中自定义BM25算法的参数。

      • text：字符串，且可通过分词器解析，存入索引。取值如下：

        • analyzer：解析text存入索引的分词器。

          • 您可直接选择TairSearch内置分词器，包含standard（默认）、jieba（推荐的中文分词，效果比chinese好）、stop、IK、pattern、whitespace、simple、keyword、chinese、french、dutch和russian等。例如"analyzer":"jieba"，表示使用Jieba中文分词器，更多信息请参见内置分词器。

          • 您也可以自定义分词器，例如"analyzer":"my_custom_analyzer"，并在settings中的analysis参数中进行具体的分词器配置。

        • search_analyzer：指定搜索时使用的分词器，支持的分词器类型与analyzer相同，默认为analyzer的设置。

        • similarity：相似度算法，取值为classic（默认，表示使用TF-IDF算法）、BM25（Okapi BM25算法），您也可以在settings中自定义BM25算法的参数。

      • long：长整型，您可以将时间点转为Unix时间戳，存入该数据类型中。

      • integer：整型。

      • double：双精度浮点型，但不支持NaN、Inf、-Inf等特殊的数据类型。

• settings（可选）：配置索引设置，支持如下配置项。

  • analysis：自定义分词器，更多信息请参见自定义分词器。

  • index：自定义相似度算法，支持修改Okapi BM25算法的参数，示例如下：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}}}}}'。参数说明：

    • k1：词项在文档中的出现频率对得分（分数）的影响，该值越大，出现频率对于得分影响越大，默认值为1.2，取值范围需大于0。

    • b：文档长度对得分（分数）的影响，该值越大，文档长度对于得分影响越大，默认值为0.75，取值范围为[0,1]。

  • queries_cache：当您查询文档时，TairSearch支持将查询结果存入缓存，该缓存称为查询缓存，默认最大缓存为10000条查询结果（内存无限制），达到上限后，将通过LRU算法（最近最少使用的）逐出查询结果。您可以通过配置queries_cache，配置查询缓存的最大内存和TTL（Time To Live）配置，配置后，查询缓存的最大内存将以size为准。取值如下：

    • size：字符串类型，表示所有查询缓存的最大内存，当达到查询缓存最大内存后，也将通过LRU算法逐出查询结果。

      该参数的默认单位为字节，例如"size": "1000"表示最多能存储1000字节的查询缓存，同时还支持单位："kb"、"mb"，例如"size": "10kb"、"size": "1mb"。

    • ttl：整型，表示一条查询缓存的过期时间，默认为10s，单位为秒。

    示例："settings":{"queries_cache":{"size":"100mb","ttl":3}}。

    queries_cache配置项为节点维度的参数，在一个索引中配置后，在同进程内的其他索引也会受到影响。因此，建议所有索引都是用相同的queries_cache配置。

  • compress_doc：配置是否启用文档透明压缩功能。开启该功能会消耗更多的CPU，并增大读写时延，因此只建议在索引较大（如KB级别）且优先考虑存储成本时启用该功能。取值如下：

    • size：字符串类型，表示压缩的阈值，当索引达到该阈值时，才会被压缩，默认值为“10kb”。

      该参数的默认单位为字节，同时还支持单位："kb"、"mb"，例如"size": "1000"、"size": "10kb"、"size": "1mb"。

    • enable：布尔类型，表示是否启用文档压缩功能，取值为false（默认）和true。

    示例："settings":{"compress_doc":{"size":"1kb","enable":true}}。

    在通过TFT.UPDATEINDEX命令开启或关闭压缩功能后，压缩功能只对新写入或更新的文档生效，不会对已写入的文档生效。例如，通过TFT.UPDATEINDEX命令开启压缩功能，Tair仅会对之后写入或更新的文档进行压缩，不会对已写入的文档进行压缩操作。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

# 创建商品ID（product_id）为keyword数据类型，并设置上限为128个字符。
# 创建商品名称（product_name）为text数据类型。
# 创建商品标题（product_title）为text数据类型，并设置分词器为中文。
# 创建价格（price）为double数据类型。

返回示例：

OK

类别

说明

语法

TFT.UPDATEINDEX index mappings settings

命令描述

向指定的索引中新增properties字段，或修改索引设置。

选项

• index：待操作的索引名称。

• mappings：映射内容，仅输入新增的properties字段（无需输入dynamic、_source等信息），且新增的properties字段不能与原有字段冲突，否则会新增失败。

• settings：修改索引设置。仅支持修改queries_cache、compress_doc和index参数，其中index参数仅支持修改BM25算法中k1、b的值。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

OK

类别

说明

语法

TFT.GETINDEX index

命令描述

获取索引的映射内容。

选项

• index：待操作的索引名称。

返回值

• 执行成功：返回索引的映射内容，格式为JSON。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.GETINDEX idx:product

返回示例：

{"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 index document [WITH_ID doc_id]

命令描述

向索引中插入一个文档（document），可通过WITH_ID指定该文档在索引内的唯一ID（doc_id），若doc_id已存在，则更新并覆盖原文档。若不指定WITH_ID（默认），则自动生成doc_id。

选项

• index：待操作的索引名称。

• document：插入的文档，JSON格式，插入的值需与该字段定义的数据类型一致。

  说明

  若索引通过_source的includes参数配置了仅保存部分字段，则在插入或更新文档时仅保存includes中配置的字段。

• WITH_ID doc_id：是否指定文档ID，如需指定文档ID需输入doc_id值，doc_id的格式为任意字符串。

返回值

• 执行成功：返回文档ID，格式为JSON。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

{"id":"00001"}

数组的添加示例：

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

类别

说明

语法

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

命令描述

向索引中插入多个文档（document），每个文档必须指定文档ID（doc_id）。若某个文档写入失败（例如写入的文档内容与定义的格式不符），则该命令的所有文档均不会写入。

选项

• index：待操作的索引名称。

• document：插入的文档，JSON格式，插入的值需与该字段定义的数据类型一致。

  说明

  若索引通过_source的includes参数配置了仅保存部分字段，则在插入或更新文档时仅保存includes中配置的字段。

• doc_id：指定文档ID，doc_id的格式为任意字符串。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

OK

类别

说明

语法

TFT.UPDATEDOCFIELD index doc_id document

命令描述

选项

• index：待操作的索引名称。

• doc_id：指定文档ID。

• document：更新的文档内容，JSON格式。

  说明

  若索引通过_source的includes参数配置了仅保存部分字段，则在插入或更新文档时仅保存includes中配置的字段。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

OK

类别

说明

语法

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

命令描述

选项

• index：待操作的索引名称。

• doc_id：指定文档ID。

• field：待删除的字段。

返回值

• 执行成功：返回成功删除的字段数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.DELDOCFIELD idx:product 00011 product_group

返回示例：

(integer) 1

类别

说明

语法

TFT.INCRLONGDOCFIELD index doc_id field increment

命令描述

选项

• index：待操作的索引名称。

• doc_id：指定文档ID。

• field：待操作的字段，支持的字段类型为long或int类型，且不支持数组类型的字段。

• increment：待增加操作的值，可以指定该值为负数实现相减，数据类型为整型（int）。

返回值

• 执行成功：返回执行操作后字段的数值。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.INCRLONGDOCFIELD idx:product 00011 stock 100

返回示例：

(integer)100

类别

说明

语法

TFT.INCRFLOATDOCFIELD index doc_id field increment

命令描述

选项

• index：待操作的索引名称。

• doc_id：指定文档ID。

• field：待操作的字段，支持的字段类型double类型，且不支持数组类型的字段。

• increment：待增加操作的值，可以指定该值为负数实现相减，数据类型为双精度浮点型（double）。

返回值

• 执行成功：返回执行操作后字段的数值。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.INCRFLOATDOCFIELD idx:product 00011 stock 299.6

返回示例：

"299.6"

类别

说明

语法

TFT.GETDOC index doc_id

命令描述

获取索引中指定doc_id的文档内容。

选项

• index：待查询的索引名称。

• doc_id：指定文档ID。

返回值

• 执行成功：返回文档ID和文档内容。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.GETDOC idx:product 00011

返回示例：

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

类别

说明

语法

TFT.EXISTS index doc_id

命令描述

查询索引中指定doc_id的文档是否存在。

选项

• index：待查询的索引名称。

• doc_id：指定文档ID。

返回值

• 执行成功：

  • 若文档存在，返回1。

  • 若索引或文档不存在，返回0。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.EXISTS idx:product 00011

返回示例：

(integer) 1

类别

说明

语法

TFT.DOCNUM index

命令描述

获取索引中的文档数量。

选项

• index：待查询的索引名称。

返回值

• 执行成功：索引的文档数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.DOCNUM idx:product

返回示例：

(integer) 3

类别

说明

语法

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

命令描述

获取索引中所有的doc_id。

选项

• index：待查询的索引名称。

• cursor：指定本次扫描的游标。

• MATCH *value*：模式匹配，value为待匹配的值，例如MATCH *redis*。

• COUNT count：指定本次扫描的最大数量，默认为100。

返回值

• 执行成功：返回一个数组。

  • 第一个元素：下次查询的cursor，若该key已扫描完成，则返回0。

  • 第二个元素：本次查询的doc_id。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.SCANDOCID idx:product 0 COUNT 3

返回示例：

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

类别

说明

语法

TFT.DELDOC index doc_id [doc_id] ...

命令描述

删除索引中doc_id指定的文档，支持指定多个doc_id。

选项

• index：待查询的索引名称。

• doc_id：指定文档ID。

返回值

• 执行成功：返回成功删除的文档数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.DELDOC idx:product 00011 00014

返回示例：

"1"    # 本示例中ID"00014"文档不存在，故仅删除ID"00011"文档，返回1。

类别

说明

语法

TFT.DELALL index

命令描述

删除索引中所有文档，但不会删除index。

选项

• index：待查询的索引名称。

• doc_id：指定文档ID。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.DELALL idx:product

返回示例：

OK

类别

说明

语法

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

命令描述

查询分词器分词效果。

选项

• analyzer_name：分词器名称，支持内置分词器和自定义分词器。

  若指定自定义分词器或修改了内置分词器的配置（停用词或词典），您还需要指定创建该分词器的索引名称（INDEX）。

• text：待分词的文档，utf-8格式。

• INDEX（可选）：分词器的索引名称。若指定自定义分词器或修改了内置分词器的配置（停用词或词典），该参数必选。

• SHOW_TIME（可选）：指定是否返回分词执行的时间，单位为微秒（us）。

  该时间包含词库加载的时间，当第一次加载JiebaAnalyzer、IKAnalyzer等具有较大内置词库的分词器时，耗时可能会达到秒级。

返回值

• 执行成功：返回Token信息，JSON格式。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.ANALYZER standard "Tair is a nosql database"

返回示例：

'{
    "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 index query

命令描述

根据query语句搜索索引的文档，query语法类似ES语法。

选项

index为待查询的索引名称；query为类似ES语法的DLS语句，支持如下字段：

• query：查询子句，支持如下语法。

  • match：基础的匹配查询，支持如下参数。

    在不需要对文档进行分词拆分或模糊匹配的场景下，推荐使用term、prefix等命令，以提高查询效率。

    • query：查询的文档内容。

      说明

      • 未开启模糊匹配（fuzziness）时，query中的文档会被指定分词器（analyzer）拆分成多个词根，同时您可以指定operator（不同词根之间的关系）、minimum_should_match（至少需要匹配多少个词根）参数。

      • 开启了模糊匹配（fuzziness）时，上述参数将无效，您可以指定prefix_length参数。

    • analyzer：指定match查询语句的分词器，支持standard（默认，英文分词器）、chinese、arabic、cjk、czech、brazilian、german、greek、persian、french、dutch、russian和jieba（中分分词），更多信息请参见Search分词器。

    • minimum_should_match：查询语句会通过分词器拆分成多个词根，您可以通过本参数指定至少需要匹配多少个词根。该参数在未开启模糊匹配且operator为OR时生效。

    • operator：指定通过分词器拆分的词根之间的关系，取值为AND和OR（默认）。例如'{"query":{"match":{"f0":{"query":"redis cluster","operator":"OR"}}}}'，表示待搜索的文档中包含"redis"或"cluster"即满足查询条件。

    • fuzziness：是否开启模糊匹配查询，默认为关闭，"fuzziness":1为开启模糊匹配，例如'{"query":{"match":{"f0":{"query":"excelentl","fuzziness":1}}}}'。

    • prefix_length：设置模糊匹配保持不变的起始字符数，默认为0，该参数仅在开启模糊匹配时生效。

  • term：词根查询，不会对查询内容进行拆分，效率比match高，支持查询所有字段类型。同时，该查询方式支持指定lowercase参数，表示是否将待查询的词根预先转换为小写，取值为true（默认）和false。例如'{"query":{"term":{"f0":{"value":"redis","boost": 2.0}}}}'或'{"query":{"term":{"f0":{"value":"redis","lowercase": false}}}}'。

    若添加文档时使用的分词器不会将文档转化为小写，建议将lowercase参数设置为false，否则可能查不到结果。

  • terms：多词根查询，上限为1024个词根。同时，该查询方式支持指定lowercase参数，表示是否将待查询的词根预先转换为小写，取值为true（默认）和false。例如'{"query":{"terms":{"f0":["redis","excellent"]}}}'。

    若添加文档时使用的分词器不会将文档转化为小写，建议将lowercase参数设置为false，否则可能查不到结果。

  • range：范围查询，支持所有字段类型，取值为lt（小于）、gt（大于）、lte（小于等于）和gte（大于等于），例如'{"query":{"range":{"f0":{"lt":"abcd","gt":"ab"}}}}'。

  • wildcard：通配符查询，格式为"wildcard":{"待查询field":{"value":"查询内容"}}，只支持*和?通配符，例如'{"query":{"wildcard":{"f0":{"value":"*b?Se"}}}}'。

  • prefix：前缀查询，例如'{"query":{"prefix":{"f0":"abcd"}}'，表示查询f0字段以abcd为开头的文档。

  • bool：复合查询，上限为1024个词根，取值如下。

    • must：查询结果需匹配must列表中所有查询子句，例如'{"query":{"bool":{"must":[{"match":{"DB":"redis"}},{"match":{"Architectures":"cluster"}}]}}}'，表示查询DB为Redis、架构（Architectures）为cluster的文档。

    • must_not：查询结果需不匹配must_not列表中所有查询子句。

    • should：查询结果需匹配should列表中任意一个查询子句（表示或），可指定minimum_should_match参数。

    • minimum_should_match：该参数需搭配should语句使用，表示至少需匹配多少个查询子句。若bool语句中只有should语句，则该参数默认为1；bool语句中还有must或must_not语句，则该参数默认为0。例如'{"query":{"bool":{"minimum_should_match":1,"should":[{"match":{"DB":"redis"}},{"match":{"Architectures":"cluster"}}]}}}'，表示查询DB为Redis或架构（Architectures）为cluster的文档。

    说明

    bool查询语句中可嵌套任何类型的子查询语句，例如嵌套bool语句，示例为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：最佳匹配复合查询，默认返回queries查询子句中单个query分数最高的结果在首位。

    若指定了tie_breaker参数，将增加匹配多个查询子句的文档分数，tie_breaker的取值范围为[0，1]，默认为0。指定tie_breaker后，目标文档分数的计算规则为：query的最高分+（（将除最高分以外的query分数相加） * tie_breaker）。例如查询中有3个子句，tie_breaker为0.5，doc1在每个子句的分数为[5,1,3]，最终doc1分数为5+((1+3)*0.5)。

    命令示例为'{"query":{"dis_max":{"queries":[{"term":{"f0":"redis"}},{"term":{"f1":"database"}},{"match":{"title":"redis memory database"}}],"tie_breaker": 0.5}}}'。

  • constant_score：固定分数的复合查询，通过filter查询并返回任意一个符合的文档，支持设置权重（boost，double类型，默认为1.0），文档将以指定的boost返回。例如'{"query":{"constant_score":{"filter":{"term":{"f0":"abc"}},"boost":1.2}}}'。

  • match_all：查询全部文档，支持设置权重（boost，double类型，默认为1.0），可以将指定的分数赋予所有返回的文档，例如'{"query":{"match_all":{"boost":2.3}}}'。

  说明

  通过bool、dis_max与constant_score进行复合查询时，可对term、terms、range、wildcard设置权重（boost，默认为1），区分多个条件的权重，例如'{"query":{"bool":{"must":[{"match":{"f0":"v0"}},"term":{"f0":{"value":"redis","boost":2}}]}}}'。

• sort：结果排序，但不支持指定数组类型的字段，取值如下。

  • _score（默认）：按计分权重降序，示例为"sort":"_score"。

  • _doc：按文档ID升序，示例为"sort":"_doc"。

  • 指定字段：按指定字段升序，该字段必须为索引（index为true）字段或开启强制类型检查（enabled为true）的字段，同时仅支持指定字段类型为：keyword、long、integer、double。例如"sort":"price"，表示指定以price字段升序排序。

  支持输入一个数组进行多条件排序，将按照数组内的顺序进行排序，可通过order调整默认顺序，取值为desc（降序）和acs（升序）。例如'{"sort":[{"price":{"order":"desc"}},{"_doc":{"order":"desc"}}]}'，表示优先根据price排序，在price相同时根据_doc排序。

• _source：指定查询结果中的字段，可指定includes（需要展示的field）和excludes（不需要展示的field），支持配置通配符模式（WildCard）的field。例如"_source":{"includes":["f0"]，表示查询结果仅返回f0字段。

• aggs：对query查询子句的结果进行聚合。若字段为数组类型，则仅支持Terms Aggregation。语法与示例请参见Aggregations介绍。

• track_total_hits：通过term、terms、match（不开启模糊匹配）语句查询（含复合查询）时，是否查询所有文档。取值如下：

  • false（默认）：仅查询score排名前100的文档。

  • true：查询所有文档。

    警告

    开启后，若命中的文档数过多会导致慢查询，请谨慎使用。

• from：指定开始返回的目标文档起点，默认为0，表示从第一个查到的文档开始返回。

• size：返回查询的文档数量，默认为10，取值范围为[0,10000]。size为0表示结果集中不返回具体的文档， 只返回命中查询的总文档数量（total）。

  说明

  可通过from和size参数到达分页的效果，但分页越多越影响性能。

返回值

• 执行成功：返回查询到的文档信息。

  说明

  返回参数中的relation为查询到的文档数量，取值：eq（表示查询到的文档数量等于value值）、gte（表示大于或等于value值），示例如下。

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

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

{"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 index_count index [index1] ... query

命令描述

根据query语句搜索多个索引的文档（待查询索引的mappings和settings的配置必须相同），汇聚多个索引的查询结果，再次进行打分、排序、聚合并返回。

选项

• index_cout：待查询的索引数量，取值范围为[1,100]。

• index：待查询的索引名称。查询多个索引时，待查询索引的mappings和settings的配置必须相同，若各索引的mappings配置不一致或索引不存在均会报错。

• query：聚合查询语句，支持如下参数：

  • query：查询子句。

  • sort：结果排序，但不支持指定数组类型的字段。

  • _source：指定查询结果中的字段。

  • aggs：对query查询子句的结果进行聚合。若字段为数组类型，则仅支持Terms Aggregation。

  • track_total_hits：通过term、terms、match（不开启模糊匹配）语句查询（含复合查询）时，是否查询所有文档。

  • size：指定查询返回的文档数量。

    可通过size、reply_with_keys_cursor与keys_cursor参数实现分页查询。若keys_cursor为0（默认情况下），Tair会在各索引的查询结果中，从排序最高的文档（第一位）开始，获取指定数量的文档；若keys_cursor不为0，则从指定位置开始获取指定数量的文档，再将多个索引的查询结果汇聚在一起，进行打分、排序、聚合，并输出最终文档。

    例如单次查询3个索引（key0、key1、key2），设置size为10：

    • 首次搜索，可设置keys_cursor为0：Tair会从3个索引中各搜索出排序靠前的10个文档（此时共有30个候选文档），然后汇聚、打分、排序、聚合等，输出整体排名靠前的10个文档。返回的keys_cursor示例为{"keys_cursor":{"key0":2,"key1":5,"key2":3}}。

    • 第二次查询时，可使用同样的查询语句，并加上{"keys_cursor":{"key0":2,"key1":5,"key2":3}}：Tair会在各个索引中，从指定的位置开始再获取10个文档（例如key0从第3位开始向后获取10个文档，key1与key2也类似，此时仍有30个候选文档），再将多个索引的查询结果汇聚在一起，进行打分、排序、聚合，并输出最终文档。

  • reply_with_keys_cursor：指定是否返回每个索引下一轮查询的游标信息，取值：true、false（默认）。

  • keys_cursor：指定本次查询的各索引的游标，可以将上轮查询返回的keys_cursor作为本次查询的输入，实现分页查询。默认为0，表示第一位。

返回值

• 执行成功：返回查询到的文档信息，与TFT.SEARCH的返回结果类似，同时还会返回aux_info。

  aux_info字段中包含：索引mappings和settings的CRC-64值（业务请求可忽略该值）、keys_cursor值（可选，下次各索引开始查询的游标位置）、field_type值（字段的数据类型，仅在根据索引字段排序时返回），aux_info示例如下：

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

• 其他情况返回相应的异常信息。

示例

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

命令示例：

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

返回示例：

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

第二页查询命令示例：

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}}'
# 查询语句与第一次查询相同，但需要增加上轮查询返回的keys_cursor信息。

返回示例：

{"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 index query

命令描述

查询query语句的执行耗时，返回内容包括查询过程中涉及到的文档集合数及各阶段的耗时。

选项

• index：待查询的索引名称。

• query：查询语句，语法与TFT.SEARCH相同。

返回值

• 执行成功：返回查询耗时信息，JSON格式，整体耗时由如下三部分组成。

  • QUERY_COST：query查询耗时，单位为微秒（time_cost_us）。同时还包含查询视图信息（query）和query对应的文档集合数（doc_num）。若涉及bool查询方法会展示bool查询过程的步骤耗时（steps）。

  • AGGS_COST：查询过程中聚合（Aggregations）的耗时，单位为微秒（time_cost_us），若查询语句中没有指定聚合查询，则无该耗时。

  • COLLECTOR_COST：查询结果采集、排序的耗时，单位为微秒（time_cost_us），同时还包含排序类型（collector_type），返回值为sort排序（ScoreCollector）和分数排序（CustomSortCollector）。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

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

类别

说明

语法

TFT.EXPLAINSCORE index query [doc_id] ...

命令描述

查询执行query语句的计分详情信息，您可以通过该命令了解文档分数的计算过程，并优化Search语句，提升文档的查询效果。

该命令当前仅内存型（兼容Redis 6.0）支持。

选项

• index：待查询的索引名称。

• query：查询语句，语法与TFT.SEARCH相同。

• doc_id：指定文档ID，若指定了该参数，返回结果只会包含doc_id对应的文档。

返回值

• 执行成功：返回查询到的文档信息，在TFT.SERACH返回结果的基础上增加每个文档的计分详情信息（_explanation），_explanation中存在如下字段。

  • score：该文档的得分。

  • description：score计算使用的公式。

  • field：该文档被query中指定的field所命中。

  • term：该文档被query中指定的词项所命中。

  • query_boost：该文档在本次查询中的计分权重。

  • details：文档的元数据与计分过程。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

{
    "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 index text weight [text weight] ...

命令描述

在指定索引中，添加自动补全的文本及对应权重，支持添加多个文本。

选项

• index：待操作的索引名称。

• text：自动补全文本。

• weight：对应文本的计分权重，范围为正整数。

返回值

• 执行成功：返回成功添加的文档数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

(integer) 2

类别

说明

语法

TFT.DELSUG index text [text] ...

命令描述

在指定索引中，删除自动补全的文本，支持删除多个文本。

选项

• index：待查询的索引名称。

• text：待删除的文本，需指定完整、正确的文本。

返回值

• 执行成功：返回成功删除的文本数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

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

返回示例：

(integer) 2

类别

说明

语法

TFT.SUGNUM index

命令描述

获取指定索引中自动补全文本的数量。

选项

• index：待查询的索引名称。

返回值

• 执行成功：返回索引中的文本数量。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.SUGNUM idx:redis

返回示例：

(integer) 3

类别

说明

语法

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

命令描述

根据指定前缀，查询匹配的自动补全文本，将优先返回权重比较高的text。

选项

• index：待查询的索引名称。

• prefix：指定的查询前缀。

• MAX_COUNT count：配置返回文本的最大数量，count的取值范围为[0,255]。

• FUZZY：是否启用模糊匹配。

返回值

• 执行成功：返回自动补全文本的列表。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.GETSUG idx:redis res MAX_COUNT 2 FUZZY

返回示例：

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

类别

说明

语法

TFT.GETALLSUGS index

命令描述

获取指定索引的全量自动补全文本。

选项

• index：待查询的索引名称。

返回值

• 执行成功：返回自动补全文本的列表。

• 其他情况返回相应的异常信息。

示例

命令示例：

TFT.GETALLSUGS idx:redis

返回示例：

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