Avro-Daten aus Cloud Storage laden

Avro-Dateien aus Cloud Storage laden

Avro ist ein Open-Source-Datenformat, in dem serialisierte Daten mit dem jeweiligen Schema in einer Datei gebündelt werden.

Sie können Avro-Daten aus Cloud Storage in eine neue Tabelle oder Partition laden bzw. an eine vorhandene Tabelle oder Partition anfügen. Damit lässt sich auch eine Tabelle oder Partition überschreiben. Beim Laden von Daten in BigQuery werden die Daten in ein Spaltenformat für Capacitor (BigQuery-Speicherformat) umgewandelt.

Wenn Sie Daten aus Cloud Storage in eine BigQuery-Tabelle laden, muss sich das Dataset, das die Tabelle enthält, am selben regionalen oder multiregionalen Standort wie der Cloud Storage-Bucket befinden.

Informationen zum Laden von Avro-Daten aus einer lokalen Datei finden Sie unter Daten aus einer lokalen Datenquelle in BigQuery laden.

Vorteile von Avro

Avro ist das bevorzugte Format zum Laden von Daten in BigQuery. Das Laden von Avro-Dateien hat gegenüber CSV und JSON (durch Zeilenumbruch getrennt) folgende Vorteile:

Für das Avro-Binärformat gilt:
- Es bietet kürzere Ladezeiten. Die Daten können parallel gelesen werden, auch wenn die Datenblöcke komprimiert sind.
- Es erfordert keine manuellen Eingaben oder Serialisierung.
- ist einfacher zu analysieren, da keine Codierungsprobleme wie in anderen Formaten wie ASCII auftreten.
Wenn Sie Avro-Dateien in BigQuery laden, wird das Tabellenschema automatisch aus den selbstbeschreibenden Quelldaten abgerufen.

Avro-Schemas

Wenn Sie Avro-Dateien in BigQuery laden, wird das Tabellenschema automatisch mithilfe der Quelldaten abgerufen. Wenn BigQuery das Schema aus den Quelldaten abruft, wird die letzte Datei in alphabetischer Reihenfolge verwendet.

In Cloud Storage gibt es z. B. die folgenden Avro-Dateien:

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

Wenn Sie diesen Befehl im bq-Befehlszeilentool ausführen, werden alle Dateien (als durch Kommas getrennte Liste) geladen und das Schema wird von mybucket/01/b.avro abgeleitet:

bq load \
--source_format=AVRO \
dataset.table \
"gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

Wenn Sie mehrere Avro-Dateien mit unterschiedlichen Avro-Schemas importieren, müssen alle Schemas mit der Schema-Auflösung von Avro kompatibel sein.

Wenn das Schema in BigQuery erkannt wird, werden bestimmte Avro-Datentypen in BigQuery-Datentypen konvertiert, damit sie mit der BigQuery-SQL-Syntax kompatibel sind. Weitere Informationen finden Sie unter Avro-Konvertierungen.

Avro-Komprimierung

BigQuery unterstützt die folgenden Komprimierungscodecs für Datenblöcke in Avro-Dateien:

Snappy
DEFLATE

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, ist außerdem die Berechtigung storage.objects.list erforderlich.

Die vordefinierte IAM-Rolle storage.objectViewer kann erteilt werden, um Berechtigungen der Typen storage.objects.get und storage.objects.list zu gewähren.

Avro-Daten in eine neue Tabelle laden

Sie können Avro-Daten mit den folgenden Methoden in eine neue Tabelle laden:

Mit der Cloud Console oder der klassischen Web-UI
Mit dem Befehl bq load im bq-Befehlszeilentool
Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
Mit den Clientbibliotheken

So laden Sie Avro-Daten aus Cloud Storage in eine neue BigQuery-Tabelle:

Console

Öffnen Sie in der Cloud Console die Seite "BigQuery".

