Interroger des données protobuf

Ce document fournit des exemples de schémas de requête courants pour lire et interroger des données de tampon de protocole (protobuf) stockées dans Bigtable.

Avant de lire cette page, familiarisez-vous avec les points suivants :

Exemple de données

Les exemples suivants utilisent une table Music qui stocke des informations sur les albums et les artistes. Les données sont stockées dans une famille de colonnes nommée album_details, avec un qualificatif de colonne album. Le qualificatif de colonne contient des messages protobuf.

Le schéma protobuf est défini dans les fichiers proto suivants :

  • 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;
}

Par conséquent, Bigtable crée un bundle de schémas pour cette table qui contient l'ensemble de descripteurs de fichier protobuf suivant pour ces définitions 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"
}

Exemples de requêtes

Les exemples suivants montrent comment interroger des données protobuf à l'aide de GoogleSQL pour les tables externes Bigtable et BigQuery.

Caster une colonne en message protobuf

Vous pouvez utiliser l'opérateur CAST pour interpréter une valeur BYTES en tant que message protobuf. Pour ce faire, vous devez fournir le nom complet du message protobuf au format suivant : SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

Remplacez les éléments suivants :

  • SCHEMA_BUNDLE_ID : Identifiant unique que vous avez attribué à votre groupe de schémas lors de sa création.
  • FULLY_QUALIFIED_MESSAGE_NAME : nom complet du message, qui doit inclure le nom du package défini dans votre fichier proto (par exemple, package_name.message_name).

L'exemple de requête suivant caste la colonne album vers le message protobuf Album. Ce message est défini dans le package package_name et fait partie d'un bundle de schéma nommé bundle_name :

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

Accéder aux champs imbriqués

Vous pouvez accéder aux champs imbriqués dans un message protobuf à l'aide de la notation par points.

La requête suivante récupère le nom de l'artiste à partir du message Artist imbriqué dans le message Album :

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

Filtrer en fonction des champs protobuf

Vous pouvez utiliser la clause WHERE pour filtrer les lignes en fonction des valeurs des champs d'un message protobuf.

La requête suivante sélectionne tous les albums de l'artiste Dana A.:

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

Champs protobuf d'agrégation

Vous pouvez utiliser des fonctions d'agrégation telles que SUM, AVG, MIN, MAX et COUNT sur les champs numériques de vos messages protobuf.

La requête suivante calcule l'année de sortie moyenne de tous les albums de la table :

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

Trier par champs protobuf

Vous pouvez utiliser la clause ORDER BY pour trier l'ensemble de résultats en fonction d'un champ de votre message protobuf.

La requête suivante récupère tous les albums et les trie par année de sortie, par ordre décroissant :

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

Utiliser avec des vues

Vous pouvez créer des vues matérialisées continues ou des vues logiques qui lisent les données protobuf.

La commande suivante crée une vue logique qui extrait tous les champs du message Album :

QUERY="SELECT _key, CAST(album_details['album'] AS bundle_name.package_name.Album).* FROM Music"

gcloud bigtable logical-views create LOGICAL_VIEW_ID \
    --instance=INSTANCE_ID \
    --query=$QUERY

Remplacez les éléments suivants :

  • LOGICAL_VIEW_ID : ID de la vue logique qui référence le bundle de schémas.
  • INSTANCE_ID : ID de l'instance que vous utilisez pour créer le bundle de schémas.

Lorsqu'une vue fait référence à un bundle de schémas, vous devez supprimer la vue avant de pouvoir supprimer le bundle. De plus, ne mettez pas à jour le bundle de schémas vers un nouvel ensemble de descripteurs de fichiers protobuf qui n'est pas rétrocompatible avec l'ensemble existant.

Utiliser avec des tables externes BigQuery

Vous pouvez interroger des données protobuf stockées dans Bigtable à partir de BigQuery en créant une table externe. Lorsque vous créez la table externe, vous spécifiez le type de colonne JSON, son encodage PROTO_BINARY et vous l'associez à un bundle de schémas. Ce processus convertit les octets du message protobuf en données JSON équivalentes, ce qui vous permet d'interroger directement ses champs.

Voici un exemple de fichier de définition de table permettant de créer une table externe BigQuery sur la table 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"
                        }
                    }
                ]
            }
        ]
    }
}

Une fois la table externe créée, vous pouvez interroger les données protobuf en tant que colonne JSON dans BigQuery.

La requête suivante récupère le titre de tous les albums sortis en 2022 à partir de la table externe 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;

Étapes suivantes