Descripción general de las consultas de Spanner Graph

En este documento, se describe cómo consultar gráficos de propiedades en Spanner Graph. Los ejemplos de esta sección usan el esquema de gráfico que creaste en Configura y consulta Spanner Graph, que se ilustra en el siguiente diagrama:

Ejemplo de esquema de Spanner Graph.

Ejecuta una consulta de Spanner Graph

Puedes ejecutar consultas de Spanner Graph de las siguientes maneras:

Estructura de la consulta de Spanner Graph

En esta sección, se describe cada componente de la consulta en detalle.

En el siguiente ejemplo, se ilustra la estructura básica de una consulta de Spanner Graph.

Ejemplo de estructura de consulta de Spanner Graph.

Spanner Graph te permite crear varios gráficos dentro de una base de datos. La consulta comienza por especificar el grafo de destino, FinGraph, con la cláusula GRAPH.

Coincidencia de patrones de grafos

La coincidencia de patrones de gráficos encuentra patrones específicos dentro de tu gráfico. Los patrones más básicos son los patrones de elementos (patrones de nodos y patrones de aristas), que coinciden con los elementos del grafo (nodos y aristas, respectivamente). Los patrones de elementos se pueden componer en patrones de ruta y patrones más complejos.

Patrones de nodos

Un patrón de nodo es un patrón que coincide con los nodos de tu gráfico. Este patrón consiste en un par de paréntesis coincidentes, que de manera opcional puede contener una variable de patrón de gráfico, una expresión de etiqueta y filtros de propiedades.

Busca todos los nodos

La siguiente consulta muestra todos los nodos del grafo. La variable n, llamada variable de patrón de gráfico, se vincula a los nodos coincidentes. En este caso, el patrón de nodos coincide con todos los nodos del gráfico.

GRAPH FinGraph
MATCH (n)
RETURN LABELS(n) AS label, n.id;

Resultado

La consulta muestra label y id de la siguiente manera:

etiqueta id
Cuenta 7
Cuenta 16
Cuenta 20
Persona 1
Persona 2
Persona 3

Cómo encontrar todos los nodos con una etiqueta específica

La siguiente consulta coincide con todos los nodos del grafo que tienen la etiqueta Person. La consulta muestra las propiedades label, id y name de los nodos coincidentes.

GRAPH FinGraph
MATCH (p:Person)
RETURN LABELS(p) AS label, p.id, p.name;

Resultado

etiqueta id nombre
Persona 1 Alex
Persona 2 Dana
Persona 3 Lee

Busca todos los nodos que coincidan con una expresión de etiqueta

Puedes crear una expresión de etiqueta con uno o más operadores lógicos.

La siguiente consulta coincide con todos los nodos del grafo que tienen la etiqueta Person o Account. El conjunto de propiedades que expone la variable de patrón de gráfico n es el superconjunto de las propiedades que exponen los nodos que tienen la etiqueta Person o Account.

GRAPH FinGraph
MATCH (n:Person|Account)
RETURN LABELS(n) AS label, n.id, n.birthday, n.create_time;
  • En los resultados, todos los nodos tienen la propiedad id.
  • Los nodos que coinciden con la etiqueta Account tienen la propiedad create_time, pero no tienen la propiedad birthday. Se muestra un NULL para la propiedad birthday de esos nodos.
  • Los nodos que coinciden con la etiqueta Person tienen la propiedad birthday, pero no tienen la propiedad create_time. Se muestra un NULL para la propiedad create_time de esos nodos.

Resultado

etiqueta id birthday create_time
Cuenta 7 NULL 2020-01-10T14:22:20.222Z
Cuenta 16 NULL 2020-01-28T01:55:09.206Z
Cuenta 20 NULL 2020-02-18T13:44:20.655Z
Persona 1 1991-12-21T08:00:00Z NULL
Persona 2 1980-10-31T08:00:00Z NULL
Persona 3 1986-12-07T08:00:00Z NULL

Para obtener más información sobre las reglas de expresión de etiquetas, consulta Expresión de etiqueta.

Busca todos los nodos que coincidan con la expresión de etiqueta y el filtro de propiedad

