Azure Cosmos DB for Gremlin-Diagramme: Unterstützung und Kompatibilität mit TinkerPop-Features

GILT FÜR: Gremlin

Azure Cosmos DB unterstützt die Apache Tinkerpop-Graphdurchlauf-Sprache, auch als Gremlin bezeichnet. Mithilfe der Gremlin-Sprache können Sie Diagrammentitäten (Vertices und Edges) erstellen, Eigenschaften innerhalb dieser Entitäten ändern, Abfragen und Traversierungen ausführen und Entitäten löschen.

Die Azure Cosmos DB Graph-Engine hält sich eng an die Apache TinkerPop-Spezifikation für die Durchlaufschritte, es gibt jedoch Azure Cosmos DB-spezifische Unterschiede bei der Implementierung. Dieser Artikel enthält eine kurze exemplarische Vorgehensweise zu Gremlin und listet die Funktionen von Gremlin auf, die von der API für Gremlin unterstützt werden.

Kompatible Clientbibliotheken

In der folgenden Tabelle werden gängige Gremlin-Treiber aufgeführt, die Sie für Azure Cosmos DB verwenden können:

Download	`Source`	Erste Schritte	Unterstützte/empfohlene Connectorversion
.NET	Gremlin.NET auf GitHub	Erstellen von Graph mithilfe von .NET	3.4.13
Java	Gremlin JavaDoc	Erstellen von Graph mithilfe von Java	3.4.13
Python	Gremlin-Python auf GitHub	Erstellen von Graph mithilfe von Python	3.4.13
Gremlin-Konsole	TinkerPop-Dokumente	Erstellen von Graph mithilfe der Gremlin-Konsole	3.4.13
Node.js	Gremlin-JavaScript auf GitHub	Erstellen von Graph mithilfe von Node.js	3.4.13
PHP	Gremlin-PHP auf GitHub	Erstellen von Graph mithilfe von PHP	3.1.0
Go Lang	Go Lang		Diese Bibliothek wird von externen Mitwirkenden erstellt. Das Azure Cosmos DB-Team bietet keine Unterstützung für die Bibliothek, und die Bibliothek wird nicht vom Azure Cosmos DB-Team gewartet.

Hinweis

Gremlin-Clienttreiberversionen für 3.5.*, 3.6.* weisen bekannte Kompatibilitätsprobleme auf, sodass wir die Verwendung der neuesten, oben aufgeführten unterstützten 3.4.*-Treiberversionen empfehlen. Diese Tabelle wird aktualisiert, wenn die Kompatibilitätsprobleme für diese neueren Treiberversionen behoben wurden.

Unterstützte Graph-Objekte

TinkerPop ist ein Standard, der eine große Bandbreite an Diagrammtechnologien abdeckt. Daher weist diese Standardterminologie auf, die beschreiben, welche Funktionen von einem Diagrammanbieter bereitgestellt werden. Azure Cosmos DB stellt eine beständige und beschreibbare Diagrammdatenbank mit hoher Parallelität dar, die über mehrere Server oder Cluster hinweg partitioniert werden kann.

Die folgende Tabelle enthält die TinkerPop-Funktionen, die von Azure Cosmos DB implementiert werden:

Category	Implementierung von Azure Cosmos DB	Notizen
Diagrammfunktionen	Stellen Persistenz und ConcurrentAccess bereit. Sind zur Unterstützung für Transaktionen ausgelegt.	Computermethoden können über den Spark-Connector implementiert werden.
Variablenfunktionen	Unterstützen Boolean-, Integer-, Byte-, Double-, Float-, Long- und String-Datentypen	Unterstützen primitive Typen; ist mit komplexen Typen über Datenmodelle kompatibel
Vertex-Funktionen	Unterstützen RemoveVertices MetaProperties, AddVertices MultiProperties, StringIds UserSuppliedIds, AddProperty, RemoveProperty	Unterstützen die Erstellung, Änderung und Löschung von Vertices
Vertex-Eigenschafts-Funktionen	StringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues	Unterstützen die Erstellung, Änderung und Löschung von Vertex-Eigenschaften
Edgefunktionen	AddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemoveProperty	Unterstützen die Erstellung, Änderung und Löschung von Edges
Edge-Eigenschafts-Funktionen	Properties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues	Unterstützen die Erstellung, Änderung und Löschung von Edge-Eigenschaften

Gremlin-Sendeformat

