O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Consultas de visualização materializada contínua

Para criar uma visualização materializada contínua de uma tabela do Bigtable, execute uma consulta SQL que defina a visualização materializada contínua.

Este documento descreve conceitos e padrões para ajudar você a preparar sua consulta SQL de visualização materializada contínua. Antes de ler este documento, você deve estar familiarizado com as visualizações materializadas contínuas e o GoogleSQL para Bigtable.

As visualizações materializadas contínuas usam uma sintaxe SQL restrita. O padrão a seguir mostra como criar uma consulta SQL de visualização materializada contínua:

SELECT
  expression AS alias [, ...]
FROM from_item
[ WHERE bool_expression ]
GROUP BY expression [, ...];

from_item:
    {
      table_name [ as_alias ]
      | field_path
      }

as_alias:
    [ AS ] alias

Se você quiser criar uma consulta SQL de visualização materializada contínua como um índice secundário assíncrono, use a cláusula ORDER BY:

SELECT
  expression AS alias [, ...]
FROM from_item
[ WHERE bool_expression ]
ORDER BY expression [, ...];

from_item:
    {
      table_name [ as_alias ]
      | field_path
      }

as_alias:
    [ AS ] alias

As consultas SQL que usam funções não determinísticas são semanticamente diferentes de outras consultas de visualização materializada contínua. Para mais informações, consulte a seção Consultas não determinísticas deste documento.

Limitações de consulta

As regras a seguir se aplicam a uma consulta SQL usada para criar uma visualização materializada contínua:

Precisa ser uma instrução SELECT.
Precisa ter uma cláusula GROUP BY ou, para consultas de índice secundário assíncrono, uma cláusula ORDER BY, mas não ambas.
Precisa usar apenas funções de agregação compatíveis.
Pode ter várias agregações por grupo.

Agregações compatíveis

É possível usar as seguintes funções de agregação em uma consulta SQL que define uma visualização materializada contínua:

COUNT
SUM
MIN
MAX
HLL_COUNT.INIT
HLL_COUNT.MERGE
HLL_COUNT.MERGE_PARTIAL
ANY_VALUE
BIT_AND
BIT_OR
BIT_XOR
AVG

Se você SELECT COUNT(*) precisar definir uma chave de linha, como no exemplo a seguir:

SELECT
  '*' AS _key,
  COUNT(*) AS count
FROM
  foo
GROUP BY
  _key;

Recursos do SQL incompatíveis

Não é possível usar os seguintes recursos do SQL:

Qualquer recurso não compatível com o GoogleSQL para Bigtable
ARRAY
ARRAY_AGG
ARRAY_CONCAT_AGG
COUNT_IF
CURRENT_TIME e a maioria das outras funções não determinísticas, com exceções.
DATE, DATETIME como colunas de saída (use TIMESTAMP ou armazene uma string).
Classificação DESC na saída
Opção DISTINCT, como em SUM(*DISTINCT* value))
LIMIT/OFFSET
SELECT *
Cláusula OVER para criar uma agregação de janela
STRUCT

Também não é possível aninhar cláusulas GROUP BY ou ORDER BY nem criar colunas de mapa. Para outras limitações, consulte Limitações.

Como evitar linhas excluídas

As linhas de entrada são excluídas de uma visualização materializada contínua nas seguintes circunstâncias:

Mais de 1 MiB de dados é selecionado na linha. Por exemplo, se a consulta for SELECT apple AS apples , SUM(banana) AS sum_bananas FROM my_table GROUP BY apples, qualquer linha que contenha mais de 1 MiB de dados nas apple e banana colunas será excluída da visualização materializada contínua.
Mais de 1 MiB de dados é gerado na linha. Isso pode ocorrer quando você usa consultas como SELECT REPEAT(apple, 1000) ou usa constantes grandes.
Mais de 10 vezes mais dados são gerados do que foram selecionados.
A consulta não corresponde aos seus dados. Isso inclui tentar dividir um zero, estouro de número inteiro ou esperar um formato de chave de linha que não seja usado em todas as chaves de linha.

