The listVectors interface is used to list vectors. This article explains how to perform this operation using the listVectors interface of the TOS Vectors Node.js SDK.

Notes

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

To prevent key leakage, the sample code 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 details, see Configure Long-Term Access Credentials.

The TOS Vectors Node.js SDK supports using temporary access credentials; it also supports timeout mechanisms, retry strategies, and other methods. You can flexibly set these according to 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 have no permissions by default. If you want to perform the listVectors operation with a sub-account, the main account needs to grant the following permissions to the sub-account through IAM policies and bucket policies:

tosvectors:ListVectors

Code examples

Basic usage of listing vectors

// Basic usage of listing vectors​
​
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',​
});​
​
/**​
 * Handle possible errors during SDK calls.​
 *@paramerror the caught error object​
 */​
function handleError(error: Error) {​
  if (error instanceof TosClientError) {​
    // Client exceptions, usually 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 exceptions, 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 vectorBucketName = 'Provide your vector bucket name';​
  const accountId = process.env["TOS_ACCOUNT_ID"];​
  const indexName = "test";​
​
  try {​
    console.log(​
      `List the vector list under index ${indexName} in vector bucket ${vectorBucketName}...`,​
    );​
​
    // 1. Call the listVectors method to list vectors under the index, returning data and metadata​
    const result = await client.listVectors({​
      vectorBucketName,​
      accountID: accountId,​
      indexName,​
      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: number of returned vectors and each vector's key, vector dimension, and metadata fields​
    const vectors = result.data.vectors || [];​
    console.log(`  Number of returned vectors: ${vectors.length}`);​
​
    if (vectors.length === 0) {​
      console.log("  The current request did not return any vectors.");​
    }​
​
    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>");​
      }​
    });​
​
    // 4. Print next page token (if any)​
    if (result.data.nextToken) {​
      console.log("Next Token:", result.data.nextToken);​
    }​
  } catch (error: any) {​
    handleError(error);​
  }​
}​
​
main();​
​

Paginated vector listing

// Paginate vectors​
​
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',​
  });​
​
/**​
 * Handle possible errors during SDK calls.​
 *@paramerror the caught error object​
 */​
function handleError(error: Error) {​
  if (error instanceof TosClientError) {​
    // client error, usually due to parameter issues or network problems​
    console.log("Client Error:");​
    console.log("  Message:", error.message);​
    if (error.stack) {​
      console.log("  Stack:", error.stack);​
    }​
  } else if (error instanceof TosServerError) {​
    // server error, 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 errors​
    console.log("Unexpected Error:");​
    console.log("  Message:", error.message);​
  }​
}​
​
async function main() {​
  const vectorBucketName = 'Provide your vector bucket name';​
  const accountId = process.env["TOS_ACCOUNT_ID"];​
  const indexName = "test";​
  let maxResults = 100;​
​
  try {​
    console.log("Start paginated listing of vectors...");​
​
    let nextToken: string | undefined = undefined;​
    let page = 1;​
​
    // use nextToken to paginate in a loop​
    do {​
      console.log(`\n Request the vector list for page ${page}...`);​
​
      const result = await client.listVectors({​
        vectorBucketName,​
        accountID: accountId,​
        indexName,​
        maxResults,​
        nextToken,​
      });​
​
      // print common request information per page​
      console.log("Page Request Info:");​
      console.log("  Request ID:", result.requestId);​
      console.log("  Status Code:", result.statusCode);​
      console.log("  Headers:", result.headers);​
​
      // print summary of the vector list on this page​
      const vectors = result.data.vectors || [];​
      console.log(`  Number of returned vectors on this page: ${vectors.length}`);​
​
      if (vectors.length === 0) {​
        console.log("  This page did not return any vectors.");​
      }​
​
      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>");​
        }​
      });​
​
      nextToken = result.data.nextToken;​
      if (nextToken) {​
        console.log("  Next Token:", nextToken);​
        page += 1;​
      } else {​
        console.log("  There are no more paging results.");​
      }​
    } while (nextToken);​
  } catch (error: any) {​
    handleError(error);​
  }​
}​
​
main();​
​