Sie können Daten aus Cloud Storage oder aus einer lokalen Datei als Batchvorgang in BigQuery laden. Die Quelldaten können folgende Formate haben:
- Avro
- Kommagetrennte Werte (CSV)
- JSON (durch Zeilenumbruch getrennt)
- ORC
- Parquet
- Firestore-Exporte, die in Cloud Storage gespeichert sind
Sie können auch den BigQuery Data Transfer Service verwenden, um wiederkehrende Ladevorgänge von Cloud Storage in BigQuery einzurichten.
Erforderliche Berechtigungen
Wenn Sie Daten in BigQuery laden möchten, benötigen Sie Berechtigungen zum Ausführen eines Ladejobs und zum Laden von Daten in neue oder vorhandene BigQuery-Tabellen und -Partitionen. Zum Laden von Daten aus Cloud Storage sind außerdem Berechtigungen für den Zugriff auf den Bucket erforderlich, der Ihre Daten enthält.
BigQuery-Berechtigungen
Die folgenden Berechtigungen sind mindestens erforderlich, um Daten in BigQuery zu laden. Sie werden benötigt, wenn Sie Daten in eine neue Tabelle oder Partition laden oder Daten in einer Tabelle oder Partition anfügen oder überschreiben möchten:
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Die folgenden vordefinierten IAM-Rollen enthalten die Berechtigungen bigquery.tables.create
und bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Die folgenden vordefinierten IAM-Rollen enthalten Berechtigungen vom Typ bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Wenn ein Nutzer mit Berechtigungen vom Typ bigquery.datasets.create
ein Dataset erstellt, hat er dafür außerdem bigquery.dataOwner
-Zugriff.
Mit bigquery.dataOwner
-Zugriff kann der Nutzer Tabellen im Dataset über einen Ladejob erstellen und aktualisieren.
Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Zugriffssteuerung.
Cloud Storage-Berechtigungen
Zum Laden von Daten aus einem Cloud Storage-Bucket benötigen Sie die Berechtigung storage.objects.get
. Wenn Sie einen URI-Platzhalter verwenden, benötigen Sie außerdem die Berechtigung storage.objects.list
.
Die vordefinierte IAM-Rolle storage.objectViewer
kann erteilt werden, um die Berechtigungen storage.objects.get
und storage.objects.list
zu gewähren.
Daten aus Cloud Storage laden
BigQuery unterstützt das Laden von Daten aus den folgenden Cloud Storage-Speicherklassen:
- Standard
- Nearline
- Coldline
- Archiv
Mehr zum Laden von Daten in BigQuery finden Sie auf der Seite zu Ihrem Datenformat:
Informationen zum Konfigurieren eines wiederkehrenden Ladevorgangs aus Cloud Storage in BigQuery finden Sie unter Cloud Storage-Übertragungen.
Überlegungen zum Standort
Beachten Sie Folgendes, wenn Sie einen Standort für Ihre Daten auswählen:
- Platzieren Sie die Cloud Storage-Buckets zum Laden von Daten am selben Standort.
- Wenn sich Ihr BigQuery-Dataset an einem multiregionalen Standort befindet, muss sich der Cloud Storage-Bucket mit den Daten, die Sie laden, in einem regionalen oder multiregionalen Bucket am selben Standort befinden. Wenn sich Ihr BigQuery-Dataset zum Beispiel in der EU befindet, muss sich der Cloud Storage-Bucket in einem regionalen oder multiregionalen Bucket in der EU befinden.
- Wenn sich Ihr Dataset an einem regionalen Standort befindet, muss der Cloud Storage-Bucket ein regionaler Bucket am selben Standort sein. Wenn sich Ihr Dataset zum Beispiel in der Region "Tokio" befindet, muss der Cloud Storage-Bucket ein regionaler Bucket in Tokio sein.
- Ausnahme: Wenn sich Ihr Dataset am multiregionalen Standort "US" befindet, können Sie Daten aus einem Cloud Storage-Bucket laden, der sich an einem beliebigen regionalen oder multiregionalen Standort befindet.
- Entwickeln Sie einen Plan zur Datenverwaltung:
- Wenn Sie eine regionale Speicherressource wie ein BigQuery-Dataset oder einen Cloud Storage-Bucket auswählen, sollten Sie einen Plan für die geografische Verwaltung Ihrer Daten entwickeln.
Weitere Informationen zu Cloud Storage-Standorten finden Sie unter Bucket-Standorte in der Cloud Storage-Dokumentation.
Der Standort eines Datasets lässt sich nach seiner Erstellung nicht mehr ändern. Sie können aber eine Kopie des Datasets erstellen oder es manuell verschieben. Weitere Informationen
Cloud Storage-URI abrufen
Wenn Sie Daten aus einer Cloud Storage-Datenquelle laden möchten, müssen Sie den Cloud Storage-URI angeben.
Der Cloud Storage-URI enthält den Namen Ihres Buckets und Ihr Objekt (Dateiname).
Wenn der Cloud Storage-Bucket beispielsweise den Namen mybucket
hat und die Datendatei den Namen myfile.csv
hat, lautet der Bucket-URI gs://mybucket/myfile.csv
.
Wenn Ihre Daten auf mehrere Dateien verteilt sind, können Sie im URI einen Platzhalter verwenden. Weitere Informationen dazu finden Sie unter Anfrage-URIs für Cloud Storage.
BigQuery unterstützt keine Quell-URIs, die nach dem anfänglichen doppelten Schrägstrich weitere, aufeinanderfolgende Schrägstriche enthalten. Cloud Storage-Objektnamen können mehrere aufeinanderfolgende Schrägstriche ("/") enthalten. BigQuery wandelt sie jedoch in einen einzelnen Schrägstrich um. Der folgende Quell-URI ist beispielsweise in Cloud Storage gültig, funktioniert aber nicht in BigQuery: gs://bucket/my//object//name
So rufen Sie den Cloud Storage-URI ab:
Öffnen Sie die Cloud Storage-Konsole.
Gehen Sie zum Standort des Objekts (Datei), das die Quelldaten enthält.
Am oberen Rand der Cloud Storage Console sehen Sie den Pfad zum Objekt. Wenn Sie den URI erstellen möchten, ersetzen Sie
gs://bucket/file
durch den entsprechenden Pfad, z. B.gs://mybucket/myfile.json
. bucket ist der Name des Cloud Storage-Buckets und file der Name des Objekts (Datei), das die Daten enthält.
Unterstützung von Platzhaltern für Cloud Storage-URIs
Wenn Ihre Cloud Storage-Daten auf mehrere Dateien verteilt sind, die einen gemeinsamen Basisnamen haben, können Sie beim Laden der Daten einen Platzhalter im URI verwenden.
Im Cloud Storage-URI hängen Sie dabei als Platzhalter ein Sternchen (*
) an den Basisnamen an. Wenn Sie beispielsweise zwei Dateien mit den Namen fed-sample000001.csv
und fed-sample000002.csv
haben, lautet dann der Bucket-URI gs://mybucket/fed-sample*
.
Sie können diesen Platzhalter-URI dann in der Cloud Console, dem bq
-Befehlszeilentool, der API oder den Clientbibliotheken verwenden.
Sie können nur einen Platzhalter für Objekte (Dateinamen) in Ihrem Bucket verwenden. Der Platzhalter kann innerhalb oder am Ende des Objektnamens stehen. Das Anhängen eines Platzhalters an den Bucketnamen wird nicht unterstützt.
Bei Google Datastore-Exporten kann nur ein URI angegeben werden, der außerdem auf .backup_info
oder .export_metadata
enden muss.
Das Sternchenzeichen ist in folgenden Fällen nicht zulässig:
- Externe Tabellen erstellen, die mit Datastore- oder Firestore-Exporten verknüpft sind
- Datastore- oder Firestore-Exportdaten aus Cloud Storage laden
Beschränkungen
Beim Laden von Daten aus einem Cloud Storage-Bucket in BigQuery gelten die folgenden Beschränkungen:
- Wenn für den Speicherort Ihres Datasets ein anderer Wert als
US
festgelegt ist, muss sich der regionale oder multiregionale Cloud Storage-Bucket in derselben Region wie das Dataset befinden. - BigQuery übernimmt bei externen Datenquellen keine Garantie für die Datenkonsistenz. Werden die zugrunde liegenden Daten während der Ausführung der Abfrage geändert, kann dies zu einem unerwarteten Verhalten führen.
Je nach Format Ihrer Cloud Storage-Quelldaten sind weitere Beschränkungen möglich. Weitere Informationen:
- CSV-Beschränkungen
- JSON-Beschränkungen
- Datastore-Exportbeschränkungen
- Firestore-Exportbeschränkungen
- Beschränkungen bei verschachtelten und wiederkehrenden Daten
Daten aus lokalen Dateien laden
Sie können mit einer der folgenden Methoden Daten aus einer lesbaren Datenquelle (z. B. von Ihrem lokalen Rechner) laden:
- Mit der Google Cloud Console
- Mit dem Befehl
bq
desbq load
-Befehlszeilentools - Mit der API
- Mit den Clientbibliotheken
Beim Laden von Daten über die Cloud Console oder das bq
-Befehlszeilentool wird automatisch ein Ladejob erstellt.
So laden Sie Daten aus einer lokalen Datenquelle:
Console
Öffnen Sie in der Cloud Console die Seite „BigQuery“.
Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Google Cloud-Projekt und wählen Sie ein Dataset aus.
Klicken Sie auf der rechten Seite des Fensters im Detailbereich auf Tabelle erstellen. Der Vorgang zum Laden von Daten ist mit dem Vorgang zum Erstellen einer leeren Tabelle identisch.
Gehen Sie auf der Seite Create table (Tabelle erstellen) im Abschnitt Source (Quelle) so vor:
Wählen Sie unter Tabelle erstellen aus die Option Hochladen aus.
Klicken Sie unter Datei auswählen auf Durchsuchen.
Gehen Sie dann zur gewünschten Datei und klicken Sie auf Öffnen. Beachten Sie, dass Platzhalter und durch Kommas getrennte Listen in lokalen Dateien nicht unterstützt werden.
Wählen Sie für File format (Dateiformat) die Option CSV, JSON (newline delimited) (JSON (durch Zeilenumbruch getrennt)), Avro, Parquet oder ORC aus.
Gehen Sie auf der Seite Create table (Tabelle erstellen) im Abschnitt Destination (Ziel) so vor:
Wählen Sie für Dataset-Name das entsprechende Dataset aus.
Geben Sie im Feld Tabellenname den Namen der Tabelle ein, die Sie in BigQuery erstellen.
Achten Sie darauf, dass Table type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.
Geben Sie im Abschnitt Schema die Schemadefinition ein.
Für CSV- und JSON-Dateien können Sie die Option Auto-detect (Automatisch erkennen) anklicken, um die automatische Schemaerkennung zu aktivieren. Die Schemainformationen sind in den Quelldaten für andere unterstützte Dateitypen selbstbeschreibend.
Sie können Schemainformationen auch manuell eingeben:
Klicken Sie dazu auf Als Text bearbeiten und geben Sie das Tabellenschema als JSON-Array ein:
Geben Sie das Schema mit Feld hinzufügen manuell ein.
Wählen Sie die entsprechenden Elemente im Abschnitt Erweiterte Optionen aus. Informationen zu den verfügbaren Optionen finden Sie unter CSV-Optionen und JSON-Optionen.
Optional: Wählen Sie unter Erweiterte Optionen die Schreibanordnung aus:
- Schreiben, wenn leer: Die Daten werden nur geschrieben, wenn die Tabelle leer ist.
- An Tabelle anfügen: Die Daten werden an das Ende der Tabelle angefügt. Dies ist die Standardeinstellung.
- Tabelle überschreiben: Alle vorhandenen Daten in der Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden.
Klicken Sie auf Tabelle erstellen.
bq
Verwenden Sie den Befehl bq load
und geben Sie das source_format
sowie den Pfad zur lokalen Datei an.
Optional: Geben Sie das Flag --location
an und legen Sie als Wert Ihren Standort fest.
Wenn Sie Daten in ein anderes Projekt als Ihr Standardprojekt laden, fügen Sie die Projekt-ID im folgenden Format dem Dataset hinzu: PROJECT_ID:DATASET
.
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
Dabei gilt:
LOCATION
: Ihr Standort. Das Flag--location
ist optional. Wenn Sie beispielsweise BigQuery in der Region Tokio verwenden, legen Sie den Wert des Flags aufasia-northeast1
fest. Mit der Datei ".bigqueryrc" können Sie für den Standort einen Standardwert festlegen.FORMAT
:CSV
,AVRO
,PARQUET
,ORC
oderNEWLINE_DELIMITED_JSON
.project_id
: Ihre Projekt-ID.dataset
: ein vorhandenes Dataset.table
: der Name der Tabelle, in die Sie Daten laden.path_to_source
: der Pfad zur lokalen Datei.schema
: ein gültiges Schema. Das Schema kann als lokale JSON-Datei bereitgestellt oder als Bestandteil des Befehls inline eingegeben werden. Sie können statt der Schemadefinition auch das Flag--autodetect
verwenden.
Darüber hinaus haben Sie die Möglichkeit, Flags für Optionen einzufügen, mit denen sich steuern lässt, wie BigQuery Ihre Daten parst. Sie können beispielsweise mit dem Flag --skip_leading_rows
festlegen, dass Header-Zeilen in einer CSV-Datei ignoriert werden. Weitere Informationen finden Sie unter CSV-Optionen und JSON-Optionen.
Beispiele:
Mit dem folgenden Befehl wird eine lokale durch Zeilenumbruch getrennte JSON-Datei (mydata.json
) in eine Tabelle namens mytable
in mydataset
in Ihrem Standardprojekt geladen. Das Schema ist in einer lokalen Schemadatei namens myschema.json
definiert.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
Mit dem folgenden Befehl wird eine lokale CSV-Datei (mydata.csv
) in eine Tabelle namens mytable
inmydataset
in myotherproject
geladen. Das Schema ist inline im Format FIELD:DATA_TYPE, FIELD:DATA_TYPE
definiert.
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
Mit dem folgenden Befehl wird eine lokale CSV-Datei (mydata.csv
) in eine Tabelle namens mytable
in mydataset
in Ihrem Standardprojekt geladen. Das Schema wird mithilfe der automatischen Schemaerkennung definiert.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von C# in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery C# API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Für lokale Dateien anderer Formate verwenden Sie anstelle vonUploadCsvOptions
die Klasse "UploadOptions" für das entsprechende Format aus der Basisklasse JobCreationOptions.
Go
Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie das entsprechende Format mit dem Attribut DataFormat vonNewReaderSource
fest.
Java
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Java API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für FormatOptions das entsprechende Format fest.
Node.js
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für den Parametermetadata
der load-Funktion das entsprechende Format fest.
PHP
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von PHP in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery PHP API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Für lokale Dateien anderer Formate geben Sie für sourceFormat das entsprechende Format an.
Python
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Python API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate geben Sie für das Attribut LoadJobConfig.source_format das entsprechende Format an.
Ruby
Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Ruby in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Ruby API.
Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für den Parameterformat
der Methode Table#load_job das entsprechende Format fest.
Beschränkungen
Das Laden von Daten aus einer lokalen Datenquelle unterliegt folgenden Beschränkungen:
- Platzhalter und durch Kommas getrennte Listen werden nicht unterstützt. Dateien müssen einzeln geladen werden.
- Wenn Sie über die klassische BigQuery-Web-UI laden, dürfen die Dateien höchstens 10 MB groß sein und nicht mehr als 16.000 Zeilen enthalten.
Komprimierte und unkomprimierte Daten laden
Das Avro-Binärformat ist das bevorzugte Format zum Laden komprimierter und unkomprimierter Daten. Avro-Daten können schneller geladen werden, da die Daten parallel gelesen werden können, selbst wenn die Datenblöcke komprimiert sind. Komprimierte Avro-Dateien werden nicht unterstützt, komprimierte Datenblöcke hingegen schon. BigQuery unterstützt die Codecs DEFLATE und Snappy für komprimierte Datenblöcke in Avro-Dateien.
Das binäre Parquet-Format ist auch eine gute Wahl, da die effiziente Spaltencodierung von Parquet in der Regel zu einer besseren Komprimierungsrate und kleineren Dateien führt. Parquet-Dateien nutzen auch Komprimierungstechniken, mit denen Dateien parallel geladen werden können. Komprimierte Parquet-Dateien werden nicht unterstützt, komprimierte Datenblöcke hingegen schon. Die Codecs Snappy, GZip und LZO_1X werden von BigQuery für komprimierte Datenblöcke in Parquet-Dateien unterstützt.
Das ORC-Binärformat bietet ähnliche Vorteile wie das Parquet-Format. Daten in ORC-Dateien können durch das parallele Lesen von Datenstreifen schnell geladen werden. Die in jedem Datenstreifen enthaltenen Zeilen werden nacheinander geladen. Verwenden Sie zum Optimieren der Ladezeit Datenstreifen mit maximal rund 256 MB. Komprimierte ORC-Dateien werden nicht unterstützt, komprimierte Dateifußzeilen und Datenstreifen hingegen schon. BigQuery unterstützt Zlib-, Snappy-, LZO- und LZ4-Komprimierung für Fußzeilen und Datenstreifen in ORC-Dateien.
Bei anderen Datenformaten wie CSV und JSON kann BigQuery unkomprimierte Dateien aufgrund der parallelen Lesevorgänge wesentlich schneller laden als komprimierte Dateien. Da unkomprimierte Dateien größer sind, kann ihre Verwendung zu Bandbreitenbeschränkungen und höheren Kosten für Daten führen, die in Cloud Storage bereitgestellt sind, bevor sie in BigQuery geladen werden. Beachten Sie außerdem, dass die Zeilenreihenfolge bei komprimierten und unkomprimierten Dateien nicht sichergestellt ist. Je nach Anwendungsfall müssen Sie die Vor- und Nachteile unbedingt abwägen.
Allgemein gilt: Wenn die Bandbreite begrenzt ist, sollten Sie Ihre CSV- und JSON-Dateien mit gzip komprimieren, bevor Sie sie in Cloud Storage hochladen. Beim Laden von Daten in BigQuery ist gzip derzeit der einzige unterstützte Komprimierungstyp für CSV- und JSON-Dateien. Wenn die Ladegeschwindigkeit für Ihre Anwendung wichtig ist und Sie viel Bandbreite zum Laden Ihrer Daten haben, lassen Sie die Dateien unkomprimiert.
An eine Tabelle anfügen oder eine Tabelle überschreiben
Zusätzliche Daten können entweder aus Quelldateien oder durch das Anfügen von Abfrageergebnissen in eine Tabelle geladen werden. Sollte das Schema der Daten nicht mit dem Schema der Zieltabelle oder -partition übereinstimmen, können Sie das Schema aktualisieren, wenn Sie Daten an das Ziel anfügen oder das Ziel überschreiben.
Wenn Sie das Schema beim Anfügen von Daten aktualisieren, können Sie in BigQuery folgende Vorgänge ausführen:
- Neue Felder hinzufügen
- Felder vom Typ
REQUIRED
in den TypNULLABLE
ändern (herunterstufen)
Beim Überschreiben einer Tabelle wird immer auch das Schema überschrieben. Schemaaktualisierungen sind beim Überschreiben einer Tabelle nicht eingeschränkt.
In der Cloud Console können Sie mit der Option Schreibeinstellung festlegen, welche Aktion beim Laden von Daten aus einer Quelldatei oder aus einem Abfrageergebnis ausgeführt werden soll. Das bq
-Befehlszeilentool und die API umfassen die folgenden Optionen:
Console-Option | bq -Tool-Flag |
BigQuery API-Attribut | Beschreibung |
---|---|---|---|
Schreiben, wenn leer | Keine | WRITE_EMPTY | Daten werden nur geschrieben, wenn die Tabelle leer ist. |
An Tabelle anfügen | --noreplace oder --replace=false . Wenn --replace nicht angegeben ist, werden Daten standardmäßig angefügt. |
WRITE_APPEND | (Standard) Daten werden an das Ende der Tabelle angefügt. |
Tabelle überschreiben | --replace oder --replace=true |
WRITE_TRUNCATE | Alle vorhandenen Daten in einer Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden. |
Kontingentrichtlinie
Informationen zu den Kontingentrichtlinien für das Laden von Daten im Batch finden Sie unter Ladejobs auf der Seite „Kontingente und Limits“.
Preise
Das Laden von Daten im Batch in BigQuery ist derzeit kostenlos. Weitere Informationen finden Sie auf der Seite Preise.