Executar algoritmos do Spanner Graph

Este documento explica como executar algoritmos no Spanner Graph.

Estrutura de consulta de algoritmo do Spanner Graph

Uma consulta de algoritmo do Spanner Graph tem a seguinte estrutura:

EXPORT DATA OPTIONS (export_option_list) AS
GRAPH graph_name
match_clause
call_statement algorithm_name(common_input, algorithm_specific_input)
  YIELD algorithm_specific_output
RETURN results

  • export_option_list: opções que definem como manter os resultados da consulta do algoritmo. Consulte as opções do Cloud Storage e as opções do Spanner.

  • graph_name: o nome do gráfico.

  • match_clause: instruções MATCH opcionais para definir elementos de entrada do algoritmo.

  • call_statement: use a instrução CALL quando você omitir a variável match_clause e quiser operar em todo o gráfico. Use a instrução CALL PER() quando a variável match_clause estiver presente e você quiser operar na tabela de trabalho. Para mais informações, consulte GQL CALL.

  • algorithm_name: o nome do algoritmo a ser executado. Para conferir os algoritmos disponíveis, consulte Algoritmos do Spanner Graph.

  • common_input: parâmetros de entrada nomeados comuns a todas as consultas de algoritmo. Para mais informações, consulte parâmetros de entrada de algoritmo comuns.

  • algorithm_specific_input: parâmetros de entrada nomeados para o algoritmo. Para mais informações, consulte os parâmetros de entrada definidos em Algoritmos do Spanner Graph.

  • algorithm_specific_output: a saída da chamada do algoritmo. Para mais informações, consulte as saídas definidas em Algoritmos do Spanner Graph e a cláusula YIELD na instrução CALL.

  • results: define o que retornar nos resultados da consulta.

A consulta é composta por uma instrução EXPORT DATA, que define como persistir os resultados, e uma CLÁUSULA GRAPH que produz o resultado da consulta do algoritmo.

Na forma mais simples, a cláusula graph identifica o gráfico, usa uma instrução CALL para invocar um algoritmo que gera uma saída predefinida e, em seguida, usa uma instrução RETURN para especificar o que retornar da saída do algoritmo.

Como opção, a cláusula de gráfico pode usar instruções MATCH compatíveis para selecionar elementos de interesse. Nesse caso, use uma cláusula PER () para agrupar todas as linhas retornadas pela instrução MATCH como entrada para o algoritmo. O algoritmo opera em um subgráfico lógico composto pelo conjunto exclusivo de nós e arestas selecionados.

A consulta não retorna dados. A variável export_option_list determina como os resultados são mantidos.

Para mais informações sobre consultas de algoritmo de grafo do Spanner, consulte as seguintes seções neste documento:

Parâmetros de entrada de algoritmo comuns

Especifique esses parâmetros de entrada nomeados no seguinte formato: NAME => VALUE, ....

Nome Tipo de valor Obrigatório Valor padrão Descrição
node_labels ARRAY Não (nenhum) Só é compatível quando CALL é usado. Uma lista de rótulos de nós a serem incluídos na entrada do algoritmo. Se especificado, somente os nós com pelo menos um rótulo correspondente serão incluídos.
edge_labels ARRAY Não (nenhum) Só é compatível quando CALL é usado. Uma lista de rótulos de borda para incluir na entrada do algoritmo. Se especificado, somente as bordas com pelo menos um rótulo correspondente serão incluídas.
edge_weight_property STRING Não (nenhum) O nome da propriedade de aresta que contém os pesos. Se não for definido, o sistema vai atribuir um peso padrão de 1 a todas as arestas. O tipo de valor da propriedade precisa ser numérico.
machine_category STRING Não padrão A categoria de máquina a ser usada para a execução do algoritmo. Valores compatíveis: default, large
fallback_compute_region STRING Não (nenhum) A região de substituição em que a execução do algoritmo ocorre se a região de origem enfrentar restrições de capacidade. Precisa estar na mesma jurisdição que a região de origem da instância do Spanner (por exemplo, us-central1 se a região de origem for us-east1).
max_idle_time STRING Não 30min Especifica por quanto tempo a instância de computação deve permanecer ativa para reutilização após a conclusão do algoritmo. O formato é uma sequência de números decimais, cada um com um sufixo de unidade, como 4m, 1.5h ou 1h45m. As unidades de tempo válidas são ns, us (ou µs), ms, s, m, h.

Processar a saída do algoritmo

É preciso persistir os resultados da consulta do algoritmo antes de inspecioná-los. Use o export_data_option para descrever como manter os resultados. É possível manter os resultados no Cloud Storage ou na mesma instância do Spanner de onde a consulta foi originada.

Manter os resultados no Cloud Storage

Para usar essa opção, verifique se o papel Administrador de objetos do Storage (roles/storage.objectAdmin) foi concedido à conta de serviço do Spanner service-PROJECT_NUMBER@gcp-sa-spanner. gerenciada pelo Google.

