Index-Befehl

Der index Befehl ermöglicht die Verwaltung von Indizes in der VCDB v5. Er stellt Unterbefehle zur Verfügung, um den Status von Indizes zu prüfen sowie sie zu erstellen oder zu entfernen.

Indizes verbessern die Abfragegeschwindigkeit und ermöglichen einen schnelleren Datenzugriff, was insbesonders für große Datenbanken ein entscheidender Vorteil ist. Die Pflege von Indizes ist jedoch mit Aufwand verbunden, da sie in Echtzeit aktualisiert werden und somit Prozesse wie Importe oder Löschvorgänge verlangsamen können. Mit dem index Befehl können Indizes direkt kontrolliert und verwaltet werden.

Syntax

vcdb index [OPTIONEN] BEFEHL

Optionen

Der index Befehl erbt globale Optionen vom Hauptbefehl vcdb. Die Unterbefehle index status und index create stellen zusätzliche Optionen für ihre jeweiligen Operationen zur Verfügung.

Globale Optionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`[@<filename>…]`	Eine oder mehrere Argumentdateien mit Optionen.
`-h`, `--help`	Hilfenachricht anzeigen und beenden.
`-V`, `--version`	Versionsinformationen ausgeben und beenden.
`--config-file=<file>`	Konfiguration aus dieser Datei laden.
`-L`, `--log-level=<level>`	Log-Level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.	`info`
`--log-file=<file>`	Log-Nachrichten in diese Datei schreiben.
`--quiet`	Deaktiviert Log-Nachrichten auf der Konsole.
`--pid-file=<file>`	Datei mit der Prozess-ID erstellen.
`--plugins=<dir>`	Plugins aus diesem Verzeichnis laden.
`--use-plugin=<plugin[=true\|false]> [,<plugin[=true\|false]>…]`	Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.	`true`

[@<filename>…]

Eine oder mehrere Argumentdateien mit Optionen.

-h, --help

Hilfenachricht anzeigen und beenden.

-V, --version

Versionsinformationen ausgeben und beenden.

--config-file=<file>

Konfiguration aus dieser Datei laden.

-L, --log-level=<level>

Log-Level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Log-Nachrichten in diese Datei schreiben.

--quiet

Deaktiviert Log-Nachrichten auf der Konsole.

--pid-file=<file>

Datei mit der Prozess-ID erstellen.

--plugins=<dir>

Plugins aus diesem Verzeichnis laden.

--use-plugin=<plugin[=true|false]> [,<plugin[=true|false]>…]

Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.

true

Weitere Informationen zu den globalen Optionen und Nutzungshinweise siehe hier.

Optionen für den Indexstatus

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-o`, `--output=<file\|->`	Ausgabe in eine JSON-Datei schreiben. Mit `-` wird nach `stdout` ausgegeben.

-o, --output=<file|->

Ausgabe in eine JSON-Datei schreiben. Mit - wird nach stdout ausgegeben.

Die oben genannte Option steht nur für den Befehl index status zur Verfügung.

Optionen für das Erstellen von Indizes

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-m`, `--index-mode=<mode>`	Indexmodus für Spalten mit Propertry-Werten: `partial`, `full`. Im `partial` Modues werden Null-Werte nicht indiziert.	`partial`

-m, --index-mode=<mode>

Indexmodus für Spalten mit Propertry-Werten: partial, full. Im partial Modues werden Null-Werte nicht indiziert.

partial

Die oben genannte Option steht nur für den Befehl index create zur Verfügung.

