ldproxy

Features - Search

specdraftimplproposal

Unterstützung für den Abruf von Features aus mehreren Collections sowie für gespeicherte Abfragen.

Umfang

Dieser Baustein unterstützt die Suche nach Features aus einer oder mehreren Collections. Das heißt, es unterstützt Abfragen, die mit den Filtermechanismen, die durch die Bausteine Features und Filter zur Verfügung stehen, nicht oder nicht bequem ausgedrückt werden können.

Datenformate, die nur eine einzige Objektart mit einem festen Schema pro Datei unterstützen, werden für Endpunkte dieses Bausteins automatisch deaktiviert.

Beispiele für die Arten von Abfragen:

  • Abfragen mit einem langen Ausdruckstext, der nicht bequem als URL angegeben werden kann;
  • Abfragen, die in einer einzigen Anfrage Ressourcen aus einer oder mehreren Collections abrufen;
  • gespeicherte Abfragen;
  • gespeicherte Abfragen, die mehrere Collections referenzieren;
  • gespeicherte Abfragen mit Parametern.

Eine Query Expression wird als JSON-Objekt ausgedrückt.

Das Query-Expression-Objekt kann eine einzelne Abfrage (Key-Value-Paare "collections", "filter", "properties" und "sortby") oder mehrere Abfragen (Key-Value-Paar "queries" mit einem Array von Abfrageobjekten) in einer einzigen Anfrage beschreiben.

Für jede Abfrage:

  • Der Wert von "collection" ist ein Array mit einem Element, dem Identifikator der abzufragenden Feature Collection.
  • Der Wert von "filter" ist ein CQL2 JSON-Filterausdruck. Siehe den Filter-Baustein.
  • Der Wert von "filterCrs" ist die URI des Koordinatenreferenzsystems der Koordinaten in einem "filter". Der Standardwert ist "http://www.opengis.net/def/crs/OGC/1.3/CRS84open in new window" (WGS 84, Longitude/Latitude).
  • Der Wert von "properties" ist ein Array mit den Namen der Eigenschaften, die in die Antwort aufgenommen werden sollen. Siehe den Projections-Baustein.
  • Der Wert von "sortby" wird zum Sortieren der Merkmale in der Antwort verwendet. Siehe den Sorting-Baustein.
  • Der Wert von "resultSets" ist ein Objekt, das benannte Result-Sets deklariert. Jeder Wert ist ein Objekt: Ist es leer, besteht das Result-Set aus den IDs der von der Abfrage selektierten Features; mit einem Member "values", das eine Eigenschaft benennt, besteht es aus den IDs, die von dieser Eigenschaft der selektierten Features referenziert werden. "resultSet" mit einem Namen ist eine Kurzform für ein einzelnes Result-Set der selektierten IDs.
  • Eine spätere Abfrage kann Features selektieren, die mit einem Result-Set in Beziehung stehen, und zwar mit dem CQL2-Prädikat {"op": "inResultSet", "args": [ { "property": "..." }, "name" ]} in ihrem "filter". Das Prädikat verhält sich wie ein IN-Ausdruck (einzelne Werte) bzw. wie ein A_OVERLAPS-Ausdruck (Arrays) gegen die Objekt-IDs im Result-Set. Ein Result-Set kann nur von Abfragen referenziert werden, die auf die deklarierende Abfrage folgen.
  • Mit "resultSetOnly": true deklariert eine Abfrage nur ihre Result-Sets; sie trägt keine Features zur Antwort bei und wird in "numberMatched" und "numberReturned" nicht berücksichtigt.

Für mehrere Abfragen:

  • Wenn mehrere Abfragen angegeben werden, werden die Ergebnisse zusammengeführt. Die Antwort ist eine einzelne Feature Collection. Die Feature-IDs in der Antwort auf eine Abfrage mit mehreren Feature Collections müssen eindeutig sein. Da der Bezeichner eines Features nur pro Feature Collection eindeutig sein muss, müssen sie mit der Feature-Collection-ID kombiniert werden. Es wird eine Verkettung mit "." als Verbindungszeichen verwendet (z. B. "apronelement.123456"). Deklariert der Feature-Provider, dass seine Feature-IDs global eindeutig sind, werden die IDs nicht umgeschrieben.
  • Die direkten Key-Value-Paare "filter" und "properties" stellen 'globale' Bedingungen dar, die in jeder Abfrage mit dem entsprechenden Key-Value-Paar kombiniert werden müssen. Die globale und die lokale Eigenschaftsauswahlliste werden verkettet. Die globalen und lokalen Filter werden mit dem logischen Operator kombiniert, der durch das Mitglied "filterOperator" angegeben wird.
  • Das globale Mitglied "filter" darf nur auf Queryables verweisen, die allen abgefragten Collections gemeinsam sind.
  • Das globale Mitglied "properties" darf nur auf Presentables verweisen, die allen abgefragten Collections gemeinsam sind.
  • Ein Feature, das von mehr als einer Abfrage selektiert wird, erscheint einmal pro selektierender Abfrage. Mit "deduplicate": true wird ein solches Feature nur einmal in die Antwort aufgenommen. Hinweis: "numberMatched" und "numberReturned" werden berechnet, bevor Duplikate entfernt werden, beide können also zu hoch sein, wenn die Deduplizierung aktiviert ist.