As seguintes opções de EXPORT DATA são compatíveis ao persistir resultados no Cloud Storage. Especifique as opções no seguinte formato: NAME=VALUE, ....

Nome Tipo de valor Obrigatório Descrição
uri STRING Sim O URI de destino da exportação, no formato gs://bucket/path/file. Se você exportar uma grande quantidade de dados, use um caractere curinga em uri para exportar dados para vários arquivos. Por exemplo, gs://bucket/path/file_*.csv.
format STRING Sim O formato dos dados exportados. Valores compatíveis: CSV, PARQUET, AVRO.
header BOOL Não Se true, o sistema vai imprimir os cabeçalhos de coluna da primeira linha de cada arquivo de dados. O padrão é false. Válido apenas para CSV.
overwrite BOOL Não Se for true, o sistema vai substituir os arquivos existentes pelo mesmo URI. Caso contrário, se houver arquivos com o mesmo URI, a instrução retornará um erro. O padrão é false.
field_delimiter STRING Não O delimitador que separa os campos. Padrão: , (vírgula). Válido apenas para CSV.
compression STRING Não Especifica o formato de compactação. Se você não especificar um formato de compactação, os arquivos vão permanecer descompactados.
  • Para CSV, o valor compatível é GZIP.
  • Para PARQUET, os valores compatíveis são: SNAPPY, GZIP, ZSTD.
  • Para AVRO, os valores compatíveis são: DEFLATE, SNAPPY.

Os nomes de coluna na cláusula RETURN definem os nomes de coluna nos arquivos de saída do Cloud Storage.

Exportar dados para um ou mais arquivos

As consultas do Spanner Graph aceitam um único operador curinga (*) no uri. O caractere curinga pode aparecer no componente do nome de arquivo, mas não no nome do bucket, no nome da pasta ou na extensão de arquivo. O uso do operador curinga instrui o Spanner Graph a criar vários arquivos fragmentados com base no padrão fornecido se o conjunto de resultados for grande. O sistema substitui o operador curinga por um número, começando em zero, com preenchimento à esquerda para 12 dígitos. Por exemplo, um URI gs://my-bucket/file-*.csv cria arquivos como gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv e semelhantes.

Se você usar um uri sem caractere curinga, o resultado será um único arquivo, como gs://my-bucket/file.csv.

Tipos de dados

Ao exportar dados, os tipos de dados do Spanner Graph são convertidos da seguinte maneira, dependendo do formato:

CSV

Todos os tipos de dados são convertidos para a representação de string:

  • Os valores BOOL são convertidos em true ou false.
  • Valores BYTES codificados em base64.
  • Os valores TIMESTAMP são formatados como YYYY-MM-DD HH:MM:SS.ffffff UTC.
  • Os valores NULL aparecem como strings vazias.

Não é possível exportar dados aninhados e repetidos no formato CSV.

Avro

Tipo de dados do Spanner Tipo de dados Avro
BOOL BOOLEAN
INT64 LONG
FLOAT FLOAT
DOUBLE DOUBLE
NUMERIC BYTES com tipo lógico DECIMAL(38,9)
STRING STRING
BYTES BYTES
TIMESTAMP LONG (microssegundos desde a Era Unix)
NULL null

Parquet

Tipo de dados do Spanner Tipo de dados do Parquet
BOOL BOOLEAN
INT64 INT64
FLOAT FLOAT
DOUBLE DOUBLE
NUMERIC DECIMAL(38,9)
STRING STRING
BYTES BYTE_ARRAY
TIMESTAMP TIMESTAMP_MICROS
NULL null

Manter os resultados no Spanner

As seguintes opções de EXPORT DATA são compatíveis ao manter os resultados na instância de origem do Spanner. Especifique as opções no seguinte formato: NAME=VALUE, ....

Nome Tipo de valor Obrigatório Descrição
format STRING Sim O formato dos dados exportados. Precisa ser CLOUD_SPANNER.
table STRING Sim O nome da tabela de destino do Spanner em que os resultados serão gravados. Pode ser qualquer tabela na instância do Spanner.
write_mode STRING Sim O modo de gravação a ser usado. Os valores compatíveis são:
  • update_ignore_all: atualiza as linhas atuais na tabela de destino.
  • upsert_ignore_all: insere novas linhas ou atualiza as linhas existentes na tabela de destino.

Nos dois modos, o Spanner ignora qualquer registro que introduza uma violação de restrição (por exemplo, chaves ausentes em uma atualização, violação de índice exclusivo, violação de restrição de chave externa). No entanto, a gravação falha em erros de violação que não são de restrição (por exemplo, incompatibilidade de tipo de coluna, valores ausentes para colunas NOT NULL).

Requisitos

