Use Go SDK V2 for scalar retrieval - Object Storage Service

Scalar retrieval lets you query objects in a bucket based on their metadata, so you can filter and retrieve object lists without scanning the entire bucket.

This topic shows how to use the OSS Go SDK V2 to enable the metadata index library, query objects by condition, check library status, and disable the library when it's no longer needed.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket
The OSS Go SDK V2 installed: github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss
Access credentials configured as environment variables. For setup instructions, see Configure access credentials

Usage notes

The sample code uses cn-hangzhou as the region. Replace it with your bucket's region.
A public endpoint is used by default. To access OSS from another Alibaba Cloud service in the same region, use an internal endpoint. See OSS regions and endpoints for the full list.

How it works

All examples in this topic follow the same pattern:

Load the default client configuration with environment variable credentials and a region.
Create a client with oss.NewClient(cfg).
Build a request struct for the target operation.
Call the corresponding client method and handle the result.

The client is initialized once and reused across all operations:

cfg := oss.LoadDefaultConfig().
    WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
    WithRegion(region)

client := oss.NewClient(cfg)

Enable the metadata management feature

API: OpenMetaQuery

Call OpenMetaQuery to enable metadata management for a bucket. OSS creates a metadata index library for the bucket, indexes all existing objects, and then performs near real-time incremental scans to index new objects as they are uploaded.

package main

import (
	"context"
	"flag"
	"log"

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

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.OpenMetaQueryRequest{
		Bucket: oss.Ptr(bucketName),
	}
	result, err := client.OpenMetaQuery(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to open meta query %v", err)
	}

	log.Printf("open meta query result:%#v\n", result)
}

Get the metadata index library status

API: GetMetaQueryStatus

Call GetMetaQueryStatus to retrieve the current status of the metadata index library for a bucket.

package main

import (
	"context"
	"flag"
	"log"

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

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.GetMetaQueryStatusRequest{
		Bucket: oss.Ptr(bucketName),
	}
	result, err := client.GetMetaQueryStatus(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get meta query status %v", err)
	}

	log.Printf("get meta query status result:%#v\n", result)
}

Query objects by condition

API: DoMetaQuery

Call DoMetaQuery to search for objects that match a query condition. The query is a JSON string that specifies a field, a comparison operator, and a value. Results can be sorted and retrieved in pages using NextToken.

The example below queries objects larger than 1 MB, sorted by size in ascending order:

package main

import (
	"context"
	"flag"
	"fmt"
	"log"

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

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.DoMetaQueryRequest{
		Bucket: oss.Ptr(bucketName),
		MetaQuery: &oss.MetaQuery{
			// Query condition: objects that are larger than 1 MB.
			Query: oss.Ptr(`{"Field": "Size","Value": "1048576","Operation": "gt"}`),
			Sort:  oss.Ptr("Size"),
			Order: oss.Ptr(oss.MetaQueryOrderAsc),
		},
	}
	result, err := client.DoMetaQuery(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to do meta query %v", err)
	}

	// Use NextToken to retrieve the next page of results.
	fmt.Printf("NextToken:%s\n", *result.NextToken)

	for _, file := range result.Files {
		fmt.Printf("File name: %s\n", *file.Filename)
		fmt.Printf("Size: %d\n", file.Size)
		fmt.Printf("Last modified: %s\n", *file.FileModifiedTime)
		fmt.Printf("Object type: %s\n", *file.OSSObjectType)
		fmt.Printf("Storage class: %s\n", *file.OSSStorageClass)
		fmt.Printf("ACL: %s\n", *file.ObjectACL)
		fmt.Printf("ETag: %s\n", *file.ETag)
		fmt.Printf("CRC-64: %s\n", *file.OSSCRC64)
		if file.OSSTaggingCount != nil {
			fmt.Printf("Tag count: %d\n", *file.OSSTaggingCount)
		}

		for _, tag := range file.OSSTagging {
			fmt.Printf("Tag key: %s, Tag value: %s\n", *tag.Key, *tag.Value)
		}

		for _, meta := range file.OSSUserMeta {
			fmt.Printf("User metadata key: %s, value: %s\n", *meta.Key, *meta.Value)
		}
	}
}

For the full list of supported fields and operators, see Data indexing.

Disable the metadata management feature

API: CloseMetaQuery

Call CloseMetaQuery to disable metadata management for a bucket.

package main

import (
	"context"
	"flag"
	"log"

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

var (
	region     string
	bucketName string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	flag.Parse()

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	request := &oss.CloseMetaQueryRequest{
		Bucket: oss.Ptr(bucketName),
	}
	result, err := client.CloseMetaQuery(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to close meta query %v", err)
	}

	log.Printf("close meta query result:%#v\n", result)
}

What's next

For a conceptual overview of scalar retrieval, see Scalar retrieval.
For all API operations related to data indexing, see Data indexing.
For the complete sample code, see the GitHub example.