Avro-Daten aus Cloud Storage laden

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

Wenn Sie Avro-Daten aus Cloud Storage laden, können Sie Daten in eine neue Tabelle oder Partition laden bzw. an eine vorhandene Tabelle oder Partition anfügen. Ebenso können Sie 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.

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 der multiregionale Wert US festgelegt ist, muss sich der Cloud Storage-Bucket in derselben Region befinden oder in derselben Multiregion enthalten sein wie das Dataset.
  • 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.
  • BigQuery unterstützt nicht die Cloud Storage-Objektversionierung. Wenn Sie dem Cloud Storage-URI eine Generierungsnummer hinzufügen, schlägt der Ladejob fehl.

Anforderungen an Eingabedateien

Beachten Sie die folgenden Richtlinien, um resourcesExceeded-Fehler beim Laden von Avro-Dateien in BigQuery zu vermeiden:

  • Die Zeilengröße darf maximal 50 MB betragen.
  • Wenn die Zeile viele Arrayfelder oder sehr lange Arrayfelder enthält, unterteilen Sie die Arraywerte in separate Felder.

Hinweise

Erteilen Sie IAM-Rollen (Identity and Access Management), über die Nutzer die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument erhalten, und erstellen Sie ein Dataset zum Speichern Ihrer Daten.

Erforderliche Berechtigungen

Zum Laden von Daten in BigQuery benötigen Sie IAM-Berechtigungen, um einen Ladejob auszuführen und Daten in BigQuery-Tabellen und -Partitionen zu laden. Zum Laden von Daten aus Cloud Storage sind außerdem IAM-Berechtigungen für den Zugriff auf den Bucket erforderlich, der Ihre Daten enthält.

Berechtigungen zum Laden von Daten in BigQuery

Wenn Sie Daten in eine neue BigQuery-Tabelle oder -Partition laden oder eine vorhandene Tabelle oder Partition anfügen oder überschreiben möchten, benötigen Sie die folgenden IAM-Berechtigungen:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

Die folgenden vordefinierten IAM-Rollen enthalten jeweils die Berechtigungen, die zum Laden von Daten in eine BigQuery-Tabelle oder -Partition erforderlich sind:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (einschließlich der Berechtigung bigquery.jobs.create)
  • bigquery.user (einschließlich der Berechtigung bigquery.jobs.create)
  • bigquery.jobUser (einschließlich der Berechtigung bigquery.jobs.create)

Wenn Sie die Berechtigung bigquery.datasets.create haben, können Sie außerdem mit einem Ladejob Tabellen in den von Ihnen erstellten Datasets anlegen und aktualisieren.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Berechtigungen zum Laden von Daten aus Cloud Storage

Um die Berechtigungen zu erhalten, die Sie zum Laden von Daten aus einem Cloud Storage-Bucket benötigen, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage Admin (roles/storage.admin) für den Bucket zu erteilen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Laden von Daten aus einem Cloud Storage-Bucket erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Daten aus einem Cloud Storage-Bucket zu laden:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

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

Dataset und Tabelle erstellen

Zum Speichern Ihrer Daten müssen Sie ein BigQuery-Dataset und dann eine BigQuery-Tabelle in diesem Dataset erstellen.

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:
    • 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 eine neue BigQuery-Tabelle laden, wird das Tabellenschema automatisch mithilfe der Quelldaten abgerufen. Wenn BigQuery das Schema aus den Quelldaten abruft, wird die alphabetisch letzte Datei 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 verschiedenen 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 GoogleSQL-Syntax kompatibel sind. Weitere Informationen finden Sie unter Avro-Konvertierungen.

Wenn Sie ein Tabellenschema zum Erstellen externer Tabellen bereitstellen möchten, legen Sie in der BigQuery API oder im
--reference_file_schema_uri-Parameter des bq-Befehlszeilentools das referenceFileSchemaUri-Attribut auf die URL der Referenzdatei fest.

Beispiel: --reference_file_schema_uri="gs://mybucket/schema.avro".

Avro-Komprimierung

BigQuery unterstützt die folgenden Komprimierungscodecs für Avro-Dateiinhalte:

  • Snappy
  • DEFLATE

Avro-Daten in eine neue Tabelle laden

Wählen Sie eine der folgenden Optionen, um Avro-Daten aus Cloud Storage in eine neue BigQuery-Tabelle zu laden:

