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:
- Erstellen Sie eine Verbindung, um Objektinformationen aus Cloud Storage zu lesen.
- Erteilen Sie die Berechtigung zum Lesen von Cloud Storage-Informationen für das Dienstkonto, das der Verbindung zugeordnet ist.
- Erstellen Sie die Objekttabelle und verknüpfen Sie sie mit der Anweisung
CREATE EXTERNAL TABLE
.
Hinweis
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
Enable the BigQuery and BigQuery Connection API APIs.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
Enable the BigQuery and BigQuery Connection API APIs.
- 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
- Rolle „BigQuery-Datenbearbeiter“ (
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.
- Rolle „BigQuery-Datenbetrachter“ (
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
.
Öffnen Sie in der Google Cloud Console die Seite BigQuery.
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 ObjekttabelleREGION
: 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 SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHE
aufrufen, um den Cache zu aktualisieren.Sie müssen
CACHE_MODE
festlegen, wennSTALENESS_INTERVAL
auf einen Wert größer als 0 festgelegt ist.
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 ObjekttabelleREGION
: 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 Formatgs://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 Siegs://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 FormatsY-M D H:M:S
. Beispiel: Geben Sie0-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 SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHE
aufrufen, um den Cache zu aktualisieren.Sie müssen
CACHE_MODE
festlegen, wennSTALENESS_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 mit 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.
Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.
Cloud Shell vorbereiten
- Rufen Sie Cloud Shell auf.
-
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).
-
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 alsmain.tf
bezeichnet.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
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.
- Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
- Speichern Sie die Änderungen.
-
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
-
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.
-
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.
- Ö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.