Azure Cosmos DB: Creare, eseguire query e attraversare un grafo nella console Gremlin

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft. È possibile creare ed eseguire rapidamente query su database di documenti, coppie chiave/valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.

Questa guida introduttiva illustra come creare un account Azure Cosmos DB, un database e un grafo (contenitore) usando il portale di Azure e quindi usare la console di Gremlin da Apache TinkerPop per usare i dati dell'API Graph (anteprima). Questa esercitazione descrive come creare ed eseguire query su vertici e archi, aggiornare la proprietà di un vertice, eseguire query sui vertici, attraversare il grafo ed eliminare un vertice.

Azure Cosmos DB dalla console Apache Gremlin

La console Gremlin è basata su Groovy/Java e può essere eseguita su Linux, Mac e Windows. È possibile scaricare la console dal sito Apache TinkerPop.

Prerequisiti

Per creare un account Azure Cosmos DB per questa guida di avvio rapido, è necessaria una sottoscrizione di Azure.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

È anche necessario installare la console Gremlin. Usare la versione 3.2.5 o successiva.

Creare un account di database

  1. In una nuova finestra accedere al portale di Azure.

  2. Nel riquadro a sinistra selezionare Nuovo > Database > Azure Cosmos DB > Crea.

    Riquadro "Database" nel portale di Azure

  3. In Nuovo account specificare la configurazione desiderata per l'account Azure Cosmos DB.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (graph), MongoDB, SQL (DocumentDB) e Table (key-value). Attualmente ogni modello richiede un account separato.

    Poiché in questa guida introduttiva viene eseguita la programmazione in base all'API Graph, scegliere Gremlin (grafo) quando si compila il modulo. Se si hanno tuttavia dati di documenti di un'app di catalogo, dati chiave/valore (tabella) o dati di cui è stata eseguita la migrazione da un'app MongoDB, tenere presente che Azure Cosmos DB può fornire una piattaforma di servizi di database con distribuzione a livello globale e a disponibilità elevata per tutte le applicazioni cruciali.

    Completare i campi nel pannello Nuovo account usando le informazioni riportate nello screenshot seguente come guida. I valori potrebbero essere diversi da quelli dello screenshot.

    Pannello "Nuovo account"

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco che identifica l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile. L'ID deve contenere solo lettere minuscole, numeri e il segno meno (-). Deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API Gremlin (graph) La programmazione in base all'API Graph verrà eseguita più avanti in questo articolo.
    Sottoscrizione Sottoscrizione in uso Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Stesso valore di ID Nome del nuovo gruppo di risorse per l'account. Per semplicità si può usare lo stesso nome usato come ID.
    Località Area più vicina ai propri utenti Posizione geografica in cui ospitare l'account Azure Cosmos DB. Scegliere la posizione più vicina ai propri utenti per fornire loro l'accesso più rapido possibile ai dati.
  4. Selezionare Crea per creare l'account.

  5. Nella barra degli strumenti selezionare l'icona Notifiche Icona Notifiche per monitorare il processo di distribuzione.

    Riquadro "Notifiche" del portale di Azure

  6. Quando la finestra Notifiche indica che la distribuzione è stata completata, chiudere la finestra. Aprire il nuovo account dal riquadro Tutte le risorse nel dashboard.

    Riquadro "Tutte le risorse"

Aggiungere un grafo

È ora possibile usare lo strumento Esplora dati nel portale di Azure per creare un database a grafo.

  1. Dal menu a sinistra del portale di Azure scegliere Esplora dati (anteprima).

  2. In Esplora dati (anteprima) selezionare New Graph (Nuovo grafo). Compilare quindi la pagina usando le informazioni seguenti:

    Esplora dati nel portale di Azure

    Impostazione Valore consigliato Descrizione
    ID database sample-database ID del nuovo database. I nomi dei database devono avere una lunghezza compresa tra 1 e 255 caratteri e non possono contenere / \ # ? o spazi finali.
    Graph id (ID grafo) sample-graph ID del nuovo grafo. I nomi dei grafi presentano gli stessi requisiti relativi ai caratteri degli ID di database.
    Capacità di archiviazione 10 GB Lasciare il valore predefinito. Indica la capacità di archiviazione del database.
    Velocità effettiva 400 UR/s Lasciare il valore predefinito. È possibile aumentare la velocità effettiva in un secondo momento se si desidera ridurre la latenza.
    Chiave di partizione /userId Chiave di partizione che distribuisce i dati in modo uniforme a ogni partizione. Quando si crea un grafo ad alte prestazioni, è importante selezionare la chiave di partizione corretta. Per altre informazioni, vedere Progettazione per il partizionamento.
  3. Dopo avere compilato il modulo, fare clic su OK.

