Ga naar hoofdinhoud

Advanced search

Introduction​

An advanced search lets a user narrow down the items of a collection with filters, such as date ranges, geolocation and facet values, combined with 'and' and 'or'. It can combine these filters with a keyword query, a sort order and a page size.

An advanced search is optional. An integration layer MAY implement it, depending on its requirements. A keyword search without filters is available as a simple search.

A collection that supports an advanced search advertises the https://specs.nde.nl/rest/v1/advanced-search capability. It also exposes a Queryables resource, which lists the properties that a filter may use.

Search object​

A search object is a JSON object. It contains the search criteria of an advanced search.

The search object is an abstraction over query languages that developers may already know, such as Elasticsearch's query language or SQL. The abstraction is essential: an integration layer chooses its own data store, and this specification cannot prescribe the query language of one search engine or database. For filters, the search object uses the Common Query Language (CQL2); the other search criteria are defined by this specification. The search object is designed for a straightforward mapping to the native query language of a data store.

A search object has the following properties:

NameData typeCardinalityDescription
qstring0 or 1A keyword query. It has the same meaning as the q query parameter of a simple search. When the search object also has a filter, an item MUST match both.
orderByarray0 or 1An ordered list of sort criteria. The criteria apply in array order. If absent, the integration layer defines the order. It has the same meaning as the orderBy query parameter of a simple search.
orderBy[*]object1A sort criterion.
orderBy[*].propertystring1The property to sort on. It MUST be one of the properties that the collection supports for sorting. Which properties a collection supports, and what they mean, is documented with that collection.
orderBy[*].orderstring1The direction of the sort. It MUST be asc or desc.
sizenumber0 or 1The maximum number of items to retrieve. It has the same meaning as the size query parameter of a simple search.
filterobject0 or 1A CQL2 filter expression. See Filters.
contextstring0 or 1An identifier for an advanced search of the context collection. It is used only by facet collections and suggestion collections, to select the items on which their own items are based. The identifier MUST identify an advanced search of that context collection; otherwise the integration layer MUST respond with a 400 status code.

q and filter are complementary. q is a keyword query: it matches text across a set of properties that the integration layer defines, and it produces the relevance score that an orderBy criterion can use. filter is a boolean condition over the properties that the Queryables resource declares; it selects items but does not affect their relevance. An integration layer MUST combine them with a logical AND: an item is included only if it matches the keyword query and satisfies the filter.

An example of a search object:

{
"q": "rembrandt",
"orderBy": [
{
"property": "relevance",
"order": "desc"
}
],
"size": 20
}

The example searches the collection for items that match the keyword query rembrandt, returns 20 items per page, and sorts them by relevance, descending.

If the search object is invalid, or contains a filter with an operator or property that the API does not support, the integration layer MUST respond with a 400 status code.

To be discussed

Add support for OGC API's /sortables endpoint, to discover the properties that may be used to sort the items in a collection?

Filters​

A presentation layer can narrow down the items of a collection with filters. Filters are part of a search object. A presentation layer sends filters in the filter property of a search object to the advanced search endpoint.

This specification uses the Common Query Language (CQL2) for filters, in its JSON encoding. It has a JSON Schema which integration layers and presentation layers can use to validate a filter before executing or sending it. It also has an ecosystem of programming libraries for building, parsing and validating filters. An integration layer translates a CQL2 filter to the native query language of its data store.

Which filters a collection supports is described in two places. The conformance declaration of the API lists the CQL2 operators that the API supports. The Queryables resource of the collection lists the properties that a filter may use. Together they determine what a presentation layer can filter on.

This specification describes the following filter types:

