> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Indexing Documents

> Adding and updating documents in VectoriaDB

Add documents with a unique `id`, the natural-language `text` to vectorize, and typed `metadata`.

## Adding Documents

### Single Document

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
await toolIndex.add('users:list', 'List all users with pagination and filtering', {
  id: 'users:list',
  toolName: 'list',
  owner: 'users',
  tags: ['read', 'user-management'],
  risk: 'safe',
});
```

### Batch Indexing

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const documents = [
  {
    id: 'billing:charge',
    text: 'Charge a customer payment method',
    metadata: {
      id: 'billing:charge',
      toolName: 'charge',
      owner: 'billing',
      tags: ['write', 'payment'],
      risk: 'destructive',
    },
  },
  {
    id: 'billing:refund',
    text: 'Process a refund for a customer',
    metadata: {
      id: 'billing:refund',
      toolName: 'refund',
      owner: 'billing',
      tags: ['write', 'payment'],
      risk: 'destructive',
    },
  },
];

await toolIndex.addMany(documents);
```

`addMany` validates every document, enforces `maxBatchSize`, and prevents duplicates.

## Type-Safe Metadata

Define your metadata interface for compile-time safety:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { VectoriaDB, DocumentMetadata } from 'vectoriadb';

interface ToolDocument extends DocumentMetadata {
  toolName: string;
  owner: string;
  tags: string[];
  risk: 'safe' | 'destructive';
  deprecated?: boolean;
}

const db = new VectoriaDB<ToolDocument>();

// TypeScript ensures metadata matches interface
await db.add('id', 'text', {
  id: 'id',
  toolName: 'test',
  owner: 'system',
  tags: [],
  risk: 'safe',
  // TypeScript error if you add wrong fields
});
```

## Updating Documents

### Update Metadata Only

Metadata-only updates are instant and don't trigger re-embedding:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
await toolIndex.updateMetadata('users:list', {
  deprecated: true,
  tags: ['read', 'user-management', 'legacy'],
});
```

### Update Text and Metadata

When text changes, VectoriaDB re-embeds the document:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
await toolIndex.update('users:list', {
  text: 'Updated description for user listing',
  metadata: {
    id: 'users:list',
    toolName: 'list',
    owner: 'users',
    tags: ['read'],
    risk: 'safe',
  },
});
```

### Batch Updates

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
await toolIndex.updateMany([
  {
    id: 'users:list',
    text: 'New description',
    metadata: { /* ... */ },
  },
  {
    id: 'billing:charge',
    metadata: { deprecated: true }, // Metadata-only update
  },
]);
```

<Tip>
  Keep the index current with `updateMetadata`, `update`, or `updateMany`. Metadata-only updates never trigger re-embedding, while text changes re-embed only the affected documents.
</Tip>

## Removing Documents

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Single document
await toolIndex.remove('users:list');

// Multiple documents
await toolIndex.removeMany(['users:list', 'billing:charge']);

// Clear all documents
await toolIndex.clear();
```

## Checking for Documents

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Check if document exists
const exists = toolIndex.has('users:list');

// Get document by ID
const doc = toolIndex.get('users:list');
if (doc) {
  console.log(doc.metadata.toolName);
}

// Get count
console.log(`Index contains ${toolIndex.size()} documents`);
```

## Document Limits

VectoriaDB enforces limits to prevent DoS attacks:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const db = new VectoriaDB({
  maxDocuments: 100000,    // Maximum documents in index
  maxDocumentSize: 1000000, // Maximum text size in characters
  maxBatchSize: 1000,      // Maximum documents per batch operation
});
```

## Embedding Generation

Embeddings are generated automatically when you add or update documents. The process:

1. Text is tokenized using the configured model
2. Embeddings are generated (\~100-200 documents/second)
3. Embeddings are stored in memory (and optionally persisted)

For large imports, use `addMany` with appropriate `maxBatchSize` to avoid memory spikes.

## Related

<CardGroup cols={3}>
  <Card title="Search" icon="magnifying-glass" href="/vectoriadb/guides/search">
    Querying the index
  </Card>

  <Card title="Persistence" icon="floppy-disk" href="/vectoriadb/guides/persistence">
    Persisting embeddings
  </Card>

  <Card title="Overview" icon="house" href="/vectoriadb/introduction">
    Getting started
  </Card>
</CardGroup>