Descripción general del esquema de Spanner Graph

Nota: Esta función está disponible en las ediciones Spanner Enterprise y Enterprise Plus. Para obtener más información, consulta la descripción general de las ediciones de Spanner.

Spanner Graph te permite modelar datos conectados como un gráfico de propiedades que representa la información como una red de nodos y aristas. Los nodos simbolizan entidades, y las aristas muestran las conexiones entre ellas. Los nodos y las aristas incluyen etiquetas que clasifican los tipos de nodos y aristas. Los nodos y las aristas también incluyen propiedades que los describen.

En este documento, se describe cómo definir un esquema de Spanner Graph mediante la asignación de filas de tablas a nodos y aristas de gráficos. También aprenderás a personalizar etiquetas y propiedades para nodos y aristas y a trabajar con dependencias de objetos de gráficos y esquemas.

Si deseas definiciones de gráficos más flexibles, consulta Administra datos sin esquema. Si quieres obtener información para usar vistas de SQL en lugar de tablas para definir nodos y aristas, consulta Descripción general de los gráficos creados a partir de vistas de SQL. Para obtener más información sobre Spanner Graph, consulta la descripción general de Spanner Graph.

Comprende el modelo de datos de gráficos de propiedades

Un gráfico de propiedades te permite modelar datos conectados. Representa la información como una red de nodos y aristas. Los nodos simbolizan entidades en tu panorama de datos, como clientes, productos o ubicaciones. Las aristas muestran las conexiones entre esos nodos, representando relaciones como comprado, sigue o ubicado en.

Tanto los nodos como las aristas pueden incluir la siguiente información:

• Etiquetas: Clasifican los nodos y los tipos de aristas. Si no defines explícitamente una etiqueta para un nodo o una arista, Spanner Graph usa el nombre de la tabla de entrada como la etiqueta predeterminada. Por ejemplo, Account podría ser una etiqueta.

• Propiedades: Se usan para describir nodos y aristas. Por ejemplo, un nodo Person podría tener una propiedad name con el valor Alex y una propiedad id con el valor 1.

En el ejemplo de la Figura 1, se muestra cómo puedes diseñar un gráfico para modelar actividades financieras. Este gráfico incluye los siguientes tipos de entidades modeladas como nodos:

• Person: Representa a una persona involucrada en transacciones financieras.
• Account: Representa una cuenta bancaria que se usa para las transacciones.

Estas entidades están conectadas por diferentes tipos de relaciones, que se representan con las siguientes aristas dirigidas:

• Owns: Una persona posee una o más cuentas.
• Transfers: El dinero se mueve de una cuenta a otra.

Cada arista dirigida indica una relación unidireccional que fluye de un nodo de origen a un nodo de destino. Por ejemplo, una arista Transfers conecta una Account de origen con una Account de destino, lo que indica el flujo de dinero.

Figura 1. Gráfico de ejemplo con varios nodos y aristas dirigidas.

Los nodos y las aristas incluyen información adicional en las propiedades.

• Los nodos Person incluyen estas propiedades:
  • name (STRING)
  • id (INT64)
• Las aristas Transfers incluyen esta propiedad:
  • amount (FLOAT64)

Aristas dirigidas y no dirigidas

El gráfico de ejemplo usa aristas dirigidas que indican una dirección específica en la relación entre entidades. Sin embargo, algunas relaciones, como la relación friend en una red social, no están dirigidas y representan una conexión recíproca sin un origen o extremo distinto. En este caso, puedes modelar aristas no dirigidas como dos aristas dirigidas, una en cada dirección.

Diseño de esquema de Spanner Graph

En Spanner Graph, usas la instrucción CREATE PROPERTY GRAPH para crear un gráfico a partir de tablas o vistas de SQL. Las tablas que se usan para crear gráficos se denominan tablas de entrada. En este documento, se muestra cómo usar tablas para crear un gráfico. Para obtener información sobre el uso de vistas de SQL, consulta Crea un Spanner Graph a partir de una vista de SQL.

