ListDatasetFileMetas - Platform For AI - Alibaba Cloud Documentation Center

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

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 about how to obtain a dataset ID, 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 about how to obtain a workspace ID, see ListWorkspaces.	105173
QueryType	string	No	The search type. MIX: Mixed search (default). TAG: Tag-based search only. VECTOR: Vector-based search 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 number of search results to return. A maximum of TopK results are returned. 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 the specified 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 specify MaxResults at the same time, the value of MaxResults takes precedence. Note This parameter is deprecated. Use NextToken and MaxResults for paged queries.	10
NextToken	string	No	The pagination token. Note If you do not set this parameter, the first page of results is returned. If a value is returned, more results are available. To get the next page, use the returned token in your next request. Repeat this 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 paged queries. If you do not specify this parameter, results are sorted by relevance from high to low. Other valid values: 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 paged query. Use this parameter with SortBy. The default value is DESC. ASC: Ascending. DESC: Descending. Valid values: ASC : ASC DESC : DESC	DESC
EndFileUpdateTime	string	No	The earliest file update time for the query. The time must be a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
StartFileUpdateTime	string	No	The end time for the query. The time must be a UTC timestamp in the ISO 8601 format.	2025-01-12T14:36:01.000Z
QueryImage	string	No	When you search by image, use this parameter to specify the image information. You can 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. Currently, thumbnails are supported only for files in OSS. Proportional scaling: p_{percentage}. The `percentage` indicates the desired scaling ratio. Valid values: 1 to 100. Example: `p_50` scales the image to 50% of its original size. Fixed width, automatic height: w_{width}. The `width` indicates the desired image width. Valid values: 1 to 16384. Example: `w_200` sets the image width to 200 pixels and scales the height proportionally. Fixed height, automatic width: h_{height}. The `height` indicates the desired image height. Valid values: 1 to 16384. Example: `h_100` sets the image height to 100 pixels and scales the width proportionally. Fixed width and height with padding: m_pad,w_{width},h_{height},color_{RGB}. `m_pad` scales the image to the maximum size that fits within a rectangle of the specified width and height. `RGB` specifies the color to fill the empty space. If you do not specify a color, white is used by default. `width` and `height` indicate the desired image dimensions. Valid values for both `width` and `height`: 1 to 16384. Example: Fixed width and height with center crop: m_fill,w_{width},h_{height}. `m_fill` proportionally scales the image to the minimum size that covers the specified width and height, then crops the excess from the center. `width` and `height` indicate the desired image dimensions. Valid values for both `width` and `height`: 1 to 16384. 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}. `width` and `height` indicate the desired image dimensions. Valid values for both `width` and `height`: 1 to 16384. Example: `m_fixed,w_100,h_100` forces the image to be scaled to 100 × 100 pixels.	w_100
QueryTagsIncludeAll	array	No	The 'include all of these tags' search condition. You can select multiple tags. The search results must contain all of these tags. If this parameter is empty, this condition is not applied. Use commas to separate multiple tags in the array. Note This parameter is valid only when QueryType is set to TAG or MIX. When QueryType is set to TAG, the value of QueryText is added to this condition.
	string	No	The tag name.	Lane line
QueryTagsIncludeAny	array	No	The 'include any of these tags' search condition. You can select multiple tags. The search results must contain at least one of these tags. If this parameter is empty, this condition is not applied. Use commas to separate multiple tags in the array. Note This parameter is valid only when QueryType is set to TAG or MIX.
	string	No	The tag name.	Lane line
QueryTagsExclude	array	No	The 'exclude these tags' search condition. You can select multiple tags. The search results must not contain any of these tags. If this parameter is empty, this condition is not applied. 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 search condition for file names. Fuzzy search is supported.	car
QueryFileDir	string	No	The search condition for file directories. Fuzzy search is supported.	cars/20250221/
QueryFileTypeIncludeAny	array	No	The 'include any of these file types' search condition. You can select multiple file types. The search results must match at least one of these types. If this parameter is empty, this condition is not applied. Use commas to separate multiple types in the array.
	string	No	The file type.	image
