Ondersteuning en compatibiliteit van Azure Cosmos DB voor Gremlin-grafieken met TinkerPop-functies

Artikel
04/06/2023

VAN TOEPASSING OP: Gremlin

Azure Cosmos DB ondersteunt de taal voor grafiekdoorkruising van Apache Tinkerpop, ook wel Gremlin genoemd. U kunt de Gremlin-taal gebruiken om grafiekentiteiten (hoekpunten en randen) te maken, eigenschappen binnen deze entiteiten te wijzigen, query’s en traversals uit te voeren, en entiteiten te verwijderen.

De Azure Cosmos DB Graph-engine volgt de specificatie voor Apache TinkerPop-doorkruisingstappen nauwkeurig, maar er zijn verschillen in de implementatie die specifiek zijn voor Azure Cosmos DB. In dit artikel geven we een beknopt overzicht van Gremlin en inventariseren we de Gremlin-functies die worden ondersteund door de API voor Gremlin.

Compatibele clientbibliotheken

In de volgende tabel ziet u populaire Gremlin-stuurprogramma’s die u kunt gebruiken met Azure Cosmos DB:

Download	Bron	Aan de slag	Ondersteunde/aanbevolen connectorversie
.NET	Gremlin.NET in GitHub	Grafiek maken met behulp van .NET	3.4.13
Java	Gremlin JavaDoc	Grafiek maken met behulp van Java	3.4.13
Python	Gremlin-Python in GitHub	Grafiek maken met behulp van Python	3.4.13
Gremlin-console	TinkerPop-documenten	Grafiek maken met behulp van de Gremlin-console	3.4.13
Node.js	Gremlin-JavaScript in GitHub	Grafiek maken met behulp van Node.js	3.4.13
PHP	Gremlin-PHP in GitHub	Grafiek maken met behulp van PHP	3.1.0
Go Lang	Go Lang		Deze bibliotheek is gebouwd door externe bijdragers. Het Azure Cosmos DB-team biedt geen ondersteuning of onderhoud voor de bibliotheek.

Notitie

Versies van Gremlin-clientstuurprogramma's voor 3.5.*, 3.6.* hebben bekende compatibiliteitsproblemen. Daarom raden we u aan de meest recente ondersteunde stuurprogrammaversies van 3.4.* te gebruiken die hierboven worden vermeld. Deze tabel wordt bijgewerkt wanneer compatibiliteitsproblemen zijn opgelost voor deze nieuwere stuurprogrammaversies.

Ondersteunde grafiekobjecten

TinkerPop is een standaard die een breed bereik aan grafiektechnologieën beslaat. Daarom beschikt TinkerPop over een standaardterminologie om te beschrijven welke functies worden aangeboden door een grafiekprovider. Azure Cosmos DB biedt een permanente, beschrijfbare grafiekdatabase met een hoge gelijktijdigheid, die kan worden gepartitioneerd op meerdere servers of clusters.

In de volgende tabel worden de TinkerPop-functies vermeld die zijn geïmplementeerd met Azure Cosmos DB:

Categorie	Azure Cosmos DB-implementatie	Opmerkingen
Graph-functies	Biedt persistentie en ConcurrentAccess. Ontworpen om transacties te ondersteunen	Computermethoden kunnen worden geïmplementeerd via de Spark-connector.
Variabele functies	Ondersteunt booleaanse waarde, geheel getal, byte, dubbel, float, lang, tekenreeks	Biedt ondersteuning voor primitieve typen, is compatibel met complexe typen via een gegevensmodel
Hoekpuntfuncties	Biedt ondersteuning voor RemoveVertices, MetaProperties, AddVertices, MultiProperties, StringIds, UserSuppliedIds, AddProperty, RemoveProperty	Biedt ondersteuning voor het maken, wijzigen en verwijderen van hoekpunten
Functies voor hoekpunteigenschappen	StringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues	Biedt ondersteuning voor het maken, wijzigen en verwijderen van hoekpunteigenschappen
Randfuncties	AddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemoveProperty	Biedt ondersteuning voor het maken, wijzigen en verwijderen van randen
Functies voor randeigenschappen	Properties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues	Biedt ondersteuning voor het maken, wijzigen en verwijderen van randeigenschappen