Azure Cosmos DB verwendet bei der Rückgabe von Ergebnissen aus Gremlin-Vorgängen das JSON-Format. Von Azure Cosmos DB wird aktuell das JSON-Format unterstützt. Der folgende Ausschnitt zeigt beispielsweise eine JSON-Darstellung eines Vertex, der von Azure Cosmos DB an den Client zurückgegeben wurde:

  {
    "id": "a7111ba7-0ea1-43c9-b6b2-efc5e3aea4c0",
    "label": "person",
    "type": "vertex",
    "outE": {
      "knows": [
        {
          "id": "3ee53a60-c561-4c5e-9a9f-9c7924bc9aef",
          "inV": "04779300-1c8e-489d-9493-50fd1325a658"
        },
        {
          "id": "21984248-ee9e-43a8-a7f6-30642bc14609",
          "inV": "a8e3e741-2ef7-4c01-b7c8-199f8e43e3bc"
        }
      ]
    },
    "properties": {
      "firstName": [
        {
          "value": "Thomas"
        }
      ],
      "lastName": [
        {
          "value": "Andersen"
        }
      ],
      "age": [
        {
          "value": 45
        }
      ]
    }
  }

Im Anschluss werden die Eigenschaften beschrieben, die im JSON-Format für Vertices verwendet werden:

Eigenschaft	Beschreibung
id	Die ID für den Vertex. Muss eindeutig sein (in Kombination mit dem Wert von _partition, falls zutreffend). Wird kein Wert angegeben, wird automatisch eine GUID bereitgestellt.
label	Die Bezeichnung des Vertex. Diese Eigenschaft dient zur Beschreibung des Entitätstyps.
type	Dient zur Unterscheidung von Vertices von anderen Dokumenten, die keine Diagramme sind.
properties	Sammlung von benutzerdefinierten Eigenschaften in Verbindung mit dem Vertex. Jede Eigenschaft kann mehrere Werte enthalten.
_partition	Der Partitionsschlüssel des Vertex. Wird für Graphpartitionierung verwendet.
outE	Diese Eigenschaft enthält eine Liste von externen Edges aus einem Vertex. Die Speicherung von Informationen zur Nähe zum Vertex ermöglicht die schnelle Ausführung von Traversierungen. Edges werden basierend auf deren Bezeichnungen gruppiert.

Jede Eigenschaft kann mehrere Werte in einem Array speichern.

Eigenschaft	Beschreibung
value	Wert der Eigenschaft

Zudem enthalten Edges folgende Informationen, die die Navigation in anderen Teilen des Diagramms unterstützen können.

Eigenschaft	Beschreibung
id	Die ID für den Edge. Muss eindeutig sein (in Kombination mit dem Wert von _partition, falls zutreffend).
label	Die Bezeichnung des Edge. Diese Eigenschaft ist optional, und dient zur Beschreibung des Beziehungstyps.
inV	Diese Eigenschaft enthält eine Liste von In-Vertices für einen Edge. Die Speicherung von Informationen über die Nähe zum Vertex mit dem Edge ermöglicht die schnelle Ausführung von Traversierungen. Vertices werden basierend auf ihren Bezeichnungen gruppiert.
properties	Sammlung von benutzerdefinierten Eigenschaften in Verbindung mit dem Edge.

Gremlin-Schritte

Sehen wir uns nun die Gremlin-Schritte an, die von Azure Cosmos DB unterstützt werden. Eine vollständige Referenz zu Gremlin finden Sie in der TinkerPop-Referenz.

