Features - Searchspecdraftimplproposal
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.
- The global member "filter" must only reference queryables that are common to all
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
anditems: 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 | Execute an ad-hoc query | |
Stored Queries | search | GET | Fetch the stored queries available on the server. | |
Stored Query | search/{queryId} | GET | 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