Ao persistir os resultados do algoritmo no Spanner, a consulta do algoritmo precisa atender aos seguintes requisitos:

  • A tabela de destino precisa existir.
  • As colunas precisam existir com um tipo correspondente: todos os nomes de coluna especificados na cláusula RETURN precisam já existir na tabela de destino com um tipo de dados correspondente. Use aliases para corresponder aos nomes das colunas da tabela de destino, se necessário. Exemplo: RETURN node.id AS person_id.
  • Inclua todas as colunas de chave primária: a cláusula RETURN precisa incluir todas as colunas de chave primária da tabela de destino.

Semântica de gravação

A persistência de resultados no Spanner é uma operação não transacional. Ele fornece atomicidade no nível da linha. Isso significa que o sistema grava todas as colunas da mesma linha ou não grava nenhuma delas. Ele segue a semântica do tipo "pelo menos uma vez". Isso significa que uma linha pode ser gravada várias vezes. A leitura da tabela de destino durante a execução pode gerar resultados incompletos.

Se a execução geral falhar, o sistema não vai reverter as mudanças que já foram confirmadas. O processo de gravação falha no primeiro erro não repetível. Quando ocorre uma falha de gravação, o ERROR_MESSAGE em GRAPH_OPERATION_EXECUTION_STATUS indica a chave primária da linha que falhou, junto com o motivo específico da falha.

O sistema grava os resultados do algoritmo de volta no Spanner Graph usando a prioridade MEDIUM.

Executar consultas de algoritmo de exemplo

Nesta seção, mostramos exemplos de consultas de algoritmo do Spanner Graph que podem ser executadas em uma instância de teste. Para uma lista completa de algoritmos compatíveis com o Spanner Graph, consulte Algoritmos do Spanner Graph.

Antes de começar

Para executar as consultas de exemplo do algoritmo do Spanner Graph, primeiro conclua o seguinte:

  1. Siga as instruções em Configurar e consultar o Spanner Graph para criar um Spanner Graph.
  2. Verifique se você tem as permissões necessárias.
  3. Opcional: aumente o esquema do Spanner Graph se você estiver mantendo a saída no Spanner.

Adicione uma nova coluna chamada page_rank à tabela Account. O Spanner grava os resultados do algoritmo nessa nova coluna. Em seguida, atualize a definição do gráfico para acessar page_rank como uma propriedade de nó.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

Executar o algoritmo no gráfico completo com filtro de rótulo e manter os resultados no Cloud Storage

Este exemplo executa a instrução PageRank para classificar as contas com base nas transferências em que elas participam. Os resultados da consulta são mantidos em um bucket do Cloud Storage no formato CSV como my-bucket-name/my-output.csv.

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

No Cloud Storage, você verá um arquivo CSV com duas colunas (id e page_rank) quando essa consulta for concluída.

Executar o algoritmo no subgráfico definido por MATCH e manter os resultados no gráfico

Este exemplo usa o padrão MATCH para corresponder dinamicamente a um subgrafo lógico que contém todos os nós Account e apenas arestas Transfer com um valor menor que 500. Esse subgrafo lógico é a entrada para o algoritmo PageRank. O Spanner mantém os resultados do algoritmo na tabela Account.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

Depois que a consulta for concluída, execute esta consulta:

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

Os resultados serão semelhantes aos exibidos abaixo:

ID page_rank
20 0,49
16 0.46
7 0,05

Verificar o status de execução do algoritmo

Quando uma consulta de algoritmo de grafo é concluída, ela retorna zero linhas e o status Success. Dependendo do tamanho do gráfico de entrada e das configurações específicas do algoritmo, a execução do algoritmo pode levar algum tempo para ser concluída. É possível verificar o progresso e o status de execução de uma consulta de algoritmo de gráfico na tabela SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS. Essa tabela retém informações por 30 dias.

GRAPH_OPERATION_EXECUTION_STATUS esquema

Nome da coluna Tipo Descrição
QUERY_ID STRING O ID da consulta do algoritmo de gráfico.
QUERY_TEXT STRING O texto da instrução de consulta.
START_TIMESTAMP TIMESTAMP O horário em que a consulta começou a ser executada.
LAST_UPDATE_TIMESTAMP TIMESTAMP A hora em que o status foi atualizado pela última vez.
PROGRESS FLOAT64 Porcentagem estimada de conclusão. O valor está entre 0 e 1, em que 0 significa "iniciado" e 1 significa "concluído".
STATUS STRING Estado atual da execução. Os valores possíveis incluem PENDING, IN_PROGRESS, OK ou um código de status de erro, como CANCELLED, DEADLINE_EXCEEDED, INVALID_ARGUMENT, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, UNAVAILABLE ou UNKNOWN.
ERROR_MESSAGE STRING Mensagem de erro se a execução da consulta falhar.

O exemplo de consulta a seguir lista as consultas de gráfico que ainda não foram concluídas:

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

Cancelar execução do algoritmo

Para cancelar uma consulta de algoritmo de gráfico em andamento, localize o query_id na tabela SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS e chame cancel_query para esse query_id.

A seguir