Features - Search

specdraftimplproposal

Support for fetching features from multiple collections as well as for stored queries.

Scope

This building block supports searching for features from one or more collections. That is, it supports query expressions that cannot be expressed, or cannot be conveniently expressed, using the filtering mechanisms available through the building blocks Features and Filter.

Examples of the types of query expressions that can be expressed:

• query expressions with a long expression text that cannot be conveniently specified as URL;
• query expressions that, in a single request, fetch resources from one or more collections;
• stored queries;
• stored queries referencing multiple resource collections;
• stored queries with parameters.

A query expression is expressed as a JSON object.

The query expression object can describe a single query (the properties "collections", "filter", "filterCrs", "properties" and "sortby" are members of the query expression object) or multiple queries (a "queries" member with an array of query objects is present) in a single request.

For each query:

• The value of "collection" is an array with one item, the identifier of the collection to query.
• The value of "filter" is a CQL2 JSON filter expression. See the Filter building block.
• The value of "filterCrs" is the URI of the coordinate reference system of coordinates in a "filter". The default is "http://www.opengis.net/def/crs/OGC/1.3/CRS84" (WGS 84, longitude/latitude).
• The value of "properties" is an array with the names of properties to include in the response. See the Projections building block.
• The value of "sortby" is used to sort the features in the response. See the Sorting building block.
• The value of "resultSets" is an object that declares named result sets. Each value is an
  object: if it is empty, the result set consists of the ids of the features selected by the
  query; with a member "values" naming a property, it consists of the ids referenced by that
  property of the selected features. "resultSet" with a name is a shorthand for a single
  result set of the selected ids.
• A later query can select features that are related to a result set with the CQL2 predicate
  {"op": "inResultSet", "args": [ { "property": "..." }, "name" ]} in its "filter". The
  predicate behaves like an IN expression (single values) or an A_OVERLAPS expression (arrays)
  against the object ids in the result set. A result set can only be referenced by queries
  that follow the declaring query.
• With "resultSetOnly": true, a query only declares its result sets; it contributes no
  features to the response and is excluded from "numberMatched" and "numberReturned".

For multiple queries:

• If multiple queries are specified, the results are concatenated. The response is a single
  feature collection. The feature ids in the response to a multi-collection query must be
  unique. Since the identifier of a feature only has to be unique per collection, they need
  to be combined with the collection identifier. A concatenation with "." as the joining
  character is used (e.g., "apronelement.123456"). If the feature provider declares that its
  feature ids are globally unique, the ids are not rewritten.
• The direct members "filter" and "properties" represent "global" constraints that must be
  combined with the corresponding member in each query. The global and local property selection
  list are concatenated and then the global and local filters are combined using the logical
  operator specified by the "filterOperator" member.
• The global member "filter" must only reference queryables that are common to all
  collections being queried.
• The global member "properties" must only reference presentables that are common to all
  collections being queried.
• A feature that is selected by more than one query appears once per selecting query. With
  "deduplicate": true, such a feature is only included in the response once. Note that
  "numberMatched" and "numberReturned" are computed before duplicates are dropped, so both
  can overcount when deduplication is enabled.

General remarks:

• A "title" and "description" for the query expression can be added. Providing both is
  strongly recommended to explain the query to users.
• The "limit" member applies to the entire result set. Responses are single-shot: there is no
  paging and no "next" links, "limit" is an upper bound for the number of features in the
  response.
• By default the response includes "numberMatched". Setting "computeNumberMatched" to false
  skips it; this avoids a count query per query and can be considerably faster for query
  expressions with many or chained queries. "numberMatched" is then not reported.
• The \u201ccrs\u201d and \u201cverticalCrs\u201d members are optional and can be used to specify the coordinate
  reference system for the coordinates in the response. If no value is specified, the default
  coordinate reference system is used. If "verticalCrs" is specified, then it must be the URI
  of a vertical coordinate reference system and "crs" must be specified and be the URI of a
  horizontal 2D coordinate reference system.
• "sortby" will only apply per query. A global "sortby" would require that the
  results of all queries are compiled first and then the combined result set is sorted. This
  would not support "streaming" the response.
• In case of a parameterized stored query, the query expression may contain JSON objects
  with a member "$parameter". The value of "$parameter" is an object with a member where the
  key is the parameter name and the value is a JSON schema describing the parameter. When
  executing the stored query, all objects with a "$parameter" member are replaced with the
  value of the parameter for this query execution. Comma-separated parameter values are
  converted to an array, if the parameter is of type "array".
