ldproxy

Features - Search

specdraftimplproposal

The building block Features - Search adds 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:

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:

Conformance Classes

This building block implements the OGC API Features extensions specified in the OGC Testbed-18 Filtering Service and Rule Set Engineering Report (to be published). The implementation will change as the draft will evolve during the standardization process.

Operations

ResourcePathMethodsMedia TypesDescription
Ad-hoc Query
search
POST
CSV, CityJSON, CityJSON-Seq, FlatGeobuf, GML, GeoJSON, HTML, JSON-FG
Execute an ad-hoc query
Stored Queries
search
GET
Fetch the stored queries available on the server.
Stored Query
search/{queryId}
GET
CSV, CityJSON, CityJSON-Seq, FlatGeobuf, GML, GeoJSON, HTML, JSON-FG
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

NameResourcesDescription
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

NameResourcesDescription
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

NameDefaultDescriptionTypeSince
buildingBlock
Always SEARCH.
string
v3.1
extensionType
Deprecated See buildingBlock.
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
Legal NoticePrivacy Notice