The getVectors interface allows batch querying of vectors by vector keys. This article explains how to perform this operation using the getVectors interface of the TOS Vectors Node.js SDK.

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, you need to configure long-term access credentials before using the SDK. For details, see Configure Long-term Access Credentials.

The TOS Vectors Node.js SDK supports temporary access credentials. It also supports configuring mechanisms like timeout and retry policies. You can flexibly set these based on your business needs to enhance application security. For details, see Common Configuration Scenarios.

Permissions required

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

tosvectors:GetVectors

Code example

Batch query vectors by vector key

// Batch query vectors by vector key​
​
import {​
  TosVectorsClient,​
  TosClientError,​
  TosServerError,​
} from "@volcengine/tos-sdk";​
​
// Get authentication info 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-side exception, usually due to parameter errors 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-side 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() {​
  const keys = ["key1", "key2", "key3"];​
​
  try {​
    console.log(​
      `Begin batch querying vectors based on vector key, vector bucket: ${vectorBucketName}, index: ${indexName}, number of keys: ${keys.length}...`,​
    );​
​
    // 1. Call getVectors method to batch query vector data based on the specified vector key list​
    const result = await client.getVectors({​
      vectorBucketName,​
      accountID: accountId,​
      indexName,​
      keys,​
      returnData: true,​
      returnMetadata: true,​
    });​
​
    // 2. Print general return information​
    console.log("Request Succeeded:");​
    console.log("  Request ID:", result.requestId);​
    console.log("  Status Code:", result.statusCode);​
    console.log("  Headers:", result.headers);​
​
    // 3. Print business data: the number of returned vectors and for each vector, the key, vector dimension, and metadata fields​
    const vectors = result.data.vectors || [];​
    console.log(`  Number of returned vectors: ${vectors.length}`);​
​
    vectors.forEach((vector, index) => {​
      const dataLength = vector.data?.float32?.length ?? 0;​
      const metadataKeys = vector.metadata ? Object.keys(vector.metadata) : [];​
​
      console.log(`  Vector #${index + 1}:`);​
      console.log(`    - Key: ${vector.key}`);​
​
      if (dataLength > 0) {​
        console.log(`    - Vector dimension (float32 Length): ${dataLength}`);​
      } else {​
        console.log("    - Vector data: <not returned or empty>");​
      }​
​
      if (metadataKeys.length > 0) {​
        console.log(`    - Metadata field: ${metadataKeys.join(", ")}`);​
      } else {​
        console.log("    - Metadata field: <None>");​
      }​
    });​
  } catch (error: any) {​
    handleError(error);​
  }​
}​
​
main();​
​