Supporto dei grafi Gremlin in Azure Cosmos DB e compatibilità con le funzionalità di TinkerPopAzure Cosmos DB Gremlin graph support and compatibility with TinkerPop features

SI APPLICA A: API Gremlin

Azure Cosmos DB supporta il linguaggio di attraversamento di grafi di Apache Tinkerpop, noto come Gremlin.Azure Cosmos DB supports Apache Tinkerpop's graph traversal language, known as Gremlin. È possibile usare il linguaggio Gremlin per creare le entità dei grafi (vertici e archi), modificare proprietà all'interno di tali entità, eseguire query e attraversamenti ed eliminare entità.You can use the Gremlin language to create graph entities (vertices and edges), modify properties within those entities, perform queries and traversals, and delete entities.

Il motore Azure Cosmos DB Graph segue rigorosamente la specifica dei passaggi trasversali di Apache TinkerPop, ma esistono differenze nell'implementazione specifiche per Azure Cosmos DB.Azure Cosmos DB Graph engine closely follows Apache TinkerPop traversal steps specification but there are differences in the implementation that are specific for Azure Cosmos DB. Questo articolo illustra una procedura dettagliata di Gremlin ed enumera le funzionalità di Gremlin supportate dall'API Gremlin.In this article, we provide a quick walkthrough of Gremlin and enumerate the Gremlin features that are supported by the Gremlin API.

Librerie client compatibiliCompatible client libraries

La tabella seguente illustra i driver Gremlin noti che è possibile usare in Azure Cosmos DB:The following table shows popular Gremlin drivers that you can use against Azure Cosmos DB:

DownloadDownload Source (Sorgente)Source IntroduzioneGetting Started Versione connettore supportataSupported connector version
.NET.NET Gremlin.NET su GitHubGremlin.NET on GitHub Creare un'app Graph con .NETCreate Graph using .NET 3.4.63.4.6
JavaJava JavaDoc GremlinGremlin JavaDoc Creare un'app Graph con JavaCreate Graph using Java 3.2.0+3.2.0+
Node.jsNode.js Gremlin-JavaScript in GitHubGremlin-JavaScript on GitHub Creare un'app Graph con Node.jsCreate Graph using Node.js 3.3.4+3.3.4+
PythonPython Gremlin-Python in GitHubGremlin-Python on GitHub Creare un'app Graph con PythonCreate Graph using Python 3.2.73.2.7
PHPPHP Gremlin-PHP su GitHubGremlin-PHP on GitHub Creare un'app Graph con PHPCreate Graph using PHP 3.1.03.1.0
Go LangGo Lang Go LangGo Lang Questa libreria è creata da collaboratori esterni.This library is built by external contributors. Il team di Azure Cosmos DB non offre alcun supporto né gestisce la libreria.The Azure Cosmos DB team doesn't offer any support or maintain the library.
Console GremlinGremlin console Documenti TinkerPopTinkerPop docs Creare un'app Graph con la console GremlinCreate Graph using Gremlin Console 3.2.0 +3.2.0 +

Graph oggetti supportatoSupported Graph Objects

TinkerPop è uno standard che copre un'ampia gamma di tecnologie a grafi.TinkerPop is a standard that covers a wide range of graph technologies. Pertanto, ha una terminologia standard usata per descrivere le funzionalità offerte da un provider di grafi.Therefore, it has standard terminology to describe what features are provided by a graph provider. Azure Cosmos DB offre un database a grafi scrivibile, ad alta concorrenza, persistente, che può essere partizionato tra più server o cluster.Azure Cosmos DB provides a persistent, high concurrency, writeable graph database that can be partitioned across multiple servers or clusters.

La tabella seguente elenca le funzionalità di TinkerPop implementate da Azure Cosmos DB:The following table lists the TinkerPop features that are implemented by Azure Cosmos DB:

