Query language¶
The body of POST /v1/query
looks like so:
The elements of that query are defined here.
Fallback rule¶
Unless otherwise required by one of the other rules below or to follow, values are interpreted according to Daml-LF JSON Encoding, and compared for equality.
All types are supported by this simple equality comparison except:
- lists
- textmaps
- genmaps
Simple equality¶
Match records having at least all the (potentially nested) keys expressed in the query. The result record may contain additional properties.
Example: { person: { name: "Bob" }, city: "London" }
- Match:
{ person: { name: "Bob", dob: "1956-06-21" }, city: "London", createdAt: "2019-04-30T12:34:12Z" }
- No match:
{ person: { name: "Bob" }, city: "Zurich" }
- Typecheck failure:
{ person: { name: ["Bob", "Sue"] }, city: "London" }
A JSON object, when considered with a record type, is always interpreted as a field equality query. Its type context is thus mutually exclusive with comparison queries.
Comparison query¶
Match values on comparison operators for int64, numeric, text, date, and
time values. Instead of a value, a key can be an object with one or more
operators: { <op>: value }
where <op>
can be:
"%lt"
for less than"%gt"
for greater than"%lte"
for less than or equal to"%gte"
for greater than or equal to
"%lt"
and "%lte"
may not be used at the same time, and likewise
with "%gt"
and "%gte"
, but all other combinations are allowed.
Example: { "person" { "dob": { "%lt": "2000-01-01", "%gte": "1980-01-01" } } }
- Match:
{ person: { dob: "1986-06-21" } }
- No match:
{ person: { dob: "1976-06-21" } }
- No match:
{ person: { dob: "2006-06-21" } }
These operators cannot occur in objects interpreted in a record context, nor may other keys than these four operators occur where they are legal, so there is no ambiguity with field equality.
Appendix: Type-aware queries¶
This section is non-normative.
This is not a JSON query language, it is a Daml-LF query language. So, while we could theoretically treat queries (where not otherwise interpreted by the “may contain additional properties” rule above) without concern for what LF type (i.e. template) we’re considering, we will not do so.
Consider the subquery {"foo": "bar"}
. This query conforms to types,
among an unbounded number of others:
In the cases of A
and B
, "foo"
is part of the query
language, and only "bar"
is treated as an LF value; in the case of
C
, the whole query is treated as an LF value. The wide variety of
ambiguous interpretations about what elements are interpreted, and what
elements treated as literal, and how those elements are interpreted or
compared, would preclude many techniques for efficient query compilation
and LF value representation that we might otherwise consider.
Additionally, it would be extremely easy to overlook unintended meanings
of queries when writing them, and impossible in many cases to suppress
those unintended meanings within the query language. For example, there
is no way that the above query could be written to match A
but never
C
.
For these reasons, as with LF value input via JSON, queries written in JSON are also always interpreted with respect to some specified LF types (e.g. template IDs). For example:
will treat "foo"
as a field equality query for A and B, and
(supposing templates’ associated data types were permitted to be
variants, which they are not, but for the sake of argument) as a whole
value equality query for C.
The above “Typecheck failure” happens because there is no LF type to
which both "Bob"
and ["Bob", "Sue"]
conform; this would be
caught when interpreting the query, before considering any contracts.
Appendix: Known issues¶
When using Oracle, queries fail if a token is too large¶
This limitation is exclusive to users of the HTTP JSON API using Daml Enterprise support for Oracle. Due to a known limitation in Oracle, the full-test JSON search index on the contract payloads rejects query tokens larger than 256 bytes. This limitations shouldn’t impact most workloads, but if this needs to be worked around, the HTTP JSON API server can be started passing the additional disableContractPayloadIndexing=true
(after wiping an existing query store database, if necessary).