Zur Seite "BigQuery"
Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.
Klicken Sie auf der rechten Seite des Fensters im Detailbereich auf Create table (Tabelle erstellen). Der Vorgang zum Laden von Daten entspricht dem Vorgang zum Erstellen einer leeren Tabelle.
Gehen Sie auf der Seite Tabelle erstellen im Bereich Quelle wie folgt vor:
- Wählen Sie unter Tabelle erstellen aus die Option "Google Cloud Storage" aus.
- Suchen Sie im Feld für die Quelle nach dem Cloud Storage-URI oder geben Sie ihn ein. In der Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die von Ihnen erstellte Tabelle enthält.
- Wählen Sie als Dateiformat die Option Avro aus.
Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen vor:
- Wählen Sie für Dataset-Name das entsprechende Dataset aus.
- Achten Sie darauf, dass Table Type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.
- Geben Sie im Feld Table name (Tabellenname) den Namen der Tabelle ein, die Sie in BigQuery erstellen.
Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Avro-Dateien selbstbeschreibend.
(Optional) Wählen Sie zum Partitionieren der Tabelle die jeweiligen Optionen unter Partitions- und Clustereinstellungen aus:
- Zum Erstellen einer partitionierten Tabelle klicken Sie auf Keine Partitionierung, wählen dann Nach Feld partitionieren und anschließend eine DATE- oder TIMESTAMP-Spalte aus. Diese Option ist nicht verfügbar, wenn Ihr Schema keine DATE- oder TIMESTAMP-Spalte enthält.
- Zum Erstellen einer nach Aufnahmezeit partitionierten Tabelle klicken Sie auf Keine Partitionierung und wählen dann Nach Aufnahmezeit partitionieren aus.
Optional: Klicken Sie unter Partitionierungsfilter auf das Kästchen Partitionsfilter anfordern, damit Nutzer eine WHERE-Klausel zum Angeben der abzufragenden Partitionen einfügen müssen. Das Anfordern eines Partitionsfilters kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Partitionierte Tabellen abfragen. Diese Option ist nicht verfügbar, wenn Keine Partitionierung ausgewählt ist.
Optional: Wenn Sie die Tabelle clustern möchten, geben Sie im Feld Clustering-Reihenfolge einen bis vier Feldnamen ein.
(Optional) Klicken Sie auf Erweiterte Optionen.
- Lassen Sie unter Schreibeinstellung die Option Schreiben, wenn leer ausgewählt. Mit dieser Option werden eine neue Tabelle erstellt und Ihre Daten in diese Tabelle geladen.
- Übernehmen Sie für Number of errors allowed (Anzahl zulässiger Fehler) den Standardwert 0 oder geben Sie an, wie viele Zeilen mit Fehlern maximal ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl.
- Übernehmen Sie unter Unbekannte Werte das Kästchen Unbekannte Werte ignorieren ohne Häkchen. Diese Option gilt nur für CSV- und JSON-Dateien.
- Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
Klicken Sie auf Tabelle erstellen.

Klassische UI

