Ingerir dados em massa no Azure Cosmos DB para Gremlin com uma biblioteca de executor em massa

  • Artigo

APLICA-SE A: Gremlin

Muitas vezes, as bases de dados de grafos precisam de ingerir dados em massa para atualizar um gráfico inteiro ou atualizar uma parte do mesmo. O Azure Cosmos DB, uma base de dados distribuída e a estrutura principal do Azure Cosmos DB para Gremlin, destina-se a ter um melhor desempenho quando as cargas estão bem distribuídas. As bibliotecas de executor em massa no Azure Cosmos DB foram concebidas para explorar esta capacidade exclusiva do Azure Cosmos DB e proporcionar um desempenho ideal. Para obter mais informações, veja Introdução ao suporte em massa no SDK .NET.

Neste tutorial, vai aprender a utilizar a biblioteca do executor em massa do Azure Cosmos DB para importar e atualizar objetos de grafos para um contentor do Azure Cosmos DB para Gremlin. Durante este processo, vai utilizar a biblioteca para criar objetos de vértice e edge programaticamente e, em seguida, inserir múltiplos objetos por pedido de rede.

Em vez de enviar consultas do Gremlin para uma base de dados, onde os comandos são avaliados e executados um de cada vez, utilize a biblioteca do executor em massa para criar e validar os objetos localmente. Depois de a biblioteca inicializar os objetos de grafos, permite-lhe enviá-los para o serviço de base de dados sequencialmente.

Ao utilizar este método, pode aumentar as velocidades de ingestão de dados até uma centena de vezes, o que o torna uma forma ideal de realizar migrações de dados iniciais ou operações periódicas de movimento de dados.

A biblioteca do executor em massa vem agora nas seguintes variedades.

.NET

Pré-requisitos

Antes de começar, certifique-se de que tem o seguinte:

Clone

Para utilizar este exemplo, execute o seguinte comando:

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

Para obter o exemplo, aceda a .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Sample


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);

Executar

Modifique os parâmetros, conforme descrito na tabela seguinte:

Parâmetro Description
ConnectionString A cadeia de ligação de serviço, que encontrará na secção Chaves da sua conta do Azure Cosmos DB para Gremlin. Está formatado como AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Os nomes da base de dados de destino e do contentor.
DocumentsToInsert O número de documentos a serem gerados (relevantes apenas para dados sintéticos).
PartitionKey Garante que uma chave de partição é especificada com cada documento durante a ingestão de dados.
NumberOfRUs Só é relevante se um contentor ainda não existir e precisar de ser criado durante a execução.

Transfira a aplicação de exemplo completa no .NET.

Java

Utilização de exemplo

A aplicação de exemplo seguinte ilustra como utilizar o pacote GraphBulkExecutor. Os exemplos utilizam as anotações de objetos de domínio ou os objetos POJO (objeto Java antigo simples) diretamente. Recomendamos que experimente ambas as abordagens para determinar qual melhor satisfaz as suas exigências de implementação e desempenho.

Clone

Para utilizar o exemplo, execute o seguinte comando:

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

Para obter o exemplo, aceda a .\azure-cosmos-graph-bulk-executor\java\.

Pré-requisitos

Para executar este exemplo, tem de ter o seguinte software:

  • OpenJDK 11
  • Maven
  • Uma conta do Azure Cosmos DB configurada para utilizar a API do Gremlin

Sample

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);
    }

Configuração

Para executar o exemplo, veja a seguinte configuração e modifique-a conforme necessário.

O ficheiro /resources/application.properties define os dados necessários para configurar o Azure Cosmos DB. Os valores necessários estão descritos na tabela seguinte:

Propriedade Descrição
sample.sql.host O valor fornecido pelo Azure Cosmos DB. Certifique-se de que está a utilizar o URI do SDK .NET, que encontrará na secção Descrição geral da conta do Azure Cosmos DB.
sample.sql.key Pode obter a chave primária ou secundária na secção Chaves da conta do Azure Cosmos DB.
sample.sql.database.name O nome da base de dados na conta do Azure Cosmos DB para executar o exemplo. Se a base de dados não for encontrada, o código de exemplo cria-a.
sample.sql.container.name O nome do contentor na base de dados para executar o exemplo. Se o contentor não for encontrado, o código de exemplo cria-o.
sample.sql.partition.path Se precisar de criar o contentor, utilize este valor para definir o partitionKey caminho.
sample.sql.allow.throughput O contentor será atualizado para utilizar o valor de débito definido aqui. Se estiver a explorar várias opções de débito para satisfazer as suas exigências de desempenho, certifique-se de que repõe o débito no contentor quando terminar a exploração. Existem custos associados à saída do contentor aprovisionado com um débito mais elevado.

Executar

Depois de modificar a configuração de acordo com o seu ambiente, execute o seguinte comando:

mvn clean package

Para maior segurança, também pode executar os testes de integração ao alterar o skipIntegrationTests valor no ficheiro depom.xml para false.

Depois de executar os testes de unidades com êxito, pode executar o código de exemplo:

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

