Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Executar algoritmos do Spanner Graph

OBSERVAÇÃO:se você estiver executando algoritmos de grafo em uma instância do Spanner na região us-east1, especifique um destes como zone nos parâmetros de entrada do algoritmo: us-east1-b, us-east1-c ou us-east1-d. Para todas as outras regiões, não é necessário especificar uma zona.

Este documento explica como executar algoritmos no Spanner Graph.

Estrutura de consulta do 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 Opções do Cloud Storage e 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 CALL quando você omitir <match_clause> e quiser operar em todo o gráfico. Use CALL PER() quando <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 comuns do algoritmo.
<algorithm_specific_input>: parâmetros de entrada nomeados para o algoritmo. Para mais informações, consulte os parâmetros de entrada definidos em Algoritmos de grafo do Spanner.
<algorithm_specific_output>: a saída da chamada do algoritmo. Para mais informações, consulte as saídas definidas em Spanner Graph algorithms e YIELD na instrução CALL.
<results>: define o que será retornado 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 de grafo identifica o grafo, CALL é um algoritmo que gera uma saída predefinida e especifica o que RETURN da saída do algoritmo.

Opcionalmente, 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 por MATCH como entrada para o algoritmo. O algoritmo opera em um subgrafo lógico composto pelo conjunto exclusivo de nós e arestas selecionados.

A consulta não retorna dados. Os resultados são mantidos de acordo com export_option_list.

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

Parâmetros de entrada comuns do algoritmo
Processar a saída do algoritmo
Executar consultas de exemplo de algoritmo

Parâmetros de entrada comuns do algoritmo

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)	Compatível apenas quando `CALL` é usado. Uma lista de rótulos de nós a serem incluídos na entrada do algoritmo. Se especificado, apenas os nós com pelo menos um rótulo correspondente serão incluídos.
`edge_labels`	`ARRAY`	Não	(nenhum)	Compatível apenas quando `CALL` é usado. Uma lista de rótulos de arestas a serem incluídos na entrada do algoritmo. Se especificado, somente as arestas 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 aceitos: `default`, `large`
`zone`	`STRING`	Não	(nenhum)	A zona em que a execução do algoritmo ocorre. Precisa ser uma das zonas na região em que a consulta é recebida.
`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

É necessário manter 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.

Persistir 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 gerenciada pelo Google service-PROJECT_NUMBER@gcp-sa-spanner.iam.gserviceaccount.com.

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 aceitos: `CSV`, `PARQUET` e `AVRO`.
`header`	`BOOL`	Não	Se `true`, o sistema vai imprimir cabeçalhos de coluna para a 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 existirem arquivos com o mesmo URI, a instrução vai 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 sem compactação. Para `CSV`, o valor compatível é `GZIP`. Para `PARQUET`, os valores aceitos são: `SNAPPY`, `GZIP` e `ZSTD`. Para `AVRO`, os valores aceitos são: `DEFLATE`, `SNAPPY`.

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

Exportar dados para um ou mais arquivos

As consultas do Spanner Graph aceitam um único operador de caractere curinga (*) em uri. O caractere curinga pode aparecer no componente de nome do arquivo, mas não no nome do bucket, da pasta ou na extensão do arquivo. O uso do operador de caractere curinga faz com que o Spanner Graph crie 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 de 12 dígitos preenchido à esquerda, começando por zero. 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 de gráfico do Spanner são convertidos da seguinte maneira, dependendo do formato:

CSV

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

Os valores BOOL são convertidos em true ou false.
Os valores de BYTES são 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 Parquet
`BOOL`	`BOOLEAN`
`INT64`	`INT64`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTE_ARRAY`
`TIMESTAMP`	`TIMESTAMP_MICROS`
`NULL`	`null`

Persistir resultados no Spanner

As seguintes opções de EXPORT DATA são compatíveis ao persistir 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 para gravar os resultados. Pode ser qualquer tabela na instância do Spanner.
`write_mode`	`STRING`	Sim	O modo de gravação a ser usado. Os valores aceitos 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 para erros que não são de violaçã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 colunas especificados na cláusula RETURN já precisam 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. Ela oferece 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 "pelo menos uma vez". Isso significa que uma linha pode ser gravada várias vezes. A leitura da tabela de destino enquanto a execução está em andamento 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 com falha e 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 exemplo de algoritmo

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

Antes de começar

Para executar as consultas de exemplo do algoritmo de gráfico do Spanner, primeiro faça o seguinte:

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

Adicione uma 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 do 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 algoritmo no gráfico completo com filtro de rótulo e manter os resultados no Cloud Storage

Este exemplo executa PageRank para classificar Accounts com base nos Transactionss em que participam e mantém os resultados em um 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ê vai encontrar um arquivo CSV com duas colunas (id e page_rank) quando a consulta for concluída.

Executar algoritmo no subgrafo 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 as arestas Transfer com um valor menor que 500. Esse subgrafo lógico é a entrada do algoritmo PageRank. O Spanner salva os resultados do algoritmo de volta 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 o seguinte comando:

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 da execução do algoritmo

Quando uma consulta de algoritmo de grafo é concluída com sucesso, 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 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 execução da consulta foi iniciada.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	A hora em que o status foi atualizado pela última vez.
`PROGRESS`	`FLOAT`	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 são `PENDING`, `IN_PROGRESS`, `OK`, `CANCELLED`, `DEADLINE_EXCEEDED`, `UNKNOWN`.
`ERROR_MESSAGE`	`STRING`	Mensagem de erro se a execução da consulta falhar.

A consulta de exemplo 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 a 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.