Filter typeDescriptionExample
StringMatches text with =, in or like.Name starts with "Rem"
NumberCompares numbers with =, in, >, >=, <, <= or between.Number of pages is at least 300
DateCompares dates with =, in, >, >=, < or <=.Date of creation is between 1900 and 1950
BooleanCompares a boolean with = or in.Item has an image
GeolocationMatches a location with a spatial operator such as s_within, using a geometry such as a bounding box or polygon.Location of creation is inside a bounding box around Delft
FacetMatches the dimension of one of the collection's facet collections with =, in, a_contains or not a_overlaps, depending on the dimension's type. A facet filter uses the dimension of a facet collection: the queryable that the facet collection groups by. A presentation layer translates a selected facet item into a filter on that dimension. It uses the item's id or name as the value or, for a range value, its min and max as the bounds of the range. The dimension MUST be a property that the collection's Queryables resource declares.Creator is "Rembrandt" or "Vincent van Gogh", and Type is "Painting"
SetMatches all or none of a set of values with a_contains or not a_overlaps.Creator includes both "Rembrandt" and "Vincent van Gogh"

All filter types use the same CQL2 syntax. They differ only in the operators that apply and in the type of the operands that those operators expect.

A presentation layer MUST only use operators that the API's conformance declaration covers and properties that the collection's Queryables resource declares. If it uses another operator or property, the integration layer MUST respond with a 400 status code. Ignoring an unsupported filter would silently give the presentation layer more items than it asked for.

Conformance​

Which CQL2 operators the integration layer supports is declared in its conformance declaration. An integration layer that supports filters MUST publish such a declaration. It lists the CQL2 conformance classes that apply.

The conformance declaration MUST include http://www.opengis.net/spec/cql2/1.0/conf/cql2-json, because this specification uses the JSON encoding of CQL2. It MUST also include the class for every operator family that the API supports:

Conformance classURIAdds
Basic CQL2http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2and, or, not, =, <>, <, <=, >, >= and isNull
Advanced Comparison Operatorshttp://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operatorslike, between and in
Case-insensitive Comparisonhttp://www.opengis.net/spec/cql2/1.0/conf/case-insensitive-comparisoncasei
Accent-insensitive Comparisonhttp://www.opengis.net/spec/cql2/1.0/conf/accent-insensitive-comparisonaccenti
Spatial Functionshttp://www.opengis.net/spec/cql2/1.0/conf/spatial-functionss_within and the other spatial predicates
Temporal Functionshttp://www.opengis.net/spec/cql2/1.0/conf/temporal-functionst_after, t_before and the other temporal predicates
Array Functionshttp://www.opengis.net/spec/cql2/1.0/conf/array-functionsa_contains, a_overlaps and the other array predicates
Functionshttp://www.opengis.net/spec/cql2/1.0/conf/functionsCustom functions

Filter expressions​

The filter property holds one CQL2 expression. An expression is a JSON object. For example:

{
"op": "a_contains",
"args": [
{
"property": "creator"
},
["https://example.org/v1/entities/1234"]
]
}

Put in the filter property of a search object, it matches items that have the creator with ID https://example.org/v1/entities/1234.

The integration layer MUST validate the expression against the CQL2 JSON Schema, against the operators in the API's conformance declaration, and against the properties in the collection's Queryables resource. If the expression is invalid or contains an unsupported operator or property, the integration layer MUST respond with a 400 status code.

Operators​

CQL2 supports various operators. The table underneath lists examples of operators that an integration layer may support. It shows what each operator does in this API and which data types it applies to. The list is not exhaustive: an integration layer may also support other CQL2 operators and declare them in its conformance declaration.

CQL2 operator or functionApplies toMeaning
and, or, notAnyCombine or negate filter expressions.
=String, number, date, booleanEquals the value.
inString, number, date, booleanEquals one of the values.
likeStringMatches a pattern. % matches any sequence of characters; _ matches one character.
betweenNumberIs equal to or greater than the first value and equal to or less than the second value.
>, >=, <, <=Number, dateCompares with the value.
a_containsMulti-valued propertyContains every one of the values.
a_overlapsMulti-valued propertyShares at least one value. Use not a_overlaps for 'contains none'.
s_withinLocationIs inside a bounding box or polygon.

