Suporte e compatibilidade de grafo do Azure Cosmos DB para Gremlin com recursos do TinkerPop

  • Artigo

APLICA-SE A: Gremlin

Azure Cosmos DB suporta a linguagem transversal de gráficos Apache Tinkerpop, conhecida como gráfica Gremlin. É possível usar a linguagem Gremlin para criar entidades de grafo (vértices e bordas), modificar propriedades dentro dessas entidades, executar consultas e passagens e excluir entidades.

O mecanismo de grafo do Azure Cosmos DB segue estreitamente a especificação de etapas de travessia do Apache TinkerPop, mas há diferenças na implementação que são específicas para o Azure Cosmos DB. Neste artigo, fornecemos instruções passo a passo rápidas do Gremlin e enumeramos os recursos do Gremlin compatíveis com a API para Gremlin.

Bibliotecas de cliente compatíveis

A tabela a seguir mostra drivers Gremlin populares que você pode usar com o BD Cosmos do Azure:

Baixar Fonte Introdução Versão do conector com suporte/recomendada
.NET Gremlin.NET no GitHub Criar Grafo usando .NET 3.4.13
Java Gremlin JavaDoc Criar Grafo usando Java 3.4.13
Python Gremlin-Python no GitHub Criar Grafo usando Python 3.4.13
Console do Gremlin Documentos do TinkerPop Criar Grafo usando Console do Gremlin 3.4.13
Node.js Gremlin-JavaScript no GitHub Criar Grafo usando Node.js 3.4.13
PHP Gremlin-PHP no GitHub Criar Grafo usando PHP 3.1.0
Linguagem Go Linguagem Go Essa biblioteca foi criada por colaboradores externos. A equipe do Azure Cosmos DB não oferece suporte nem manutenção à biblioteca.

Observação

As versões do driver do cliente Gremlin para 3.5.* e 3.6.* têm problemas de compatibilidade conhecidos, portanto, recomendamos usar as últimas versões do driver 3.4.* com suporte listadas acima. Essa tabela será atualizada quando os problemas de compatibilidade forem resolvidos nessas versões mais recentes do driver.

Suporte para objetos de gráficos

O TinkerPop é um padrão que abrange uma ampla variedade de tecnologias de grafo. Portanto, ele tem uma terminologia padrão para descrever quais recursos são fornecidos por um provedor de grafo. O Azure Cosmos DB fornece um banco de dados de grafo gravável, persistente e de alta simultaneidade que pode ser particionado em vários servidores ou clusters.

A tabela a seguir lista os recursos do TinkerPop que são implementados pelo BD Cosmos do Azure:

Categoria Implementação do BD Cosmos do Azure Observações
Recursos de grafo Fornece persistência e ConcurrentAccess. Projetado para dar suporte a Transactions Métodos de computador podem ser implementados por meio do conector Spark.
Recursos variáveis Dá suporte a Boolean, Integer, Byte, Double, Float, Long, String Dá suporte a tipos primitivos, é compatível com tipos complexos por meio do modelo de dados
Recursos do vértice Dá suporte a RemoveVertices, MetaProperties, AddVertices, MultiProperties, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Dá suporte à criação, modificação e exclusão de vértices
Recursos de propriedade do vértice StringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Dá suporte à criação, modificação e exclusão de propriedades do vértice
Recursos da borda AddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Dá suporte à criação, modificação e exclusão de bordas
Recursos de propriedade da borda Properties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Dá suporte à criação, modificação e exclusão de propriedades da borda

Formato de transmissão do Gremlin

O Azure Cosmos DB usa o formato JSON ao retornar resultados de operações do Gremlin. No momento, o Azure Cosmos DB é compatível com o formato JSON. Por exemplo, o snippet de código a seguir mostra uma representação em JSON de um vértice retornado ao cliente do Azure Cosmos DB:

  {
    "id": "a7111ba7-0ea1-43c9-b6b2-efc5e3aea4c0",
    "label": "person",
    "type": "vertex",
    "outE": {
      "knows": [
        {
          "id": "3ee53a60-c561-4c5e-9a9f-9c7924bc9aef",
          "inV": "04779300-1c8e-489d-9493-50fd1325a658"
        },
        {
          "id": "21984248-ee9e-43a8-a7f6-30642bc14609",
          "inV": "a8e3e741-2ef7-4c01-b7c8-199f8e43e3bc"
        }
      ]
    },
    "properties": {
      "firstName": [
        {
          "value": "Thomas"
        }
      ],
      "lastName": [
        {
          "value": "Andersen"
        }
      ],
      "age": [
        {
          "value": 45
        }
      ]
    }
  }

