Consultas estruturadas de chave de linha

Se uma tabela tiver um esquema de chave de linha que defina chaves de linha estruturadas, use o SQL para consultar os segmentos ou colunas individuais 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 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 estruturado, cada linha é indexada por uma única chave de linha. Quando você consulta a tabela com SQL, a chave de linha é uma coluna chamada _key que o SQL usa como chave primária. Ela não é uma pseudocoluna. Portanto, 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" "calçados" "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 vai retornar cada segmento da chave de linha como uma coluna separada. Como em qualquer consulta SQL a uma tabela do Bigtable, as colunas em um grupo de colunas são expressas como mapas.

  SELECT * from sales

Os resultados vão ser assim:

user_id purchase_date order_number produto
Usuário 1 2025-05-20 "abcd1233" { product_type: "phone", product_name: "iPhone16_pro_max" }
Usuário 1 2025-05-20 "abcd1235" { product_type: "shoes", product_name: "nike_hyperdunk" }
Usuário 2 2025-05-24 "defg456" { product_type: "headphones", product_name: "sony_wh_1000mx5" }

Você também pode especificar as colunas de chave de linha na sua 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"
"calçados" "nike_hyperdunk"

Filtros

É possível filtrar as colunas de 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
Usuário 2 "sony_wh_1000mx5"

Consultas agregadas

O exemplo a seguir mostra como usar uma consulta de agregação em campos de chave de linha estruturada:

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

Os resultados da consulta são estes:

user_id product_type contagem
Usuário 1 telefone 1
Usuário 1 calçados 1
Usuário 2 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" Usuário 1
"user1#2025-05-20#abcd1235" Usuário 1
"user2#2025-05-24#defg456" Usuário 2

A seguir