Gremlin-draadindeling

Azure Cosmos DB gebruikt de JSON-indeling bij het retourneren van resultaten uit Gremlin-bewerkingen. Azure Cosmos DB ondersteunt momenteel de JSON-indeling. In het volgende fragment wordt bijvoorbeeld een JSON-representatie weergegeven van een hoekpunt dat is geretourneerd naar de client vanuit Azure Cosmos DB:

  {
    "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
        }
      ]
    }
  }

De eigenschappen die worden gebruikt door de JSON-indeling voor hoekpunten, worden hieronder beschreven:

Eigenschap	Beschrijving
`id`	De id voor het hoekpunt. Moet uniek zijn (in combinatie met de waarde `_partition`, indien van toepassing). Als er geen waarde wordt opgegeven, wordt deze automatisch opgegeven met een GUID
`label`	Het label van het hoekpunt. Deze eigenschap wordt gebruikt om het entiteitstype te beschrijven.
`type`	Wordt gebruikt om hoekpunten te onderscheiden van niet-Graph-documenten
`properties`	Groep door de gebruiker gedefinieerde eigenschappen die zijn gekoppeld aan het hoekpunt. Elke eigenschap kan meerdere waarden hebben.
`_partition`	De partitiesleutel van het hoekpunt. Gebruikt voor graph-partitionering.
`outE`	Deze eigenschap bevat een lijst met uitlopende randen vanaf een hoekpunt. Het opslaan van informatie over aangrenzing met het hoekpunt zorgt voor een snelle uitvoering van traversals. Randen zijn gegroepeerd op basis van de bijbehorende labels.

Met elke eigenschap kunnen meerdere waarden worden opgeslagen binnen een matrix.

Eigenschap	Beschrijving
`value`	De waarde van de eigenschap

En de rand bevat de volgende informatie voor hulp bij het navigeren naar andere delen van de grafiek.

Eigenschap	Beschrijving
`id`	De id voor de rand. Moet uniek zijn (in combinatie met de waarde `_partition`, indien van toepassing)
`label`	Het label van de rand. Deze eigenschap is optioneel en wordt gebruikt om het relatietype te beschrijven.
`inV`	Deze eigenschap bevat een lijst met inkomende hoekpunten voor een rand. Het opslaan van informatie over aangrenzing aan de rand zorgt voor een snelle uitvoering van traversals. Hoekpunten zijn gegroepeerd op basis van de bijbehorende labels.
`properties`	Groep door de gebruiker gedefinieerde eigenschappen die zijn gekoppeld aan de rand.

Gremlin-stappen

We gaan nu de Gremlin-stappen bekijken die worden ondersteund in Azure Cosmos DB. Zie TinkerPop-naslagwerken voor een compleet overzicht van Gremlin.

