Referência do Spanner Graph para usuários do openCypher

Neste documento, comparamos o openCypher e o gráfico do Spanner nos maneiras:

  • Terminologia
  • Modelo de dados
  • Esquema
  • Consulta
  • Mutação

Este documento pressupõe que você esteja familiarizado com openCypher v9 (link em inglês).

Antes de começar

Configure e consulte o Spanner Graph usando o console do Google Cloud.

Terminologia

openCypher Spanner Graph
nós nós
relacionamentos bordas
rótulos de nó rótulos de nó
tipos de relacionamento rótulos de borda
cláusulas O gráfico do Spanner usa o termo statement para uma unidade completa de execução, e clause para um modificador de instruções.

Por exemplo, MATCH é uma instrução, enquanto WHERE é uma cláusula.
exclusividade da relação

O openCypher não retorna resultados com arestas repetidas em uma única correspondência.		 Caminho TRAIL

Quando quiser exclusividade no Spanner Graph, usar Modo TRAIL para retornar bordas únicas em uma única correspondência.

Conformidade com os padrões

O Spanner Graph adota a ISO Graph Query Language (GQL) e os padrões SQL/Property Graph Queries (SQL/PGQ).

Modelo de dados

Tanto o Spanner Graph quanto o openCypher adotam o modelo de dados do gráfico de propriedades com algumas diferenças.

openCypher Spanner Graph
Cada relacionamento tem exatamente um tipo.
 Tanto os nós quanto as arestas têm um ou mais rótulos.

Esquema

openCypher Spanner Graph
Um gráfico não tem um esquema predefinido. Um esquema de gráfico precisa ser definido explicitamente usando a instrução CREATE PROPERTY GRAPH.
Os identificadores são definidos estaticamente no esquema. Para atualizar os rótulos, você precisa atualizar o esquema.
Para mais informações, consulte Criar, atualizar ou excluir um esquema do Spanner Graph.

Consulta

Os recursos de consulta do gráfico do Spanner são semelhantes aos do openCypher. As diferenças entre o Spanner Graph e o openCypher são descritas nesta seção.

Especificar o gráfico

No openCypher, há um gráfico padrão, e as consultas operam no gráfico. No gráfico do Spanner, é possível definir mais de um gráfico e uma consulta precisa começar com a cláusula GRAPH para especificar o gráfico a ser consultado. Exemplo:

   GRAPH FinGraph
   MATCH (p:Person)
   RETURN p.name
   ORDER BY p.name
   LIMIT 1;

Para mais informações, consulte a sintaxe de consulta do gráfico.

Correspondência de padrões de gráfico

O gráfico do Spanner dá suporte a recursos de correspondência de padrões de gráfico do openCypher. As diferenças são explicadas nas seções a seguir.

Exclusividade de relação e modo TRAIL

O openCypher não retorna resultados com arestas repetidas em uma única correspondência. Isso é chamado de exclusividade de relacionamento no openCypher. No Spanner Graph, as arestas repetidas são retornadas por padrão. Quando a exclusividade for desejada, use o modo TRAIL para garantir que não haja bordas repetidas na correspondência única. Para semântica detalhada de TRAIL e outros modos de caminho diferentes, consulte Modo de caminho.

O exemplo a seguir mostra como os resultados de uma consulta mudam com o modo TRAIL:

  • As consultas do modo openCypher e gráfico TRAIL do Spanner retornam vazias resultados, porque o único caminho possível é repetir t1 duas vezes.
  • Por padrão, a consulta do Spanner Graph retorna um caminho válido.

Exemplo de gráfico

openCypher Spanner Graph (modo TRAIL) Gráfico do Spanner (modo padrão) 
MATCH
  (src:Account)-[t1:Transfers]->
  (dst:Account)-[t2:Transfers]->
  (src)-[t1]->(dst)
WHERE src.id = 16
RETURN src.id AS src_id, dst.id AS dst_id;
      
GRAPH FinGraph
MATCH TRAIL
  (src:Account)-[t1:Transfers]->
  (dst:Account)-[t2:Transfers]->
  (src)-[t1]->(dst)
WHERE src.id = 16
RETURN src.id AS src_id, dst.id AS dst_id;
      
GRAPH FinGraph
MATCH
  (src:Account)-[t1:Transfers]->
  (dst:Account)-[t2:Transfers]->
  (src)-[t1]-> (dst)
WHERE src.id = 16
RETURN src.id AS src_id, dst.id AS dst_id;
Resultado vazio. Resultado vazio. Resultado:
src_id dst_id
16 20

Retornar elementos do gráfico como resultados da consulta

openCypher Spanner Graph 
MATCH (account:Account)
WHERE account.id = 16;
RETURN account;
 