Console

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

    BigQuery aufrufen

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie ein Dataset aus.

  3. Maximieren Sie die Option Aktionen und klicken Sie auf Öffnen.

  4. Klicken Sie im Detailfeld auf Tabelle erstellen.

  5. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelle so 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 direkt ein. In der Google 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.

      Datei auswählen

    • Wählen Sie als Dateiformat die Option Avro aus.

  6. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen vor:

    • Wählen Sie für Dataset name (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.
  7. Im Abschnitt Schema ist muss nichts unternommen werden. Das Schema ist in Avro-Dateien selbstbeschreibend.

  8. (Optional) Wählen Sie zum Partitionieren der Tabelle die jeweiligen Optionen unter Partition and cluster settings (Partitions- und Clustereinstellungen) aus. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen.

  9. 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.

  10. Optional: Wenn Sie die Tabelle clustern möchten, geben Sie im Feld Clustering-Reihenfolge einen bis vier Feldnamen ein.

  11. (Optional) Klicken Sie auf Erweiterte Optionen.

    • Lassen Sie unter Schreibeinstellung die Option Schreiben, wenn leer ausgewählt. Diese Option erstellt eine neue Tabelle und lädt Ihre Daten in diese Tabelle.
    • Ü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.
  12. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine Avro-Datei in die neue Tabelle mytable geladen.

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

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    LOAD DATA OVERWRITE mydataset.mytable
    FROM FILES (
      format = 'avro',
      uris = ['gs://bucket/path/file.avro']);
    

  3. Klicken Sie auf Ausführen.

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

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. Mögliche Werte sind HOUR, DAY, MONTH und YEAR. Dieses Flag ist optional, wenn Sie eine Tabelle erstellen, die nach einer DATE-, DATETIME- oder TIMESTAMP-Spalte partitioniert wird. Der Standardpartitionstyp für die zeitbasierte Partitionierung ist DAY. Sie können die Partitionierungsspezifikation für eine vorhandene Tabelle nicht ändern.
  • --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:

    Weitere Informationen zu geclusterten Tabellen finden Sie unter:

    Weitere Informationen zur Tabellenverschlüsselung finden Sie unter:

Mit dem folgenden Befehl können Sie Avro-Daten in BigQuery 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 neue 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

  1. Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.

  2. Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.

  3. Das Attribut source URIs muss vollständig qualifiziert sein und das Format gs://bucket/object haben. Jeder URI kann ein Platzhalterzeichen (*) enthalten.

  4. Geben Sie das Avro-Datenformat an. Legen Sie dazu für das Attribut sourceFormat den Wert AVRO fest.

  5. 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.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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 zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

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

// 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 zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

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))

JSON-Daten aus Avro-Daten extrahiere

Es gibt zwei Möglichkeiten, dafür zu sorgen, dass Avro-Daten als JSON-Daten in BigQuery geladen werden:

  1. Annotieren Sie das Avro-Schema mit sqlType, das auf JSON gesetzt ist. Beispiel: Wenn Sie Daten mit dem folgenden Avro-Schema laden, wird die json_field-Spalte als JSON-Typ gelesen:

    {
        "type": {"type": "string", "sqlType": "JSON"},
        "name": "json_field"
    }
    
  2. Geben Sie das Schema der BigQuery-Zieltabelle explizit an und legen Sie den Spaltentyp auf JSON fest. Weitere Informationen finden Sie unter Schema angeben.

Wenn Sie JSON weder im Avro-Schema noch im BigQuery-Tabellenschema angeben, werden die Daten als STRING gelesen.

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 Google 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.

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

Console-Option bq-Tool-Flag BigQuery API-Attribut Beschreibung
Schreiben, wenn leer Nicht unterstützt WRITE_EMPTY Daten werden nur geschrieben, wenn die Tabelle leer ist.
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 --replace oder --replace=true WRITE_TRUNCATE Alle vorhandenen Daten in einer Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden. Mit dieser Aktion werden auch das Tabellenschema und die Sicherheit auf Zeilenebene gelöscht und alle Cloud KMS-Schlüssel entfernt.

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

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