As propriedades usadas pelo formato JSON para vértices são descritas abaixo:

Propriedade Descrição
id A ID do vértice. Deve ser exclusiva (em combinação com o valor de _partition, se aplicável). Se nenhum valor for fornecido, ele será automaticamente fornecido com um GUID
label O rótulo do vértice. Esta propriedade é usada para descrever o tipo de entidade.
type Usado para distinguir vértices de documentos que não são grafos
properties Recipiente de propriedades definidas pelo usuário associadas ao vértice. Cada propriedade pode ter vários valores.
_partition A chave de partição do vértice. Usado para particionamento de gráfico.
outE Essa propriedade contém uma lista de bordas externas de um vértice. Armazenar as informações de adjacência com o vértice permite a execução rápida de passagens. As bordas são agrupadas com base em seus rótulos.

Cada propriedade pode armazenar diversos valores em uma matriz.

Propriedade Descrição
value O valor da propriedade

E a borda contém as seguintes informações para ajudar com a navegação para outras partes do grafo.

Propriedade Descrição
id A ID da borda. Deve ser exclusiva (em combinação com o valor de _partition, se aplicável)
label O rótulo da borda. Esta propriedade é opcional e é usada para descrever o tipo de relacionamento.
inV Ela contém uma lista nos vértices de uma borda. Armazenar as informações de adjacência com a borda permite a execução rápida das passagens. Os vértices são agrupados com base em seus rótulos.
properties Recipiente de propriedades definidas pelo usuário associadas à borda.

Etapas do Gremlin

Agora, vejamos as etapas do Gremlin com suporte do BD Cosmos do Azure. Para obter uma referência completa sobre o Gremlin, consulte Referência do TinkerPop.

