AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 人工智能平台 PAI 开发参考 API参考 PAI-AI WorkSpace API目录 数据集 多模态检索 ListDatasetFileMetas - 获取数据集文件元数据列表

ListDatasetFileMetas - 获取数据集文件元数据列表

更新时间：
产品详情
我的收藏

查询数据集文件列表。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

paidataset:ListDatasetFileMetas

list

*全部资源

*

 无 无

请求语法

GET /api/v1/datasets/{DatasetId}/datasetfilemetas HTTP/1.1

路径参数

名称

类型

必填

描述

示例值
DatasetId

string

是

数据集 ID。如何获取数据集 ID，详情请参见 ListDatasets 。

d-rbvg5*****jhc9ks92

请求参数

名称

类型

必填

描述

示例值
DatasetVersion

string

是

数据集版本名。

v1
WorkspaceId

string

是

数据集所在工作空间 ID。如何获取工作空间 ID，请参见 ListWorkspaces 。

105173
QueryType

string

否

检索类型。

  • MIX：混合检索（默认值）。

  • TAG：仅标签检索。

  • VECTOR：仅向量检索。

枚举值：

  • TAG :

    TAG

  • MIX :

    MIX

  • VECTOR :

    VECTOR

MIX
QueryText

string

否

待搜索文本内容。

A fallen water
TopK

integer

否

检索结果返回数量，最多只返回 TopK 个检索结果。

说明

当 QueryType=VECTOR 或 MIX 时有效。

100
ScoreThreshold

number

否

相似度分数过滤。只返回大于 ScoreThreshold 的结果。

说明

当 QueryType=VECTOR 或 MIX 时有效。

0.6
PageSize deprecated

integer

否

每页数量。如果同时传入 MaxResults，则以 MaxResults 数量为准。

说明

该参数即将下线，推荐您使用 NextToken 与 MaxResults 完成分页查询操作。

10
NextToken

string

否

分页游标标识。

说明

如果不设置该参数，则表示获取第一页的数据。当该参数有返回值时，说明还有下一页，您可以将返回的 NextToken 作为参数再次请求获得下一页的数据，直到返回为 Null 为止，表示获取到了所有的数据。

90a6ee35-****-4cd4-927e-1f45e1cb8b62_1729644433000
SortBy

string

否

分页查询时的排序字段，缺省时按检索时相关性由高到低排序。其他取值如下。

  • FileCreateTime：按文件创建时间。

  • FileUpdateTime：按文件最后修改时间。

枚举值：

  • FileCreateTime :

    FileCreateTime

  • FileUpdateTime :

    FileUpdateTime

FileCreateTime
Order

string

否

分页查询时，对指定的排序字段进行升序或降序，与 SortBy 结合使用。默认 DESC。

  • ASC：升序。

  • DESC：降序。

枚举值：

  • ASC :

    ASC

  • DESC :

    DESC

DESC
EndFileUpdateTime

string

否

用于指定查询的起始文件更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

StartFileUpdateTime

string

否

用于指定查询的结束文件更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

QueryImage

string

否

以图搜图时，该参数传入图片的信息。

  • 支持传入图片的可公网访问的 oss url 格式。格式为：oss://{bucket_name}/{object_path}。其中 bucket_name 为 bucket 名称，object_path 为文件在 bucket 中的路径。

说明

当 QueryType=VECTOR 或 MIX 时有效。

oss://test-xxx-oss/car/0001.png
ThumbnailMode

string

否