QueryContentTypeIncludeAny	array	No	The 'include any of these content types' search condition. You can select multiple content types. The search results must match at least one of these 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 start of the time range to query by tag update time. The time is a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
EndTagUpdateTime	string	No	The end of the time range to query by tag update time. The time is a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
MaxResults	integer	No	The maximum number of results to return per page when you use the NextToken parameter. Valid values: 1 to 100. Default value: 10.	10
QueryExpression	string	No	The search statement (DSL) is a domain-specific language used to express complex search conditions. It supports grouping, Boolean logic (AND/OR/NOT), range comparisons (>, >=, <, <=), property existence checks (HAS/NOT HAS), token matching (:), and exact matching (=). DSL is suitable for advanced search scenarios. It is generally used for complex advanced search conditions. Important To avoid conflicts, do not use this parameter with other query parameters.	(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	The metadata status to query. ACTIVE: Queries only active data (default). ALL: Queries all data. DELETED: Queries only logically deleted data.	ACTIVE

DSL query syntax

Keyword	Description	Example
:	Token match	`FileName:'lane line'` Finds data where the tokenized file name contains "lane line".
NOT :	Token non-match	`NOT FileName : 'lane line'` Finds data where the tokenized file name does not contain "lane line".
=	Exact match	`FileType='image'` Finds data where the file type is exactly "image".
NOT =	Exact exclusion	`NOT FileType = 'video'` Finds all data where FileType is not equal to "video".
HAS	Exists	`HAS SemanticIndexJobId` Finds all data that has the SemanticIndexJobId property.
NOT HAS	Does not exist	`NOT 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 fuzzy-matches "black" and the content type is "image/jpeg", OR where the file name fuzzy-matches "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 12345 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 12345 bytes.
<=	Range query: Less than or equal to	Same as above.
AND	AND Case-insensitive.	`FileType='image' AND ContentType:'image/png'` Finds images where the file type is "image" and the content type is "image/png".
OR	OR 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 name	Internal type	Token contains	Token does not contain	Equals	Not equals	Exists/Does not exist	Range query	AND logic	OR logic
DatasetFileMetaId	KEYWORD	-	-	✅	✅	✅	-	✅	✅
FileName	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileDir	TEXT	✅	✅	✅	✅	✅	-	✅	✅
FileType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
ContentType	KEYWORD	-	-	✅	✅	✅	-	✅	✅
DataSize	NUMBER	-	-	✅	-	✅	✅	✅	✅
FileUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SyncTime	DATE	-	-	-	-	✅	✅	✅	✅
TagUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
SemanticIndexUpdateTime	DATE	-	-	-	-	✅	✅	✅	✅
Status	KEYWORD	-	-	✅	❌	❌	-	✅	❌

Tag properties

Property name	Internal type	Token contains	Token does not contain	Equals	Not equals	Exists/Does not exist	Range query	AND logic	OR logic
Tags.ai	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.user	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.all	KEYWORD	-	-	✅	✅	✅	-	✅	✅

Vector query properties

Property name	Internal type	Token contains	Token does not contain	Equals	Not equals	Exists/Does not exist	Range query	AND logic	OR logic
Content	TEXT	✅	-	❌	❌	❌	-	✅	❌
TopK	NUMBER	-	-	✅	-	❌	❌	✅	❌
ScoreThreshold	NUMBER	-	-	✅	-	❌	❌	✅	❌

General query properties

Property name	Internal type	Token contains	Token does not contain	Equals	Not equals	Exists/Does not exist	Range query	AND logic	OR logic
QueryType	KEYWORD	-	-	✅	❌	❌	-	✅	❌
SignMode	KEYWORD	-	-	✅	❌	❌	-	✅	❌
ThumbnailMode	KEYWORD	-	-	✅	❌	❌	-	✅	❌
SortBy	KEYWORD	-	-	✅	❌	❌	-	✅	❌
Order	KEYWORD	-	-	✅	❌	❌	-	✅	❌
NextToken	KEYWORD	-	-	✅	❌	❌	-	✅	❌
MaxResults	NUMBER	-	-	✅	-	❌	❌	✅	❌

Response elements

Element	Type	Description	Example
	object	The request result.
TotalCount	integer	The total number of returned entries.	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 value in your next request. Repeat this until no token is returned, which indicates that all data has been retrieved.	90******-f5c5-4cd4-927e-1f45e1cb8b62_1729644433000
DatasetFileMetas	array	The list of dataset file metadata details.
	DatasetFileMeta	The details of the dataset file metadata.
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.