GRAPH FinGraph
MATCH (account:Account)
WHERE account.id = 16;
RETURN TO_JSON(account) AS account;

No Spanner Graph, os resultados da consulta não retornam elementos de gráfico. Use a função TO_JSON para retornar elementos do gráfico como JSON.

Correspondência de padrões de comprimento variável e quantificação de padrões

A correspondência de padrões de comprimento variável no openCypher é chamada de quantificação de caminho no Spanner Graph. A quantificação do caminho usa uma sintaxe diferente, como mostrado no exemplo a seguir. Para mais informações, consulte Padrão de caminho quantificado.

openCypher Spanner Graph 
MATCH (src:Account)-[:Transfers*1..2]->(dst:Account)
WHERE src.id = 16
RETURN dst.id
ORDER BY dst.id;
     
GRAPH FinGraph
MATCH (src:Account)-[:Transfers]->{1,2}(dst:Account)
WHERE src.id = 16
RETURN dst.id
ORDER BY dst.id;

Padrão de comprimento variável: lista de elementos

O Spanner Graph permite acessar diretamente as variáveis usadas nas quantificações de caminho. No exemplo a seguir, e no gráfico do Spanner é o mesmo como edges(p) no openCypher.

openCypher Spanner Graph 
MATCH p=(src:Account)-[:Transfers*1..3]->(dst:Account)
WHERE src.id = 16
RETURN edges(p);
      
GRAPH FinGraph
MATCH (src:Account) -[e:Transfers]->{1,3} (dst:Account)
WHERE src.id = 16
RETURN TO_JSON(e) AS e;

Caminho mais curto

O openCypher tem duas funções integradas para encontrar o caminho mais curto entre nós: shortestPath e allShortestPath.

  • O shortestPath encontra um único caminho mais curto entre os nós.
  • allShortestPath encontra todos os caminhos mais curtos entre os nós. Não é possível ter vários caminhos do mesmo tamanho.

O gráfico do Spanner usa uma sintaxe diferente para encontrar um único caminho mais curto entre os nós: ANY SHORTEST para shortestPath. O allShortestPath não é compatível com o gráfico do Spanner.

openCypher Spanner Graph 
MATCH
  (src:Account {id: 7}),
  (dst:Account {id: 20}),
  p = shortestPath((src)-[*1..10]->(dst))
RETURN length(p) AS path_length;
      
GRAPH FinGraph
MATCH ANY SHORTEST
  (src:Account {id: 7})-[e:Transfers]->{1, 3}
  (dst:Account {id: 20})
RETURN ARRAY_LENGTH(e) AS path_length;

Instruções e cláusulas

A tabela a seguir lista as cláusulas openCypher e indica se elas têm suporte ou não no Spanner Graph.

openCypher Spanner Graph
MATCH Compatível. Para mais informações, consulte correspondência de padrão de gráfico.
OPTIONAL MATCH Compatível. Para mais informações, consulte Correspondência de padrões de gráfico.
RETURN / WITH Compatível. Para mais informações, consulte a instrução RETURN e WITH.
O Spanner Graph requer um alias explícito para expressões complicadas.

Compatível.		 
GRAPH FinGraph
MATCH (p:Person)
RETURN EXTRACT(YEAR FROM p.birthday) AS birthYear;

Não é compatível.		 
GRAPH FinGraph
MATCH (p:Person)
RETURN EXTRACT(YEAR FROM p.birthday); -- No aliasing
WHERE Compatível. Para obter mais informações, consulte a definição de padrão de gráfico.
ORDER BY Compatível. Para mais informações, consulte a instrução ORDER BY.
SKIP / LIMIT Compatível. Para mais informações, consulte a instrução SKIP e LIMIT.

O gráfico do Spanner requer uma expressão constante para o deslocamento e o limite.

Compatível.		 
GRAPH FinGraph
MATCH (n:Account)
RETURN n.id
SKIP @offsetParameter
LIMIT 3;

Não suportado.		 
GRAPH FinGraph
MATCH (n:Account)
RETURN n.id
LIMIT VALUE {
  MATCH (m:Person)
  RETURN COUNT(*) AS count
} AS count; -- Not a constant expression
UNION Compatível. Para mais informações, consulte Consulta de gráfico composto.
UNION ALL Compatível. Para mais informações, consulte Consulta de gráfico composto.
UNWIND Suporte para a instrução FOR. 
GRAPH FinGraph
LET arr = [1, 2, 3]
FOR num IN arr
RETURN num;
MANDATORY MATCH Incompatível.
CALL[YIELD...] Incompatível.
CREATE, DELETE, SET, REMOVE, MERGE Para saber mais, consulte a seção Mutação. e Inserir, atualizar ou excluir dados no gráfico do Spanner.

