Partilhar via

Ingerir dados em massa no Azure Cosmos DB para Gremlin usando uma biblioteca de executores em massa

  • Artigo

APLICA-SE A: Gremlin

Os bancos de dados gráficos geralmente precisam ingerir dados em massa para atualizar um gráfico inteiro ou atualizar uma parte dele. O Azure Cosmos DB, um banco de dados distribuído e a espinha dorsal do Azure Cosmos DB para Gremlin, destina-se a ter um melhor desempenho quando as cargas são bem distribuídas. As bibliotecas de executores em massa no Azure Cosmos DB são projetadas para explorar esse recurso exclusivo do Azure Cosmos DB e fornecer desempenho ideal. Para obter mais informações, consulte Apresentando suporte em massa no SDK do .NET.

Neste tutorial, você aprenderá a usar a biblioteca de executores em massa do Azure Cosmos DB para importar e atualizar objetos gráficos em um contêiner do Azure Cosmos DB para Gremlin. Durante esse processo, você usa a biblioteca para criar objetos de vértice e borda programaticamente e, em seguida, inserir vários objetos por solicitação de rede.

Em vez de enviar consultas Gremlin para um banco de dados, onde os comandos são avaliados e, em seguida, executados um de cada vez, você usa a biblioteca de executores em massa para criar e validar os objetos localmente. Depois que a biblioteca inicializa os objetos gráficos, ela permite enviá-los para o serviço de banco de dados sequencialmente.

Usando esse método, você pode aumentar as velocidades de ingestão de dados até cem vezes, o que o torna uma maneira ideal de executar migrações iniciais de dados ou operações periódicas de movimentação de dados.

A biblioteca executor em massa agora vem nas seguintes variedades.

.NET

Pré-requisitos

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

  • Visual Studio 2019 com a carga de trabalho de desenvolvimento do Azure. Você pode começar a usar o Visual Studio 2019 Community Edition gratuitamente.

  • Uma subscrição do Azure. Se ainda não tiver uma subscrição, pode criar uma conta gratuita do Azure.

    Como alternativa, você pode criar uma conta gratuita do Azure Cosmos DB sem uma assinatura do Azure.

  • Um banco de dados do Azure Cosmos DB para Gremlin com uma coleção ilimitada. Para começar, vá para Azure Cosmos DB para Gremlin em .NET.

  • Git. Para começar, vá para a página de downloads do git.

Clone

Para usar esse exemplo, execute o seguinte comando:

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

Para obter a amostra, vá para .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Exemplo


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 a seguir:

Parâmetro Description
ConnectionString Sua cadeia de conexão de serviço, que você encontrará na seçã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 do banco de dados e do contêiner de destino.
DocumentsToInsert O número de documentos a gerar (relevante apenas para dados sintéticos).
PartitionKey Garante que uma chave de partição seja especificada com cada documento durante a ingestão de dados.
NumberOfRUs É relevante somente se um contêiner ainda não existir e precisar ser criado durante a execução.

Baixe o aplicativo de exemplo completo em .NET.

Java

Uso da amostra

O aplicativo de exemplo a seguir ilustra como usar o pacote GraphBulkExecutor. Os exemplos usam as anotações de objeto de domínio ou os objetos POJO (objeto Java antigo simples) diretamente. Recomendamos que você tente ambas as abordagens para determinar qual atende melhor às suas demandas de implementação e desempenho.

Clone

Para usar o exemplo, execute o seguinte comando:

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

Para obter a amostra, vá para .\azure-cosmos-graph-bulk-executor\java\.

Pré-requisitos

Para executar este exemplo, você precisa ter o seguinte software:

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

Exemplo

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, consulte a seguinte configuração e modifique-a conforme necessário.

O arquivo /resources/application.properties define os dados necessários para configurar o Azure Cosmos DB. Os valores necessários são descritos na tabela a seguir:

Property Description
sample.sql.host O valor fornecido pelo Azure Cosmos DB. Verifique se você está usando o URI do .NET SDK, que você encontrará na seção Visão geral da conta do Azure Cosmos DB.
sample.sql.key Você pode obter a chave primária ou secundária na seção Chaves da conta do Azure Cosmos DB.
sample.sql.database.name O nome do banco de dados na conta do Azure Cosmos DB para executar o exemplo. Se o banco de dados não for encontrado, o código de exemplo o criará.
sample.sql.container.name O nome do contêiner dentro do banco de dados para executar o exemplo. Se o contêiner não for encontrado, o código de exemplo o criará.
sample.sql.partition.path Se você precisar criar o contêiner, use esse valor para definir o partitionKey caminho.
sample.sql.allow.throughput O contêiner será atualizado para usar o valor de taxa de transferência definido aqui. Se você estiver explorando várias opções de taxa de transferência para atender às suas demandas de desempenho, certifique-se de redefinir a taxa de transferência no contêiner quando terminar a exploração. Há custos associados a deixar o contêiner provisionado com uma taxa de transferência mais alta.

