All Products
Search
Document Center

Platform For AI:ListDatasetFileMetas

Last Updated:Jan 26, 2026

Queries the files in a dataset.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

paidataset:ListDatasetFileMetas

list

*All Resource

*

None None

Request syntax

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

Path Parameters

Parameter

Type

Required

Description

Example

DatasetId

string

Yes

The dataset ID. For more information, see ListDatasets.

d-rbvg5*****jhc9ks92

Request parameters

Parameter

Type

Required

Description

Example

DatasetVersion

string

Yes

The version name of the dataset.

v1

WorkspaceId

string

Yes

The ID of the workspace where the dataset is located. For more information, see ListWorkspaces.

105173

QueryType

string

No

The search type. Valid values:

  • MIX: Mixed search. This is the default value.

  • TAG: Searches by tag only.

  • VECTOR: Searches by vector only.

Valid values:

  • TAG :

    TAG

  • MIX :

    MIX

  • VECTOR :

    VECTOR

MIX

QueryText

string

No

The text to search for.

A fallen water

TopK

integer

No

The maximum number of search results to return.

Note

This parameter is valid only when `QueryType` is set to `VECTOR` or `MIX`.

100

ScoreThreshold

number

No

The similarity score threshold. Only results with a score greater than this threshold are returned.

Note

This parameter is valid only when `QueryType` is set to `VECTOR` or `MIX`.

0.6

PageSize deprecated

integer

No

The number of entries per page. If you also specify `MaxResults`, the value of `MaxResults` takes precedence.

Note

This parameter is deprecated. Use `NextToken` and `MaxResults` for paginated queries.

10

NextToken

string

No

The pagination token.

Note

If you do not specify this parameter, the first page of results is returned. If a value is returned for this parameter, more results are available. To get the next page, use the returned token in your next request. Repeat this process until no token is returned, which indicates that all results have been retrieved.

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

SortBy

string

No

The field to sort by for paginated queries. If you do not specify this parameter, results are sorted by relevance from high to low. Other valid values are as follows:

  • FileCreateTime: Sort by file creation time.

  • FileUpdateTime: Sort by file last modified time.

Valid values:

  • FileCreateTime :

    FileCreateTime

  • FileUpdateTime :

    FileUpdateTime

FileCreateTime

Order

string

No

The sort order for the specified field in a paginated query. Use this parameter with `SortBy`. The default value is `DESC`. Valid values:

  • ASC: Ascending.

  • DESC: Descending.

Valid values:

  • ASC :

    ASC

  • DESC :

    DESC

DESC

EndFileUpdateTime

string

No

The start time for the query that filters files by update time. The time must be a UTC timestamp in ISO 8601 format.

2025-01-12T14:36:01.000Z

StartFileUpdateTime

string

No

The end of the time range for a query based on file update time. The value is a UTC timestamp in ISO 8601 format.

2025-01-12T14:36:01.000Z

QueryImage

string

No

The image information to use for an image-based search.

  • Specify the public URL of an image in an OSS bucket. The format is `oss://{bucket_name}/{object_path}`. `bucket_name` is the name of the bucket, and `object_path` is the path of the file in the bucket.

Note

This parameter is valid only when `QueryType` is set to `VECTOR` or `MIX`.

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

ThumbnailMode

string

No

The mode for generating image thumbnails. Thumbnails are supported only for files in OSS.

  • Proportional scaling: `p_{percentage}`. The `percentage` parameter specifies the scaling ratio. Valid values: 1 to 100. For example, `p_50` scales the image to 50% of its original size.

  • Fixed width, adaptive height: `w_{width}`. The `width` parameter specifies the image width. Valid values: 1 to 16,384. For example, `w_200` sets the image width to 200 pixels and scales the height adaptively.

  • Fixed height, adaptive width: `h_{height}`. The `height` parameter specifies the image height. Valid values: 1 to 16,384. For example, `h_100` sets the image height to 100 pixels and scales the width adaptively.

  • Fixed width and height with padding: `m_pad,w_{width},h_{height},color_{RGB}`. The `m_pad` parameter scales the image to the maximum size that fits within a rectangle of the specified width and height. The `RGB` parameter specifies the color for the centered padding in the empty areas. If you do not specify this parameter, the empty areas are filled with white by default. The `width` and `height` parameters specify the image width and height. The values for both `width` and `height` must be between 1 and 16,384.

  • Fixed width and height with center crop: `m_fill,w_{width},h_{height}`. The `m_fill` parameter proportionally scales the image to the minimum size that covers the specified width and height, and then crops the excess from the center. The `width` and `height` parameters specify the image width and height. The values for both `width` and `height` must be between 1 and 16,384. For example, `m_fill,w_100,h_100` scales and crops the image to 100 × 100 pixels from the center.

  • Forced width and height scaling: `m_fixed,w_{width},h_{height}`. The `width` and `height` parameters specify the image width and height. The values for both `width` and `height` must be between 1 and 16,384. For example, `m_fixed,w_100,h_100` forces the image to be scaled to 100 × 100 pixels.