Schritt	Beschreibung	Dokumentation zu TinkerPop 3.2
addE	Fügt einen Edge zwischen zwei Vertices hinzu	addE-Schritt
addV	Fügt einen Vertex zum Diagramm hinzu	addV-Schritt
and	Stellt sicher, dass alle Traversierungen einen Wert zurückgeben	and-Schritt
as	Ein Schrittmodulator für die Zuweisung einer Variable zur Ausgabe eines Schritts	as-Schritt
by	Ein mit group und order verwendeter Schrittmodulator	by-Schritt
coalesce	Gibt die erste Traversierung, die ein Ergebnis zurückgibt, zurück	coalesce-Schritt
constant	Gibt einen konstanten Wert zurück. Wird mit coalesce verwendet.	constant-Schritt
count	Gibt die Anzahl aus der Traversierung zurück	count-Schritt
dedup	Gibt die Werte mit entfernten Duplikaten zurück	dedup-Schritt
drop	Löscht die Werte (Vertex/Edge)	drop-Schritt
executionProfile	Erstellt eine Beschreibung aller Vorgänge, die im ausgeführten Gremlin-Schritt generiert werden.	executionProfile-Schritt
fold	Fungiert als Grenze, die Ergebnisse berechnet und zusammenfasst	fold-Schritt
group	Gruppiert die Werte basierend auf den angegebenen Bezeichnungen	group-Schritt
has	Wird zum Filtern von Eigenschaften, Vertices und Edges verwendet. Unterstützt die Varianten hasLabel, hasId, hasNot und has.	has-Schritt
inject	Fügt Werte in einen Stream ein	inject-Schritt
is	Dient zur Ausführung eines Filters mithilfe eines booleschen Ausdrucks	is-Schritt
limit	Dient zur Beschränkung der Anzahl der Elemente in der Traversierung	limit-Schritt
local	Umschließt lokal einen Abschnitt einer Traversierung, ähnlich wie bei einer Unterabfrage	local-Schritt
not	Dient zur Negierung eines Filters	not-Schritt
optional	Gibt das Ergebnis der angegebenen Traversierung zurück, wenn diese ein anderes Ergebnis als das vom aufrufenden Element zurückgegebene Ergebnis liefert	optional-Schritt
or	Stellt sicher, dass mindestens einer der Traversierungen einen Wert zurückgibt	or-Schritt
order	Gibt die Ergebnisse in der angegebenen Sortierreihenfolge zurück	order-Schritt
path	Gibt den vollständigen Pfad der Traversierung zurück	path-Schritt
project	Projiziert die Eigenschaften als Karte	project-Schritt
properties	Gibt die Eigenschaften für die angegebenen Bezeichnungen zurück	properties-Schritt
range	Filtert auf den angegebenen Wertebereich	range-Schritt
repeat	Wiederholt den Schritt für die angegebene Anzahl von Versuchen. Wird für die Ausführung als Schleife verwendet.	repeat-Schritt
sample	Wird zum Testen von Ergebnissen aus der Traversierung verwendet	sample-Schritt
select	Wird zum Projizieren von Ergebnissen aus der Traversierung verwendet	select-Schritt
store	Wird für nicht blockierende Aggregate aus der Traversierung verwendet	store-Schritt
TextP.startingWith(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft mit dem Anfang einer bestimmten Zeichenfolge zu finden.	TextP-Prädikate
TextP.endingWith(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft mit dem Ende einer bestimmten Zeichenfolge zu finden.	TextP-Prädikate
TextP.containing(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft mit dem Inhalt einer bestimmten Zeichenfolge zu finden.	TextP-Prädikate
TextP.notStartingWith(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft zu finden, die nicht mit einer bestimmten Zeichenfolge beginnt.	TextP-Prädikate
TextP.notEndingWith(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft zu finden, die nicht auf eine bestimmte Zeichenfolge endet.	TextP-Prädikate
TextP.notContaining(string)	Filterfunktion für Zeichenfolgen. Diese Funktion dient als ein Prädikat für den Schritt has(), um eine Eigenschaft zu finden, die eine bestimmte Zeichenfolge nicht enthält.	TextP-Prädikate
tree	Aggregiert Pfade aus einem Vertex in einer Struktur	tree-Schritt
unfold	Löst einen Iterator als Schritt auf	unfold-Schritt
union	Führt Ergebnisse aus mehreren Traversierungen zusammen	union-Schritt
V	Enthält die erforderlichen Schritte für Traversierungen zwischen Vertices und Edges: V, E, out, in, both, outE, inE, bothE, outV, inV, bothV und otherV für	vertex-Schritte
where	Wird zum Filtern von Ergebnissen aus der Traversierung verwendet. Unterstützt die Operatoren eq, neq, lt, lte, gt, gte und between.	where-Schritt

Die von Azure Cosmos DB bereitgestellte, für Schreibvorgänge optimierte Engine unterstützt standardmäßig die automatische Indizierung aller Eigenschaften in Vertices und Edges. Daher werden Abfragen mit Filtern, Bereichsabfragen, Sortierungen oder Aggregate von Eigenschaften über den Index verarbeitet und effizient übermittelt. Weitere Informationen zur Indizierung in Azure Cosmos DB finden Sie in unserem Dokument unter Schemagnostische Indizierung.

Unterschiede im Verhalten

• Die Azure Cosmos DB Graph-Engine führt einen Durchlauf mit breitenorientiertem Lastenausgleich aus, während TinkerPop Gremlin einen tiefenorientierten Ansatz verfolgt. Dieses Verhalten erzielt eine bessere Leistung in einem horizontal skalierbaren System wie Azure Cosmos DB.

Nicht unterstützte Funktionen

• Gremlin Bytecode ist eine von der Programmiersprache unabhängige Spezifikation für Diagrammdurchläufe. Azure Cosmos DB Graph unterstützt dies noch nicht. Verwenden Sie GremlinClient.SubmitAsync(), und übergeben Sie den Durchlauf als eine Textzeichenfolge.

• property(set, 'xyz', 1): Das Festlegen der Kardinalität wird noch nicht unterstützt. Verwenden Sie stattdessen property(list, 'xyz', 1). Weitere Informationen finden Sie unter Vertex-Eigenschaften mit TinkerPop.

• Der match() Schritt ist derzeit nicht verfügbar. Dieser Schritt bietet deklarative Abfragefunktionen.

• Objekte als Eigenschaften werden für Vertices und Edges nicht unterstützt. Eigenschaften können nur primitive Typen oder Arrays sein.

• Sortieren nach Arrayeigenschaften order().by(<array property>) wird nicht unterstützt. Die Sortierung wird nur von primitiven Typen unterstützt.

• Nicht primitive JSON-Typen werden nicht unterstützt. Verwenden Sie die Typen string, number oder true/false. null-Werte werden nicht unterstützt.

• Das GraphSONv3-Serialisierungsmodul wird derzeit nicht unterstützt. Verwenden Sie das GraphSONv2-Serialisierungsmodul sowie Reader- und Writerklassen in der Verbindungskonfiguration. Das Format der von Azure Cosmos DB for Gremlin zurückgegebenen Ergebnisse ist nicht identisch mit dem GraphSON-Format.

• Lambdaausdrücke und -funktionen werden derzeit nicht unterstützt. Dies umfasst die Funktionen .map{<expression>}, .by{<expression>} und .filter{<expression>}. Weitere Informationen und wie Sie sie mithilfe der Gremlin-Schritte neu schreiben können, finden Sie unter A Note on Lambdas (Hinweis zu Lambdas).

• Transaktionen werden aufgrund der verteilten Natur des Systems nicht unterstützt. Konfigurieren Sie ein geeignetes Konsistenzmodell für das Gremlin-Konto, um „Ihre eigenen Schreibvorgänge zu lesen“, und verwenden Sie optimistische Nebenläufigkeit, um Schreibvorgänge aufzulösen, zu einen Konflikt verursachen.

Bekannte Einschränkungen

• Indexverwendung für Gremlin-Abfragen mit Schritten vom Typ .V() während des Durchlaufs: Aktuell wird nur beim ersten .V()-Aufruf eines Durchlaufs der Index genutzt, um alle angefügten Filter oder Prädikate aufzulösen. Bei späteren Aufrufen wird der Index nicht herangezogen, wodurch sich die Wartezeit und die Kosten der Abfrage erhöhen können.

Bei Verwendung der Standardindizierung werden von einer typischen Gremlin-Leseabfrage, die mit dem Schritt .V() beginnt, Parameter wie .has() oder .where() in den angefügten Filterschritten verwendet, um die Kosten und die Leistung der Abfrage zu optimieren. Beispiel:

g.V().has('category', 'A')

Enthält die Gremlin-Abfrage allerdings mehrere Schritte vom Typ .V(), ist die Auflösung der Daten für die Abfrage möglicherweise nicht optimal. Ein Beispiel hierfür wäre etwa die folgende Abfrage:

g.V().has('category', 'A').as('a').V().has('category', 'B').as('b').select('a', 'b')

Diese Abfrage gibt auf der Grundlage der Eigenschaft category zwei Gruppen von Vertices zurück. In diesem Fall wird nur beim ersten Aufruf (g.V().has('category', 'A')) der Index genutzt, um die Vertices auf der Grundlage der Werte ihrer Eigenschaften aufzulösen.

Zur Umgehung dieses Problems können bei dieser Abfrage untergeordnete Durchlaufschritte wie .map() und union() verwendet werden. Beispiel:

// Query workaround using .map()
g.V().has('category', 'A').as('a').map(__.V().has('category', 'B')).as('b').select('a','b')

// Query workaround using .union()
g.V().has('category', 'A').fold().union(unfold(), __.V().has('category', 'B'))

Die Leistung der Abfragen kann mithilfe des GremlinexecutionProfile()-Schritts überprüft werden.

Nächste Schritte

• Erste Schritte zum Erstellen einer Diagrammanwendung mithilfe unserer SDKs
• Informieren Sie sich ausführlicher über die Diagrammunterstützung in Azure Cosmos DB.