Ingesta masiva de datos en Azure Cosmos DB for Gremlin mediante una biblioteca bulk executor

  • Artículo

SE APLICA A: Gremlin

Las bases de datos de grafos suelen necesitar ingerir datos de forma masiva para actualizar un grafo completo o actualizar una parte de él. Azure Cosmos DB, base de datos distribuida y columna vertebral de Azure Cosmos DB for Gremlin, se ha pensado para funcionar si la carga está bien distribuida. Las bibliotecas Bulk Executor de Azure Cosmos DB están diseñadas para aprovechar esta funcionalidad única de Azure Cosmos DB y proporcionar un rendimiento óptimo. Para más información, consulte Introducción a la compatibilidad masiva en el SDK de .NET.

En este tutorial aprenderá a usar la biblioteca Bulk Executor de Azure Cosmos DB para importar y actualizar objetos de grafos en un contenedor de Azure Cosmos DB for Gremlin. Durante este proceso, usará la biblioteca para crear objetos de vértices y perimetrales mediante programación e insertar varios objetos por solicitud de red.

En lugar de enviar consultas de Gremlin a una base de datos, en las que los comandos se evalúan y se ejecutan uno cada vez, se usa la biblioteca Bulk Executor para crear y validar los objetos de forma local. Una vez que la biblioteca haya inicializado los objetos del grafo, permite enviarlos al servicio de base de datos de forma secuencial.

Mediante este método puede aumentar las velocidades de ingesta de datos hasta cien veces, por lo que es ideal para las migraciones de datos iniciales o las operaciones periódicas de movimiento de datos.

La biblioteca Bulk Executor ahora viene en las siguientes variedades.

.NET

Requisitos previos

Antes de comenzar, asegúrese de que tiene lo siguiente:

Clonar

Para usar este ejemplo, ejecute el comando siguiente:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Para obtener el ejemplo, vaya a .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Muestra


IGraphBulkExecutor graphBulkExecutor = new GraphBulkExecutor("MyConnectionString", "myDatabase", "myContainer");

List<IGremlinElement> gremlinElements = new List<IGremlinElement>();
gremlinElements.AddRange(Program.GenerateVertices(Program.documentsToInsert));
gremlinElements.AddRange(Program.GenerateEdges(Program.documentsToInsert));
BulkOperationResponse bulkOperationResponse = await graphBulkExecutor.BulkImportAsync(
    gremlinElements: gremlinElements,
    enableUpsert: true);

Execute

Modifique los parámetros, como se describe en la tabla siguiente:

Parámetro Descripción
ConnectionString Su cadena de conexión de servicio, que encontrará en la sección Clavesde su cuenta de Azure Cosmos DB para Gremlin. Tiene el formato AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Nombre de la base de datos y del contenedor de destino.
DocumentsToInsert Número de documentos que se van a generar (solo para los datos sintéticos).
PartitionKey Garantiza que se especifica una clave de partición con cada documento durante la ingesta de datos.
NumberOfRUs Solo procede si aún no existe un contenedor y debe crearse durante la ejecución.

Descargue la aplicación de ejemplo completa en .NET.

Java

Ejemplo de uso

La aplicación de ejemplo siguiente ilustra cómo usar el paquete GraphBulkExecutor. Los ejemplos usan directamente las anotaciones del objeto de dominio o los objetos POJO (objeto Java antiguo sin formato). Se recomienda probar ambos enfoques para determinar cuál responde mejor a sus necesidades de implementación y rendimiento.

Clonar

Para usar el ejemplo, ejecute el comando siguiente:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Para obtener el ejemplo, vaya a .\azure-cosmos-graph-bulk-executor\java\.

Prerrequisitos

Para ejecutar este ejemplo, deberá tener el software siguiente:

  • OpenJDK 11
  • Maven
  • Una cuenta de Azure Cosmos DB configurada para usar Gremlin API

Muestra

private static void executeWithPOJO(Stream<GremlinVertex> vertices,
                                        Stream<GremlinEdge> edges,
                                        boolean createDocs) {
        results.transitionState("Configure Database");
        UploadWithBulkLoader loader = new UploadWithBulkLoader();
        results.transitionState("Write Documents");
        loader.uploadDocuments(vertices, edges, createDocs);
    }

Configuración

Para ejecutar el ejemplo, consulte la configuración siguiente y modifíquela según sea necesario.

El archivo /resources/application.properties define los datos necesarios para configurar Azure Cosmos DB. Los valores obligatorios se describen en la tabla siguiente:

Propiedad Descripción
sample.sql.host Valor proporcionado por Azure Cosmos DB. Asegúrese de que usa el URI del SDK de .NET que encontrará en la sección Información general de la cuenta de Azure Cosmos DB.
sample.sql.key Puede obtener la clave principal o secundaria de la sección Claves de la cuenta de Azure Cosmos DB.
sample.sql.database.name Nombre de la base de datos dentro de la cuenta de Azure Cosmos DB en la que se va a ejecutar el ejemplo. Si no se encuentra la base de datos, el código de ejemplo la crea.
sample.sql.container.name Nombre del contenedor dentro de la base de datos en la que se va a ejecutar el ejemplo. Si no se encuentra el contenedor, el código de ejemplo lo crea.
sample.sql.partition.path Si necesita crear el contenedor, use este valor para definir la ruta de acceso partitionKey.
sample.sql.allow.throughput El contenedor se actualizará para usar el valor de rendimiento definido aquí. Si está explorando diferentes opciones de rendimiento para satisfacer sus demandas de rendimiento, asegúrese de restablecer el rendimiento en el contenedor cuando haya terminado con la exploración. Hay costos asociados al dejar el contenedor aprovisionado con un rendimiento más alto.

