For AI agents: this page is also available as Markdown at /docs/concepts.md. Every docs page is: add .md to its URL. llms.txt lists them all.
Core concepts
WarpSearch stores JSON documents in collections and lets you search them with keywords, vectors or both in one query. This page names the building blocks you will meet in the rest of the docs, and how they fit together. Each term links to the page that covers it in depth.
#The building blocks
| Term | What it is |
|---|---|
| Organization | Your account. Collections, API keys, members and billing all belong to one organization. A person can belong to several. |
| Collection | A named set of documents that you search together. It is the unit you create, size and delete. See Collections. |
| Document | A flat JSON object with an id. Writing a document with an existing id replaces the old one. See Ingesting documents. |
| Field | A key in a document. Each field has a type that decides how it is searched, sorted and faceted. See Schemas and field types. |
| Query | What you ask for, in the query language you already know. See Query languages. |
| Facet and metric | Counts, buckets and numbers computed over every match, in the same request as the hits. See Facets and aggregations. |
| API key | A ws_live_... secret with a role. See API keys, roles and rate limits. |
#Documents and fields
A document is a flat JSON object. Nested objects are not a field type: flatten them before you send them, or model relations with ids.
{
"id": "b1",
"title": "The Way of Kings",
"genre": "fantasy",
"year": 2010,
"embedding": [0.12, -0.08, 0.31]
}
Fields are typed. A text field is split into words and scored with BM25, so a search for
kings finds the title above. A keyword (string) field is matched whole, which is what you
want for filters, sorting and facets. Numbers, dates, geo points and vectors have their own
types. You declare types when you create the collection, or you let a field-name suffix such as
_t or _s choose the type for you. Both are described in
Schemas and field types.
#Keyword, vector and hybrid search
One collection serves all three:
- Keyword search matches words and phrases and ranks them with BM25. It is the right tool for names, codes and exact phrases. See Searching.
- Vector search finds the nearest neighbors of an embedding. You compute the embeddings and send them; WarpSearch does not embed text for you. See Vector search.
- Hybrid search combines the two in one request so each covers the other's blind spots. See Hybrid search.
Filters, sorting, facets and metrics work the same way in all three.
#Query in the language you know
Every search names a language: SQL, Lucene, Elasticsearch/OpenSearch Query DSL, Solr, LogQL,
Grafana or the native WarpSearch syntax. They all run on the same engine, and POST /v1/translate
shows you the native form of any of them. If you already have an Elasticsearch, OpenSearch or
Solr client, you can also point it at WarpSearch unchanged. See
Query languages and Elasticsearch compatibility.
#Writes, then searches
A write is accepted first and becomes searchable at the next commit. You can ask for the commit
as part of the write (commit=true) or let WarpSearch commit on its own schedule, which takes
seconds. Replacing a document always replaces the whole document. The details, including
what to do after a timeout, are in
Writes, visibility and durability.
#Serverless by design
You do not size or run anything. Data lives in durable storage, and compute is attached to a
collection when you use it. The visible consequence is the cold start: a collection that has been
idle for a while is loaded on its next request. That request can answer 503 warming_up with a
Retry-After header, and you retry. Keep-warm, an optional setting, avoids it; see
Pricing and cost control.
#Who can do what
Organization roles map to what an API key or console session may do:
| Role | Can |
|---|---|
viewer |
List and describe collections, search, count, get a document by id. |
editor |
Everything a viewer can, plus write, replace and delete documents. |
admin |
Everything an editor can, plus create, change and delete collections, and manage members and keys. |
Collection names, field names and the rest of the naming rules are in Collections. Limits that depend on your plan, and the errors you get when you reach them, are in Limits and errors.
#Where to go next
- Quickstart to load data and run a first query.
- Collections and Schemas and field types to model your data.
- Ingesting documents and Searching to build.
- Feature status for what is available, in development or not supported.