CategoryCategory Implementazione di Azure Cosmos DBAzure Cosmos DB implementation NoteNotes
Funzionalità del grafoGraph features Offre persistenza e accesso simultaneo.Provides Persistence and ConcurrentAccess. Progettata per supportare le transazioniDesigned to support Transactions Metodi di calcolo possono essere implementati tramite il connettore Spark.Computer methods can be implemented via the Spark connector.
Funzionalità della variabileVariable features Supporta Boolean, Integer, Byte, Double, Float, Integer, Long, StringSupports Boolean, Integer, Byte, Double, Float, Integer, Long, String Supporta i tipi primitivi, è compatibile con i tipi complessi tramite modello di datiSupports primitive types, is compatible with complex types via data model
Funzionalità del verticeVertex features Supporta RemoveVertices, MetaProperties, AddVertices, MultiProperties, StringIds, UserSuppliedIds, AddProperty, RemovePropertySupports RemoveVertices, MetaProperties, AddVertices, MultiProperties, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Supporta la creazione, la modifica e l'eliminazione di verticiSupports creating, modifying, and deleting vertices
Funzionalità della proprietà del verticeVertex property features StringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValuesStringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Supporta la creazione, la modifica e l'eliminazione di proprietà di verticiSupports creating, modifying, and deleting vertex properties
Funzionalità dell'arcoEdge features AddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemovePropertyAddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Supporta la creazione, la modifica e l'eliminazione di archiSupports creating, modifying, and deleting edges
Funzionalità della proprietà dell'arcoEdge property features Properties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValuesProperties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Supporta la creazione, la modifica e l'eliminazione di proprietà dell'arcoSupports creating, modifying, and deleting edge properties

Formato wire GremlinGremlin wire format

Azure Cosmos DB usa il formato JSON per la restituzione di risultati dalle operazioni Gremlin.Azure Cosmos DB uses the JSON format when returning results from Gremlin operations. Azure Cosmos DB attualmente supporta il formato JSON.Azure Cosmos DB currently supports the JSON format. Ad esempio, il frammento di codice seguente mostra una rappresentazione JSON di un vertice restituito al client da Azure Cosmos DB:For example, the following snippet shows a JSON representation of a vertex returned to the client from 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
        }
      ]
    }
  }

Le proprietà usate dal formato JSON per i vertici sono descritte di seguito:The properties used by the JSON format for vertices are described below:

ProprietàProperty DescrizioneDescription
id ID del vertice.The ID for the vertex. Deve essere univoco (in combinazione con il valore di _partition se applicabile).Must be unique (in combination with the value of _partition if applicable). Se non viene specificato alcun valore, viene automaticamente assegnato un GUIDIf no value is provided, it will be automatically supplied with a GUID
label Etichetta del vertice.The label of the vertex. Questa proprietà viene usata per descrivere il tipo di entità.This property is used to describe the entity type.
type Usato per distinguere i vertici da documenti non a grafoUsed to distinguish vertices from non-graph documents
properties Contenitore delle proprietà definite dall'utente associate al vertice.Bag of user-defined properties associated with the vertex. Ogni proprietà può avere più valori.Each property can have multiple values.
_partition La chiave di partizione del vertice.The partition key of the vertex. Usata per il partizionamento Graph.Used for graph partitioning.
outE Questa proprietà contiene un elenco degli archi uscenti da un vertice.This property contains a list of out edges from a vertex. L'archiviazione delle informazioni di adiacenza con il vertice consente l'esecuzione rapida degli attraversamenti.Storing the adjacency information with vertex allows for fast execution of traversals. Gli archi vengono raggruppati in base alle relative etichette.Edges are grouped based on their labels.

E l'arco contiene le informazioni seguenti per spostarsi in altre parti del grafo.And the edge contains the following information to help with navigation to other parts of the graph.

ProprietàProperty DescrizioneDescription
id ID dell'arco.The ID for the edge. Deve essere univoco (in combinazione con il valore di _partition se applicabile).Must be unique (in combination with the value of _partition if applicable)
label Etichetta dell'arco.The label of the edge. Questa proprietà è facoltativa e viene usata per descrivere il tipo di relazione.This property is optional, and used to describe the relationship type.
inV Questa proprietà contiene un elenco di vertici per un bordo.This property contains a list of in vertices for an edge. L'archiviazione delle informazioni di adiacenza con il bordo consente l'esecuzione rapida degli attraversamenti.Storing the adjacency information with the edge allows for fast execution of traversals. I vertici vengono raggruppati in base alle relative etichette.Vertices are grouped based on their labels.
properties Contenitore delle proprietà definite dall'utente associate all'arco.Bag of user-defined properties associated with the edge. Ogni proprietà può avere più valori.Each property can have multiple values.

