Protobuf-Daten abfragen

In diesem Dokument finden Sie Beispiele für gängige Abfragemuster zum Lesen und Abfragen von Protocol Buffer-Daten (Protobuf), die in Bigtable gespeichert sind.

Bevor Sie diese Seite lesen, sollten Sie sich mit den folgenden Themen vertraut machen:

Beispieldaten

In den folgenden Beispielen wird eine Tabelle Music verwendet, in der Informationen zu Alben und Künstlern gespeichert sind. Die Daten werden in einer Spaltenfamilie mit dem Namen album_details und einem Spaltenqualifizierer album gespeichert. Der Spaltenqualifizierer enthält Protobuf-Nachrichten.

Das Protobuf-Schema ist in den folgenden Proto-Dateien definiert:

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

Daher erstellt Bigtable ein Schemabundle für diese Tabelle, das den folgenden Protobuf-Dateideskriptorsatz für diese Protobuf-Definitionen enthält:

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

Beispielabfragen

In den folgenden Beispielen wird gezeigt, wie Sie Protobuf-Daten mit GoogleSQL für Bigtable und externen BigQuery-Tabellen abfragen.

Spalte in eine Protobuf-Nachricht umwandeln

Mit dem Operator CAST können Sie einen BYTES-Wert als Protobuf-Nachricht interpretieren. Dazu müssen Sie den vollständigen Namen der Protobuf-Nachricht in dem folgenden Format angeben: SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

Ersetzen Sie Folgendes:

SCHEMA_BUNDLE_ID: Die eindeutige ID, die Sie Ihrem Schemabundle beim Erstellen zugewiesen haben.
FULLY_QUALIFIED_MESSAGE_NAME: Der vollständige Name der Nachricht, der den in Ihrer Proto-Datei definierten Paketnamen enthalten muss, z. B. package_name.message_name.

Die folgende Beispielabfrage wandelt die Spalte album in die Protobuf-Nachricht Album um. Diese Nachricht ist im Paket package_name definiert und Teil eines Schemabundles mit dem Namen bundle_name:

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

Auf verschachtelte Felder zugreifen

Sie können mit der Punktnotation auf verschachtelte Felder in einer Protobuf-Nachricht zugreifen.

Die folgende Abfrage ruft den Namen des Künstlers aus der verschachtelten Nachricht Artist in der Nachricht Album ab:

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

Nach Protobuf-Feldern filtern

Mit der Klausel WHERE können Sie Zeilen anhand der Werte von Feldern in einer Protobuf-Nachricht filtern.

Die folgende Abfrage wählt alle Alben des Künstlers Dana A. aus:

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

Protobuf-Felder aggregieren

Sie können Aggregatfunktionen wie SUM, AVG, MIN, MAX und COUNT auf numerische Felder in Ihren Protobuf-Nachrichten anwenden.

Die folgende Abfrage berechnet das durchschnittliche Erscheinungsjahr aller Alben in der Tabelle:

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

Nach Protobuf-Feldern sortieren

Mit der Klausel ORDER BY können Sie das Ergebnisset anhand eines Felds in Ihrer Protobuf-Nachricht sortieren.

Die folgende Abfrage ruft alle Alben ab und sortiert sie absteigend nach Erscheinungsjahr:

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

Mit Ansichten verwenden

Sie können kontinuierliche materialisierte Ansichten oder logische Ansichten erstellen, die Protobuf-Daten lesen.

Mit dem folgenden Befehl wird eine logische Ansicht erstellt, die alle Felder in der Nachricht Album extrahiert:

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

Ersetzen Sie Folgendes:

LOGICAL_VIEW_ID: Die ID der logischen Ansicht, die auf das Schemabundle verweist.
INSTANCE_ID: Die ID der Instanz, mit der Sie das Schemabundle erstellen.

Wenn eine Ansicht auf ein Schemabundle verweist, müssen Sie die Ansicht löschen, bevor Sie das Bundle löschen können. Aktualisieren Sie das Schemabundle außerdem nicht auf einen neuen Protobuf-Dateideskriptorsatz, der nicht abwärtskompatibel mit dem vorhandenen ist.

Mit externen BigQuery-Tabellen verwenden

Sie können Protobuf-Daten, die in Bigtable gespeichert sind, in BigQuery abfragen, indem Sie eine externe Tabelle erstellen. Beim Erstellen der externen Tabelle geben Sie den Spaltentyp als JSON, die Codierung als PROTO_BINARY an und verknüpfen sie mit einem Schemabundle. Dadurch werden die Protobuf-Nachrichtenbytes in die entsprechenden JSON-Daten konvertiert, sodass Sie die Felder direkt abfragen können.

Im Folgenden finden Sie ein Beispiel für eine Tabellendefinitionsdatei zum Erstellen einer externen BigQuery-Tabelle für die Music Tabelle:

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

Nachdem die externe Tabelle erstellt wurde, können Sie die Protobuf-Daten in BigQuery als JSON-Spalte abfragen.

Die folgende Abfrage ruft den Titel aller Alben ab, die 2022 veröffentlicht wurden, aus der externen BigQuery-Tabelle ab:

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;

Nächste Schritte

Best Practices für das Schemadesign für Protobufs