The createIndex interface is used to create a new vector index in TOS Vectors. This article explains how to create an index using the createIndex interface of the TOS Vectors Java SDK, specifying the dimension, metric type, and update strategy.

Notes

You need to fill in the region and access domain in the sample code according to your actual situation. For detailed information, see Region and Access Domain (Endpoint).

To prevent key leaks, the sample code in this article 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 detailed information, see Configuring Long-Term Access Credentials.

The TOS Vectors Java SDK supports using temporary access credentials and configuring timeout mechanisms, retry policies, and other settings. You can flexibly configure these based on business needs to enhance application security. For detailed information, see Common Configuration Scenarios.

The vector index name must be unique within the vector bucket.

Permissions required

The main account has all permissions by default, but IAM users have no permissions by default. If you need to use a sub-account to perform the createIndex operation, the primary account must grant the following permissions to the sub-account through IAM policies and bucket policies:

tosvectors:CreateIndex

Code example

Basic usage for creating vector index

// Basic usage of creating 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.comm.common.DataType;​
import com.volcengine.tos.comm.common.DistanceMetricType;​
import com.volcengine.tos.model.vectors.CreateIndexInput;​
import com.volcengine.tos.model.vectors.CreateIndexOutput;​
import com.volcengine.tos.model.vectors.MetadataConfiguration;​
​
import java.util.Arrays;​
​
public class CreateIndexExample {​
    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 storage bucket name.​
        String vectorBucketName = 'Provide your vector bucket name';​
        // Fill in the index name.​
        String indexName = "testindex";​
​
        // Initialize client.​
        TOSVectors client = new TOSVectorsClientBuilder().build(region, endpoint, accessKey, secretKey);​
​
        try {​
            // Create vector index​
            // 1. Set index parameters: Vector dimension is 128, data type is float32, and distance metric is cosine.​
            // 2. Configure metadata: Set non-filterable metadata keys.​
            CreateIndexInput input = CreateIndexInput.builder()​
                    .vectorBucketName(vectorBucketName)​
                    .accountId(accountID)​
                    .indexName(indexName)​
                    .dataType(DataType.DATA_TYPE_FLOAT32)  // Data type: float32​
                    .dimension(128)  // Vector dimension: 128​
                    .distanceMetric(DistanceMetricType.DISTANCE_METRIC_COSINE)  // Distance metric: Cosine similarity​
                    .metadataConfiguration(new MetadataConfiguration()​
                            .setNonFilterableMetadataKeys(Arrays.asList("key1", "key2")))  // Filterable metadata keys​
                    .build();​
​
            // Call the create index API.​
            CreateIndexOutput output = client.createIndex(input);​
            ​
            // Process the return result.​
            System.out.println("Create vector index successfully.");​
            System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
            System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
            System.out.println("Index name: " + indexName);​
            System.out.println("Vector dimension: 128");​
            System.out.println("Data type: float32");​
            System.out.println("Distance metric: cosine");​
​
        } catch (TosClientException e) {​
            // Operation failed, caught 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, it generally won't execute here.​
            System.out.println("Operation failed");​
            System.out.println("unexpected exception, message: " + t.getMessage());​
        }​
    }​
}​