Visão geral do esquema

Observação: esse recurso pode não estar disponível ao usar reservas criadas com determinadas edições do BigQuery. Para mais informações sobre quais recursos estão ativados em cada edição, consulte Introdução às edições do BigQuery.

Neste documento, explicamos os componentes de um esquema de gráfico e mostramos 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 deles e propriedades que os descrevem. Para definir um esquema de gráfico, mapeie linhas de tabelas de entrada para nós e arestas de gráfico e defina 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 de gráfico

Um gráfico permite modelar dados conectados como uma rede de nós e bordas. 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 estudantes 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 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 relacionamentos, que são representados pelas seguintes arestas direcionadas:

• Proprietário: uma pessoa é proprietária de uma ou mais contas.
• Transferências: o dinheiro é transferido 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 origem Account a um destino Account, 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 bordas 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 as 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 amizade 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 instrução CREATE PROPERTY GRAPH para criar um gráfico com base em 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 nos seguintes tipos de tabelas ou visualizações:

• Tabelas padrão
• Tabelas externas
• Tabelas gerenciadas do Apache Iceberg
• Tabelas do catálogo REST do Lakehouse Iceberg
• Visualizações, incluindo as autorizadas
• Visualizações materializadas não incrementais

Para definir um nó, adicione uma definição de nó na cláusula NODE TABLES. 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 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, use 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 podem 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 é associada a 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 é associada a um nó para cada definição de nó.

Definir uma borda

As arestas são definidas por linhas nos seguintes tipos de tabelas ou visualizações:

• Tabelas padrão
• Tabelas externas
• Tabelas gerenciadas do Apache Iceberg
• Tabelas do catálogo REST do Lakehouse Iceberg
• Visualizações, incluindo as autorizadas
• Visualizações materializadas não incrementais

Para definir uma borda, adicione uma definição de borda à cláusula EDGE TABLES. A forma mais simples de definição de borda 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 as arestas do 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 de elemento de cada aresta é definida da mesma forma que os nós.

Referências de nós de origem e destino

Uma definição de borda 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 chamado FinGraph com os seguintes elementos:

• Nós Person e Account
• PersonOwnAccount aresta

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 borda PersonOwnAccount conecta um nó Person (origem) a um nó Account (destino).

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

Mapear linhas para arestas

Cada linha na tabela de entrada de arestas 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 de destino corresponder a zero ou mais nós na tabela de nós de origem ou de destino, a linha na tabela de entrada de arestas 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 dela definirem uma relação com outra tabela. Essa abordagem reduz o número de tabelas, simplifica o gerenciamento de dados e pode melhorar o desempenho da consulta, eliminando a necessidade de uma mesclagem com uma tabela de borda 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 borda 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 seguinte instrução CREATE PROPERTY GRAPH. Na cláusula EDGE TABLES, você atribui à tabela Account o alias Owns. Isso ocorre porque cada elemento no esquema do 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

Use as cláusulas LABEL e PROPERTIES 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'],
                                  extensions = [('data_classification', 'user'), ('currency', 'USD')])
      )
  );

• 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 às colunas 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, uma lista de sinônimos e uma lista de pares de chave-valor de metadados.

Especificar opções

É possível especificar metadados personalizados definidos pelo usuário na cláusula OPTIONS() de uma definição de rótulo ou propriedade, incluindo uma definição de medição. As seguintes opções são compatíveis:

• description: uma descrição de string legível por humanos do rótulo ou da propriedade.
• synonyms: uma matriz de strings que representa sinônimos do rótulo ou da propriedade.
• extensions: uma matriz de pares de strings (ARRAY<STRUCT<STRING, STRING>>) que representa metadados adicionais. É possível usar extensões para fornecer metadados, unidades ou regras de formatação personalizados, como [('currency', 'USD')].

Essas opções fornecem contexto e melhoram a facilidade de descoberta para interfaces de consulta em linguagem natural. Não é possível acessar esses campos diretamente nas consultas de gráfico, e eles não alteram os resultados da consulta GQL de forma alguma.

Consistência de rótulos e propriedades

Em um gráfico, os rótulos e as propriedades são identificados de forma exclusiva 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. As duas definições incluem o mesmo conjunto de nomes de propriedade, id e name, com tipos de valor 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 da 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 interruptivas no 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 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.

Ver esquemas de gráfico

Para ver a instrução CREATE PROPERTY GRAPH usada para construir um gráfico existente, 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 do gráfico em um notebook.

Atualizar um esquema de gráfico

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

Excluir um esquema de gráfico

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

Práticas recomendadas

As seções a seguir descrevem as práticas recomendadas para definir o esquema de gráfico para melhorar o desempenho 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ós ou arestas à 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 prejudica o desempenho.

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

A definição de tabela de nós 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áficos

O BigQuery pode usar restrições de chave primária e chave estrangeira nas tabelas de nós e de arestas 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 chaves externas para otimização de consultas poderá levar a resultados incorretos.

O exemplo a seguir define restrições de chave primária e chave estrangeira nas tabelas de nós Person e Account e na tabela de borda 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

• Saiba mais sobre o BigQuery Graph.
• Saiba como criar e consultar um gráfico.
• Saiba como escrever consultas de gráfico.
• Saiba mais sobre como criar gráficos com medições.