As linhas excluídas incrementam a métrica de erros do usuário quando são processadas pela primeira vez. Para mais informações sobre as métricas que podem ajudar a monitorar suas visualizações materializadas contínuas, consulte Métricas.

Detalhes da consulta

Esta seção descreve uma consulta de visualização materializada contínua e como os resultados podem aparecer quando a visualização é consultada. Os dados na tabela de origem são a entrada, e os dados de resultado na visualização materializada contínua são a saída. Os dados de saída são agregados ou não agregados (na chave definida).

Instrução SELECT

A instrução select configura as colunas e agregações usadas na visualização materializada contínua. A instrução precisa usar uma cláusula GROUP BY para agregar linhas ou uma cláusula ORDER BY para criar um índice secundário assíncrono.

SELECT * não é compatível, mas SELECT COUNT(*) é.

Como em uma instrução SELECT típica, é possível ter várias agregações por um conjunto de dados agrupados. As colunas não agrupadas precisam ser um resultado de agregação.

Este é um exemplo de uma consulta de agregação GROUP BY padrão em SQL:

SELECT
  myfamily["node"] AS node,
  myfamily["type"] AS type,
  COUNT(clicks) AS clicks_per_key
FROM
  mytable
GROUP BY
  node,
  type

Chaves de linha e dados não agregados

É possível especificar uma _key como a chave de linha para uma visualização materializada contínua. Caso contrário, as colunas na cláusula GROUP BY formam a chave na visualização.

Chaves de linha definidas por uma coluna `_key`

É possível especificar uma coluna _key ao definir sua visualização materializada contínua. (Isso é diferente da _key coluna que você recebe ao executar uma consulta SQL em uma tabela do Bigtable.) Se você especificar uma _key, as seguintes regras serão aplicadas:

É necessário agrupar por _key, e não é possível agrupar por mais nada, exceto (opcionalmente) por _timestamp. Para mais informações, consulte Carimbos de data/hora.
A coluna _key precisa ser do tipo BYTES.

Especificar uma _key é útil se você planeja ler a visualização com ReadRows em vez de SQL, porque isso permite controlar o formato da chave de linha. Por outro lado, uma consulta SQL para uma visualização com uma _key definida pode precisar decodificar a _key explicitamente em vez de apenas retornar colunas de chave estruturadas.

Chaves de linha definidas pela cláusula `GROUP BY` ou `ORDER BY`

Se você não especificar uma _key, as colunas não agregadas na lista SELECT se tornarão a chave de linha na visualização. É possível atribuir às colunas de chave qualquer nome compatível com as convenções SQL. Use essa abordagem se você planeja usar o SQL para consultar a visualização em vez de uma solicitação ReadRows.

As colunas de saída não agregadas na lista SELECT precisam ser incluídas na cláusula GROUP BY. A ordem em que as colunas são gravadas na cláusula GROUP BY é a ordem em que os dados são armazenados na chave de linha da visualização materializada contínua. Por exemplo, GROUP BY a, b, c é implicitamente ORDER BY a ASC, b ASC, c ASC.

Se você usar uma cláusula ORDER BY em vez de uma cláusula GROUP BY para criar um índice secundário assíncrono, as colunas na lista SELECT que fazem parte da cláusula ORDER BY se tornarão a chave de linha na visualização. A ordem em que as colunas são gravadas na cláusula ORDER BY é a ordem em que os dados são armazenados na chave de linha da visualização materializada contínua. Por exemplo, ORDER BY a, b, c armazena os dados com chaves de linha ordenadas por a ASC, depois b ASC e, em seguida, c ASC.

O filtro SQL precisa eliminar possíveis valores NULL ou outros valores inválidos que possam causar erros. Uma linha inválida, como uma que contém uma coluna de chave NULL, é omitida dos resultados e contada na métrica materialized_view/user_errors. Para depurar erros do usuário, tente executar a consulta SQL fora de uma visualização materializada contínua.

Dados agregados

As colunas agregadas na consulta definem os cálculos que geram os dados na visualização materializada contínua.

O alias de uma coluna agregada é tratado como um qualificador de coluna na visualização materializada contínua.