Tipos de dados

O gráfico do Spanner dá suporte a todos os tipos de dados do GoogleSQL. Para mais informações, consulte Tipos de dados no GoogleSQL.

As seções a seguir comparam os tipos de dados do openCypher com os dados do gráfico do Spanner tipos

Tipo estrutural

openCypher Spanner Graph
Nó Nó
Edge Edge
Caminho Incompatível.

Tipo de propriedade

openCypher Spanner Graph
INT INT64
FLOAT FLOAT64
STRING STRING
BOOLEAN BOOL
LIST
Uma lista homogênea de tipos simples.
Por exemplo, Lista de INT, Lista de STRING.
Não é possível misturar INT e STRING em uma única lista.		 ARRAY

Tipo composto

openCypher Spanner Graph
LIST ARRAY ou JSON
MAP STRUCT ou JSON

O Spanner Graph não oferece suporte a listas heterogêneas de tipos ou mapas de uma lista de chaves dinâmicas e tipos de valores de elementos heterogêneos. Usar JSON para esses casos de uso.

Coerção de tipo

openCypher Spanner Graph
INT -> FLOAT Compatível.

Para mais informações sobre as regras de conversão de tipo, consulte Regras de conversão no GoogleSQL.

Funções e expressões

Além das funções e expressões de gráfico, o Spanner Graph também é compatível com todas as funções e expressões integradas do GoogleSQL.

Para ver uma lista completa de funções e expressões, consulte Funções, operadores e condicionais do GoogleSQL.

Esta seção lista as funções e expressões do openCypher e os respectivos equivalentes no Spanner Graph.

Funções e expressões de tipo estrutural

Tipo Função ou expressão openCypher
 Gráfico do Spanner
função ou expressão

Nó e borda		 exists(n.prop) PROPERTY_EXISTS(n, prop)
id (retorna um número inteiro) Incompatível.
properties TO_JSON
keys
(nomes de tipos de propriedades, mas não valores de propriedades)		 PROPERTY_NAMES
labels LABELS
Edge endNode Incompatível.
startNode Incompatível.
type LABELS
Caminho length Incompatível.
nodes Incompatível.
relationships Incompatível.
Nó e borda .
property reference		 .
[]
dynamic property reference
MATCH (n)
RETURN n[n.name]

Incompatível.
Padrão como expressão size(pattern) Incompatível. Use uma subconsulta desta forma:
VALUE {
  MATCH pattern
  RETURN COUNT(*) AS count;
}

Funções e expressões de tipo de propriedade

Tipo Função ou expressão openCypher
 Função ou expressão
do Spanner Graph
Escalar coalesce COALESCE
head ARRAY_FIRST
last ARRAY_LAST
size(list) ARRAY_LENGTH
size(string) LENGTH
timestamp UNIX_MILLIS(CURRENT_TIMESTAMP())
toBoolean/toFloat/toInteger CAST(expr AS type)
Agregar avg AVG
collect ARRAY_AGG
count COUNT
max MAX
min MIN
percentileCont PERCENTILE_CONT
percentileDisc PERCENTILE_DISC
stDev STDDEV
stDevP Incompatível.
sum SUM
Lista range GENERATE_ARRAY
reverse ARRAY_REVERSE
tail O gráfico do Spanner não oferece suporte a tail.
Use ARRAY_SLICE e ARRAY_LENGTH como alternativa.
matemáticos abs ABS
ceil CEIL
floor FLOOR
rand RAND
round ROUND
sign SIGN
e EXP(1)
exp EXP
log LOG
log10 LOG10
sqrt SQRT
acos ACOS
asin ASIN
atan ATAN
atan2 ATAN2
cos COS
cot COT
degrees r * 90 / ASIN(1)
pi ACOS(-1)
radians d * ASIN(1) / 90
sin SIN
tan TAN
String left LEFT
ltrim LTRIM
replace REPLACE
reverse REVERSE
right RIGHT
rtrim RTRIM
split SPLIT
substring SUBSTR
tolower LOWER
tostring CAST(expr AS STRING)
toupper UPPER
trim TRIM
DISTINCT DISTINCT DISTINCT
Matemática + +
- -
* *
/ /
% MOD
^ POW
Comparação = =
<> <>
< <
> >
<= <=
>= >=
IS [NOT] NULL IS [NOT] NULL
Cadeia de comparação
a < b < c

Gráfico do Spanner não suporta uma cadeia de comparação. Isso é equivalente a comparações conjugadas com AND.
Exemplo: 

      a < b AND b < C

