简介
本文档提供关于简单查询的相关 API 概览以及 SDK 示例代码。
API | 操作描述 |
简单查询 |
简单查询
功能说明
可以根据已提取的文件元数据(包含文件名、标签、路径、自定义标签、文本等字段)查询和统计数据集内文件,支持逻辑关系表达方式。
示例代码
def ci_dataset_simple_query():# 简单查询body = {# 数据集名称,同一个账户下唯一。# 是否必传:是'DatasetName': "test",# 简单查询参数条件,可自嵌套。# 是否必传:否'Query': {# 操作运算符。枚举值: not:逻辑非。 or:逻辑或。 and:逻辑与。 lt:小于。 lte:小于等于。 gt:大于。 gte:大于等于。 eq:等于。 exist:存在性查询。 prefix:前缀查询。 match-phrase:字符串匹配查询。 nested:字段为数组时,其中同一对象内逻辑条件查询。# 是否必传:是'Operation': "and",# 子查询的结构体。 只有当Operations为逻辑运算符(and、or、not或nested)时,才能设置子查询条件。 在逻辑运算符为and/or/not时,其SubQueries内描述的所有条件需符合父级设置的and/or/not逻辑关系。 在逻辑运算符为nested时,其父级的Field必须为一个数组类的字段(如:Labels)。 子查询条件SubQueries组的Operation必须为and/or/not中的一个或多个,其Field必须为父级Field的子属性。# 是否必传:否'SubQueries': [{# 查询的字段值。当Operations为逻辑运算符(and、or、not或nested)时,该字段无效。# 是否必传:否'Value': "image/jpeg",# 操作运算符。枚举值:not:逻辑非。or:逻辑或。and:逻辑与。lt:小于。lte:小于等于。gt:大于。gte:大于等于。eq:等于。exist:存在性查询。prefix:前缀查询。match-phrase:字符串匹配查询。nested:字段为数组时,其中同一对象内逻辑条件查询。# 是否必传:是'Operation': "eq",# 字段名称。关于支持的字段,请参考字段和操作符的支持列表。# 是否必传:否'Field': "ContentType",}],},# 返回文件元数据的最大个数,取值范围为0200。 使用聚合参数时,该值表示返回分组的最大个数,取值范围为02000。 不设置此参数或者设置为0时,则取默认值100。# 是否必传:否'MaxResults': 100,# 排序字段列表。请参考[字段和操作符的支持列表](https://cloud.tencent.com/document/product/460/106154)。 多个排序字段可使用半角逗号(,)分隔,例如:Size,Filename。 最多可设置5个排序字段。 排序字段顺序即为排序优先级顺序。# 是否必传:否'Sort': "CustomId",# 排序字段的排序方式。取值如下: asc:升序; desc(默认):降序。 多个排序方式可使用半角逗号(,)分隔,例如:asc,desc。 排序方式不可多于排序字段,即参数Order的元素数量需小于等于参数Sort的元素数量。例如Sort取值为Size,Filename时,Order可取值为asc,desc或asc。 排序方式少于排序字段时,未排序的字段默认取值asc。例如Sort取值为Size,Filename,Order取值为asc时,Filename默认排序方式为asc,即升序排列# 是否必传:否'Order': "desc",}response, data = client.ci_dataset_simple_query(Body=body,ContentType="application/json")print(response)print(data)return response, data
参数说明
调用 ci_dataset_simple_query 函数,具体请求参数如下:
参数名称 | 参数描述 | 类型 | 是否必填 |
Body | 简单查询请求参数 | Container | 是 |
Body 节点内容:
参数名称 | 参数描述 | 类型 | 是否必填 |
DatasetName | 数据集名称,同一个账户下唯一。 | String | 是 |
Query | 简单查询参数条件,可自嵌套。 | Container | 否 |
MaxResults | 返回文件元数据的最大个数, 取值范围为0-200。 使用聚合参数时,该值表示返回分组的最大个数,取值范围为0-2000。 不设置此参数或者设置为0时,则取默认值100。 | Integer | 否 |
NextToken | 当绑定关系总数大于设置的 MaxResults 时,用于翻页的 token。 从 NextToken 开始按字典序返回绑定关系信息列表。 第一次调用此接口时,设置为空。 | String | 否 |
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 | 否 |
Aggregations | 聚合字段信息列表。 当您使用聚合查询时,仅返回聚合结果,不再返回匹配到的元信息列表。 | Container Array | 否 |
WithFields | 仅返回特定字段的值,而不是全部已有的元信息字段。 可用于降低返回的结构体大小。 不填或留空则返回所有字段。 | String Array | 否 |
Aggregations 节点内容:
参数名称 | 参数描述 | 类型 | 是否必填 |
Operation | 聚合字段的操作符。枚举值: min:最小值。 max:最大值。 average:平均数。 sum:求和。 count:计数。 distinct:去重计数。 group:分组计数,按照分组计数结果从高到低排序。 | String | 否 |
Field | 字段名称。关于支持的字段,请参考字段和操作符的支持列表。 | String | 否 |
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 | 否 |
SubQueries 节点内容:
参数名称 | 参数描述 | 类型 | 是否必填 |
Value | 查询的字段值。当 Operations 为逻辑运算符(and、or、not 或 nested)时,该字段无效。 | String | 否 |
Operation | 操作运算符。枚举值: not:逻辑非。 or:逻辑或。 and:逻辑与。 lt:小于。 lte:小于等于。 gt:大于。 gte:大于等于。 eq:等于。 exist:存在性查询。 prefix:前缀查询。 match-phrase:字符串匹配查询。 nested:字段为数组时,其中同一对象内逻辑条件查询。 | String | 是 |
Field | 字段名称。关于支持的字段,请参考字段和操作符的支持列表。 | String | 否 |
返回结果说明
response 为响应头,data 为响应结果,数据类型都为 dict。
response 内容
响应体 data
响应体具体数据内容如下:
参数名称 | 参数描述 | 类型 |
RequestId | 请求 ID | String |
Files | 文件信息列表。仅在请求的 Aggregations 为空时返回。 | Container Array |
Aggregations | 聚合字段信息列表。仅在请求的 Aggregations 不为空时返回。 | Container Array |
NextToken | 翻页标记。当文件总数大于设置的 MaxResults 时,用于翻页的 Token。符合条件的文件信息未全部返回时,此参数才有值。下一次列出文件信息时将此值作为 NextToken 传入,将后续的文件信息返回。 | String |
AggregationsResult 节点内容:
参数名称 | 参数描述 | 类型 |
Operation | 聚合字段的聚合操作符。 | String |
Value | 聚合的统计结果。 | float |
Groups | 分组聚合的结果列表。仅在请求的 Aggregations 中存在 group 类型的 Operation 时才会返回。 | Container Array |
Field | 聚合字段名称。 | String |
Groups 节点内容:
参数名称 | 参数描述 | 类型 |
Count | 分组聚合的总个数。 | Integer |
Value | 分组聚合的值。 | String |
FileResult 节点内容:
参数名称 | 参数描述 | 类型 |
ObjectId | 对象唯一ID。 | String |
CreateTime | 元数据创建时间的时间戳,格式为 RFC3339Nano | String |
UpdateTime | 元数据修改时间的时间戳,格式为 RFC3339Nano 创建元数据后,如果未更新过元数据,则元数据修改时间的时间戳和元数据创建时间的时间戳相同 | String |
URI | 资源标识字段,表示需要建立索引的文件地址 | String |
Filename | 文件路径 | String |
MediaType | 文件媒体类型。 枚举值: image:图片。 other:其他。 document:文档。 archive:压缩包。 audio:音频。 video:视频。 | String |
ContentType | 文件内容类型(MIME Type)。 | String |
COSStorageClass | 文件存储空间类型。 | String |
COSCRC64 | 文件 CRC64值。 | String |
Size | 文件大小,单位为字节。 | Integer |
CacheControl | 指定 Object 被下载时网页的缓存行为。该字段需要设置 COS Object HTTP 属性 Cache-Control。 | String |
ContentDisposition | 指定 Object 被下载时的名称。需要设置 COS Object HTTP 属性 Content-Disposition。 | String |
ContentEncoding | 指定该 Object 被下载时的内容编码格式。需要设置 COS Object HTTP 属性 Content-Encoding。 | String |
ContentLanguage | Object 内容使用的语言。需要设置 COS Object HTTP 属性 Content-Language。 | String |
ServerSideEncryption | 加密算法,需要设置 x-cos-server-side-encryption。 | String |
ETag | Object 生成时会创建相应的 ETag ,ETag 用于标识一个 Object 的内容。 | String |
FileModifiedTime | 文件最近一次修改时间的时间戳, 格式为 RFC3339Nano。 | String |
CustomId | 该文件的自定义 ID。该文件索引到数据集后,作为该行元数据的属性存储,用于和您的业务系统进行关联、对应。您可以根据业务需求传入该值,例如将某个 URI 关联到您系统内的某个 ID。推荐传入全局唯一的值。 | String |
CustomLabels | 文件自定义标签列表。储存您业务自定义的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | Container |
COSUserMeta | cos 自定义头部。储存您业务在 cos object 上的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | Container |
ObjectACL | 文件访问权限属性。 | String |
COSTagging | cos 自定义标签。储存您业务在 cos object 上的自定义标签的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | Container |
COSTaggingCount | cos 自定义标签的数量。 | Integer |
DatasetName | 数据集名称。 | String |