La siguiente consulta coincide con todos los nodos del grafo que tienen la etiqueta Person y en los que la propiedad id es igual a 1.

GRAPH FinGraph
MATCH (p:Person {id: 1})
RETURN LABELS(p) AS label, p.id, p.name, p.birthday;

Resultado

etiqueta id nombre birthday
Persona 1 Alex 1991-12-21T08:00:00Z

Puedes usar la cláusula WHERE para crear condiciones de filtrado más complejas en las etiquetas y las propiedades.

La siguiente consulta coincide con todos los nodos del grafo que tienen la etiqueta Person y la propiedad birthday está antes de 1990-01-10.

GRAPH FinGraph
MATCH (p:Person WHERE p.birthday < '1990-01-10')
RETURN LABELS(p) AS label, p.name, p.birthday;

Resultado

etiqueta nombre birthday
Persona Dana 1980-10-31T08:00:00Z
Persona Lee 1986-12-07T08:00:00Z

Patrones de borde

Un patrón de arista coincide con aristas o relaciones entre nodos. Los patrones de aristas se encierran entre corchetes [] con los símbolos -, -> o <- para indicar direcciones.

Al igual que los patrones de nodos, las variables de patrones de gráfico se usan para vincularse a elementos de borde que coincidan.

Busca todos los bordes con etiquetas coincidentes

La siguiente consulta muestra todos los bordes del grafo que tienen la etiqueta Owns. La variable del patrón de grafo e está vinculada a los bordes coincidentes.

GRAPH FinGraph
MATCH -[e:Owns]->
RETURN e.id AS owner_id, e.account_id;

Resultado

owner_id account_id
1 7
3 16
2 20

Busca todos los bordes que coincidan con la expresión de etiqueta y el filtro de propiedad

Al igual que un patrón de nodo, un patrón de borde puede usar expresiones de etiqueta, especificación de propiedades y cláusulas WHERE, como se muestra en la siguiente consulta. La consulta encuentra todos los bordes etiquetados con Owns y tiene la propiedad create_time en un período especificado.

GRAPH FinGraph
MATCH -[e:Owns WHERE e.create_time > '2020-01-14'
                 AND e.create_time < '2020-05-14']->
RETURN e.id AS owner_id, e.create_time, e.account_id;

Resultado

owner_id create_time account_id
2 2020-01-28T01:55:09.206Z 20
3 2020-02-18T13:44:20.655Z 16

Busca todos los bordes con cualquier patrón de borde de dirección

Aunque todos los bordes del grafo de Spanner son dirigidos, puedes usar el patrón de borde any direction -[]- en una consulta para hacer coincidir los bordes en cualquier dirección.

La siguiente consulta encuentra todas las transferencias en las que está involucrada una cuenta bloqueada.

GRAPH FinGraph
MATCH (account:Account)-[transfer:Transfers]-(:Account)
WHERE account.is_blocked
RETURN transfer.order_number, transfer.amount;

Resultado

order_number cantidad
304330008004315 300
304120005529714 100
103650009791820 300
302290001255747 200

Patrones de ruta de acceso

Un patrón de ruta se crea a partir de patrones de nodos y bordes alternados.

Encuentra todas las rutas de un nodo con filtros de etiqueta y propiedad especificados mediante un patrón de ruta

La siguiente consulta encuentra todas las transferencias a una cuenta que se inició desde una cuenta que pertenece a Person con id igual a 2.

Cada resultado coincidente representa una ruta de Person {id: 2} a través de un Account conectado con el borde Owns a otro Account con el borde Transfers.

GRAPH FinGraph
MATCH
  (p:Person {id: 2})-[:Owns]->(account:Account)-[t:Transfers]->
  (to_account:Account)
RETURN
  p.id AS sender_id, account.id AS from_id, to_account.id AS to_id;

Resultado

sender_id from_id to_id
2 20 7
2 20 16

Patrones de ruta de acceso cuantificados

Un patrón cuantificado permite que un patrón se repita dentro de un rango especificado.

Cómo hacer coincidir un patrón de borde cuantificado

La siguiente consulta encuentra todas las cuentas de destino a una o tres transferencias de una Account de origen con id igual a 7, además de sí misma.