Executar o comando anterior executa o exemplo com um pequeno lote (1000 vértices e cerca de 5000 arestas). Utilize os argumentos da linha de comandos nas secções seguintes para ajustar os volumes que são executados e qual a versão de exemplo a executar.

Argumentos da linha de comandos

Estão disponíveis vários argumentos da linha de comandos enquanto executa este exemplo, conforme descrito na tabela seguinte:

Argumento Description
--vertexCount (-v) Indica à aplicação quantos vértices para gerar.
--edgeMax (-e) Indica à aplicação o número máximo de arestas a gerar para cada vértice. O gerador seleciona aleatoriamente um número de 1 para o valor fornecido.
--domainSample (-d) Indica à aplicação para executar o exemplo com as estruturas de domínio de pessoa e relação em vez de GraphBulkExecutors, GremlinVertexe GremlinEdge POJOs.
--createDocuments (-c) Indica à aplicação para utilizar create operações. Se o argumento não estiver presente, a aplicação tem a predefinição de utilizar upsert operações.

Informações detalhadas de exemplo

Vértice de pessoa

A classe de pessoa é um objeto de domínio simples que foi decorado com várias anotações para ajudar a transformar na GremlinVertex classe, conforme descrito na seguinte tabela:

Anotação de classe Description
GremlinVertex Utiliza o parâmetro opcional label para definir todos os vértices que criar com esta classe.
GremlinId Utilizado para definir que campo será utilizado como o ID valor. O nome do campo na classe de pessoa é ID, mas não é necessário.
GremlinProperty Utilizado no email campo para alterar o nome da propriedade quando está armazenada na base de dados.
GremlinPartitionKey Utilizado para definir o campo na classe que contém a chave de partição. O nome do campo que fornecer deve corresponder ao valor definido pelo caminho de partição no contentor.
GremlinIgnore Utilizado para excluir o isSpecial campo da propriedade que está a ser escrita na base de dados.

A classe RelationshipEdge

A RelationshipEdge classe é um objeto de domínio versátil. Ao utilizar a anotação da etiqueta ao nível do campo, pode criar uma coleção dinâmica de tipos de arestas, conforme mostrado na tabela seguinte:

Anotação de classe Description
GremlinEdge A GremlinEdge decoração na classe define o nome do campo para a chave de partição especificada. Quando cria um documento edge, o valor atribuído provém das informações do vértice de origem.
GremlinEdgeVertex São definidas duas instâncias de GremlinEdgeVertex , uma para cada lado da margem (origem e destino). O nosso exemplo tem o tipo de dados do campo como GremlinEdgeVertexInfo. As informações fornecidas pela GremlinEdgeVertex classe são necessárias para que o edge seja criado corretamente na base de dados. Outra opção seria fazer com que o tipo de dados dos vértices fosse uma classe que tenha sido decorada com as GremlinVertex anotações.
GremlinLabel O edge de exemplo utiliza um campo para definir o label valor. Permite a definição de várias etiquetas, uma vez que utiliza a mesma classe de domínio base.

Saída explicada

A consola termina a execução com uma cadeia JSON que descreve os tempos de execução do exemplo. A cadeia JSON contém as seguintes informações:

Cadeia de carateres JSON Description
startTime Quando System.nanoTime() o processo foi iniciado.
endTime O System.nanoTime() quando o processo foi concluído.
durationInNanoSeconds A diferença entre os endTime valores e startTime .
durationInMinutes O durationInNanoSeconds valor, convertido em minutos. O durationInMinutes valor é representado como um número flutuante, não como um valor de tempo. Por exemplo, um valor de 2,5 representa 2 minutos e 30 segundos.
vertexCount O volume de vértices gerados, que deve corresponder ao valor transmitido para a execução da linha de comandos.
edgeCount O volume de arestas geradas, que não é estática e é criada com um elemento de aleatoriedade.
Exceção Preenchido apenas se for emitida uma exceção quando tentar executar a execução.

Matriz estados

A matriz de estados dá informações sobre quanto tempo demora cada passo dentro da execução. Os passos estão descritos na seguinte tabela:

Passo de execução Description
Criar vértices de exemplo A quantidade de tempo que demora a fabricar o volume pedido de objetos pessoais.
Criar margens de exemplo A quantidade de tempo que demora a fabricar os objetos de relação.
Configurar base de dados A quantidade de tempo que demora a configurar a base de dados, com base nos valores fornecidos no application.properties.
Escrever documentos O tempo que demora a escrever os documentos na base de dados.

Cada estado contém os seguintes valores:

Valor de estado Description
stateName O nome do estado que está a ser comunicado.
startTime O System.nanoTime() valor quando o estado começou.
endTime O System.nanoTime() valor quando o estado foi concluído.
durationInNanoSeconds A diferença entre os endTime valores e startTime .
durationInMinutes O durationInNanoSeconds valor, convertido em minutos. O durationInMinutes valor é representado como um número flutuante, não como um valor de tempo. Por exemplo, um valor de 2,5 representa 2 minutos e 30 segundos.

Passos seguintes