Descripción general del esquema

En este documento, se explican los componentes de un esquema de grafo de propiedades y se muestra cómo crear y administrar un esquema de grafo.

Los grafos te permiten modelar datos conectados que representan información como una red de nodos y aristas. Un esquema de grafo consta de nodos y aristas, junto con etiquetas que clasifican su tipo y propiedades que los describen. Para definir un esquema de grafo de propiedades, debes asignar filas de tablas de entrada a nodos y aristas del grafo, y definir etiquetas y propiedades personalizadas. Para obtener más información sobre BigQuery Graph, consulta la descripción general de BigQuery Graph.

Comprende el modelo de datos de grafo de propiedades

Un grafo de propiedades te permite modelar datos conectados como una red de nodos y aristas. Los nodos representan entidades en tus datos, como clientes, productos o ubicaciones. Las aristas representan conexiones entre esos nodos, capturando relaciones como compras, seguimientos o ubicaciones.

Los nodos y las aristas pueden incluir la siguiente información:

  • Etiquetas: clasifican los nodos y los tipos de aristas. Por ejemplo, los estudiantes de una clase pueden tener una etiqueta Student y una etiqueta Person. Si no defines explícitamente una etiqueta para un nodo o una arista, BigQuery Graph usa el nombre de la tabla de entrada como etiqueta predeterminada.

  • Propiedades: se usan para describir nodos y aristas. Por ejemplo, un nodo que representa a una persona puede 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 grafo para modelar actividades financieras. Este grafo incluye los siguientes tipos de entidades modeladas como nodos:

  • Persona: representa a una persona involucrada en transacciones financieras.
  • Cuenta: 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.
  • Transferencias: 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.

Nodos, aristas, etiquetas y propiedades de un grafo financiero.

Figura 1. Grafo 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

Las aristas dirigidas indican una dirección específica en la relación entre entidades. Por ejemplo, una persona posee una cuenta, pero una cuenta no posee a una persona. Sin embargo, algunas relaciones, como la relación de amistad en una red social, son no dirigidas y representan una conexión recíproca. En este caso, puedes modelar aristas no dirigidas como dos aristas dirigidas, una en cada dirección.

Diseña tu esquema

BigQuery Graph te permite usar la CREATE PROPERTY GRAPH instrucción para crear un grafo a partir de tablas. Las tablas que crean grafos se denominan tablas de entrada.

Define un nodo

Los nodos se definen por filas en tablas. Para definir un nodo, agrega una definición de nodo en la NODE TABLES cláusula. La forma más simple de una definición de nodo contiene el nombre de una tabla de entrada con una clave primaria. BigQuery Graph asigna filas de la tabla de entrada a nodos del grafo.

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

-- Create an Account table.
CREATE TABLE graph_db.Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

-- Use the Account table as the input table for the Account node definition.
CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Account
  );

De forma predeterminada, BigQuery usa el nombre de la tabla como etiqueta y expone todas las columnas de la tabla de entrada como propiedades.

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

Clave del elemento

Una definición de nodo también define la clave del elemento, una colección de columnas que identifica de forma única un nodo del grafo. De forma predeterminada, la clave del elemento es la clave primaria de la tabla de entrada. Como alternativa, puedes usar la cláusula KEY para definir explícitamente las claves del elemento.

En el siguiente ejemplo, se definen un nodo Account y un nodo Person. El nodo Account usa la clave primaria de la tabla Account como clave del elemento. El nodo Person especifica explícitamente la columna id como la clave del elemento mediante la cláusula KEY.

CREATE TABLE graph_db.Person (
  id           INT64 NOT NULL,
  name         STRING
);

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

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id),
    graph_db.Account
  );
  • Cada fila con una clave del elemento no nula se asigna a un nodo único en el grafo identificado por la clave del elemento.
  • Se ignoran las filas con una clave del elemento nula.

La misma tabla de entrada se puede usar en varias definiciones de nodos. En este caso, una fila determinada de la tabla de entrada se asigna a un nodo para cada definición de nodo.

Define una arista

Las aristas se definen por filas en tablas. Para definir una arista, agrega una definición de arista a la EDGE TABLES cláusula. La forma más simple de definición de conexión de integración contiene el nombre de una tabla de entrada y define referencias de nodos de origen y destino. BigQuery Graph usa esta definición para asignar filas de la tabla de entrada a aristas del grafo.

De forma predeterminada, BigQuery usa el nombre de la tabla como etiqueta y expone todas las columnas de la tabla de entrada como propiedades.

Referencias de nodos de origen y destino

Una definición de arista define la referencia de nodo de origen y destino mediante las cláusulas SOURCE KEY, DESTINATION KEY y REFERENCES. Debes definir los nodos de origen y destino antes de usarlos en la definición de arista.