El patrón de borde con el sufijo del cuantificador {1, 3}

GRAPH FinGraph
MATCH (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account)
WHERE src != dst
RETURN src.id AS src_account_id, ARRAY_LENGTH(e) AS path_length, dst.id AS dst_account_id;

Resultado

src_account_id path_length dst_account_id
7 1 16
7 1 16
7 1 16
7 3 16
7 3 16
7 2 20
7 2 20

En el ejemplo anterior, se usa la función ARRAY_LENGTH para acceder a e de group variable. Para obtener más información, consulta variable de grupo de acceso.

Algunas filas de los resultados del ejemplo se repiten porque puede haber varias rutas entre el mismo par de cuentas de src y dst que coinciden con el patrón.

Coincidir con un patrón de ruta cuantificado

La siguiente consulta encuentra rutas entre nodos Account con uno o dos bordes Transfers a través de cuentas intermedias bloqueadas.

El patrón de ruta entre paréntesis se cuantifica y la cláusula WHERE se usa en los paréntesis para especificar las condiciones del patrón repetido.

GRAPH FinGraph
MATCH
  (src:Account)
  ((:Account)-[:Transfers]->(interm:Account) WHERE interm.is_blocked){1,2}
    -[:Transfers]->(dst:Account)
RETURN src.id AS src_account_id, dst.id AS dst_account_id;

Resultado

src_account_id dst_account_id
7 20
7 20
20 20

Cómo agrupar variables

Una variable de patrón de grafo declarada en un patrón cuantificado se considera una variable de grupo cuando se accede a ella fuera del patrón cuantificado y se vincula a un array de elementos de grafo coincidentes.

Puedes acceder a una variable de grupo como un array en el que se conservan los elementos del gráfico en el orden de aparición a lo largo de las rutas coincidentes. Puedes agregar una variable de grupo con la agregación horizontal.

Variable de grupo de acceso

En el siguiente ejemplo, se accede a la variable e de la siguiente manera:

  • Es una variable de patrón de gráfico vinculada a un solo borde en la cláusula WHERE e.amount > 100 (dentro del patrón cuantificado).
  • Es una variable de grupo vinculada a un array de elementos de borde en ARRAY_LENGTH(e) en la sentencia RETURN (fuera del patrón cuantificado).
  • Es una variable de grupo vinculada a un array de elementos de borde, que SUM(e.amount) agrega fuera del patrón cuantificado. Este es un ejemplo de agregación horizontal.
GRAPH FinGraph
MATCH
  (src:Account {id: 7})-[e:Transfers WHERE e.amount > 100]->{0,2}
  (dst:Account)
WHERE src.id != dst.id
LET total_amount = SUM(e.amount)
RETURN
  src.id AS src_account_id, ARRAY_LENGTH(e) AS path_length,
  total_amount, dst.id AS dst_account_id;

Resultado

src_account_id path_length total_amount dst_account_id
7 1 300 16
7 2 600 20

Rutas más cortas de cualquier tipo

Para limitar las rutas coincidentes en cada grupo de rutas que comparten los mismos nodos de origen y destino, puedes usar el prefijo de búsqueda de la ruta ANY o ANY SHORTEST. Solo puedes aplicar estos prefijos antes de un patrón de ruta completo y no puedes aplicarlos dentro de paréntesis.

Cómo hacer coincidencias con CUALQUIERA

En la siguiente consulta, se encuentran todas las cuentas únicas accesibles que están a una o dos Transfers de un nodo Account determinado.

El prefijo de búsqueda de ruta ANY garantiza que se devuelva solo una ruta entre un par único de nodos Account src y dst. En el siguiente ejemplo, aunque puedes llegar al nodo Account con {id: 16} en dos rutas diferentes desde el nodo Account de origen, los resultados solo incluyen una ruta.

GRAPH FinGraph
MATCH ANY (src:Account {id: 7})-[e:Transfers]->{1,2}(dst:Account)
LET ids_in_path = ARRAY(SELECT e.to_id FROM UNNEST(e) AS e)
RETURN src.id AS src_account_id, dst.id AS dst_account_id, ids_in_path;

Resultado

src_account_id dst_account_id ids_in_path
7 16 16
7 20 16,20

