New MetaQuery features

Use cases

• Fine-grained search for mixed multi-device and multi-service data: Store videos from entrance, warehouse, and office cameras, or images from multiple applications, in a single bucket. Create a separate Dataset for each source to restrict queries to the target Dataset, preventing interference between services.

• Cross-language content understanding and search: Configure different output languages for Insights, such as Chinese or English, for each Dataset. This ensures that AI-generated descriptions match the service's language, which simplifies cross-language search and display.

• Custom event detection: For security or inspection services, configure custom event tags (for example, "person fell down") for a Dataset. When videos are ingested, they are automatically tagged, enabling you to later search directly for files that match these event tags.

• Smart grouping (SmartCluster): Automatically cluster and group faces, images, or other objects within a Dataset to support applications such as photo albums and media asset libraries.

How it works

The new MetaQuery uses Datasets as the core unit for organizing metadata and AI processing. The overall workflow is as follows:

1. Enable and route: Enable MetaQuery for a bucket in semantic mode. If you need multiple Datasets, configure a RouteRule when you enable the feature. This rule specifies which OSS object tag to use for routing files to different Datasets.

2. Process by Dataset: MetaQuery routes files to the corresponding Dataset based on their tag and then processes them for AI content awareness according to that Dataset's DatasetConfig (for example, image or video content descriptions, Insights language, and custom event tags). The results are written to the Dataset's metadata.

3. Dataset-level query: After indexing is complete, use SimpleQuery for structured queries or SemanticQuery for natural language semantic search within a specific Dataset. The query returns only files from that Dataset.

4. Smart grouping (optional): Use a SmartCluster to automatically cluster and group files within a Dataset.

New vs. legacy versions

Limitations

The RouteRule takes effect only when mode=semantic and is set when you enable MetaQuery. To change the rule, you must first call CloseMetaQuery and then call OpenMetaQuery again. This action clears all indexed metadata.

Step 1: Enable MetaQuery

Enable MetaQuery for the target bucket in semantic mode. Before you run the code, configure your access credentials by using the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables. Replace examplebucket with the name of your bucket.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.OpenMetaQueryRequest;
import com.aliyun.sdk.service.oss2.models.OpenMetaQueryResult;

public class OpenMetaQuerySample {
    public static void main(String[] args) throws Exception {
        try (OSSClient client = OSSClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            OpenMetaQueryResult result = client.openMetaQuery(OpenMetaQueryRequest.newBuilder()
                    .bucket("examplebucket")
                    .mode("semantic")
                    .build());
            System.out.println("open meta query status: " + result.statusCode());
        }
    }
}

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	client := oss.NewClient(cfg)

	_, err := client.OpenMetaQuery(context.TODO(), &oss.OpenMetaQueryRequest{
		Bucket: oss.Ptr("examplebucket"),
		Mode:   oss.Ptr("semantic"),
	})
	if err != nil {
		log.Fatalf("open meta query failed: %v", err)
	}
	log.Println("open meta query success")
}

To route files to different Datasets, configure a RouteRule when you enable the feature. The following RouteRule reads the routing-dataset tag from a file and routes the file to a Dataset with the same name. If the Dataset does not exist, MetaQuery creates it automatically.

<RouteRule>
  <Type>OSSTag</Type>
  <OSSTagKey>routing-dataset</OSSTagKey>
  <AutoCreateDataset>True</AutoCreateDataset>
</RouteRule>

Step 2: Create and configure a Dataset

DatasetConfig is the unified configuration entry point for AI content awareness and smart grouping. The following example creates a Dataset named photos-en and configures it to generate image content descriptions (Insights) in English.

import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.dataprocess.OSSDataProcessClient;
import com.aliyun.sdk.service.oss2.dataprocess.models.CreateDatasetRequest;

public class CreateDatasetSample {
    public static void main(String[] args) throws Exception {
        // Use DatasetConfig (in JSON format) to specify the AI content awareness configuration.
        // This example sets the output language for image content descriptions (Insights) to English.
        String datasetConfig = "{\n" +
                "  \"Insights\": {\n" +
                "    \"Language\": \"en\",\n" +
                "    \"Image\": {\n" +
                "      \"Caption\": { \"Enable\": \"true\" }\n" +
                "    }\n" +
                "  }\n" +
                "}";
        try (OSSDataProcessClient client = OSSDataProcessClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            client.createDataset(CreateDatasetRequest.newBuilder()
                    .bucket("examplebucket")
                    .datasetName("photos-en")
                    .datasetConfig(datasetConfig)
                    .build());
            System.out.println("create dataset success");
        }
    }
}

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/dataprocess"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	client := dataprocess.NewClient(cfg)

	// Use DatasetConfig (in JSON format) to set the output language for this Dataset's
    // image content descriptions (Insights) to English.
	datasetConfig := `{
  "Insights": {
    "Language": "en",
    "Image": {
      "Caption": { "Enable": "true" }
    }
  }
}`

	_, err := client.CreateDataset(context.TODO(), &dataprocess.CreateDatasetRequest{
		Bucket:        oss.Ptr("examplebucket"),
		DatasetName:   oss.Ptr("photos-en"),
		DatasetConfig: oss.Ptr(datasetConfig),
	})
	if err != nil {
		log.Fatalf("create dataset failed: %v", err)
	}
	log.Println("create dataset success")
}

