向量数据库精确查询

接口定义
query() 用于精确查找与查询条件完全匹配的数据。
def query(
    document_ids: List | None = None,
    retrieve_vector: bool = False,
    limit: int | None = None,
    offset: int | None = None,
    filter: Filter | str = None,
    output_fields: List[str] | None = None,
    timeout: float | None = None,
    sort: dict | None = None
) -> List[Dict]
使用示例
说明：
支持根据主键 id（Document ID），搭配自定义的标量字段的 Filter 表达式一并查询数据。
支持指定查询起始位置 offset 和返回数量 limit，精确检索查询区间内的数据，实现数据 SCAN 能力。
import tcvectordb
from tcvectordb.model.document import Filter, SearchParams
﻿
# 设置标量字段的 Filter 表达式，便于过滤需查询的数据，支持直接以字符串的形式赋值
# filter_param=Filter(Filter.In("bookName",["三国演义", "西游记"])).And(Filter.Include("tags",["曹操", "诸葛亮"]))
filter_param='bookName in ("三国演义","西游记") and (tags include ("曹操","诸葛亮"))'
# 调用接口 query() 查询数据
doc_list = client.query(
            database_name='db-test',
            collection_name='book-vector',
            document_ids=['0001','0002','0003'],
            retrieve_vector=True,
            filter=filter_param,
            limit=3,
            offset=0,
            output_fields=['bookName','author','page']
)
for doc in doc_list:
    print(doc)
入参描述
参数
是否必选
参数含义
参数配置
database_name
是
指定检索的数据库名。
Database 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
collection_name
是
指定检索的集合名
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
documentIds
否
表示要查询的文档的所有 ID。
每个 ID 长度限制为[1,128]。支持批量查询，数组元素范围[1,20]。
retrieve_vector
否
标识是否需要返回检索结果的向量值。
取值如下：
True：需要。
False：不需要。默认为 False。
filter
否
使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。
Filter 的表达式格式为 '<field_name><operator><value>'，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见 Filter 条件表达式。其中 
<field_name>：表示要过滤的字段名。
<operator>：表示要使用的运算符。
string：匹配单个字符串值（=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。
uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如，expired _time >  1623388524。
array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。
json：json 类型的 Filter 表达式语法和 json 字段的键值类型保持一致。若访问 Json 对象中的键，使用点（.）符号连接。例如：Json 类型的字段 bookInfo ，其键 bookName 的 Filter 表达式如下所示。更多信息，请参见 Json 类型表达式。
filter_param='bookInfo.bookName in ("三国演义","西游记")'
<value>：表示要匹配的值。
limit
是
每页返回的 Document 数量。
﻿
﻿
每页返回的 Document 数量。默认为10。
数据类型：uint 64
取值范围：[1,16384]
注意：
若使用 query 检索数据时，不配置 documentIds 和 filter 参数，则必须配置 offset 和 limit 参数，返回从 offset 开始的 limit 条数据，避免遍历所有数据而浪费不必要的资源。
offset
否
设置分页偏移量，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览。
取值要求如下：
取值：为 limit 整数倍。
计算公式：offset = limit * (page-1)。
例如：当 limit = 10，page = 2 时，分页偏移量 offset = 10 * (2 - 1) = 10，表示从查询结果的第11条记录开始返回数据。
output_fields
否
配置需返回的字段。
以数组形式配置需返回的字段。若不配置，返回所有字段。
说明：
output_fields 与 retrieve_vector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
输出 Json 字段时，output_fields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，output_fields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。
sort
否
指定查询结果按照特定字段升序或降序排序。
数据类型为数组。
sort={
    'fieldName': 'page',
    'direction': 'desc'
},
fieldName：指定特定字段，查询结果将依据该字段确定输出顺序。当前排序字段仅支持 uint64 的类型，且该字段为标量字段索引，可通过接口 describe_collection() 确认该字段是否为索引字段。
说明：
当满足条件的数据量小于或等于1000时，orderby 操作将正常生效，否则会引发错误。
目前仅支持对单个字段进行排序，暂时不支持多字段排序功能。
direction：指定排序的方向。
desc：降序排序。
asc：升序排序。
timeout
否
请求超时时间。
单位：秒。
默认值：VectorDBClient() 接口配置的 timeout 时长。
取值范围：大于等于0。
出参描述
检索结果，如下所示。
{'id': '0001', 'score': 0.0, 'vector': [0.21230000257492065, 0.23000000417232513, 0.21299999952316284], 'sparse_vector': [[2, 0.9599999785423279], [5, 0.5299999713897705], [100, 0.4429999887943268]], 'page': 21, 'author': '罗贯中', 'bookName': '三国演义'}
参数名
参数含义
id
Document 的 ID 信息。
vector
Document 的向量值。
author、page、section
Document 自定义扩展的标量字段。