Execute

Después de modificar la configuración según el entorno, ejecute el siguiente comando:

mvn clean package

Para mayor seguridad, también puede ejecutar las pruebas de integración; para ello, cambie el valor skipIntegrationTests del archivo pom.xml a false.

Después de ejecutar correctamente las pruebas unitarias, puede ejecutar el código de ejemplo:

java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d

Al ejecutar el comando anterior, se ejecuta el ejemplo con un lote pequeño (1000 vértices y aproximadamente 5000 bordes). Use los argumentos de la línea de comandos de las secciones siguientes para ajustar los volúmenes que se ejecutan y la versión de ejemplo que se va a ejecutar.

Argumentos de la línea de comandos

Hay varios argumentos de línea de comandos disponibles mientras ejecuta este ejemplo, como se describe en la tabla siguiente:

Argumento Descripción
--vertexCount (-v) Indica a la aplicación cuántos vértices de persona se van a generar.
--edgeMax (-e) Indica a la aplicación el máximo de bordes que se van a generar para cada vértice. El generador selecciona aleatoriamente un número entre el 1 y el valor que proporcione.
--domainSample (-d) Indica a la aplicación que ejecute el ejemplo usando las estructuras de dominio Person y Relationship en lugar de los POJO GraphBulkExecutors, GremlinVertex y GremlinEdge.
--createDocuments (-c) Indica a la aplicación que use operaciones create. Si el argumento no está presente, la aplicación usa las operaciones upsert de forma predeterminada.

Información detallada de ejemplo

Vértice de persona

La clase person es un objeto de dominio simple que se ha decorado con varias anotaciones para ayudar a una transformación a la clase GremlinVertex, como se describe en la tabla siguiente:

Anotación de clase Descripción
GremlinVertex Usa el parámetro opcional label para definir todos los vértices que cree mediante esta clase.
GremlinId Se usa para definir qué campo se usará como valor ID. El nombre de campo de la clase person es ID, pero no es obligatorio.
GremlinProperty Se usa en el campo email para cambiar el nombre de la propiedad cuando se almacena en la base de datos.
GremlinPartitionKey Se usa para definir qué campo de la clase contiene la clave de partición. El nombre del campo proporcionado debe coincidir con el valor definido por la ruta de acceso de la partición en el contenedor.
GremlinIgnore Se usa para excluir el campo isSpecial de la propiedad que se está escribiendo en la base de datos.

Clase RelationshipEdge

La clase RelationshipEdge es un objeto de dominio versátil. Mediante el uso de la anotación de etiqueta de nivel de campo, puede crear una colección dinámica de tipos de borde, tal y como se muestra en la tabla siguiente:

Anotación de clase Descripción
GremlinEdge La decoración GremlinEdge en la clase define el nombre del campo para la clave de partición especificada. Al crear un documento de borde, el valor asignado procede de la información del vértice de origen.
GremlinEdgeVertex Se definen dos instancias de GremlinEdgeVertex, una para cada lado del borde (origen y destino). Nuestro ejemplo tiene el tipo de datos del campo como GremlinEdgeVertexInfo. La información que proporciona la clase GremlinEdgeVertex es necesaria para que el borde se cree correctamente en la base de datos. Otra opción sería que el tipo de datos de los vértices fuera una clase decorada con las anotaciones de GremlinVertex.
GremlinLabel El borde de ejemplo usa un campo para definir el valor label. Permite definir varias etiquetas, ya que usa la misma clase de dominio base.

Descripción de la salida

La consola finaliza su ejecución con una cadena JSON que describe los tiempos de ejecución del ejemplo. La cadena JSON contiene la información siguiente:

Cadena JSON. Descripción
startTime System.nanoTime() en que se inició el proceso.
endTime System.nanoTime() de finalización del proceso.
durationInNanoSeconds Diferencia entre los valores endTime y startTime.
durationInMinutes Valor durationInNanoSeconds, convertido en minutos. El valor durationInMinutes se representa como número flotante, no como valor de tiempo. Por ejemplo, un valor de 2,5 correspondería a 2 minutos y 30 segundos.
vertexCount Volumen de vértices generados que debe coincidir con el valor pasado a la ejecución de la línea de comandos.
edgeCount Volumen de bordes generados, no es estático y se genera con un elemento de aleatoriedad.
excepción Solo se rellena si se produce una excepción al intentar realizar la ejecución.

Matriz de estados

La matriz de estados proporciona información sobre cuánto tiempo tarda cada paso de la ejecución. Los pasos se describen en la tabla siguiente:

Paso de ejecución Descripción
Compilación de los vértices de ejemplo Tiempo necesario para crear el volumen solicitado de objetos person.
Creación de bordes de ejemplo Tiempo que se tarda en crear los objetos de relación.
Configuración de la base de datos Tiempo que se tarda en configurar la base de datos en función de los valores proporcionados en application.properties.
Escritura de documentos Tiempo que se tarda en escribir los documentos en la base de datos.

Cada estado contiene los valores siguientes:

Valor de estado Descripción
stateName Nombre del estado del que se está informando.
startTime Valor de System.nanoTime() cuando se inició el estado.
endTime Valor de System.nanoTime() cuando finalizó el estado.
durationInNanoSeconds Diferencia entre los valores endTime y startTime.
durationInMinutes Valor durationInNanoSeconds, convertido en minutos. El valor durationInMinutes se representa como número flotante, no como valor de tiempo. Por ejemplo, un valor de 2,5 correspondería a 2 minutos y 30 segundos.

Pasos siguientes