Consultar dados do protobuf

Este documento fornece exemplos de padrões de consulta comuns para ler e consultar dados de buffer de protocolo (protobuf) armazenados no Bigtable.

Antes de ler esta página, familiarize-se com o seguinte:

Dados de exemplo

Os exemplos a seguir usam uma tabela Music que armazena informações sobre álbuns e artistas. Os dados são armazenados em um grupo de colunas chamado album_details, com um qualificador de coluna album. O qualificador de coluna contém mensagens do protobuf.

O esquema do protobuf é definido nos seguintes arquivos 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, o Bigtable cria um pacote de esquema para essa tabela que contém o seguinte conjunto de descritores para essas definições do protobuf:

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"
}

Exemplo de consultas

Os exemplos a seguir mostram como consultar dados do protobuf usando o GoogleSQL para Bigtable e tabelas externas do BigQuery.

Converter uma coluna em uma mensagem do protobuf

É possível usar o operador CAST para interpretar um valor BYTES como uma mensagem do protobuf. Para fazer isso, forneça o nome completo da mensagem do protobuf no seguinte formato: SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

Substitua:

  • SCHEMA_BUNDLE_ID: o ID exclusivo atribuído ao pacote de esquema quando ele foi criado.
  • FULLY_QUALIFIED_MESSAGE_NAME: o nome completo da mensagem, que precisa incluir o nome do pacote definido no arquivo proto, por exemplo, package_name.message_name.

A consulta de exemplo a seguir converte a coluna album na mensagem do protobuf Album. Essa mensagem é definida no pacote package_name e faz parte de um pacote de esquema chamado bundle_name:

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

Acessar campos aninhados

É possível acessar campos aninhados em uma mensagem do protobuf usando a notação de ponto.

A consulta a seguir recupera o nome do artista da mensagem Artist aninhada na mensagem Album:

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

Filtrar com base em campos do protobuf

É possível usar a cláusula WHERE para filtrar linhas com base nos valores dos campos em uma mensagem do protobuf.

A consulta a seguir seleciona todos os álbuns do artista Dana A.:

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

Agregar campos do protobuf

É possível usar funções de agregação como SUM, AVG, MIN, MAX e COUNT em campos numéricos nas mensagens do protobuf.

A consulta a seguir calcula o ano médio de lançamento de todos os álbuns na tabela:

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

Ordenar por campos do protobuf

É possível usar a cláusula ORDER BY para classificar o conjunto de resultados com base em um campo na mensagem do protobuf.

A consulta a seguir recupera todos os álbuns e os classifica por ano de lançamento em ordem decrescente:

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

Usar com tabelas externas do BigQuery

É possível consultar dados do protobuf armazenados no Bigtable no BigQuery criando uma tabela externa. Ao criar a tabela externa, especifique o tipo de coluna como JSON, a codificação como PROTO_BINARY e associe-a a um pacote de esquema. Esse processo converte os bytes da mensagem do protobuf nos dados JSON equivalentes, permitindo que você consulte os campos diretamente.

A seguir, um exemplo de arquivo de definição de tabela para criar uma tabela externa do BigQuery na tabela 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"
                        }
                    }
                ]
            }
        ]
    }
}

Depois que a tabela externa for criada, será possível consultar os dados do protobuf como uma coluna JSON no BigQuery.

A consulta a seguir recupera o título de todos os álbuns lançados em 2022 na tabela externa do 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;

A seguir