Vector Index

Vector Index stores high-dimensional vector data for similarity search operations. You can use it for text embeddings, image features, audio fingerprints, or any numerical vectors that need fast similarity queries.

Vector Index supports various distance metrics and filtering capabilities. You can store metadata with each vector and perform filtered similarity searches. The component handles high-performance vector operations with automatic indexing.

For users building RAG solutions, consider using SmartBuckets which provide higher-level document processing and semantic search capabilities.

Creating

Define a vector index in your raindrop.manifest file with dimensions and distance metric:

application "my-app" {
  vector_index "embeddings" {
    dimensions = 1024
    metric = "cosine"  // or "euclidean", "dot-product"
  }
}

Distance Metrics:

• cosine - Measures angle between vectors (ignores magnitude). Best for text embeddings and semantic similarity.
• euclidean - Straight-line distance in vector space. Good when magnitude matters (coordinates, measurements).
• dot-product - Combines angle and magnitude. Useful when vector length represents confidence or importance.

Accessing

Access your vector index through environment bindings in your service functions:

export default async function handler(req: Request, env: Env) {
  // Access the vector index
  const embeddings = env.EMBEDDINGS;

  // Perform similarity search
  const results = await embeddings.query([0.1, 0.2, 0.3]);
  return new Response(JSON.stringify(results.matches));
}

Core Concepts

Main Interfaces

• VectorIndex - Async operations for vector storage and querying
• VectorIndexIndex - Sync operations for index management

Core Data Types

VectorIndexVector - Represents a single vector with metadata:

interface VectorIndexVector {
  id: string;                    // Unique identifier for the vector
  values: number[] | Float32Array; // Vector values as array
  namespace?: string;            // Optional namespace for organization
  metadata?: Record<string, any>; // Optional metadata key-value pairs
}

VectorIndexMatch - Search result with similarity score:

interface VectorIndexMatch {
  id: string;           // Vector identifier
  score: number;        // Similarity score (higher = more similar)
  values?: number[];    // Vector values if returnValues is true
  metadata?: Record<string, any>; // Metadata if returnMetadata is set
  namespace?: string;   // Vector namespace
}

VectorIndexQueryOptions - Query configuration:

interface VectorIndexQueryOptions {
  topK?: number;        // Number of results to return (default: 5, max: 100)
  namespace?: string;   // Filter by namespace
  returnValues?: boolean; // Include vector values in results (default: false)
  returnMetadata?: boolean | string; // Include metadata (default: 'none')
  filter?: Record<string, any>; // Metadata filters for results
}

System Limits

• Maximum 1536 dimensions per vector
• Maximum 5M vectors per index
• TopK maximum: 100 without metadata, 20 with metadata
• Maximum 1000 vectors per batch operation

describe

describe(): Promise<VectorIndexIndexInfo>

Returns index statistics and configuration details.

Input

// No parameters required
await env.EMBEDDINGS.describe();

Output

{
  vectorCount: 15420,           // Total vectors in index
  dimensions: 1024,             // Vector dimensions
  processedUpToDatetime: 1641234567890, // Last processing timestamp
  processedUpToMutation: 98765  // Last processed mutation ID
}

Example

Get basic statistics about your vector index including total vector count and dimensions.

export default async function handler(req: Request, env: Env) {
  // Get index statistics
  const info = await env.EMBEDDINGS.describe();

  return new Response(`Index contains ${info.vectorCount} vectors`);
}

query

query(vector: number[] | Float32Array, options?: VectorIndexQueryOptions): Promise<VectorIndexMatches>

Finds vectors most similar to the input query vector.

Input

const queryVector = [0.1, 0.2, 0.3, 0.4]; // Query vector
const options = {
  topK: 10,              // Return top 10 matches
  returnMetadata: true,  // Include metadata
  filter: { category: 'product' } // Filter by metadata
};

Output

{
  matches: [
    {
      id: "vec_123",
      score: 0.95,         // Similarity score
      metadata: { category: "product", name: "Widget A" },
      namespace: "products"
    }
    // ... more matches
  ],
  count: 10              // Number of matches returned
}

Example

Perform similarity search with a query vector and return the top 5 most similar vectors.

export default async function handler(req: Request, env: Env) {
  const queryVector = [0.1, 0.2, 0.3];

  // Find similar vectors with metadata
  const results = await env.EMBEDDINGS.query(queryVector, {
    topK: 5,
    returnMetadata: true
  });

  return new Response(JSON.stringify(results.matches));
}

queryById