Veja o exemplo a seguir.

SELECT
  fam["baz"] AS baz,
  SUM(fam["foo"]) AS sum_foo,
  SUM(fam["bar"]) AS sum_bar
FROM
  TABLE

GROUP BY
  baz;

A saída da consulta tem as seguintes características:

A saída de cada baz está em uma linha separada na ordem baz ASC.
Se um determinado baz tiver pelo menos um foo, o sum_foo da linha de saída será um valor não NULL.
Se um determinado baz tiver pelo menos um bar, o sum_bar da linha de saída será um valor não NULL.
Se um determinado baz não tiver valor para nenhuma das colunas, ele será omitido dos resultados.

Em seguida, se você consultar a visualização com SELECT *, o resultado será semelhante ao seguinte:

baz	sum_foo	sum_bar
baz1	sum_foo1	sum_bar1
baz2	sum_foo2	sum_bar2

Carimbos de data/hora

O carimbo de data/hora padrão para uma célula de saída em uma visualização materializada contínua é 0 (1970-01-01 00:00:00Z). Isso fica visível quando você lê a visualização com ReadRows e não quando a consulta com SQL.

Para usar um carimbo de data/hora diferente na saída, adicione uma coluna do tipo TIMESTAMP à lista SELECT da consulta e nomeie-a como _timestamp. Se você consultar a visualização materializada contínua usando ReadRows, _timestamp se tornará o carimbo de data/hora para as outras células na linha.

Um carimbo de data/hora não pode ser NULL, precisa ser maior ou igual a zero e precisa ser um múltiplo de 1.000 (precisão de milissegundos). O Bigtable não oferece suporte a carimbos de data/hora de células anteriores à época Unix (1970-01-01T00:00:00Z).

Considere o exemplo a seguir, que reamostra dados agregados por dia. A consulta usa a função UNPACK.

SELECT
  _key,
  TIMESTAMP_TRUNC(_timestamp, DAY) AS _timestamp,
  SUM(sum_family["sum_column"]) AS sum_column,
  SUM(sum_family["foo"]) AS second_sum_column
FROM
  UNPACK(
  SELECT
    *
  FROM
    my_table(with_history => TRUE))
GROUP BY
  1,
  2

Se um determinado SUM tiver uma entrada não vazia para um determinado dia, a linha de saída vai conter um valor agregado com um carimbo de data/hora que corresponde ao dia truncado.

Se você consultar a visualização com SELECT *, o resultado será semelhante ao seguinte:

_key	_timestamp	sum_column	second_sum_column
1	2024-05-01 00:00:00Z	23	99
2	2024-05-02 00:00:00Z	45	201
3	2024-05-03 00:00:00Z	NULL	56
4	2024-05-04 00:00:00Z	8	NULL

Consultas não determinísticas

As visualizações materializadas contínuas oferecem suporte às seguintes funções SQL não determinísticas.

A função de atributo do cluster

A função CLUSTER_ATTRIBUTE() permite acessar programaticamente metadados sobre o cluster do Bigtable que executa a consulta de visualização materializada contínua. O atributo cluster_id retorna o identificador de string do cluster que processa a visualização.

Isolar uma visualização em um único cluster

Para isolar a computação e o armazenamento de visualização materializada contínua em um único cluster, como um cluster de análise ou relatórios dedicado, compare CLUSTER_ATTRIBUTE('cluster_id') a um literal de string constante que contenha o identificador do cluster:

SELECT
  metrics['sensor_id'] AS sensor_id,
  COUNT(1) AS reading_count
FROM `TABLE_ID`
WHERE CLUSTER_ATTRIBUTE('cluster_id') = 'CLUSTER_ID'
GROUP BY 1

Substitua:

TABLE_ID: o identificador exclusivo da tabela do Bigtable.
CLUSTER_ID: o identificador do cluster em que você quer materializar a visualização.

Essa consulta se comporta da seguinte maneira na sua instância:

Cluster designado: no cluster que corresponde a CLUSTER_ID, a condição WHERE é avaliada como true. O Bigtable agrega todos os dados da tabela de origem, independentemente de qual cluster os ingeriu ou replicou, e materializa esses dados na cópia da visualização do cluster.
Outros clusters: em todos os outros clusters na instância, CLUSTER_ATTRIBUTE('cluster_id') é avaliado como os IDs de cluster respectivos, tornando a condição WHERE false. Esses clusters não computam nem armazenam linhas para a visualização materializada contínua, o que economiza recursos de computação e armazenamento.

Filtrar dados por origem do cluster

Se o aplicativo gravar metadados de cluster nas linhas da tabela de origem, por exemplo, em uma coluna chamada origin_cluster, você poderá comparar o cluster de origem da linha com o cluster de processamento:

SELECT
  metrics['sensor_id'] AS sensor_id,
  COUNT(1) AS reading_count
FROM `TABLE_ID`
WHERE metrics['origin_cluster'] = CLUSTER_ATTRIBUTE('cluster_id')
GROUP BY 1

Nessa consulta, metrics['origin_cluster'] é uma propriedade dos dados armazenados na linha, enquanto CLUSTER_ATTRIBUTE('cluster_id') é uma propriedade do cluster que processa a visualização. A réplica de cada cluster da visualização materializada contínua agrega apenas as linhas em que o origin_cluster armazenado corresponde ao ID desse cluster.

Se algumas linhas não tiverem um cluster de origem especificado, use IF_NULL para atribuir um cluster de fallback:

SELECT
  metrics['sensor_id'] AS sensor_id,
  COUNT(1) AS reading_count
FROM `TABLE_ID`
WHERE IF_NULL(metrics['origin_cluster'], 'DEFAULT_CLUSTER_ID') = CLUSTER_ATTRIBUTE('cluster_id')
GROUP BY 1

Características da consulta

As consultas que usam CLUSTER_ATTRIBUTE têm as seguintes características:

Como sensor_id está na cláusula GROUP BY, ele se torna parte da chave de linha na visualização materializada contínua.
Para usar essa função não determinística, defina a flag ignore_warnings como true ao criar a visualização. Para mais informações, consulte Criar uma visualização materializada contínua.

Quando você consulta a visualização com SELECT *, o resultado é semelhante ao seguinte:

sensor_id	reading_count
sensor-1234	25
sensor-5678	68

Limitações

O uso da função CLUSTER_ATTRIBUTE não determinística introduz requisitos de roteamento rigorosos:

O roteamento de vários clusters não é compatível: como a saída da função depende de qual cluster físico executa a consulta, o roteamento de vários clusters produziria resultados não determinísticos.
Usar roteamento de cluster único: ao consultar uma visualização materializada contínua que usa CLUSTER_ATTRIBUTE, use um perfil de aplicativo configurado para roteamento de cluster único.
Rotear para o cluster designado: se você isolar uma visualização em um cluster específico, como WHERE CLUSTER_ATTRIBUTE('cluster_id') = 'my-reporting-cluster', direcione o perfil do aplicativo diretamente para esse cluster. A consulta de outro cluster retorna resultados vazios porque a visualização não é preenchida em outros clusters.

Codificação

Se você consultar sua visualização materializada contínua com SQL, não será necessário saber como os valores agregados são codificados, porque o SQL expõe os resultados como colunas digitadas.

Se você ler a visualização usando ReadRows, será necessário decodificar os dados agregados na solicitação de leitura. Para mais informações sobre ReadRows solicitações, consulte Leituras.

Os valores agregados em uma visualização materializada contínua são armazenados usando a codificação descrita na tabela a seguir, com base no tipo de saída da coluna da definição da visualização.

Tipo	Codificação
BOOL	Valor de 1 byte, 1 = verdadeiro, 0 = falso
BYTES	Sem codificação
INT64 (ou INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT)	Big-endian de 64 bits
FLOAT64	IEEE 754 de 64 bits, excluindo NaN e +/-inf
STRING	UTF-8
TIME/TIMESTAMP	Número inteiro de 64 bits que representa o número de microssegundos desde a época Unix (consistente com o GoogleSQL)

Para mais informações, consulte Codificação na referência da API Data.