Rufen Sie die BigQuery-Web-UI auf.
Zur BigQuery-Web-UI
Bewegen Sie den Mauszeiger im Navigationsbereich auf ein Dataset. Klicken Sie auf den Abwärtspfeil und dann auf Neue Tabelle erstellen. Der Vorgang zum Laden von Daten entspricht dem Vorgang zum Erstellen einer leeren Tabelle.
Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelldaten so vor:
- Klicken Sie auf Aus Quelle erstellen.
- Wählen Sie unter Speicherort die Option Cloud Storage aus und geben Sie im Quellfeld den Cloud Storage-URI ein. In der BigQuery-Web-UI kann zwar nur ein URI eingefügt werden, Platzhalter werden aber unterstützt. Der Cloud Storage-Bucket muss sich am selben Speicherort wie das Dataset befinden, das die von Ihnen erstellte Tabelle enthält.
- Wählen Sie als Dateiformat die Option Avro aus.
Gehen Sie im Abschnitt Zieltabelle folgendermaßen vor:
- Wählen Sie für Tabellenname das entsprechende Dataset aus und geben Sie im Namensfeld für die Tabelle den Namen der Tabelle ein, die Sie in BigQuery erstellen.
- Achten Sie darauf, dass Table type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.
Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Avro-Dateien selbstbeschreibend.
Optional: Gehen Sie im Bereich Optionen so vor:
- Übernehmen Sie für Number of errors allowed (Anzahl zulässiger Fehler) den Standardwert 0 oder geben Sie an, wie viele Zeilen mit Fehlern maximal ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl.
- Übernehmen Sie unter Schreibeinstellung die Option Schreiben, wenn leer. Mit dieser Option werden eine neue Tabelle erstellt und Ihre Daten in diese Tabelle geladen.
- So partitionieren Sie die Tabelle:
  - Klicken Sie unter Partitionierungstyp auf Keiner und wählen Sie Tag aus.
  - Gehen Sie für Partitionierungsfeld so vor:
  - Wählen Sie zum Erstellen einer partitionierten Tabelle eine DATE- oder TIMESTAMP-Spalte aus. Diese Option ist nicht verfügbar, wenn Ihr Schema keine DATE- oder TIMESTAMP-Spalte enthält.
  - Übernehmen Sie zum Erstellen einer nach Aufnahmezeit partitionierten Tabelle den Standardwert _PARTITIONTIME.
  - Klicken Sie auf das Kästchen Partitionsfilter anfordern, wenn Nutzer beim Erstellen einer Tabelle mithilfe einer eingefügten WHERE-Klausel die Partitionen angeben sollen, die abgefragt werden sollen. Das Anfordern eines Partitionsfilters kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Partitionierte Tabellen abfragen. Diese Option ist nicht verfügbar, wenn für Partitionierungstyp der Wert Keiner festgelegt ist.
- Zum Clustern der Tabelle im Feld Clustering-Felder können Sie einen bis vier Feldnamen eingeben.
- Wählen Sie unter Destination encryption die Option Customer-managed encryption aus, um einen Cloud Key Management Service-Schlüssel zum Verschlüsseln der Tabelle zu verwenden. Wenn Sie die Einstellung Default übernehmen, verschlüsselt BigQuery inaktive Daten mit einem von Google verwalteten Schlüssel.
Klicken Sie auf Tabelle erstellen.

bq

Verwenden Sie den Befehl bq load, geben Sie AVRO mit dem Flag --source_format an und fügen Sie einen Cloud Storage-URI ein. Sie können einen einzelnen URI, eine durch Kommas getrennte Liste von URIs oder einen URI mit Platzhalter einfügen.

Optional: Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

Andere optionale Flags sind:

--time_partitioning_type: Aktiviert die zeitbasierte Partitionierung für eine Tabelle und legt den Partitionstyp fest. Der einzig mögliche Wert ist derzeit DAY. Er generiert eine Partition pro Tag. Dieses Flag ist optional, wenn Sie eine Tabelle erstellen, die nach einer DATE- oder TIMESTAMP-Spalte partitioniert wird.
--time_partitioning_expiration: Eine Ganzzahl, die (in Sekunden) angibt, wann eine zeitbasierte Partition gelöscht werden soll. Die Ablaufzeit entspricht dem UTC-Datum der Partition plus dem ganzzahligen Wert.
--time_partitioning_field: Die DATE- oder TIMESTAMP-Spalte zum Erstellen einer partitionierten Tabelle. Wenn die zeitbasierte Partitionierung ohne Angabe dieses Werts aktiviert wird, erstellt BigQuery eine nach Aufnahmezeit partitionierte Tabelle.
--require_partition_filter: Wenn diese Option aktiviert ist, müssen die Nutzer eine WHERE-Klausel zur Angabe der abzufragenden Partitionen einfügen. Das Anfordern eines Partitionsfilters kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Partitionierte Tabellen abfragen.
--clustering_fields: Eine durch Kommas getrennte Liste mit bis zu vier Spaltennamen zum Erstellen einer geclusterten Tabelle.
--destination_kms_key: Der Cloud KMS-Schlüssel für die Verschlüsselung der Tabellendaten.

