对象存储
容器与中间件专题文档捉虫活动邀您参加 > HOT
文档中心>对象存储>API 文档>数据处理接口>智能检索 MetaInsight>查询与统计>简单查询

简单查询

最近更新时间：2024-06-12 17:46:52

我的收藏

本页目录：

功能描述

可以根据已提取的文件元数据（包含文件名、标签、路径、自定义标签、文本等字段）查询和统计数据集内文件，支持逻辑关系表达方式。

授权说明

授权策略中 action 设置为 ci:DatasetSimpleQuery ，详情请参见 数据万象 action。

限制说明

每次查询最多返回100个文件信息。
每次查询最多返回2000条聚合统计信息。
子查询条件最大支持设置100个。
子查询嵌套深度最多支持5层。

请求

请求示例

POST /datasetquery/simple HTTP/1.1
Host: <AppId>.ci.<Region>.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: application/json
说明：
Authorization: Auth String（详情请参见 请求签名 文档）。
通过子账号使用时，需要授予相关的权限，详情请参见 授权粒度详情 文档。

请求头

此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。

请求体

{
    "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.1
Host: ci.<Region>.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: 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 OK
Content-Type: application/json
Content-Length: 645
Date: Thu, 15 Jun 2023 07:59:50 GMT
Status: 200 OK
x-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.1
Host: ci.<Region>.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: application/json

{
    "Aggregations": [{
        "Field": "Filename",
        "Operation": "group"
    }],
    "DatasetName": "test",
    "MaxResults": 100
}

响应

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 645
Date: Thu, 15 Jun 2023 07:59:50 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

{
    "RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****",
    "Aggregations": [{
        "Field": "Size",
        "Groups": [{
            "Count": 1,
            "Value": "file001"
        }, {
            "Count": 1,
            "Value": "file002"
        }],
        "Operation": "group"
    }],
    "Files": [],
    "NextToken": ""
}
中国站
文档反馈
文档活动
message-icon联系我们
目录