本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# FT.SEARCH
<a name="vector-search-commands-ft.search"></a>

对指定索引执行搜索。系统会返回与查询表达式匹配的键。

```
FT.SEARCH <index-name> <query>
[NOCONTENT]
[RETURN <token_count> (<field-identifier> [AS <alias>])+]
[TIMEOUT timeout] 
[PARAMS <count> <name> <value> [<name> <value>]]
[LIMIT <offset> <count>]
```
+ <index>（必填）：要查询的索引名称。
+ <query>（必填）：查询字符串，详情见下文。
+ NOCONTENT（可选）：如果存在，则仅返回生成的键名称，不包含任何键值。
+ TIMEOUT <timeout>（可选）：允许您为搜索命令设置超时值。该值必须是整数，以毫秒为单位。
+ PARAMS <count> <name1> <value1> <name2> <value2> ...（可选）：`count` 是参数的数量，即值名对数量的两倍。有关用法的详细信息，请参阅查询字符串。
+ RETURN <count> <field1> <field2> ...（可选）：计数是要返回的字段数量。指定要从文档中检索的字段，以及返回值的任何别名。默认情况下，系统会返回所有字段，除非设置了 NOCONTENT 选项，在这种情况下，系统不会返回任何字段。如果计数设置为“0”，则其行为与 NOCONTENT 相同。
+ LIMIT: <offset> <count>：让您能够选择结果的一部分。系统会跳过第一个 <offset> 键，最多只能包含 <count> 个键。默认值为“LIMIT 0 10”，最多返回 10 个键。
+ PARAMS：键值对数量的两倍。可以在查询表达式中引用参数 key/value 对。有关更多信息，请参阅[向量搜索查询表达式](https://docs.amazonaws.cn/memorydb/latest/devguide/vector-search-overview.html#vector-search-query-expression)。
+ DIALECT: <dialect>（可选）：指定方言。唯一支持的方言是 2。

**RESPONSE**

如果成功，该命令会返回数组，否则会返回错误。

成功后，响应数组中的第一个条目表示匹配键的数量，后面是每个匹配键的一个数组条目。请注意，如果指定 `LIMIT` 选项，它将仅控制返回的键的数量，不会影响第一个条目的值。

如果指定 `NOCONTENT`，则响应中的每个条目仅包含匹配的键名称。否则，每个条目都包含匹配的键名称，后面是返回的字段数组。密钥的结果字段由一组 name/value 对组成。第一 name/value 对用于计算的距离。该对名称由向量字段名称前缀“\_\_”、后缀“\_score”构成，其值是计算出的距离。其余 name/value 对是该`RETURN`子句控制的密钥的成员和值。

查询字符串遵循以下语法：

```
<filtering>=>[ KNN <K> @<vector_field_name> $<vector_parameter_name> <query-modifiers> ]
```

其中：
+ <filtering>：是 \* 或筛选表达式。\* 表示不筛选，因此将搜索索引内的所有向量。您可以使用筛选表达式来指定要搜索的向量的子集。
+ <vector\_field\_name>：指定索引内向量字段的名称。
+ <K>：要返回的近邻向量的数量。
+ <vector\_parameter\_name>：PARAM 名称，其相应值为 KNN 算法提供查询向量。请注意，此参数必须以 little-endian 格式编码为 32 位 IEEE 754 二进制浮点数。
+ <query-modifiers>:（可选）修改此特定 KNN 搜索的 keyword/value 配对列表。当前，支持两个关键字：
  + EF\_RUNTIME：此关键字附带一个整数值，该值将覆盖创建索引时指定的 EF\_RUNTIME 的默认值。
  + AS：此关键字附带一个字符串值，该值将成为结果中分数字段的名称，覆盖默认的分数字段名称生成算法。

**筛选表达式**

筛选表达式是一个逻辑组合，由括号内的标签和数值搜索运算符构成。

**Tag**

标签搜索运算符使用一个或多个字符串来指定，这些字符串通过 \| 字符分隔。如果指定的字段包含任何一个指定的字符串，则键将满足标签搜索运算符的要求。

```
@<field_name>:{<tag>}
or
@<field_name>:{<tag1> | <tag2>}
or
@<field_name>:{<tag1> | <tag2> | ...}
```

例如，以下查询将返回蓝色、黑色或绿色的文档。

`@color:{blue | black | green}`

再举一个例子，以下查询将返回包含“hello world”或“hello universe”的文档。

`@description:{hello world | hello universe}`

**数值范围**

数值范围运算符允许筛选查询，仅返回介于给定起始值和结束值之间的值。既支持包含范围查询，也支持排除范围查询。对于简单的关系比较，您可以将 \+inf 和 -inf 与范围查询一起使用。范围搜索运算符的语法是：

```
@<field_name>:[ [(] <bound> [(] <bound>]
```

...其中 <bound> 要么是数字，要么是 \+inf 或 -inf。包含没有前导左圆括号的边界值，排除有前导左圆括号的边界值。

参照下表，了解数学表达式与筛选查询的映射关系。

```
min <= field <= max         @field:[min max]
min < field <= max          @field:[(min max]
min <= field < max            @field:[min (max]
min < field < max            @field:[(min (max]
field >= min                @field:[min +inf]
field > min                    @field:[(min +inf]
field <= max                @field:[-inf max]
field < max                    @field:[-inf (max]
field == val                @field:[val val]
```

**逻辑运算符**

多个标签和数值搜索运算符可用于使用逻辑运算符来构造复杂的查询。

**逻辑和**

要设置逻辑 AND，请在谓词之间使用空格。例如：

`query1 query2 query3`

**逻辑或**

要设置逻辑 OR，请在谓词之间使用空格。例如：

`query1 | query2 | query3`

**逻辑否定**

对于任何查询，您都可以通过在其前面加上 `-` 字符来执行否定查询。否定查询会返回所有与查询不匹配的条目。这也包括没有相应字段的键。

例如，对 @genre:{comedy} 的否定查询将返回所有不是喜剧的书籍以及所有没有类型字段的书籍。

以下查询将返回所有属于“喜剧”类型且出版时间不在 2015 至 2024 年之间的书籍，或者没有年份字段“@genre:[comedy] -@year:[2015 2024]”的书籍。

**运算符优先顺序**

典型运算符优先顺序规则适用，即逻辑 NEGATE 是最高优先级，其次是逻辑 AND，然后是逻辑 OR（优先级最低）。要覆盖默认优先顺序规则，您可以使用圆括号。

*组合逻辑运算符的示例*

您可以组合逻辑运算符以组成复杂的筛选表达式。

以下查询将返回所有类型为“喜剧”或“恐怖”（且）出版时间在 2015 至 2024 年间的书籍：`@genre:[comedy|horror] @year:[2015 2024]`

以下查询将返回所有类型为“喜剧”或“恐怖”（或者）出版时间在 2015 至 2024 年间的书籍：`@genre:[comedy|horror] | @year:[2015 2024]`

以下查询将返回所有没有类型字段或类型字段不是“喜剧”且出版时间在 2015 年至 2024 年间的书籍：`-@genre:[comedy] @year:[2015 2024]`