SQL

implmaturemainfull

Die Features sind in einer SQL-Datenbank gespeichert (PostgreSQL/PostGIS, GeoPackage, SQLite/SpatiaLite).

Limitierungen

Alle Bezeichner müssen nicht in Anführungszeichen gesetzt werden, d.h. die Bezeichner werden klein geschrieben.

Für PGIS gibt es die folgenden bekannten Einschränkungen:

• Nicht alle CQL2-Ausdrücke werden in JSON-Spalten unterstützt.

Für GPKG gibt es die folgenden bekannten Einschränkungen:

• Die Option linearizeCurves wird nicht unterstützt. Alle Geometrien müssen Geometrien gemäß
  dem Standard OGC Simple Feature Access sein.
• Die CQL2-Funktionen DIAMETER2D() und DIAMETER3D() werden nicht unterstützt.
• Arrays als Queryables werden für GeoPackage Feature Provider nicht unterstützt.
• Queryables, die Werte in einem Array sind, werden für GeoPackage Feature-Anbieter nicht
  unterstützt.

Konfiguration

Optionen

Name	Default	Beschreibung	Typ	Seit
connectionInfo		Siehe Connection-Info.	object	v2.0
datasetChanges		Behandlung von Datensatzänderungen, für Details siehe Datensatzänderungen.	object	v4.3
sourcePathDefaults		Defaults für die Pfad-Ausdrücke in sourcePath, für Details siehe SQL-Pfad-Defaults.	object	v2.0
queryGeneration		Einstellungen für die Query-Generierung, für Details siehe Query-Generierung.	object	v2.0

Connection Info

Das Connection-Info-Objekt für SQL-Datenbanken wird wie folgt beschrieben:

Name	Default	Beschreibung	Typ	Seit
dialect	PGIS	PGIS für PostgreSQL/PostGIS, GPKG für GeoPackage oder SQLite/SpatiaLite.	string	v2.0
database		Der Name der Datenbank. Für GPKG ein relativer Pfad zu einer Ressource mit Typ features im Store.	string	v2.0
host		Der Datenbankhost. Wird ein anderer Port als der Standardport verwendet, ist dieser durch einen Doppelpunkt getrennt anzugeben, z.B. db:30305. Nicht relevant für GPKG.	string	v2.0
user		Der Benutzername. Nicht relevant für GPKG.	string	v2.0
password		Das mit base64 kodierte Passwort des Benutzers. Nicht relevant für GPKG.	string	v2.0
schemas	[]	Die Namen der Schemas in der Datenbank, auf die zugegriffen werden soll. Nicht relevant für GPKG.	array	v2.0
pool	see below	Einstellungen für den Connection-Pool, für Details siehe Pool.	object	v2.0
defaultCollation	en-US	Die Standard Collation Locale, die von der Datenbank für Stringvergleiche verwendet wird, z.B. de oder de-DE für Deutsch. Der spezielle Wert C ist für die C- oder POSIX-Collation erlaubt. Dies ändert nicht die Datenbankeinstellungen oder die Queries, sondern wird nur für Stringvergleiche in der Anwendung benötigt.	string	v2.0
driverOptions	{}	Einstellungen für den JDBC-Treiber. Für PGIS werden gssEncMode, ssl, sslmode, sslcert, sslkey, sslrootcert und sslpassword durchgereicht. Für Details siehe die Dokumentation des Treibers.	object	v2.0
assumeExternalChanges	false	Deprecated (ersetzt durch datasetChanges.mode). Annehmen, dass der verbundene Datensatz durch externe Applikationen geändert werden kann. Wenn diese Option auf true gesetzt wrid, werden z.B. Extents und Counts bei jedem Start oder Reload des Providers neu berechnet.	boolean	v4.0

Pool

Einstellungen für den Connection-Pool.

Name	Default	Beschreibung	Typ	Seit
maxConnections	dynamic	Steuert die maximale Anzahl von Verbindungen zur Datenbank. Der Default-Wert ist abhängig von der Anzahl der Prozessorkerne und der Anzahl der Joins in der Types-Konfiguration. Der Default-Wert wird für optimale Performanz unter Last empfohlen. Der kleinstmögliche Wert ist ebenfalls von der Anzahl der Joins abhängig, kleinere Werte werden zurückgewiesen.	number	v2.0
minConnections	maxConnections	Steuert die minimale Anzahl von Verbindungen zur Datenbank, die jederzeit offen gehalten werden.	number	v2.0
idleTimeout	10m	Die maximale Zeit die eine Connection unbeschäftigt im Pool verbleibt. Bezieht sich nur auf Connections über der minConnections Grenze. Ein Wert von 0 bedeutet, dass unbeschäftigte Connections niemals aus dem Pool entfernt werden.	string	v2.0
shared	false	Wenn shared für mehrere Provider mit übereinstimmenden host, database und user aktiviert ist, teilen sich diese Provider einen Connection-Pool. Wenn eine der anderen Optionen in connectionInfo nicht übereinstimmt, schlägt der Start des Providers fehl.	boolean	v2.0

Datensatzänderungen