Connettersi al servizio app

  1. Prima di avviare la console Gremlin, creare o modificare il file di configurazione remote-secure.yaml nella directory apache-tinkerpop-gremlin-console-3.2.5/conf.
  2. Immettere le configurazioni per Hosts, Port, Username, Password, ConnectionPool e Serializer:

    Impostazione Valore consigliato Descrizione
    hosts [***.graphs.azure.com] Vedere lo screenshot di seguito. Si tratta del valore URI Gremlin disponibile nella pagina Panoramica del portale di Azure, tra parentesi quadre, senza la parte finale :443/.

    Questo valore può anche essere recuperato dalla scheda Chiavi, usando il valore dell'URI senza https://, sostituendo documents con graphs e rimuovendo la parte :443/ finale.
    port 443 Impostare su 443.
    username Nome utente Risorsa nel formato /dbs/<db>/colls/<coll>, dove <db> è il nome del database e <coll> è il nome della raccolta.
    password Chiave primaria Vedere il secondo screenshot di seguito. Si tratta della chiave primaria, che può essere recuperata dalla pagina Chiavi del portale di Azure nella casella Chiave primaria. Per copiare il valore, usare il pulsante di copia a sinistra della casella.
    connectionPool {enableSsl: true} Impostazione del pool di connessioni per SSL.
    serializer { className: org.apache.tinkerpop.gremlin.
    driver.ser.GraphSONMessageSerializerV1d0,
    config: { serializeResultToString: true }}
    Impostare questo valore ed eliminare qualsiasi interruzione di riga \n quando si incolla il valore.

    Per il valore Hosts, copiare il valore URI Gremlin dalla pagina Panoramica: Visualizzare e copiare il valore URI Gremlin nella pagina Panoramica del portale di Azure

    Per il valore Password, copiare la chiave primaria dalla pagina Chiavi: Visualizzare e copiare la chiave primaria nella pagina Chiavi del portale di Azure

  3. Nel terminale eseguire bin/gremlin.bat o bin/gremlin.sh per avviare la console Gremlin.

  4. Nel terminale eseguire :remote connect tinkerpop.server conf/remote-secure.yaml per connettersi al servizio app.

    Suggerimento

    Se viene visualizzato l'errore No appenders could be found for logger assicurarsi di aver aggiornato il valore del serializzatore nel file remote-secure.yaml come descritto nel passaggio 2.

L'installazione è riuscita. Al termine della configurazione, è possibile iniziare a eseguire alcuni comandi della console.

Provare un comando count () semplice. Digitare quanto segue al prompt nella console:

:> g.V().count()

Suggerimento

Si noti :> prima del testo g.V().count().

Si tratta di una parte del comando che è necessario digitare. È importante quando si usa la console Gremlin con Azure Cosmos DB.

Se il prefisso :> viene omesso, la console esegue il comando in locale, spesso su un grafo in memoria. L'uso di :> indica alla console di eseguire un comando remoto, in questo caso su Cosmos DB (l'emulatore localhost o un'istanza di Azure).

Creare vertici e archi

Per iniziare, aggiungere cinque vertici per le persone per Thomas, Mary Kay, Robin, Ben e Jack.

Input (Thomas):

:> g.addV('person').property('firstName', 'Thomas').property('lastName', 'Andersen').property('age', 44).property('userid', 1)

Output:

==>[id:796cdccc-2acd-4e58-a324-91d6f6f5ed6d,label:person,type:vertex,properties:[firstName:[[id:f02a749f-b67c-4016-850e-910242d68953,value:Thomas]],lastName:[[id:f5fa3126-8818-4fda-88b0-9bb55145ce5c,value:Andersen]],age:[[id:f6390f9c-e563-433e-acbf-25627628016e,value:44]],userid:[[id:796cdccc-2acd-4e58-a324-91d6f6f5ed6d|userid,value:1]]]]

Input (Mary Kay):