Nota: Spanner Graph usa SQL/PGQ (consultas de gráficos de propiedades), que forma parte de los estándares SQL:2023.

Define un nodo a partir de una tabla

Para definir un nodo, agrega una definición de nodo en la cláusula NODE TABLES. La forma más simple de una definición de nodo contiene el nombre de una tabla de entrada que tiene referencias de nodos de origen y destino definidas. Spanner Graph asigna filas de la tabla de entrada a nodos de gráficos.

En el siguiente ejemplo, usas la cláusula NODE TABLES para definir el nodo Account en el gráfico de propiedades FinGraph. La definición de nodo contiene la tabla de entrada Account.

-- First, create an Account table.
CREATE TABLE Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
) PRIMARY KEY (id);

-- Next, use the Account table as input table of Account node definition.
CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Account
  );

Etiquetas y propiedades predeterminadas

Además de usar el nombre de la tabla de entrada como la etiqueta predeterminada, Spanner Graph expone todas las columnas de la tabla de entrada como propiedades de nodo.

En el ejemplo anterior,

• Cada nodo de cuenta usa la etiqueta Account.
• Cada nodo de cuenta incluye propiedades [id, create_time] de las columnas de la tabla Account.

Clave del elemento

Una definición de nodo también define la clave del elemento que identifica de forma única un nodo de gráfico.

• De forma predeterminada, la clave del elemento es la clave primaria de la tabla de entrada.
• Puedes usar la cláusula KEY para definir explícitamente las claves de los elementos.
• Puedes usar columnas con una restricción de índice único como claves de elementos.

En el siguiente ejemplo, se definen el nodo Account y el nodo Person.

• De forma predeterminada, el nodo Account usa la clave primaria de la tabla Account como su clave de elemento.
• Por otro lado, el nodo Person especifica explícitamente el id como la clave del elemento con la cláusula KEY.

CREATE TABLE Person (
  id           INT64 NOT NULL,
  name         STRING(MAX),
) PRIMARY KEY (id);

CREATE TABLE Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
) PRIMARY KEY (id);

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Person KEY (id),
    Account
  );

Asigna una fila en la tabla de entrada a un nodo en el gráfico

• Cada fila con una clave de elemento no nula se asigna a un nodo único en el gráfico, identificado por la clave del elemento.
• Se ignoran las filas con una clave de elemento nula.

Nota: La misma tabla de entrada se puede usar en varias definiciones de nodos. En este caso, una fila determinada de la tabla se asigna a nodos únicos (un nodo para cada una de esas definiciones de nodos).

Define una arista a partir de una tabla

Para definir una arista, agrega una definición de arista en la cláusula EDGE TABLES. La forma más simple de definición de arista contiene solo un nombre de tabla de entrada. Spanner Graph asigna filas de la tabla de entrada a aristas de gráficos.

• La etiqueta y las propiedades predeterminadas de las aristas se definen de la misma manera que los nodos.

• La clave del elemento de cada arista se define de la misma manera que los nodos.

Referencias de nodos de origen y destino

En el siguiente ejemplo, se crea un gráfico de propiedades FinGraph con lo siguiente:

• Nodos Person y Account
• Arista PersonOwnAccount

CREATE TABLE Person (
  id            INT64 NOT NULL,
  name          STRING(MAX),
) PRIMARY KEY (id);

CREATE TABLE Account (
  id            INT64 NOT NULL,
  create_time   TIMESTAMP,
) PRIMARY KEY (id);

CREATE TABLE PersonOwnAccount (
  id            INT64 NOT NULL,
  account_id    INT64 NOT NULL,
  create_time   TIMESTAMP,
  FOREIGN KEY (account_id) REFERENCES Account (id)
) PRIMARY KEY (id, account_id),
  INTERLEAVE IN PARENT Person;

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Person,
    Account
  )
  EDGE TABLES (
    PersonOwnAccount
      SOURCE KEY (id) REFERENCES Person (id)
      DESTINATION KEY (account_id) REFERENCES Account (id)
  );