Definiert wie Änderungen am Datensatz erkannt werden sollen. Es gibt die folgenden Modi:

• OFF: Der Datensatz wird als statisch betrachtet und es wird keine Änderungserkennung durchgeführt.
  Wenn es eine neue Datensatzversion gibt, sollte diese zu Änderungen an connectionInfo führen. (Dies
  wird in v5.x der Standard sein)
• CRUD: Änderungen am Datensatz werden ausschließlich von der Anwendung selbst über die CRUD-
  Schnittstelle vorgenommen. (Dies ist in v4.x der Standard)
• TRIGGER: Es sind Trigger für den Datensatz eingerichtet, die die Anwendung über Änderungen
  informieren (siehe z.B. Change Listener). Zusätzlich kann eine
  periodische Synchronisation mit syncPeriodic für den Fall von verpassten Benachrichtigungen
  konfiguriert werden.
• EXTERNAL: Annehmen, dass der Datensatz von externen Anwendungen geändert werden kann.
  In diesem Modus erfolgt eine Synchronisation bei jedem Start oder Reload des Providers.
  Zusätzlich kann eine periodische Synchronisation mit syncPeriodic konfiguriert werden.

Name	Default	Beschreibung	Typ	Seit
mode	CRUD v4 | OFF v5	Der Modus für die Erkennung von Datensatzänderungen, siehe oben.	string	v4.3
syncPeriodic	null	Ein Crontab-Pattern zum regelmäßigen Aktualisieren aller gecachten Daten, die sich aus dem Datensatz ableiten. Nur verfügbar für die Modi EXTERNAL und TRIGGER.	string	v4.3

Query-Generierung

Optionen für die Query-Generierung in queryGeneration.

Name	Default	Beschreibung	Typ	Seit
computeNumberMatched	true	Steuert, ob bei Abfragen die Anzahl der selektierten Features berechnet und in numberMatched zurückgegeben werden soll oder ob dies aus Performancegründen unterbleiben soll. Bei großen Datensätzen empfiehlt es sich in der Regel, die Option zu deaktivieren.	boolean	v2.0
nullOrder	-	Ohne Angabe wird die Sortierreihenfolge der Datenbank verwendet (normalerweise last für aufsteigend und first für absteigend). last oder first kann verwendet werden, um eine bestimmte Sortierreihenfolge für Spalten mit Nullwerten zu erzwingen.	string	v4.3
geometryEncoding	WKB	Kodierung der zurückgegebenen Geometrien, entweder Well-Known Text (WKT) oder Well-Known Binary (WKB). WKB ist die Standardkodierung seit v4.5.	string	v4.4

SQL-Pfad-Defaults

Defaults für die Pfad-Ausdrücke in sourcePath, siehe auch SQL-Pfad-Syntax.

Name	Default	Beschreibung	Typ	Seit
primaryKey	id	Die Standard-Spalte die zur Analyse von Joins verwendet wird, wenn keine abweichende Spalte in sourcePath gesetzt wird. Nur relevant für CRUD.	string	v2.0
sortKey	id	Die Standard-Spalte die zur Sortierung von Rows verwendet wird, wenn keine abweichende Spalte in sourcePath gesetzt wird. Es wird empfohlen, dass als Datentyp eine Ganzzahl verwendet wird.	string	v2.0
schema	null	Das Standard-Schema das Tabellen ohne Präfix in sourcePaths vorangestellt wird.	string	v3.3

SQL-Pfad-Syntax

In dem Beispiel oben sind die wesentlichen Elemente der Pfadsyntax in der Datenbank bereits erkennbar. Der Pfad zu einer Eigenschaft ergibt sich immer als Konkatenation der relativen Pfadangaben (sourcePath), jeweils ergänzt um ein "/". Die Eigenschaft sourcePath ist beim ersten Objekt, das die Objektart repräsentiert, angegeben und bei allen untergeordneten Schemaobjekten, außer es handelt sich um einen festen Wert.

Auf der obersten Ebene entspricht der Pfad einem "/" gefolgt vom Namen der Tabelle zur Objektart. Jede Zeile in der Tabelle entsprich einem Feature. Beispiel: /kita.

Bei nachgeordneten relativen Pfadangaben zu einem Feld in derselben Tabelle wird einfach der Spaltenname angeben, z.B. name. Daraus ergibt sich der Gesamtpfad /kita/name.

Ein Join wird nach dem Muster [id=fk]tab angegeben, wobei id der Primärschlüssel der Tabelle aus dem übergeordneten Schemaobjekt ist, fk der Fremdschlüssel aus der über den Join angebundenen Tabelle und tab der Tabellenname. Siehe [oid=kita_fk]plaetze in dem Beispiel oben. Bei der Verwendung einer Zwischentabelle werden zwei dieser Joins aneinandergehängt, z.B. [id=fka]a_2_b/[fkb=id]tab_b.

Auf einer Tabelle (der Haupttabelle eines Features oder einer über Join-angebundenen Tabelle) kann zusätzlich ein einschränkender Filter durch den Zusatz {filter=ausdruck} angegeben werden, wobei ausdruck das Selektionskriertium in CQL2 Text spezifiziert. Für Details siehe den Baustein Filter / CQL, welches die Implementierung bereitstellt, aber nicht aktiviert sein muss.

