Inicio rápido: Creación, consulta y recorrido de una base de datos de grafos de Azure Cosmos DB en la consola de Gremlin

  • Artículo
  • 11 minutos para leer

SE APLICA A: Gremlin API

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft. Puede crear rápidamente bases de datos de documentos, clave-valor y grafos, y realizar consultas en ellas. Todas las bases de datos se beneficiarán de las funcionalidades de distribución global y escala horizontal en Azure Cosmos DB.

En este inicio rápido se muestra cómo crear una cuenta de Gremlin API, una base de datos y un grafo (contenedor) de Azure Cosmos DB mediante Azure Portal y cómo usar la consola de Gremlin de Apache TinkerPop para trabajar con los datos de Gremlin API. En este tutorial, creará y consultará vértices y bordes, actualizará una propiedad de vértice, consultará vértices, recorrerá el grafo y quitará un vértice.

Azure Cosmos DB desde la consola de Apache Gremlin

La consola de Gremlin se basa en Groovy/Java y se ejecuta en Linux, Mac y Windows. Puede descargarla desde el sitio de Apache TinkerPop.

Requisitos previos

Necesita tener una suscripción de Azure para crear una cuenta de Azure Cosmos DB para este inicio rápido.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

También necesita instalar la consola de Gremlin. Se recomienda la versión v3.4.3, o cualquier versión anterior (Para usar la consola de Gremlin en Windows, debe instalar Java Runtime, como mínimo Java 8, pero es preferible usar Java 11).

Creación de una cuenta de base de datos

  1. En una nueva ventana del explorador, inicie sesión en Azure Portal.

  2. En el menú de la izquierda, seleccione Crear un recurso.

    Crear un recurso en Azure Portal

  3. En la página Nuevo, seleccione Bases de datos > Azure Cosmos DB.

    El panel Bases de datos de Azure Portal

  4. En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.

    Configuración Value Descripción
    Suscripción Nombre de suscripción Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
    Grupo de recursos Definición de un nombre de grupo de recursos Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
    Nombre de cuenta Escriba un nombre único. Escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El URI de la cuenta será gremlin.azure.com y se anexará al nombre único de la cuenta.

    El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 44 caracteres de longitud.
    API Gremlin (grafo) La API determina el tipo de cuenta que se va a crear. Azure Cosmos DB proporciona cinco API: Core (SQL) para bases de datos de documentos, Gremlin para bases de datos de grafos, MongoDB para bases de datos de documentos, Azure Table y Cassandra. Debe crear una cuenta independiente para cada API.

    Seleccione Gremlin (grafo), ya que en este inicio rápido va a crear una tabla que funciona con Gremlin API.

    Más información sobre Gremlin API.
    Location Región más cercana a los usuarios Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
    Capacity mode (Modo de capacidad) Rendimiento aprovisionado o sin servidor Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.
    Aplicar el descuento del nivel Gratis de Azure Cosmos DB Aplicar o No aplicar Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.

    Nota

    Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.

    Página de la nueva cuenta de Azure Cosmos DB

  5. En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:

    Configuración Value Descripción
    Redundancia geográfica Deshabilitar Habilite o deshabilite la distribución global en su cuenta. Para ello, debe emparejar su región con una región de par. Puede agregar más regiones a su cuenta más adelante.
    Escrituras en varias regiones Deshabilitar La funcionalidad de escrituras en varias regiones le permite aprovechar el rendimiento aprovisionado para sus bases de datos y contenedores de todo el mundo.

    Nota

    Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):

    • Aplicación de descuento por nivel Gratis
    • Redundancia geográfica
    • Escrituras en varias regiones

  6. Opcionalmente, puede configurar detalles adicionales en las pestañas siguientes:

    • Redes: configure el acceso desde una red virtual.
    • Directiva de copia de seguridad: configure una directiva de copia de seguridad periódica o continua.
    • Cifrado: use una clave administrada por el servicio o una clave administrada por el cliente.
    • Etiquetas: son pares nombre-valor que permiten categorizar los recursos y ver una facturación consolidada mediante la aplicación de la misma etiqueta en varios recursos y grupos de recursos.

  7. Seleccione Revisar + crear.

  8. La cuenta tarda unos minutos en crearse. Espere a que el portal muestre la página ¡Enhorabuena! Se ha creado su cuenta de Azure Cosmos DB.

    Página creada de la cuenta de Azure Cosmos DB

