# 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](collections.md). |
| **Document** | A flat JSON object with an `id`. Writing a document with an existing `id` replaces the old one. See [Ingesting documents](ingesting-documents.md). |
| **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](schemas-and-fields.md). |
| **Query** | What you ask for, in the query language you already know. See [Query languages](query-languages.md). |
| **Facet and metric** | Counts, buckets and numbers computed over every match, in the same request as the hits. See [Facets and aggregations](facets-and-aggregations.md). |
| **API key** | A `ws_live_...` secret with a role. See [API keys, roles and rate limits](access-control.md). |

## 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.

```json
{
  "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](schemas-and-fields.md).

## 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](searching.md).
- **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](vector-search.md).
- **Hybrid search** combines the two in one request so each covers the other's blind spots. See
  [Hybrid search](hybrid-search.md).

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](query-languages.md) and [Elasticsearch compatibility](compat-elasticsearch.md).

## 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](consistency-and-durability.md).

## 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](pricing.md#cold-starts-and-keep-warm).

## 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](collections.md). Limits that depend on your plan, and the errors you get when you
reach them, are in [Limits and errors](limits-and-errors.md).

## Where to go next

1. [Quickstart](quickstart.md) to load data and run a first query.
2. [Collections](collections.md) and [Schemas and field types](schemas-and-fields.md) to model
   your data.
3. [Ingesting documents](ingesting-documents.md) and [Searching](searching.md) to build.
4. [Feature status](roadmap-and-status.md) for what is available, in development or not
   supported.