Console

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

    BigQuery aufrufen

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie ein Dataset aus.

  3. Maximieren Sie die Option Aktionen und klicken Sie auf Öffnen.

  4. Klicken Sie im Detailfeld auf Tabelle erstellen.

  5. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelle so vor:

    • Wählen Sie unter Create table from (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 Google 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.

      Datei auswählen

    • Wählen Sie als Dateiformat die Option Avro aus.

  6. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen vor:

    • Wählen Sie für Dataset-Name das entsprechende Dataset aus.

      Dataset auswählen

    • 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.

  7. Im Abschnitt Schema ist muss nichts unternommen werden. Das Schema ist in Avro-Dateien selbstbeschreibend.

  8. 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 ist es mit der Google Cloud Console nicht möglich, Daten in partitionierten oder geclusterten Tabellen in einem Ladejob anzufügen bzw. zu überschreiben.

  9. Klicken Sie auf 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 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.
  10. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine Avro-Datei an die mytable-Tabelle angefügt:

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

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    LOAD DATA INTO mydataset.mytable
    FROM FILES (
      format = 'avro',
      uris = ['gs://bucket/path/file.avro']);
    

  3. Klicken Sie auf Ausführen.

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

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

  1. Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.

  2. Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.

  3. 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.

  4. Geben Sie das Datenformat an. Legen Sie dazu das Attribut configuration.load.sourceFormat auf AVRO fest.

  5. Geben Sie die Schreibeinstellung an. Legen Sie dazu das Attribut configuration.load.writeDisposition auf WRITE_TRUNCATE oder WRITE_APPEND fest.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

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

// 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

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

import io

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 = io.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üllt die Hive-Partitionierungsspalten so aus, als wären Sie Spalten in der verwalteten BigQuery-Zieltabelle. 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 ohne das Attribut logicalType BigQuery-Datentyp Hinweise
null Diese Werte werden von BigQuery ignoriert
boolean BOOLEAN
int INTEGER
long INTEGER
float FLOAT
double FLOAT
bytes BYTES
string STRING Nur UTF-8

Logische Typen

Standardmäßig ignoriert BigQuery das Attribut logicalType für die meisten Typen und verwendet stattdessen den zugrunde liegenden Avro-Typ. Um logische Avro-Typen in die entsprechenden BigQuery-Datentypen zu konvertieren, setzen Sie das Flag --use_avro_logical_types mit dem bq-Befehlszeilentool auf true oder legen Sie das Attribut useAvroLogicalTypes in der Jobressource fest, wenn Sie die Methode jobs.insert aufrufen, um einen Ladejob zu erstellen.

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

Logischer Avro-Typ BigQuery-Datentyp: Logischer Typ deaktiviert BigQuery-Datentyp: Logischer Typ aktiviert
date INTEGER DATE
time-millis INTEGER TIME
time-micros INTEGER (umgewandelt von LONG) TIME
timestamp-millis INTEGER (umgewandelt von LONG) TIMESTAMP
timestamp-micros INTEGER (umgewandelt von LONG) TIMESTAMP
local-timestamp-millis INTEGER (umgewandelt von LONG) DATETIME
local-timestamp-micros INTEGER (umgewandelt von LONG) DATETIME
Dauer BYTES (umgewandelt vom Typ fixed der Größe 12) BYTES (umgewandelt vom Typ fixed der Größe 12)
decimal NUMERIC, BIGNUMERIC, oder STRING (sieheLogischer Typ "decimal"). NUMERIC, BIGNUMERIC, oder STRING (sieheLogischer Typ "decimal").

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

Logischer Typ "date"

Geben Sie in jeder Avro-Datei, die Sie laden möchten, logische Datumstypen im folgenden Format an:

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

Logischer Typ "decimal"

Die logischen Typen Decimal können in die Typen NUMERIC, BIGNUMERIC oder STRING umgewandelt werden. Der umgewandelte Typ hängt von den Genauigkeits- und Skalierungsparametern des logischen Typs decimal und den angegebenen Dezimalzieltypen ab. Geben Sie den Dezimalzieltyp so an:

Wenn die dezimalen Zieltypen nicht angegeben sind, können Sie aus Gründen der Abwärtskompatibilität eine Avro-Datei mit einer bytes-Spalte mit dem logischen Typ decimal in eine BYTES-Spalte einer vorhandenen Tabelle laden. In diesem Fall wird der logische Typ decimal für die Spalte in der Avro-Datei ignoriert. Dieser Conversion-Modus wurde verworfen und wird demnächst möglicherweise entfernt.

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

Logischer Typ "time"

In jeder Avro-Datei, die Sie laden möchten, müssen Sie logische Zeittypen in einem der folgenden Formate angeben.

Für eine Genauigkeit im Millisekundenbereich:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Für eine Genauigkeit im Mikrosekundenbereich:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Logischer Typ "timestamp"

In jeder Avro-Datei, die Sie laden möchten, müssen Sie logische Zeitstempeltypen in einem der folgenden Formate angeben.

Für eine Genauigkeit im Millisekundenbereich:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Für eine Genauigkeit im Mikrosekundenbereich:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Logischer Typ „Local-Timestamp“

In jeder Avro-Datei, die Sie laden möchten, müssen Sie einen logischen Typ „local-timestamp“ in einem der folgenden Formate angeben.

Für eine Genauigkeit im Millisekundenbereich:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Für eine Genauigkeit im Mikrosekundenbereich:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

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.
  • Größe wird ignoriert

Beschränkungen

  • Die verschachtelte Arrayformatierung wird in BigQuery nicht unterstützt. Avro-Dateien mit diesem Format müssen vor dem Import konvertiert werden.
  • In einer Avro-Datei dürfen Namen und Namespaces für einen vollständigen Namen nur alphanumerische Zeichen und den Unterstrich _ enthalten. Der folgende reguläre Ausdruck zeigt die zulässigen Zeichen: [A-Za-z_][A-Za-z0-9_]*

Weitere Informationen finden Sie unter Limits für BigQuery-Ladejobs.