Nota: En el DDL anterior, la tabla de aristas PersonOwnAccount usa la INTERLEAVE IN PARENT cláusula. El intercalado de tablas es una optimización de almacenamiento en Spanner que coloca las filas de la tabla secundaria (aristas) con las filas superiores (nodos de origen). Esta ubicación conjunta es fundamental para el rendimiento de las consultas de gráficos durante el recorrido de aristas. Para obtener más información, consulta Optimiza el recorrido de aristas.

Una definición de arista define la referencia de nodo de origen y destino con las cláusulas SOURCE KEY, DESTINATION KEY y REFERENCES. En el siguiente ejemplo, se usa la definición de arista de PersonOwnAccount para ilustrar este concepto:

EDGE TABLES (
  PersonOwnAccount
    SOURCE KEY (id) REFERENCES Person (id)
    DESTINATION KEY (account_id) REFERENCES Account (id)
)

Cada arista PersonOwnAccount conecta un Person (origen) con un nodo Account (destino).

• El nodo de origen de una arista es un nodo Person en el que el id es el mismo que el id de la arista.
• El nodo de destino de una arista es un nodo Account en el que el id es el mismo que el account_id de la arista.

Nota: Debes definir los nodos de origen y destino antes de usarlos en la definición de arista.

Además, lo siguiente es verdadero para la arista PersonOwnAccount:

• La clave del elemento es la clave primaria de la tabla PersonOwnAccount, es decir, (id, account_id).
• Cada arista tiene el mismo conjunto de propiedades que las columnas de la tabla PersonOwnAccount.
• Cada arista tiene la etiqueta PersonOwnAccount predeterminada.

Asigna una fila en una tabla de entrada de aristas a aristas en el gráfico

• Cada fila de la tabla de entrada de aristas, en la que la clave del elemento no es nula, suele asignarse a una arista única en el gráfico.
• Una fila puede corresponder a cero o más de una arista en el gráfico. Por ejemplo, esto ocurre cuando la referencia del nodo de origen coincide con cero o más nodos en la tabla de nodos de origen.

Define nodos y aristas dentro de una sola tabla

Puedes definir un nodo y sus aristas entrantes o salientes en una sola tabla si las columnas de la tabla definen una relación con otra tabla. Este enfoque reduce la cantidad de tablas, simplifica la administración de datos y puede mejorar el rendimiento de las consultas, ya que elimina la necesidad de una unión a una tabla de aristas separada.

Por ejemplo, si la siguiente tabla Account tiene una clave primaria compuesta (owner_id, account_id), la parte owner_id puede ser una clave externa que haga referencia a una tabla Person. Esta estructura permite que la tabla Account represente el nodo Account y la arista entrante del nodo Person.

  CREATE TABLE Person (
    id INT64 NOT NULL,
  ) PRIMARY KEY (id);

  -- Assume each account has exactly one owner.
  CREATE TABLE Account (
    owner_id INT64 NOT NULL,
    account_id INT64 NOT NULL,
    FOREIGN KEY (owner_id) REFERENCES Person(id)
  ) PRIMARY KEY (owner_id, account_id);

Puedes usar la tabla Account para definir el nodo Account y su arista Owns entrante. Esto se muestra en la siguiente instrucción CREATE PROPERTY GRAPH. En la cláusula EDGE TABLES, le das a la tabla Account el alias Owns. Esto se debe a que cada elemento del esquema de gráfico debe tener un nombre único.

  CREATE PROPERTY GRAPH FinGraph
    NODE TABLES (
      Person,
      Account
    )
    EDGE TABLES (
      Account AS Owns
        SOURCE KEY (owner_id) REFERENCES Person
        DESTINATION KEY (owner_id, account_id) REFERENCES Account
    );

Personaliza etiquetas y propiedades

Puedes usar las LABEL y PROPERTIES para personalizar etiquetas y propiedades.

En el siguiente ejemplo, se definen dos nodos: Person y Account.