Step 3: Upload and route a file

After you configure a RouteRule, set the corresponding OSS object tag when you upload a file to route it to the target Dataset. The following example routes the photos/snow.jpg file to the photos-en Dataset.

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.PutObjectRequest;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import java.nio.file.Files;
import java.nio.file.Paths;

public class PutObjectSample {
    public static void main(String[] args) throws Exception {
        try (OSSClient client = OSSClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            // Route the file to the photos-en Dataset by using an object tag.
            client.putObject(PutObjectRequest.newBuilder()
                    .bucket("examplebucket")
                    .key("photos/snow.jpg")
                    .tagging("routing-dataset=photos-en")
                    .body(BinaryData.fromStream(Files.newInputStream(Paths.get("/local/path/snow.jpg"))))
                    .build());
            System.out.println("put object success");
        }
    }
}

package main

import (
	"context"
	"log"
	"os"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	client := oss.NewClient(cfg)

	file, err := os.Open("/local/path/snow.jpg")
	if err != nil {
		log.Fatalf("open file failed: %v", err)
	}
	defer file.Close()

	// Route the file to the photos-en Dataset by using an object tag.
	_, err = client.PutObject(context.TODO(), &oss.PutObjectRequest{
		Bucket:  oss.Ptr("examplebucket"),
		Key:     oss.Ptr("photos/snow.jpg"),
		Tagging: oss.Ptr("routing-dataset=photos-en"),
		Body:    file,
	})
	if err != nil {
		log.Fatalf("put object failed: %v", err)
	}
	log.Println("put object success")
}

Step 4: Query within a Dataset

After indexing is complete, you can use Dataset-level query APIs to search within a specific Dataset. The following example uses SimpleQuery to perform a structured query. For natural language semantic search, you can use SemanticQuery instead.

import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.dataprocess.OSSDataProcessClient;
import com.aliyun.sdk.service.oss2.dataprocess.models.File;
import com.aliyun.sdk.service.oss2.dataprocess.models.Label;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQuery;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQueryRequest;
import com.aliyun.sdk.service.oss2.dataprocess.models.SimpleQueryResult;
import java.util.Arrays;

public class SimpleQueryLabelSample {
    public static void main(String[] args) throws Exception {
        try (OSSDataProcessClient client = OSSDataProcessClient.newBuilder()
                .region("cn-hangzhou")
                .credentialsProvider(new EnvironmentVariableCredentialsProvider())
                .build()) {
            SimpleQueryResult result = client.simpleQuery(SimpleQueryRequest.newBuilder()
                    .bucket("examplebucket")
                    .datasetName("security-events")
                    .query(SimpleQuery.newBuilder()
                            .field("Labels.LabelName")
                            .value("person fell down")
                            .operation("eq")
                            .build())
                    .withFields(Arrays.asList("Filename", "URI", "Labels"))
                    .maxResults(20)
                    .build());
            for (File file : result.files()) {
                StringBuilder names = new StringBuilder();
                if (file.labels() != null) {
                    for (Label label : file.labels()) {
                        names.append(label.labelName()).append(" ");
                    }
                }
                System.out.println(file.filename() + " -> " + names);
            }
        }
    }
}

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/dataprocess"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	client := dataprocess.NewClient(cfg)

	result, err := client.SimpleQuery(context.TODO(), &dataprocess.SimpleQueryRequest{
		Bucket:      oss.Ptr("examplebucket"),
		DatasetName: oss.Ptr("security-events"),
		Query:       oss.Ptr(`{"Field":"Labels.LabelName","Value":"person fell down","Operation":"eq"}`),
		WithFields:  oss.Ptr(`["Filename","URI","Labels"]`),
		MaxResults:  oss.Ptr(int32(20)),
	})
	if err != nil {
		log.Fatalf("simple query failed: %v", err)
	}
	for _, file := range result.Files {
		log.Printf("%s %v", oss.ToString(file.Filename), file.Labels)
	}
}

API reference

The new version of MetaQuery retains the OpenMetaQuery, GetMetaQueryStatus, CloseMetaQuery, and DoMetaQuery APIs, and adds the following APIs.