图片缩略图的模式，当前仅 OSS 文件支持缩略图：

  • 等比例缩小: p_{percentage}, percentage 表示期望的缩放比例，取值范围为[1, 100] 。示例：p_50 表示使用原始文件的 50%大小作为缩略图。

  • 宽度固定，高度自适应缩小: w_{width}, width 表示期望的图片宽度，取值范围为[1, 16384]。示例：w_200 表示将图片宽度固定为 200 像素，高度自适应进行缩小。

  • 高度固定，宽度自适应缩小：h_{height}, height 表示期望的图片高度，取值范围为[1, 16384]。示例：h_100 表示将图片高度固定为 100 像素，宽度自适应进行缩小。

  • 固定宽高，缩略填充：m_pad,w_{height},h_{height},color_{RGB}, m_pad 表示图片缩放为指定 w 与 h 的矩形内的最大图片，RGB 表示指定居中填充空白部分的颜色，若不设置该参数，默认用白色填充。width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]。示例:

  • 固定宽高，居中裁剪：m_fill,w_{width},h_{height}。m_fill 表示图片等比缩放为延伸出指定 w 与 h 的矩形框外的最小图片，超出的部分进行居中裁剪。width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]示例：m_fill,w_100,h_100 表示将图片宽度和高度都固定为 100 像素进行居中裁剪缩放。

  • 强制宽高缩放: m_fixed,w_{height},h_{height}，width 表示期望的图片宽度，height 表示期望的图片高度。width 和 height 的取值范围都为[1,16384]。示例：m_fixed,w_100,h_100 表示将图片宽度和高度都固定为 100 像素进行强制宽高缩放。

w_100
QueryTagsIncludeAll

array

否

表示“同时包含以下标签”检索条件。用户可以选择多个标签，查询结果必须同时满足这些标签。如果为空，则不应用此条件。数组使用逗号分隔。

说明

当 QueryType=TAG 或 MIX 时有效。当 QueryType=TAG 时会将 QueryText 加入到该条件下。

string

否

标签名。

Lane line
QueryTagsIncludeAny

array

否

表示“包含以下任意标签”检索条件。 用户可以选择多个标签，查询结果只需满足其中一个即可。 如果为空，则不应用此条件。数组使用逗号分隔。

说明

当 QueryType=TAG 或 MIX 时有效。

string

否

标签名。

Lane line
QueryTagsExclude

array

否

表示“排除以下标签”检索条件。用户可以选择多个标签，查询结果中不能包含这些标签。如果为空，则不应用此条件。

说明

当 QueryType=TAG 或 MIX 时有效。

string

否

标签名。

Lane line
QueryFileName

string

否

文件名检索条件。支持模糊检索。

car
QueryFileDir

string

否

文件目录检索条件。支持模糊检索。

cars/20250221/
QueryFileTypeIncludeAny

array

否

表示“包含以下任意文件类型”检索条件。用户可以选择多个文件类型，查询结果只需满足其中一个即可。如果为空，则不应用此条件。数组使用逗号分隔。

string

否

文件类型。

image
QueryContentTypeIncludeAny

array

否

表示“包含以下任意文件内容类型”检索条件。用户可以选择多个文件内容类型，查询结果只需满足其中一个即可。如果为空，则不应用此条件。数组使用逗号分隔。

string

否

文件内容类型。

image/jpeg
StartTagUpdateTime

string

否

用于指定查询的起始标签最后更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

EndTagUpdateTime

string

否

用于指定查询的结束标签最后更新时间。ISO 8601 格式的 UTC 时间戳。

2025-01-12T14:36:01.000Z

MaxResults

integer

否

使用 NextToken 方式查询时，每次最多返回的结果数。取值范围：1~100。默认值：10。

10
QueryExpression

string

否

查询语句（DSL）是一种用于表达复杂检索条件的领域特定语言。它支持分组、布尔逻辑（AND/OR/NOT）、范围比较（>, >=, <, <=）、属性存在性（HAS/NOT HAS）、分词匹配（:）与精确匹配（=）等，适用于高级检索场景。 一般用于较为复杂的高级检索条件。

重要 为避免冲突，设置该查询语句后，建议不要与其他查询参数混用

(FileUpdateTime > '2025-02-28T00:00:00Z' AND FileUpdateTime < '2025-05-30T09:27:29Z') AND FileDir:'blue_car' AND NOT FileName="toyota.jpg" AND (( Tags.all='lane line' AND Tags.all='barrier gate') OR NOT Tags.user='rainy days' ) AND HAS SemanticIndexJobId AND Content:'a fallen water horse' AND TopK=100 AND SignMode='PUBLIC'