• Los nodos Person usan la etiqueta Customer para exponer la propiedad address. La propiedad address se define con la expresión CONCAT(city, ", ", country), que hace referencia a las columnas city y country de la tabla de entrada Person.
• Para Account, el nodo Account usa la etiqueta Account para exponer las propiedades id y create_time.
• Person y Account tienen la etiqueta Entity con las propiedades [id, name].
  • Para Person, las propiedades id y name provienen de las columnas de la tabla de entrada.
  • Para Account, la propiedad name hace referencia a la columna nick_name de la tabla de entrada.

CREATE TABLE Person (
  id               INT64 NOT NULL,
  name             STRING(MAX),
  birthday         TIMESTAMP,
  country          STRING(MAX),
  city             STRING(MAX),
) PRIMARY KEY (id);

CREATE TABLE Account (
  id               INT64 NOT NULL,
  create_time      TIMESTAMP,
  is_blocked       BOOL,
  nick_name        STRING(MAX),
) PRIMARY KEY (id);

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Person KEY (id)
      LABEL Customer
        PROPERTIES (CONCAT(city, ", ", country) AS address)
      LABEL Entity PROPERTIES (id, name),
    Account KEY (id)
      LABEL Account PROPERTIES (id, create_time)
      LABEL Entity PROPERTIES (id, nick_name AS name)
  );

Coherencia de etiquetas y propiedades

En un gráfico, las etiquetas y las propiedades se identifican de forma única por sus nombres. Puedes usar etiquetas y propiedades con el mismo nombre en varias definiciones de nodos o aristas. Sin embargo, las etiquetas y las propiedades con el mismo nombre deben seguir estas reglas:

• Las propiedades con el mismo nombre usan el mismo tipo de valor.
• Las etiquetas con el mismo nombre exponen la misma lista de propiedades.

En el ejemplo anterior, la etiqueta Entity se define en los nodos Person y Account. Ambas definiciones incluyen el mismo conjunto de nombres de propiedades [id, name] con tipos de valores idénticos.

Dependencias entre gráficos y otros objetos de esquema

El gráfico creado por CREATE PROPERTY GRAPH depende de otros objetos de esquema, como las tablas de entrada de las definiciones de nodos y aristas, y las columnas de la tabla a las que hacen referencia las propiedades. Spanner Graph no permite un cambio de esquema que interrumpa una de estas dependencias.

La siguiente instrucción hace que FinGraph dependa de la tabla Account y de las columnas id y create_time.

CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Account PROPERTIES (id, create_time)
  );

En este ejemplo, Spanner Graph no permite los siguientes cambios de esquema:

• No puedes quitar la tabla Account. Para ello, debes quitar la definición de nodo Account. Para obtener más información, consulta Quita nodos o definiciones de aristas existentes.
• No puedes quitar las columnas create_time de la tabla Account. Para ello, debes quitar la propiedad create_time de la definición de nodo Account. Para obtener más información, consulta Actualiza nodos o definiciones de aristas existentes.

Sin embargo, puedes realizar los siguientes cambios de esquema:

• Modifica el esquema de la tabla Account y las columnas id y create_time si otros requisitos de esquema lo permiten. Para obtener más información, consulta Realiza actualizaciones de esquemas.

Visualiza un esquema

Puedes ver una visualización de esquema en Spanner Studio después de ejecutar una consulta de Spanner Graph. Para obtener más información, consulta Usa visualizaciones de Spanner Graph.

Administra datos sin esquema

Spanner Graph también admite la administración de datos sin esquema, lo que es útil cuando necesitas una definición de gráfico más flexible. Para obtener más información, consulta Administra datos sin esquema en Spanner Graph.

¿Qué sigue?

• Crea un esquema de Spanner Graph.
• Actualiza o borra un esquema de Spanner Graph.
• Administra datos sin esquema con Spanner Graph.
• Obtén información sobre las prácticas recomendadas para el diseño de esquemas de Spanner Graph.
• Obtén información sobre las prácticas recomendadas para ajustar las consultas de Spanner Graph.