Queries the files in a dataset.
Try it now
Test
RAM authorization
|
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:
Valid values:
|
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:
Valid values:
|
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:
Valid values:
|
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.
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.
|
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 |
|
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.
|
oss://test-xxx-oss/car/0001.mp4 |
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 value match | FileType='image'Finds data where the file type is exactly "image". |
| NOT = | Exact value exclusion | NOT FileType = 'video'Finds all data where FileType is not equal to "video". |
| HAS | Exists | HAS SemanticIndexJobIdFinds all data that has the SemanticIndexJobId property. |
| NOT HAS | Does not exist | NOT HAS SemanticIndexJobIdFinds 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 >= 12345The 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 <= 12345The 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. |
| AND | AND 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". |
| OR | OR 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 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 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.