Get started fast with the Agent Skill
Give your agents our
SKILL.md. The skill file follows the guidelines in this doc and instructs agents with everything they need to know to best use 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:- Start with a user query
- Use an LLM to generate multiple keyword-based queries
- Send each query to Ceramic
- Aggregate and rank the results
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
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
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.3. Natural language / conversational queries
Ceramic does not interpret intent like an LLM or semantic search system.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 contextInclude multiple relevant terms
More context = better matchingUse 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.Unsupported query content
Ceramic doesn’t support queries that contain:- Slashes, so no URLs, links, or file paths
- Numbers with commas, such as
101,342 - Non-Latin characters
Search operators
Ceramic supports a few operators that give you more control over your results.Search a specific domain with site:
Use site: followed by a domain to only get results from that domain.
Match alternatives with OR
Put OR between two terms or phrases to match either one. OR must be capitalized. Use parentheses to group the alternatives.
You don’t need
AND. Ceramic already includes all of your terms by default.
Match an exact phrase with quotation marks
Put quotation marks around a phrase to match those exact words in that order.
If no results contain the exact phrase, Ceramic falls back to matching the individual words.
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 Transformations
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 themaxDescriptionLength parameter.
Default: 3000 characters, which works well for most use cases.
Range: 1000 – 8000 characters.
When to adjust it
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