stap	Beschrijving	TinkerPop 3.2-documentatie
`addE`	Voegt een rand toe tussen twee hoekpunten	stap: addE
`addV`	Voegt een hoekpunt toe aan de grafiek	stap: addV
`and`	Zorgt ervoor dat alle traversals een waarde retourneren	stap: and
`as`	Een stapmodulator om een variabele toe te wijzen aan de uitvoer van een stap	stap: as
`by`	Een stapmodulator die wordt gebruikt met `group` en `order`	stap: by
`coalesce`	Retourneert de eerste traversal die wordt geretourneerd als resultaat	stap: coalesce
`constant`	Retourneert een constante waarde. Wordt gebruikt met `coalesce`	stap: constant
`count`	Retourneert het aantal van de traversal	stap: count
`dedup`	Retourneert de waarden, zonder de dubbele waarden	stap: dedup
`drop`	Verwijdert de waarden (hoekpunt/rand)	stap: drop
`executionProfile`	Hiermee wordt een beschrijving gemaakt van alle bewerkingen die zijn gegenereerd door de uitgevoerde Gremlin-stap	executionProfile-stap
`fold`	Fungeert als barrière waarmee de combinatie van resultaten wordt berekend	stap: fold
`group`	Groepeert de waarden op basis van de opgegeven labels	stap: group
`has`	Wordt gebruikt om eigenschappen, hoekpunten en randen te filteren. Biedt ondersteuning voor de varianten `hasLabel`, `hasId`, `hasNot` en `has`.	stap: has
`inject`	Waarden invoeren in een stroom	stap: inject
`is`	Wordt gebruikt om een filter uit te voeren met behulp van een booleaanse expressie	stap: is
`limit`	Wordt gebruikt om het aantal items in de traversal te beperken	stap: limit
`local`	Verpakt een gedeelte van een traversal lokaal in, vergelijkbaar met een subquery	stap: local
`not`	Wordt gebruikt om de ontkenning van een filter te produceren	stap: not
`optional`	Retourneert het resultaat van de opgegeven traversal, indien er een resultaat is, anders wordt het aanroepende element geretourneerd	stap: optional
`or`	Zorgt ervoor dat minstens een van de traversals een waarde retourneert	stap: or
`order`	Retourneert resultaten in de opgegeven sorteervolgorde	stap: order
`path`	Retourneert het volledige pad van de traversal	stap: path
`project`	Projecteert de eigenschappen als een kaart	stap: project
`properties`	Retourneert de eigenschappen voor de opgegeven labels	stap: properties
`range`	Filtert op het opgegeven waardenbereik	stap: range
`repeat`	Herhaalt de stap zo vaak als is opgegeven. Wordt gebruikt om een lus te maken	stap: repeat
`sample`	Wordt gebruikt voor voorbeeldresultaten van de traversal	stap: sample
`select`	Wordt gebruikt voor projectresultaten van de traversal	stap: select
`store`	Wordt gebruikt voor niet-blokkerende combinaties van de traversal	stap: store
`TextP.startingWith(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap met het begin van een bepaalde tekenreeks	TextP-predicaten
`TextP.endingWith(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap met het einde van een bepaalde tekenreeks	TextP-predicaten
`TextP.containing(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap met de inhoud van een bepaalde tekenreeks	TextP-predicaten
`TextP.notStartingWith(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap die niet begint met een bepaalde tekenreeks	TextP-predicaten
`TextP.notEndingWith(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap die niet eindigt met een bepaalde tekenreeks	TextP-predicaten
`TextP.notContaining(string)`	Functie voor het filteren van tekenreeksen. Deze functie wordt gebruikt als een predicaat voor de `has()`-stap die gelijk is aan een eigenschap die geen bepaalde tekenreeks bevat	TextP-predicaten
`tree`	Paden van een hoekpunt combineren in een boomstructuur	stap: tree
`unfold`	Een iterator uitvoeren als stap	stap: unfold
`union`	Resultaten van meerdere traversals samenvoegen	stap: union
`V`	Bevat de stappen die nodig zijn voor traversals tussen hoekpunten en randen `V`, `E`, `out`, `in`, `both`, `outE`, `inE`, `bothE`, `outV`, `inV`, `bothV` en `otherV` voor	stap: vertex
`where`	Wordt gebruikt om resultaten van de traversal te filteren. Biedt ondersteuning voor de operators `eq`, `neq`, `lt`, `lte`, `gt`, `gte` en `between`	stap: where

De voor schrijven geoptimaliseerde engine van Azure Cosmos DB biedt standaard ondersteuning voor het automatisch indexeren van alle eigenschappen binnen hoekpunten en randen. Daarom worden query’s met filters, bereikquery’s, sorteringen of combinaties van elke willekeurige eigenschap verwerkt vanaf de index en efficiënt geleverd. Bekijk onze paper over schema-agnostisch indexeren voor meer informatie over hoe indexeren werkt in Azure Cosmos DB.

Gedragsverschillen

De Azure Cosmos DB Graph-engine voert breedte-eerste doorkruising uit, terwijl TinkerPop Gremlin diepte-eerst is. Dit gedrag zorgt voor betere prestaties in een horizontaal schaalbaar systeem, zoals Azure Cosmos DB.

Niet-ondersteunde functies

Gremlin Bytecode is een programmeertaalagnostische specificatie voor graafkruisingen. Azure Cosmos DB Graph biedt nog geen ondersteuning. Gebruik GremlinClient.SubmitAsync() en geef doorkruising door als een tekenreeks.
Instellen van kardinaliteit met property(set, 'xyz', 1) wordt momenteel niet ondersteund. Gebruik in plaats daarvan property(list, 'xyz', 1). Zie Vertex properties with TinkerPop voor meer informatie.
De match() stap is momenteel niet beschikbaar. Deze stap biedt declaratieve querymogelijkheden.
Objecten als eigenschappen op hoekpunten of randen worden niet ondersteund. Eigenschappen kunnen alleen primitieve typen of matrices zijn.
Sorteren op matrixeigenschappenorder().by(<array property>) wordt niet ondersteund. Alleen sorteren op primitieve typen wordt ondersteund.
Niet-primitieve JSON-typen worden niet ondersteund. Gebruik de typen string, number of true/false. null-waarden worden niet ondersteund.
GraphSONv3-serialisatiefunctie wordt momenteel niet ondersteund. Gebruik GraphSONv2 Serializer-, Reader- en Writer-klassen in de configuratie van de verbinding. De resultaten die door De Azure Cosmos DB voor Gremlin worden geretourneerd, hebben niet dezelfde indeling als de GraphSON-indeling.
Lambda-expressies en functies worden momenteel niet ondersteund. Dit geldt ook voor de functies .map{<expression>}, .by{<expression>}en .filter{<expression>}. Zie A Note on Lambdas voor meer informatie en om te leren hoe u deze functies kunt herschrijven met behulp van Gremlin-stappen.
Transacties worden niet ondersteund vanwege de gedistribueerde aard van het systeem. Configureer het juiste consistentie model op het Gremlin-account om uw eigen schrijfbewerkingen te lezen en gebruik optimistische gelijktijdigheid om conflicterende schrijfbewerkingen op te lossen.

Bekende beperkingen

Indexgebruik voor Gremlin-query's met .V()-stappen binnen doorkruising: Momenteel gebruikt alleen de eerste aanroep van .V() in een doorkruising gebruik van de index om gekoppelde filters of predicaten op te lossen. Bij volgende aanroepen wordt de index niet geraadpleegd, wat de latentie en de kosten van de query zou kunnen verhogen.

Uitgaande van standaardindexering, zou een typische Gremlin-query die begint met de stap .V() in de gekoppelde filterstappen parameters zoals .has() of .where() gebruiken om de kosten en de prestaties van de query te optimaliseren. Bijvoorbeeld:

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

Als er echter meer dan één .V()-stap is opgenomen in de Gremlin-query, is de resolutie van de gegevens voor de query mogelijk niet optimaal. Neem de volgende query als voorbeeld:

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

Met deze query worden twee groepen hoekpunten geretourneerd op basis van hun eigenschap category. In dit geval maakt alleen de eerste aanroep, g.V().has('category', 'A'), gebruik van de index om de hoekpunten op te lossen op basis van de waarden van hun eigenschappen.

Een tijdelijke oplossing voor deze query is het gebruiken van subdoorkruisingsstappen zoals .map() en union(). Hieronder ziet u een voorbeeld:

// 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'))

U kunt de prestaties van de query's controleren met behulp van de Gremlin-stap executionProfile().

Volgende stappen

Aan de slag met het bouwen van een grafiektoepassing met behulp van onze SDK’s
Meer informatie over ondersteuning voor grafieken in Azure Cosmos DB