# Match API (reverse search)

> **Coming soon:** the Match API is implemented in the gateway and rolls out to the hosted service with the next release. This page describes the API as it ships.

The **Match API** is a **reverse search** API. A search keeps documents and takes a query: you ask which documents match.
Reverse search keeps queries and takes documents: you ask which queries match. You may also know it as
**percolation**, the name Elasticsearch and OpenSearch give it. If you are looking for `percolate`, this is the feature.

| | Search | Match (reverse search) |
|---|---|---|
| You store | documents | queries |
| A request sends | one query | one or more documents |
| The answer is | the documents that match | the registered queries that match |
| Route | `POST /v1/search/{collection}` | `POST /v1/match/{queries-collection}` |

You **register** a query once, with an id of your own. From then on every document you send to the Match API is
checked against all registered queries at once, and each document comes back with the ids of the queries it matches.
Registered queries are written in the same query languages as search (`text` by default, or `lucene`, `es`, `sql`
and the others), so there is nothing new to learn about queries.

## When to use it

**Saved-search alerts.** A property site lets people save a search such as `bedrooms:[3 TO *] AND city:Denver AND
price:<500000`. Register each saved search as a query, with the user in its `labels`. When a new listing is ingested,
match it: the answer lists exactly the saved searches it satisfies, so you notify only those users. Without reverse
search you would have to run every saved search against the whole catalog after each change.

**Routing and tagging.** A support desk receives thousands of tickets an hour. Register a query per routing rule
(`"refund" OR "chargeback"` goes to billing, `"outage" AND product:api` goes to on-call) and match each incoming
ticket. The matching ids tell you which team, priority or tag to apply. The same pattern flags messages that break a
keyword policy, classifies log lines, and watches a news or job feed for topics people follow.

Rule of thumb: when you have many queries and a stream of documents, use the Match API. When you have many documents
and a few queries, use search.

## Queries collections

Registered queries live in a **queries collection**. It is an ordinary collection created with `"class": "queries"`.
Its schema describes the **documents you will match**, not the queries, because every registered query is checked
against that schema when you register it.

```bash
curl -X PUT https://api.warpsearch.io/v1/collections/alerts \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "class": "queries",
    "description": "Saved searches for new listings",
    "schema": {"fields": {"title": "_t", "city": "string", "bedrooms": "int", "price": "double"}}
  }'
```

