tencent cloud

Cloud Infinite

DokumentasiCloud InfiniteAPI DocumentationIntelligent Search MetaInsightBasic SearchScalar Search

Scalar Search

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-08 16:24:28
Diterjemahkan oleh AI

API Description

You can query and count files in a dataset based on extracted file metadata, including fields such as filename, tag, path, custom tag, and text. Logical expressions are supported.

Authorization Description

When using a sub-account, add the ci:DatasetSimpleQuery permission to the action of the authorization policy. For all operations supported by Cloud Infinite, see CI action.

Use Limits

Before using search, complete creating a dataset first.
Only the Jakarta region is supported. In the request Host, Region can only be set to ap-jakarta.
For more usage limitations, see Usage Limits.

Request

Request sample

POST /datasetquery/simple HTTP/1.1
Host: <AppId>.ci.ap-jakarta.myqcloud.com
Authorization: <Auth String>
Content-Length: <length>
Content-Type: application/json
Accept: application/json
Note:
Authorization: Auth String. For details, see Request Signature.

Request header

This API only uses common request headers. For details, see Common Request Headers.

Request body

{
    "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
}

Request Parameters

Parameter Name
Description
Type
Required
DatasetName
Dataset name, unique within the same account. You can query it through the console or API
String
Yes
Query
Simple query parameter conditions that can be nested
Container
No
Sort
List of sort fields. For details, see Scalar Search Expression Syntax
Multiple sort fields can be separated by half-width commas (,), for example: Size,Filename
You can set up to 5 sort fields
The order of sort fields determines their priority
String
No
Order
Sort order of the sort fields. Valid values:
asc: Ascending
desc (default): Descending
Specify the rule information as follows:
Multiple sort methods can be separated by half-width commas (,), for example: asc,desc
The number of sort methods cannot exceed the number of sort fields. In other words, the number of elements in the Order parameter must be less than or equal to the number of elements in the Sort parameter. For example, if Sort is set to Size,Filename, Order can be asc,desc or asc
If the number of sort methods is less than the number of sort fields, the unspecified fields default to asc. For example, if Sort is set to Size,Filename and Order is set to asc, Filename defaults to asc, which means ascending order
String
No
MaxResults
Maximum number of file metadata entries to return
Valid values range from 0 to 200
When aggregate parameters are used, this value indicates the maximum number of groups to return, with a valid range of 0 - 2000
If this parameter is not set or is set to 0, the default value 100 is used
Integer
No
NextToken
token used for pagination when the total number of binding relationships exceeds the specified MaxResults
Returns the list of binding relationship information in lexicographic order starting from NextToken
Set this parameter to null when you call this API for the first time
String
No
Aggregations
List of aggregation field information
When you use aggregation queries, only aggregated results are returned, and the list of matched metadata is not returned
Container Array
No
WithFields
Returns only the values of specified fields instead of all existing metadata fields
Can be used to reduce the size of the returned structure
If this parameter is not specified or is left empty, all fields are returned
String Array
No
Query node content:
Parameter Name
Description
Type
Required
Operation
Operation operator. Enum values:
not: logical negation
or: logical OR
and: logical AND
lt: less than
lte: less than or equal to
gt: greater than
gte: greater than or equal to
eq: equal to
exist: existence query
prefix: prefix query
match-phrase: string match query
String
Yes
SubQueries
Structure for subqueries
Subquery conditions can be set only when Operations is a logical operator (and, or, not).
When the logical operator is and/or/not, all conditions described in its SubQueries must conform to the and/or/not logical relationship set by the parent
Container Array
No
Field
Field name. For supported fields, see Scalar Search Expression Syntax
String
No
Value
Field value to query. When Operations is a logical operator (and, or, not), this field is invalid
String
No
Aggregations node content:
Parameter Name
Description
Type
Required
Field
Field name. For supported fields, see Scalar Search Expression Syntax
String
No
Operation
Operator for aggregating fields. Enum values:
min: minimum value
max: maximum value
average: average
sum: sum
count: count
distinct: distinct count
group: group count, sorted in descending order by the group count result
String
No

Response

Response Headers

This API only returns common response headers. For details, see Common Response Headers.

Response Body