Operator support is the same for every collection: it follows from the conformance declaration, not from a capability of a collection. Property support differs per collection and is described by the collection's Queryables resource. A presentation layer MUST NOT use an operator that the API does not declare, or a property that the collection's Queryables resource does not declare. If it does, the integration layer MUST respond with a 400 status code.

Examples​

The examples below show a filter for each filter type and for combinations of filters.

String​

A text filter compares a string property. In CQL2, string properties are compared with =, in and like. The like operator uses % as a wildcard for any sequence of characters and _ for exactly one character. A pattern such as Rem% matches values that start with 'Rem'; %Rem% matches values that contain 'Rem'. For example:

{
"op": "like",
"args": [
{
"property": "name"
},
"Rem%"
]
}

This filter matches items whose name starts with 'Rem'.

Whether a string comparison is case-sensitive is defined by the integration layer. CQL2 also defines casei and accenti for case- and accent-insensitive comparison.

Number​

A numeric filter compares a number property. CQL2's =, in, >, >=, <, <= and between apply. between includes both boundaries: an item that equals either boundary matches. For example:

{
"op": "between",
"args": [
{
"property": "numberOfPages"
},
200,
300
]
}

This filter matches items that have 200 to 300 pages.

Date​

A date filter compares a date property. In CQL2, a date value is a full date in ISO 8601 YYYY-MM-DD format, written as { "date": "1900-01-01" }.

CQL2's =, in, >, >=, < and <= apply to dates. A single date is compared with =. For example:

{
"op": "=",
"args": [
{
"property": "dateCreated"
},
{
"date": "1900-01-01"
}
]
}

This filter matches items that were created on 1 January 1900.

A date range uses two comparisons, one for each boundary:

{
"op": "and",
"args": [
{
"op": ">=",
"args": [
{
"property": "dateCreated"
},
{
"date": "1900-01-01"
}
]
},
{
"op": "<=",
"args": [
{
"property": "dateCreated"
},
{
"date": "1950-12-31"
}
]
}
]
}

This filter matches items that were created between 1 January 1900 and 31 December 1950.

Boolean​

A boolean property is compared with = or in. For example:

{
"op": "=",
"args": [
{
"property": "hasImage"
},
true
]
}

This filter matches items that have an image.

Geolocation​

A geolocation filter uses a property that the collection documents as a location, such as the place where an item was created. CQL2 uses GeoJSON geometries. Coordinates are in decimal degrees, longitude first, latitude second.

A bounding box is a CQL2 bbox literal, in west, south, east, north order. For example:

{
"op": "s_within",
"args": [
{
"property": "locationCreated"
},
{
"bbox": [4.35, 52.005, 4.368, 52.018]
}
]
}

This filter matches items that were created inside the box around the city centre of Delft, the Netherlands.

