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

Elasticsearch compatibility

WarpSearch answers the Elasticsearch REST API at https://api.warpsearch.io/compat/es. Official clients, Logstash, Beats, Fluent Bit and Grafana's Elasticsearch datasource talk to it the same way they talk to a cluster. The root URL reports Elasticsearch 8.11.0 and sends the X-Elastic-Product: Elasticsearch header that 8.x clients require.

The rule is simple. If a query or parameter can be translated exactly, it is. If only the scores differ and the same documents match, it runs and a Warning: 299 response header tells you what was approximated. Anything else fails with 400 and error type unsupported_feature, so you never get a silently wrong answer.

#Compatibility at a glance

#Connect

Create an API key in the management console. The role of the key decides what it may do: viewer searches, editor also writes documents, admin also creates collections and changes mappings.

WarpSearch accepts the key in any of these forms:

Not supported: HTTP Basic authentication with a console API key as the password. Configure your client to send one of the headers above.

Python:

from elasticsearch import Elasticsearch

es = Elasticsearch(
    "https://api.warpsearch.io/compat/es",
    api_key="ws_live_...",
)

es.search(index="books", query={"match": {"title": "dune"}})

curl:

curl -s https://api.warpsearch.io/compat/es/books/_search \
  -H "Authorization: ApiKey ws_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": {"match": {"title": "dune"}}}'

For the Java clients, set the same Authorization: ApiKey ... header as a default header on the REST client. The Java API client sends typed_keys=true, which WarpSearch does not honor, so aggregation results do not parse through it. Use the low-level REST client or raw JSON for aggregations.

Logstash and Beats use their normal Elasticsearch output with hosts set to the base URL and api_key set to your key. Grafana: add an Elasticsearch datasource with the base URL, send the key as a custom header, and choose the collection as the index.

#Endpoints

Index names are collection names.

Any other route answers 404.

#Query DSL

Coming soon: exact scoring for dis_max, multi_match best_fields and field patterns such as title*, multi-word match_phrase_prefix, and highlight. Today highlight is accepted with a warning and hits carry no highlight section.

#Aggregations

Sub-aggregations under a terms aggregation need a string or id field. Aggregation names can be any string and come back unchanged.

Not supported: pipeline aggregations (bucket_script, derivative, cumulative_sum, moving_fn, and the rest), composite, multi_terms, rare_terms, significant_terms, sampler, terms include and exclude, geo aggregations, and any aggregation with a script or missing on metrics.

#kNN and hybrid search

Send the Elasticsearch top-level knn section, or a knn query:

{
  "knn": {
    "field": "embedding",
    "query_vector": [0.12, -0.03, 0.88],
    "k": 10,
    "num_candidates": 100,
    "filter": {"term": {"genre": "scifi"}}
  }
}

A knn section beside a query is hybrid search. A document matches if either side matches, and its score is the sum of the two scores times their boosts. Several knn sections and boost work the same way. A knn filter narrows the vector search itself, before ranking.

Scores are WarpSearch similarity scores, not Elasticsearch's rescaled _score. Rank order is what to compare.

A dense_vector mapping with index_options.type such as hnsw or int8_hnsw asks for an approximate index. It is built when you call _refresh or _forcemerge; until then searches scan exactly. Build parameters such as m and ef_construction are accepted and ignored with a warning. See Vector search and Hybrid search.

Not supported: retriever and rank fusion, query_vector_builder, semantic and sparse_vector queries, inner_hits on nested vectors, and bit vectors (read as floats).

#Mappings

There is no dynamic mapping. A field in a document must either be mapped or carry a type suffix in its name (_t text, _s string, _i integer, _f float, _d double, _dt date, _v vector). Documents with other unmapped fields are rejected. See Schemas and field types.

Mappings can use text, keyword, boolean (stored as keyword), integer types, float, double, scaled_float, date, geo_point and dense_vector. Multi-fields such as title.keyword and copy_to work. Custom analyzers in settings.analysis are translated where possible; a component that cannot be reproduced (stop words, synonyms, n-grams, non-English stemmers) is dropped with a warning.

Field names that are not plain identifiers are mapped for you. @timestamp is stored as timestamp, and dots become underscores, so event.created is stored as event_created. You keep using your own names in queries and responses. If two names collide after mapping, the request fails.

Not supported: nested, join, ip, flattened, range types, geo_shape, completion, binary and alias fields. boolean and ip values are stored as strings today.

Coming soon: native boolean and ip types, flattened, range types and polygon geo queries.

#Write semantics

_bulk batches consecutive actions on one index and reports each item's result separately. Overload is reported per item as 429 so clients can retry just those items. An unknown index is created on first write if your key has the admin role.

• Without refresh, new documents become searchable on WarpSearch's own schedule. Use ?refresh=true or wait_for to make them searchable before the call returns.
• create and _create overwrite an existing document instead of failing with 409.
• _version is always 1, and result is always created (or updated for an upsert) and deleted. A delete of a missing id is not an error.
• update works only as doc_as_upsert with a whole document, which replaces the stored one. Partial updates fail per item.
• version, if_seq_no, if_primary_term and routing are ignored. Document gets see committed documents only.

Not supported: _update, _update_by_query, _delete_by_query, _reindex, ingest pipelines (the pipeline parameter is ignored), and conditional writes.

#Behavior differences

• Scores differ. Relevance scoring is not identical to Elasticsearch. Expect different _score values and occasional rank changes. Which documents match is exact wherever a feature is supported.
• _source is rebuilt from stored fields with your field names and object nesting. Booleans come back as strings and geo_point values may be absent.
• Totals are exact. hits.total.relation is always eq, and track_total_hits bounds are not applied (false still skips the count).
• Search responses omit _shards, and timed_out is always false. typed_keys and rest_total_hits_as_int are not supported.
• Hits carry no sort values, _version or _seq_no.
• Limits apply to result size, result window, facet size, query size and request rate. See Limits and errors.

Coming soon: bounded total hits for faster ranked queries.

#Errors and warnings

An unsupported feature fails with 400 in the Elasticsearch error shape:

{"error": {"type": "unsupported_feature", "reason": "..."}, "status": 400}

Unknown query or aggregation names are a normal query_error. An approximation returns 200 plus a Warning: 299 header. Your client library may surface these as warnings; log them while you test.

#Not supported, by theme

• Paging and exports: scroll, search_after, point in time, slices.
• Text: span, intervals, more_like_this, terms_set, percolate, suggesters, rescore, search_as_you_type subfields, highlight.
• Data model: nested and join fields, scripts and runtime_mappings, script_fields.
• Several indices: index patterns such as logs-*, multi-index searches, aliases, data streams.
• Cluster and lifecycle APIs: index templates, ILM, snapshots, cross-cluster search, _cat, _cluster, _nodes, _field_caps, _validate, _sql, _async_search.
• Applications: Kibana, ES|QL.

See Roadmap and status for what is in development, and Query languages for the native query languages that cover some of these gaps.

View this page as Markdown