向量数据库查询文件详情

接口定义
query_file_details() 接口用于获取文件的详细信息。
def query_file_details(self,
                       database_name: str,
                       collection_name: str,
                       file_names: List[str] = None,
                       filter: Union[Filter, str] = None,
                       output_fields: Optional[List[str]] = None,
                       limit: Optional[int] = None,
                       offset: Optional[int] = None,
                       ) -> List[Dict]:
使用示例
说明：
如果需要进行腾讯云向量数据库的测试，请获取 腾讯云向量数据库.pdf 文档。
import json
import tcvectordb
res = client.query_file_details(
    database_name='db-test',
    collection_name='coll-file-test',
    file_names=['腾讯云向量数据库.pdf'],
    limit=2,
)
print(f'file_details={json.dumps(res, ensure_ascii=False)}')
入参描述
参数名
参数含义
是否必选
配置方法
database_name
指定 Database 名称。
是
使用 /database/list 获取集群中的数据库列表，复制数据库名。
collection_name
指定 Collection 的名称。
是
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
file_names
表示要查询的文档名
是
每个 ID 长度限制为[1,128]。支持批量查询，数组元素范围[1,20]。
文件上传成功之后，可使用 query 查询文件的 ID 信息。
filter
使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。
否
Filter 的表达式格式为 '<field_name><operator><value>'，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见 Filter 条件表达式。其中 
<field_name>：表示要过滤的字段名。
<operator>：表示要使用的运算符。
string：匹配单个字符串值（=）、排除单个字符串值（!=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。
uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如，exipred_time > 1623388524。
array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。
json：json 类型的 Filter 表达式语法和 json 字段的键值类型保持一致。若访问 Json 对象中的键，使用点（.）符号连接。例如：Json 类型的字段 bookInfo ，其键 bookName 的 Filter 表达式如下所示。更多信息，请参见 Json 类型表达式。
"filter": "bookInfo.bookName in (\\"三国演义\\",\\"西游记\\")"
<value>：表示要匹配的值。
output_fields
以数组形式配置需返回的字段。
否
说明：
outputFields 与 retrieveVector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
输出 Json 字段时，outputFields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，outputFields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。
limit
每页返回的 Document 数量。默认为1。
否
数据类型：uint 64。
取值范围：[1,16384]
注意：
若使用 query 检索数据时，不配置 documentIds 和 filter 参数，则必须配置 offeset 和 limit 参数，返回从 offset 开始的 limit 条数据，避免遍历所有数据而浪费不必要的资源。
offset
设置分页偏移量，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览。
否
取值：为 limit 整数倍。
计算公式：offset = limit * (page-1)。
例如：当 limit = 10，page = 2 时，分页偏移量 offset = 10 * (2 - 1) = 10，表示从查询结果的第11条记录开始返回数据。
出参描述
{
  "file_details": [
    {
      "id": "腾讯云向量数据库.pdf",
      "_append_keywords_to_chunk": true,
      "_append_titles_to_chunk": false,
      "_column_map": {
        "chunkNum": "chunk_num",
        "filename": "file_name",
        "imageList": "image_list",
        "sectionNum": "section_num",
        "text": "text"
      },
      "_context_hash_data": 10564368669172951642,
      "_cos_address": "vectordb-pre-gz-**********/embedding_file/vdb-oegil4o8/db-test/coll-file-test-292/腾讯云向量数据库.pdf",
      "_create_time": "2025-07-18 15:40:04",
      "_embedding_model": "bge-base-zh",
      "_file_keywords": "向量 腾讯 数据库 数据 服务 结构化 公司 版权所有 计算 北京",
      "_file_size": 1925502,
      "_file_type": "pdf",
      "_indexed": 100,
      "_indexed_status": "Ready",
      "_last_update_time": "2025-07-18 15:40:47",
      "_parsing_type": "VisionModelParsing",
      "_text_length": 11945,
      "_text_prefix": "![vdb-image](************.png)\\n\\n![vdb-image](*******.png)\\n\\n## 版权所有：腾讯云计算（北京）有限责任公司\\n\\n![vdb-image](**********.png)\\n\\n\\n\\n![vdb",
      "_user_metadata": {
        "author": "Tencent",
        "tags": [
          "向量",
          "Embedding",
          "AI"
        ]
      }
    }
  ]
}
参数
子参数
参数含义
id
-
文件名。
_append_keywords_to_chunk
-
在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示：
false：不追加。
true：将全文的 keywords 追加到切分后的段落。默认值为 true。
_append_titles_to_chunk
-
在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示：
false：不追加。默认值为 false。
true：将段落 Title 追加到切分后的段落。
_column_map
chunkNum
数据库中存放文件切分语块序号的字段。
﻿
filename
文件名映射的字段。
﻿
imageList
图片信息存放的字段。
﻿
sectionNum
指定数据库中用于存储文件段落序号的字段名。
﻿
text
指定文件内容文本映射的字段，存储知识点的原始文本内容。
_context_hash_data
-
文档内容哈希值。
_cos_address
-
文件 COS 存储路径。
_create_time
-
文件上传在数据库的时间
_embedding_model
-
指定使用的 Embedding 模型的名称。您需根据业务的语言类型、数据维度要求等综合选择合适的模型。具体信息，参见 Embedding 介绍。取值如下所示：
bge-large-zh-v1.5：适用中文，1024维，推荐使用。
bge-base-zh-v1.5：适用中文，768维。
bge-large-zh：适用中文，1024维。
bge-base-zh：适用中文，768维。
m3e-base：适用中文，768维。
e5-large-v2：适用英文，1024维。
text2vec-large-chinese：适用中文，1024维。
multilingual-e5-base：适用于多种语言类型，768维。
BAAI/bge-m3：适用于多种语言类型，1024维。
_file_keywords
-
文件关键字。
_file_size
-
文件大小。
_file_type
-
文件类型。
_indexed
-
文档的解析进度。
_indexed_status
-
索引状态。
_last_update_time
-
文件最后更新的时间。
_parsing_type
-
指定 PDF 类型文件的解析方式，取值如下所示：
VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。
AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。
_text_length
-
文本的长度。
_text_prefix
-
预处理后提取的起始部分文本内容。
_user_metadata
-
文件的 Metadata 元数据信息。

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

