> ## 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.

# search()

> Search for documents using semantic similarity

Search for documents using semantic similarity.

## Signature

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
async search(query: string, options?: SearchOptions<T>): Promise<SearchResult<T>[]>
```

## Parameters

| Parameter | Type               | Description                   |
| --------- | ------------------ | ----------------------------- |
| `query`   | `string`           | Natural language search query |
| `options` | `SearchOptions<T>` | Optional search configuration |

### SearchOptions

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface SearchOptions<T extends DocumentMetadata> {
  topK?: number;           // Maximum results (default: 10)
  threshold?: number;      // Minimum similarity 0-1 (default: 0.3)
  filter?: (metadata: T) => boolean;  // Metadata filter
  includeVector?: boolean; // Include embedding vectors (default: false)
}
```

## Return Value

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface SearchResult<T extends DocumentMetadata> {
  id: string;           // Document ID
  score: number;        // Similarity score (0-1)
  metadata: T;          // Document metadata
  text: string;         // Original document text
  vector?: Float32Array; // Embedding (if includeVector: true)
}
```

Results are sorted by `score` in descending order (highest similarity first).

## Examples

### Basic Search

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const results = await db.search('find users');

for (const result of results) {
  console.log(`${result.id}: ${result.score.toFixed(2)}`);
}
```

### With Options

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const results = await db.search('payment processing', {
  topK: 5,
  threshold: 0.5,
  filter: (m) => m.owner === 'billing' && !m.deprecated,
});
```

### With Vectors

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const results = await db.search('query', {
  includeVector: true,
});

console.log(results[0].vector); // Float32Array
```

## Errors

| Error                         | Condition                                           |
| ----------------------------- | --------------------------------------------------- |
| `VectoriaNotInitializedError` | Database not initialized                            |
| `QueryValidationError`        | Empty query, invalid `topK`, or invalid `threshold` |

## Error Handling

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

try {
  const results = await db.search(query, { topK: -1 });
} catch (error) {
  if (error instanceof QueryValidationError) {
    console.error('Invalid search:', error.message);
  }
}
```

## Performance

* **Brute-force**: O(n) - scans all documents
* **HNSW**: O(log n) - approximate nearest neighbor

Enable HNSW for datasets > 10,000 documents.

## Related

<CardGroup cols={3}>
  <Card title="add()" icon="plus" href="/vectoriadb/api-reference/vectoriadb/add">
    Add documents
  </Card>

  <Card title="filter()" icon="filter" href="/vectoriadb/api-reference/vectoriadb/query-methods">
    Non-semantic filtering
  </Card>

  <Card title="SearchOptions" icon="gear" href="/vectoriadb/api-reference/interfaces/search">
    Search interface
  </Card>
</CardGroup>