Objekttabellen erstellen

In diesem Dokument wird beschrieben, wie Sie durch Erstellen einer Objekttabelle auf unstrukturierte Daten in BigQuery zugreifen können.

Zum Erstellen einer Objekttabelle müssen Sie die folgenden Schritte ausführen:

  1. Erstellen Sie eine Verbindung, um Objektinformationen aus Cloud Storage zu lesen.
  2. Erteilen Sie die Berechtigung zum Lesen von Cloud Storage-Informationen für das Dienstkonto, das der Verbindung zugeordnet ist.
  3. Erstellen Sie die Objekttabelle und verknüpfen Sie sie mit der Anweisung CREATE EXTERNAL TABLE.

Hinweis

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the BigQuery and BigQuery Connection API APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the BigQuery and BigQuery Connection API APIs.

    Enable the APIs

    8.
  8. Achten Sie darauf, dass Ihr BigQuery-Administrator eine Verbindung erstellt und den Zugriff auf Cloud Storage eingerichtet hat.

Erforderliche Rollen

Zur Verwendung von Objekttabellen benötigen Ihre Nutzer die folgenden IAM-Berechtigungen basierend auf ihrer Rolle in Ihrer Organisation. Weitere Informationen zu Nutzerrollen finden Sie unter Sicherheitsmodell. Weitere Informationen zum Gewähren von Berechtigungen finden Sie unter Zuweisbare Rollen für Ressourcen aufrufen.

  • Data-Lake-Administrator

    Bitten Sie Ihren Administrator, Ihnen die Rolle "BigQuery-Verbindungsadministrator" (roles/bigquery.connectionAdmin) für das Projekt zuzuweisen, um die Berechtigungen abzurufen, die Sie für eine Verbindung zu Cloud Storage benötigen.

    Bitten Sie Ihren Administrator, Ihnen die Rolle "Storage-Administrator" (roles/storage.admin) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Cloud Storage-Buckets benötigen.

    Diese vordefinierte Rolle enthält die Berechtigungen, die zum Herstellen einer Verbindung zu Cloud Storage und zum Erstellen und Verwalten von Cloud Storage-Buckets erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

    Erforderliche Berechtigungen

    • bigquery.connections.create
    • bigquery.connections.get
    • bigquery.connections.list
    • bigquery.connections.update
    • bigquery.connections.use
    • bigquery.connections.delete
    • storage.bucket.*
    • storage.object.*

  • Data Warehouse-Administrator

    Bitten Sie Ihren Administrator, Ihnen die folgenden Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die zum Erstellen von Objekttabellen erforderlich sind:

    • Rolle „BigQuery-Datenbearbeiter“ (roles/bigquery.dataEditor)
    • Rolle „BigQuery-Verbindungsadministrator“ (roles/bigquery.connectionAdmin)

    Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen von Objekttabellen erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

    Erforderliche Berechtigungen

    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.connections.delegate

  • Datenanalyst

    Bitten Sie Ihren Administrator, Ihnen die folgenden Rollen für das Projekt zu erteilen, um die erforderlichen Berechtigungen für die Abfrage von Objekttabellen zu erhalten:

    • Rolle „BigQuery-Datenbetrachter“ (roles/bigquery.dataViewer)
    • Rolle „BigQuery-Verbindungsnutzer“ (roles/bigquery.connectionUser)

    Diese vordefinierte Rolle enthält die Berechtigungen, die zum Abfragen von Objekttabellen erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

    Erforderliche Berechtigungen

    • bigquery.jobs.create
    • bigquery.tables.get
    • bigquery.tables.getData
    • bigquery.readsessions.create

    Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Objekttabellen erstellen

Damit Sie eine Objekttabelle erstellen können, benötigen Sie ein vorhandenes Dataset. Weitere Informationen finden Sie unter Datasets erstellen.

So erstellen Sie eine Objekttabelle:

SQL

Verwenden Sie die Anweisung CREATE EXTERNAL TABLE.

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');

    Dabei gilt:

    • PROJECT_ID ist Ihre Projekt-ID.
    • DATASET_ID: die ID des Datasets, das die Objekttabelle enthalten soll.
    • TABLE_NAME: der Name der Objekttabelle
    • REGION: die Region oder Multiregion, die die Verbindung enthält.
    • CONNECTION_ID: die ID der Cloud-Ressourcenverbindung, die mit dieser Objekttabelle verwendet werden soll. Die Verbindung bestimmt, welches Dienstkonto zum Lesen von Daten aus Cloud Storage verwendet wird.

      Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

    • BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die von der Objekttabelle dargestellten Objekte im Format ['gs://bucket_name/[folder_name/]*'] enthält.

      Sie können in jedem Pfad ein Sternchen (*) als Platzhalterzeichen verwenden, um die in der Objekttabelle enthaltenen Objekte zu begrenzen. Beispiel: Wenn der Bucket mehrere Arter unstrukturierten Daten enthält, können Sie bestimmen, dass für die Erstellung der Objekttabelle nur PDF-Objekte genutzt werden. Dazu geben Sie ['gs://bucket_name/*.pdf'] an. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

      Sie können mehrere Buckets für die Option uris angeben. Dazu geben Sie mehrere Pfade an, z. B. ['gs://mybucket1/*', 'gs://mybucket2/folder5/*'].

      Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

    • STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Objekttabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

      Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

      Geben Sie zum Aktivieren des Metadaten-Cachings für das Intervallliteral einen Wert zwischen 30 Minuten und 7 Tagen an. Beispiel: Geben Sie INTERVAL 4 HOUR für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

    • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

      Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

      Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den Systemvorgang BQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

      Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

