Consultas de claves de fila estructuradas

Si una tabla tiene un esquema de clave de fila que define claves de fila estructuradas, puede usar SQL para consultar los segmentos o las columnas individuales de la clave de fila.

Las vistas materializadas continuas, incluidos los índices secundarios asíncronos, generan claves de fila estructuradas de forma predeterminada. También puede definir una clave de fila estructurada para cualquier tabla de Bigtable que quiera consultar con SQL creando un esquema de clave de fila para la tabla. Para obtener más información, consulta Gestionar esquemas de claves de fila.

Claves

En una tabla de Bigtable sin un esquema de clave de fila estructurado, cada fila se indexa por una sola clave de fila. Cuando consultas la tabla con SQL, la clave de fila es una columna llamada _key que SQL usa como clave principal. No es una pseudocolumna, por lo que los valores de la columna _key se devuelven al ejecutar una consulta SELECT * en la tabla.

Por otro lado, en una tabla que tiene un esquema de clave de fila, la clave de fila (clave principal) es la combinación de todas las columnas denominadas como campos en el esquema de clave de fila. Cuando añades un esquema de clave de fila a una tabla, la columna _key se convierte en una pseudocolumna, lo que significa que no aparecerá en una consulta SELECT *, pero puedes seleccionarla explícitamente con una instrucción SELECT _key.

Consultas de ejemplo

En los ejemplos de esta sección se da por hecho que una tabla llamada sales tiene el siguiente 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 "#" }
  }

La tabla sales contiene los siguientes datos. La familia de columnas product tiene dos columnas.

clave del registro producto
  product_type product_name
"user1#2025-05-20#abcd1233" "phone" "iPhone16_pro_max"
"user1#2025-05-20#abcd1235" "zapatos" "nike_hyperdunk"
"user2#2025-05-24#defg456" "auriculares" "sony_wh_1000mx5"

Resultados de consultas de claves de fila estructuradas

Como la tabla sales tiene claves de fila estructuradas, si la consultas con una instrucción SELECT *, la consulta devuelve cada segmento de la clave de fila como una columna independiente. Al igual que en cualquier consulta SQL a una tabla de Bigtable, las columnas de una familia de columnas se expresan como mapas.

  SELECT * from sales

Los resultados tienen este aspecto:

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

También puedes especificar las columnas de clave de fila en tu consulta, como se muestra en el siguiente ejemplo:

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

Los resultados tienen este aspecto:

product_type product_name
"phone" "iphone16_pro_max"
"zapatos" "nike_hyperdunk"

Filtros

Puedes filtrar las columnas del esquema de claves de fila mediante funciones SQL. En el siguiente ejemplo se presupone que CURRENT_DATE() devuelve 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"

Estos son los resultados:

user_id product_name
usuario2 "sony_wh_1000mx5"

Consultas de agregación

En el siguiente ejemplo se muestra cómo usar una consulta agregada en campos de clave de fila estructurados:

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

Los resultados de la consulta son los siguientes:

user_id product_type recuento
usuario1 teléfono 1
usuario1 zapatos 1
usuario2 auriculares 1

Clave de fila original

Para recuperar la clave de fila original en una tabla con claves de fila estructuradas, especifica la columna _key en tu consulta.

  SELECT
    _key, user_id
  FROM sales

La consulta devuelve lo siguiente:

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

Siguientes pasos