Consultas de chave de linha estruturada

Se uma tabela tiver um esquema de chave de linha que define chaves de linha estruturadas, você poderá usar SQL para consultar os segmentos individuais ou colunas da chave de linha.

As visualizações materializadas contínuas, incluindo índices secundários assíncronos, geram chaves de linha estruturadas por padrão. Também é possível definir uma chave de linha estruturada para qualquer tabela do Bigtable que você queira consultar com o SQL criando um esquema de chave de linha para a tabela. Para mais informações, consulte Gerenciar esquemas de chave de linha.

Chaves

Em uma tabela do Bigtable sem um esquema de chave de linha estruturada, cada linha é indexada por uma única chave de linha. Ao consultar a tabela com o SQL, a chave de linha é uma coluna chamada _key que o SQL usa como chave primária. Ela não é uma pseudocoluna, então os valores na coluna _key são retornados quando você executa uma consulta SELECT * na tabela.

Por outro lado, em uma tabela que tem um esquema de chave de linha, a chave de linha (chave primária) é a combinação de todas as colunas nomeadas como campos no esquema de chave de linha. Quando você adiciona um esquema de chave de linha a uma tabela, a coluna _key se torna uma pseudocoluna, o que significa que ela não aparece em uma consulta SELECT *, mas pode ser selecionada explicitamente com uma instrução SELECT _key.

Amostras de consultas

Os exemplos nesta seção pressupõem que uma tabela chamada sales tenha 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. O grupo de colunas product tem duas colunas.

chave de linha produto
  product_type product_name
"user1#2025-05-20#abcd1233" "telefone" "iPhone16_pro_max"
"user1#2025-05-20#abcd1235" "sapatos" "nike_hyperdunk"
"user2#2025-05-24#defg456" "fones de ouvido" "sony_wh_1000mx5"

Resultados da consulta de chave de linha estruturada

Como a tabela sales tem chaves de linha estruturadas, se você consultar a tabela com uma instrução SELECT *, a consulta retornará cada segmento da chave de linha como uma coluna separada. Como em qualquer consulta SQL para uma tabela do Bigtable, as colunas em um grupo de colunas são expressas como mapas.

  SELECT * from sales

Os resultados têm a seguinte aparência:

user_id purchase_date order_number produto
user1 2025-05-20 "abcd1233" { product_type: "telefone", 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 é possível especificar as colunas de chave de linha na consulta, conforme mostrado no exemplo a seguir:

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

Os resultados têm a seguinte aparência:

product_type product_name
"telefone" "iphone16_pro_max"
"sapatos" "nike_hyperdunk"

Filtros

É possível filtrar as colunas do esquema de chave de linha usando funções SQL. O exemplo a seguir pressupõe que CURRENT_DATE() retorne 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"

Os resultados são estes:

user_id product_name
user2 "sony_wh_1000mx5"

Consultas agregadas

O exemplo a seguir mostra como usar uma consulta agregada 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 telefone 1
user1 sapatos 1
user2 fones de ouvido 1

Chave de linha original

Para recuperar a chave de linha original em uma tabela com chaves de linha estruturadas, especifique a coluna _key na consulta.

  SELECT
    _key, user_id
  FROM sales

A consulta retorna o resultado a seguir:

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

A seguir