Wenn z.B. in dem Beispiel oben nur Angaben zur Belegungskapazität selektiert werden sollen, deren Wert nicht NULL und gleichzeitig größer als Null ist, dann könnte man schreiben: [oid=kita_fk]plaetze{filter=anzahl IS NOT NULL AND anzahl>0}.

Ein vom Standard abweichender sortKey kann durch den Zusatz von {sortKey=Spaltenname} nach dem Tabellennamen angegeben werden. Wenn dieser nicht eindeutig ist, kann {sortKeyUnique=false} hinzugefügt werden.

Ein vom Standard abweichender primaryKey kann durch den Zusatz von {primaryKey=Spaltenname} nach dem Tabellennamen angegeben werden.

Zusätzliche Spalten für CRUD Inserts können durch den Zusatz {inserts=Spaltenname=Wert} nach dem Tabellennamen angegeben werden. Der Wert kann eine Konstante oder eine Funktion sein, z.B. {inserts=id=gen_random_uuid()&featuretype='type1'}.

Auch im Hinblick auf CRUD: wenn eine Eigenschaft mit role: ID dem Primärschlüssel der Haupttabelle entspricht, aber der Wert beim Einfügen nicht automatisch generiert werden soll, dann ist für diese Eigenschaft in sourcePath das Flag {generated=false} anzugeben.

Alle Tabellen- und Spaltennamen müssen "unquoted Identifier" sein.

Beliebige SQL-Ausdrücke für Werte sind möglich, z.B. um Funktionsaufrufe anzuwenden. So würde z.B. dieser Ausdruck [EXPRESSION]{sql=$T$.length+55.5} (anstatt nur length) einen fixen Wert zur Längen-Spalte addieren. Der Präfix $T$ wird durch den Tabellen-Alias ersetzt.

CRUD

Wenn die Features dieses Providers über die API verändert werden sollen, muss datasetChanges.mode auf CRUD gesetzt werden. Außerdem sind die folgenden Absätze zu beachten, um zu verstehen, welche Anpassungen am Mapping für den eigenen Anwendungsfall notwendig sind.

Tabellentypen

• main Haupttabellen repräsentieren die Instanzen einer Objektart. Sie sind im
  obersten sourcePath einer Objektart definiert.
• secondary Sekundärtabellen sind über Joins mit Haupttabellen verbunden, entweder direkt
  oder über eine Kette von Sekundär- und/oder Junction-Tabellen.
• junction Junction-Tabellen repräsentieren in der Regel m:n-Beziehungen. Sie enthalten
  hauptsächlich zwei Fremdschlüssel von Haupt- und/oder Sekundärtabellen.

Primärschlüssel

Es wird erwartet, dass jede Haupt- und Sekundärtabelle einen Primärschlüssel hat und dass der Wert für den Primärschlüssel beim Einfügen automatisch generiert wird. In der Regel sollte sourcePathDefaults.primaryKey dem Primärschlüssel aus der Datenbank entsprechen. Wenn nicht jede Tabelle denselben Primärschlüssel hat, kann dieser überschrieben werden, siehe SQL-Pfad-Syntax.

In seltenen Fällen, wenn in Join-Bedingungen eine andere Spalte als der Primärschlüssel verwendet wird, muss der primaryKey im Mapping dieser Spalte entsprechen und sich vom tatsächlichen Primärschlüssel unterscheiden. Ein Beispiel wäre eine Junction-Tabelle, die Feature-Instanzen über deren Ids verbindet.

Feature-Ids

Es gibt vier Varianten, um bei Inserts neue Feature-Ids zu erzeugen:

• Primärschlüssel, automatisch generiert Der sourcePath der Eigenschaft mit role: ID
  entspricht dem primaryKey und neue Werte werden beim Einfügen automatisch von der
  Datenbank generiert.
• Primärschlüssel, benutzerdefiniert Der sourcePath der Eigenschaft mit role: ID
  entspricht dem primaryKey und hat das Flag {generated=false}, der Wert aus dem
  Payload wird eingefügt.
• Andere Spalte, automatisch generiert Der sourcePath der Eigenschaft mit role: ID
  entspricht nicht dem primaryKey, und der sourcePath der Haupttabelle hat ein
  entsprechendes inserts-Flag mit einer Generierungsfunktion, z.B.
  {inserts=id=gen_random_uuid()'} (siehe SQL-Pfad-Syntax).
• Andere Spalte, benutzerdefiniert Der sourcePath der Eigenschaft mit role: ID
  entspricht nicht dem primaryKey, und der sourcePath der Haupttabelle hat kein
  entsprechendes inserts-Flag, der Wert aus der Nutzlast wird eingefügt.

Zusätzliche Spalten

Wenn bei einem Insert oder Update zusätzliche Spalten gesetzt werden sollen, die nicht auf eine Eigenschaft abgebildet sind, kann das inserts-Flag in sourcePath verwendet werden (siehe SQL-Pfad-Syntax), z.B. {inserts=id=gen_random_uuid()&featuretype='Strasse'}.