w_100

QueryTagsIncludeAll

array

No

The metadata IDs to query.

string

No

The metadata ID.

Lane line

QueryTagsIncludeAny

array

No

A condition that retrieves items that have all of the specified tags. The tags are specified as a comma-separated array. This condition is not applied if the parameter is empty.

Note

This parameter takes effect only when QueryType is set to TAG or MIX. If QueryType is set to TAG, the value of QueryText is also added to this condition.

string

No

The tag name.

Lane line

QueryTagsExclude

array

No

A comma-separated list of tags. The query returns files that match at least one of the specified tags. If you do not specify this parameter, this filter is ignored.

Note

This parameter is valid only when QueryType is set to TAG or MIX.

string

No

The tag name.

Lane line

QueryFileName

string

No

The tags to exclude from the query results. If you do not specify any tags, this filter is not applied.

Note

This parameter is valid only when QueryType is set to TAG or MIX.

car

QueryFileDir

string

No

The name of the file to retrieve. This parameter supports fuzzy search.

cars/20250221/

QueryFileTypeIncludeAny

array

No

The search keyword for the file directory. Fuzzy search is supported.

string

No

The file type.

image

QueryContentTypeIncludeAny

array

No

A search condition to include any of the specified content types. The search results must match at least one of these types. You can specify multiple content types. If this parameter is empty, this condition is not applied. Use commas to separate multiple types in the array.

string

No

The content type of the file.

image/jpeg

StartTagUpdateTime

string

No

The file content types. The query returns files that match any of the specified types. You can specify multiple types and separate them with commas. If this parameter is empty, this filter is ignored.

2025-01-12T14:36:01.000Z

EndTagUpdateTime

string

No

The start time for querying tags by their last update time. The time must be in UTC and in the ISO 8601 format.

2025-01-12T14:36:01.000Z

MaxResults

integer

No

The end of the time range for a query that filters tags by their last update time. The time is a UTC timestamp in ISO 8601 format.

10

QueryExpression

string

No

The maximum number of results to return per page. Valid values: 1 to 100. Default value: 10.