A bounding box around a point can also be used to approximate a radius search. CQL2 has no standard radius search operator. Developers may know one from a search engine, but such operators are not portable: they differ in the unit of distance (for example metres, feet or degrees) and in the distance metric (straight-line distance in a projected coordinate system or distance over the Earth's surface). A bounding box (or a polygon — see below) is a portable approximation.

A polygon is a GeoJSON Polygon. For example:

{
"op": "s_within",
"args": [
{
"property": "locationCreated"
},
{
"type": "Polygon",
"coordinates": [
[
[4.3435, 52.0173],
[4.3484, 52.0176],
[4.3489, 52.0156],
[4.3477, 52.0145],
[4.3442, 52.0144],
[4.3435, 52.0173]
]
]
}
]
}

This filter matches items that were created inside a polygon of the Agnetapark in Delft, the Netherlands.

Facet​

A facet filter translates a selected facet item into a filter on the facet collection's dimension. For example:

{
"op": "=",
"args": [
{
"property": "additionalType"
},
"https://example.org/v1/entities/1122"
]
}

This filter matches items with type 'Painting', identified by its URI. The facet collection's dimension is additionalType. The filter value is the facet item's id when it has one, and its name otherwise. See Facet items.

Set​

A set filter matches all or none of a set of values. The a_contains operator matches items that have every value; not a_overlaps matches items that have none. For example:

{
"op": "a_contains",
"args": [
{
"property": "creator"
},
[
"https://example.org/v1/entities/7890",
"https://example.org/v1/entities/9012"
]
]
}

This filter matches items that have both creators, identified by their URIs. Use a_overlaps instead to match items that have at least one of them.

Combine or negate filters​

A filter with nested and and not conditions:

{
"filter": {
"op": "and",
"args": [
{
"op": "and",
"args": [
{
"op": ">=",
"args": [
{
"property": "dateCreated"
},
{
"date": "1600-01-01"
}
]
},
{
"op": "<=",
"args": [
{
"property": "dateCreated"
},
{
"date": "1700-12-31"
}
]
}
]
},
{
"op": "a_overlaps",
"args": [
{
"property": "creator"
},
[
"https://example.org/v1/entities/7890",
"https://example.org/v1/entities/9012"
]
]
},
{
"op": "not",
"args": [
{
"op": "=",
"args": [
{
"property": "additionalType"
},
"https://example.org/v1/entities/1122"
]
}
]
}
]
}
}

The filter matches items that were created between 1600 and 1700, have one of two creators, and are not of type 'Painting'.

Another example, with geolocation filters:

{
"filter": {
"op": "or",
"args": [
{
"op": "and",
"args": [
{
"op": "s_within",
"args": [
{
"property": "locationCreated"
},
{
"type": "Polygon",
"coordinates": [
[
[4.8858, 52.3854],
[4.9006, 52.3792],
[4.9135, 52.3735],
[4.9142, 52.3652],
[4.9045, 52.3588],
[4.8902, 52.3578],
[4.8785, 52.3635],
[4.8758, 52.3738],
[4.8805, 52.3818],
[4.8858, 52.3854]
]
]
}
]
},
{
"op": "like",
"args": [
{
"property": "name"
},
"De%"
]
}
]
},
{
"op": "and",
"args": [
{
"op": "s_within",
"args": [
{
"property": "locationCreated"
},
{
"bbox": [4.35, 52.005, 4.368, 52.018]
}
]
},
{
"op": ">=",
"args": [
{
"property": "numberOfPages"
},
300
]
}
]
}
]
}
}

The filter matches items that are either inside a polygon of Amsterdam and have a name that starts with 'De', or lie inside a bounding box around Delft and have at least 300 pages.

A filter can combine string conditions in the same way:

{
"filter": {
"op": "or",
"args": [
{
"op": "=",
"args": [
{
"property": "name"
},
"The Night Watch"
]
},
{
"op": "like",
"args": [
{
"property": "description"
},
"%Rembrandt%"
]
}
]
}
}

The filter matches items whose name or description matches one of several string conditions.

Translating filters​

CQL2 is independent of the data store of an integration layer. The table below shows the closest equivalent of each CQL2 operator. It is illustrative, not prescriptive: data stores differ between versions, and an integration layer can preprocess data or evaluate an expression in application code when there is no native equivalent.

CQL2ElasticsearchTypesense filter_byPostgreSQL
andbool.must&&AND
orbool.should with minimum_should_match: 1||OR
notbool.must_notnegate the conditionNOT
=term or matchproperty:=valueproperty = value
intermsproperty:=[a, b]property IN (a, b)
a_containsbool.must with one term per valueproperty:=a && property:=bproperty @> ARRAY[a, b]
a_overlapsbool.should with one term per valueproperty:=[a, b]property && ARRAY[a, b]
not a_overlapsbool.must_not with termsproperty:!=[a, b]NOT (property && ARRAY[a, b])
betweenrange with gte and lteproperty:[a..b]property BETWEEN a AND b
<, <=, >, >=range with the same nameproperty:<value, property:<=value, property:>value, property:>=value<, <=, >, >=
like with v%prefixproperty:value*property LIKE 'v%'
like with %v%wildcard with *v*property:*value* (requires an infix index)property LIKE '%v%'
s_within with bboxgeo_bounding_boxproperty:(...) polygon with the four cornersST_Within with ST_MakeEnvelope
s_within with Polygongeo_shape with a polygonproperty:(...) polygon with the cornersST_Within with ST_GeomFromGeoJSON
casei, accentidepends on the analyzer or normalizercase-insensitive by defaultILIKE or lower()

Queryables​

A Queryables resource describes the properties of a collection that a filter may refer to. It is a machine-readable list of property names and their data types. With it, a presentation layer can build a filter without guessing which properties exist.

A Queryables resource is a JSON Schema document, not a resource of the data model. A collection refers to it with a queryables property that holds its identifier.

The resource follows the Queryables requirements class. That standard defines the resource, its media type and the shape of its response.

A Queryables resource describes properties, not operators. Which CQL2 operators the API supports is declared once, in the API's conformance declaration. A collection that advertises the advanced search capability MUST expose its Queryables resource.

Search identifier​

An advanced search needs an identifier, because a presentation layer cannot repeat the search criteria in later requests. It sends the criteria in the body of the POST request that starts the search, but it retrieves pages and facets with GET requests, which have no request body. The identifier lets the presentation layer refer to the same search in those requests.

The integration layer returns the identifier in the response URIs of the advanced search. In those URIs, it appears as the search query string parameter: that parameter is the protocol implementation of the identifier.

An identifier is opaque. A presentation layer MUST NOT try to interpret it, build it or change it. It MUST pass the value back unchanged in every subsequent request.

The integration layer connects the identifier to the search object. It can do that in two ways:

  • Stateless: the integration layer encodes the search object in the identifier itself. It MAY compress, sign or encrypt the value. It MAY also use a plain encoding, such as Base64URL, as long as it validates the decoded search object before using it. For example, the identifier may be the JSON search object compressed and then encoded with Base64URL.
  • Stateful: the integration layer stores the search object on its server and gives the identifier a value that refers to it. It manages the lifecycle of the stored object itself, such as its expiry date. For example, the identifier may be a random UUID that the integration layer uses as the key of the stored search object in a database.

Both implementations look the same to a presentation layer. The specification does not prescribe which one an integration layer uses.

An identifier is bound to the collection and to the search object. A presentation layer MUST NOT use it with another collection or with another advanced search. If it does, the integration layer MUST respond with a 400 status code.

The identifier MUST appear in every URI that navigates the search results: the id of the page, prev.id, next.id, partOf.id, partOf.pageUriTemplate, partOf.first.id and partOf.last.id. It MUST also appear in the id, first.id, first.next.id, last.id and pageUriTemplate of the filtered collection.

The search parameter and the simple search parameters (q, orderBy, size) are mutually exclusive. A presentation layer MUST NOT combine them in one request. If it does, the integration layer MUST respond with a 400 status code.

A facet collection and a suggestion collection can also use the context parameter. It holds the identifier of an advanced search of the collection's context collection. It is independent of the search parameter: search refers to an advanced search of the collection itself, while context refers to an advanced search of its context collection. See the search context of facet collections and suggestion collections.

To be discussed

A filtered collection is a view with its own id, totalItems and pages. Is it part of the collection tree, or a separate, temporary resource? And how long must the identifier remain valid? A URI that contains an identifier is only dereferenceable while the integration layer knows the search object. Should the specification define a minimum lifetime, and what should the integration layer return after that (e.g. 410 Gone)?

The endpoint searches a collection. The integration layer MUST implement this endpoint for every collection that supports advanced search.

HTTP request​

POST /{version}/{...collections}/search

The endpoint uses the POST method. It does not use GET, because a query string is a poor fit for complex criteria. It has a limited length, and it must be URL-encoded, which makes the search criteria hard to read and easy to get wrong.

The search path segment of the endpoint is a verb rather than a noun. This is an explicit exception to the naming of resources, allowed by the REST API Design Rules.

Path parameters​

NameData typeCardinalityDescription
versionstring1The version of the API. Example: v1.
...collectionsstring1 or moreThe path identifier(s) of the context collection. Example: collections/objects.

Query parameters​

None.

Request headers​

NameValue
Content-Typeapplication/json

Request body​

The request body MUST contain a JSON-formatted search object.

Response body​

The response is the filtered Collection. If the collection is divided into pages, it includes the first page in first; otherwise it includes all matching items in items. The response URIs contain the search identifier.

Example​

An example request from a presentation layer:

POST /v1/collections/masterpieces/search
Host: example.org
Content-Type: application/json

{
"q": "rembrandt",
"orderBy": [
{
"property": "relevance",
"order": "asc"
}
]
}

This tells the integration layer that the presentation layer is searching for resources in the 'Masterpieces' collection that match the keyword 'rembrandt' and that matching resources must be ordered by relevance, ascending.

An example of the response of the integration layer:

{
"@context": "https://example.org/v1/context.json",
"id": "https://example.org/v1/collections/masterpieces?search=abc",
"type": "CuratedCollection",
"name": "Masterpieces",
"totalItems": 42,
"pageUriTemplate": "https://example.org/v1/collections/masterpieces?search=abc{&page}",
"first": {
"id": "https://example.org/v1/collections/masterpieces?search=abc&page=1",
"type": "Page",
"name": "Masterpieces: page 1",
"items": [
{
"id": "https://example.org/v1/entities/1234",
"type": "HeritageObject",
"name": "The Night Watch"
}
// Other items...
],
"next": {
"id": "https://example.org/v1/collections/masterpieces?search=abc&page=2",
"type": "Page"
}
},
"last": {
"id": "https://example.org/v1/collections/masterpieces?search=abc&page=3",
"type": "Page"
},
"partOf": {
"id": "https://example.org/v1/collections",
"type": "CuratedCollection",
"name": "Collections"
},
"capabilities": [
"https://specs.nde.nl/rest/v1/simple-search",
"https://specs.nde.nl/rest/v1/advanced-search",
"https://specs.nde.nl/rest/v1/facets",
"https://specs.nde.nl/rest/v1/suggestions"
],
"queryables": {
"id": "https://example.org/v1/collections/masterpieces/queryables"
}
}

The response indicates that the advanced search has 42 results, that the collection includes its first page in first, and that the next page is page 2. The search parameter in the URIs of properties id, first.id, first.next.id, last.id and pageUriTemplate is an identifier for a search object.

Endpoint: Queryables​

The endpoint returns the Queryables resource of a collection: a JSON Schema document that lists the properties a filter may use, with their data types. A presentation layer requests it before it builds a filter. The integration layer MUST implement this endpoint for every collection that supports advanced search.

HTTP request​

GET /{version}/{...collections}/queryables

Path parameters​

NameData typeCardinalityDescription
versionstring1The version of the API. Example: v1.
...collectionsstring1 or moreThe path identifier(s) of the collection. Example: collections/objects.

Query parameters​

None.

Request body​

None.

Response headers​

NameValue
Content-Typeapplication/schema+json

Response body​

The body MUST be a JSON Schema document. It describes one object: the collection's properties. The following requirements apply:

  • $schema MUST be https://json-schema.org/draft/2020-12/schema.
  • $id MUST be the URI of the Queryables resource, without query parameters.
  • type MUST be object.
  • properties MUST contain one entry for every property that a filter may use. The key of an entry is the property name that a presentation layer puts in a CQL2 property reference.
  • title and description SHOULD describe the resource and each property, in plain language.
  • A property MUST have a type, such as string, number, integer, boolean or array, with items for an array. A property MAY add constraints, such as enum, minimum or maximum.
  • A date or date-time property MUST have type string and format date or date-time.
  • A geolocation property MUST NOT have a type or $ref. It MUST have a format that starts with geometry-, such as geometry-point or geometry-polygon.
  • additionalProperties determines what happens with a property that is not declared. If it is false, the integration layer MUST respond with a 400 status code when a filter uses another property. If it is true or omitted, another property is allowed and evaluates to null when the item has no such value.

A property name is an opaque reference. The integration layer decides how it maps to its data model. That matters for nested data: CQL2 has no syntax for a path into a nested object, which means every filterable value needs its own name. For example, an item with a nested creator.name can expose a queryable creatorName next to its top-level name.

Example​

Example of the response body of the Queryables resource of a collection of heritage objects:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.org/v1/collections/objects/queryables",
"type": "object",
"title": "Heritage objects",
"description": "The properties of heritage objects that can be used in a filter",
"properties": {
"name": {
"title": "Name",
"description": "The name of the heritage object",
"type": "string"
},
"dateCreated": {
"title": "Date of creation",
"description": "The date on which the object was created",
"type": "string",
"format": "date"
},
"hasImage": {
"title": "Has image",
"description": "Whether the object has an image",
"type": "boolean"
},
"creator": {
"title": "Creator",
"description": "The identifiers of the creators of the object",
"type": "array",
"items": {
"type": "string"
}
},
"locationCreated": {
"title": "Location of creation",
"description": "The place where the object was created",
"format": "geometry-point"
}
}
}