Ogni proprietà può archiviare più valori all'interno di una matrice.Each property can store multiple values within an array.

ProprietàProperty DescrizioneDescription
value Valore della proprietàThe value of the property

Step di GremlinGremlin steps

Verranno ora esaminati gli step di Gremlin supportati da Azure Cosmos DB.Now let's look at the Gremlin steps supported by Azure Cosmos DB. Per informazioni complete su Gremlin, vedere TinkerPop reference (Riferimento a TinkerPop).For a complete reference on Gremlin, see TinkerPop reference.

stepstep DescrizioneDescription Documentazione TinkerPop 3.2TinkerPop 3.2 Documentation
addE Aggiunge un arco tra due verticiAdds an edge between two vertices addE stepaddE step
addV Aggiunge un vertice al grafoAdds a vertex to the graph addV stepaddV step
and Assicura che tutti gli attraversamenti restituiscono un valoreEnsures that all the traversals return a value and stepand step
as Modulatore di step per assegnare una variabile all'output di uno stepA step modulator to assign a variable to the output of a step as stepas step
by Modulatore di step usato con group e orderA step modulator used with group and order by stepby step
coalesce Restituisce il primo attraversamento che restituisce un risultatoReturns the first traversal that returns a result coalesce stepcoalesce step
constant Restituisce un valore costante.Returns a constant value. Usato con coalesceUsed with coalesce constant stepconstant step
count Restituisce il conteggio risultante dall'attraversamentoReturns the count from the traversal count stepcount step
dedup Restituisce i valori con i duplicati rimossiReturns the values with the duplicates removed dedup stepdedup step
drop Elimina i valori (vertice/arco)Drops the values (vertex/edge) drop stepdrop step
executionProfile Crea una descrizione di tutte le operazioni generate dallo step di Gremlin eseguitoCreates a description of all operations generated by the executed Gremlin step executionProfile stepexecutionProfile step
fold Si comporta come una barriera che calcola l'aggregazione di risultatiActs as a barrier that computes the aggregate of results fold stepfold step
group Raggruppa i valori in base alle etichette specificateGroups the values based on the labels specified group stepgroup step
has Usato per filtrare proprietà, vertici e archi.Used to filter properties, vertices, and edges. Supporta hasLabel, hasId, hasNot e le varianti has.Supports hasLabel, hasId, hasNot, and has variants. has stephas step
inject Inserisce i valori in un flussoInject values into a stream inject stepinject step
is Usato per eseguire un filtro con un'espressione booleanaUsed to perform a filter using a boolean expression is stepis step
limit Usato per limitare il numero di elementi nell'attraversamentoUsed to limit number of items in the traversal limit steplimit step
local Esegue il wrapping di una sezione di attraversamento, simile a una sottoqueryLocal wraps a section of a traversal, similar to a subquery local steplocal step
not Usato per produrre la negazione di un filtroUsed to produce the negation of a filter not stepnot step
optional Restituisce il risultato dell'attraversamento specificato se fornisce un risultato, in caso contrario restituisce l'elemento chiamanteReturns the result of the specified traversal if it yields a result else it returns the calling element optional stepoptional step
or Garantisce che almeno uno degli attraversamenti restituisca un valoreEnsures at least one of the traversals returns a value or stepor step
order Restituisce i risultati nell'ordinamento specificatoReturns results in the specified sort order order steporder step
path Restituisce il percorso completo dell'attraversamentoReturns the full path of the traversal path steppath step
project Proietta le proprietà come MappaProjects the properties as a Map project stepproject step
properties Restituisce le proprietà per le etichette specificateReturns the properties for the specified labels properties stepproperties step
range Filtra per l'intervallo di valori specificatoFilters to the specified range of values range steprange step
repeat Ripete lo step per il numero di volte specificato.Repeats the step for the specified number of times. Usato per eseguire i cicliUsed for looping repeat steprepeat step
sample Usato per campionare i risultati dell'attraversamentoUsed to sample results from the traversal sample stepsample step
select Usato per proiettare i risultati dell'attraversamentoUsed to project results from the traversal select stepselect step
store Usato per le aggregazioni non bloccanti risultanti dall'attraversamentoUsed for non-blocking aggregates from the traversal store stepstore step
TextP.startingWith(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che inizia con una determinata stringaThis function is used as a predicate for the has() step to match a property with the beginning of a given string Predicati TextPTextP predicates
TextP.endingWith(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che termina con una determinata stringaThis function is used as a predicate for the has() step to match a property with the ending of a given string Predicati TextPTextP predicates
TextP.containing(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che contiene una determinata stringaThis function is used as a predicate for the has() step to match a property with the contents of a given string Predicati TextPTextP predicates
TextP.notStartingWith(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che non inizia con una determinata stringaThis function is used as a predicate for the has() step to match a property that doesn't start with a given string Predicati TextPTextP predicates
TextP.notEndingWith(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che non termina con una determinata stringaThis function is used as a predicate for the has() step to match a property that doesn't end with a given string Predicati TextPTextP predicates
TextP.notContaining(string) Funzione di filtraggio di stringhe.String filtering function. Viene usata come predicato relativo allo step has() per consentire di trovare una corrispondenza con una proprietà che non contiene una determinata stringaThis function is used as a predicate for the has() step to match a property that doesn't contain a given string Predicati TextPTextP predicates
tree Aggrega i percorsi da un vertice a una struttura ad alberoAggregate paths from a vertex into a tree tree steptree step
unfold Srotola un iteratore come stepUnroll an iterator as a step unfold stepunfold step
union Unisce i risultati di più attraversamentiMerge results from multiple traversals union stepunion step
V Include gli step necessari per gli attraversamenti tra vertici e archi V, E, out, in, both, outE, inE, bothE, outV, inV, bothV, e otherV perIncludes the steps necessary for traversals between vertices and edges V, E, out, in, both, outE, inE, bothE, outV, inV, bothV, and otherV for vertex stepsvertex steps
where Usato per filtrare i risultati dell'attraversamento.Used to filter results from the traversal. Supporta eq, neq, lt, lte, gt, gte e gli operatori betweenSupports eq, neq, lt, lte, gt, gte, and between operators where stepwhere step

Il motore ottimizzato per la scrittura fornito da Azure Cosmos DB supporta l'indicizzazione automatica di tutte le proprietà comprese all'interno di vertici e archi per impostazione predefinita.The write-optimized engine provided by Azure Cosmos DB supports automatic indexing of all properties within vertices and edges by default. Pertanto, query con filtri, query di intervallo, ordinamento o aggregazioni in qualsiasi proprietà vengono elaborati dall'indice e serviti in modo efficiente.Therefore, queries with filters, range queries, sorting, or aggregates on any property are processed from the index, and served efficiently. Per altre informazioni sul funzionamento dell'indicizzazione in Azure Cosmos DB, vedere il documento sull'indicizzazione senza schema.For more information on how indexing works in Azure Cosmos DB, see our paper on schema-agnostic indexing.

Differenze di comportamentoBehavior differences

  • Il motore Azure Cosmos DB Graph esegue l'attraversamento *in ampiezza, mentre quello di TinkerPop Gremlin è in profondità.Azure Cosmos DB Graph engine runs *breadth-first _ traversal while TinkerPop Gremlin is depth-first. Questo comportamento consente di ottenere prestazioni migliori in un sistema scalabile orizzontalmente, come Cosmos DB.This behavior achieves better performance in horizontally scalable system like Cosmos DB.

Funzionalità non supportateUnsupported features

_ * Gremlin Bytecode _ è una specifica non dipendente da un linguaggio di programmazione per gli attraversamenti dei grafi._ *Gremlin Bytecode _ is a programming language agnostic specification for graph traversals. Cosmos DB Graph non la supporta ancora.Cosmos DB Graph doesn't support it yet. Usare GremlinClient.SubmitAsync() e passare l'attraversamento come stringa di testo.Use GremlinClient.SubmitAsync() and pass traversal as a text string.

_ La cardinalità set * property(set, 'xyz', 1) _ non è attualmente supportata._ *property(set, 'xyz', 1) _ set cardinality isn't supported today. In alternativa, utilizzare property(list, 'xyz', 1).Use property(list, 'xyz', 1) instead. Per altre informazioni, vedere le proprietà dei vertici con TinkerPop.To learn more, see Vertex properties with TinkerPop.

_ Il passaggio * match() _ non è attualmente disponibile._ The *match() step _ isn't currently available. Questo passaggio fornisce funzionalità di query dichiarative.This step provides declarative querying capabilities.

_ Gli *oggetti come proprietà _ su vertici o archi non sono supportati._ *Objects as properties _ on vertices or edges aren't supported. Le proprietà possono essere solo tipi primitivi o matrici.Properties can only be primitive types or arrays.

_ L'*ordinamento per proprietà di matrici _ order().by(<array property>) non è supportato._ *Sorting by array properties _ order().by(<array property>) isn't supported. L'ordinamento è supportato solo per tipi primitivi.Sorting is supported only by primitive types.

_ I *tipi JSON non primitivi _ non sono supportati._ *Non-primitive JSON types _ aren't supported. Usare i tipi string, number o true/false.Use string, number, or true/false types. I valori null non sono supportati.null values aren't supported.

_ Il serializzatore *GraphSONv3 _ non è attualmente supportato._ *GraphSONv3 _ serializer isn't currently supported. Usare le classi Serializer, Reader e Writer di GraphSONv2 nella configurazione della connessione.Use GraphSONv2 Serializer, Reader, and Writer classes in the connection configuration. I risultati restituiti dall'API Gremlin di Azure Cosmos DB non hanno lo stesso formato di GraphSON.The results returned by the Azure Cosmos DB Gremlin API don't have the same format as the GraphSON format.

_ Le *espressioni e le funzioni lambda non sono attualmente supportate._ Lambda expressions and functions aren't currently supported. Sono incluse le funzioni .map{<expression>}, .by{<expression>} e .filter{<expression>}.This includes the .map{<expression>}, the .by{<expression>}, and the .filter{<expression>} functions. Per altre informazioni, anche su come riscriverle usando i passaggi di Gremlin, vedere le note sulle espressioni lambda.To learn more, and to learn how to rewrite them using Gremlin steps, see A Note on Lambdas.

  • Le *transazioni _ non sono supportate a causa della natura distribuita del sistema.*Transactions _ aren't supported because of distributed nature of the system. Configurare il modello di coerenza appropriato nell'account Gremlin per ottenere garanzie "read your own writes" e usare la concorrenza ottimistica per risolvere le scritture in conflitto.Configure appropriate consistency model on Gremlin account to "read your own writes" and use optimistic concurrency to resolve conflicting writes.

Limitazioni noteKnown limitations

_ Utilizzo degli indici per le query Gremlin con passaggi di attraversamento intermedio .V() : Attualmente, solo la prima chiamata .V() di un attraversamento userà l'indice per risolvere eventuali filtri o predicati collegati._ Index utilization for Gremlin queries with mid-traversal .V() steps: Currently, only the first .V() call of a traversal will make use of the index to resolve any filters or predicates attached to it. Le chiamate successive non consulteranno l'indice, il che potrebbe aumentare la latenza e il costo della query.Subsequent calls will not consult the index, which might increase the latency and cost of the query.

Assuming default indexing, a typical read Gremlin query that starts with the `.V()` step would use parameters in its attached filtering steps, such as `.has()` or `.where()` to optimize the cost and performance of the query. For example:

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

However, when more than one `.V()` step is included in the Gremlin query, the resolution of the data for the query might not be optimal. Take the following query as an example:

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

This query will return two groups of vertices based on their property called `category`. In this case, only the first call, `g.V().has('category', 'A')` will make use of the index to resolve the vertices based on the values of their properties.

A workaround for this query is to use subtraversal steps such as `.map()` and `union()`. This is exemplified below:

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

You can review the performance of the queries by using the [Gremlin `executionProfile()` step](graph-execution-profile.md).

Passaggi successiviNext steps