Executar

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

mvn clean package

Para maior segurança, você também pode executar os testes de integração alterando o skipIntegrationTests valor no arquivo pom.xml para false.

Depois de executar os testes de unidade com êxito, você 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

A execução do comando anterior executa a amostra com um pequeno lote (1.000 vértices e aproximadamente 5.000 arestas). Use os argumentos de linha de comando nas seções a seguir para ajustar os volumes que são executados e qual versão de exemplo executar.

Argumentos de linha de comando

Vários argumentos de linha de comando estão disponíveis enquanto você executa este exemplo, conforme descrito na tabela a seguir:

Argumento Description
--vertexCount (-v) Informa ao aplicativo quantos vértices de pessoa gerar.
--edgeMax (-e) Informa ao aplicativo 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) Diz ao aplicativo para executar o exemplo usando as estruturas de domínio de pessoa e relacionamento em vez de , GraphBulkExecutorsGremlinVertex, e GremlinEdge POJOs.
--createDocuments (-c) Diz ao aplicativo para usar create operações. Se o argumento não estiver presente, o aplicativo assume como padrão o uso de upsert operações.

Informações de amostra detalhadas

Vertice da pessoa

A classe person é um objeto de domínio simples que foi decorado GremlinVertex com várias anotações para ajudar a uma transformação na classe, conforme descrito na tabela a seguir:

Anotação de classe Description
GremlinVertex Usa o parâmetro opcional label para definir todos os vértices que você cria usando essa classe.
GremlinId Usado para definir qual campo será usado como o ID valor. O nome do campo na classe person é ID, mas não é obrigatório.
GremlinProperty Usado no email campo para alterar o nome da propriedade quando ela é armazenada no banco de dados.
GremlinPartitionKey Usado para definir qual campo na classe contém a chave de partição. O nome do campo fornecido deve corresponder ao valor definido pelo caminho da partição no contêiner.
GremlinIgnore Usado para excluir o isSpecial campo da propriedade que está sendo gravada no banco de dados.

A classe RelationshipEdge

A RelationshipEdge classe é um objeto de domínio versátil. Usando a anotação de rótulo no nível de campo, você pode criar uma coleção dinâmica de tipos de borda, conforme mostrado na tabela a seguir:

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 você cria um documento de borda, o valor atribuído vem das informações de vértice de origem.
GremlinEdgeVertex Duas instâncias de GremlinEdgeVertex são definidas, uma para cada lado da borda (origem e destino). Nosso exemplo tem o tipo de dados do campo como GremlinEdgeVertexInfo. As informações fornecidas pela GremlinEdgeVertex classe são necessárias para que a borda seja criada corretamente no banco 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 A borda de exemplo usa um campo para definir o label valor. Ele permite que vários rótulos sejam definidos, porque usa a mesma classe de domínio base.

Saída explicada

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

Cadeia JSON Description
startTime O System.nanoTime() quando o processo começou.
endTime O System.nanoTime() quando o processo terminou.
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 que é passado para a execução da linha de comando.
edgeCount O volume de arestas geradas, que não é estático e é construído com um elemento de aleatoriedade.
exception Preenchido somente se uma exceção for lançada quando você tentar executar a execução.

Matriz de estados

A matriz de estados fornece informações sobre quanto tempo leva cada etapa dentro da execução. As etapas são descritas na tabela a seguir:

Etapa de execução Description
Construir vértices de amostra A quantidade de tempo que leva para fabricar o volume solicitado de objetos de pessoa.
Construir bordas de amostra A quantidade de tempo que leva para fabricar os objetos de relacionamento.
Configurar banco de dados O tempo necessário para configurar o banco de dados, com base nos valores fornecidos em application.properties.
Escrever documentos A quantidade de tempo que leva para gravar os documentos no banco de dados.

Cada estado contém os seguintes valores:

Valor do estado Description
stateName O nome do estado que está sendo relatado.
startTime O System.nanoTime() valor quando o estado começou.
endTime O System.nanoTime() valor quando o estado terminou.
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.

Próximos passos