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

# Search

> Semantic, full-text, and hybrid search for your documents

Whilst provides powerful search capabilities combining PostgreSQL full-text search with OpenAI vector embeddings for semantic similarity.

## Search Modes

<CardGroup cols={3}>
  <Card title="Semantic" icon="brain">
    Uses OpenAI embeddings (text-embedding-3-small, 1536 dimensions) to find conceptually similar results even with different wording.
  </Card>

  <Card title="Full-Text" icon="text">
    PostgreSQL `tsvector` search with GIN indexes. Fast exact keyword matching with ranking.
  </Card>

  <Card title="Hybrid (RRF)" icon="shuffle">
    Combines both approaches using Reciprocal Rank Fusion for best-in-class accuracy.
  </Card>
</CardGroup>

## How It Works

```
User Query
    ↓
Generate Embedding (if semantic/hybrid)
    ↓
Execute Search
    ├─ Semantic: pgvector cosine similarity
    ├─ Full-text: ts_rank matching
    └─ Hybrid: Both + RRF re-ranking
    ↓
Apply Filters (folder, tags, workspace)
    ↓
Rank & Return Results
```

## Usage

### Basic Search

```typescript theme={null}
import { searchDocs } from '@/lib/ai/actions/search-docs';

// Semantic search
const results = await searchDocs({
  query: 'machine learning best practices',
  mode: 'semantic',
  limit: 10,
  workspaceId: 'workspace-uuid',
});

// Full-text search
const results = await searchDocs({
  query: 'react hooks',
  mode: 'fulltext',
  limit: 10,
  workspaceId: 'workspace-uuid',
});

// Hybrid search (recommended)
const results = await searchDocs({
  query: 'deployment strategies',
  mode: 'hybrid',
  limit: 10,
  workspaceId: 'workspace-uuid',
});
```

### Filtered Search

```typescript theme={null}
// Search within a folder
const results = await searchDocs({
  query: 'API documentation',
  mode: 'semantic',
  folderId: 'folder-uuid',
  workspaceId: 'workspace-uuid',
});

// Search by tags
const results = await searchDocs({
  query: 'infrastructure',
  mode: 'semantic',
  tags: ['aws', 'devops'],
  workspaceId: 'workspace-uuid',
});
```

## Database Schema

The search system relies on these database features:

```sql theme={null}
-- Documents with FTS and vector support
CREATE TABLE docs (
  id UUID PRIMARY KEY,
  workspace_id UUID NOT NULL,
  title TEXT NOT NULL,
  content TEXT,
  content_tsv tsvector GENERATED ALWAYS AS (
    to_tsvector('english', coalesce(title, '') || ' ' || coalesce(content, ''))
  ) STORED,
  embedding vector(1536)
);

-- Full-text search index
CREATE INDEX docs_fts_idx ON docs USING GIN(content_tsv);

-- Vector similarity index
CREATE INDEX docs_embedding_idx ON docs
  USING ivfflat(embedding vector_cosine_ops)
  WITH (lists = 100);
```

## Embedding Generation

Embeddings are generated automatically when documents are created or updated. For bulk operations:

```typescript theme={null}
import { batchGenerateEmbeddings } from '@/lib/ai/embeddings';

const docs = await getDocs();
const texts = docs.map(d => d.title + ' ' + d.content);
const embeddings = await batchGenerateEmbeddings(texts);
```

## API Endpoint

Search is also available via the REST API at `/api/docs/hybrid-search`. See the [API Reference](/api-reference/endpoints/docs-search) for details.