Consultar dados de protobuf

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

Antes de ler esta página, familiarize-se com os seguintes tópicos:

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 protobuf.

O esquema 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 de 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 protobuf usando GoogleSQL para tabelas externas do Bigtable e do BigQuery.

Converter uma coluna em uma mensagem do Protobuf

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

Substitua:

  • SCHEMA_BUNDLE_ID: o ID exclusivo que você atribuiu ao pacote de esquemas ao criá-lo.
  • 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 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 protobuf usando a notação por pontos.

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

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

Filtrar com base em campos protobuf

É possível usar a cláusula WHERE para filtrar linhas com base nos valores dos campos em uma mensagem 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 protobuf

É possível usar funções de agregação como SUM, AVG, MIN, MAX e COUNT em campos numéricos nas mensagens 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 protobuf

É possível usar a cláusula ORDER BY para classificar o conjunto de resultados com base em um campo na mensagem 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 protobuf armazenados no Bigtable pelo 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 um pacote de esquema. Esse processo converte os bytes da mensagem protobuf nos dados JSON equivalentes, permitindo que você consulte os campos diretamente.

Confira 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, você poderá 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 da 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