En el siguiente ejemplo, se crea un grafo de propiedades FinGraph con lo siguiente:

  • Nodos Person y Account
  • Arista PersonOwnAccount
CREATE TABLE graph_db.Person (
  id            INT64 NOT NULL,
  name          STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

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

CREATE TABLE graph_db.PersonOwnAccount (
  id            INT64 NOT NULL,
  account_id    INT64 NOT NULL,
  create_time   TIMESTAMP,
  FOREIGN KEY (account_id) REFERENCES graph_db.Account (id) NOT ENFORCED,
  PRIMARY KEY (id, account_id) NOT ENFORCED
);

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

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

  • El nodo de origen de una arista es un nodo Person en el que la propiedad id es la misma que la propiedad id de la arista.
  • El nodo de destino de una arista es un nodo Account en el que la propiedad id es la misma que la propiedad account_id de la arista.
  • 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 filas a aristas

Cada fila de la tabla de entrada de aristas con una clave del elemento no nula suele asignarse a una sola arista en tu grafo. Sin embargo, si la referencia de nodo de origen o destino coincide con cero o más nodos en la tabla de nodos de origen o destino, la fila de la tabla de entrada de aristas podría generar cero o varias aristas en tu grafo.

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 columna owner_id puede ser una clave externa que haga referencia a una tabla Person. Esta estructura permite que la tabla Account represente tanto el nodo Account como la arista entrante del nodo Person.

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

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

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

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person,
    graph_db.Account
  )
  EDGE TABLES (
    graph_db.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 cláusulas para personalizar etiquetas y propiedades.

En el siguiente ejemplo, se define un nodo Person con una propiedad personalizada y un nodo Account con varias etiquetas:

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

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

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id)
      LABEL Customer
      PROPERTIES (CONCAT(city, ", ", country) AS address)
      LABEL Entity PROPERTIES (id, name),
    graph_db.Account KEY (id)
      LABEL Account OPTIONS(description = 'A checking or savings account')
      PROPERTIES (id, create_time)
      LABEL Entity
      PROPERTIES (
        id,
        nick_name AS name OPTIONS(description = 'A user-defined account name',
                                  synonyms = ['friendly name', 'display name'])
      )
  );

  • Los nodos Person usan la etiqueta Customer para exponer la propiedad address. La propiedad address se define mediante la expresión CONCAT(city, ", ", country), que hace referencia a las columnas city y country de la tabla de entrada Person.

  • El nodo Account usa la etiqueta Account para exponer las propiedades id y create_time.

Los nodos Person y Account tienen la etiqueta Entity con las propiedades id y name.

  • En el nodo Person, las propiedades id y name provienen de las columnas de la tabla de entrada.
  • En el nodo Account, la propiedad name hace referencia a la columna nick_name de la tabla de entrada.
  • En el nodo Account, la propiedad name usa la cláusula OPTIONS para proporcionar una descripción de la propiedad y una lista de sinónimos. Estos campos proporcionan contexto y mejoran la capacidad de descubrimiento para las interfaces de consulta de lenguaje natural. No puedes acceder a estos campos directamente en las consultas del grafo, y no cambian los resultados de la consulta de ninguna manera.

Coherencia de etiquetas y propiedades

En un grafo, 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 deben usar el mismo tipo de valor.
  • Las etiquetas con el mismo nombre deben exponer 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 y name, con tipos de valores idénticos.

Administra las dependencias del esquema

Los grafos dependen del esquema de las tablas de entrada para las definiciones de nodos y aristas, y de las columnas de la tabla a las que hacen referencia las propiedades. BigQuery Graph no verifica si borrar o modificar tablas o columnas invalida un esquema de grafo existente.

Eres responsable de evitar cambios en el esquema que lo interrumpan. Sigue estas prácticas recomendadas:

  • Antes de borrar una tabla que se usa en una definición de nodo del grafo, primero quita esa definición de nodo del grafo.
  • Antes de quitar una columna de una tabla que se expone como una propiedad en un grafo, quita la propiedad de la definición de nodo o arista correspondiente.

Visualiza esquemas de grafos

Para ver la instrucción CREATE PROPERTY GRAPH que se usó para construir un grafo existente, consulta la vista INFORMATION_SCHEMA.PROPERTY_GRAPHS:

SELECT
  property_graph_name,
  ddl
FROM
  `region-REGION`.INFORMATION_SCHEMA.PROPERTY_GRAPHS;

Reemplaza REGION por la región del conjunto de datos que contiene el grafo.

Como alternativa, puedes visualizar el esquema del grafo en un notebook.

Actualiza un esquema de grafo

Para realizar cualquier cambio en el esquema de un grafo existente, debes volver a definir el esquema del grafo con la instrucción CREATE PROPERTY GRAPH.

Borra un esquema de grafo

Para borrar un grafo de propiedades, usa la DROP PROPERTY GRAPH instrucción.

¿Qué sigue?