接口定义
query() 用于精确查找与查询条件完全匹配的数据。
def query(self,database_name: str,collection_name: str,document_ids: Optional[List] = None,retrieve_vector: bool = False,limit: Optional[int] = None,offset: Optional[int] = None,filter: Union[Filter, str] = None,output_fields: Optional[List[str]] = None,timeout: Optional[float] = None,) -> List[Dict]
使用实例
说明:
支持根据主键 id(Document ID),搭配自定义的标量字段的 Filter 表达式一并查询数据。
支持指定查询起始位置 offset 和返回数量 limit,精确检索查询区间内的数据,实现数据 SCAN 能力。
import tcvectordbfrom tcvectordb.model.document import FilterSearchParams# 设置标量字段的 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-10',document_ids=['0001','0002','0003'], retrieve_vector=True, filter=filter_param, limit=3, offset=0, output_fields=['bookName','author'])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 必须使用英文双引号括起来。 unit64:大于(>)、大于等于(>=)、等于(=)、小于(<)、小于等于(<=)。例如,expired _time > 1623388524。 array:数组类型,包含数组元素之一(include)、排除数组元素之一(exclude)、全包含数组元素(include all)。例如,name include (\\"Bob\\", \\"Jack\\")。 <value>:表示要匹配的值。 示例: Filter('author="jerry"').And('page>20')。 |
limit | 是 | 每页返回的 Document 数量。 | 每页返回的 Document 数量。默认为 1。 数据类型: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 参数均可以配置是否输出向量值,二者任意一个配置需输出向量字段,则将输出向量字段。 |
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]], 'author': '罗贯中', 'bookName': '三国演义'}
参数名 | 参数含义 |
id | Document 的 ID 信息。 |
vector | Document 的向量值。 |
author、page、section | Document 自定义扩展的标量字段。 |