queryById(vectorId: string, options?: VectorIndexQueryOptions): Promise<VectorIndexMatches>

Finds vectors similar to an existing vector by its ID.

Input

const vectorId = "vec_123";      // ID of existing vector
const options = {
  topK: 5,                       // Return top 5 similar vectors
  returnValues: false,           // Don't return vector values
  namespace: "products"          // Search within namespace
};

Output

{
  matches: [
    {
      id: "vec_456",
      score: 0.89,
      metadata: { category: "similar_product" },
      namespace: "products"
    }
    // ... more matches
  ],
  count: 5
}

Example

Find vectors similar to an existing vector using its ID instead of providing vector values.

export default async function handler(req: Request, env: Env) {
  // Find vectors similar to an existing one
  const similar = await env.EMBEDDINGS.queryById("vec_123", {
    topK: 3,
    returnMetadata: true
  });

  return new Response(JSON.stringify(similar.matches));
}

insert

insert(vectors: VectorIndexVector[]): Promise<VectorIndexAsyncMutation>

Adds new vectors to the index. Fails if vector IDs already exist.

Input

const vectors = [
  {
    id: "vec_001",
    values: [0.1, 0.2, 0.3],
    namespace: "products",
    metadata: { category: "electronics", price: 299 }
  },
  {
    id: "vec_002",
    values: [0.4, 0.5, 0.6],
    metadata: { category: "books", author: "Smith" }
  }
];

Output

{
  mutationId: "mut_abc123"  // Async operation identifier
}

Example

Add new vectors to the index, operation will fail if any vector ID already exists.

export default async function handler(req: Request, env: Env) {
  const vectors = [
    {
      id: "product_001",
      values: [0.1, 0.2, 0.3],
      metadata: { name: "Laptop", price: 999 }
    }
  ];

  // Insert new vectors
  const mutation = await env.EMBEDDINGS.insert(vectors);

  return new Response(`Mutation ID: ${mutation.mutationId}`);
}

upsert

upsert(vectors: VectorIndexVector[]): Promise<VectorIndexAsyncMutation>

Inserts new vectors or updates existing ones by ID.

Input

const vectors = [
  {
    id: "vec_001",           // Will update if exists
    values: [0.2, 0.3, 0.4], // New vector values
    metadata: { updated: true, version: 2 }
  },
  {
    id: "vec_new",           // Will insert as new
    values: [0.7, 0.8, 0.9],
    namespace: "latest"
  }
];

Output

{
  mutationId: "mut_def456"  // Async operation identifier
}

Example

Insert new vectors or update existing ones, automatically handling both create and update operations.

export default async function handler(req: Request, env: Env) {
  const vectors = [
    {
      id: "product_001",
      values: [0.2, 0.3, 0.4],
      metadata: { name: "Updated Laptop", price: 899 }
    }
  ];

  // Insert or update vectors
  const mutation = await env.EMBEDDINGS.upsert(vectors);

  return new Response(`Upsert mutation: ${mutation.mutationId}`);
}

deleteByIds

deleteByIds(ids: string[]): Promise<VectorIndexAsyncMutation>

Removes vectors from the index by their IDs.

Input

const vectorIds = ["vec_001", "vec_002", "vec_003"]; // IDs to delete

Output

{
  mutationId: "mut_ghi789"  // Async operation identifier
}

Example

Remove multiple vectors from the index using their unique identifiers.

export default async function handler(req: Request, env: Env) {
  const idsToDelete = ["old_vec_1", "old_vec_2"];

  // Delete vectors by ID
  const mutation = await env.EMBEDDINGS.deleteByIds(idsToDelete);

  return new Response(`Delete mutation: ${mutation.mutationId}`);
}

getByIds

getByIds(ids: string[]): Promise<VectorIndexVector[]>

Retrieves specific vectors by their IDs with full data.

Input

const vectorIds = ["vec_001", "vec_002"]; // IDs to retrieve

Output

[
  {
    id: "vec_001",
    values: [0.1, 0.2, 0.3],
    namespace: "products",
    metadata: { category: "electronics" }
  },
  {
    id: "vec_002",
    values: [0.4, 0.5, 0.6],
    metadata: { category: "books" }
  }
]

Example

Retrieve complete vector data including values and metadata for specific vector IDs.

export default async function handler(req: Request, env: Env) {
  const targetIds = ["product_001", "product_002"];

  // Get specific vectors by ID
  const vectors = await env.EMBEDDINGS.getByIds(targetIds);

  return new Response(JSON.stringify(vectors));
}