简介
简单查询功能是由 数据万象(Cloud Infinite,CI)提供的,数据万象将处理能力与 COS SDK 完全结合,您可以直接按照本篇文档指引进行使用。
本文档提供关于简单查询的相关 API 概览以及 SDK 示例代码。
注意:
API | 操作描述 |
简单查询 |
简单查询
功能说明
可以根据已提取的文件元数据(包含文件名、标签、路径、自定义标签、文本等字段)查询和统计数据集内文件,支持逻辑关系表达方式。
方法原型
public DatasetSimpleQueryResponse datasetSimpleQuery(DatasetSimpleQueryRequest customRequest)
请求示例
DatasetSimpleQueryRequest request = new DatasetSimpleQueryRequest();request.setAppId("1234567890");// 设置数据集名称,同一个账户下唯一。;是否必传:是request.setDatasetName("test");// 设置操作运算符。枚举值: not:逻辑非。 or:逻辑或。 and:逻辑与。 lt:小于。 lte:小于等于。 gt:大于。 gte:大于等于。 eq:等于。 exist:存在性查询。 prefix:前缀查询。 match-phrase:字符串匹配查询。 nested:字段为数组时,其中同一对象内逻辑条件查询。;是否必传:是request.getQuery().setOperation("and");// 设置返回文件元数据的最大个数,取值范围为0200。 使用聚合参数时,该值表示返回分组的最大个数,取值范围为02000。 不设置此参数或者设置为0时,则取默认值100。;是否必传:否request.setMaxResults(100);// 设置排序字段列表。请参考[字段和操作符的支持列表](https://cloud.tencent.com/document/product/460/106154)。 多个排序字段可使用半角逗号(,)分隔,例如:Size,Filename。 最多可设置5个排序字段。 排序字段顺序即为排序优先级顺序。;是否必传:否request.setSort("CustomId");// 设置排序字段的排序方式。取值如下: asc:升序; desc(默认):降序。 多个排序方式可使用半角逗号(,)分隔,例如:asc,desc。 排序方式不可多于排序字段,即参数Order的元素数量需小于等于参数Sort的元素数量。例如Sort取值为Size,Filename时,Order可取值为asc,desc或asc。 排序方式少于排序字段时,未排序的字段默认取值asc。例如Sort取值为Size,Filename,Order取值为asc时,Filename默认排序方式为asc,即升序排列;是否必传:否request.setOrder("desc");DatasetSimpleQueryResponse response = client.datasetSimpleQuery(request);
参数说明
Request: 中的具体数据描述如下
参数名称 | 描述 | 类型 | 是否必传 |
AppId | String | 是 | |
datasetName | 数据集名称,同一个账户下唯一。 | String | 是 |
query | 简单查询参数条件,可自嵌套。 | Container | 否 |
maxResults | 返回文件元数据的最大个数,取值范围为0-200。 使用聚合参数时,该值表示返回分组的最大个数,取值范围为0-2000。 不设置此参数或者设置为0时,则取默认值100。 | Integer | 否 |
nextToken | 当绑定关系总数大于设置的 MaxResults 时,用于翻页的 token。 从 NextToken 开始按字典序返回绑定关系信息列表。 第一次调用此接口时,设置为空。 | String | 否 |
sort | 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 | 聚合字段的操作符。枚举值: not:逻辑非。 or:逻辑或。 and:逻辑与。 lt:小于。 lte:小于等于。 gt:大于。 gte:大于等于。 eq:等于。 exist:存在性查询。 prefix:前缀查询。 match-phrase:字符串匹配查询。 nested:字段为数组时,其中同一对象内逻辑条件查询。 | 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 | 否 |
响应参数说明:
DatasetSimpleQueryResponse 中的具体数据描述如下:
参数名称 | 描述 | 类型 |
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 | 文件自定义标签列表。储存您业务自定义的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | HashMap<String, String> |
cOSUserMeta | cos 自定义头部。储存您业务在 cos object 上的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | HashMap<String, String> |
objectACL | 文件访问权限属性。 | String |
cOSTagging | cos 自定义标签。储存您业务在 cos object 上的自定义标签的键名、键值对信息,用于在查询时可以据此为筛选项进行检索。 | HashMap<String, String> |
cOSTaggingCount | cos 自定义标签的数量。 | Integer |
datasetName | 数据集名称。 | String |
返回结果说明
成功:返回 DatasetSimpleQueryResponse 对象响应信息。
失败:发生错误(如 Bucket 不存在),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理。