参数	是否必选	参数含义	参数配置
database_name	是	指定检索的数据库名。	Database 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
collection_name	是	指定检索的集合名	Collection 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
documentIds	否	表示要查询的文档的所有 ID。	每个 ID 长度限制为[1,128]。支持批量查询，数组元素范围[1,20]。
retrieve_vector	否	标识是否需要返回检索结果的向量值。	取值如下： True：需要。 False：不需要。默认为 False。
filter	否	使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。	Filter 的表达式格式为 '<field_name><operator><value>'，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见 Filter 条件表达式。其中 <field_name>：表示要过滤的字段名。 <operator>：表示要使用的运算符。 string：匹配单个字符串值（=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。 uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如，expired _time > 1623388524。 array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。 json：json 类型的 Filter 表达式语法和 json 字段的键值类型保持一致。若访问 Json 对象中的键，使用点（.）符号连接。例如：Json 类型的字段 bookInfo ，其键 bookName 的 Filter 表达式如下所示。更多信息，请参见 Json 类型表达式。 filter_param='bookInfo.bookName in ("三国演义","西游记")' <value>：表示要匹配的值。
limit	是	每页返回的 Document 数量。	每页返回的 Document 数量。默认为10。数据类型：uint 64 取值范围：[1,16384] 注意：若使用 query 检索数据时，不配置 documentIds 和 filter 参数，则必须配置 offset 和 limit 参数，返回从 offset 开始的 limit 条数据，避免遍历所有数据而浪费不必要的资源。
offset	否	设置分页偏移量，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览。	取值要求如下：取值：为 limit 整数倍。计算公式：offset = limit * (page-1)。例如：当 limit = 10，page = 2 时，分页偏移量 offset = 10 * (2 - 1) = 10，表示从查询结果的第11条记录开始返回数据。
output_fields	否	配置需返回的字段。	以数组形式配置需返回的字段。若不配置，返回所有字段。说明： output_fields 与 retrieve_vector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。输出 Json 字段时，output_fields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入`"a": {"b": "test", "c": 12}`，output_fields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。
sort	否	指定查询结果按照特定字段升序或降序排序。	数据类型为数组。 sort={ 'fieldName': 'page', 'direction': 'desc' }, fieldName：指定特定字段，查询结果将依据该字段确定输出顺序。当前排序字段仅支持 uint64 的类型，且该字段为标量字段索引，可通过接口 describe_collection() 确认该字段是否为索引字段。说明：当满足条件的数据量小于或等于1000时，orderby 操作将正常生效，否则会引发错误。目前仅支持对单个字段进行排序，暂时不支持多字段排序功能。 direction：指定排序的方向。 desc：降序排序。 asc：升序排序。
timeout	否	请求超时时间。	单位：秒。默认值：VectorDBClient() 接口配置的 timeout 时长。取值范围：大于等于0。

参数名	参数含义
id	Document 的 ID 信息。
vector	Document 的向量值。
author、page、section	Document 自定义扩展的标量字段。

精确查询

本页目录：

接口定义

使用示例

入参描述

出参描述