Query JSON

A search as data: a JSON document with "v": 1, checked against a schema as it is read. It is meant for programs and language models that build a query without a C# compiler, and it compiles to the same query objects as every other surface. It is not compatible with Elasticsearch's query DSL.

{
  "v": 1,
  "q": "overdue \"acme corp\" -draft",
  "filter": "Tags = invoice AND Modified > 2024-01-01",
  "limit": 10,
  "highlight": true
}

SearchQuery<Invoice> search = index.Parse(json);            // throws QueryParseException with the JSON path
QueryRequest request = QueryJson.Read(json, index.Schema);   // the same, as data
string canonical = QueryJson.Write(request);

The document

With no q and no query, every document is a candidate. Unknown properties are errors that name the path and the nearest known name. These names are reserved for later versions and rejected with a message of their own: facets, aggregations, distinct, vector. hybrid is a property: an object that fuses the text search of q with a vector search over its embedding, and a node type hybrid joins knn for callers that bring a vector (both in hybrid.md; additive to version 1, so every document that was accepted reads the same). rerank is a property too: an object {"window":50} that rescores the best hits of the search with the index's reranker; it reads the text of q and is described in rerank.md (additive to version 1 as well). (sort and searchAfter were reserved in the first drafts of version 1 and are now properties: documents that used to be rejected are accepted, and every document that was accepted reads the same.)

Limits: the document is at most 1 MiB, strings 8,192 characters, query nodes nested 32 deep, 2,048 nodes in all. Invalid UTF-8 and lone surrogates are errors.

Query nodes

A node is an object with a type. Every node accepts "boost" (a non-negative number; default 1). Fields are checked against the schema: the name must exist and be indexed, and the kind of field decides what the node accepts.

A function object has a type, an optional weight (not negative; default 1) and an optional filter (a filter string or a node):

Function fields need a column, not an index. The custom function of the low-level API has no JSON form. A written origin is always a number (a date as milliseconds since 1970).

phrase, prefix, fuzzy, regex and multiFieldTerm carry already analyzed terms, as the query objects do: write them lower case for the default analyzer. To search words the way a user would, use text or strict ({"type":"strict","text":"Title:\"acme corp\""}).

Numbers on integer fields may be fractional in a range (rounded inward, as in filter strings). Dates are ISO strings: 2024-01-31, 2024-01-31T10:00:00Z, with an optional fraction and offset.

Paths in dynamic JSON

Wherever a node names a field, the name of a [Dynamic] property, a dot and a path name a path inside it ("field":"Meta.customer.age"). term, range and exists choose the kind of value from the JSON type of the value given (string, number, boolean; a string bound that reads as a date makes a date range); prefix, fuzzy, regex and phrase apply to strings. See dynamic.md.

Errors

A QueryParseException has Path ($.query.must[1].field), Detail, and Suggestion for a misspelt field, property or type. Text that is not JSON has no path; its Line and Column locate the syntax error. A filter or strict string with a mistake reports the position inside that string in the message, and the path of the string.

Canonical form and round trips

QueryJson.Write is canonical: properties in a fixed order (v, query, filter, limit, offset, countExactly, highlight, sort, searchAfter, rankingRules), nodes with type first, no white space, defaults left out, boosts as shortest round-trip numbers.

• Object to JSON to object is identity: Read(Write(request)) equals request for every request whose boolean clauses are grouped as must, filter, should, mustNot (the shapes of all our parsers). Interleaved clauses are written grouped, which keeps the order inside each group; their meaning is the same.
• JSON to object to JSON is canonical: any accepted document, whatever its property order or spacing, and with q, text, strict and filter nodes already compiled into query nodes, writes as one canonical document. Writing is deterministic.
• Range(v, v) with both bounds included and a value that is not text is written as a term; Range with no bounds as exists; a MatchAll as matchAll.
• Boost of 1 is not written. Include flags on an open bound are normalized to true.