Patrones de gráficos

Un patrón de gráfico consta de uno o más patrones de ruta de acceso, separados por comas ,. Los patrones de grafos pueden contener una cláusula WHERE, que te permite acceder a todas las variables de patrones de grafos en los patrones de ruta para formar condiciones de filtrado. Cada patrón de ruta produce una colección de rutas.

Realiza coincidencias con un patrón de gráfico

La siguiente consulta identifica las cuentas intermediarias y sus propietarios involucrados en transacciones por un importe superior a 200, a través de las cuales se transfieren fondos de una cuenta de origen a una cuenta bloqueada.

Los siguientes patrones de ruta de acceso forman el patrón de grafo:

  • El primer patrón encuentra rutas en las que la transferencia se produce de una cuenta a una cuenta bloqueada con una cuenta intermedia.
  • El segundo patrón encuentra rutas de acceso de una cuenta a la persona propietaria.

La variable interm actúa como un vínculo común entre los dos patrones de ruta, lo que requiere que interm haga referencia al mismo nodo de elemento en ambos patrones de ruta. Esto crea una operación de unión equitativa basada en la variable interm.

GRAPH FinGraph
MATCH
  (src:Account)-[t1:Transfers]->(interm:Account)-[t2:Transfers]->(dst:Account),
  (interm)<-[:Owns]-(p:Person)
WHERE dst.is_blocked = TRUE AND t1.amount > 200 AND t2.amount > 200
RETURN
  src.id AS src_account_id, dst.id AS dst_account_id,
  interm.id AS interm_account_id, p.id AS owner_id;

Resultado

src_account_id dst_account_id interm_account_id owner_id
20 16 7 1

Sentencias de consulta lineal

Puedes encadenar varias instrucciones de gráfico para formar una instrucción de consulta lineal. Las instrucciones se ejecutan en el mismo orden en que aparecen en la consulta.

  • Cada sentencia toma el resultado de la sentencia anterior como entrada. La entrada está vacía para la primera sentencia.
  • El resultado de la última sentencia es el resultado final.

Cómo encontrar la transferencia máxima a una cuenta bloqueada

La siguiente consulta encuentra la cuenta y su propietario con la transferencia saliente más grande a una cuenta bloqueada.

GRAPH FinGraph
MATCH (src_account:Account)-[transfer:Transfers]->(dst_account:Account)
WHERE dst_account.is_blocked
ORDER BY transfer.amount DESC
LIMIT 1
MATCH (src_account:Account)<-[owns:Owns]-(owner:Person)
RETURN src_account.id AS account_id, owner.name AS owner_name;

En la siguiente tabla, se muestra cómo se pasan los resultados intermedios a las sentencias. Por brevedad, solo se muestran algunas propiedades de los resultados intermedios.

Declaración Resultado intermedio (abreviado)
MATCH
  (src_account:Account)
    -[transfer:Transfers]->
  (dst_account:Account)
WHERE dst_account.is_blocked
src_account transferir dst_account
{id: 7} {amount: 300.0} {id: 16, is_blocked: true}
{id: 7} {amount: 100.0} {id: 16, is_blocked: true}
{id: 20} {amount: 200.0} {id: 16, is_blocked: true}

ORDER BY transfer.amount DESC
src_account transferir dst_account
{id: 7} {amount: 300.0} {id: 16, is_blocked: true}
{id: 20} {amount: 200.0} {id: 16, is_blocked: true}
{id: 7} {amount: 100.0} {id: 16, is_blocked: true}

LIMIT 1
src_account transferir dst_account
{id: 7} {amount: 300.0} {id: 16, is_blocked: true}

MATCH
  (src_account:Account)
    <-[owns:Owns]-
  (owner:Person)
src_account transferir dst_account es propietario de owner
{id: 7} {amount: 300.0} {id: 16, is_blocked: true} {person_id: 1, account_id: 7} {id: 1, name: Alex}

RETURN
  src_account.id AS account_id,
  owner.name AS owner_name
account_id owner_name
7 Alex

Resultado

account_id owner_name
7 Alex

Sentencia return