Allgemeines:

  • Ein "Titel" und eine "Beschreibung" für die Query Expression können hinzugefügt werden. Es wird dringend empfohlen, beides anzugeben, um Benutzern die Abfrage zu erklären.
  • Das Element "limit" gilt für die gesamte Ergebnismenge. Antworten werden nicht in Seiten aufgeteilt: Es gibt kein Paging und keine "next"-Links, "limit" ist eine Obergrenze für die Anzahl der Features in der Antwort.
  • Standardmäßig enthält die Antwort "numberMatched". Wird "computeNumberMatched" auf false gesetzt, wird darauf verzichtet; dies vermeidet eine Count-Abfrage pro Abfrage und kann bei Query Expressions mit vielen oder verketteten Abfragen deutlich schneller sein. "numberMatched" wird dann nicht ausgegeben.
  • Die Elemente "crs" und "verticalCrs" sind optional und können verwendet werden, um das Koordinatenreferenzsystem für die Koordinaten in der Antwort zu spezifizieren. Ist kein Wert angegeben, dann wird das Standard-Koordinatenreferenzsystem verwendet. Ist "verticalCrs" angegeben, dann muss es die URI eines vertikalen Koordinatenreferenzsystem sind und "crs" angegeben sein und die URI eines horizontales 2D-Koordinatenreferenzsystem sein.
  • "sortby" wird nur pro Abfrage angewendet. Ein globales "sortby" würde erfordern, dass die Ergebnisse aller Abfragen zuerst kompiliert werden und dann die kombinierte Ergebnismenge sortiert wird. Dies würde das "Streaming" der Antwort nicht unterstützen.
  • Im Falle einer parametrisierten gespeicherten Abfrage kann der Abfrageausdruck JSON-Objekte mit einem Member "$parameter" enthalten. Der Wert von "$parameter" ist ein Objekt mit einem Key-Value-Paar, bei dem der Schlüssel der Parametername und der Wert ein JSON-Schema ist, das den Parameter beschreibt. Bei der Ausführung der gespeicherten Abfrage werden alle Objekte mit einem "$parameter"-Member durch den Wert des Parameters für diese Abfrageausführung ersetzt. Kommagetrennte Parameterwerte werden in ein Array umgewandelt, wenn der Parameter vom Typ "array" ist.
  • Parameter können auch in einem Member "parameters" im Abfrageausdruck angegeben werden und mit "$ref" referenziert werden.
  • Parameter können in allen Membern der Query Expression verwendet werden, außer in "id", "title" und "description".
  • Ein Parameter, dessen Schema ein "format" hat, das mit "geometry" beginnt (und keinen "type"), nimmt eine Geometrie entgegen, zum Beispiel ein Suchgebiet in einem räumlichen Prädikat. Der Wert kann eine Geometrie als WKT (Well-Known Text) oder eine GeoJSON-Geometrie sein. Ein Format wie "geometry-polygon" beschränkt den Parameter auf diesen Geometrietyp (der Typ wird validiert). Die Koordinaten liegen in dem durch "filterCrs" angegebenen Koordinatenreferenzsystem vor.

Limitierungen

Für parametrisierte gespeicherte Abfragen gelten die folgenden Beschränkungen:

  • Das JSON-Schema eines Parameters unterstützt eine Teilmenge der Sprache. Insbesondere werden patternProperties, additionalProperties, allOf, oneOf, prefixItems, additionalItems und items: false nicht unterstützt.
  • Parameter in Filterausdrücken sind auf Skalarwerte (Strings, Zahlen, Boolesche Werte), Arrays von Skalarwerten oder Geometrien als WKT (siehe oben) beschränkt.
  • POST zur Ausführung einer gespeicherten Abfrage wird nicht unterstützt. Dies wird hinzugefügt, nachdem die Spezifikation in OGC diskutiert wurde (z.B. ob die Nutzlast JSON oder URL-kodierte Abfrageparameter sein sollen).

Für Result-Sets gelten die folgenden Beschränkungen:

  • Alle in einer Query Expression mit Result-Sets referenzierten Collections müssen vom selben Feature-Provider bereitgestellt werden.

