Compartilhar via

Início Rápido: biblioteca de clientes do Azure Cosmos DB para Apache Gremlin para Node.js

  • Aplica-se a: ✅ Apache Gremlin

Importante

Você está procurando uma solução de banco de dados para cenários de alta escala com um SLA (contrato de nível de serviço de disponibilidade) de 99,999%, dimensionamento automático instantâneo e failover automático em várias regiões? Considere o Azure Cosmos DB para NoSQL.

Você deseja implementar um grafo OLAP (processamento analítico online) ou migrar um aplicativo Apache Gremlin existente? Considere o Graph do Microsoft Fabric.

Introdução à biblioteca de clientes do Azure Cosmos DB para Apache Gremlin para Node.js para armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes Node.js, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

Código-fonte da biblioteca | Pacote (NPM)

Pré-requisitos

  • Uma assinatura do Azure

    • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
  • Node.js 22 ou mais recente

Configurando

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Gremlin. Depois que a conta for criada, crie o banco de dados e os recursos de grafo.

  1. Se você ainda não tiver um grupo de recursos de destino, use o az group create comando para criar um novo grupo de recursos em sua assinatura.

    az group create \
    --name "<resource-group-name>" \
    --location "<location>"

  2. Use o az cosmosdb create comando para criar uma nova conta do Azure Cosmos DB para Apache Gremlin com configurações padrão.

    az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableGremlin"

  3. Crie um novo banco de dados usando az cosmosdb gremlin database create nomeado cosmicworks.

    az cosmosdb gremlin database create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

  4. Use o az cosmosdb gremlin graph create comando para criar um novo grafo chamado products.

    az cosmosdb gremlin graph create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category"

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

  1. Use az cosmosdb show para obter o host da conta.

    az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{host:name}"

  2. Registre o valor da propriedade host da saída dos comandos anteriores. O valor dessa propriedade é o host que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

  3. Use az cosmosdb keys list para obter as chaves da conta.

    az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

  4. Registre o valor da propriedade primaryMasterKey da saída dos comandos anteriores. O valor dessa propriedade é a chave que você usará posteriormente neste guia para se conectar à conta com a biblioteca.

Prepare o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca de clientes. Esta etapa é o último pré-requisito necessário antes de passar para o restante deste guia.

  1. Iniciar em uma pasta vazia.

  2. Inicializar um novo módulo.

    npm init es6 --yes

  3. Instale o gremlin pacote do Gerenciador de Pacotes do Node (npm).

    npm install --save gremlin

  4. Crie o arquivo index.js .

  1. Iniciar em uma pasta vazia.

  2. Inicializar um novo módulo.

    npm init es6 --yes

  3. Instale o typescript pacote do Gerenciador de Pacotes do Node (npm).

    npm install --save-dev typescript

  4. Instale o tsx pacote a partir do npm.

    npm install --save-dev tsx

  5. Instale o gremlin pacote a partir do npm.

    npm install --save gremlin

  6. Instale o @types/node pacote a partir do npm.

    npm install --save-dev @types/node

  7. Instale o @types/gremlin pacote a partir do npm.

    npm install --save-dev @types/gremlin

  8. Inicialize o projeto TypeScript usando o compilador (tsc).

    npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

  9. Crie o arquivo index.ts .

Modelo de objeto

Descrição
DriverRemoteConnection Representa a conexão com o servidor Gremlin
GraphTraversalSource Usado para construir e executar travessias Gremlin

Exemplos de código

Autenticar cliente

Comece autenticando o cliente usando as credenciais coletadas anteriormente neste guia.

  1. Abra o arquivo index.js no IDE (ambiente de desenvolvimento integrado).

  2. Importe o gremlin pacote e os tipos necessários.

    import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

  3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis hostname e primaryKey.

    const hostname = '<host>';
const primaryKey = '<key>';

  4. Crie um objeto de tipo PlainTextSaslAuthenticator usando as credenciais e as variáveis de configuração criadas nas etapas anteriores. Armazene o objeto em uma variável chamada authenticator.

    const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);

  5. Crie um Client objeto usando a variável de autenticador. Dê o nome client à variável.

    const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

  1. Abra o arquivo index.ts no IDE (ambiente de desenvolvimento integrado).

  2. Importe o gremlin pacote e os tipos necessários.

    import gremlin from 'gremlin';
const { Client, auth } = gremlin.driver;
const { PlainTextSaslAuthenticator } = auth;

  3. Crie variáveis de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis hostname e primaryKey.

    const hostname: string = '<host>';
