The getIndex interface retrieves metadata and configuration information of a specified index. This article explains how to query index structure, shard count, mapping, and other attributes using the getIndex interface.

Notes

You need to fill in the region and access domain name in the example code based on your actual situation. For details, see Region and Access Domain Name (Endpoint).

To prevent key leaks, the example code requires reading 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.

Temporary access credentials are supported; timeout mechanisms, retry strategies, and other methods are also supported. You can flexibly set them according to business needs to improve application security. For details, see Common Configuration Scenarios.

Permissions required

The primary account has all permissions by default, but an IAM user has no permissions by default. If you need a sub-account to perform the getIndex operation, the primary account must grant the following permissions to this sub-account through the IAM policy and bucket policy:

tosvectors:GetIndex

Code example

Retrieve information for a specified vector index

// Get information about the specified vector index.​
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.GetIndexInput;​
import com.volcengine.tos.model.vectors.GetIndexOutput;​
​
​
public class GetIndexExample {​
    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 {​
            // Construct input parameters for retrieving index information.​
            GetIndexInput input = GetIndexInput.builder()​
                    .vectorBucketName(vectorBucketName)  // Set the name of the vector storage bucket.​
                    .indexName(indexName)                // Set index name.​
                    .accountId(accountID)                  // Set account ID.​
                    .build();​
​
            // Call the getIndex API to obtain index information.​
            GetIndexOutput output = client.getIndex(input);​
            ​
            // Print request information.​
            System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
            System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
            ​
            // Print index details.​
            if (output.getIndex() != null) {​
                System.out.println("Index Name: " + output.getIndex().getIndexName());​
                System.out.println("Vector Bucket Name: " + output.getIndex().getVectorBucketName());​
                System.out.println("Creation Time: " + output.getIndex().getCreationTime());​
                System.out.println("Data Type: " + output.getIndex().getDataType());​
                System.out.println("Dimension: " + output.getIndex().getDimension());​
                System.out.println("Distance Metric: " + output.getIndex().getDistanceMetric());​
                System.out.println("Index TRN: " + output.getIndex().getIndexTrn());​
                ​
                // Print metadata configuration information.​
                if (output.getIndex().getMetadataConfiguration() != null && ​
                    output.getIndex().getMetadataConfiguration().getNonFilterableMetadataKeys() != null) {​
                    System.out.println("Non-filterable Metadata Keys: " + ​
                        output.getIndex().getMetadataConfiguration().getNonFilterableMetadataKeys());​
                }​
            }​
            ​
            System.out.println("Obtain vector index information successfully");​
​
        } 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, caught server exception, can obtain information from the service.​
            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());​
        }​
    }​
}​