Conformidade com os padrões do Gremlin no Amazon Neptune

As seções a seguir oferecem uma visão geral da implementação do Gremlin para o Neptune e como ela difere da implementação do Apache TinkerPop.

O Neptune implementa algumas etapas do Gremlin de forma nativa em seu mecanismo e usa a implementação do Apache TinkerPop Gremlin para processar outras (consulte Suporte nativo para etapas do Gremlin no Amazon Neptune).

Padrões aplicáveis para Gremlin

Variáveis e parâmetros em scripts

No que diz respeito às variáveis pré-vinculadas, o objeto de percurso g é pré-vinculado no Neptune, e o objeto graph não é compatível.

Embora o Neptune não seja compatível com variáveis do Gremlin nem com a parametrização em scripts, é possível encontrar exemplos de scripts para o Gremlin Server na Internet que contêm declarações de variáveis, como:

String query = "x = 1; g.V(x)";
List<Result> results = client.submit(query).all().get();

Também há muitos exemplos que usam parametrização (ou vinculações) ao enviar consultas, como:

Map<String,Object> params = new HashMap<>();
params.put("x",1);
String query = "g.V(x)";
List<Result> results = client.submit(query).all().get();

Os exemplos de parâmetro geralmente são associados a avisos sobre penalidades de desempenho por não parametrizar quando possível. Há muitos exemplos desse tipo para o TinkerPop que podem ser encontrados, e todos parecem bastante convincentes sobre a necessidade de parametrizar.

No entanto, tanto o atributo de declaração de variáveis quanto o de parametrização (junto com os avisos) só se aplicam ao Gremlin Server do TinkerPop quando ele está usando o GremlinGroovyScriptEngine. Eles não se aplicam quando o Gremlin Server usa a gramática gremlin-language ANTLR do Gremlin para analisar consultas. A gramática ANTLR não aceita declarações de variáveis nem parametrização, portanto, ao usar o ANTLR, você não precisa se preocupar em deixar de parametrizar. Como a gramática ANTLR é um componente mais novo do TinkerPop, o conteúdo antigo encontrado na Internet geralmente não reflete essa distinção.

O Neptune usa a gramática ANTLR no mecanismo de processamento de consultas em vez do GremlinGroovyScriptEngine, portanto, não é compatível com variáveis, parametrização nem com a propriedade bindings. Como resultado, os problemas relacionados à falha na parametrização não se aplicam ao Neptune. Usando o Neptune, é perfeitamente seguro simplesmente enviar a consulta como está, onde normalmente seria parametrizada. Como resultado, o exemplo anterior pode ser simplificado sem penalidades de desempenho da seguinte forma:

String query = "g.V(1)";
List<Result> results = client.submit(query).all().get();

Enumerações do TinkerPop

O Neptune não é compatível com nomes de classes totalmente qualificados para valores de enumeração. Por exemplo, você deve usar single e não org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality.single na solicitação do Groovy.

O tipo de enumeração é determinado pelo tipo do parâmetro.

A tabela a seguir mostra os valores de enumeração permitidos e o nome totalmente qualificado do TinkerPop relacionado.

Código Java

O Neptune não é compatível com chamadas para métodos definidos por chamadas arbitrárias do Java ou da biblioteca Java que não sejam as APIs do Gremlin compatíveis. Por exemplo java.lang.*, Date() e g.V().tryNext().orElseGet() não são permitidos.

Propriedades em elementos

O Neptune não é compatível com o sinalizador materializeProperties introduzido no TinkerPop 3.7.0 para retornar propriedades em elementos. Como resultado, o Neptune retornará somente vértices ou bordas como referências com somente seu id e label.

Execução do script

Todas as consultas devem começar com g, o objeto de percurso.

Em envios de consulta de string, é possível emitir vários percursos separados por ponto-e-vírgula (;) ou um caractere de nova linha (\n). Para ser executada, cada instrução que não seja a última deve terminar com uma etapa .iterate(). Somente os dados de percurso final são retornados. Isso não se aplica a envios de consulta GLV ByteCode.

Sessões

As sessões no Neptune se limitam a apenas dez minutos de duração. Consulte Sessões baseadas em script do Gremlin e a Referência de sessões TinkerPop para obter mais informações.

Transações

O Neptune abre uma nova transação no início de cada percurso do Gremlin e fecha a transação após a conclusão bem-sucedida do percurso. A operação é revertida quando há um erro.

Várias instruções separadas por um ponto-e-vírgula (;) ou um caractere de nova linha (\n) são incluídos em uma única transação. Cada instrução diferente da última deve terminar com uma etapa next() a ser executada. Somente os dados de percurso final são retornados.

A lógica da transação manual que usa tx.commit() e tx.rollback() não é compatível.

IDs de vértice e de borda

Os IDs de vértice e borda do Gremlin no Neptune devem ser do tipo String. Essas strings de ID são compatíveis com caracteres Unicode e não podem exceder 55 MB de tamanho.