Beispiele

Im folgenden Beispiel wird eine Objekttabelle mit einem Veralterungsintervall eines Metadaten-Cache von 1 Tag erstellt:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

Im folgenden Beispiel wird eine Objekttabelle über die Objekte in drei Cloud Storage-Buckets erstellt:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

Im folgenden Beispiel wird eine Objekttabelle über die PDF-Objekte in einem Cloud Storage-Bucket erstellt:

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

Führen Sie den Befehl bq mk aus.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Dabei gilt:

  • PROJECT_ID ist Ihre Projekt-ID.
  • DATASET_ID: die ID des Datasets, das die Objekttabelle enthalten soll.
  • TABLE_NAME: der Name der Objekttabelle
  • REGION: die Region oder Multiregion, die die Verbindung enthält.
  • CONNECTION_ID: die ID der Cloud-Ressourcenverbindung, die mit dieser externen Tabelle verwendet werden soll. Die Verbindung bestimmt, welches Dienstkonto zum Lesen von Daten aus Cloud Storage verwendet wird.

    Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

  • BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die von der Objekttabelle dargestellten Objekte im Format gs://bucket_name/[folder_name/]* enthält.

    Sie können in jedem Pfad ein Sternchen (*) als Platzhalterzeichen verwenden, um die in der Objekttabelle enthaltenen Objekte zu begrenzen. Beispiel: Wenn der Bucket mehrere Arter unstrukturierten Daten enthält, können Sie bestimmen, dass für die Erstellung der Objekttabelle nur PDF-Objekte genutzt werden. Dazu geben Sie gs://bucket_name/*.pdf an. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

    Sie können mehrere Buckets für die Option uris angeben. Dazu geben Sie mehrere Pfade an, z. B. gs://mybucket1/*,gs://mybucket2/folder5/*.

    Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

  • STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Objekttabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

    Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

    Geben Sie zum Aktivieren des Metadaten-Cachings einen Intervallwert zwischen 30 Minuten und 7 Tagen unter Verwendung des in der INTERVAL-Datentypdokumentation beschriebenen Formats Y-M D H:M:S. Beispiel: Geben Sie 0-0 0 4:0:0 für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

  • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

    Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

    Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den Systemvorgang BQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

    Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

Beispiele

Im folgenden Beispiel wird eine Objekttabelle mit einem Veralterungsintervall eines Metadaten-Cache von 1 Tag erstellt:

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

Im folgenden Beispiel wird eine Objekttabelle über die Objekte in drei Cloud Storage-Buckets erstellt:

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

Im folgenden Beispiel wird eine Objekttabelle über die PDF-Objekte in einem Cloud Storage-Bucket erstellt:

bq mk --table \
--external_table_definition=gs://bucket1/*.pdf@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

Rufen Sie die Methode tables.insert auf. Fügen Sie ein ExternalDataConfiguration-Objekt ein, bei dem das Feld objectMetadata in der Table-Ressource auf SIMPLE gesetzt ist. die Sie übergeben.

Das folgende Beispiel zeigt, wie diese Methode mithilfe von curl aufgerufen wird:

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

In diesem Beispiel wird eine Objekttabelle mit aktiviertem Metadaten-Caching und manueller Aktualisierung erstellt.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Die Schlüsselfelder, die für eine Objekttabelle angegeben werden sollen, sind: google_bigquery_table.external_data_configuration.object_metadata, google_bigquery_table.external_data_configuration.metadata_cache_mode und google_bigquery_table.max_staleness. Weitere Informationen zu den einzelnen Ressourcen finden Sie in der Terraform BigQuery-Dokumentation. 


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.

Cloud Shell vorbereiten

  1. Rufen Sie Cloud Shell auf.

  2. Legen Sie das Google Cloud-Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

    Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

  1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

    Kopieren Sie den Beispielcode in das neu erstellte main.tf.

    Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

  3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
  4. Speichern Sie die Änderungen.
  5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich. 
    terraform init

    Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden: 

    terraform init -upgrade

Änderungen anwenden

  1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen: 
    terraform plan

    Korrigieren Sie die Konfiguration nach Bedarf.

  2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

    Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

  3. Öffnen Sie Ihr Google Cloud-Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

Objekttabellen abfragen

Sie können eine Objekttabelle wie jede andere BigQuery-Abfrage abfragen. Beispiel:

SELECT *
FROM mydataset.myobjecttable;

Beim Abfragen einer Objekttabelle werden Metadaten für die zugrunde liegenden Objekte zurückgegeben. Weitere Informationen finden Sie unter Objekttabellenschema.

Nächste Schritte