Booleano AND AND
OR OR
XOR
 O Spanner Graph não oferece suporte a XOR. Escreva a consulta com <>.

Por exemplo:
      boolean_1 <> boolean_2

NOT NOT
String STARTS WITH STARTS_WITH
ENDS WITH ENDS_WITH
CONTAINS REGEXP_CONTAINS
+ CONCAT
Lista + ARRAY_CONCAT
IN ARRAY_INCLUDES
[] []

Outras expressões

openCypher Spanner Graph
Expressão CASE: Compatível.
Subconsulta existente Compatível.
Projeção do mapa Incompatível.Os tipos
STRUCT oferecem funcionalidades semelhantes.
Compreensão de lista Incompatível.
GENERATE_ARRAY e ARRAY_TRANSFORM abrangem a maioria dos casos de uso.

Parâmetro de consulta

As consultas a seguir mostram a diferença entre o uso de parâmetros no openCypher e no Spanner Graph.

openCypher Spanner Graph
Parâmetro 
MATCH (n:Person)
WHERE n.id = $id
RETURN n.name;
 
GRAPH FinGraph
MATCH (n:Person)
WHERE n.id = @id
RETURN n.name;

Mutação

O gráfico do Spanner usa a DML do GoogleSQL para modificar as tabelas de entrada de nó e borda. Para mais informações, consulte Inserir, atualizar ou excluir dados do gráfico do Spanner.

Criar nó e borda

openCypher Spanner Graph
Criar nós e arestas 
CREATE (:Person {id: 100, name: 'John'});
CREATE (:Account {id: 1000, is_blocked: FALSE});


MATCH (p:Person {id: 100}),
      (a:Account {id: 1000})
CREATE (p)-[:Owns {create_time: timestamp()}]->(a);
 
INSERT INTO
Person (id, name)
VALUES (100, "John");


INSERT INTO
Account (id, is_blocked)
VALUES (1000, FALSE);


INSERT INTO PersonOwnAccount (id, account_id, create_time)
VALUES (100, 1000, CURRENT_TIMESTAMP());
Criar nós e bordas com resultados de consulta
 
MATCH (a:Account {id: 1}), (oa:Account)
WHERE oa <> a
CREATE (a)-[:Transfers {amount: 100, create_time: timestamp()}]->(oa);
 
INSERT INTO AccountTransferAccount(id, to_id, create_time, amount)
SELECT a.id, oa.id, CURRENT_TIMESTAMP(), 100
FROM GRAPH_TABLE(
  FinGraph
  MATCH
    (a:Account {id:1000}),
    (oa:Account)
  WHERE oa <> a
);

No Spanner Graph, os rótulos são atribuídos estaticamente de acordo com a instrução DDL CREATE PROPERTY GRAPH.

Atualizar nó e borda

openCypher Spanner Graph
Atualizar propriedades 
MATCH (p:Person {id: 100})
SET p.country = 'United States';
 
UPDATE Person AS p
SET p.country = 'United States'
WHERE p.id = 100;

Para atualizar os rótulos do gráfico do Spanner, consulte Criar, atualizar ou descartar um esquema de gráfico do Spanner.

Mesclar nó e borda

openCypher Spanner Graph
Inserir um novo elemento ou atualizar propriedades 
MERGE (p:Person {id: 100, country: 'United States'});
 
INSERT OR UPDATE INTO Person
(id, country)
VALUES (100, 'United States');

Excluir nó e borda

Excluir bordas é o mesmo que excluir a tabela de entrada.

openCypher Spanner Graph
Excluir nós e bordas 
MATCH (p:Person {id:100}), (a:Account {id:1000})
DELETE (p)-[:Owns]->(a);
 
DELETE PersonOwnAccount
WHERE id = 100 AND account_id = 1000;

A exclusão de nós exige o tratamento de possíveis bordas soltas. Quando DELETE CASCADE é especificado, DELETE remove as bordas associadas do nós como DETACH DELETE no openCypher. Para mais informações, consulte o Spanner visão geral do esquema.

openCypher Spanner Graph
Excluir nós e bordas associadas 
DETACH DELETE (:Account {id: 1000});
 
DELETE Account
WHERE id = 1000;

Retornar resultados de mutação

openCypher Spanner Graph
Retornar resultados após a inserção ou atualização 
MATCH (p:Person {id: 100})
SET p.country = 'United States'
RETURN p.id, p.name;
 
UPDATE Person AS p
SET p.country = 'United States'
WHERE p.id = 100
THEN RETURN id, name;
Retornar resultados após a exclusão 
DELETE (p:Person {id: 100})
RETURN p.country;
 
DELETE FROM Person
WHERE id = 100
THEN RETURN country;

A seguir