Consulta datos de protobuf

En este documento, se proporcionan ejemplos de patrones de consultas comunes para leer y consultar datos de búfer de protocolo (protobuf) almacenados en Bigtable.

Antes de leer esta página, familiarízate con lo siguiente:

Datos de ejemplo

En los siguientes ejemplos, se usa una tabla Music que almacena información sobre álbumes y artistas. Los datos se almacenan en una familia de columnas llamada album_details, con un calificador de columna album. El calificador de columna contiene mensajes de protobuf.

El esquema de protobuf se define en los siguientes archivos .proto:

  • artist.proto:

    syntax = "proto3";

package package_name;

message Artist {
 string name = 1;
}

  • album.proto:

    syntax = "proto3";

package package_name;

import "artist.proto";

message Album {
 string title = 1;
 Artist artist = 2;
 int32 release_year = 3;
}

Como resultado, Bigtable crea un paquete de esquema para esta tabla que contiene el siguiente conjunto de descriptores para estas definiciones de .proto:

file {
  name: "artist.proto"
  package: "package_name"
  message_type {
    name: "Artist"
    field {
      name: "name"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "name"
    }
  }
  syntax: "proto3"
}
file {
  name: "album.proto"
  package: "package_name"
  dependency: "artist.proto"
  message_type {
    name: "Album"
    field {
      name: "title"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "title"
    }
    field {
      name: "artist"
      number: 2
      label: LABEL_OPTIONAL
      type: TYPE_MESSAGE
      type_name: ".package_name.Artist"
      json_name: "artist"
    }
    field {
      name: "release_year"
      number: 3
      label: LABEL_OPTIONAL
      type: TYPE_INT32
      json_name: "releaseYear"
    }
  }
  syntax: "proto3"
}

Consultas de ejemplo

En los siguientes ejemplos, se muestra cómo consultar datos de Protobuf con GoogleSQL para tablas externas de Bigtable y BigQuery.

Cómo convertir una columna en un mensaje de Protobuf

Puedes usar el operador CAST para interpretar un valor de BYTES como un mensaje de protobuf. Para ello, debes proporcionar el nombre completo del mensaje de protobuf en el siguiente formato: SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID único que le asignaste a tu paquete de esquemas cuando lo creaste.
  • FULLY_QUALIFIED_MESSAGE_NAME: Es el nombre completo del mensaje, que debe incluir el nombre del paquete definido en tu archivo .proto, por ejemplo, package_name.message_name.

En la siguiente consulta de ejemplo, se convierte la columna album al mensaje Album de protobuf. Este mensaje se define en el paquete package_name y forma parte de un paquete de esquemas llamado bundle_name:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).title
FROM
  Music;

Accede a campos anidados

Puedes acceder a los campos anidados dentro de un mensaje de protobuf con la notación de puntos.

La siguiente consulta recupera el nombre del artista del mensaje Artist anidado dentro del mensaje Album:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name
FROM
  Music;

Filtra según los campos de protobuf

Puedes usar la cláusula WHERE para filtrar filas según los valores de los campos dentro de un mensaje de protobuf.

La siguiente consulta selecciona todos los álbumes del artista Dana A.:

SELECT
  *
FROM
  Music
WHERE
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name = 'Dana A.';

Agrega campos de protobuf

Puedes usar funciones de agregación como SUM, AVG, MIN, MAX y COUNT en campos numéricos dentro de tus mensajes de Protobuf.

La siguiente consulta calcula el año de lanzamiento promedio de todos los álbumes de la tabla:

SELECT
  AVG(CAST(album_details['album'] AS bundle_name.package_name.Album).release_year)
FROM
  Music;

Ordenar por campos de Protobuf

Puedes usar la cláusula ORDER BY para ordenar el conjunto de resultados según un campo de tu mensaje .proto.

La siguiente consulta recupera todos los álbumes y los ordena por año de lanzamiento en orden descendente:

SELECT
  *
FROM
  Music
ORDER BY
  CAST(album_details['album'] AS bundle_name.package_name.Album).release_year DESC;

Uso con tablas externas de BigQuery

Puedes consultar los datos de protobuf almacenados en Bigtable desde BigQuery creando una tabla externa. Cuando creas la tabla externa, especificas el tipo de columna como JSON, su codificación como PROTO_BINARY y la asocias con un paquete de esquema. Este proceso convierte los bytes del mensaje de protobuf en los datos JSON equivalentes, lo que te permite consultar sus campos directamente.

A continuación, se muestra un ejemplo de un archivo de definición de tabla para crear una tabla externa de BigQuery sobre la tabla Music:

{
    "sourceFormat": "BIGTABLE",
    "sourceUris": [
        "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/Music"
    ],
    "bigtableOptions": {
        "columnFamilies" : [
            {
                "familyId": "album_details",
                "columns": [
                    {
                        "qualifierString": "album",
                        "type": "JSON",
                        "encoding": "PROTO_BINARY",
                        "protoConfig": {
                            "schemaBundleId": "bundle_name",
                            "protoMessageName": "package_name.Album"
                        }
                    }
                ]
            }
        ]
    }
}

Una vez que se crea la tabla externa, puedes consultar los datos de protobuf como una columna JSON en BigQuery.

La siguiente consulta recupera el título de todos los álbumes lanzados en 2022 de la tabla externa de BigQuery:

SELECT JSON_VALUE(value, '$.title') AS title
FROM
`PROJECT_ID.DATASET.TABLE_NAME` AS t,
UNNEST(t.album_details.album.cell)
WHERE INT64(JSON_EXTRACT(value, '$.releaseYear')) = 2022;

¿Qué sigue?