Guia de Início Rápido: Biblioteca cliente do Azure Cosmos DB para Apache Gremlin em Python

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

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

Pré-requisitos

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• Python 3.12 ou posterior

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.

Obter credenciais

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

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. Importe o gremlinpython pacote do PyPI (Índice de Pacotes do Python).

   pip install gremlinpython
   

3. Crie o arquivo app.py.

Modelo de objeto

Exemplos de código

• Autenticar cliente
• Inserir dados
• Ler dados
• Consultar dados

Autenticar cliente

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

1. Abra o arquivo app.py em seu IDE (ambiente de desenvolvimento integrado).

2. Importe os seguintes tipos da gremlin_python.driver biblioteca:

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

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

   hostname = "<host>"
   primary_key = "<key>"
   

4. Crie um Client objeto usando as credenciais e as variáveis de configuração criadas nas etapas anteriores. Dê o nome client à variável.

   client = client.Client(
       url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
       traversal_source="g",
       username="/dbs/cosmicworks/colls/products",
       password=f"{primary_key}",
       message_serializer=serializer.GraphSONSerializersV2d0()
   )
   

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.

   client.submit("g.V().drop()").all().result()
   

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

   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.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

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

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

5. Crie outra consulta Gremlin que adicione uma aresta.

   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.

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

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.

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

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

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

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.

   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.

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

3. Iterar sobre os resultados da consulta.

   for result in find_results:
       # Do something here with each result
   

Executar o código

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

python app.py

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>"

Próxima etapa