Visão geral do esquema

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: Para solicitar suporte ou enviar feedback sobre esse recurso, envie um e-mail para [e-mail].

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 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 turma 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 são conectadas por diferentes tipos de relações, que são representadas pelas seguintes arestas direcionadas:

• Owns: uma pessoa tem 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.

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

Os nós e as arestas incluem mais informações 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 tem uma conta, mas uma conta não tem 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 do 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 as 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.

Aviso: As chaves de elemento precisam ser exclusivas, mas o BigQuery não realiza nenhuma verificação de exclusividade. Você é responsável por garantir que as chaves de elemento sejam exclusivas. Caso contrário, as consultas de gráfico poderão retornar resultados incorretos.

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 de 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.

• A chave do elemento de cada aresta é definida da mesma forma que os nós.

Referências de nó de origem e destino

Uma definição de aresta define a referência do 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 junção a 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)
      LABEL Account PROPERTIES (id, create_time)
      LABEL Entity PROPERTIES (id, nick_name AS 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.

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 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.

A seguir

• Saiba mais sobre o BigQuery Graph.
• Aprenda a criar e consultar um gráfico de propriedades.
• Saiba mais sobre as práticas recomendadas de esquema de gráfico.