Use Java SDK for vector search - Object Storage Service - Alibaba Cloud Documentation Center

OSS vector search lets you find objects from a large bucket based on semantic content, OSS metadata, multimedia metadata, ETags, tags, and custom metadata—without knowing exact filenames or paths.

How it works

Vector search is built on OSS metadata management. A typical workflow follows four steps:

Enable vector search on the bucket. OSS starts building a semantic index of your objects.
Check the index status to confirm the index is ready before running queries.
Query objects by natural language description, media type, or object attributes.
Disable vector search when you no longer need the index.

Prerequisites

Before you begin, ensure you have:

Java SDK version 3.18.2 or later
A bucket in a supported region
The required permissions (see below)

Permissions

An Alibaba Cloud root account has all required permissions by default. For Resource Access Management (RAM) users or Security Token Service (STS), grant the following permissions:

Operation	Required permission
Enable vector search	`oss:OpenMetaQuery`
Get metadata index status	`oss:GetMetaQueryStatus`
Query objects	`oss:DoMetaQuery`
Disable vector search	`oss:CloseMetaQuery`

Supported regions

China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hangzhou), China (Shanghai), China (Shenzhen), China (Guangzhou), China (Chengdu), China (Hong Kong), Singapore, Indonesia (Jakarta), Germany (Frankfurt), US (Virginia), and US (Silicon Valley).

Client setup

All examples use the following client configuration. Replace the endpoint and region with your bucket's actual values.

Credentials are loaded from the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables. For other credential options, see Configure access credentials.

The examples use the public endpoint for China (Hangzhou). To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. For a full list of endpoints, see OSS regions and endpoints.

String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
String bucketName = "examplebucket";
String region = "cn-hangzhou";

EnvironmentVariableCredentialsProvider credentialsProvider =
    CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

OSS ossClient = OSSClientBuilder.create()
    .endpoint(endpoint)
    .credentialsProvider(credentialsProvider)
    .clientConfiguration(clientBuilderConfiguration)
    .region(region)
    .build();

Enable vector search

Call openMetaQuery with MetaQueryMode.SEMANTIC to enable vector search on the bucket. OSS starts indexing objects.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.MetaQueryMode;

public class OpenMetaQuery {
    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String bucketName = "examplebucket";
        String region = "cn-hangzhou";

        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
            .endpoint(endpoint)
            .credentialsProvider(credentialsProvider)
            .clientConfiguration(clientBuilderConfiguration)
            .region(region)
            .build();

        try {
            // MetaQueryMode.SEMANTIC enables vector (semantic) search mode.
            ossClient.openMetaQuery(bucketName, MetaQueryMode.SEMANTIC);
        } catch (OSSException oe) {
            // OSSException indicates a server-side error (e.g., permission denied, invalid bucket).
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            // ClientException indicates a client-side error (e.g., network issue, misconfiguration).
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Get metadata index status

Before running queries, confirm the index is ready. Call getMetaQueryStatus to retrieve the current index state.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetMetaQueryStatusResult;

public class GetMetaQueryStatus {
    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String bucketName = "examplebucket";
        String region = "cn-hangzhou";

        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
            .endpoint(endpoint)
            .credentialsProvider(credentialsProvider)
            .clientConfiguration(clientBuilderConfiguration)
            .region(region)
            .build();

        try {
            GetMetaQueryStatusResult result = ossClient.getMetaQueryStatus(bucketName);
            System.out.println("Mode: " + result.getMetaQueryMode());   // retrieval pattern
            System.out.println("Phase: " + result.getPhase());          // current scan type
            System.out.println("State: " + result.getState());          // status of the metadata index
            System.out.println("Created: " + result.getCreateTime());
            System.out.println("Updated: " + result.getUpdateTime());
        } catch (OSSException oe) {
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Query objects

Call doMetaQuery to search for objects by semantic content and attribute filters. The example below finds up to 20 images that match the query "Snow" and have a size greater than 30 bytes, sorted by size.

DoMetaQueryRequest accepts the following parameters:

Parameter	Description	Example
`bucketName`	Target bucket	`"examplebucket"`
`maxResults`	Maximum number of results to return	`20`
`query`	Natural language description for semantic search	`"Snow"`
`sort`	Object attribute to sort results by	`"Size"`
`MetaQueryMode`	Search mode — use `SEMANTIC` for vector search	`MetaQueryMode.SEMANTIC`
`mediaTypes`	Filter by media type (e.g., `"image"`, `"video"`)	`["image"]`
`simpleQuery`	JSON filter on object attributes	`{"Operation":"gt","Field":"Size","Value":"30"}`

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;

public class DoMetaQuery {
    public static void main(String[] args) throws Exception {
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String bucketName = "examplebucket";
        String region = "cn-hangzhou";

        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
            .endpoint(endpoint)
            .credentialsProvider(credentialsProvider)
            .clientConfiguration(clientBuilderConfiguration)
            .region(region)
            .build();

        try {
            int maxResults = 20;
            List<String> mediaTypes = new ArrayList<>();
            mediaTypes.add("image");

            String query = "Snow";
            String simpleQuery = "{\"Operation\":\"gt\", \"Field\": \"Size\", \"Value\": \"30\"}";
            String sort = "Size";

            DoMetaQueryRequest doMetaQueryRequest = new DoMetaQueryRequest(
                bucketName, maxResults, query, sort,
                MetaQueryMode.SEMANTIC, mediaTypes, simpleQuery
            );
            DoMetaQueryResult doMetaQueryResult = ossClient.doMetaQuery(doMetaQueryRequest);
        } catch (OSSException oe) {
            System.out.println("Error Message: " + oe.getErrorMessage());
            System.out.println("Error Code: " + oe.getErrorCode());
            System.out.println("Request ID: " + oe.getRequestId());
            System.out.println("Host ID: " + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Disable vector search

Call closeMetaQuery to disable vector search on the bucket.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

public class CloseMetaQuery {
    public static void main(String[] args) throws Exception {
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String bucketName = "examplebucket";
        String region = "cn-hangzhou";

        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
            .endpoint(endpoint)
            .credentialsProvider(credentialsProvider)
            .clientConfiguration(clientBuilderConfiguration)
            .region(region)
            .build();

        try {
            ossClient.closeMetaQuery(bucketName);
        } catch (OSSException oe) {
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Error Message: " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Object Storage Service:Vector search (Java SDK V1)