• Parameters may also be provided in a member "parameters" in the query expression and
  referenced using "$ref".
• Parameters may be used in all members of the query expression, except "id", "title", and
  "description".
• A parameter whose schema has a "format" that starts with "geometry" (and no "type") takes a
  geometry, for example an area of interest in a spatial predicate. The value may be a geometry
  as WKT (well-known text) or a GeoJSON geometry. A format like "geometry-polygon" restricts the
  parameter to that geometry type (the type is validated). The coordinates are in the coordinate
  reference system specified by "filterCrs".

Limitations

Parameterized stored queries have the following constraints:

• The JSON Schema of a parameter supports a subset of the language. In particular,
  patternProperties, additionalProperties, allOf, oneOf, prefixItems,
  additionalItems and items: false are not supported.
• Parameters in filter expressions are limited to scalar values (string, number, boolean),
  arrays of scalar values, or geometries as WKT (see above).
• POST to execute a stored query is not supported. This will be added after discussing the
  specification in OGC (e.g., whether the payload should be JSON or URL-encoded query
  parameters).

Result sets have the following constraints:

• All collections referenced in a query expression that uses result sets must be served by the
  same feature provider.

In addition:

• Responses are not paged, limit is an upper bound for the number of features in the
  response. Large extracts are the use case for asynchronous execution, which is a separate
  work item.

Conformance Classes

This building block implements the OGC API Features extensions specified in chapters 5 and 6 of the OGC Testbed-18 Filtering Service and Rule Set Engineering Report. The implementation will change as the draft will evolve during the standardization process.

Operations

Resource	Path	Methods	Media Types	Description
Ad-hoc Query	search	POST	CSV, Debug Tokens, FlatGeobuf, GML, GeoJSON, HTML	Execute an ad-hoc query
Stored Queries	search	GET		Fetch the stored queries available on the server.
Stored Query	search/{queryId}	GET	CSV, Debug Tokens, FlatGeobuf, GML, GeoJSON, HTML	Execute the stored query. Parameters are submitted as query parameters.
Stored Query	search/{queryId}	DELETE, PUT		Create, Replace and Delete stored queries.
Stored Query Definition	search/{queryId}/definition	GET		Get the definition of the stored query.
Stored Query Parameters	search/{queryId}/parameters	GET		Get the definition of the query parameters
Stored Query Parameter	search/{queryId}/parameters/{name}	GET		Get the details of a query parameter

Path Parameters

Name	Resources	Description
queryId	Stored Query, Stored Query Definition, Stored Query Parameters, Stored Query Parameter	The identifier of the stored query.
name	Stored Query Parameter	The name of the query parameter.

Query Parameters

Name	Resources	Description
f	Search	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f	Search	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f	Stored Query	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
f	Stored Query Definition	Select the output format of the response. If no value is provided, the standard HTTP rules apply, i.e., the "Accept" header will be used to determine the format.
dry-run	Stored Query	Set to true to only validate the request, but not alter the stored query.

Configuration

Options

Name	Default	Description	Type	Since
buildingBlock		Always SEARCH.	string	v3.1
enabled	false	Enable the building block?	boolean	v3.1
caching	{}	Sets fixed values for HTTP Caching Headers for the resources.	object	v3.1
managerEnabled	false	Option to manage stored queries using PUT and DELETE.	boolean	v3.4
optimisticLockingLastModified	false	Option to enable support for conditional processing of PUT and DELETE requests, based on the time when the stored query was last updated. Such requests on an existing stored query must include an If-Unmodified-Since header, otherwise they will be rejected. A stored query will only be changed, if the stored query was not changed since the timestamp in the header (or if no last modification time is known for the stored query). The setting is ignored, if optimisticLockingETag is enabled.	boolean	v3.5
optimisticLockingETag	false	Option to enable support for conditional processing of PUT and DELETE requests, based on a strong Entity Tag (ETag) of the stored query. Such requests on an existing stored query must include an If-Match header, otherwise they will be rejected. A stored query will only be changed, if the stored query matches the Etag(s) in the header.	boolean	v3.5
validationEnabled	false	Option to validate stored queries when using PUT by setting a Prefer header with handling=strict.	boolean	v3.4
allLinksAreLocal	false	Signals feature encoders whether all link targets are within the same document.	boolean	v3.4

Storage

Stored queries must be located in the value store under the relative path queries/{apiId}/{queryId}.json.

Examples

- buildingBlock: SEARCH
 enabled: true
 managerEnabled: true
 validationEnabled: false
 allLinksAreLocal: true