DSL 查询语法说明：

keyword说明范例
:分词匹配FileName:'车道线'
查找文件名分词后包含“车道线”的数据
NOT :分词不匹配NOT FileName : '车道线'
查找文件名分词后不包含“车道线”的数据
=精确值匹配FileType='image'
查找文件类型为“image”的数据（精确匹配）
NOT =精确值排除NOT FileType = 'video'
查找所有 FileType 不等于"video"的数据
HAS存在HAS SemanticIndexJobId
查找所有存在 SemanticIndexJobId 属性的数据
NOT HAS不存在NOT HAS SemanticIndexJobId
查找所有不存在 SemanticIndexJobId 属性的数据
""对值的字符串类型进行包裹单双引号效果一致
()分组操作(FileName:'black' AND ContentType='image/jpeg') OR (FileName:'white' AND ContentType='image/png')
查找 FileName 为模糊匹配 black 并且 ContentType 为 image/jpeg 或者 FileName 为模糊匹配 white 并且 ContentType 为 image/png
>范围查询：
大于		FileUpdateTime> '2025-01-16T11:52:56.000Z' AND DataSize >= 12345
文件最后修改时间在 2025-01-16T11:52:56.000Z 之后的并且文件大小大于等于 12345 字节
>=范围查询：
大于等于		同上
<范围查询：
小于		FileUpdateTime < '2025-01-16T11:52:56.000Z' AND DataSize <= 12345
文件最后修改时间在 2025-01-16T11:52:56.000Z 之前并且文件大小小于等于 12345 字节
<=范围查询：
小于等于		同上
AND并且
大小写都支持		FileType='image' AND ContentType:'image/png'
查找文件类型为 image 且文件格式为 png 的图片
OR或者
大小写都支持		FileType='image' OR FileType='video'
查找文件类型为 image 或 video 的数据

属性支持列表

支持文件基础元数据属性、标签属性、向量检索属性、通用检索属性. 所有属性在查询条件中都必须是非必选的。

类型的说明：

  • KEYWORD：仅支持等于、不等于、存在、不存在中的一种或多种

  • TEXT：仅支持分词包含、分词不包含、等于、不等于、存在、不存在中的一种或多种

  • NUMBER：仅支持范围查询、等于、存在、不存在中的一种或多种

  • DATE：仅支持范围查询、存在、不存在中的一种或多种

基础元数据属性

属性名内部类型分词包含分词不包含等于不等于存在/不存在范围查询AND 逻辑OR 逻辑
DatasetFileMetaIdKEYWORD--✅✅✅-✅✅
FileNameTEXT✅✅✅✅✅-✅✅
FileDirTEXT✅✅✅✅✅-✅✅
FileTypeKEYWORD--✅✅✅-✅✅
ContentTypeKEYWORD--✅✅✅-✅✅
DataSizeNUMBER--✅-✅✅✅✅
SemanticIndexUpdateTimeKEYWORD--✅✅✅-✅✅
FileUpdateTimeDATE----✅✅✅✅
SyncTimeDATE----✅✅✅✅
TagUpdateTimeDATE----✅✅✅✅
SemanticIndexUpdateTimeDATE----✅✅✅✅

标签属性

属性名内部类型分词包含分词不包含等于不等于存在/不存在范围查询AND 逻辑OR 逻辑
Tags.aiKEYWORD--✅✅✅-✅✅
Tags.userKEYWORD--✅✅✅-✅✅
Tags.allKEYWORD--✅✅✅-✅✅

向量查询属性

属性名内部类型分词包含分词不包含等于不等于存在/不存在范围查询AND 逻辑OR 逻辑
ContentTEXT✅-❌❌❌-✅❌
TopKNUMBER--✅-❌❌✅❌
ScoreThresholdNUMBER--✅-❌❌✅❌

通用查询属性