:> g.addV('person').property('firstName', 'Mary Kay').property('lastName', 'Andersen').property('age', 39).property('userid', 2)

Output:

==>[id:0ac9be25-a476-4a30-8da8-e79f0119ea5e,label:person,type:vertex,properties:[firstName:[[id:ea0604f8-14ee-4513-a48a-1734a1f28dc0,value:Mary Kay]],lastName:[[id:86d3bba5-fd60-4856-9396-c195ef7d7f4b,value:Andersen]],age:[[id:bc81b78d-30c4-4e03-8f40-50f72eb5f6da,value:39]],userid:[[id:0ac9be25-a476-4a30-8da8-e79f0119ea5e|userid,value:2]]]]

Input (Robin):

:> g.addV('person').property('firstName', 'Robin').property('lastName', 'Wakefield').property('userid', 3)

Output:

==>[id:8dc14d6a-8683-4a54-8d74-7eef1fb43a3e,label:person,type:vertex,properties:[firstName:[[id:ec65f078-7a43-4cbe-bc06-e50f2640dc4e,value:Robin]],lastName:[[id:a3937d07-0e88-45d3-a442-26fcdfb042ce,value:Wakefield]],userid:[[id:8dc14d6a-8683-4a54-8d74-7eef1fb43a3e|userid,value:3]]]]

Input (Ben):

:> g.addV('person').property('firstName', 'Ben').property('lastName', 'Miller').property('userid', 4)

Output:

==>[id:ee86b670-4d24-4966-9a39-30529284b66f,label:person,type:vertex,properties:[firstName:[[id:a632469b-30fc-4157-840c-b80260871e9a,value:Ben]],lastName:[[id:4a08d307-0719-47c6-84ae-1b0b06630928,value:Miller]],userid:[[id:ee86b670-4d24-4966-9a39-30529284b66f|userid,value:4]]]]

Input (Jack):

:> g.addV('person').property('firstName', 'Jack').property('lastName', 'Connor').property('userid', 5)

Output:

==>[id:4c835f2a-ea5b-43bb-9b6b-215488ad8469,label:person,type:vertex,properties:[firstName:[[id:4250824e-4b72-417f-af98-8034aa15559f,value:Jack]],lastName:[[id:44c1d5e1-a831-480a-bf94-5167d133549e,value:Connor]],userid:[[id:4c835f2a-ea5b-43bb-9b6b-215488ad8469|userid,value:5]]]]

Aggiungere quindi gli archi per le relazioni tra le persone.

Input (Thomas -> Mary Kay):

:> g.V().hasLabel('person').has('firstName', 'Thomas').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Mary Kay'))

Output:

==>[id:c12bf9fb-96a1-4cb7-a3f8-431e196e702f,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:0d1fa428-780c-49a5-bd3a-a68d96391d5c,outV:1ce821c6-aa3d-4170-a0b7-d14d2a4d18c3]

Input (Thomas -> Robin):

:> g.V().hasLabel('person').has('firstName', 'Thomas').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Robin'))

Output:

==>[id:58319bdd-1d3e-4f17-a106-0ddf18719d15,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:3e324073-ccfc-4ae1-8675-d450858ca116,outV:1ce821c6-aa3d-4170-a0b7-d14d2a4d18c3]

Input (Robin -> Ben):

:> g.V().hasLabel('person').has('firstName', 'Robin').addE('knows').to(g.V().hasLabel('person').has('firstName', 'Ben'))

Output:

==>[id:889c4d3c-549e-4d35-bc21-a3d1bfa11e00,label:knows,type:edge,inVLabel:person,outVLabel:person,inV:40fd641d-546e-412a-abcc-58fe53891aab,outV:3e324073-ccfc-4ae1-8675-d450858ca116]

Aggiornare un vertice

Aggiornare il vertice Thomas con la nuova età 45.

Input:

:> g.V().hasLabel('person').has('firstName', 'Thomas').property('age', 45)

Output:

==>[id:ae36f938-210e-445a-92df-519f2b64c8ec,label:person,type:vertex,properties:[firstName:[[id:872090b6-6a77-456a-9a55-a59141d4ebc2,value:Thomas]],lastName:[[id:7ee7a39a-a414-4127-89b4-870bc4ef99f3,value:Andersen]],age:[[id:a2a75d5a-ae70-4095-806d-a35abcbfe71d,value:45]]]]

Eseguire query sul grafo

