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

# Best Practices

> Best practices for using Ceramic Search API

Ceramic is a **lexical search engine** built from the ground up for AI. Understanding how lexical search works and following these guidelines will help you get the most relevant results from Ceramic Search.

## What is Lexical Search?

Ceramic uses **lexical (keyword-based) search**, which matches documents based on the **exact words and phrases** in your query.
Unlike semantic search systems, Ceramic does not infer meaning, intent, or synonyms—it focuses on precise term matching for speed, transparency, and control.

#### Key characteristics

* Matches **exact keywords and phrases**
* Fast and computationally efficient
* Does **not automatically handle synonyms or intent**

## Why Keyword Search Works Well with LLMs

While Ceramic uses keyword-based (lexical) search, this approach works especially well when combined with LLMs.

#### LLMs are good at query generation

LLMs can transform natural language into high-quality keyword queries. Instead of relying on the search system to interpret intent, you can use an LLM to:

* Rewrite queries into precise keyword-based searches
* Expand queries with synonyms or related terms
* Generate multiple variations of a query

***

#### Search becomes a plentiful resource

Many search systems treat search as a **scarce and expensive operation**, encouraging a single, highly optimized query.

Ceramic takes a different approach.

With a Search API at very low cost, we found more value in creating several keyword-based searches rather than one overemphasized query.

This enables new patterns:

* Multi-query retrieval (increase recall)
* Query variation (capture different terminology)
* Iterative refinement (improve results over time)

***

#### Example: single query vs multi-query

**Instead of one over-optimized query:**

`impact of climate change on agriculture in developing countries`

**You can issue multiple simpler queries:**

`climate change agriculture impact`

`global warming crop yields`

`developing countries farming climate effects`

***

#### Why this works

* Lexical search provides **fast, precise matching**
* LLMs provide **understanding and query generation**
* Combining both gives you **control + flexibility**

***

#### Recommended approach

For LLM-powered applications:

1. Start with a user query
2. Use an LLM to generate multiple keyword-based queries
3. Send each query to Ceramic
4. Aggregate and rank the results

This often produces better results than relying on a single complex query.

## What Works Well

Lexical search performs best when your query includes **specific, well-defined terms** that are likely to appear in the target documents.

#### Good Query Patterns

* Exact names
* Technical terms
* Product names or identifiers
* Specific phrases

| Use case                  | Example query                                   |
| ------------------------- | ----------------------------------------------- |
| `Person lookup`           | `Serena Williams Grand Slam titles`             |
| `Technical documentation` | `OAuth 2.0`                                     |
| `Legal text`              | `California tenant security deposit return law` |
| `News/event lookup`       | `2026 Super bowl halftime performer`            |

## What Doesn’t Work Well

Because Ceramic does not perform semantic understanding, it may struggle with:

#### 1. Synonyms

Different words with the same meaning are not automatically matched

* BBQ ≠ barbecue
* gym ≠ fitness center

For example, a query for `gym membership cost` may miss results that use `fitness center pricing`.

#### 2. Vague or abstract queries

Queries without clear keywords may return weak or irrelevant results.

| Query                      | Issue                  |
| -------------------------- | ---------------------- |
| `technology trends`        | `Too broad`            |
| `how people feel about AI` | `Lacks concrete terms` |

#### 3. Natural language / conversational queries

Ceramic does not interpret intent like an LLM or semantic search system.

| Query                                               | Issue                                      |
| --------------------------------------------------- | ------------------------------------------ |
| `What are the best ways to invest money right now?` | `Too conversational`                       |
| `Why is rent so high in California?`                | `Requires reasoning, not keyword matching` |

#### 4. Misspellings or loosely related terms

Lexical search relies on exact matching, so spelling and wording matter.

## How to Write Effective Queries

Specific queries return better results than broad ones. Include relevant context and details.

#### Be specific

Include **important keywords, entities, and context**

| Instead of        | Try                                              |
| ----------------- | ------------------------------------------------ |
| `technology news` | `OpenAI GPT-5 announcement 2025`                 |
| `California laws` | `California tenant security deposit return laws` |

#### Include multiple relevant terms

More context = better matching

| Instead of | Try                                        |
| ---------- | ------------------------------------------ |
| `climate`  | `climate change policy United States 2024` |

#### Use explicit synonyms when needed

If you’re unsure which term appears in documents, include multiple:

`college university tuition costs US`

#### Word order matters

The order of words in your query affects results. The same words in different orders can return different results.

| Query       | Finds                     |
| ----------- | ------------------------- |
| `cat house` | Outdoor shelters for cats |
| `house cat` | Domestic cats as pets     |

## Using Ceramic with LLMs (Query Rewriting)

If you're using Ceramic in an AI or RAG pipeline, you should **rewrite user queries into keyword-focused search queries** before sending them to the API.
LLMs are great at this transformation.

### Example

**User query (natural language):**
`Why is rent so high in California right now?`

**Rewritten query (Ceramic-optimized):**
`California rent increase causes housing shortage 2025`

***

### Prompt Template

Use the following prompt to convert user input into effective Ceramic queries:

```
Rewrite the following user query into a concise, keyword-based search query optimized for a lexical search engine.

Guidelines:
- Use specific keywords and entities
- Avoid conversational language
- Include relevant context (location, date, topic)
- Do not include full sentences
- Output only the rewritten query

User query:
{user_query}
```

***

### Example Transformations

| User Query                                   | Rewritten Query                                     |
| -------------------------------------------- | --------------------------------------------------- |
| `What are the effects of climate change?`    | `climate change effects global warming impact`      |
| `Who performed at the Super Bowl this year?` | `2026 Super Bowl halftime performer`                |
| `How do I start investing?`                  | `beginner investing strategies stocks bonds basics` |

***

### Why this matters

Ceramic does not interpret intent like an LLM. Rewriting queries helps:

* Improve keyword matching
* Produce more consistent and predictable results

## Controlling Result Description Length

Each search result includes a description — a snippet of text from the matched document. You can control the maximum character length of these descriptions using the `maxDescriptionLength` parameter.

**Default:** `3000` characters, which works well for most use cases.
**Range:** `1000` – `8000` characters.

### When to adjust it

| Situation                                                 | Recommendation                                                                   |
| --------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Feeding results into an LLM with a limited context window | Lower it (e.g. `1000`–`1500`) to fit more results without exceeding token limits |
| Deep document analysis where full context matters         | Raise it (e.g. `6000`–`8000`) to retain more of the source text                  |
| Multi-query retrieval with many results                   | Lower it so the combined output stays within your context budget                 |

Start with the default `3000` and adjust based on how many results you're passing to your model and what context window you're working within.

***

## When NOT to Use Ceramic Alone

You may want to combine Ceramic with other systems if your use case requires:

* Understanding intent or meaning
* Handling natural language questions
* Matching concepts rather than exact words

We're actively exploring semantic and hybrid retrieval patterns—if this applies to your use case, reach out to our team at [support](mailto:support@ceramic.ai).

## Language support

Ceramic currently supports English web pages. Support for additional languages is coming soon.