For AI agents: this page is also available as Markdown at /docs/match-api.md. Every docs page is: add .md to its URL. llms.txt lists them all.

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.

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.

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.

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.
filters Non-scoring restrictions, written in the query's language, as in search.
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.

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.

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"]}
  }'
{
  "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. 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:

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

View this page as Markdown

Cookie settings

Optional tracking stays off until you choose it. Your choice applies to this browser for 180 days. Read the details.

Essential storage keeps you signed in, protects forms, and remembers this choice. It is always available.