Consultas de chaves de linhas estruturadas

Se uma tabela tiver um esquema de chaves de linhas que defina chaves de linhas estruturadas, pode usar SQL para consultar os segmentos individuais, ou colunas, da chave de linha.

As vistas materializadas contínuas, incluindo índices secundários assíncronos, geram chaves de linhas estruturadas por predefinição. Também pode definir uma chave de linha estruturada para qualquer tabela do Bigtable que queira consultar com SQL criando um esquema de chave de linha para a tabela. Para mais informações, consulte o artigo Faça a gestão dos esquemas de chaves de linhas.

Chaves

Numa tabela do Bigtable sem um esquema de chave de linha estruturado, cada linha é indexada por uma única chave de linha. Quando consulta a tabela com SQL, a chave da linha é uma coluna denominada _key que o SQL usa como chave primária. Não é uma pseudocoluna, pelo que os valores na coluna _key são devolvidos quando executa uma consulta SELECT * na tabela.

Por outro lado, numa tabela que tem um esquema de chave de linha, a chave de linha (chave principal) é a combinação de todas as colunas denominadas campos no esquema de chave de linha. Quando adiciona um esquema de chave de linha a uma tabela, a coluna _key torna-se uma pseudocoluna, o que significa que não é apresentada numa consulta SELECT *, mas pode selecioná-la explicitamente com uma declaração SELECT _key.

Consultas de exemplo

Os exemplos nesta secção partem do princípio de que uma tabela denominada sales tem o seguinte esquema:

  field {
    field_name: "user_id"
    type: { bytes_type { encoding { raw {} } } }
  }
  field {
    field_name: "purchase_date"
    type: { string_type { encoding { utf8_bytes {} } } }
  }
  field {
    field_name: "order_number"
    type: { string_type { encoding { utf8_bytes {} } } }
  }
  encoding {
    delimited_bytes { delimiter "#" }
  }

A tabela sales contém os seguintes dados. A família de colunas product tem duas colunas.

chave da linha produto
  product_type product_name
"user1#2025-05-20#abcd1233" "telemóvel" "iPhone16_pro_max"
"user1#2025-05-20#abcd1235" "sapatos" "nike_hyperdunk"
"user2#2025-05-24#defg456" "headphones" "sony_wh_1000mx5"

Resultados de consultas de chaves de linhas estruturadas

Uma vez que a tabela sales tem chaves de linhas estruturadas, se consultar a tabela com uma declaração SELECT *, a consulta devolve cada segmento da chave de linha como uma coluna separada. Tal como em qualquer consulta SQL a uma tabela do Bigtable, as colunas numa família de colunas são expressas como mapas.

  SELECT * from sales

Os resultados têm o seguinte aspeto:

user_id purchase_date order_number produto
user1 2025-05-20 "abcd1233" { product_type: "phone", product_name: "iPhone16_pro_max" }
user1 2025-05-20 "abcd1235" { product_type: "shoes", product_name: "nike_hyperdunk" }
user2 2025-05-24 "defg456" { product_type: "headphones", product_name: "sony_wh_1000mx5" }

Também pode especificar as colunas de chaves de linhas na sua consulta, conforme mostrado no exemplo seguinte:

  SELECT
    product[product_type] AS product_type,
    product[product_name] AS product_name
  FROM sales
  WHERE user_id = b"user1"

Os resultados têm o seguinte aspeto:

product_type product_name
"telemóvel" "iphone16_pro_max"
"sapatos" "nike_hyperdunk"

Filtros

Pode filtrar as colunas do esquema de chaves de linhas através de funções SQL. O exemplo seguinte pressupõe que CURRENT_DATE() devolve 2025-05-24:

  SELECT
    user_id,
    product["product_name"] AS product_name
  FROM
    sales
  WHERE
    PARSE_DATE("YYYY-MM-DD", purchase_date) = CURRENT_DATE()
    AND user_id = b"user2"

Seguem-se os resultados:

user_id product_name
user2 "sony_wh_1000mx5"

Consultas agregadas

O exemplo seguinte mostra como usar uma consulta de agregação em campos de chave de linha estruturados:

  SELECT
    user_id,
    product[product_type] AS product_type,
    count(*) AS count
  FROM sales
  GROUP BY 1, 2

Os resultados da consulta são os seguintes:

user_id product_type contagem
user1 telemóvel 1
user1 sapatos 1
user2 auscultadores 1

Chave da linha original

Para obter a chave da linha original numa tabela com chaves de linhas estruturadas, especifique a coluna _key na sua consulta.

  SELECT
    _key, user_id
  FROM sales

A consulta devolve o seguinte:

_key user_id
"user1#2025-05-20#abcd1233" user1
"user1#2025-05-20#abcd1235" user1
"user2#2025-05-24#defg456" user2

O que se segue?