The putVectors interface is used to write vector data. This article explains how to batch write vector sets to a specified storage space using the putVectors interface of the TOS Vectors Java SDK.

Notes

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

To prevent key leakage, the example 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 Configure Long-term Access Credentials.

The TOS Vectors Java SDK supports using temporary access credentials and also supports configuring timeout mechanisms, retry policies, and other mechanisms. You can flexibly configure these settings based on your business needs to enhance 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 you want a sub-account to perform the putVectors operation, the main account must grant the following permissions to the sub-account via IAM policies and bucket policies:

tosvectors:PutVectors

Code example

Batch insert vectors into the vector index

// Batch insert vectors into the 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.PutVectorsInput;​
import com.volcengine.tos.model.vectors.PutVectorsOutput;​
import com.volcengine.tos.model.vectors.Vector;​
import com.volcengine.tos.model.vectors.VectorData;​
​
import java.util.ArrayList;​
import java.util.HashMap;​
import java.util.List;​
import java.util.Map;​
​
public class PutVectorsExample {​
    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 of vectors to insert​
            List<Vector> vectors = new ArrayList<>();​
            ​
            // Create the first vector.​
            float[] vectorData1 = new float[128];​
            for (int i = 0; i < 128; i++) {​
                vectorData1[i] = (float) Math.random();​
            }​
            Map<String, Object> metadata1 = new HashMap<>();​
            metadata1.put("category", "electronics");​
            metadata1.put("timestamp", System.currentTimeMillis());​
            metadata1.put("source", "user-upload");​
            ​
            Vector vector1 = Vector.builder()​
                    .key("product-vector-001")​
                    .data(VectorData.builder().float32(vectorData1).build())​
                    .metadata(metadata1)​
                    .build();​
            vectors.add(vector1);​
            ​
            // Create the second vector.​
            float[] vectorData2 = new float[128];​
            for (int i = 0; i < 128; i++) {​
                vectorData2[i] = (float) Math.random();​
            }​
            Map<String, Object> metadata2 = new HashMap<>();​
            metadata2.put("category", "clothing");​
            metadata2.put("timestamp", System.currentTimeMillis());​
            metadata2.put("source", "batch-import");​
            ​
            Vector vector2 = Vector.builder()​
                    .key("product-vector-002")​
                    .data(VectorData.builder().float32(vectorData2).build())​
                    .metadata(metadata2)​
                    .build();​
            vectors.add(vector2);​
            ​
            // Create the third vector.​
            float[] vectorData3 = new float[128];​
            for (int i = 0; i < 128; i++) {​
                vectorData3[i] = (float) Math.random();​
            }​
            Map<String, Object> metadata3 = new HashMap<>();​
            metadata3.put("category", "books");​
            metadata3.put("timestamp", System.currentTimeMillis());​
            metadata3.put("source", "manual-entry");​
            ​
            Vector vector3 = Vector.builder()​
                    .key("product-vector-003")​
                    .data(VectorData.builder().float32(vectorData3).build())​
                    .metadata(metadata3)​
                    .build();​
            vectors.add(vector3);​
            ​
            // Construct a batch insert vector request.​
            PutVectorsInput input = PutVectorsInput.builder()​
                    .vectorBucketName(vectorBucketName)​
                    .accountId(accountID)​
                    .indexName(indexName)​
                    .vectors(vectors)​
                    .build();​
            ​
            // Perform batch insert vector operation.​
            PutVectorsOutput output = client.putVectors(input);​
            ​
            // Process the return result.​
            System.out.println("Batch insert vector successfully");​
            System.out.println("RequestID: " + output.getRequestInfo().getRequestId());​
            System.out.println("StatusCode: " + output.getRequestInfo().getStatusCode());​
            System.out.println("Number of successfully inserted vectors: " + vectors.size());​
            ​
            // Print the information of the inserted vector.​
            for (int i = 0; i < vectors.size(); i++) {​
                Vector vector = vectors.get(i);​
                System.out.println("Vector " + (i + 1) + ":");​
                System.out.println("  Key: " + vector.getKey());​
                System.out.println("  Dimension: " + vector.getData().getFloat32().length);​
                System.out.println("  Metadata: " + vector.getMetadata());​
            }​
​
        } 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());​
        }​
    }​
}​