The createIndex interface is used to create vector indexes. This article explains how to use the createIndex interface of the TOS Vectors Node.js SDK to complete this operation.

Notes

You need to fill in the region and access domain in the sample code according to your actual situation. For detailed information, see Regions and Access Domains (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 temporary access credentials and allows configuring timeout mechanisms, retry policies, and other settings. You can flexibly adjust these according to your business needs to enhance application security. For details, see Common Configuration Scenarios.

Vector index names must be unique within the vector bucket.

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 the createIndex operation, the main account must grant the following permissions to the sub-account through IAM policies and bucket policies:

tosvectors:CreateIndex

Code example

Create a vector index

// Create vector index​
​
import {​
  TosVectorsClient,​
  TosClientError,​
  TosServerError,​
  DataType,​
  DistanceMetricType,​
} from "@volcengine/tos-sdk";​
​
// Get authentication information and configuration from environment variables​
const accessKeyId = process.env["TOS_ACCESS_KEY"] as string;​
const accessKeySecret = process.env["TOS_SECRET_KEY"] as string;​
const region = 'Provide your region';​
const endpoint = 'Provide your vector endpoint';​
​
const vectorBucketName = 'Provide your vector bucket name';​
const accountId = process.env["TOS_ACCOUNT_ID"];​
​
// Initialize TosVectorsClient client​
const client = new TosVectorsClient({​
  accessKeyId,​
  accessKeySecret,​
  region,​
  endpoint,​
});​
​
/**​
 * Handle errors that may occur during SDK calls.​
 *@paramerror the error object caught​
 */​
function handleError(error: Error) {​
  if (error instanceof TosClientError) {​
    // Client 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 exception, indicating the request was received but failed to process​
    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() {​
  // Prepare index name and configuration information for the current example​
  const indexName = `example-index-${Date.now()}`; // Example index name; please name according to your business needs​
  const dimension = 128; // Vector dimension, for example, 128 dimensions​
​
  // Optional metadata configuration: configure metadata fields that cannot be used for filtering​
  const metadataConfiguration = {​
    nonFilterableMetadataKeys: ["timestamp", "source"],​
  };​
​
  try {​
    console.log(`Begin creating vector index: ${indexName} ...`);​
​
    // 1. Call createIndex to create a vector index​
    const createResult = await client.createIndex({​
      vectorBucketName,​
      accountID: accountId,​
      indexName,​
      dataType: DataType.DataTypeFloat32, // Vector data type, currently supports float32​
      dimension, // Vector dimension​
      distanceMetric: DistanceMetricType.DistanceMetricEuclidean, // Vector similarity measurement method, here using Euclidean distance as an example​
      metadataConfiguration, // Optional metadata configuration​
    });​
​
    // 2. Print general return information​
    console.log("CreateIndex Request Succeeded:");​
    console.log("  Request ID:", createResult.requestId);​
    console.log("  Status Code:", createResult.statusCode);​
    console.log("  Headers:", createResult.headers);​
​
    // The business return body of createIndex is an empty object {}, here only printing placeholder information​
    console.log("  Business Data (CreateIndex):", createResult.data);​
​
    // 3. Call getIndex to retrieve the details of the newly created index to display business data​
    console.log("Start querying the details of the newly created vector index...");​
​
    const getResult = await client.getIndex({​
      vectorBucketName,​
      accountID: accountId,​
      indexName,​
    });​
​
    // Print general return information of getIndex​
    console.log("GetIndex Request Succeeded:");​
    console.log("  Request ID:", getResult.requestId);​
    console.log("  Status Code:", getResult.statusCode);​
    console.log("  Headers:", getResult.headers);​
​
    // Print key information of the index​
    const index = getResult.data.index;​
    console.log("  Index Detail:");​
    console.log(`    - Index Name: ${index.indexName}`);​
    console.log(`    - Data Type: ${index.dataType}`);​
    console.log(`    - Dimension: ${index.dimension}`);​
    console.log(`    - Distance Metric: ${index.distanceMetric}`);​
    console.log(`    - Creation Time: ${index.creationTime}`);​
    console.log(`    - Index TRN: ${index.indexTrn}`);​
    console.log(`    - Vector Bucket Name: ${index.vectorBucketName}`);​
​
    // Print metadata configuration (if available)​
    if (​
      index.metadataConfiguration &&​
      index.metadataConfiguration.nonFilterableMetadataKeys &&​
      index.metadataConfiguration.nonFilterableMetadataKeys.length > 0​
    ) {​
      console.log(​
        "    - Non-filterable Metadata Keys:",​
        index.metadataConfiguration.nonFilterableMetadataKeys.join(", "),​
      );​
    } else {​
      console.log("    - Non-filterable Metadata Keys: <none>");​
    }​
  } catch (error: any) {​
    handleError(error);​
  }​
}​
​
main();​
​