Agregar un grafo

Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos de grafos.

  1. Seleccione Explorador de datos > New Graph (Nuevo grafo).

    El área Agregar gráfico se muestra en el extremo derecho, pero es posible que haya que desplazarse hacia la derecha para verlo.

    Explorador de datos en Azure Portal, página Agregar gráfico

  2. En la página Agregar gráfico, especifique la configuración del nuevo gráfico.

    Configuración Valor sugerido Descripción
    Identificador de base de datos sample-database Escriba sample-database como nombre de la nueva base de datos. Los nombres de bases de datos deben tener entre 1 y 255 caracteres y no pueden contener / \ # ? o un espacio al final.
    Throughput 400 RU Cambie el rendimiento a 400 unidades de solicitud por segundo (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante.
    Identificador de grafo sample-graph Escriba sample-graph como nombre de la nueva colección. Los nombres de grafo tienen los mismos requisitos de caracteres que los identificadores de base de datos.
    Partition Key /pk Todas las cuentas de Cosmos DB necesitan una clave de partición para escalar horizontalmente. Aprenda a seleccionar una clave de partición adecuada en el artículo de creación de particiones de datos de Graph.

  3. Una vez que haya rellenado el formulario, seleccione Aceptar.

Conectarse a su App Service/Graph

  1. Antes de iniciar la consola de Gremlin, cree o modifique el archivo de configuración remote-secure.yaml en el directorio apache-tinkerpop-gremlin-console-3.2.5/conf.

  2. Rellene sus configuraciones de host, puerto, nombre de usuario, contraseña, connectionPool y serializador como se define en la siguiente tabla:

    Configuración Valor sugerido Descripción
    hosts [account-name.gremlin.cosmos.azure.com] Vea la siguiente captura de pantalla. Este es el valor de URI de Gremlin de la página Información general de Azure Portal, entre corchetes, sin la terminación :443/. Nota: Asegúrese de usar el valor de Gremlin, no el identificador URI que termina en [account-name.documents.azure.com], lo que probablemente daría como resultado la excepción "Host did not respond in a timely fashion" (El host no respondió a tiempo) al intentar ejecutar consultas Gremlin después.
    port 443 Se establece en 443.
    username Su nombre de usuario El recurso con la forma /dbs/<db>/colls/<coll> donde <db> es el nombre de la base de datos y <coll> es el nombre de la colección.
    password La clave principal Ver la segunda captura de pantalla más adelante. Es la clave principal, que puede obtener en la página Claves de Azure Portal, en el cuadro de texto Clave principal. Use el botón Copiar a la izquierda del cuadro de texto para copiar el valor.
    connectionPool {enableSsl: true} La configuración del grupo de conexiones para TLS.
    serializer { className:org.apache.tinkerpop.gremlin.
    driver.ser.GraphSONMessageSerializerV2d0,
    config: { serializeResultToString: true }}    		 Establecer en este valor y eliminar los saltos de línea \n cuando se pegue el valor.

    Para obtener el valor de los hosts, copie el valor de URI de Gremlin de la página Introducción:

    Copie del valor del URI de Gremlin en la página Introducción en Azure Portal

    Para obtener el valor de la contraseña, copie la Clave principal de la página Claves:

    Visualización y copia de la clave principal en Azure Portal, página Claves

    El archivo remote-secure.yaml debe tener este aspecto:

    hosts: [your_database_server.gremlin.cosmos.azure.com] 
port: 443
username: /dbs/your_database/colls/your_collection
password: your_primary_key
connectionPool: {
  enableSsl: true
}
serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0, config: { serializeResultToString: true }}

    asegúrese de que encapsular el valor del parámetro de hosts entre corchetes [].

  3. En el terminal, ejecute bin/gremlin.bat o bin/gremlin.sh para iniciar la Consola de Gremlin.

  4. En el terminal, ejecute :remote connect tinkerpop.server conf/remote-secure.yaml para conectarse a App Service.

    Sugerencia

    Si recibe el error No appenders could be found for logger asegúrese de que ha actualizado el valor de serializador en el archivo remote-secure.yaml tal como se describe en el paso 2. Si la configuración es correcta, esta advertencia se puede omitir sin problemas, ya que no debería afectar al uso de la consola.

  5. A continuación ejecute :remote console para redirigir todos los comandos de la consola al servidor remoto.

    Nota

    Si no ejecuta el comando :remote console pero quiere redirigir todos los comandos de consola al servidor remoto, debe anteponer :> al comando. Por ejemplo, tiene que ejecutarlo como :> g.V().count(). Este prefijo es parte del comando y es importante si se usa la consola de Gremlin con Azure Cosmos DB. Si omite este prefijo, le indica a la consola que ejecute el comando localmente, a menudo en un gráfico en memoria. Con este prefijo :>, le indica a la consola que ejecute un comando remoto, en este caso en Azure Cosmos DB (ya sea el emulador local o una instancia de Azure).