La sentencia Return define qué mostrar de los patrones coincidentes. Puede acceder a las variables de patrones de gráfico, contener expresiones y otras cláusulas, como ORDER_BY y GROUP_BY. Consulta la sentencia RETURN.

Ten en cuenta que Spanner Graph no admite mostrar elementos de gráfico como resultados de la consulta. Para mostrar todo el elemento del gráfico, usa la función TO_JSON o la función SAFE_TO_JSON. De estas dos funciones, te recomendamos que uses SAFE_TO_JSON.

Muestra los elementos del gráfico como JSON

GRAPH FinGraph
MATCH (n:Account {id: 7})
-- Returning a graph element in the final results is NOT allowed. Instead, use
-- the TO_JSON function or explicitly return the graph element's properties.
RETURN TO_JSON(n) AS n;
GRAPH FinGraph
MATCH (n:Account {id: 7})
-- Certain fields in the graph elements, such as TOKENLIST, can't be returned
-- in the TO_JSON function. In those cases, use the SAFE_TO_JSON function instead.
RETURN SAFE_TO_JSON(n) AS n;

Resultado

n
{"identifier":"mUZpbkdyYXBoLkFjY291bnQAeJEO","kind":"node","labels":["Account"],"properties":{"create_time":"2020-01-10T14:22:20.222Z","id":7,"is_blocked":false,"nick_name":"Vacation Fund"}}

Cómo redactar consultas más grandes con la palabra clave NEXT

Puedes encadenar varias sentencias de consulta lineal de gráfico con la palabra clave NEXT. La entrada a la primera sentencia de consulta lineal está vacía. El resultado de cada instrucción de consulta lineal se convierte en la entrada de la siguiente instrucción de consulta lineal.

En el siguiente ejemplo, se encuentra el propietario de la cuenta con la mayor cantidad de transferencias entrantes encadenando varias sentencias lineales de gráfico. Ten en cuenta que puedes usar la misma variable, account en este ejemplo, para hacer referencia al mismo elemento de gráfico en varias sentencias lineales.

GRAPH FinGraph
MATCH (:Account)-[:Transfers]->(account:Account)
RETURN account, COUNT(*) AS num_incoming_transfers
GROUP BY account
ORDER BY num_incoming_transfers DESC
LIMIT 1

NEXT

MATCH (account:Account)<-[:Owns]-(owner:Person)
RETURN account.id AS account_id, owner.name AS owner_name, num_incoming_transfers;

Resultado

account_id owner_name num_incoming_transfers
16 Lee 3

Funciones y expresiones

Puedes usar todas las funciones (tanto funciones agregadas como escalares), operadores y expresiones condicionales de GoogleSQL en la consulta de Spanner Graph. Spanner Graph también admite funciones y operadores específicos del grafo.

Operadores y funciones integrados

Las siguientes funciones y operadores se usan comúnmente en GQL:

  • PROPERTY_EXISTS(n, birthday): Muestra si n expone la propiedad birthday.
  • LABELS(n): Muestra las etiquetas de n como se define en el esquema del grafo.
  • PROPERTY_NAMES(n): Muestra los nombres de las propiedades de n.
  • TO_JSON(n): Muestra n en formato JSON. Para obtener más información, consulta la función TO_JSON.

En la siguiente consulta, se ilustran el predicado PROPERTY_EXISTS, la función LABELS y la función TO_JSON, así como otras funciones integradas, como ARRAY_AGG y CONCAT.

GRAPH FinGraph
MATCH (person:Person)-[:Owns]->(account:Account)
RETURN person, ARRAY_AGG(account.nick_name) AS accounts
GROUP BY person

NEXT

RETURN
  LABELS(person) AS labels,
  TO_JSON(person) AS person,
  accounts,
  CONCAT(person.city, ", ", person.country) AS location,
  PROPERTY_EXISTS(person, is_blocked) AS is_blocked_property_exists,
  PROPERTY_EXISTS(person, name) AS name_property_exists
LIMIT 1;

Resultado

is_blocked_property_exists name_property_exists etiquetas cuentas ubicación persona
falso verdadero Persona ["Vacation Fund"] Adelaida, Australia {"identifier":"mUZpbkdyYXBoLlBlcnNvbgB4kQI=","kind":"node","labels":["Person"],"properties":{"birthday":"1991-12-21T08:00:00Z","city":"Adelaide","country":"Australia","id":1,"name":"Alex"}}