Weitere Informationen zu partitionierten Tabellen finden Sie unter:
- Partitionierte Tabellen erstellen und verwenden
- Nach Aufnahmezeit partitionierte Tabellen erstellen und verwenden
Weitere Informationen zu geclusterten Tabellen finden Sie unter:
- Geclusterte Tabellen erstellen und verwenden
Weitere Informationen zur Tabellenverschlüsselung finden Sie unter:
- Daten mit Cloud KMS-Schlüsseln schützen

Geben Sie den folgenden Befehl ein, um Avro-Daten in BigQuery zu laden:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

Dabei gilt:

location ist Ihr Standort. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, können Sie für das Flag den Wert asia-northeast1 festlegen. Mit der Datei .bigqueryrc können Sie einen Standardwert für den Standort festlegen.
format ist AVRO.
dataset ist ein vorhandenes Dataset.
table ist der Name der Tabelle, in die Sie Daten laden.
path_to_source ist ein vollständig qualifizierter Cloud Storage-URI oder eine durch Kommas getrennte Liste von URIs. Platzhalter werden ebenfalls unterstützt.

Beispiele:

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.avro in eine Tabelle mit dem Namen mytable in mydataset geladen.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.avro in eine nach Aufnahmezeit partitionierte Tabelle mit dem Namen mytable in mydataset geladen:

    bq load \
    --source_format=AVRO \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.avro in eine partitionierte Tabelle mit dem Namen mytable in mydataset geladen. Die Tabelle ist nach der Spalte mytimestamp partitioniert.

    bq load \
    --source_format=AVRO \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Mit dem folgenden Befehl werden Daten aus mehreren Dateien in gs://mybucket/ in eine Tabelle namens mytable in mydataset geladen. Für den Cloud Storage-URI wird ein Platzhalter verwendet.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

Mit dem folgenden Befehl werden Daten aus mehreren Dateien in gs://mybucket/ in eine Tabelle namens mytable in mydataset geladen. Der Befehl enthält eine durch Kommas getrennte Liste von Cloud Storage-URIs mit Platzhaltern.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.
Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.
Das Attribut source URIs muss vollständig qualifiziert sein und das Format gs://bucket/object haben. Jeder URI kann ein Platzhalterzeichen (*) enthalten.
Geben Sie das Avro-Datenformat an. Legen Sie dazu für das Attribut sourceFormat den Wert AVRO fest.
Rufen Sie zum Prüfen des Jobstatus jobs.get(job_id*) auf, wobei job_id die ID des Jobs ist, der von der ursprünglichen Anfrage zurückgegeben wurde.
- Wenn status.state = DONE zurückgegeben wird, wurde der Job erfolgreich abgeschlossen.
- Wenn das Attribut status.errorResult zurückgegeben wird, ist die Anfrage fehlgeschlagen. Das Objekt enthält in diesem Fall Angaben zur Fehlerursache. Wenn eine Anfrage fehlschlägt, wird keine Tabelle erstellt und es werden keine Daten geladen.
- Wenn das Attribut status.errorResult nicht vorhanden ist, wurde der Job erfolgreich abgeschlossen. Es können aber einige nicht schwerwiegende Fehler aufgetreten sein, z. B. Probleme beim Importieren einiger Zeilen. Nicht schwerwiegende Fehler werden im Attribut status.errors des Objekts des zurückgegebenen Jobs aufgeführt.

API-Hinweise:

