# Elasticsearch

Elasticsearch powers all full-text search and content discovery at Suno.

## What is Elasticsearch?

Distributed search and analytics engine optimized for text queries and filtering.

## Access Pattern

### Text Search with Filters

```python
from studio_api.search.clip_search import search_clips

# Text search with filters
results = search_clips(
    query="upbeat pop song",
    filters={
        "bpm_min": 120,
        "bpm_max": 140,
        "genres": ["pop", "electronic"],
    },
    limit=20,
)
```

### Vector Similarity Search

```python
# Find similar clips using embeddings
similar_clips = find_similar_clips(
    clip_id="abc123",
    limit=10,
)
```

## Ingestion

### Full Reindex

import { Callout } from 'nextra/components'

<Callout type="warning">
  This command is resource-intensive and can take hours on production data. **Do not run this without consulting the team first**, especially on staging or production environments.
</Callout>

```bash
cd studio_api
uv run manage.py ingest_clips_for_search --rebuild_index
```

**Use cases for full reindex**:
- Local development with fresh data
- After major Elasticsearch schema changes
- When instructed by the team during planned maintenance

### Incremental Updates

Updates happen automatically when clips are saved.

## Pros

✅ **Fast Full-Text Search** - Optimized for text queries

✅ **Complex Filters** - Range queries, boolean logic

✅ **Vector Search** - Semantic similarity via embeddings

✅ **Autocomplete** - Suggestion APIs

✅ **Analytics** - Aggregations and stats

## Cons

❌ **Resource-Intensive** - High memory and CPU usage

❌ **Can Drift** - Must stay in sync with PostgreSQL

❌ **Operational Complexity** - Requires tuning and monitoring

❌ **Eventual Consistency** - Not real-time by default

## When to Use

### ✅ Use Elasticsearch for:
- Full-text search (lyrics, titles, descriptions)
- Autocomplete and suggestions
- Filtered search (BPM range, genre, mood)
- Vector similarity search

### ❌ Don't use Elasticsearch for:
- Source of truth (use [PostgreSQL](/backend/data-storage/postgresql))
- Simple key-value lookups (use [Redis](/backend/data-storage/redis))