# 标量查询 - QueryEntities
#### 功能介绍
接口用于精确查找与查询条件完全匹配的向量，此操作使用指定的布尔表达式对标量字段进行筛选。
#### URI
POST /v1/entities/query
#### 请求参数
表1请求Body参数 
| 参数              | 是否必选 | 参数类型             | 描述                                                                                                                                                                                                                                                                                                                                                                                                                        |
|:---|:---|:---|:---|
| store_name      | 是    | String           | **参数解释：** 知识仓实例名称，region内唯一。 **约束限制：** 长度范围为3到63个字符，支持小写字母、数字、中划线（ - ），第一个字符只能够是小写字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。                                             |
| collection_name | 是    | String           | **参数解释：** collection名称，知识仓内唯一。 **约束限制：** 长度范围为1到255个字符，支持字母、数字、中划线（ - ）和下划线（ _ ），大小写敏感。第一个字符只能够是下划线（ _ ）和字母，中划线（ - ）不得出现在字符串末尾。 **取值范围：** 不涉及。 **默认取值：** 不涉及。                      |
| output_fields   | 否    | Array of strings | **参数解释：** field名称列表，配置需与搜索结果一起返回的字段。 **约束限制：** 当取值为*\["count(\*)"\]*时，top_k必须为负数，表示统计符合条件的entity数量。 **取值范围：** 不涉及。 **默认取值：** *\[ \]*，不返回任何额外的字段数据。                                 |
| top_k           | 否    | Integer          | **参数解释：** 返回的entity个数限制。可以将此参数与offset结合使用以启用分页。当取值为负数时，表示返回所有符合条件的数据。 **约束限制：** 与offset取值的总和应小于16384。当output_field为*\["count(\*)"\]*时，top_k必须为负数。 **取值范围：** 小于等于16384 **默认取值：** 10 |
| offset          | 否    | Integer          | **参数解释：** 在搜索结果中跳过的记录数。可以将此参数与 top_k 参数结合使用以启用分页。 **约束限制：** 与top_k取值的总和应小于16384。 **取值范围：** 大于等于0 **默认取值:** 0                                                                       |
| filter          | 是    | String           | **参数解释：** 用于过滤匹配entity的标量过滤条件。 **约束限制：** 要构建标量过滤条件，请参阅filter表达式规则。 **取值范围：** 不涉及。 **默认取值：** 不涉及。                                                                                   |
   
#### 响应参数
**状态码：200**
表2响应Body参数 
| 参数      | 参数类型                                                           | 描述                                                                                                                                                                                                                                                                                                         |
|:---|:---|:---|
| code    | String                                                         | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 |
| message | String                                                         | **参数解释：** 描述信息 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。         |
| data    | [entities_data] object | **参数解释：** 响应数据。 **约束限制：** 不涉及。                                                                                                                                                                          |
   
 表3entities_data 
| 参数       | 参数类型                                                       | 描述                                                                                                                                  |
|:---|:---|:---|
| entities | Array of [entity] objects | **参数解释：** 查询到的信息。 **约束限制：** 不涉及。 |
   
 表4entity 
| 参数       | 参数类型                 | 描述                                                                                                                                                                                                                                                                                                                                                            |
|:---|:---|:---|
| {自定义key} | Map\<String,Object\> | **参数解释：** collection中的一个基本结构化数据实体，包含向量和标量等字段数据。 **约束限制：** 必须满足目标collection field schema。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 |
   
**状态码：400**
表5响应Body参数 
| 参数      | 参数类型   | 描述                                                                                                                                                                                                                                                                                                         |
|:---|:---|:---|
| code    | String | **参数解释：** 返回码。参见错误码章节。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。 |
| message | String | **参数解释：** 描述信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值:** 不涉及。        |
   
#### 请求示例
```
/v1/entities/query
{
  "store_name" : "test-storename",
  "collection_name" : "test-collection",
  "output_fields" : [ "pk", "vector", "scalar" ],
  "filter" : "pk > 0",
  "top_k" : 2,
  "offset" : 0
}
```
#### 响应示例
**状态码：200**
搜索成功
```
{
  "code" : "LMS.00000000",
  "data" : {
    "entities" : [ {
      "pk" : 1,
      "scalar" : "文档1",
      "vector" : [ 0.324, 0.21, 0.2456 ]
    }, {
      "pk" : 2,
      "scalar" : "文档4",
      "vector" : [ 0.333, 0.222, 0.1116 ]
    } ]
  },
  "message" : "query entities success"
}
```
**状态码：400**
搜索失败
```
{
  "code" : "LMS.00004002",
  "message" : "ErrInvalidSearchResult:Fail to parse search result"
}
```
#### 状态码
| 状态码 | 描述   |
|:---|:---|
| 200 | 搜索成功 |
| 400 | 搜索失败 |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-dwr/ErrorCode.html)。