All Products
Search

This Product

    Intelligent Media Management:SimpleQuery

    Document Center

    Intelligent Media Management:SimpleQuery

    Last Updated:Dec 11, 2024

    Queries files in a dataset by performing a simple query operation. The operation supports logical expressions.

    Operation description

    • Before you call this operation, make sure that you are familiar with the billing of Intelligent Media Management (IMM).****
    • Before you call this operation, make sure that you have indexed file metadata into the dataset automatically by calling the CreateBinding operation or manually by calling the IndexFileMeta or BatchIndexFileMeta operation.
    • The sample response is provided for reference only. The metadata type and content in your response may differ based on factors such as the workflow template configurations. For any inquiries, join the DingTalk chat group (ID: 31690030817) and share your questions with us.

    Limits

    • Each query returns information about up to 100 files.
    • Each query returns up to 2,000 aggregations.
    • A subquery supports up to 100 conditions.
    • A subquery can have a maximum nesting depth of 5 levels.

    Example query conditions

    • Retrieve JPEG images larger than 1,000 pixels:
    {
  "SubQueries":[
    {
      "Field":"ContentType",
      "Value": "image/jpeg",
      "Operation":"eq"
    },         
    {
      "Field":"ImageWidth",
      "Value":"1000",
      "Operation":"gt"
    }
  ],
  "Operation":"and"
}
    • Search oss://examplebucket/path/ for objects that have the TV or Stereo label and are larger than 10 MB in size:
    Note This query requires matching files to have the TV or Stereo label. The two labels are specified as separate objects in the Labels fields. 
    {
  "SubQueries": [
    {
      "Field": "URI",
      "Value": "oss://examplebucket/path/",
      "Operation": "prefix"
    },
    {
      "Field": "Size",
      "Value": "1048576",
      "Operation": "gt"
    },
    {
      "SubQueries": [
        {
          "Field": "Labels.LabelName",
          "Value": "TV",
          "Operation": "eq"
        },
        {
          "Field": "Labels.LabelName",
          "Value": "Stereo",
          "Operation": "eq"
        }
      ],
      "Operation": "or"
    }
  ],
  "Operation": "and"
}
    • Exclude images that contain a face of a male over the age of 36:
    Note In this example query, an image will be excluded from the query results if it contains a face of a male over the age of 36. This query is different from excluding an image that contains a male face or a face of a person over the age of 36. In this query, you need to use the nested operator to specify that the conditions are met on the same element. 
    {
	"Operation": "not",
	"SubQueries": [{
		"Operation": "nested",
		"SubQueries": [{
			"Operation": "and",
			"SubQueries": [{
				"Field": "Figures.Age",
				"Operation": "gt",
				"Value": "36"
			}, {
				"Field": "Figures.Gender",
				"Operation": "eq",
				"Value": "male"
			}]
		}]
	}]
}
    • Query JPEG images that have both custom labels and system labels:
    {
  "SubQueries":[
    {
      "Field":"ContentType",
      "Value": "image/jpeg",
      "Operation":"eq"
    },         
    {
      "Field":"CustomLabels.test",
      "Operation":"exist"
    },         
    {
      "Field":"Labels.LabelName",
      "Operation":"exist"
    }
  ],
  "Operation":"and"
}

    You can also perform aggregate operations to collect and analyze different data based on the specified conditions. For example, you can calculate the sum, count, average value, or maximum value of all files that meet the query conditions. You can also calculate the size distribution of images that meet the query conditions.

    Debugging

    You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    imm:SimpleQuerylist
    *Dataset
    acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}/dataset/{#DatasetName}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    NextTokenstringNo

    The pagination token is used in the next request to retrieve a new page of results if the total number of results exceeds the value of the MaxResults parameter.

    The next call to the operation returns results lexicographically after the NextToken parameter value.

    You do not need to specify this parameter in your initial request.

    		MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
    MaxResultsintegerNo
    • If the Aggregations parameter is not specified, this parameter specifies the maximum number of files that can be returned. Valid values: 1 to 100.
    • If the Aggregations parameter is specified, this parameter specifies the maximum number of aggregation groups that can be returned. Valid values: 0 to 2000.
    • If you do not specify this parameter or set the parameter to 0, the default value of 100 is used.
    		10
    ProjectNamestringYes

    The name of the project.

    		test-project
    DatasetNamestringYes

    The name of the dataset.

    		test-dataset
    QuerySimpleQueryNo

    The query conditions.

    SortstringNo

    The sort fields. For more information, see Supported fields and operators.

    Note

    • If you specify multiple sort fields, separate them with commas (,), as in Size,Filename.

    • You can specify up to five sort fields.

    • The order of the sort fields determines their precedence in the sorting process.

    		Size,Filename
    OrderstringNo

    The sort order. Valid values:

    • asc: sorts the results in ascending order.

    • desc: sorts the results in descending order. This is the default value.

    • You can specify multiple sort orders that are separated by commas. Example: asc,desc.

    • 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 the value of the Sort parameter is Size,Filename, you can set the Order parameter to desc,asc.

    • If the number of sort orders is less than the number of sort fields, the sort fields for which no sorting orders are explicitly specified use the asc order by default. For example, if you set Sort to Size,Filename and Order to asc, the Filename field defaults to the value of asc.

    		asc,desc
    Aggregationsarray<object>No

    The aggregations.

    Note If you perform an aggregate query, the aggregation returned in the response contains only statistical results, not the actual metadata.
    objectNo

    The structure of the aggregation.

    FieldstringNo

    The name of the field. For more information about supported fields, see Supported fields and operators.

    		Size
    OperationstringNo

    The operator.

    Enumerated values:

    • average: calculates the average number.
    • min: finds the minimum value.
    • max: finds the maximum value.
    • count: counts the number of results.
    • distinct: counts the number of distinct results.
    • sum: calculates the sum of all matching results..
    • group: counts the number of results by group. The results are sorted by the count number in descending order.
    		sum
    WithFieldsarrayNo

    The fields that you want to include in the response. You can use this parameter to reduce the size of the response.

    If you do not specify this parameter or leave this parameter empty, the operation returns all metadata fields.

    stringNo

    The name of the field. Fields in the File structure are supported.

    		Filename
    WithoutTotalHitsbooleanNo

    Specifies whether to return the total number of hits. Valid values:

    • true
    • false

    Response parameters

    ParameterTypeDescriptionExample
    object

    The response parameters.

    NextTokenstring

    The pagination token is used in the next request to retrieve a new page of results if the total number of results exceeds the value of the MaxResults parameter.

    It can be used in the next request to retrieve a new page of results.

    If NextToken is empty, no next page exists.

    		MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
    RequestIdstring

    The request ID.

    		2C5C1E0F-D8B8-4DA0-8127-EC32C771****
    Filesarray

    The files. This parameter is returned only when the value of the Aggregations request parameter is empty.

    FilesFile

    The information about the file.

    Aggregationsarray<object>

    The aggregations. This parameter is returned only when the value of the Aggregations request parameter is not empty.

    Aggregationsobject

    The structure of the aggregation.

    Fieldstring

    The name of the field.

    		Size
    Operationstring

    The operator.

    		sum
    Valuedouble

    The statistical result.

    		200
    Groupsarray<object>

    The grouped aggregations. This parameter is returned only when the group operator is specified in the Aggregations request parameter.

    Groupsobject

    The grouped aggregation.

    Valuestring

    The value for the grouped aggregation.

    		100
    Countlong

    The number of results in the grouped aggregation.

    		5
    TotalHitslong

    The number of total hits.

    		10

    Examples

    Sample success responses

    JSONformat

    {
  "NextToken": "MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==",
  "RequestId": "2C5C1E0F-D8B8-4DA0-8127-EC32C771****",
  "Files": [
    {
      "OwnerId": "102321002467****",
      "ProjectName": "test-project",
      "DatasetName": "test-dataset",
      "ObjectType": "file",
      "ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
      "UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
      "CreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "URI": "oss://examplebucket/sampleobject.jpg",
      "OSSURI": "oss://examplebucket/sampleobject.jpg",
      "Filename": "sampleobject.jpg",
      "MediaType": "image",
      "ContentType": "image/jpeg",
      "Size": 1000,
      "FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
      "FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
      "FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
      "ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
      "LatLong": "30.134390,120.074997",
      "Timezone": "",
      "Addresses": [
        {
          "Language": "zh-hans",
          "AddressLine": "",
          "Country": "",
          "Province": "",
          "City": "",
          "District": "",
          "Township": ""
        }
      ],
      "TravelClusterId": "-",
      "Orientation": 0,
      "Figures": [
        {
          "FigureId": "868a9e74-cde5-4c7a-9013-28bb984****",
          "FigureConfidence": 1,
          "FigureClusterId": "Cluster-dbe72fec-b84c-4ab6-885b-3678e64****",
          "FigureClusterConfidence": 1,
          "FigureType": "face",
          "Age": 29,
          "AgeSD": 5,
          "Gender": "female",
          "GenderConfidence": 1,
          "Emotion": "happiness",
          "EmotionConfidence": 0.70784568786621,
          "FaceQuality": 0.960875928401947,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          },
          "Mouth": "close",
          "MouthConfidence": 1,
          "Beard": "none",
          "BeardConfidence": 1,
          "Hat": "none",
          "HatConfidence": 1,
          "Mask": "none",
          "MaskConfidence": 1,
          "Glasses": "none",
          "GlassesConfidence": 0.8,
          "Sharpness": 0.7,
          "Attractive": 0.96,
          "HeadPose": {
            "Pitch": 18.385589599609375,
            "Roll": 4.204030513763428,
            "Yaw": 2.4945924282073975
          }
        }
      ],
      "FigureCount": 10,
      "Labels": [
        {
          "Language": "zh-Hans",
          "LabelName": "",
          "LabelLevel": 1,
          "LabelConfidence": 0.9891784601980591,
          "ParentLabelName": "",
          "CentricScore": 0.7319999933242798
        }
      ],
      "Title": "test",
      "ImageWidth": 270,
      "ImageHeight": 500,
      "EXIF": "{\"Compression\":{\"value\":\"6\"},\"DateTime\":{\"value\":\"2020:08:19 17:11:11\"}}",
      "ImageScore": {
        "OverallQualityScore": 0.736
      },
      "CroppingSuggestions": [
        {
          "AspectRatio": "2:3",
          "Confidence": 0.7079545259475708,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          }
        }
      ],
      "OCRContents": [
        {
          "Language": "zh-hans",
          "Contents": "",
          "Confidence": 0.8254936695098877,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          }
        }
      ],
      "VideoWidth": 1080,
      "VideoHeight": 1920,
      "VideoStreams": [
        {
          "Index": 0,
          "Language": "en",
          "CodecName": "h264",
          "CodecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "Profile": "High",
          "CodecTimeBase": "1373627/83160000",
          "CodecTagString": "avc1",
          "CodecTag": "0x31637661",
          "Width": 1280,
          "Height": 720,
          "HasBFrames": 2,
          "SampleAspectRatio": "1:1",
          "DisplayAspectRatio": "16:9",
          "PixelFormat": "yuv420p",
          "Level": 40,
          "FrameRate": "25/1",
          "AverageFrameRate": "25/1",
          "TimeBase": "1/12800",
          "StartTime": 0,
          "Duration": 22.88,
          "Bitrate": 5407765,
          "FrameCount": 572,
          "Rotate": "90",
          "BitDepth": 8,
          "ColorSpace": "bt709",
          "ColorRange": "tv",
          "ColorTransfer": "bt709",
          "ColorPrimaries": "bt709"
        }
      ],
      "Subtitles": [
        {
          "Index": 2,
          "Language": "en",
          "CodecName": "mov_text",
          "CodecLongName": "MOV text",
          "CodecTagString": "tx3g",
          "CodecTag": "0x67337874",
          "StartTime": 0,
          "Duration": 71.378,
          "Bitrate": 74,
          "Content": "",
          "Width": 600,
          "Height": 30
        }
      ],
      "AudioStreams": [
        {
          "Index": 1,
          "Language": "en",
          "CodecName": "aac",
          "CodecLongName": "AAC (Advanced Audio Coding)",
          "CodecTimeBase": "1/44100",
          "CodecTagString": "mp4a",
          "CodecTag": "0x6134706d",
          "TimeBase": "1/48000",
          "StartTime": 0.0235,
          "Duration": 3.690667,
          "Bitrate": 320087,
          "FrameCount": 173,
          "Lyric": "test",
          "SampleFormat": "fltp",
          "SampleRate": 48000,
          "Channels": 2,
          "ChannelLayout": "stereo"
        }
      ],
      "Artist": "Jane",
      "AlbumArtist": "Jane",
      "AudioCovers": [
        {
          "ImageWidth": 500,
          "ImageHeight": 820,
          "EXIF": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"}}",
          "ImageScore": {
            "OverallQualityScore": 0.736
          },
          "CroppingSuggestions": [
            {
              "AspectRatio": "2:3",
              "Confidence": 0.7079545259475708
            }
          ],
          "OCRContents": [
            {
              "Language": "zh-hans",
              "Contents": "",
              "Confidence": 0.8254936695098877
            }
          ]
        }
      ],
      "Composer": "Jane",
      "Performer": "Jane",
      "Language": "eng",
      "Album": "FirstAlbum",
      "PageCount": 5,
      "ETag": "\"1D9C280A7C4F67F7EF873E28449****\"",
      "CacheControl": "no-cache",
      "ContentDisposition": "attachment; filename =test.jpg",
      "ContentEncoding": "UTF-8",
      "ContentLanguage": "zh-CN",
      "AccessControlAllowOrigin": "https://aliyundoc.com",
      "AccessControlRequestMethod": "PUT",
      "ServerSideEncryptionCustomerAlgorithm": "SM4",
      "ServerSideEncryption": "AES256",
      "ServerSideDataEncryption": "SM4",
      "ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
      "OSSStorageClass": "Standard",
      "OSSCRC64": "559890638950338001",
      "ObjectACL": "default",
      "ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
      "OSSUserMeta": {
        "key": "val"
      },
      "OSSTaggingCount": 2,
      "OSSTagging": {
        "key": "val"
      },
      "OSSExpiration": "2120-01-01T12:00:00.000Z",
      "OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
      "OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
      "OSSObjectType": "Normal",
      "CustomId": "\t\nmember-image-id-0001",
      "CustomLabels": {
        "MemberName": "Tim",
        "Enabled": "True",
        "ItemCount": "10"
      },
      "StreamCount": 1,
      "ProgramCount": 1,
      "FormatName": "mov",
      "FormatLongName": "QuickTime / MOV",
      "StartTime": 0,
      "Bitrate": 13091201,
      "Duration": 15.263,
      "SemanticSimilarity": 0.855123,
      "SemanticTypes": [
        "content"
      ],
      "Elements": [
        {
          "ElementContents": [
            {
              "Type": "text",
              "Content": "",
              "URL": "http://aliyun.com",
              "TimeRange": [
                0
              ]
            }
          ],
          "ObjectId": "",
          "ElementType": "",
          "SemanticSimilarity": 0,
          "ElementRelations": [
            {
              "Type": "",
              "ObjectId": ""
            }
          ]
        }
      ],
      "SceneElements": [
        {
          "TimeRange": [
            0
          ],
          "FrameTimes": [
            0
          ]
        }
      ],
      "OCRTexts": "Alibaba Cloud IMM\n",
      "FileStatus": "",
      "Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
      "SmartClusters": [
        {
          "SmartClusterId": "",
          "Similarity": 0
        }
      ],
      "ObjectStatus": "Indexed",
      "SequenceNumber": 3,
      "ClusterStatus": {
        "key": {
          "key": [
            ""
          ]
        }
      },
      "ClusterModifications": {
        "key": {
          "key": [
            ""
          ]
        }
      }
    }
  ],
  "Aggregations": [
    {
      "Field": "Size",
      "Operation": "sum",
      "Value": 200,
      "Groups": [
        {
          "Value": "100",
          "Count": 5
        }
      ]
    }
  ],
  "TotalHits": 10
}

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2023-11-22The request parameters of the API has changedView Change Details
    2023-09-04The response structure of the API has changedView Change Details
    2022-01-25The response structure of the API has changedView Change Details
    2021-06-15Add OperationView Change Details