The listVectors interface enumerates the vector collections in a specified space. This article explains how to use the listVectors interface of the TOS Vectors Java SDK to retrieve a vector list with support for pagination and filtering conditions.

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, the sample code reads the Access Key ID and Secret Access Key from environment variables. Therefore, before using the SDK, you need to configure long-term access credentials. For details, see Configure Long-Term Access Credentials.

The TOS Vectors Java SDK supports temporary access credentials; it also supports timeout settings, retry policies, and other mechanisms. You can configure these flexibly according to your business needs to improve application security. For details, see Common Configuration Scenarios.

Permissions required

The main account has all permissions by default, but IAM users do not have any permissions by default. If a subaccount needs to perform the listVectors operation, the main account must grant the following permissions to the subaccount through IAM policies and bucket policies:

tosvectors:ListVectors

Code examples

List basic vector usage

// List the basic usage of the 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.ListVectorsInput;​
import com.volcengine.tos.model.vectors.ListVectorsOutput;​
import com.volcengine.tos.model.vectors.Vector;​
​
public class ListVectorsExample {​
    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 the vector bucket name and index name.​
        String vectorBucketName = 'Provide your vector bucket name';​
        String indexName = "testindex";​
​
        // Initialize client.​
        TOSVectors client = new TOSVectorsClientBuilder().build(region, endpoint, accessKey, secretKey);​
​
        try {​
            // Create a list vector request and set basic parameters.​
            ListVectorsInput input = ListVectorsInput.builder()​
                    .vectorBucketName(vectorBucketName)​
                    .accountId(accountID)​
                    .indexName(indexName)​
                    .returnData(true)​
                    .returnMetadata(true)​
                    .build();​
            ​
            // Call the list vector interface.​
            ListVectorsOutput output = client.listVectors(input);​
            ​
            // Process the return result.​
            System.out.println("List vector successfully");​
            System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
            System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
            ​
            // Print vector list information.​
            if (output.getVectors() != null && !output.getVectors().isEmpty()) {​
                System.out.println("Vector quantity: " + output.getVectors().size());​
                for (Vector vector : output.getVectors()) {​
                    System.out.println("Vector Key: " + vector.getKey());​
                    if (vector.getData() != null) {​
                        System.out.println("Vector data dimension: " + vector.getData().getFloat32().length);​
                    }​
                    if (vector.getMetadata() != null) {​
                        System.out.println("Vector metadata: " + vector.getMetadata());​
                    }​
                }​
            } else {​
                System.out.println("Vector not found");​
            }​
​
        } catch (TosClientException e) {​
            // Operation failed, caught a Client exception. Generally, it is due to incorrect request parameters, 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, this generally won't be executed.​
            System.out.println("Operation failed");​
            System.out.println("unexpected exception, message: " + t.getMessage());​
        }​
    }​
}​

List vectors with pagination

// Paginated list of 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.ListVectorsInput;​
import com.volcengine.tos.model.vectors.ListVectorsOutput;​
import com.volcengine.tos.model.vectors.Vector;​
import java.util.ArrayList;​
import java.util.List;​
​
public class ListVectorsExample2 {​
    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 the vector bucket name and index name.​
        String vectorBucketName = 'Provide your vector bucket name';​
        String indexName = "testindex";​
​
        // Initialize client.​
        TOSVectors client = new TOSVectorsClientBuilder().build(region, endpoint, accessKey, secretKey);​
​
        try {​
            // Pagination parameter settings.​
            int pageSize = 2; // Number of vectors displayed per page.​
            String nextToken = null; // Pagination token.​
            List<String> allVectorKeys = new ArrayList<>(); // Key for storing all vectors.​
            int totalVectors = 0; // Total number of vectors.​
            ​
            System.out.println("Begin paginated listing of vectors...");​
            ​
            // Loop through the list until there is no more data.​
            int pageNum = 1;​
            do {​
                // Create a paginated list of vectors please.​
                ListVectorsInput input = ListVectorsInput.builder()​
                        .vectorBucketName(vectorBucketName)​
                        .accountId(accountID)​
                        .indexName(indexName)​
                        .maxResults(pageSize) // Set the number of items per page.​
                        .nextToken(nextToken) // Set pagination command.​
                        .returnData(false) // Does not return vector data, only returns the key.​
                        .returnMetadata(false) // Do not return metadata.​
                        .build();​
                ​
                // Call the list vector interface.​
                ListVectorsOutput output = client.listVectors(input);​
                ​
                System.out.println("\n Page " + pageNum + ":");​
                System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
                System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
                ​
                // Process the vectors on the current page.​
                if (output.getVectors() != null && !output.getVectors().isEmpty()) {​
                    int currentPageSize = output.getVectors().size();​
                    totalVectors += currentPageSize;​
                    System.out.println("Number of vectors on the current page: " + currentPageSize);​
                    ​
                    // Collect the keys of all vectors.​
                    for (Vector vector : output.getVectors()) {​
                        allVectorKeys.add(vector.getKey());​
                        System.out.println("  Vector Key: " + vector.getKey());​
                    }​
                } else {​
                    System.out.println("There is no vector data on the current page");​
                }​
                ​
                // Get the pagination token for the next page.​
                nextToken = output.getNextToken();​
                pageNum++;​
                ​
                // If nextToken is null, it indicates that all data has been listed​
                if (nextToken == null || nextToken.isEmpty()) {​
                    System.out.println("\n All vector data has been listed");​
                    break;​
                }​
            } while (true);​
            ​
            // Print summary information.​
            System.out.println("\n Summary of completion enumeration:");​
            System.out.println("Total number of vectors: " + totalVectors);​
            System.out.println("List page numbers: " + (pageNum - 1));​
            System.out.println("Number of all vector keys: " + allVectorKeys.size());​
            ​
            // Demonstration: Get the first page and include detailed data.​
            System.out.println("\n Demonstration: Obtain detailed data for the first page...");​
            ListVectorsInput detailedInput = ListVectorsInput.builder()​
                    .vectorBucketName(vectorBucketName)​
                    .accountId(accountID)​
                    .indexName(indexName)​
                    .maxResults(5) // Only retrieve the first 5.​
                    .returnData(true) // Return vector data.​
                    .returnMetadata(true) // Return metadata.​
                    .build();​
            ​
            ListVectorsOutput detailedOutput = client.listVectors(detailedInput);​
            if (detailedOutput.getVectors() != null && !detailedOutput.getVectors().isEmpty()) {​
                System.out.println("Detailed data - The first " + detailedOutput.getVectors().size() + " vectors:");​
                for (int i = 0; i < detailedOutput.getVectors().size(); i++) {​
                    Vector vector = detailedOutput.getVectors().get(i);​
                    System.out.println("  Vector " + (i + 1) + ":");​
                    System.out.println("    Key: " + vector.getKey());​
                    if (vector.getData() != null && vector.getData().getFloat32() != null) {​
                        System.out.println("    Data dimension: " + vector.getData().getFloat32().length);​
                    }​
                    if (vector.getMetadata() != null) {​
                        System.out.println("    Metadata: " + vector.getMetadata());​
                    }​
                }​
            }​
​
        } catch (TosClientException e) {​
            // Operation failed, caught a Client exception. Generally, it is due to incorrect request parameters, 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, 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());​
        }​
    }​
}​