The response indicates that a filter on this collection may use five properties. name is a string, dateCreated is a date, hasImage is a boolean, creator is an array of identifiers and locationCreated is a point geometry.

An advanced search takes several requests. A presentation layer starts the search with one request and then uses the search identifier that the response contains to retrieve further results.

The steps below use a collection that is divided into pages as an example. If the integration layer returns the full collection instead, some steps differ: there are no page URIs to follow, but the identifier still appears in the URIs of the collection.

  1. Check the capability. The collection advertises the https://specs.nde.nl/rest/v1/advanced-search capability.
  2. Retrieve the Queryables. The presentation layer requests the collection's Queryables resource to learn which properties a filter may use.
  3. Submit the search. A presentation layer sends a POST request with a search object to the search endpoint of the collection, using the properties that the Queryables resource declares and the operators that the API's conformance declaration lists. The integration layer runs the search and returns the filtered Collection. If the collection is divided into pages, the first results are in first; otherwise they are in items. It gives the search an identifier and includes it as the search parameter in every URI that refers to the search.
  4. Retrieve further results. If the collection is divided into pages, a presentation layer follows a page URI from the response, such as first.next.id. If the collection has a pageUriTemplate, it can also expand that template with a page number to go straight to a page. It passes the search parameter unchanged. It does not send the search object again: the identifier already refers to it.
  5. Retrieve facets (optional). A presentation layer requests each facet collection separately, with the context parameter set to the identifier of the advanced search of the collection. It can set size and orderBy per request, which means every facet can show its own number of items in its own order. The facet items and their counts then cover only the items that match the search. The search parameter of the facet collection refers to an advanced search of the facet collection itself, not to the context collection.
  6. Start another search. A new search is a new POST request with a new search object. It gets its own identifier. An identifier is bound to its collection and its search object; it cannot be used for another collection or another search.

Steps 1 and 2 are discovery, not part of the search itself. Their results change only when the collection changes. A presentation layer can retrieve them once, cache them and reuse them for later searches; the caching headers of the responses determine for how long.

The following sequence diagram shows the requests for this paginated example: