Avro-Daten aus Cloud Storage laden

Avro-Dateien aus Cloud Storage laden

Avro ist ein Open-Source-Datenformat, mit 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.

Hinweis: BigQuery unterstützt das Laden von Avro-Schemadateien (.avsc) nicht. Wenn Sie ein Schema in BigQuery importieren möchten, müssen Sie eine JSON-Schemadatei angeben.

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

Avro-Daten in eine neue Tabelle laden

Sie können auf folgenden Wegen Avro-Daten in eine neue Tabelle laden:

• Mit der Cloud Console
• Mit dem Befehl bq load im bq-Befehlszeilentool
• Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
• Mithilfe der Clientbibliotheken

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

Console

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

   Zur Seite "BigQuery"

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

   Hinweis: Die Standardeinstellung ist die Vorschau der Cloud Console. Wenn Sie auf Vorschaufunktionen ausblenden geklickt haben, um zur allgemein verfügbaren Cloud Console zu gelangen, gehen Sie stattdessen so vor: Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.

3. Klicken Sie im Detailfeld auf Tabelle erstellen.

4. 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 direkt 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.

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

6. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Avro-Dateien selbstbeschreibend.

7. (Optional) Wählen Sie zum Partitionieren der Tabelle die jeweiligen Optionen unter Partition and cluster settings (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.

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

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

10. (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.

11. Klicken Sie auf Tabelle erstellen.

Hinweis: Wenn Sie Daten mithilfe der Cloud Console in eine leere Tabelle laden, können Sie kein Label, keine Beschreibung und keine Ablaufzeit für die Tabelle oder Partition hinzufügen.

Nachdem die Tabelle erstellt wurde, können Sie die Ablaufzeit, die Beschreibung und die Labels der Tabelle aktualisieren. Allerdings lässt sich keine Ablaufzeit für die Partition hinzufügen, nachdem eine Tabelle über die Cloud Console erstellt wurde. Weitere Informationen finden Sie unter Tabellen verwalten.

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

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

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 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	–	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 wird auch das Tabellenschema gelöscht und alle Cloud KMS-Schlüssel werden entfernt.

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

Sie können auf folgenden Wegen Daten an eine Tabelle anhängen oder die Tabelle überschreiben:

• Mit der Cloud Console
• Mit dem Befehl bq load im bq-Befehlszeilentool
• Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
• Mithilfe der Clientbibliotheken

Hinweis: Das Anfügen und Überschreiben von Daten in partitionierten Tabellen wird auf dieser Seite nicht behandelt. Weitere Informationen dazu finden Sie unter Daten in partitionierten Tabellen anfügen oder überschreiben.

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

Console

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

   Zur Seite "BigQuery"

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

   Hinweis: Die Standardeinstellung ist die Vorschau der Cloud Console. Wenn Sie auf Vorschaufunktionen ausblenden geklickt haben, um zur allgemein verfügbaren Cloud Console zu gelangen, gehen Sie stattdessen so vor: Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.

3. Klicken Sie im Detailfeld auf Tabelle erstellen.

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

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

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

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

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

     

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

Hinweis: Das Schema der Tabelle kann beim Anfügen oder Überschreiben geändert werden. Weitere Informationen zu unterstützten Schemaänderungen für einen Ladevorgang finden Sie unter Tabellenschemas ändern.

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.

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

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 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: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API.

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 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 setzen Sie das Attribut useAvroLogicalTypes in der Jobressource, 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
duration	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.

Hinweis: Es gibt keinen logischen Typ, der direkt DATETIME entspricht, und BigQuery unterstützt keine direkte Konvertierung von einem Avro-Typ in ein DATETIME-Feld.

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:

• Verwenden Sie für einen Ladejob mit der jobs.insert API das Feld JobConfigurationLoad.decimalTargetTypes.
• Verwenden Sie für einen Ladejob mit dem Befehl bq load im bq-Befehlszeilentool das Flag --decimal_target_types.
• Für das Abfragen einer Tabelle mit externen Quellen verwenden Sie das Feld ExternalDataConfiguration.decimalTargetTypes.
• Für eine nichtflüchtige externe Tabelle, die mit DDL erstellt wurde: Verwenden Sie die Option decimal_target_types.

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.

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