Os IDs fornecidos pelo usuário são compatíveis, mas são opcionais em uso normal. Se você não fornecer um ID ao adicionar um vértice ou uma borda, o Neptune vai gerar um UUID e convertê-lo em uma string, da seguinte forma: "48af8178-50ce-971a-fc41-8c9a954cea62". Esses UUIDs não estão em conformidade com o padrão RFC, portanto, se você precisar de UUIDs padrão, deverá gerá-los externamente e fornecê-los ao adicionar vértices ou bordas.

IDs fornecidos pelo usuário

Os IDs fornecidos pelo usuário são permitidos no Gremlin do Neptune com as condições a seguir.

Para criar um novo vértice com um ID personalizado, use a etapa property com a palavra-chave id: g.addV().property(id, 'customid').

Todos os IDs de vértice devem ser exclusivos, e todos os IDs de presença devem ser exclusivos. O Neptune, no entanto, permite que um vértice e uma borda tenham o mesmo ID.

Se você tentar criar um novo vértice usando o g.addV() e já existir um vértice com esse ID, haverá falha na operação. A exceção para isso é que, se você especificar um novo rótulo para o vértice, a operação terá êxito, mas adiciona o novo rótulo e quaisquer propriedades adicionais especificadas ao vértice existente. Nada é substituído. Um novo vértice não é criado. O ID do vértice não altera e permanece exclusivo.

Por exemplo, os comandos a seguir do Gremlin Console serão bem-sucedidos:

gremlin> g.addV('label1').property(id, 'customid')
gremlin> g.addV('label2').property(id, 'customid')
gremlin> g.V('customid').label()
==>label1::label2

IDs de propriedades de vértice

Os IDs de propriedades de vértice são gerados automaticamente e podem ser exibidos como números positivos ou negativos quando consultados.

Cardinalidade de propriedades de vértice

O Neptune é compatível com a cardinalidade set e a cardinalidade single. Se não estiver especificado, a cardinalidade set será selecionada. Isso significa que, se você definir um valor para a propriedade, um novo valor será adicionado à propriedade, mas somente se ela ainda estiver exibida no conjunto de valores. Esse é o valor da enumeração do Gremlin de Set.

ListNão há suporte ao . Para obter mais informações sobre a cardinalidade da propriedade, consulte o tópico Vertex no JavaDoc do Gremlin.

Atualizar uma propriedade de vértice

Para atualizar o valor de uma propriedade sem adicionar mais um valor ao conjunto de valores, especifique cardinalidade single na etapa property.

g.V('exampleid01').property(single, 'age', 25)

Isso remove todos os valores existentes da propriedade.

Rótulos

O Neptune é compatível com vários rótulos para um vértice. Quando cria um rótulo, você pode especificar vários rótulos separados com ::. Por exemplo, g.addV("Label1::Label2::Label3") adiciona um vértice com três diferentes rótulos. A etapa hasLabel corresponde esse vértice com qualquer um destes três rótulos: hasLabel("Label1"), hasLabel("Label2") e hasLabel("Label3").

Caracteres de escape

O Neptune resolve todos os caracteres de escape, conforme descrito na seção Escaping Special Characters da documentação da linguagem Apache Groovy.

Limitações do Groovy

O Neptune não é compatível com comandos do Groovy que não começam com g. Isso inclui matemática (por exemplo: 1+1), chamadas do sistema (por exemplo: System.nanoTime()) e definições das variáveis (por exemplo: 1+1).

Serialização

O Neptune é compatível com as serializações a seguir com base no tipo MIME solicitado.

O Neptune expõe todos os serializadores que o TinkerPop faz, com suporte para as várias versões e configurações do GraphSON e do GraphBinary. Apesar de haver muitas opções presentes, a orientação sobre qual usar é simples:

Etapas do Lambda

O Neptune não é compatível com as etapas do Lambda.

Métodos do Gremlin não compatíveis

O Neptune não é compatível com os seguintes métodos do Gremlin:

Por exemplo, a seguinte travessia não é permitida: : g.V().addE('something').from(__.V().next()).to(__.V().next()).

Etapas do Gremlin não compatíveis

O Neptune não é compatível com as seguintes etapas de Gremlin:

Atributos do grafo do Gremlin no Neptune

A implementação do Gremlin no Neptune não expõe o objeto graph. As tabelas a seguir listam os atributos do Gremlin e indicam se o Neptune é compatível ou não com eles.

Compatibilidade do Neptune com atributos do graph

Os atributos de grafo do Neptune, quando compatíveis, são os mesmos que seriam gerados pelo comando graph.features().

Compatibilidade do Neptune com atributos de variável

Compatibilidade do Neptune com atributos do vértice

Compatibilidade do Neptune com atributos de propriedade do vértice

Compatibilidade do Neptune com atributos de borda

Compatibilidade do Neptune com atributos de propriedade de borda