API Syntax 101

The query syntax for metadata server follows a client directed query methodology, whereby the consumer of the API provides a detailed specification of the query it wants to execute rather than adhering to a very strict REST template. This provides flexibility to the client but puts a lot of responsibility on the client developer to write efficient queries.

Query document

MDS uses the idea of a query document to specify queries, rather than a more traditional key-value filter or DQL (e.g. SQL) format. The query documents are JSON format and are provided in the filter parameter of an API request.

Equality

Simple equality is expressed through query-by-example semantics; for example, to get the object with id "1234-5678":

?filter={"id": "1234-5678"}

Sub-object reference

If the API being queried supports sub-objects, you can reference the fields of the sub-object using simple dot notation:

?filter={"editorial.id": "1234-5678"}

Conjunction (AND)

A comma-list of conditions is naturally joined as an AND:

?filter={"editorial.id": "1234", "technical.id": "5678"}

For much more complex queries, you can explicitly write this with an $and:

?filter={"$and": [{"editorial.id": "1234"}, {"technical.id": "5678"}]}

Disjunction (OR)

Similar to $and:

?filter={"$or": [{"editorial.id": "1234"}, {"technical.id": "5678"}]}

Negation (NOT)

To apply an inverse condition:

?filter={$ne": {"editorial.id": "1234-5678"}}

Ranges

Greater than ($gt), less than ($lt), greater than or equal to ($gte), and less than or equal to ($lte), can be applied as follows:

?filter={"period.start": {"$gte": 1000, "$lt": 2000}}

In

Allows you to match on a set of values:

?filter={"editorial.id": {"$in": ["1234", "5678"]}

Exists

Returns if a field exists (or not):

?filter={"editorial.id": {"$exists": true}}