Docs

Torch Object Storage

Vector

PutVectors（TOS Vectors Node.js SDK）

The putVectors interface is used to batch insert vectors into the vector index. This guide explains how to perform this operation using the putVectors interface of the TOS Vectors Node.js SDK.

Notes

You need to fill in the region and access domain in the sample code based on your actual situation. For detailed information, see Region and Endpoint.

To prevent key leaks, the sample code reads the Access Key ID and Secret Access Key from environment variables. Therefore, before using the SDK, you must configure long-term access credentials. For detailed information, see Configure Long-Term Access Credentials.

The TOS Vectors Node.js SDK supports using temporary access credentials and allows you to configure timeout mechanisms, retry strategies, and other features. You can flexibly set these according to your business needs to enhance application security. For details, see Common Configuration Scenarios.

Permissions required

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

tosvectors:PutVectors

Code example

Batch insert vectors into the vector index

// Batch insert vectors into the vector index​
​
import {​
  TosVectorsClient,​
  TosClientError,​
  TosServerError,​
} from "@volcengine/tos-sdk";​
​
// Retrieve authentication information and configuration from environment variables​
const client = new TosVectorsClient({​
  accessKeyId: process.env["TOS_ACCESS_KEY"], // TOS_ACCESS_KEY: your Access Key ID​
  accessKeySecret: process.env["TOS_SECRET_KEY"], // TOS_SECRET_KEY: your Secret Key​
  region: 'Provide your region',​
  endpoint: 'Provide your vector endpoint',​
});​
​
const vectorBucketName = 'Provide your vector bucket name';​
const accountId = process.env["TOS_ACCOUNT_ID"];​
const indexName = "test"​
​
/**​
 * handle possible errors during SDK calls.​
 *@paramerror the error object caught​
 */​
function handleError(error: Error) {​
  if (error instanceof TosClientError) {​
// client exception, usually due to parameter error or network issues​
    console.log("Client Error:");​
    console.log("  Message:", error.message);​
    if (error.stack) {​
      console.log("  Stack:", error.stack);​
    }​
  } else if (error instanceof TosServerError) {​
    // server exception, indicating the request was received but processing failed​
    console.log("Server Error:");​
    console.log("  Request ID:", error.requestId);​
    console.log("  Status Code:", error.statusCode);​
    console.log("  Code:", error.code);​
    console.log("  Message:", error.message);​
    console.log("  Headers:", error.headers);​
  } else {​
    // other unknown exceptions​
    console.log("Unexpected Error:");​
    console.log("  Message:", error.message);​
  }​
}​
​
async function main() {​
  // ensure the following dimension matches the dimension used when creating the index​
  const dimension = 128;​
​
  try {​
    console.log(​
      `Putting vectors into index: ${indexName} in vector bucket: ${vectorBucketName}...`,​
    );​
​
   // 1. Prepare the vector data to be written​
    // Each vector includes:​
 // - key: unique identifier of the vector​
    // - data.float32: float vector matching the index dimension​
    // - metadata: optional metadata for filtering or business tagging​
    const vectors = [​
      {​
        key: `product-1-${Date.now()}`,​
        data: {​
          float32: Array.from({ length: dimension }, () => Math.random()),​
        },​
        metadata: {​
          category: "book",​
          price: 19.9,​
          source: "demo",​
        },​
      },​
      {​
        key: `product-2-${Date.now()}`,​
        data: {​
          float32: Array.from({ length: dimension }, () => Math.random()),​
        },​
        metadata: {​
          category: "electronics",​
          price: 1999,​
          source: "demo",​
        },​
      },​
    ];​
​
    const putVectorsInput = {​
      vectorBucketName,​
      accountID: accountId,​
      indexName,​
 vectors,​
    };​
​
    // 2. Call the putVectors method to write a batch of vectors into the specified index​
    const result = await client.putVectors(putVectorsInput);​
​
    // 3. Print general return information and business data​
    console.log("PutVectors Request Succeeded:");​
    console.log("  Request ID:", result.requestId);​
    console.log("  Status Code:", result.statusCode);​
    console.log("  Headers:", result.headers);​
​
    // The current PutVectors interface business response body is an empty object {}, success is mainly determined by the HTTP status code and request ID​
    console.log("  Business Data (PutVectors):", result.data);​
​
    // To facilitate troubleshooting, additionally print the list of vector keys written this time​
    console.log(​
      "  Inserted Vector Keys:",​
      vectors.map((v) => v.key),​
    );​
  } catch (error: any) {​
    handleError(error);​
  }​
}​
​
main();​
​