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.

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.

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

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

Limitierungen

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

  • Parameter können nur in Filterausdrücken vorkommen.
  • 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.
  • 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).

Ad-hoc-Queries haben die folgenden Beschränkungen:

  • Paging wird für Ad-Hoc-Queries nicht unterstützt. Bis zur Klärung sollten ausreichend große Werte für limit verwendet werden. Siehe Issue 906open in new window.

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

Beispiele


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