向量数据库 queryFileDetails

该接口用于在使用 AI 套件上传文件后，获取文件的详细信息。
Method 与 URL
POST https://{实例访问 IP 地址}:{实例网络端口}/ai/document/queryFileDetails。
请求参数
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/ai/document/queryFileDetails \\
  -d '{
    "database":"db-test",
    "collection":"coll-ai-files",
    "readConsistency": "eventualConsistency",
    "query": {
      "fileNames": ["tcvdb.pdf","tcvdb.md"],
      "filter": "_indexed_status = \\"Ready\\" ",
      "limit":1,
      "offset":0
    }
  }'
参数
子参数
参数含义
是否必选
配置方法
database
﻿
指定 Database 名称。
是
使用 /database/list 获取集群中的数据库列表，复制数据库名。
collection
﻿
指定 Collection 的名称。
是
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
readConsistency
-
配置读一致性要求。
否
取值如下所示，默认为 eventualConsistency。
strongConsistency：强一致性。
eventualConsistency：最终一致性。
query
fileNames
表示要查询的文档名
是
每个 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>：表示要匹配的值。
﻿
outputFields
以数组形式配置需返回的字段。
否
说明：
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条记录开始返回数据。
响应信息
{
  "code": 0,
  "msg": "Operation success",
  "requestId": "d2fe5156f2495318e1819232f00eb0a4",
  "count": 1,
  "documents": [
    {
      "id": "tcvdb.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-********/db-test/coll-file-test-***/tcvdb.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![vdb-image](********.png)\\n\\n\\n\\n!",
      "_user_metadata": {
        "author": "Tencent",
        "tags": ["向量", "Embedding", "AI"]
      }
    }
  ]
}
参数名
子参数
﻿
参数含义
count
-
-
文件数量。
documents
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		指定 Database 名称。	是	使用 /database/list 获取集群中的数据库列表，复制数据库名。
collection		指定 Collection 的名称。	是	Collection 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
readConsistency	-	配置读一致性要求。	否	取值如下所示，默认为 eventualConsistency。 strongConsistency：强一致性。 eventualConsistency：最终一致性。
query	fileNames	表示要查询的文档名	是	每个 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>：表示要匹配的值。
		outputFields	以数组形式配置需返回的字段。	否	说明： 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条记录开始返回数据。

参数名	子参数		参数含义
count	-	-	文件数量。
documents	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 元数据信息。

queryFileDetails

本页目录：

Method 与 URL

请求参数

响应信息