(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'

Status

string

No

A query statement, also known as a Domain-Specific Language (DSL) query, lets you express complex retrieval conditions. It supports grouping, Boolean logic (AND/OR/NOT), range comparisons (>, >=, <, <=), property existence (HAS/NOT HAS), tokenized matches (:), and exact matches (=). Use DSL for advanced retrieval scenarios.

Important To avoid conflicts, do not use this query statement with other query parameters.

ACTIVE

QueryVideo

string

No

The status of the metadata to query.

  • ACTIVE: Returns metadata for active files. This is the default value.

  • ALL: Returns metadata for all files.

  • DELETED: Returns metadata for logically deleted files.

oss://test-xxx-oss/car/0001.mp4

DSL query syntax

KeywordDescriptionExample
:Token matchFileName:'lane line'
Finds data where the tokenized file name contains "lane line".
NOT :Token non-matchNOT FileName : 'lane line'
Finds data where the tokenized file name does not contain "lane line".
=Exact value matchFileType='image'
Finds data where the file type is exactly "image".
NOT =Exact value exclusionNOT FileType = 'video'
Finds all data where FileType is not equal to "video".
HASExistsHAS SemanticIndexJobId
Finds all data that has the SemanticIndexJobId property.
NOT HASDoes not existNOT HAS SemanticIndexJobId
Finds all data that does not have the SemanticIndexJobId property.
""Encloses a string value.Single and double quotation marks have the same effect.
()Grouping operation(FileName:'black' AND ContentType='image/jpeg') OR (FileName:'white' AND ContentType='image/png')
Finds data where the file name contains the token "black" and the content type is "image/jpeg", or where the file name contains the token "white" and the content type is "image/png".
>Range query:
Greater than
FileUpdateTime> '2025-01-16T11:52:56.000Z' AND DataSize >= 12345
The file was last modified after 2025-01-16T11:52:56.000Z and the file size is greater than or equal to 12,345 bytes.
>=Range query:
Greater than or equal to
Same as above.
<Range query:
Less than
FileUpdateTime < '2025-01-16T11:52:56.000Z' AND DataSize <= 12345
The file was last modified before 2025-01-16T11:52:56.000Z and the file size is less than or equal to 12,345 bytes.
<=Range query:
Less than or equal to
Same as above.
ANDAND
The keyword is case-insensitive.
FileType='image' AND ContentType:'image/png'
Finds images where the file type is "image" and the content type is "image/png".
OROR
The keyword is case-insensitive.
FileType='image' OR FileType='video'
Finds data where the file type is "image" or "video".

Supported properties for DSL queries

DSL queries support properties for basic file metadata, tags, vector search, and general search. All properties in the query conditions are optional.

Type descriptions:

  • KEYWORD: Supports one or more of the following operations: equals, not equals, exists, and does not exist.

  • TEXT: Supports one or more of the following operations: token contains, token does not contain, equals, not equals, exists, and does not exist.

  • NUMBER: Supports one or more of the following operations: range query, equals, exists, and does not exist.

  • DATE: Supports one or more of the following operations: range query, exists, and does not exist.

Basic metadata properties

Property nameInternal typeToken containsToken does not containEqualsNot equalsExists/Does not existRange queryAND logicOR logic
DatasetFileMetaIdKEYWORD---
FileNameTEXT-
FileDirTEXT-
FileTypeKEYWORD---
ContentTypeKEYWORD---
DataSizeNUMBER---
FileUpdateTimeDATE----
SyncTimeDATE----
TagUpdateTimeDATE----
SemanticIndexUpdateTimeDATE----
StatusKEYWORD---

Tag properties

Property nameInternal typeToken containsToken does not containEqualsNot equalsExists/Does not existRange queryAND logicOR logic
Tags.aiKEYWORD---
Tags.userKEYWORD---
Tags.allKEYWORD---

Vector query properties

Property nameInternal typeToken containsToken does not containEqualsNot equalsExists/Does not existRange queryAND logicOR logic
ContentTEXT--
TopKNUMBER---
ScoreThresholdNUMBER---

General query properties

Property nameInternal typeToken containsToken does not containEqualsNot equalsExists/Does not existRange queryAND logicOR logic
QueryTypeKEYWORD---
SignModeKEYWORD---
ThumbnailModeKEYWORD---
SortByKEYWORD---
OrderKEYWORD---
NextTokenKEYWORD---
MaxResultsNUMBER---

Response elements

Element

Type

Description

Example

object

The request result.

TotalCount

integer

The total number of entries returned.

123

PageSize deprecated

integer

The number of entries on the current page.

30

NextToken

string

The pagination token. If the number of results that match the query exceeds the page size, this token is returned. To retrieve the next page of data, use the returned token in your next request. Repeat this process until no token is returned, which indicates that all data has been retrieved.

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

DatasetFileMetas

array

The detailed metadata of the dataset files.

DatasetFileMeta

The detailed metadata of the dataset file.

DatasetId

string

The dataset ID.

d-rbvg5*****jhc9ks92

WorkspaceId

string

The workspace ID.

105173

DatasetVersion

string

The version name of the dataset.

v1

MaxResults

integer

The maximum number of results returned per page when you use the `NextToken` parameter.

10

Examples

Success response

JSON format

{
  "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",
      "Status": "ACTIVE"
    }
  ],
  "DatasetId": "d-rbvg5*****jhc9ks92\n",
  "WorkspaceId": "105173",
  "DatasetVersion": "v1",
  "MaxResults": 10
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.