{
    "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": "image",
        "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****"
}
The specific data content of the response body is as follows:
Parameter Name
Type
Description
Aggregations
Container Array
List of aggregation field information. Returned only when Aggregations in the request is not empty
Files
Container Array
List of file information. Returned only when Aggregations in the request is empty
RequestId
String
Request ID
NextToken
String
Pagination marker
token used for pagination when the total number of files exceeds the configured MaxResults
This parameter has a value only when the information of matching files is not fully returned
Pass this value as NextToken the next time you list file information to return the subsequent file information
File node content:
Parameter Name
Type
Description
COSCRC64
String
File CRC64 value
COSStorageClass
String
File storage class
CacheControl
String
Specifies the caching behavior of the webpage when the Object is downloaded. This field requires setting the COS Object HTTP attribute Cache-Control
ContentType
String
File content type (MIME Type)
CreateTime
String
Timestamp of metadata creation time in RFC3339Nano format
CustomId
String
Custom ID of the file. After the file is indexed into the dataset, it is stored as an attribute of the metadata in that row for association and mapping with your business system. You can pass in this value based on your business requirements, for example, associating a URI with an ID in your system. It is recommended to pass in a globally unique value.
CustomLabels
Container
Custom tag list of the file. Stores the key names and key-value pairs defined by your business, which can be used as filter criteria for search during queries.
DatasetName
String
Data set name
ETag
String
When an Object is generated, a corresponding ETag is created. The ETag is used to identify the content of the Object.
FileModifiedTime
String
Timestamp of the file's last modification time in RFC3339Nano format
Filename
String
File path
MediaType
String
File media type. Enumerated values:
image: image
other: other
document: document
archive: archive
audio: audio
video: video
ObjectACL
String
File access permission attribute
Size
Int
File size, in bytes
URI
String
Resource identifier field, indicating the file address for which an index needs to be created.
UpdateTime
String
Timestamp of metadata modification time in RFC3339Nano format
After metadata is created, if it has not been updated, the timestamp of the metadata modification time is the same as the timestamp of the metadata creation time.
ObjectId
String
Unique object ID
ContentDisposition
String
Specifies the name of the Object when the Object is downloaded. The COS Object HTTP attribute Content-Disposition needs to be set.
ContentEncoding
String
Specifies the content encoding format of the Object when the Object is downloaded. The COS Object HTTP attribute Content-Encoding needs to be set.
ContentLanguage
String
Language used by the Object content. The COS Object HTTP attribute Content-Language needs to be set.
ServerSideEncryption
String
Encryption algorithm. The x-cos-server-side-encryption parameter needs to be set.
COSUserMeta
Container
COS custom headers. Stores the key names and key-value pairs of your business on COS objects, which can be used as filter criteria for search during queries.
COSTagging
Container
COS custom tags. Stores the key names and key-value pairs of your business custom tags on COS objects, which can be used as filter criteria for search during queries.
COSTaggingCount
Int
Number of COS custom tags
Aggregations node content:
Parameter Name
Type
Description
Field
String
Aggregation field name
Operation
String
Aggregation operator for the aggregation field
Value
Float
Aggregated statistical result
Groups
Container Array
List of group aggregation results. Returned only when the requested Aggregations contain group-type operations.
Groups node content:
Parameter Name
Type
Description
Value
String
Value after grouping and aggregation
Count
Integer
Total number of groups after aggregation

Practical Case

Case 1: Querying jpeg Images Larger Than 1000 in size

Request

POST /datasetquery/simple HTTP/1.1
Host: <AppId>.ci.ap-jakarta.myqcloud.com
Authorization: <Auth String>
Content-Length: <length>
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
}

Response

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": "image",
        "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****"
}

Case 2: Aggregating Queries by File Name

Request

POST /datasetquery/simple HTTP/1.1
Host: <AppId>.ci.ap-jakarta.myqcloud.com
Authorization: <Auth String>
Content-Length: <length>
Content-Type: application/json
Accept: application/json

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

Response

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": "Filename",
        "Groups": [{
            "Count": 1,
            "Value": "file001"
        }, {
            "Count": 1,
            "Value": "file002"
        }],
        "Operation": "group"
    }],
    "Files": [],
    "NextToken": ""
}

Topik sebelumnya: Deleting Metadata IndexTopik selanjutnya: Creating an Asynchronous Export Task

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation