Visão geral do esquema

Este documento explica os componentes de um esquema de gráfico de propriedades e mostra como criar e gerenciar um esquema de gráfico.

Os gráficos permitem modelar dados conectados que representam informações como uma rede de nós e arestas. Um esquema de gráfico consiste em nós e arestas, além de rótulos que classificam o tipo e propriedades que os descrevem. Você define um esquema de gráfico de propriedades mapeando linhas de tabelas de entrada para nós e arestas de gráfico e definindo rótulos e propriedades personalizados. Para saber mais sobre o BigQuery Graph, consulte a visão geral do BigQuery Graph.

Entender o modelo de dados do gráfico de propriedades

Um gráfico de propriedades permite modelar dados conectados como uma rede de nós e arestas. Os nós representam entidades nos seus dados, como clientes, produtos ou locais. As arestas representam conexões entre esses nós, capturando relações como compras, seguidores ou locais.

Os nós e as arestas podem incluir as seguintes informações:

  • Rótulos: classificam nós e tipos de arestas. Por exemplo, os alunos de uma classe podem ter um rótulo Student e um rótulo Person. Se você não definir explicitamente um rótulo para um nó ou uma aresta, o BigQuery Graph usará o nome da tabela de entrada como o rótulo padrão.

  • Propriedades: usadas para descrever nós e arestas. Por exemplo, um nó que representa uma pessoa pode ter uma propriedade name com o valor Alex e uma propriedade id com o valor 1.

O exemplo na Figura 1 mostra como você pode projetar um gráfico para modelar atividades financeiras. Esse gráfico inclui os seguintes tipos de entidades modeladas como nós:

  • Pessoa: representa um indivíduo envolvido em transações financeiras.
  • Conta: representa uma conta bancária usada para transações.

Essas entidades estão conectadas por diferentes tipos de relações, que são representadas pelas seguintes arestas direcionadas:

  • Possui: uma pessoa é proprietária de uma ou mais contas.
  • Transfers: o dinheiro se move de uma conta para outra.

Cada aresta direcionada indica uma relação unidirecional que flui de um nó de origem para um nó de destino. Por exemplo, uma aresta Transfers conecta uma Account de origem a uma Account de destino, indicando o fluxo de dinheiro.

Nós, arestas, rótulos e propriedades de um gráfico financeiro.

Figura 1. Exemplo de gráfico com vários nós e arestas direcionadas.

Os nós e as arestas incluem informações adicionais nas propriedades.

  • Os nós Person incluem estas propriedades:

    • name (STRING)
    • id (INT64)

  • As arestas Transfers incluem esta propriedade:

    • amount (FLOAT64)

Arestas direcionadas e não direcionadas

As arestas direcionadas indicam uma direção específica na relação entre entidades. Por exemplo, uma pessoa é proprietária de uma conta, mas uma conta não é proprietária de uma pessoa. No entanto, algumas relações, como a relação de amigo em uma rede social, são não direcionadas e representam uma conexão recíproca. Nesse caso, é possível modelar arestas não direcionadas como duas arestas direcionadas, uma em cada direção.

Projetar o esquema

O BigQuery Graph permite usar a CREATE PROPERTY GRAPH instrução para criar um gráfico de tabelas. As tabelas que criam gráficos são chamadas de tabelas de entrada.

Definir um nó

Os nós são definidos por linhas em tabelas. Para definir um nó, adicione uma definição de nó na NODE TABLES cláusula. A forma mais simples de uma definição de nó contém o nome de uma tabela de entrada com uma chave primária. O BigQuery Graph mapeia linhas da tabela de entrada para nós de gráfico.

No exemplo a seguir, você usa a cláusula NODE TABLES para definir o nó Account no gráfico de propriedades FinGraph. A definição de nó contém a tabela 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
  );

Por padrão, o BigQuery usa o nome da tabela como rótulo e expõe todas as colunas da tabela de entrada como propriedades.

  • Cada nó de conta usa o rótulo Account.
  • Cada nó de conta inclui propriedades id e create_time das colunas da tabela Account.

Chave do elemento

Uma definição de nó também define a chave do elemento, uma coleção de colunas que identifica exclusivamente um nó de gráfico. Por padrão, a chave do elemento é a chave primária da tabela de entrada. Como alternativa, é possível usar a cláusula KEY para definir explicitamente as chaves de elemento.

O exemplo a seguir define um nó Account e um nó Person. O nó Account usa a chave primária da tabela Account como chave de elemento. O nó Person especifica explicitamente a coluna id como a chave do elemento usando a 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 linha com uma chave de elemento não nula é mapeada para um nó exclusivo no gráfico identificado pela chave do elemento.
  • As linhas com uma chave de elemento nula são ignoradas.

A mesma tabela de entrada pode ser usada em várias definições de nó. Nesse caso, uma determinada linha na tabela de entrada é mapeada para um nó para cada definição de nó.

Definir uma aresta

As arestas são definidas por linhas em tabelas. Para definir uma aresta, adicione uma definição de aresta à EDGE TABLES cláusula. A forma mais simples de definição de aresta contém o nome de uma tabela de entrada e define referências de nó de origem e destino. O BigQuery Graph usa essa definição para mapear linhas da tabela de entrada para arestas de gráfico.

Por padrão, o BigQuery usa o nome da tabela como rótulo e expõe todas as colunas da tabela de entrada como propriedades.

Referências de nó de origem e destino

Uma definição de aresta define a referência de nó de origem e destino usando as cláusulas SOURCE KEY, DESTINATION KEY e REFERENCES. É necessário definir os nós de origem e destino antes de usá-los na definição de aresta.

No exemplo a seguir, você cria um gráfico de propriedades FinGraph com o seguinte:

  • Nós Person e Account
  • Aresta 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 aresta PersonOwnAccount conecta um nó Person (origem) a um nó Account (destino).

  • O nó de origem de uma aresta é um nó Person em que a propriedade id é a mesma que a propriedade id da aresta.
  • O nó de destino de uma aresta é um nó Account em que a propriedade id é a mesma que a propriedade account_id da aresta.
  • A chave do elemento é a chave primária da tabela PersonOwnAccount, ou seja, (id, account_id).
  • Cada aresta tem o mesmo conjunto de propriedades que as colunas da tabela PersonOwnAccount.
  • Cada aresta tem o rótulo PersonOwnAccount padrão.

Mapear linhas para arestas

Cada linha na tabela de entrada de aresta com uma chave de elemento não nula normalmente é mapeada para uma única aresta no gráfico. No entanto, se a referência do nó de origem ou destino corresponder a zero ou mais nós na tabela de nós de origem ou destino, a linha na tabela de entrada de aresta poderá resultar em zero ou várias arestas no gráfico.

Definir nós e arestas em uma única tabela

É possível definir um nó e as arestas de entrada ou saída em uma única tabela se as colunas da tabela definirem uma relação com outra tabela. Essa abordagem reduz o número de tabelas, simplifica o gerenciamento de dados e pode melhorar a performance da consulta, eliminando a necessidade de uma mesclagem em uma tabela de arestas separada.

Por exemplo, se a tabela Account a seguir tiver uma chave primária composta (owner_id, account_id), a coluna owner_id poderá ser uma chave externa que faz referência a uma tabela Person. Essa estrutura permite que a tabela Account represente o nó Account e a aresta de entrada do nó 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
);

É possível usar a tabela Account para definir o nó Account e a aresta Owns de entrada. Isso é mostrado na instrução CREATE PROPERTY GRAPH a seguir. Na cláusula EDGE TABLES, você atribui o alias Owns à tabela Account. Isso ocorre porque cada elemento no esquema de gráfico precisa ter um nome exclusivo.

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
  );

Personalizar rótulos e propriedades

É possível usar as LABEL e as PROPERTIES cláusulas para personalizar rótulos e propriedades.

O exemplo a seguir define um nó Person com uma propriedade personalizada e um nó Account com vários rótulos:

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)
      DEFAULT LABEL 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'])
      )
  );

  • Os nós Person usam o rótulo Customer para expor a propriedade address. A propriedade address é definida pela expressão CONCAT(city, ", ", country), que se refere à coluna city e country da tabela de entrada Person.

  • O nó Account usa o rótulo Account para expor as propriedades id e create_time.

Os nós Person e Account têm o rótulo Entity com as propriedades id e name.

  • No nó Person, as propriedades id e name vêm das colunas da tabela de entrada.
  • No nó Account, a propriedade name se refere à coluna nick_name da tabela de entrada.
  • No nó Account, a propriedade name usa a cláusula OPTIONS para fornecer uma descrição da propriedade e uma lista de sinônimos. Esses campos fornecem contexto e melhoram a capacidade de descoberta para interfaces de consulta de linguagem natural. Não é possível acessar esses campos diretamente nas consultas de gráfico, e eles não mudam os resultados da consulta de forma alguma.

Consistência de rótulos e propriedades

Em um gráfico, os rótulos e as propriedades são identificados exclusivamente pelos nomes. É possível usar rótulos e propriedades com o mesmo nome em várias definições de nó ou aresta. No entanto, os rótulos e as propriedades com o mesmo nome precisam seguir estas regras:

  • As propriedades com o mesmo nome precisam usar o mesmo tipo de valor.
  • Os rótulos com o mesmo nome precisam expor a mesma lista de propriedades.

No exemplo anterior, o rótulo Entity é definido nos nós Person e Account. Ambas as definições incluem o mesmo conjunto de nomes de propriedades, id e name, com tipos de valores idênticos.

Gerenciar dependências de esquema

Os gráficos dependem do esquema das tabelas de entrada para as definições de nó e aresta e das colunas de tabela referenciadas pelas propriedades. O BigQuery Graph não verifica se a exclusão ou alteração de tabelas ou colunas invalida um esquema de gráfico atual.

Você é responsável por evitar mudanças de esquema. Siga estas práticas recomendadas:

  • Antes de excluir uma tabela usada em uma definição de nó de gráfico, remova essa definição de nó do gráfico.
  • Antes de remover uma coluna de uma tabela que é exposta como uma propriedade em um gráfico, remova a propriedade da definição de nó ou aresta correspondente.

Visualizar esquemas de gráfico

Para conferir a instrução CREATE PROPERTY GRAPH usada para construir um gráfico atual, consulte a visualização INFORMATION_SCHEMA.PROPERTY_GRAPHS:

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

Substitua REGION pela região do conjunto de dados que contém o gráfico.

Como alternativa, é possível visualizar o esquema de gráfico em um notebook.

Atualizar um esquema de gráfico

Para fazer qualquer mudança no esquema de um gráfico atual, é necessário redefinir o esquema do gráfico usando a instrução CREATE PROPERTY GRAPH.

Excluir um esquema de gráfico

Para excluir um gráfico de propriedades, use a DROP PROPERTY GRAPH instrução.

Práticas recomendadas

As seções a seguir descrevem as práticas recomendadas para definir o esquema de gráfico e melhorar a performance da consulta de gráfico.

Definir o escopo das definições de propriedade

As propriedades são pares de chave-valor que fornecem informações adicionais anexadas a nós ou arestas. Recomendamos incluir apenas as propriedades necessárias em nós ou arestas e evitar o uso da sintaxe PROPERTIES ALL COLUMNS ou da sintaxe padrão que anexa todas as colunas das tabelas de nó ou aresta à lista de propriedades. Ter muitas propriedades em nós ou arestas pode causar verificações de coluna desnecessárias em consultas de gráfico, o que degrada a performance.

Para restringir as propriedades incluídas em uma definição de nó ou aresta, use a palavra-chave PROPERTIES ao definir as propriedades do elemento na instrução CREATE PROPERTY GRAPH.

A definição de tabela de nó a seguir restringe as propriedades da tabela de nós Person a id e name:

NODE TABLES (
  graph_db.Person PROPERTIES (id, name)
)

Definir restrições de chave primária e externa em nós e arestas de gráfico

O BigQuery pode usar restrições de chave primária e chave estrangeira nas tabelas de nó e aresta para otimizar as consultas de gráfico , reduzindo as verificações de tabela desnecessárias. No entanto, o BigQuery não aplica restrições de chave primária ou externa em tabelas. Se o aplicativo não puder garantir a integridade referencial ou a exclusividade nas chaves primárias, o uso de chaves primárias ou externas para otimização de consultas poderá levar a resultados incorretos.

O exemplo a seguir define restrições de chave primária e externa nas tabelas de nó Person e Account, e na tabela de arestas PersonOwnAccount:

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

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

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

A seguir