属性名内部类型分词包含分词不包含等于不等于存在/不存在范围查询AND 逻辑OR 逻辑
QueryTypeKEYWORD--✅❌❌-✅❌
SignModeKEYWORD--✅❌❌-✅❌
ThumbnailModeKEYWORD--✅❌❌-✅❌
SortByKEYWORD--✅❌❌-✅❌
OrderKEYWORD--✅❌❌-✅❌
NextTokenKEYWORD--✅❌❌-✅❌
MaxResultsNUMBER--✅-❌❌✅❌

返回参数

名称

类型

描述

示例值

object

请求结果。

TotalCount

integer

返回数据总条数

123
PageSize deprecated

integer

当前页大小。

30
NextToken

string

分页游标的标识。如果匹配查询条件的返回结果超过了分页大小，则会返回这个分页游标。如果需要获取下一页数据，将返回的游标值作为请求参数即可，直到无游标值返回，表示已经获取了全部数据。

90******-f5c5-4cd4-927e-1f45e1cb8b62_1729644433000
DatasetFileMetas

array

数据集文件元数据详情列表。

DatasetFileMeta

数据集文件元数据详情。

DatasetId

string

数据集 ID。

d-rbvg5*****jhc9ks92

WorkspaceId

string

工作空间 ID。

105173
DatasetVersion

string

数据集版本名。

v1
MaxResults

integer

使用 NextToken 方式查询时，每次最多返回的结果数。

10

示例

正常返回示例

JSON格式

{
  "TotalCount": 123,
  "PageSize": 30,
  "NextToken": "90******-f5c5-4cd4-927e-1f45e1cb8b62_1729644433000",
  "DatasetFileMetas": [
    {
      "DatasetFileMetaId": "07914c9534586e4e7aa6e9dbca5009082df******fd8a0d857b33296c59bf6",
      "Uri": "oss://test-bucket/dataset/cat.png",
      "FileName": "cat.png",
      "DownloadUrl": "https://test-bucket.oss-cn-shanghai.aliyuncs.com/dataset/cat.png?Expires=171280****&OSSAccessKeyId=LTAI************&Signature=****jZcXOn7FHMCT1DLE22NuNjs%3D",
      "Score": 0.6,
      "DataSize": 120000,
      "FileFingerPrint": "D41D8CD98F*****E9800998ECF8\n",
      "FileUpdateTime": "2025-01-12T14:36:01Z",
      "Tags": "{\n    \"ai\":\n    [\n        \"Lane line\",\n        \"Water horse\",\n        \"Sunny day\"\n    ],\n    \"user\":\n    [\n        \"Everett\",\n        \"Intelligent driving Dataset 1\",\n        \"Cloudy day\"\n    ],\n    \"user-delete-ai-tags\":\n    [\n        \"Sunny day\"\n    ]\n}",
      "ThumbnailUrl": "https://test-bucket.oss-cn-shanghai.aliyuncs.com/dataset/cat.png?Expires=171280****&OSSAccessKeyId=LTAI************&Signature=****jZcXOn7FHMCT1DLE22NuNjs%3D",
      "MetaAttributes": "{     \"ImageHeight\": 400,     \"ImageWidth\": 800 }",
      "SyncTime": "2021-01-12T14:36:01.000Z",
      "TagUpdateTime": "2021-01-12T14:36:01.000Z",
      "SemanticIndexJobId": "dsjob-klfwtjto****scvt3",
      "SemanticIndexUpdateTime": "2021-01-12T14:36:01.000Z",
      "FileCreateTime": "2021-01-12T14:36:01.000Z",
      "FileType": "image",
      "ContentType": "image/jpeg"
    }
  ],
  "DatasetId": "d-rbvg5*****jhc9ks92\n",
  "WorkspaceId": "105173",
  "DatasetVersion": "v1",
  "MaxResults": 10
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。

上一篇：ListDatasetJobConfigs - 获取数据集任务配置列表下一篇：GetDatasetJobConfig - 获取数据集任务配置