参数	子参数	参数含义
id	-	文件名。
_append_keywords_to_chunk	-	在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示： false：不追加。 true：将全文的 keywords 追加到切分后的段落。默认值为 true。
_append_titles_to_chunk	-	在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示： false：不追加。默认值为 false。 true：将段落 Title 追加到切分后的段落。
_column_map	chunkNum	数据库中存放文件切分语块序号的字段。
		filename	文件名映射的字段。
		imageList	图片信息存放的字段。
		sectionNum	指定数据库中用于存储文件段落序号的字段名。
		text	指定文件内容文本映射的字段，存储知识点的原始文本内容。
_context_hash_data	-	文档内容哈希值。
_cos_address	-	文件 COS 存储路径。
_create_time	-	文件上传在数据库的时间
_embedding_model	-	指定使用的 Embedding 模型的名称。您需根据业务的语言类型、数据维度要求等综合选择合适的模型。具体信息，参见 Embedding 介绍。取值如下所示： bge-large-zh-v1.5：适用中文，1024维，推荐使用。 bge-base-zh-v1.5：适用中文，768维。 bge-large-zh：适用中文，1024维。 bge-base-zh：适用中文，768维。 m3e-base：适用中文，768维。 e5-large-v2：适用英文，1024维。 text2vec-large-chinese：适用中文，1024维。 multilingual-e5-base：适用于多种语言类型，768维。 BAAI/bge-m3：适用于多种语言类型，1024维。
_file_keywords	-	文件关键字。
_file_size	-	文件大小。
_file_type	-	文件类型。
_indexed	-	文档的解析进度。
_indexed_status	-	索引状态。
_last_update_time	-	文件最后更新的时间。
_parsing_type	-	指定 PDF 类型文件的解析方式，取值如下所示： VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。 AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。
_text_length	-	文本的长度。
_text_prefix	-	预处理后提取的起始部分文本内容。
_user_metadata	-	文件的 Metadata 元数据信息。

查询文件详情

本页目录：

接口定义

使用示例

入参描述

出参描述