To match documents shaped like an existing collection, copy its schema with `clone`:
`"clone": {"from": "listings", "documents": false}`. A queries collection holds registered queries only, no documents.
Its registered queries stay ready to match instead of being released when idle. See
[Collection classes](collections.md#collection-classes).

## Register a query

`PUT /v1/match/{queries-collection}/{id}` registers one query. It needs the `writer` role. The id is yours; registering
the same id again replaces the query.

```bash
curl -X PUT https://api.warpsearch.io/v1/match/alerts/q-4411 \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "title:(garden OR patio)",
    "filters": ["city:Denver", "bedrooms:[3 TO *]", "price:[* TO 500000]"],
    "labels": {"user": "u-77", "channel": "email"},
    "metadata": {"name": "Denver 3-bed under 500k"}
  }'
```

| Field | Meaning |
|---|---|
| `query` | The query, written in `language`. Required. |
| `language` | `text` (the default), `lucene`, `es`, `sql` and the other [query languages](query-languages.md). |
| `filters` | Non-scoring restrictions, written in the query's language, as in [search](searching.md#request-fields). |
| `labels` | String key/value pairs, up to 64. You can select queries by label when you match or list. |
| `metadata` | A JSON object of your own, up to 16 KB. It is returned with every match and never searched. |

A query that cannot be parsed, or that names a field the schema does not define, is refused with `400 query_error` and a
message that says what is wrong. Nothing is stored. Add `?dry_run=true` to check a query without registering it. A
registered query applies to the next match request.

Register many queries in one call with `PUT /v1/match/{queries-collection}`: a JSON array of objects, each with an
`id`, or `{"objects": [...], "replace": true}` to replace every registered query. Failures are reported per object
(`207`, or `400` when all fail), as in [ingest](ingesting-documents.md).

| Method and path | Role | Purpose |
|---|---|---|
| `PUT /v1/match/{queries-collection}/{id}` | writer | Register or replace one query. |
| `PUT /v1/match/{queries-collection}` | writer | Register many queries. |
| `GET /v1/match/{queries-collection}/{id}` | viewer | Read one registered query. |
| `GET /v1/match/{queries-collection}` | viewer | List registered queries, ordered by id. Takes `limit`, `offset` and repeated `label=key=value`. |
| `DELETE /v1/match/{queries-collection}/{id}` | writer | Unregister a query. |
| `POST /v1/match/{queries-collection}` | viewer | Match documents against the registered queries. |

An id is up to 128 characters of letters, digits and `-`, `_`, `.`, `:`, starting with a letter or digit.

## Match documents

`POST /v1/match/{queries-collection}` takes documents and returns, for each one, the registered queries that match. It
needs the `viewer` role.

```bash
curl -X POST https://api.warpsearch.io/v1/match/alerts \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": [
      {"id": "l-901", "title": "Sunny home with garden", "city": "Denver", "bedrooms": 3, "price": 450000},
      {"id": "l-902", "title": "Downtown studio", "city": "Denver", "bedrooms": 1, "price": 210000}
    ],
    "limit": 50,
    "highlight": {"fields": ["title"]}
  }'
```

```json
{
  "took_ms": 3,
  "collection": "alerts",
  "results": [
    {
      "doc": "l-901",
      "total": 1,
      "matches": [
        {
          "id": "q-4411",
          "labels": {"user": "u-77", "channel": "email"},
          "metadata": {"name": "Denver 3-bed under 500k"},
          "highlight": {"title": ["Sunny home with <em>garden</em>"]}
        }
      ]
    },
    {"doc": "l-902", "total": 0, "matches": []}
  ]
}
```

| Request field | Meaning |
|---|---|
| `docs` | The documents to match: flat JSON objects shaped like the collection's schema, as in [ingest](ingesting-documents.md#document-shape). An `id` is optional and comes back as `doc`. Required. |
| `labels` | Only try registered queries that carry all of these labels, for example `{"channel": "email"}`. |
| `limit`, `offset` | Page the matches of each document (default `limit` 100, capped by your plan). They count matches. |
| `highlight` | `{"fields": [...]}` with optional `pre_tag`, `post_tag` (default `<em>`, `</em>`) and `fragment_size`. Each match gets a `highlight` map of the fields' matching text. |
| `timeout_ms`, `max_bytes` | Caps for this request, each up to the plan's limit. |

Each result has `doc` (the document's `id`, or its position when it has none), `total` (the exact number of matches, so
you can tell when `limit` cut the list) and `matches`. Matches are ordered by query id and are not scored: a query
either matches the document or it does not. A document that cannot be read, for example one with an undefined field,
gets an `error` in its result and the others are still matched (`207`).

Matching a prefix, wildcard, regex or fuzzy query is decided per document, so a document's matches never depend on the
other documents in the request. Send documents in batches of up to 64 for the best throughput; the plan's limits on
documents and bytes per request apply (`413 request_too_large`).

## Match while ingesting

To match documents as you index them, name a queries collection on the ingest request. The documents go to the
collection in the path and are matched against the queries collection in `match`:

```bash
curl -X POST "https://api.warpsearch.io/v1/collections/listings/documents?commit=true&match=alerts" \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"id": "l-903", "title": "Garden flat", "city": "Denver", "bedrooms": 3, "price": 480000}]'
```

The ingest response gains a `matches` list per document, in the shape of a match result. The key needs the `writer`
role on `listings` and the `viewer` role on `alerts`. The queries collection must accept the documents' schema.

## Schema changes

A change to a queries collection's schema that would break registered queries, such as changing a field's type or
removing a field a query uses, is refused with `409 incompatible_schema`, and the message lists the query ids. Delete
or change those queries first. You can always add fields.

## Errors

| Status | Code | Meaning |
|---|---|---|
| `400` | `query_error` | The query to register cannot be parsed or names an unknown field. |
| `400` | `invalid_request` | Malformed body, unknown request field, an invalid query id, or no documents. |
| `404` | `not_found` | The queries collection or the registered query does not exist, or the collection is not of class `queries`. |
| `409` | `incompatible_schema` | A schema change would break registered queries. |
| `413` | `request_too_large` | Too many documents or bytes in one request. |
| `422` | `limit_exceeded` | `limit`, `offset + limit` or the query size is above the plan's limit. |

See [Limits and errors](limits-and-errors.md) for the plan limits that apply to requests.

## If you come from Elasticsearch or OpenSearch

There is no `percolator` field type, no `percolate` query and no mapping to keep in step with another index: the
queries collection's schema is the document schema. Registering is a `PUT`, not an index request on a document. The
answer lists every matching query id, unscored, instead of the top ten scored hits. The Elasticsearch-compatible API
does not support `percolate`; use this API instead. See [Elasticsearch](compat-elasticsearch.md).