Estupendo. Ahora que hemos terminado la configuración, comencemos a ejecutar algunos comandos de la consola.

Probemos un comando count() sencillo. En el símbolo del sistema de la consola, escriba lo siguiente:

g.V().count()

Crear vértices y bordes

Comencemos agregando cinco vértices de personas para Thomas, Mary Kay, Robin, Ben y Jack.

Entrada (Thomas):

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

Salida:

==>[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]]]]

Entrada (Mary Kay):

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

Salida:

==>[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]]]]

Entrada (Robin):

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

Salida:

==>[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]]]]

Entrada (Ben):

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

Salida:

==>[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]]]]

Entrada (Jack):

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

Salida:

==>[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]]]]

Después, vamos a agregar bordes a las relaciones entre estas personas.

Entrada (Thomas -> Mary Kay):

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

Salida:

==>[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]

Entrada (Thomas -> Robin):

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

Salida:

==>[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]

Entrada (Robin -> Ben):

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

Salida:

==>[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]

Actualizar un vértice

Vamos a actualizar el vértice Thomas con una nueva edad de 45.

Entrada:

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

Salida:

==>[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]]]]

Consultar el grafo

Ahora, vamos a ejecutar una variedad de consultas en su grafo.

Primero, vamos a probar una consulta con un filtro para devolver solo las personas mayores de 40 años.

Entrada (consulta de filtro):

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

Salida:

==>[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]]]]

Después, vamos a proyectar el nombre de las personas que sean mayores de 40 años.

Entrada (filtro + consulta de proyección):

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

Salida:

==>Thomas

Recorrer el grafo

Vamos a recorrer el grafo para devolver todos los amigos de Thomas.

Entrada (amigos de Thomas):

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

Salida:

==>[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]]]]

Ahora, vamos a obtener la siguiente capa de vértices. Recorra el grafo para devolver todos los amigos de los amigos de Thomas.

Entrada (amigos de los amigos de Thomas):

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

Salida:

==>[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]]]]

Quitar un vértice

Vamos a eliminar un vértice de la base de datos del grafo.

Entrada (quitar vértice de Jack):

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

Borrar el grafo

Por último, vamos a borrar todos los vértices y bordes de la base de datos.

Entrada:

g.E().drop()
g.V().drop()

Felicidades. Acaba de completar este tutorial de Azure Cosmos DB: Gremlin API

Revisión de los SLA en Azure Portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:

  1. Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.

  2. Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha. Compare las líneas Real y SLA de los gráficos.

    Conjunto de métricas de Azure Cosmos DB

  3. Revise las métricas de las otras pestañas.

Limpieza de recursos

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos. Para eliminar los recursos:

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.

  2. En la lista, seleccione el grupo de recursos que creó para este inicio rápido.

    Selección del grupo de recursos que se eliminará

  3. En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.

    Eliminar el grupo de recursos

  4. En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.

Pasos siguientes

En este inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear un grafo con el Explorador de datos, crear vértices y bordes, y recorrer el grafo con la consola de Gremlin. Ahora puede crear consultas más complejas e implementar con Gremlin una lógica eficaz de recorrido del grafo.

Consulta mediante Gremlin