Ladejobs sind atomar und konsistent. Wenn ein Ladejob fehlschlägt, sind keine der zu ladenden Daten verfügbar. Wenn ein Ladejob erfolgreich ist, sind alle Daten verfügbar.
Erstellen Sie als Best Practice eine nur einmal vorkommende ID und übergeben Sie diese als jobReference.jobId, wenn jobs.insert zum Erstellen eines Ladejobs aufgerufen wird. Diese Vorgehensweise ist weniger anfällig für Netzwerkfehler, da der Client anhand der bekannten Job-ID einen Abruf oder einen neuen Versuch ausführen kann.
Das Aufrufen von jobs.insert für eine bestimmte Job-ID ist idempotent. Das bedeutet, dass Sie den Aufruf für dieselbe Job-ID beliebig oft wiederholen können. Höchstens einer dieser Vorgänge ist dann erfolgreich.

Java

Auf GitHub ansehen

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

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.

Auf GitHub ansehen Feedback

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvro() {
  // Imports a GCS file into a table with Avro source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

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.

Auf GitHub ansehen Feedback

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(source_format=bigquery.SourceFormat.AVRO)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Avro-Daten an eine Tabelle anfügen oder Tabelle mit Avro-Daten überschreiben

Zusätzliche Daten können entweder aus Quelldateien oder durch das Anfügen von Abfrageergebnissen in eine Tabelle geladen werden.

In der Console oder der klassischen Web-UI von BigQuery können Sie mit der Option Write preference (Schreibeinstellung) festlegen, welche Aktion beim Laden von Daten aus einer Quelldatei oder aus einem Abfrageergebnis ausgeführt werden soll.

Sie haben folgende Möglichkeiten, wenn Sie zusätzliche Daten in eine Tabelle laden:

Cloud Console-Option	Option der klassischen Web-UI	Flag des `bq`-Befehlszeilentools	BigQuery API-Attribut	Beschreibung
Schreiben, wenn leer	Schreiben, wenn leer	–	`WRITE_EMPTY`	Daten werden nur geschrieben, wenn die Tabelle leer ist.
An Tabelle anfügen	Append to table (An Tabelle anfügen)	`--noreplace` oder `--replace=false`. Wenn `--[no]replace` nicht angegeben ist, werden Daten standardmäßig angefügt.	`WRITE_APPEND`	(Standard) Daten werden an das Ende der Tabelle angefügt.
Tabelle überschreiben	Tabelle überschreiben	`--replace` oder `--replace=true`	`WRITE_TRUNCATE`	Alle vorhandenen Daten in einer Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden.

Wenn Sie Daten in eine vorhandene Tabelle laden, kann der Ladejob die Daten anfügen oder die Tabelle damit überschreiben.

Mit den folgenden Methoden können Sie Daten an Tabellen anfügen oder in diesen überschreiben:

Mit der Cloud Console oder der klassischen Web-UI
Mit dem Befehl bq load im bq-Befehlszeilentool
Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
Mit den Clientbibliotheken

So fügen Sie Avro-Daten an eine Tabelle an oder überschreiben die Tabelle damit:

Console

Öffnen Sie in der Cloud Console die Seite "BigQuery".

Zur Seite "BigQuery"
Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.
Klicken Sie auf der rechten Seite des Fensters im Detailbereich auf Tabelle erstellen. Der Vorgang zum Anfügen und Überschreiben von Daten in einem Ladejob ist mit dem Vorgang zum Erstellen einer Tabelle in einem Ladejob identisch.
Gehen Sie auf der Seite Tabelle erstellen im Bereich Quelle wie folgt vor:
- Wählen Sie unter Tabelle erstellen aus die Option "Google Cloud Storage" aus.
- Suchen Sie im Feld für die Quelle nach dem Cloud Storage-URI oder geben Sie ihn ein. In der Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort befinden wie das Dataset, das die Tabelle enthält, in der Sie Daten anfügen oder überschreiben.
- Wählen Sie als Dateiformat die Option Avro aus.
Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen vor:
- Wählen Sie für Dataset-Name das entsprechende Dataset aus.
- Geben Sie im Feld für den Tabellennamen den Namen der Tabelle ein, in der Daten in BigQuery angefügt oder überschrieben werden.
- Achten Sie darauf, dass Table type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.
Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Avro-Dateien selbstbeschreibend.

Hinweis: Das Schema der Tabelle kann beim Anfügen oder Überschreiben geändert werden. Weitere Informationen zu unterstützten Schemaänderungen während eines Ladevorgangs finden Sie unter Tabellenschemas ändern.
Behalten Sie für Partitions- und Clustereinstellungen die Standardwerte bei. Sie können eine Tabelle nicht durch Anfügen oder Überschreiben von Daten in eine partitionierte oder geclusterte Tabelle umwandeln. Außerdem unterstützt die Cloud Console das Anfügen bzw. Überschreiben von Daten in partitionierten oder geclusterten Tabellen in einem Ladejob nicht.
Klicken Sie auf Advanced options (Erweiterte Optionen).
- Wählen Sie für Write preference (Schreibeinstellung) die Option Append to table (An Tabelle anfügen) oder Overwrite table (Tabelle überschreiben) aus.
- Übernehmen Sie für Number of errors allowed (Anzahl zulässiger Fehler) den Standardwert 0 oder geben Sie an, wie viele Zeilen mit Fehlern maximal ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl.
- Übernehmen Sie unter Unbekannte Werte das Kästchen Unbekannte Werte ignorieren ohne Häkchen. Diese Option gilt nur für CSV- und JSON-Dateien.
- Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
Klicken Sie auf Create table (Tabelle erstellen).

Klassische UI

Rufen Sie die BigQuery-Web-UI auf.
Zur BigQuery-Web-UI
Bewegen Sie den Mauszeiger im Navigationsbereich auf ein Dataset. Klicken Sie auf den Abwärtspfeil und dann auf Neue Tabelle erstellen. Der Vorgang zum Anfügen und Überschreiben von Daten in einem Ladejob entspricht dem Vorgang zum Erstellen einer Tabelle in einem Ladejob.
Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelldaten so vor:
- Wählen Sie unter Speicherort die Option Cloud Storage aus und geben Sie im Quellfeld den Cloud Storage-URI ein. In der UI kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort befinden wie das Dataset mit der Tabelle, in der Sie Daten anfügen bzw. überschreiben.
- Wählen Sie als File format (Dateiformat) die Option Avro aus.
Gehen Sie auf der Seite Create Table (Tabelle erstellen) im Abschnitt Destination Table (Zieltabelle) so vor:
- Wählen Sie als Table name (Tabellenname) das entsprechende Dataset aus und geben Sie im Namensfeld für die Tabelle den Namen der Tabelle ein, in der Daten angefügt oder überschrieben werden sollen.
- Achten Sie darauf, dass Table type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.
Im Abschnitt Schema ist keine Aktion erforderlich. Schemainformationen sind in den Avro-Dateien selbstbeschreibend.

Hinweis: Das Schema der Tabelle kann beim Anfügen oder Überschreiben geändert werden. Weitere Informationen zu unterstützten Schemaänderungen während eines Ladevorgangs finden Sie unter Tabellenschemas ändern.
Im Bereich Optionen gehen Sie so vor:
- Übernehmen Sie für Number of errors allowed (Anzahl zulässiger Fehler) den Standardwert 0 oder geben Sie an, wie viele Zeilen mit Fehlern maximal ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl.
- Wählen Sie unter Schreibeinstellung die Option An Tabelle anfügen oder Tabelle überschreiben aus.
- Behalten Sie die Standardwerte für Partitionierungstyp, Partitionierungsfeld, Partitionsfilter anfordern und Clustering-Felder bei. Sie können eine Tabelle nicht durch Anfügen oder Überschreiben von Daten in eine partitionierte oder geclusterte Tabelle konvertieren. Außerdem unterstützt die Web-UI das Anfügen bzw. Überschreiben von Daten in partitionierten oder geclusterten Tabellen in einem Ladejob nicht.
- Wählen Sie unter Destination encryption die Option Customer-managed encryption aus, um einen Cloud Key Management Service-Schlüssel zum Verschlüsseln der Tabelle zu verwenden. Wenn Sie die Einstellung Default übernehmen, verschlüsselt BigQuery inaktive Daten mit einem von Google verwalteten Schlüssel.
Klicken Sie auf Tabelle erstellen.

bq

Geben Sie den Befehl bq load mit dem Flag --replace ein, um die Tabelle zu überschreiben. Verwenden Sie das Flag --noreplace, um Daten an die Tabelle anzufügen. Wenn kein Flag angegeben ist, werden Daten standardmäßig angefügt. Geben Sie das Flag --source_format an und legen Sie dafür AVRO fest. Da Avro-Schemas automatisch aus den sich selbst beschreibenden Quelldaten abgerufen werden, müssen Sie keine Schemadefinition angeben.

Optional: Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

Andere optionale Flags sind:

--destination_kms_key: Der Cloud KMS-Schlüssel für die Verschlüsselung der Tabellendaten.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Dabei gilt:

location ist Ihr Standort. Das Flag --location ist optional. Mit der Datei .bigqueryrc können Sie für den Standort einen Standardwert festlegen.
format ist AVRO.
dataset ist ein vorhandenes Dataset.
table ist der Name der Tabelle, in die Sie Daten laden.
path_to_source ist ein vollständig qualifizierter Cloud Storage-URI oder eine durch Kommas getrennte Liste von URIs. Platzhalter werden ebenfalls unterstützt.

Beispiele:

Der folgende Befehl lädt Daten aus gs://mybucket/mydata.avro und überschreibt eine Tabelle namens mytable in mydataset.

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.avro geladen und an eine Tabelle namens mytable in mydataset angefügt.

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Informationen zum Anfügen und Überschreiben von partitionierten Tabellen über das bq-Befehlszeilentool finden Sie unter Daten in partitionierten Tabellen anfügen und überschreiben.

API

Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.
Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.
Das Attribut source URIs muss vollständig qualifiziert sein und das Format gs://bucket/object haben. Sie können mehrere URIs als durch Kommas getrennte Liste einfügen. Platzhalter werden ebenfalls unterstützt.
Geben Sie das Datenformat an. Legen Sie dazu das Attribut configuration.load.sourceFormat auf AVRO fest.
Geben Sie die Schreibeinstellung an. Legen Sie dazu das Attribut configuration.load.writeDisposition auf WRITE_TRUNCATE oder WRITE_APPEND fest.

Java

Auf GitHub ansehen

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Auf GitHub ansehen Feedback

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Auf GitHub ansehen Feedback

import six

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = six.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.AVRO,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Nach Hive partitionierte Avro-Daten laden

BigQuery unterstützt das Laden von mit Hive partitionierten Avro-Daten, die in Cloud Storage gespeichert sind, und fügt die Daten in die Hive-Partitionierungsspalten als Spalten in der verwalteten BigQuery-Zieltabelle ein. Weitere Informationen finden Sie unter Extern partitionierte Daten aus Cloud Storage laden.

Avro-Konvertierungen

BigQuery konvertiert Avro-Datentypen in folgende BigQuery-Datentypen:

Einfache Typen

Avro-Datentyp	BigQuery-Datentyp	Hinweise
null	Diese Werte werden von BigQuery ignoriert
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
Byte mit dem logischen Typ `decimal`	NUMERIC
string	STRING	Nur UTF-8

Komplexe Typen

Avro-Datentyp	BigQuery-Datentyp	Hinweise
record	RECORD	Aliasse werden ignoriert. Doc wird in eine Feldbeschreibung umgewandelt. Standardwerte werden bei Lesezeit eingestellt. Die Reihenfolge wird ignoriert. Rekursive Felder werden ausgelassen – beibehalten wird nur die erste Verschachtelungsebene von rekursiven Feldern.
enum	STRING	Der String ist der symbolische Wert von enum. Aliasse werden ignoriert. Doc wird in eine Feldbeschreibung umgewandelt.
array	Wiederkehrende Felder	Arrays von Arrays werden nicht unterstützt. Arrays, die nur NULL-Typen enthalten, werden ignoriert.
map<T>	RECORD	BigQuery konvertiert das Avro-Feld "map<T>" in den wiederkehrenden Datentyp RECORD mit zwei Feldern: einem Schlüssel und einem Wert. BigQuery speichert den Schlüssel als STRING und konvertiert den Wert in seinen entsprechenden Datentyp in BigQuery.
union	Feld, in dem Nullwerte zulässig sind RECORD mit einer Liste von Feldern, in denen Nullwerte zulässig sind	Wenn "union" lediglich einen Nicht-Null-Typ hat, wird es in ein Feld, in dem Nullwerte zulässig sind, konvertiert. Andernfalls wird "union" in den Datentyp RECORD mit einer Liste von Feldern, in denen Nullwerte zulässig sind, konvertiert. Nur eines dieser Felder wird bei Lesezeit eingestellt.
fixed	BYTES	Aliasse werden ignoriert. Die Größe wird ignoriert.

Logische Typen

Standardmäßig ignoriert BigQuery das Attribut logicalType und verwendet stattdessen den zugrunde liegenden Avro-Typ.

Logischer Avro-Typ	BigQuery-Datentyp
date	INTEGER
time-millis	INTEGER
time-micros	INTEGER (umgewandelt von LONG)
timestamp-millis	INTEGER (umgewandelt von LONG)
timestamp-micros	INTEGER (umgewandelt von LONG)
duration	BYTES (umgewandelt vom Typ `fixed` der Größe 12)
decimal	NUMERIC (siehe Logischer Typ "decimal")

Wenn Sie die Umwandlung von logischen Avro-Typen in die entsprechenden BigQuery-Datentypen mit dem bq-Befehlszeilentool aktivieren möchten, legen Sie das Flag --use_avro_logical_types auf True fest. Alternativ können Sie auch das Attribut useAvroLogicalTypes in der Jobressource angeben, wenn Sie die Methode jobs.insert zum Erstellen eines Ladejobs aufrufen.

Die folgende Tabelle zeigt die Umwandlung von logischen Avro-Typen in BigQuery-Datentypen.

Logischer Avro-Typ	Umgewandelter BigQuery-Datentyp
date	DATE
time-millis	TIME
time-micros	TIME
timestamp-millis	TIMESTAMP
timestamp-micros	TIMESTAMP
duration	BYTES (umgewandelt vom Typ "fixed" der Größe 12)
decimal	NUMERIC (siehe Logischer Typ "decimal")

Weitere Informationen zu Avro-Datentypen finden Sie in der Spezifikation zu Apache Avro™ 1.8.2.

Logischer Typ "decimal"

Ein Avro-Typ bytes mit einem logischen Typ decimal darf für precision höchstens einen Wert von 38 (Gesamtzahl der Ziffern) und höchstens einen Wert von scale von 9 (Ziffern rechts von der Dezimalzahl) haben. Die Anzahl der Ziffern des ganzzahligen Teils, die der Differenz aus precision und scale entspricht, darf 29 nicht übersteigen. Beispielsweise wird decimal mit 38 für precision und 9 für scale unterstützt, da die Anzahl der Ziffern des ganzzahligen Teils 29 beträgt. decimal mit 38 für precision und 5 für scale wird nicht unterstützt, da die Anzahl der Ziffern des ganzzahligen Teils 33 beträgt.

Wenn Sie eine Avro-Datei, die eine bytes-Spalte mit dem logischen Typ decimal enthält, in eine vorhandene Tabelle laden, kann der Datentyp der Spalte in der Schemadefinition der Tabelle entweder BYTES oder NUMERIC sein. Ist der Datentyp der Spalte BYTES, wird der logische Typ decimal für die Spalte in der Avro-Datei ignoriert.

Weitere Informationen zum logischen Avro-Typ decimal finden Sie in der Spezifikation zu Apache Avro™ 1.8.2.