È ora possibile eseguire diverse query sul grafo.

Prima di tutto, provare una query con un filtro per restituire solo le persone con età maggiore di 40 anni.

Input (query con filtro):

:> g.V().hasLabel('person').has('age', gt(40))

Output:

==>[id:ae36f938-210e-445a-92df-519f2b64c8ec,label:person,type:vertex,properties:[firstName:[[id:872090b6-6a77-456a-9a55-a59141d4ebc2,value:Thomas]],lastName:[[id:7ee7a39a-a414-4127-89b4-870bc4ef99f3,value:Andersen]],age:[[id:a2a75d5a-ae70-4095-806d-a35abcbfe71d,value:45]]]]

Proiettare quindi il nome delle persone con età maggiore di 40 anni.

Input (query con filtro + query di proiezione):

:> g.V().hasLabel('person').has('age', gt(40)).values('firstName')

Output:

==>Thomas

Attraversare il grafo

È ora possibile attraversare il grafo per restituire tutti gli amici di Thomas.

Input (amici di Thomas):

:> g.V().hasLabel('person').has('firstName', 'Thomas').outE('knows').inV().hasLabel('person')

Output:

==>[id:f04bc00b-cb56-46c4-a3bb-a5870c42f7ff,label:person,type:vertex,properties:[firstName:[[id:14feedec-b070-444e-b544-62be15c7167c,value:Mary Kay]],lastName:[[id:107ab421-7208-45d4-b969-bbc54481992a,value:Andersen]],age:[[id:4b08d6e4-58f5-45df-8e69-6b790b692e0a,value:39]]]]
==>[id:91605c63-4988-4b60-9a30-5144719ae326,label:person,type:vertex,properties:[firstName:[[id:f760e0e6-652a-481a-92b0-1767d9bf372e,value:Robin]],lastName:[[id:352a4caa-bad6-47e3-a7dc-90ff342cf870,value:Wakefield]]]]

Ottenere quindi il livello successivo dei vertici. Attraversare il grafo per restituire tutti gli amici degli amici di Thomas.

Input (amici degli amici di Thomas):

:> g.V().hasLabel('person').has('firstName', 'Thomas').outE('knows').inV().hasLabel('person').outE('knows').inV().hasLabel('person')

Output:

==>[id:a801a0cb-ee85-44ee-a502-271685ef212e,label:person,type:vertex,properties:[firstName:[[id:b9489902-d29a-4673-8c09-c2b3fe7f8b94,value:Ben]],lastName:[[id:e084f933-9a4b-4dbc-8273-f0171265cf1d,value:Miller]]]]

Eliminare un vertice

Verrà ora eliminato un vertice dal database del grafo.

Input (eliminazione del vertice Jack):

:> g.V().hasLabel('person').has('firstName', 'Jack').drop()

Cancellare il grafo

Infine, è possibile cancellare il database di tutti i vertici e gli archi.

Input:

:> g.E().drop()
:> g.V().drop()

Congratulazioni. Questa esercitazione sull'API Graph di Azure Cosmos DB è stata completata.

Esaminare i contratti di servizio nel portale di Azure

Ora che l'app è operativa, è opportuno garantire la continuità aziendale e controllare l'accesso degli utenti per garantire disponibilità elevata. Per esaminare la disponibilità, la latenza, la velocità effettiva e la coerenza della raccolta, si può usare il portale di Azure.

Ogni grafo associato ai contratti di servizio per Azure Cosmos DB fornisce una linea che mostra la quota necessaria per soddisfare il contratto di servizio e l'utilizzo effettivo. Queste informazioni offrono una panoramica chiara sulle prestazioni del database. Nel portale sono anche incluse altre metriche, ad esempio per quanto riguarda l'uso dello spazio di archiviazione e il numero di richieste al minuto.

  • Nel riquadro a sinistra del portale di Azure, in Monitoraggio, selezionare Metriche.

    App elenco attività con dati di esempio

Pulire le risorse

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido nel portale di Azure eseguendo questi passaggi:

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.

Passaggi successivi

In questa guida di avvio rapido si è appreso come creare un account Azure Cosmos DB, come creare un grafo con Esplora dati, come creare vertici e archi e come attraversare il grafo con la console Gremlin. È ora possibile creare query più complesse e implementare la potente logica di attraversamento dei grafi usando Gremlin.