Subconsultas

Una subconsulta es una consulta anidada en otra. En la siguiente lista, se enumeran las reglas de subconsulta de Spanner Graph:

  • Una subconsulta se encierra entre un par de llaves {}.
  • Una subconsulta puede comenzar con la cláusula GRAPH inicial para especificar el graph en el alcance. No es necesario que el gráfico especificado sea el mismo que se usa en la consulta externa.
  • Cuando se omite la cláusula GRAPH en la subconsulta, ocurre lo siguiente:
    • El gráfico dentro del alcance se infiere del contexto de consulta externa más cercano.
    • La subconsulta debe comenzar con una sentencia de coincidencia de patrones de grafos con MATCH..
  • Una variable de patrón de gráfico declarada fuera del alcance de la subconsulta no se puede volver a declarar dentro de ella, pero se puede hacer referencia a ella en expresiones o funciones dentro de la subconsulta.

Usa una subconsulta para encontrar la cantidad total de transferencias de cada cuenta

En la siguiente consulta, se ilustra el uso de la subconsulta VALUE. La subconsulta está encerrada entre llaves {} con el prefijo de la palabra clave VALUE. La consulta muestra el importe total de las transferencias que se iniciaron desde una cuenta.

GRAPH FinGraph
MATCH (p:Person)-[:Owns]->(account:Account)
RETURN p.name, account.id AS account_id, VALUE {
  MATCH (a:Account)-[transfer:Transfers]->(:Account)
  WHERE a = account
  RETURN SUM(transfer.amount) AS total_transfer
} AS total_transfer;

Resultado

nombre account_id total_transfer
Alex 7 400
Dana 20 700
Lee 16 300

Para obtener una lista de las expresiones de subconsulta compatibles, consulta Subconsultas de Spanner Graph.

Parámetros de consulta

Puedes consultar Spanner Graph con parámetros. Para obtener más información, consulta la sintaxis y aprende a consultar datos con parámetros en las bibliotecas cliente de Spanner.

En la siguiente consulta, se ilustra el uso de los parámetros de consulta.

GRAPH FinGraph
MATCH (person:Person {id: @id})
RETURN person.name;

Consulta gráficos y tablas en conjunto

Puedes usar consultas de Graph junto con SQL para acceder a la información de tus gráficos y tablas en una sola sentencia.

GRAPH_TABLE

El operador GRAPH_TABLE toma una consulta de gráfico lineal y muestra su resultado en un formato tabular que se puede integrar sin problemas en una consulta de SQL. Esta interoperabilidad te permite enriquecer los resultados de las consultas de gráficos con contenido que no es de gráficos y viceversa.

Por ejemplo, puedes crear una tabla CreditReports e insertar algunos informes de crédito, como se muestra en el siguiente ejemplo:

CREATE TABLE CreditReports (
  person_id     INT64 NOT NULL,
  create_time   TIMESTAMP NOT NULL,
  score         INT64 NOT NULL,
) PRIMARY KEY (person_id, create_time);
INSERT INTO CreditReports (person_id, create_time, score)
VALUES
  (1,"2020-01-10 06:22:20.222", 700),
  (2,"2020-02-10 06:22:20.222", 800),
  (3,"2020-03-10 06:22:20.222", 750);

Luego, identifica a las personas de interés a través de la coincidencia de patrones de gráficos en GRAPH_TABLE y une los resultados de la consulta de gráfico con la tabla CreditReports para acceder a la puntuación de crédito.

SELECT
  gt.person.id,
  credit.score AS latest_credit_score
FROM GRAPH_TABLE(
  FinGraph
  MATCH (person:Person)-[:Owns]->(:Account)-[:Transfers]->(account:Account)
  WHERE account.is_blocked
  RETURN DISTINCT person
) AS gt
JOIN CreditReports AS credit
  ON gt.person.id = credit.person_id
ORDER BY credit.create_time;

Resultado:

person_id latest_credit_score
1 700
2 800

¿Qué sigue?

Conoce las prácticas recomendadas para ajustar las consultas.