功能描述
可以根据已提取的文件元数据(包含文件名、标签、路径、自定义标签、文本等字段)查询和统计数据集内文件,支持逻辑关系表达方式。
授权说明
限制说明
每次查询最多返回100个文件信息。
每次查询最多返回2000条聚合统计信息。
子查询条件最大支持设置100个。
子查询嵌套深度最多支持5层。
请求
请求示例
POST /datasetquery/simple HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
请求头
请求体
{"DatasetName": "test","Query": {"Operation": "and","SubQueries": [{"Field": "ContentType","Value": "image/jpeg","Operation": "eq"},{"Field": "Size","Value": "1000","Operation": "gt"}]},"Sort": "CustomId","Order": "desc","MaxResults": 100}
请求参数
参数名称 | 描述 | 类型 | 是否必选 |
DatasetName | 数据集名称,同一个账户下唯一。 | String | 是 |
Query | 简单查询参数条件,可自嵌套。 | Container | 否 |
Sort | 多个排序字段可使用半角逗号(,)分隔,例如:Size,Filename。 最多可设置5个排序字段。 排序字段顺序即为排序优先级顺序。 | String | 否 |
Order | 排序字段的排序方式。取值如下: asc:升序; desc(默认):降序。 规则如下: 多个排序方式可使用半角逗号(,)分隔,例如:asc,desc。 排序方式不可多于排序字段,即参数 Order 的元素数量需小于等于参数 Sort 的元素数量。例如 Sort 取值为 Size,Filename时,Order 可取值为 asc,desc 或 asc。 排序方式少于排序字段时,未排序的字段默认取值 asc。例如 Sort 取值为 Size,Filename,Order 取值为 asc 时,Filename 默认排序方式为 asc,即升序排列。 | String | 否 |
MaxResults | 返回文件元数据的最大个数。 取值范围为0-200。 使用聚合参数时,该值表示返回分组的最大个数,取值范围为0-2000。 不设置此参数或者设置为0时,则取默认值100。 | Integer | 否 |
NextToken | 当绑定关系总数大于设置的 MaxResults 时,用于翻页的 token。 从 NextToken 开始按字典序返回绑定关系信息列表。 第一次调用此接口时,设置为空。 | String | 否 |
Aggregations | 聚合字段信息列表。 当您使用聚合查询时,仅返回聚合结果,不再返回匹配到的元信息列表。 | Container Array | 否 |
WithFields | 仅返回特定字段的值,而不是全部已有的元信息字段。 可用于降低返回的结构体大小。 不填或留空则返回所有字段。 | String Array | 否 |
Query 节点内容:
参数名称 | 描述 | 类型 | 是否必选 |
Operation | 操作运算符。枚举值: not:逻辑非。 or:逻辑或。 and:逻辑与。 lt:小于。 lte:小于等于。 gt:大于。 gte:大于等于。 eq:等于。 exist:存在性查询。 prefix:前缀查询。 match-phrase:字符串匹配查询。 nested:字段为数组时,其中同一对象内逻辑条件查询。 | String | 是 |
SubQueries | 子查询的结构体。 只有当 Operations 为逻辑运算符(and、or、not或nested)时,才能设置子查询条件。 在逻辑运算符为 and/or/not 时,其 SubQueries 内描述的所有条件需符合父级设置的 and/or/not 逻辑关系。 在逻辑运算符为 nested 时,其父级的 Field 必须为一个数组类的字段(如:Labels),子查询条件 SubQueries 组的 Operation 必须为 and/or/not 中的一个或多个,其 Field 必须为父级 Field 的子属性。 | Container Array | 否 |
Field | String | 否 | |
Value | 查询的字段值。当 Operations 为逻辑运算符(and、or、not 或 nested)时,该字段无效。 | String | 否 |
Aggregations 节点内容:
参数名称 | 描述 | 类型 | 是否必选 |
Field | String | 否 | |
Operation | 聚合字段的操作符。枚举值: min:最小值。 max:最大值。 average:平均数。 sum:求和。 count:计数。 distinct:去重计数。 group:分组计数,按照分组计数结果从高到低排序。 | String | 否 |
响应
响应头
响应体
{"Aggregations": [],"Files": [{"COSCRC64": "1111122455985959955","COSStorageClass": "STANDARD","CacheControl": "","ContentType": "image/jpeg","CreateTime": "2023-12-26T14:29:25.753167285+08:00","CustomId": "002","CustomLabels": {"age": "18","level": "18"},"DatasetName": "test","ETag": "\\"21aeb337eb76df70dcb1e2618598****5\\"","FileAccessTime": "","FileModifiedTime": "2023-06-07T07:20:28Z","Filename": "examplebucket-1250000000/test002.jpg","MediaType": "video","ObjectACL": "default","Size": "10000","URI": "cos://examplebucket-1250000000/test002.jpg","UpdateTime": "2023-12-26T14:38:11.575077683+08:00"}, {"COSCRC64": "1111125831785959934","COSStorageClass": "STANDARD","CacheControl": "","ContentType": "image/jpeg","CreateTime": "2023-12-26T11:43:18.92077679+08:00","CustomId": "001","CustomLabels": {"age": "18","level": "18"},"DatasetName": "test","ETag": "\\"21aeb337eb76df70dcb1e2618598****\\"","FileModifiedTime": "2023-06-07T07:18:04Z","Filename": "examplebucket-1250000000/test001.jpg","MediaType": "image","ObjectACL": "default","Size": "20000","URI": "cos://examplebucket-1250000000/test001.jpg","UpdateTime": "2023-12-26T11:45:02.445509346+08:00"}],"NextToken": "aP+BAwEBDlF1ZXJ5TmV4dFRva2VuAf+CAAEGAQpTb3J0RmllbGRzAQwAAQtTZWFyY2hBZnRlcgH/hAABBU9yZGVyAQwAAQVBcHBpZAEMAAEDVWluAQwAAQtEYXRhc2V0TmFtZQEMAAAAHP+DAgEBDltdaW50ZXJmYWNlIHt9Af+EAAEQAAAj/4IBCEN1c3RvbUlkAQEGc3RyaW5nDAUAAzAwMQEEZG*****","RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****"}
响应包体具体数据内容如下:
参数名称 | 类型 | 描述 |
Aggregations | Container Array | 聚合字段信息列表。仅在请求的 Aggregations 不为空时返回。 |
Files | Container Array | 文件信息列表。仅在请求的 Aggregations 为空时返回。 |
RequestId | String | 请求 ID。 |
NextToken | String | 翻页标记。 当文件总数大于设置的 MaxResults 时,用于翻页的 Token。 符合条件的文件信息未全部返回时,此参数才有值。 下一次列出文件信息时将此值作为 NextToken 传入,将后续的文件信息返回。 |
File 节点内容:
参数名称 | 类型 | 描述 |
COSCRC64 | String | 文件 CRC64值。 |
COSStorageClass | String | 文件存储空间类型。 |
CacheControl | String | 指定 Object 被下载时网页的缓存行为。该字段需要设置 COS Object HTTP 属性 Cache-Control。 |
ContentType | String | 文件内容类型(MIME Type)。 |
CreateTime | String | 元数据创建时间的时间戳,格式为 RFC3339Nano。 |
CustomId | String | 该文件的自定义 ID。该文件索引到数据集后,作为该行元数据的属性存储,用于和您的业务系统进行关联、对应。您可以根据业务需求传入该值,例如将某个 URI 关联到您系统内的某个 ID。推荐传入全局唯一的值。 |
CustomLabels | Container | 文件自定义标签列表。储存您业务自定义的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 |
DatasetName | String | 数据集名称。 |
ETag | String | Object 生成时会创建相应的 ETag ,ETag 用于标识一个 Object 的内容。 |
FileModifiedTime | String | 文件最近一次修改时间的时间戳, 格式为 RFC3339Nano。 |
Filename | String | 文件路径。 |
MediaType | String | 文件媒体类型。 枚举值: image:图片。 other:其他。 document:文档。 archive:压缩包。 audio:音频。 video:视频。 |
ObjectACL | String | 文件访问权限属性。 |
Size | Int | 文件大小,单位为字节。 |
URI | String | 资源标识字段,表示需要建立索引的文件地址。 |
UpdateTime | String | 元数据修改时间的时间戳,格式为 RFC3339Nano。 创建元数据后,如果未更新过元数据,则元数据修改时间的时间戳和元数据创建时间的时间戳相同。 |
ObjectId | String | 对象唯一 ID。 |
ContentDisposition | String | 指定 Object 被下载时的名称。需要设置 COS Object HTTP 属性 Content-Disposition。 |
ContentEncoding | String | 指定该 Object 被下载时的内容编码格式。需要设置 COS Object HTTP 属性 Content-Encoding。 |
ContentLanguage | String | Object 内容使用的语言。需要设置 COS Object HTTP 属性 Content-Language。 |
ServerSideEncryption | String | 加密算法,需要设置x-cos-server-side-encryption。 |
COSUserMeta | Container | COS 自定义头部。储存您业务在 cos object 上的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 |
COSTagging | Container | COS 自定义标签。储存您业务在 cos object 上的自定义标签的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 |
COSTaggingCount | Int | COS 自定义标签的数量。 |
Aggregations 节点内容:
参数名称 | 类型 | 描述 |
Field | String | 聚合字段名称。 |
Operation | String | 聚合字段的聚合操作符。 |
Value | Float | 聚合的统计结果。 |
Groups | Container Array | 分组聚合的结果列表。仅在请求的 Aggregations 中存在 group 类型的 Operation 时才会返回。 |
Groups 节点内容:
参数名称 | 类型 | 描述 |
Value | String | 分组聚合的值。 |
Count | Integer | 分组聚合的总个数。 |
实际案例
案例一:查询 size 大于1000的 jpeg 图片
请求
POST /datasetquery/simple HTTP/1.1Host: ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json{"DatasetName": "test","Query": {"Operation": "and","SubQueries": [{"Field": "ContentType","Value": "image/jpeg","Operation": "eq"},{"Field": "Size","Value": "1000","Operation": "gt"}]},"Sort": "CustomId","Order": "desc","MaxResults": 100}
响应
HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 645Date: Thu, 15 Jun 2023 07:59:50 GMTStatus: 200 OKx-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****{"Aggregations": [],"Files": [{"COSCRC64": "1111122455985959955","COSStorageClass": "STANDARD","CacheControl": "","ContentType": "image/jpeg","CreateTime": "2023-12-26T14:29:25.753167285+08:00","CustomId": "002","CustomLabels": {"age": "18","level": "18"},"DatasetName": "test","ETag": "\\"21aeb337eb76df70dcb1e2618598****5\\"","FileAccessTime": "","FileModifiedTime": "2023-06-07T07:20:28Z","Filename": "examplebucket-1250000000/test002.jpg","MediaType": "video","ObjectACL": "default","Size": "10000","URI": "cos://examplebucket-1250000000/test002.jpg","UpdateTime": "2023-12-26T14:38:11.575077683+08:00"}, {"COSCRC64": "1111125831785959934","COSStorageClass": "STANDARD","CacheControl": "","ContentType": "image/jpeg","CreateTime": "2023-12-26T11:43:18.92077679+08:00","CustomId": "001","CustomLabels": {"age": "18","level": "18"},"DatasetName": "test","ETag": "\\"21aeb337eb76df70dcb1e2618598****\\"","FileModifiedTime": "2023-06-07T07:18:04Z","Filename": "examplebucket-1250000000/test001.jpg","MediaType": "image","ObjectACL": "default","Size": "20000","URI": "cos://examplebucket-1250000000/test001.jpg","UpdateTime": "2023-12-26T11:45:02.445509346+08:00"}],"NextToken": "aP+BAwEBDlF1ZXJ5TmV4dFRva2VuAf+CAAEGAQpTb3J0RmllbGRzAQwAAQtTZWFyY2hBZnRlcgH/hAABBU9yZGVyAQwAAQVBcHBpZAEMAAEDVWluAQwAAQtEYXRhc2V0TmFtZQEMAAAAHP+DAgEBDltdaW50ZXJmYWNlIHt9Af+EAAEQAAAj/4IBCEN1c3RvbUlkAQEGc3RyaW5nDAUAAzAwMQEEZG*****","RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****"}
案例二:按文件名称聚合查询
请求
POST /query/simple HTTP/1.1Host: ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json{"Aggregations": [{"Field": "Filename","Operation": "group"}],"DatasetName": "test","MaxResults": 100}
响应
HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 645Date: Thu, 15 Jun 2023 07:59:50 GMTStatus: 200 OKx-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****{"RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****","Aggregations": [{"Field": "Size","Groups": [{"Count": 1,"Value": "file001"}, {"Count": 1,"Value": "file002"}],"Operation": "group"}],"Files": [],"NextToken": ""}