Außerdem:

  • Antworten werden nicht in Seiten aufgeteilt, limit ist eine Obergrenze für die Anzahl der Features in der Antwort. Für große Abrufe ist die asynchrone Ausführung von Abfragen vorgesehen, die ein separates Arbeitspaket ist.

Konformitätsklassen

Dieser Baustein implementiert die OGC-API-Features-Erweiterungen, die in den Kapiteln 5 und 6 des OGC Testbed-18 Filtering Service and Rule Set Engineering Reportopen in new window spezifiziert sind. Die Implementierung wird sich im Zuge der weiteren Standardisierung der Spezifikation noch ändern.

Operationen

RessourcePfadMethodenFormateBeschreibung
Ad-hoc Query
search
POST
CSV, Debug Tokens, FlatGeobuf, GML, GeoJSON, HTML
Eine Ad-hoc-Query ausführen
Stored Queries
search
GET
Abrufen der auf dem Server verfügbaren Abfragen.
Stored Query
search/{queryId}
GET
CSV, Debug Tokens, FlatGeobuf, GML, GeoJSON, HTML
Führt die gespeicherte Abfrage aus. Parameter werden als Abfrageparameter übergeben.
Stored Query
search/{queryId}
DELETE, PUT
Erzeugen, Ersetzen und Löschen von Stored Queries.
Stored Query Definition
search/{queryId}/definition
GET
Abrufen der Definition der gespeicherten Abfrage.
Stored Query Parameters
search/{queryId}/parameters
GET
Abrufen der Definition der Abfrageparameter
Stored Query Parameter
search/{queryId}/parameters/{name}
GET
Abrufen der Details eines Abfrageparameters

Pfad-Parameter

NameRessourcenBeschreibung
queryId
Stored Query, Stored Query Definition, Stored Query Parameters, Stored Query Parameter
Der Identifikator der gespeicherten Abfrage.
name
Stored Query Parameter
Der Name des Abfrageparameters.

Query Parameter

NameRessourcenBeschreibung
f
Search
Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
f
Search
Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
f
Stored Query
Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
f
Stored Query Definition
Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
dry-run
Stored Query
Bei true wird die Anfrage nur validiert, die gespeicherte Abfrage wird nicht geändert.

Konfiguration

Optionen

NameDefaultBeschreibungTypSeit
buildingBlock
Immer SEARCH.
string
v3.1
enabled
false
Soll der Baustein aktiviert werden?
boolean
v3.1
caching
{}
Setzt feste Werte für HTTP-Caching-Header für die Ressourcen.
object
v3.1
managerEnabled
false
Steuert, ob Stored Queries über PUT und DELETE verwaltet werden können.
boolean
v3.4
optimisticLockingLastModified
false
Option zur Aktivierung der Unterstützung für die bedingte Verarbeitung von PUT- und DELETE-Anfragen, basierend auf der Zeit, zu der die Stored Query zuletzt aktualisiert wurde. Solche Anfragen müssen bei einer bestehenden Stored Query einen If-Unmodified-Since-Header enthalten, andernfalls werden sie zurückgewiesen. Eine Stored Query wird nur dann geändert, wenn die Stored Query seit dem Zeitstempel im Header nicht geändert wurde (oder wenn kein letzter Änderungszeitpunkt für die Stored Query bekannt ist). Die Option wird ignoriert, wenn optimisticLockingETag aktiviert ist.
boolean
v3.5
optimisticLockingETag
false
Option zur Aktivierung der Unterstützung für die bedingte Verarbeitung von PUT- und DELETE-Anfragen, basierend auf einem starken Entity Tag (ETag) der Stored Query. Solche Anfragen müssen bei einer bestehenden Stored Query einen If-Match-Header enthalten, andernfalls werden sie zurückgewiesen. Eine Stored Query wird nur dann geändert, wenn der aktuelle ETag der Stored Query zu den ETag(s) im Header passt.
boolean
v3.5
validationEnabled
false
Steuert, ob bei PUT von Stored Queries die Validierung über den Header Prefer (Wert handling=strict) unterstützt werden soll.
boolean
v3.4
allLinksAreLocal
false
Signalisiert Feature-Encodern, ob alle Links auf Objekte im selben Dokuments zeigen.
boolean
v3.4

Speicherung

Stored-Queries müssen im Value-Store unter dem relativen Pfad queries/{apiId}/{queryId}.json abgelegt werden.

Beispiele


- buildingBlock: SEARCH
 enabled: true
 managerEnabled: true
 validationEnabled: false
 allLinksAreLocal: true
ImpressumDatenschutzerklärung