Etapa Descrição Documentação do TinkerPop 3.2
addE Adiciona uma borda entre dois vértices Etapa addE
addV Adiciona um vértice ao grafo Etapa addV
and Garante que todas as passagens retornem um valor e uma etapa
as Um modulador de etapa para atribuir uma variável à saída de uma etapa Etapa as
by Um modulador de etapa usado com group e order Etapa by
coalesce Retorna a primeira passagem que retorna um resultado Etapa coalesce
constant Retorna um valor constante. Usada com coalesce Etapa constant
count Retorna a contagem da passagem Etapa count
dedup Retorna os valores com as duplicatas removidas Etapa dedup
drop Remove os valores (vértice/borda) Etapa drop
executionProfile Cria uma descrição de todas as operações gerada pela etapa executada Gremlin etapa executionProfile
fold Atua como uma barreira que calcula o valor agregado dos resultados Etapa fold
group Agrupa os valores com base nos rótulos especificados Etapa group
has Usada para filtrar propriedades, vértices e bordas. Dá suporte às variantes hasLabel, hasId, hasNot e has. Etapa has
inject Insere valores em um fluxo Etapa inject
is Usada para executar um filtro usando uma expressão booliana Etapa is
limit Usada para limitar o número de itens na passagem Etapa limit
local A etapa local encapsula uma seção de uma passagem, de forma semelhante a uma subconsulta Etapa local
not Usada para produzir a negação de um filtro Etapa not
optional Retorna o resultado da passagem especificada se ela produzir um resultado. Caso contrário, retorna o elemento de chamada Etapa optional
or Garante que pelo menos uma das passagens retorne um valor Etapa or
order Retorna os resultados na ordem de classificação especificada Etapa order
path Retorna o caminho completo da passagem Etapa path
project Projeta as propriedades como um mapa Etapa project
properties Retorna as propriedades para os rótulos especificados Etapa properties
range Filtra para o intervalo de valores especificado Etapa range
repeat Repete a etapa o número de vezes especificado. Usada para efetuar loop Etapa repeat
sample Usada para fazer a amostragem dos resultados da passagem Etapa sample
select Usada para projetar resultados da passagem Etapa select
store Usada para agregações sem bloqueio da passagem Etapa store
TextP.startingWith(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade com o início de uma determinada cadeia de caracteres Predicados TextP
TextP.endingWith(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade com o final de uma determinada cadeia de caracteres Predicados TextP
TextP.containing(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade com o conteúdo de uma determinada cadeia de caracteres Predicados TextP
TextP.notStartingWith(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade que não começa com uma determinada cadeia de caracteres Predicados TextP
TextP.notEndingWith(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade que não termina com uma determinada cadeia de caracteres Predicados TextP
TextP.notContaining(string) Função de filtragem de cadeia de caracteres. Essa função é usada como um predicado para a etapa has() para corresponder uma propriedade que não contém uma determinada cadeia de caracteres Predicados TextP
tree Agrega os caminhos de um vértice em uma árvore Etapa tree
unfold Desenrola um iterador como uma etapa Etapa unfold
union Mescla resultados de várias passagens Etapa union
V Inclui as etapas necessárias para passagens entre vértices e bordas V, E, out, in, both, outE, inE, bothE, outV, inV, bothV e otherV para Etapa vertex
where Usada para filtrar os resultados da passagem. Dá suporte aos operadores eq, neq, lt, lte, gt, gte e between Etapa where

O mecanismo otimizado para gravação do Azure Cosmos DB dá suporte à indexação automática de todas as propriedades dentro dos vértices e bordas por padrão. Sendo assim, consultas com filtros, consultas de intervalo, classificações ou agregações de qualquer propriedade são processadas no índice e atendidas de modo eficiente. Para obter mais informações sobre como a indexação funciona no BD Cosmos do Azure, consulte nosso artigo sobre Indexação independente do esquema.

Diferenças de comportamento

  • O mecanismo de grafo do Azure Cosmos DB executa a travessia do balanceamento em largura, enquanto o Gremlin do TinkerPop é de balanceamento em profundidade. Esse comportamento atinge um melhor desempenho no sistema escalonável horizontalmente como o Azure Cosmos DB.

Recursos sem suporte

  • Código de bytes do Gremlin é uma especificação independente da linguagem de programação para passagens de gráfico. O grafo do Azure Cosmos DB ainda não dá suporte a isso. Use GremlinClient.SubmitAsync() e envie a travessia como uma cadeia de caracteres de texto.

  • Não há suporte à definição da cardinalidade property(set, 'xyz', 1) no momento. Use property(list, 'xyz', 1) em seu lugar. Para saber mais, confira Propriedades de vértice com TinkerPop.

  • A match()etapa não está disponível no momento. Esta etapa fornece funcionalidades de consulta declarativa.

  • Não há suporte para objetos como propriedades nos vértices ou bordas. As propriedades somente podem ser tipos primitivos ou matrizes.

  • Não há suporte à classificação por propriedades de matriz order().by(<array property>) É possível classifica apenas por tipos primitivos.

  • Não há suporte a tipos JSON não primitivos. Use os tipos string, number ou true/false. Não há suporte para valores null.

  • No momento, não há suporte para o serializador GraphSONv3. Use as classes de Serializador, Leitor e Gravador GraphSONv2 na configuração de conexão. Os resultados retornados pelo Azure Cosmos DB para Gremlin não têm o mesmo formato que o formato GraphSON.

  • Atualmente, não há suporte para as expressões e funções lambda. Isso inclui as funções .map{<expression>}, .by{<expression>} e .filter{<expression>}. Para saber mais e aprender a reescrevê-las usando as etapas do Gremlin, confira Uma observação sobre Lambdas.

  • Não há suporte a Transações devido à natureza distribuída do sistema. Configure o modelo de consistência apropriado na conta do Gremlin para "ler as próprias gravações" e use a simultaneidade otimista para resolver as gravações conflitantes.

Limitações conhecidas

  • Utilização de índice para consultas do Gremlin com etapas de .V()meia travessia: No momento, somente a primeira chamada .V() de travessia usará o índice para resolver filtros ou predicados anexados a ela. As chamadas subsequentes não consultarão o índice, o que pode aumentar a latência e o custo da consulta.

Pressupondo a indexação padrão, uma consulta do Gremlin de leitura típica que começa com a etapa .V() usaria parâmetros nas etapas de filtragem anexadas, como .has() ou .where() para otimizar o custo e o desempenho da consulta. Por exemplo:

g.V().has('category', 'A')

No entanto, quando mais de uma etapa .V() é incluída na consulta do Gremlin, a resolução dos dados para a consulta pode não ser ideal. Use a seguinte consulta como um exemplo:

g.V().has('category', 'A').as('a').V().has('category', 'B').as('b').select('a', 'b')

Essa consulta retornará dois grupos de vértices com base na propriedade deles chamada category. Nesse caso, somente a primeira chamada, g.V().has('category', 'A'), fará uso do índice para resolver os vértices com base nos valores das propriedades deles.

Uma solução alternativa para essa consulta é usar etapas de subtravessia como .map() e union(). Isso é exemplificado abaixo:

// Query workaround using .map()
g.V().has('category', 'A').as('a').map(__.V().has('category', 'B')).as('b').select('a','b')

// Query workaround using .union()
g.V().has('category', 'A').fold().union(unfold(), __.V().has('category', 'B'))

Você pode examinar o desempenho das consultas usando a etapa executionProfile() do Gremlin.

Próximas etapas