Query Dataset Files with ListDatasetFileMetas API - Platform For AI - Alibaba Cloud - Platform For AI

Queries the list of dataset files.

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 information about how to obtain the dataset ID, see ListDatasets.	d-rbvg5*****jhc9ks92

Request parameters

Parameter	Type	Required	Description	Example
DatasetVersion	string	Yes	The dataset version name.	v1
WorkspaceId	string	Yes	The workspace ID of the dataset. For information about how to obtain the workspace ID, see ListWorkspaces.	105173
QueryType	string	No	The retrieve type. Valid values: MIX: hybrid retrieve (default). TAG: label-only retrieve. VECTOR: AISearch-only retrieve. Valid values: TAG : TAG MIX : MIX VECTOR : VECTOR	MIX
QueryText	string	No	The text content to search for.	A fallen water
TopK	integer	No	The maximum number of results to return. Only the top K results are returned. Note This parameter takes effect only when QueryType is set to VECTOR or MIX.	100
ScoreThreshold	number	No	The similarity score threshold. Only results with a score greater than ScoreThreshold are returned. Note This parameter takes effect only when QueryType is set to VECTOR or MIX.	0.6
PageSize `deprecated`	integer	No	The number of entries per page. If MaxResults is also specified, MaxResults takes precedence. Note This parameter will be offline soon. Use NextToken and MaxResults to perform paging query operations.	10
NextToken	string	No	The pagination token. Note If this parameter is not specified, the first page of data is returned. If a value is returned for this parameter, more pages are available. Pass the returned NextToken value as a request parameter to retrieve the next page, until no NextToken value is returned, which indicates that all data has been retrieved.	90a6ee35-****-4cd4-927e-1f45e1cb8b62_1729644433000
SortBy	string	No	The sorting field for paging queries. By default, results are sorted by retrieve relevance in descending order. Other valid values: FileCreateTime: sorting by file creation time. FileUpdateTime: sorting by file last modified time. Valid values: FileCreateTime : FileCreateTime FileUpdateTime : FileUpdateTime	FileCreateTime
Order	string	No	The sorting order for the specified sorting field in paging queries. Used together with SortBy. Default value: DESC. Valid values: ASC: ascending order. DESC: descending order. Valid values: ASC : ASC DESC : DESC	DESC
EndFileUpdateTime	string	No	The start time of the file update time range for the query. The value is a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
StartFileUpdateTime	string	No	The end time of the file update time range for the query. The value is a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
QueryImage	string	No	The image information for image-to-image search. An OSS URL with public network access is supported. Format: oss://{bucket_name}/{object_path}, where bucket_name is the bucket name and object_path is the file path in the bucket. Note This parameter takes effect only when QueryType is set to VECTOR or MIX.	oss://test-xxx-oss/car/0001.png
ThumbnailMode	string	No	The thumbnail mode for images. Currently, only OSS files support thumbnails: Proportional scaling: p_{percentage}, where percentage specifies the desired scaling ratio. Valid values: [1, 100]. Example: p_50 uses 50% of the original file size as the thumbnail. Fixed width with adaptive height: w_{width}, where width specifies the desired image width. Valid values: [1, 16384]. Example: w_200 fixes the image width to 200 pixels and adaptively scales the height. Fixed height with adaptive width: h_{height}, where height specifies the desired image height. Valid values: [1, 16384]. Example: h_100 fixes the image height to 100 pixels and adaptively scales the width. Fixed dimensions with padding: m_pad,w_{width},h_{height},color_{RGB}. m_pad scales the image to the largest size that fits within the specified width and height rectangle. RGB specifies the fill color for blank areas. If this parameter is not specified, white is used by default. width specifies the desired image width and height specifies the desired image height. Valid values for both width and height: [1, 16384]. Example: Fixed dimensions with center cropping: m_fill,w_{width},h_{height}. m_fill proportionally scales the image to the smallest size that extends beyond the specified width and height rectangle, and center-crops the excess. width specifies the desired image width and height specifies the desired image height. Valid values for both width and height: [1, 16384]. Example: m_fill,w_100,h_100 fixes both the width and height to 100 pixels with center cropping. Forced dimensions: m_fixed,w_{width},h_{height}. width specifies the desired image width and height specifies the desired image height. Valid values for both width and height: [1, 16384]. Example: m_fixed,w_100,h_100 forces both the width and height to 100 pixels.	w_100
DatasetFileMetaIds	array	No	The list of metadata IDs to query.
	string	No	The metadata ID.	5dc037c8ec0a6fc4e15741328e531bbee036exxxxxxxxx722eff66c38a90e08c
QueryTagsIncludeAll	array	No	The search condition for "include all of the following tags". You can select multiple tags, and the query results must match all of them. If this parameter is empty, this condition is not applied. Array elements are separated by commas. Note This parameter takes effect 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 search condition for "include any of the following tags". You can select multiple tags, and the query results need to match only one of them. If this parameter is empty, this condition is not applied. Array elements are separated by commas. Note This parameter takes effect only when QueryType is set to TAG or MIX.
	string	No	The tag name.	Lane line
QueryTagsExclude	array	No	The search condition for "exclude the following tags". You can select multiple tags, and the query results must not contain any of them. If this parameter is empty, this condition is not applied. Note This parameter takes effect only when QueryType is set to TAG or MIX.
	string	No	The tag name.	Lane line