const primaryKey: string = '<key>';

  4. Crie um objeto de tipo PlainTextSaslAuthenticator usando as credenciais e as variáveis de configuração criadas nas etapas anteriores. Armazene o objeto em uma variável chamada authenticator.

    const authenticator = new PlainTextSaslAuthenticator(
    '/dbs/cosmicworks/colls/products',
    primaryKey
);

  5. Crie um Client objeto usando a variável de autenticador. Dê o nome client à variável.

    const client = new Client(
    `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
    {
        authenticator,
        traversalsource: 'g',
        rejectUnauthorized: true,
        mimeType: 'application/vnd.gremlin-v2.0+json'
    }
);

Inserir dados

Em seguida, insira novos dados de vértice e borda no grafo. Antes de criar os novos dados, desmarque o grafo de todos os dados existentes.

  1. Execute a g.V().drop() consulta para limpar todos os vértices e bordas do grafo.

    await client.submit('g.V().drop()');

  2. Crie uma consulta Gremlin que adicione um vértice.

    const insert_vertex_query = `
    g.addV('product')
        .property('id', prop_id)
        .property('name', prop_name)
        .property('category', prop_category)
        .property('quantity', prop_quantity)
        .property('price', prop_price)
        .property('clearance', prop_clearance)
`;

  3. Adicione um vértice para um único produto.

    await client.submit(insert_vertex_query, {
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    prop_name: 'Yamba Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 12,
    prop_price: 850.00,
    prop_clearance: false,
});

  4. Adicione mais dois vértices para dois produtos adicionais.

    await client.submit(insert_vertex_query, {
    prop_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_name: 'Montau Turtle Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 5,
    prop_price: 600.00,
    prop_clearance: true,
});

await client.submit(insert_vertex_query, {
    prop_id: 'cccccccc-2222-3333-4444-dddddddddddd',
    prop_name: 'Noosa Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 31,
    prop_price: 1100.00,
    prop_clearance: false,
});

  5. Crie outra consulta Gremlin que adicione uma aresta.

    const insert_edge_query = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

  6. Adicione duas bordas.

    await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
});

  1. Execute a g.V().drop() consulta para limpar todos os vértices e bordas do grafo.

    await client.submit('g.V().drop()');

  2. Crie uma consulta Gremlin que adicione um vértice.

    const insert_vertex_query: string = `
    g.addV('product')
        .property('id', prop_id)
        .property('name', prop_name)
        .property('category', prop_category)
        .property('quantity', prop_quantity)
        .property('price', prop_price)
        .property('clearance', prop_clearance)
`;

  3. Adicione um vértice para um único produto.

    await client.submit(insert_vertex_query, {
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    prop_name: 'Yamba Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 12,
    prop_price: 850.00,
    prop_clearance: false,
});

  4. Adicione mais dois vértices para dois produtos adicionais.

    await client.submit(insert_vertex_query, {
    prop_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_name: 'Montau Turtle Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 5,
    prop_price: 600.00,
    prop_clearance: true,
});

await client.submit(insert_vertex_query, {
    prop_id: 'cccccccc-2222-3333-4444-dddddddddddd',
    prop_name: 'Noosa Surfboard',
    prop_category: 'gear-surf-surfboards',
    prop_quantity: 31,
    prop_price: 1100.00,
    prop_clearance: false,
});

  5. Crie outra consulta Gremlin que adicione uma aresta.

    const insert_edge_query: string = `
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
`;

  6. Adicione duas bordas.

    await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

await client.submit(insert_edge_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
});

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente no grafo.

  1. Crie uma consulta que leia um vértice usando o identificador exclusivo e o valor da chave de partição.

    const read_vertex_query = 'g.V([prop_partition_key, prop_id])';

  2. Em seguida, leia um vértice fornecendo os parâmetros necessários.

    let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

  1. Crie uma consulta que leia um vértice usando o identificador exclusivo e o valor da chave de partição.

    const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';

  2. Em seguida, leia um vértice fornecendo os parâmetros necessários.

    let read_results = await client.submit(read_vertex_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
});

let matched_item = read_results._items[0];

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a uma passagem ou filtro específico no grafo.

  1. Crie uma consulta que encontre todos os vértices que partem de um vértice específico.

    const find_vertices_query = `
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
`;

  2. Execute a consulta especificando o Montau Turtle Surfboard produto.

    let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

  3. Percorrer os resultados da consulta.

    for (const item of find_results._items) {
    // Do something here with each result
}

  1. Crie uma consulta que encontre todos os vértices que partem de um vértice específico.

    const find_vertices_query: string = `
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
`;

  2. Execute a consulta especificando o Montau Turtle Surfboard produto.

    let find_results = await client.submit(find_vertices_query, {
    prop_partition_key: 'gear-surf-surfboards',
    prop_name: 'Montau Turtle Surfboard',
});

  3. Percorrer os resultados da consulta.

    for (const item of find_results._items) {
    // Do something here with each result
}

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

node index.js

npx tsx index.ts

Limpar os recursos

Quando você não precisar mais da conta, remova a conta de sua assinatura do Azure excluindo o recurso.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"
  • Last updated on