The queryVectors interface retrieves a list of vectors most similar to a target vector. This article explains how to perform vector similarity queries and return TopK results using the queryVectors interface of TOS Vectors Java SDK.

Notes

You need to fill in the region and access domain in the sample code according to your actual situation. For details, see region and access domain (endpoint).

To prevent key leakage, this example reads the Access Key ID and Secret Access Key from environment variables. Before using the SDK, configure long-term access credentials. For details, see configure long-term access credentials.

TOS Vectors Java SDK supports temporary access credentials and also supports timeout mechanisms, retry policies, and other settings. You can adjust these flexibly based on business needs to enhance application security. For details, see common configuration scenarios.

Permissions required

The primary account has all permissions by default, while IAM users have none by default. If you need to perform queryVectors operations using a sub-account, the primary account must grant the following permissions to the sub-account through IAM policies and bucket policies:

tosvectors:QueryVectors

Code example

Query nearest TopK vectors

// Query the nearest TopK vectors.​
import com.volcengine.tos.TOSVectorsClientBuilder;​
import com.volcengine.tos.TOSVectors;​
import com.volcengine.tos.TosClientException;​
import com.volcengine.tos.TosServerException;​
import com.volcengine.tos.model.vectors.QueryVectorsInput;​
import com.volcengine.tos.model.vectors.QueryVectorsOutput;​
import com.volcengine.tos.model.vectors.VectorData;​
import com.volcengine.tos.model.vectors.DistanceVector;​
​
import java.util.HashMap;​
import java.util.Map;​
​
public class QueryVectorsExample {​
    public static void main(String[] args) {​
        String endpoint = 'Provide your endpoint';​
        String region = 'Provide your region';​
        String accessKey = System.getenv("TOS_ACCESS_KEY");​
        String secretKey = System.getenv("TOS_SECRET_KEY");​
        String accountID = System.getenv("TOS_ACCOUNT_ID");​
​
        // Fill in BucketName.​
        String bucketName = 'Provide your bucket name';​
​
        // Initialize client.​
        TOSVectors client = new TOSVectorsClientBuilder().build(region, endpoint, accessKey, secretKey);​
​
        try {​
            // Prepare query vector data (128-dimensional floating-point vector).​
            float[] queryVector = new float[128];​
            for (int i = 0; i < 128; i++) {​
                queryVector[i] = (float) Math.random();​
            }​
​
            // Set filter (optional).​
//            Map<String, Object> filter = new HashMap<>();​
//            filter.put("category", "A");​
​
            // Construct a query request.​
            QueryVectorsInput input = QueryVectorsInput.builder()​
                    .vectorBucketName(bucketName)​
                    .accountId(accountID)​
                    .indexName("testindex")  // Replace with the actual index name.​
                    .topK(5)  // Query the 5 most similar vectors.​
                    .returnDistance(true)  // Return distance information.​
                    .returnMetadata(true)  // Return metadata information.​
                    .queryVector(VectorData.builder().float32(queryVector).build())​
                    //.filter(filter)  // Optional: Add a filter.​
                    .build();​
​
            // Execute the query.​
            QueryVectorsOutput output = client.queryVectors(input);​
​
            // Process query results.​
            System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
            System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
            ​
            if (output.getVectors() != null && !output.getVectors().isEmpty()) {​
                System.out.println("" + output.getVectors().size() + " similar vectors were found:");​
                for (int i = 0; i < output.getVectors().size(); i++) {​
                    DistanceVector vector = output.getVectors().get(i);​
                    System.out.println("Vector " + (i + 1) + ":");​
                    System.out.println("  Key: " + vector.getKey());​
                    System.out.println("  Distance: " + vector.getDistance());​
                    if (vector.getMetadata() != null) {​
                        System.out.println("  Metadata: " + vector.getMetadata());​
                    }​
                }​
            } else {​
                System.out.println("No similar vectors were found");​
            }​
​
        } catch (TosClientException e) {​
            // Operation failed, caught Client exception. Generally, it is a request parameter error, and in this case, the request was not sent.​
            System.out.println("Operation failed");​
            System.out.println("Message: " + e.getMessage());​
            if (e.getCause() != null) {​
                e.getCause().printStackTrace();​
            }​
        } catch (TosServerException e) {​
            // Operation failed, server exception captured, and detailed error information returned from the server can be obtained.​
            System.out.println("Operation failed");​
            System.out.println("StatusCode: " + e.getStatusCode());​
            System.out.println("Code: " + e.getCode());​
            System.out.println("Message: " + e.getMessage());​
            System.out.println("RequestID: " + e.getRequestID());​
        } catch (Throwable t) {​
            // As a fallback to catch other exceptions, it generally won't execute here.​
            System.out.println("Operation failed");​
            System.out.println("unexpected exception, message: " + t.getMessage());​
        }​
    }​
}​