QueryFileName	string	No	The file name search condition. Fuzzy match is supported.	car
QueryFileDir	string	No	The file directory search condition. Fuzzy match is supported.	cars/20250221/
QueryFileTypeIncludeAny	array	No	The search condition for "include any of the following file types". You can select multiple file types, and the query results need to match only one of them. If this parameter is empty, this condition is not applied. Array elements are separated by commas.
	string	No	The file type.	image
QueryContentTypeIncludeAny	array	No	The search condition for "include any of the following content types". You can select multiple content types, and the query results need to match only one of them. If this parameter is empty, this condition is not applied. Array elements are separated by commas.
	string	No	The file content type.	image/jpeg
StartTagUpdateTime	string	No	The start time of the tag last update time range for the query. The value is a UTC timestamp in ISO 8601 format.	2025-01-12T14:36:01.000Z
EndTagUpdateTime	string	No	The end time of the tag last update time range for the query. The value 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 request when using NextToken-based pagination. Valid values: 1 to 100. Default value: 10.	10
QueryExpression	string	No	The query statement (DSL) is a realm-specific language for expressing complex retrieve conditions. It supports grouping, Boolean logic (AND/OR/NOT), range comparisons (>, >=, <, <=), property existence checks (HAS/NOT HAS), token match (:), and exact match (=), which are suitable for advanced retrieve scenarios. This parameter is typically used for complex advanced retrieve conditional statements. Important To avoid conflicts, after setting this query statement, do not use it together 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. Valid values: ACTIVE: queries only non-deleted data (default). ALL: queries all data. DELETED: queries only logically deleted data. Valid values: ALL : queries all data. ACTIVE : queries only non-deleted data. DELETED : queries only logically deleted data.	ACTIVE
QueryVideo	string	No	The video file information for video-based search. A video OSS URL with public network access is supported. Format: oss://{bucket_name}/{object_path}, where bucket_name is the bucket name and object_path is the file path in the bucket. Note This parameter takes effect only when QueryType is set to VECTOR or MIX.	oss://test-xxx-oss/car/0001.mp4

DSL query syntax

Keyword	Description	Example
:	Token match	`FileName:'lane line'` Finds data whose file name contains "lane line" after tokenization.
NOT :	Token exclusion	`NOT FileName : 'lane line'` Finds data whose file name does not contain "lane line" after tokenization.
=	Exact match	`FileType='image'` Finds data whose file type is exactly "image".
NOT =	Exact exclusion	`NOT FileType = 'video'` Finds all data whose FileType is not "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.
""	Wraps string values	Single and double quotes have the same effect.
()	Grouping	`(FileName:'black' AND ContentType='image/jpeg') OR (FileName:'white' AND ContentType='image/png')` Finds data where FileName is a fuzzy match for "black" and ContentType is "image/jpeg", or FileName is a fuzzy match for "white" and ContentType is "image/png".
>	Range query: greater than	`FileUpdateTime> '2025-01-16T11:52:56.000Z' AND DataSize >= 12345` Finds files whose last modified time is after 2025-01-16T11:52:56.000Z and whose 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` Finds files whose last modified time is before 2025-01-16T11:52:56.000Z and whose file size is less than or equal to 12345 bytes.
<=	Range query: less than or equal to	Same as above.
AND	Logical AND. Case-insensitive.	`FileType='image' AND ContentType:'image/png'` Finds images whose file type is "image" and content format is "png".
OR	Logical OR. Case-insensitive.	`FileType='image' OR FileType='video'` Finds data whose file type is "image" or "video".

DSL query property reference

The following basic file metadata properties, label properties, AISearch properties, and general retrieve properties are supported. All properties are optional in query conditions.

Type descriptions:

KEYWORD: supports one or more of the following: equal to, not equal to, exists, and does not exist.
TEXT: supports one or more of the following: token match, token exclusion, equal to, not equal to, exists, and does not exist.
NUMBER: supports one or more of the following: range query, equal to, exists, and does not exist.
DATE: supports one or more of the following: range query, exists, and does not exist.

Basic metadata properties

Property	Internal type	Token match	Token exclusion	Equal to	Not equal to	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	Internal type	Token match	Token exclusion	Equal to	Not equal to	Exists/Does not exist	Range query	AND logic	OR logic
Tags.ai	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.user	KEYWORD	-	-	✅	✅	✅	-	✅	✅
Tags.all	KEYWORD	-	-	✅	✅	✅	-	✅	✅

Vector search properties

Property	Internal type	Token match	Token exclusion	Equal to	Not equal to	Exists/Does not exist	Range query	AND logic	OR logic
Content	TEXT	✅	-	❌	❌	❌	-	✅	❌
TopK	NUMBER	-	-	✅	-	❌	❌	✅	❌
ScoreThreshold	NUMBER	-	-	✅	-	❌	❌	✅	❌

General search properties

Property	Internal type	Token match	Token exclusion	Equal to	Not equal to	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 response.
TotalCount	integer	The total number of entries returned.	123
PageSize `deprecated`	integer	The current page size.	30
NextToken	string	The pagination token. If the number of results that match the query conditions exceeds the page size, this pagination token is returned. To retrieve the next page of data, pass the returned token value as a request parameter until no token value 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 dataset file metadata details.
DatasetId	string	The dataset ID.	d-rbvg5*****jhc9ks92
WorkspaceId	string	The workspace ID.	105173
DatasetVersion	string	The dataset version name.	v1
MaxResults	integer	The maximum number of results returned per request when using NextToken-based pagination.	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 }",
      "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.