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.

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").
• 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.

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.
• "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".

Limitations

Parameterized stored queries have the following constraints:

• Parameters can only occur in filter expressions.
• 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.
• 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).

Ad-hoc queries have the following limitations:

• Paging is not supported for ad-hoc queries and sufficiently large values for limit should be used. See issue 906.

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
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

Examples

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