Datenbank-Verbindungsoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-H`, `--db-host=<host>`	Hostname des VCDB Datenbankservers.
`-P`, `--db-port=<port>`	Port des VCDB Datenbankservers.	5432
`-d`, `--db-name=<database>`	Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.
`-S`, `--db-schema=<schema>`	Schema, das beim Verbinden zur VCDB verwendet werden soll.	`citydb` oder Benutzername
`-u`, `--db-username=<user>`	Benutzername für die Verbidung zur VCDB.
`-p`, `--db-password [=<password>]`	Passwort für die Verbidung zur VCDB. Leer lassen, um zur Eingabe aufgefordert zu werden.
`--db-property=<property=value> [,<proeprty=value>…]`	Datenbankspezifische Verbindungsparameter.

-H, --db-host=<host>

Hostname des VCDB Datenbankservers.

-P, --db-port=<port>

Port des VCDB Datenbankservers.

5432

-d, --db-name=<database>

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

-S, --db-schema=<schema>

Schema, das beim Verbinden zur VCDB verwendet werden soll.

citydb oder Benutzername

-u, --db-username=<user>

Benutzername für die Verbidung zur VCDB.

-p, --db-password [=<password>]

Passwort für die Verbidung zur VCDB. Leer lassen, um zur Eingabe aufgefordert zu werden.

--db-property=<property=value> [,<proeprty=value>…]

Datenbankspezifische Verbindungsparameter.

Weitere Informationen zu den Datenbank-Verbindungsoptionen und Nutzungshinweise sind hier zu finden.

Befehle

Befehl Beschreibung

Befehl	Beschreibung
`help`	Hilfe zum angegebenen Befehl anzeigen.
`status`	Indizes mit ihrem Status in der Datenbank anzeigen.
`create`	Indizes auf den Datenbanktabellen erstellen.
`drop`	Indizes auf den Datenbanktabellen entfernen.

help

Hilfe zum angegebenen Befehl anzeigen.

status

Indizes mit ihrem Status in der Datenbank anzeigen.

create

Indizes auf den Datenbanktabellen erstellen.

drop

Indizes auf den Datenbanktabellen entfernen.

Verwendung

Unterstützte Indizes

Der index Befehl arbeitet auf einer Teilmenge aller in der VCDB v5 definierten Indizes. Diese Teilmenge umfasst die zeitintensivsten räumlichen Indizes sowie reguläre Indizes auf Spalten, die für das Abfragen und Filtern von Features entscheidend sind.

Die folgenden Indizes werden von vcdb-tool unterstützt:

Tabelle Spalte(n) Index-Typ

Tabelle	Spalte(n)	Index-Typ
`APPEARANCE`	`theme`	Regulär
`FEATURE`	`identifier`, `identifier_codespace`	Regulär
`FEATURE`	`envelope`	Räumlich
`FEATURE`	`creation_date`	Regulär
`FEATURE`	`valid_from`	Regulär
`FEATURE`	`valid_to`	Regulär
`GEOMETRY_DATA`	`geometry`	Räumlich
`PROPERTY`	`name`	Regulär
`PROPERTY`	`namespace_id`	Regulär
`PROPERTY`	`val_timestamp`	Regulär
`PROPERTY`	`val_double`	Regulär
`PROPERTY`	`val_int`	Regulär
`PROPERTY`	`val_lod`	Regulär
`PROPERTY`	`val_string`	Regulär
`PROPERTY`	`val_uom`	Regulär
`PROPERTY`	`val_uri`	Regulär

APPEARANCE

theme

Regulär

FEATURE

identifier, identifier_codespace

Regulär

FEATURE

envelope

Räumlich

FEATURE

creation_date

Regulär

FEATURE

valid_from

Regulär

FEATURE

valid_to

Regulär

GEOMETRY_DATA

geometry

Räumlich

PROPERTY

name

Regulär

PROPERTY

namespace_id

Regulär

PROPERTY

val_timestamp

Regulär

PROPERTY

val_double

Regulär

PROPERTY

val_int

Regulär

PROPERTY

val_lod

Regulär

PROPERTY

val_string

Regulär

PROPERTY

val_uom

Regulär

PROPERTY

val_uri

Regulär

Indexstatus prüfen

Der Befehl index status listet alle unterstützten Indizes in der VCDB v5 mit ihrem aktuellen Status auf und zeigt an, ob sie aktiviert (on) oder gelöscht (off) sind. Jeder Index wird zusammen mit dem Namen der Tabelle und der Spalte(n) angezeigt, für die er definiert ist. Dieser Befehl hilft dabei, den aktuellen Zustand der Indizes nachzuvollziehen und zu entscheiden, ob Maßnahmen zur Indexverwaltung erforderlich sind, um nachfolgende Datenbankoperationen zu optimieren.

Beim Aufsetzen einer neuen VCDB v5 Instanz werden alle Indizes standardmäßig aktiviert.

Das folgende Beispiel zeigt, wie der Befehl index status verwendet wird, um den Status aller Indizes auf der Konsole auszugeben.

Linux
Windows CMD

./vcdb index status \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret

vcdb index status ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret

Die Liste der Index-Statuswerte kann über die Option --output optional auch im JSON-Format ausgegeben werden. Wird ein Dateipfad angegeben, dann wird die JSON-Ausgabe in diese Datei geschrieben. Wird anstelle eines Dateipfads - verwendet, dann erfolgt die JSON-Ausgabe auf stdout. Auf diese Weise lässt sich die JSON-Ausgabe einfach umleiten und mit externen Werkzeugen weiterverarbeiten.

Die folgenden Beispiele zeigen die Verwendung der Option --output.

Linux
Windows CMD

./vcdb index status [...] -o status.json      # JSON in Datei schreiben
./vcdb index status [...] -o -                # JSON auf stdout ausgeben
./vcdb index status [...] -o - > status.json  # stdout in Datei umleiten

vcdb index status [...] -o status.json      # JSON in Datei schreiben
vcdb index status [...] -o -                # JSON auf stdout ausgeben
vcdb index status [...] -o - > status.json  # stdout in Datei umleiten

Ein Auszug der erzeugten JSON-Ausgabe ist nachfolgend dargestellt.

{
  "indexes":[
    {
      "table":"appearance",
      "columns":[
        "theme"
      ],
      "type":"normal",
      "name":"appearance_theme_inx",
      "status":"on"
    },
    ...
}

Jeder Eintrag im "indexes" Array enthält die folgende Informationen:

"table": Der Name der Tabelle, für die der Index definiert ist.
"columns": Die Spalte(n), die vom Index abgedeckt werden.
"type": Entweder normal (ein Standardindex) oder spatial (ein Index auf Geometriespalten).
"name": Der Datenbankname des Index.
"status": Gibt an, ob der Index derzeit aktiviert (on) oder gelöscht (off) ist.

Die Struktur der JSON-Ausgabe wird durch die JSON Schema-Datei index-status.json.schema definiert, die sich im Ordner json-schema des vcdb-tool Installationsverzeichnisses befindet.

Indizes erstellen

Der Befehl index create ermöglicht das Erstellen der unterstützten Indizes. Diese Indizes sind entscheidend für die Optimierung von Abfragen und Filtern, und ermöglichen einen schnellen Datenzugriff, insbesondere bei großen Datenbanken. Es wird empfohlen, die Indizes spätestens vor einem Export von Daten zu erstellen, nicht zuletzt wenn der Export eine Filterung von Features umfasst.

Da die val_* Spalten der PROPERTY Tabelle häufig spärlich befüllt sind und viele NULL Werte enthalten, bietet die Option --index-mode die folgenden Modi für die Erstellung von Indizes auf diesen Spalten:

partial: Schließt die Indizierung von NULL Werten aus, was zu kleineren Indexgrößen, schnellerer Erstellung und Aktualisierung sowie verbesserter Query-Performance führt. Alledings können partielle Indizes nicht für Abfragen nach NULL Werten genutzt werden. Dies ist der Standardmodus.
full: Indiziert alle Werte und gewährleistet somit eine vollständige Abdeckung durch den Index, was jedoch auch zu einem höheren Speicherbedarf sowie höherem Zeitaufwand für die Erstellung und Aktualisierung führen kann.

Das folgende Beispiel erstellt Indizes auf einer VCDB v5 Instanz unter Verwendung des full Modus für die val_* Spalten der PROPERTY Tabelle.

Linux
Windows CMD

./vcdb index create \
    --index-mode=full
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret

vcdb index create ^
    --index-mode=full
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret

Je nach Größe der Datenbank kann der Indizierungsvorgang erheblich viel Zeit in Anspruch nehmen, da dabei große Datenmengen verarbeitet werden müssen.

Indizes löschen

Der Befehl index drop entfernt die unterstützten Indizes. Das temporäre Deaktivieren von Indizes kann Massenoperationen wie umfangreiche Datenimporte oder Löschvorgänge erheblich beschleunigen, der der Aufwand für die on-the-fly Aktualisierung der Indizies entfällt. Auch für Wartungsarbeiten an der Datenbank, wie beispielsweise das Freigeben von Speicherplatz, kann das Entfernen von Indizes sinnvoll sein.

Das folgende Beispiel zeigt, wie einfach Indizies gelöscht werden können.

Linux
Windows CMD

./vcdb index drop \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret

vcdb index drop ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret

Während das Löschen von Indizes sehr schnell geht, kann deren Wiederherstellung, insbesondere bei großen Datenbanken, sehr zeitaufwending sein. Mit zunehmender Datenbankgröße kann somit der Aufwand für das Entfernen und erneute Erstellen der Indizes die Vorteile zunichte machen, die man durch das Löschen der Indizies bei bestimmten Datenoperationen erhält – insbesondere wenn diese Operationen nur kleinere Datenmengen und nicht Massendaten betreffen.

Auch nach dem Löschen von Indizes mit dem Befehl index drop bleibt ein minimaler Satz von Indizes in der Datenbank aktiviert, um sicherzustellen, dass grundlegende Abfragen – wie das Filtern von Objekten nach ihrer objectid oder termination_date – weiterhin effizient ausgeführt werden können.