Parquet-Daten aus Cloud Storage laden

Diese Seite bietet einen Überblick über das Laden von Parquet-Daten aus Cloud Storage in BigQuery.

Parquet ist ein spaltenorientiertes Open-Source-Datenformat, das häufig in Verbindung mit Apache Hadoop genutzt wird.

Sie können aus Cloud Storage geladene Parquet-Daten in eine neue Tabelle oder Partition laden bzw. an eine vorhandene Tabelle oder Partition anfügen. Es ist außerdem möglich, eine Tabelle oder Partition zu überschreiben. Beim Laden von Daten in BigQuery werden diese 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 Parquet-Daten aus einer lokalen Datei finden Sie unter Daten aus lokalen Dateien laden.

Beschränkungen

Beim Laden von Daten aus einem Cloud Storage-Bucket in BigQuery gelten die folgenden Beschränkungen:

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

  • Im Cloud Storage-URI können Sie keinen Platzhalter verwenden, wenn eine der zu ladenden Dateien unterschiedliche Schemas hat. Jeder Unterschied an der Position der Spalten entspricht einem anderen Schema.

Anforderungen an Eingabedateien

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

  • Die Zeilengröße darf maximal 50 MB betragen.
  • Wenn Ihre Eingabedaten mehr als 100 Spalten enthalten, sollten Sie die Seitengröße verringern, damit sie kleiner als die Standardseitengröße ist (1 * 1024 * 1024 Byte). Dies ist besonders hilfreich, wenn Sie eine erhebliche Komprimierung verwenden.
  • Für eine optimale Leistung sollten Zeilengruppen mindestens 16 MiB groß sein. Kleinere Zeilengruppengrößen erhöhen die E/A-Vorgänge und verlangsamen das Laden und die Abfragen.

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 auf Projekte, Ordner und Organisationen 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 erstellen

Erstellen Sie ein BigQuery-Dataset zum Speichern Ihrer Daten.

Parquet-Schemas

Wenn Sie Parquet-Dateien in BigQuery laden, wird das Tabellenschema automatisch aus den selbstbeschreibenden Quelldaten abgeleitet. Wenn BigQuery das Schema aus den Quelldaten ableitet, wird die alphabetisch letzte Datei verwendet.

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

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

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.parquet abgeleitet:

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

Wenn Sie mehrere Parquet-Dateien mit unterschiedlichen Schemas laden, müssen identische Spalten, die in mehreren Schemas angegeben sind, in jeder Schemadefinition denselben Modus haben.

Wenn das Schema in BigQuery erkannt wird, werden bestimmte Parquet-Datentypen in BigQuery-Datentypen konvertiert, damit sie mit der GoogleSQL-Syntax kompatibel sind. Weitere Informationen finden Sie unter Parquet-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.parquet".

Parquet-Komprimierung

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

  • GZip
  • LZO_1C
  • LZO_1X
  • LZ4_RAW
  • Snappy
  • ZSTD

Parquet-Daten in eine neue Tabelle laden

Sie können Parquet-Daten mit einer der folgenden Methoden in eine neue Tabelle laden:

  • Die Google Cloud Console
  • Der Befehl bq load des bq-Befehlszeilentools
  • Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
  • Mit den Clientbibliotheken

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

Console

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

    BigQuery aufrufen

  2. Klicken Sie im linken Bereich auf  Explorer.
  3. Maximieren Sie im Bereich Explorer Ihr Projekt, klicken Sie auf Datasets und wählen Sie dann ein Dataset aus.
  4. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
  5. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
    1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
      1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI 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 Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten. Wählen Sie eine Quelldatei aus, um eine BigQuery-Tabelle zu erstellen
      2. Wählen Sie als Dateiformat die Option Parquet aus.
    2. Geben Sie im Bereich Ziel die folgenden Details an:
      1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
      2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
      3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
    3. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Parquet-Dateien selbstbeschreibend.
    4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden.
    5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
      • Lassen Sie unter Write preference (Schreibeinstellung) die Option Write if empty (Schreiben, wenn leer) ausgewählt. Mit dieser Option wird eine neue Tabelle erstellt und Ihre Daten werden in diese Tabelle geladen.
      • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
      • 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 Google-managed key übernehmen, verschlüsselt BigQuery inaktive Daten.
    6. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine Parquet-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 = 'PARQUET',
  uris = ['gs://bucket/path/file.parquet']);

  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 PARQUET 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 Partitionsfilter in Abfragen erforderlich machen.
  • --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.

  • --column_name_character_map: Definiert den Bereich und die Behandlung von Zeichen in Spaltennamen. Optional können Sie flexible Spaltennamen aktivieren. Weitere Informationen finden Sie unter: load_option_list. Weitere Informationen zu unterstützten und nicht unterstützten Zeichen finden Sie unter Flexible Spaltennamen.

    Weitere Informationen zu partitionierten Tabellen finden Sie unter:

    Weitere Informationen zu geclusterten Tabellen finden Sie unter:

    Weitere Informationen zur Tabellenverschlüsselung finden Sie unter:

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

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Dabei gilt:

  • LOCATION: Ihr Standort. Das Flag --location ist optional. Wenn Sie BigQuery z. B. 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: PARQUET.
  • DATASET: ein vorhandenes Dataset.
  • TABLE: der Name der Tabelle, in die Sie Daten laden.
  • PATH_TO_SOURCE: 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.parquet in eine Tabelle mit dem Namen mytable in mydataset geladen.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

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

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

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

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=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

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=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

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 Parquet-Datenformat an. Legen Sie dazu das Attribut sourceFormat auf PARQUET fest.

  5. Rufen Sie zum Prüfen des Jobstatus jobs.get(JOB_ID*) auf. Ersetzen Sie dabei JOB_ID durch die ID des Jobs, der von der ersten Anfrage zurückgegeben wurde.

    • Wenn status.state = DONE zurückgegeben wird, wurde der Job erfolgreich abgeschlossen.
    • Wenn das Attribut status.errorResult vorhanden ist, schlug die Anfrage fehl und dieses Objekt enthält eine Fehlerbeschreibung. 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 für den zurückgegebenen Job 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

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

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

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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

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

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

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;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    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();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \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 Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

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

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

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

  // 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), metadata);

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

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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.

Verwenden Sie die Methode Client.load_table_from_uri(), um einen Ladejob für Cloud Storage zu starten. Wenn Sie Parquet verwenden möchten, legen Sie das Attribut LoadJobConfig.source_format auf den String PARQUET fest und übergeben die Jobkonfiguration als job_config-Argument an die load_table_from_uri()-Methode. 
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.PARQUET,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

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

Parquet-Daten an eine Tabelle anfügen oder Tabelle mit Parquet-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.

Sie können eine Tabelle mit einer der folgenden Methoden anfügen oder überschreiben:

  • Die Google Cloud Console
  • Der Befehl bq load des bq-Befehlszeilentools
  • Durch Aufrufen der API-Methode jobs.insert und Konfigurieren eines load-Jobs
  • Mit den Clientbibliotheken

So fügen Sie Parquet-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. Klicken Sie im linken Bereich auf  Explorer.
  3. Maximieren Sie im Bereich Explorer Ihr Projekt, klicken Sie auf Datasets und wählen Sie dann ein Dataset aus.
  4. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
  5. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
    1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
      1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI 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 Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten. Wählen Sie eine Quelldatei aus, um eine BigQuery-Tabelle zu erstellen
      2. Wählen Sie als Dateiformat die Option Parquet aus.
    2. Geben Sie im Bereich Ziel die folgenden Details an:
      1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
      2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
      3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
    3. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema ist in Parquet-Dateien selbstbeschreibend.
    4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden. Sie können eine Tabelle nicht durch Anfügen oder Überschreiben von Daten in eine partitionierte oder geclusterte Tabelle konvertieren. Die Google Cloud Console unterstützt nicht das Anfügen oder Überschreiben von Daten in partitionierten oder geclusterten Tabellen in einem Ladejob.
    5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
      • Wählen Sie unter Schreibeinstellung die Option An Tabelle anfügen oder Tabelle überschreiben aus.
      • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
      • 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 Google-managed key übernehmen, verschlüsselt BigQuery inaktive Daten.
    6. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine Parquet-Datei an die Tabelle mytable angehängt:

  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 = 'PARQUET',
  uris = ['gs://bucket/path/file.parquet']);

  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 setzen Sie es auf PARQUET. Da Parquet-Schemas automatisch aus den selbstbeschreibenden 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:

Beispiele:

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

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

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

Go

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

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

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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

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

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


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.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    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();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * 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 = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // 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), metadata);
  // 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;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

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.

Wenn Sie die Zeilen an eine vorhandene Tabelle anhängen möchten, legen Sie das Attribut LoadJobConfig.write_disposition auf WRITE_APPEND fest.

Wenn Sie die Zeilen in einer vorhandenen Tabelle ersetzen möchten, legen Sie das Attribut LoadJobConfig.write_disposition auf WRITE_TRUNCATE fest. 

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

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
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))

Mit Hive partitionierte Parquet-Daten laden

BigQuery unterstützt das Laden von mit Hive partitionierten Parquet-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 laden.

Parquet-Konvertierungen

In diesem Abschnitt wird beschrieben, wie BigQuery verschiedene Datentypen beim Laden von Parquet-Daten parst.

Einige Parquet-Datentypen (z. B. INT32, INT64, BYTE_ARRAY und FIXED_LEN_BYTE_ARRAY) können in mehrere BigQuery-Datentypen konvertiert werden. Geben Sie in der Parquet-Datei den entsprechenden Datentyp an, um sicherzustellen, dass BigQuery die Parquet-Datentypen korrekt konvertiert.

Geben Sie beispielsweise Folgendes an, um den Parquet-Datentyp INT32 in den BigQuery-Datentyp DATE zu konvertieren:

optional int32 date_col (DATE);

BigQuery konvertiert Parquet-Datentypen in BigQuery-Datentypen, die in den folgenden Abschnitten beschrieben werden.

Typkonvertierungen

Parquet-Typ Logische Parquet-Typen BigQuery-Datentyp
BOOLEAN – BOOLEAN
INT32 Keine, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32) INT64
INT32 DECIMAL NUMERIC, BIGNUMERIC oder STRING
INT32 DATE DATE
INT64 Keine, INTEGER (UINT_64, INT_64) INT64
INT64 DECIMAL NUMERIC, BIGNUMERIC oder STRING
INT64 TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS) TIMESTAMP
INT64 TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS) TIMESTAMP
INT96 – TIMESTAMP
FLOAT – FLOAT64
DOUBLE – FLOAT64
BYTE_ARRAY – BYTES
BYTE_ARRAY STRING (UTF8) STRING
FIXED_LEN_BYTE_ARRAY DECIMAL NUMERIC, BIGNUMERIC oder STRING
FIXED_LEN_BYTE_ARRAY – BYTES

Verschachtelte Gruppen werden in STRUCT-Typen konvertiert. Andere Kombinationen von Parquet-Typen und konvertierten Typen werden nicht unterstützt.

Nicht signierte logische Typen

Die Parquet-Typen UINT_8, UINT_16, UINT_32 und UINT_64 sind nicht signiert. BigQuery behandelt Werte mit diesen Typen beim Laden in eine von BigQuery signierte Spalte INTEGER als unsigniert. Im Fall von UINT_64 wird ein Fehler zurückgegeben, wenn der nicht signierte Wert den maximalen INTEGER-Wert von 9.223.372.036.854.775.807 überschreitet.

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:

Logischer Enum-Typ

Logische Enum-Typen können in STRING oder BYTES umgewandelt werden. Geben Sie den Dezimalzieltyp so an:

Logischen Typ auflisten

Sie können die Schemainferenz für logische Parquet-Typen LIST aktivieren. BigQuery prüft, ob der Knoten LIST das Standardformat oder eines der in den Abwärtskompatibilitätsregeln beschriebenen Formate aufweist:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

Wenn ja, wird das entsprechende Feld für den Knoten LIST im konvertierten Schema so behandelt, als hätte der Knoten das folgende Schema:

repeated <element-type> <name>

Die Knoten „list“ und „element“ werden weggelassen.

Geodaten

Sie können Parquet-Dateien, die WKT, hex-codierte WKB oder GeoJSON in einer Spalte vom Typ STRING enthalten, oder WKB in einer BYTE_ARRAY-Spalte durch Angabe eines BigQuery-Schemas vom Typ GEOGRAPHY. Weitere Informationen finden Sie unter Raumbezogene Daten laden.

Sie können auch GeoParquet-Dateien laden. In diesem Fall werden die Spalten, die durch die GeoParquet-Metadaten beschrieben werden, standardmäßig als Typ GEOGRAPHY interpretiert. Sie können die WKB-Rohdaten auch in eine BYTES-Spalte laden, indem Sie ein explizites Schema angeben. Weitere Informationen finden Sie unter GeoParquet-Dateien laden.

Konvertierungen von Spaltennamen

Ein Spaltenname kann Buchstaben (az, AZ), Ziffern (0–9) und Unterstriche (_) enthalten und muss mit einem Buchstaben oder einem Unterstrich beginnen. Wenn Sie flexible Spaltennamen verwenden, unterstützt BigQuery das Starten eines Spaltennamens mit einer Zahl. Seien Sie vorsichtig, wenn Sie Spalten mit einer Zahl starten, da Sie flexible Spaltennamen mit der BigQuery Storage Read API oder der BigQuery Storage Write API verwenden müssen. Weitere Informationen zur Unterstützung flexibler Spaltennamen finden Sie unter Flexible Spaltennamen.

Spaltennamen dürfen nicht länger als 300 Zeichen sein. Spaltennamen dürfen keines der folgenden Präfixe verwenden:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

Gleiche Spaltennamen sind auch bei unterschiedlicher Groß-/Kleinschreibung nicht zulässig. So wird beispielsweise der Spaltenname Column1 als identisch mit dem Spaltennamen column1 angesehen. Weitere Informationen zu Benennungsregeln für Spalten finden Sie in der GoogleSQL-Referenz unter Spaltennamen.

Wenn ein Tabellenname (z. B. test) mit einem der Spaltennamen identisch ist (z. B. test) interpretiert der Ausdruck SELECT dietest-Spalte als STRUCT, die alle anderen Tabellenspalten enthält. Verwenden Sie eine der folgenden Methoden, um diesen Konflikt zu vermeiden:

  • Vermeiden Sie die Verwendung desselben Namens für eine Tabelle und ihre Spalten.

  • Weisen Sie der Tabelle einen anderen Alias zu. Die folgende Abfrage weist beispielsweise der Tabelle project1.dataset.test einen Tabellenalias t zu:

    SELECT test FROM project1.dataset.test AS t;

  • Geben Sie den Tabellennamen an, wenn Sie auf eine Spalte verweisen. Beispiel:

    SELECT test.test FROM project1.dataset.test;

Flexible Spaltennamen

Sie haben jetzt mehr Flexibilität bei der Benennung von Spalten, darunter erweiterter Zugriff auf Zeichen in anderen Sprachen als Englisch und zusätzliche Symbole. Flexible Spaltennamen müssen in Graviszeichen (`) eingeschlossen werden, wenn es sich um Kennungen in Anführungszeichen handelt.

In flexiblen Spaltennamen werden folgende Zeichen unterstützt:

  • Ein beliebiger Buchstabe in einer beliebigen Sprache, wie durch den regulären Unicode-Ausdruck \p{L} dargestellt.
  • Ein beliebiges numerisches Zeichen in einer beliebigen Sprache, wie durch den regulären Unicode-Ausdruck \p{N} dargestellt.
  • Ein beliebiges Satzzeichen eines Connectors, einschließlich Unterstriche, wie durch den regulären Unicode-Ausdruck \p{Pc} dargestellt.
  • Ein Bindestrich oder Gedankenstrich, wie durch den regulären Unicode-Ausdruck \p{Pd} dargestellt.
  • Ein beliebiges Zeichen, das ein anderes Zeichen begleiten soll, wie durch den regulären Unicode-Ausdruck \p{M} dargestellt. Beispiele sind Akzente, Umlaute und einschließende Rahmen.
  • Die folgenden Sonderzeichen:
    • Ein Et-Zeichen (&), wie durch den regulären Unicode-Ausdruck \u0026 dargestellt.
    • Ein Prozentzeichen (%), wie durch den regulären Unicode-Ausdruck \u0025 dargestellt.
    • Ein Gleichheitszeichen (=), wie durch den regulären Unicode-Ausdruck \u003D dargestellt.
    • Ein Pluszeichen (+), wie durch den regulären Unicode-Ausdruck \u002B dargestellt.
    • Ein Doppelpunkt (:), wie durch den regulären Unicode-Ausdruck \u003A dargestellt.
    • Ein Apostroph ('), wie durch den regulären Unicode-Ausdruck \u0027 dargestellt.
    • Ein Kleiner-als-Zeichen (<), wie durch den regulären Unicode-Ausdruck \u003C dargestellt.
    • Ein Größer-als-Zeichen (>) wie durch den regulären Unicode-Ausdruck \u003E dargestellt.
    • Ein Zahlenzeichen (#), wie durch den regulären Unicode-Ausdruck \u0023 dargestellt.
    • Eine vertikale Linie (|), wie durch den regulären Unicode-Ausdruck \u007c dargestellt.
    • Leerraum.

Folgende Sonderzeichen werden bei flexiblen Spaltennamen nicht unterstützt:

  • Ein Ausrufezeichen (!), wie durch den regulären Unicode-Ausdruck \u0021 dargestellt.
  • Ein Anführungszeichen ("), wie durch den regulären Unicode-Ausdruck \u0022 dargestellt.
  • Ein Dollar-Zeichen ($), wie durch den regulären Unicode-Ausdruck \u0024 dargestellt.
  • Eine linke Klammer ((), wie durch den regulären Unicode-Ausdruck \u0028 dargestellt.
  • Eine rechte Klammer ()), wie durch den regulären Unicode-Ausdruck \u0029 dargestellt.
  • Ein Sternchen (*) wie durch den regulären Unicode-Ausdruck \u002A dargestellt.
  • Ein Komma (,), wie durch den regulären Unicode-Ausdruck \u002C dargestellt.
  • Ein Punkt (.), wie durch den regulären Unicode-Ausdruck \u002E dargestellt. Punkte werden in Parquet-Dateispaltennamen nicht durch Unterstriche ersetzt, wenn eine Zeichentabelle für Spaltennamen verwendet wird. Weitere Informationen finden Sie unter Einschränkungen für flexible Spalten.
  • Ein Schrägstrich (/), wie durch den regulären Unicode-Ausdruck \u002F dargestellt.
  • Ein Semikolon (;), wie durch den regulären Unicode-Ausdruck \u003B dargestellt.
  • Ein Fragezeichen (?), wie durch den regulären Unicode-Ausdruck \u003F dargestellt.
  • Ein Klammeraffe (@), wie durch den regulären Unicode-Ausdruck \u0040 dargestellt.
  • Eine linke eckige Klammer {[), wie durch den regulären Unicode-Ausdruck \u005B dargestellt.
  • Ein umgekehrter Schrägstrich (\), wie durch den regulären Unicode-Ausdruck \u005C dargestellt.
  • Eine rechte eckige Klammer (]), wie durch den regulären Unicode-Ausdruck \u005D dargestellt.
  • Ein Zirkumflex-Akzent (^), wie durch den regulären Unicode-Ausdruck \u005E dargestellt.
  • Ein Gravis-Akzent (`), wie durch den regulären Unicode-Ausdruck \u0060 dargestellt.
  • Eine linke geschweifte Klammer {{), wie durch den regulären Unicode-Ausdruck \u007B dargestellt.
  • Eine rechte geschweifte Klammer (}), wie durch den regulären Unicode-Ausdruck \u007D dargestellt.
  • Eine Tilde (~), wie durch den regulären Unicode-Ausdruck \u007E dargestellt.

Weitere Richtlinien finden Sie unter Spaltennamen.

Die erweiterten Spaltenzeichen werden sowohl von der BigQuery Storage Read API als auch von der BigQuery Storage Write API unterstützt. Um die erweiterte Liste von Unicode-Zeichen mit der BigQuery Storage Read API zu verwenden, müssen Sie ein Flag festlegen. Mit dem displayName-Attribut können Sie den Spaltennamen abrufen. Das folgende Beispiel zeigt, wie Sie mit dem Python-Client ein Flag festlegen:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Um die erweiterte Liste von Unicode-Zeichen mit der BigQuery Storage Write API zu verwenden, müssen Sie das Schema mit der column_name-Notation angeben, es sei denn, Sie verwenden das JsonStreamWriter-Autor-Objekt. Das folgende Beispiel zeigt, wie das Schema bereitgestellt wird:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

In diesem Beispiel sind item_name_column und item_description_column Platzhalternamen, die der Namenskonvention des Protokollpuffers entsprechen müssen. Beachten Sie, dass column_name-Annotationen immer Vorrang vor Platzhalternamen haben.

Beschränkungen

  • Flexible Spaltennamen werden bei externen Tabellen nicht unterstützt.

  • Es können keine Parquet-Dateien mit Spalten, in deren Namen ein Punkt (.) enthalten ist, geladen werden.

  • Spaltennamen aus Parquet-Dateien werden beim Laden in BigQuery als nicht case-sensitive behandelt. Identische Namen, bei denen die Groß-/Kleinschreibung nicht berücksichtigt wird, führen zu Konflikten. Um dies zu vermeiden, hängen Sie entweder einen Unterstrich an einen der doppelten Spaltennamen an oder benennen Sie die Spalten vor dem Laden um.

Fehler in einer Parquet-Datei beheben

Wenn Ihre Ladejobs mit Datenfehlern fehlschlagen, können Sie PyArrow verwenden, um zu prüfen, ob Ihre Parquet-Datendateien korrumpiert wurden. Kann PyArrow die Dateien nicht lesen, dann werden diese wahrscheinlich vom BigQuery-Ladejob abgelehnt. Im folgenden Beispiel wird gezeigt, wie Sie den Inhalt einer Parquet-Datei mit PyArrow lesen können:

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Weitere Informationen finden Sie in den PyArrow-Dokumenten.