Schema angeben

Mit BigQuery können Sie das Schema einer Tabelle angeben, wenn Sie Daten in eine Tabelle laden oder eine leere Tabelle erstellen. Für unterstützte Datenformate können Sie alternativ auch die automatische Schemaerkennung nutzen.

Wenn Sie Avro-, Parquet-, ORC-, Firestore- oder Datastore-Exportdateien laden, wird das Schema automatisch aus den selbstbeschreibenden Quelldaten abgerufen.

Sie können das Schema einer Tabelle folgendermaßen angeben:

• Google Cloud Console verwenden.
• Verwenden Sie die SQL-Anweisung CREATE TABLE.
• Inline mit dem bq-Befehlszeilentool.
• Erstellen Sie eine Schemadatei im JSON-Format.
• Rufen Sie die Methode jobs.insert auf und konfigurieren Sie das Attribut schema in der Konfiguration des load-Jobs.
• Rufen Sie die Methode tables.insert auf und konfigurieren Sie mit dem Attribut schema das Schema in der Tabellenressource.

Nachdem Sie Daten geladen oder eine leere Tabelle erstellt haben, können Sie die Schemadefinition der Tabelle ändern.

Schemakomponenten

Wenn Sie ein Tabellenschema festlegen, müssen Sie den Namen und den Datentyp jeder Spalte angeben. Sie können auch die Beschreibung, den Modus und den Standardwert einer Spalte angeben.

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.

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

Spaltenbeschreibungen

Jede Spalte kann eine Beschreibung enthalten. Die Beschreibung ist ein String mit maximal 1.024 Zeichen.

Standardwerte

Der Standardwert einer Spalte muss ein Literal oder eine der folgenden Funktionen sein:

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

GoogleSQL-Datentypen

Mit GoogleSQL können Sie in Ihrem Schema die in der folgenden Tabelle aufgeführten Datentypen festlegen. Der Datentyp ist erforderlich.

Name	Datentyp	Beschreibung
Ganzzahl	INT64	Numerische Werte ohne Bruchkomponenten
Gleitkomma	FLOAT64	Angenäherte numerische Werte mit Bruchkomponenten
Numerisch	NUMERIC	Exakte numerische Werte mit Bruchkomponenten
BigNumeric	BIGNUMERIC	Exakte numerische Werte mit Bruchkomponenten
Boolesch	BOOL	TRUE oder FALSE (Groß-/Kleinschreibung wird nicht berücksichtigt)
String	STRING	Zeichendaten (Unicode) mit variabler Länge
Byte	BYTES	Binärdaten mit variabler Länge
Datum	DATE	Ein logisches Kalenderdatum
Datum/Uhrzeit	DATETIME	Jahr, Monat, Tag, Stunde, Minute, Sekunde und Sekundenbruchteil
Zeit	TIME	Uhrzeit, unabhängig von einem bestimmten Datum
Timestamp	TIMESTAMP	Absoluter Zeitpunkt, auf die Mikrosekunde genau
Struct (Datensatz)	STRUCT	Container mit geordneten Feldern, jeweils mit einem Typ (erforderlich) und einem Feldnamen (optional)
Geografie	GEOGRAPHY	Ein Punktsatz auf der Erdoberfläche (eine Menge von Punkten, Linien und Polygonen auf dem WGS-84-Referenzsphäroid mit geodätischen Kanten)
JSON	JSON	Steht für JSON, ein einfaches Datenaustauschformat.
RANGE	RANGE	Ein Bereich von DATE-, DATETIME- oder TIMESTAMP-Werten

Weitere Informationen zu Datentypen in GoogleSQL finden Sie unter GoogleSQL-Datentypen.

Sie können auch einen Arraytyp deklarieren, wenn Sie Daten abfragen. Weitere Informationen finden Sie unter Mit Kontingenten arbeiten.

Modi

BigQuery unterstützt für Spalten die folgenden Modi. Der Modus ist optional. Wenn kein Modus angegeben ist, wird standardmäßig NULLABLE (Nullwerte zulässig) verwendet.

Modus	Beschreibung
Nullwerte zulässig	Spalte erlaubt NULL-Werte (Standard)
Erforderlich	NULL-Werte sind nicht zulässig
Wiederholt	Spalte enthält ein Array mit Werten des angegebenen Typs

Weitere Informationen zu Modi finden Sie unter mode im TableFieldSchema.

Rundungsmodus

Wenn eine Spalte ein Typ NUMERIC oder BIGNUMERIC ist, können Sie die Spaltesoption rounding_mode festlegen, mit der bestimmt wird, wie Werte in dieser Spalte beim Schreiben in die Tabelle gerundet werden. Sie können die Option rounding_mode für eine Spalte auf oberster Ebene oder für ein Feld STRUCT festlegen. Die folgenden Rundungsmodi werden unterstützt:

• "ROUND_HALF_AWAY_FROM_ZERO": Dieser Modus (Standard) rundet halbe Zahlen von null weg.
• "ROUND_HALF_EVEN": Dieser Modus rundet die Hälfte der Fälle zur nächsten geraden Ziffer ab.

Sie können die Option rounding_mode nicht für eine Spalte festlegen, die nicht vom Typ NUMERIC oder BIGNUMERIC ist. Weitere Informationen zu diesen Typen finden Sie unter Dezimaltypen.

Im folgenden Beispiel wird eine Tabelle erstellt und Werte eingefügt, die basierend auf dem Rundungsmodus der Spalte gerundet werden:

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

Die Tabelle mytable sieht so aus:

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

Weitere Informationen finden Sie unter roundingMode im TableFieldSchema.

Schemas angeben

Wenn Sie Daten laden oder eine leere Tabelle erstellen, können Sie das Schema der Tabelle mithilfe der Google Cloud Console oder des bq-Befehlszeilentools manuell angeben. Das manuelle Angeben eines Schemas wird beim Laden von CSV- und JSON-Dateien (durch Zeilenumbruch getrennt) unterstützt. Wenn Sie Avro-, Parquet-, ORC-, Firestore- oder Datastore-Exportdaten laden, wird das Schema automatisch aus den selbstbeschreibenden Quelldaten abgerufen.

So geben Sie ein Tabellenschema an:

Console

In der Google Cloud Console können Sie mit der Option Feld hinzufügen oder der Option Als Text bearbeiten ein Schema festlegen.

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

   BigQuery aufrufen

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

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

4. Klicken Sie im Detailfeld auf Tabelle erstellen.

5. Wählen Sie auf der Seite Tabelle erstellen im Abschnitt Quelle die Option Leere Tabelle aus.

6. Gehen Sie auf der Seite Create table (Tabelle erstellen) im Abschnitt Destination (Ziel) so vor:

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

     

   • Geben Sie im Feld Tabllenname den Namen der Tabelle ein, die Sie in BigQuery erstellen.

   • Achten Sie darauf, dass Table type (Tabellentyp) auf Native table (Native Tabelle) eingestellt ist.

7. Geben Sie im Abschnitt Schema die Schemadefinition ein.

   • Option 1: Klicken Sie auf Feld hinzufügen und geben Sie für jedes Feld den Namen, den Typ und den Modus an.
   • Option 2: Klicken Sie auf Als Text bearbeiten und fügen Sie das Schema in Form eines JSON-Arrays ein. Wenn Sie ein JSON-Array verwenden, generieren Sie das Schema mit demselben Verfahren wie beim Erstellen einer JSON-Schemadatei.

8. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die Anweisung CREATE TABLE. Geben Sie das Schema mit der Option Spalte an. Im folgenden Beispiel wird eine neue Tabelle mit dem Namen newtable mit den Spalten x, y, z der Typen "Ganzzahl", "String" und "Boolesch" erstellt.

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

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

   CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRING, z BOOL)
     OPTIONS(
       description = 'My example table');

3. Klicken Sie auf Ausführen.

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

bq

Geben Sie das Schema inline im Format field:data_type,field:data_type mit einem der folgenden Befehle an:

• Verwenden Sie den Befehl bq load, wenn Sie die Daten laden.
• Verwenden Sie den Befehl bq mk, wenn Sie eine leere Tabelle erstellen möchten.

Wenn Sie das Schema in der Befehlszeile angeben, können Sie keine Typen vom Typ RECORD (STRUCT) oder RANGE einfügen. Außerdem ist es dann nicht möglich, eine Spaltenbeschreibung einzufügen oder den Modus der Spalte anzugeben. Als Modus ist immer standardmäßig NULLABLE eingestellt. Wenn Sie Beschreibungen, Modi RECORD- und RANGE-Typen einbinden möchten, müssen Sie stattdessen eine JSON-Schemadatei bereitstellen.

Wenn Sie Daten mithilfe einer Inline-Schemadefinition in eine Tabelle laden möchten, geben Sie den Befehl load ein und geben Sie das Datenformat mit dem Flag --source_format an. Wenn Sie Daten in eine Tabelle in einem Projekt laden, das nicht Ihr Standardprojekt ist, geben Sie die Projekt-ID im folgenden Format an: project_id:dataset.table_name.

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

bq --location=location load \
--source_format=format \
project_id:dataset.table_name \
path_to_source \
schema

Ersetzen Sie dabei Folgendes:

• location: Name Ihres Standorts. 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: NEWLINE_DELIMITED_JSON oder CSV.
• project_id: Ihre Projekt-ID.
• dataset: Das Dataset mit der Tabelle, in die Sie Daten laden.
• table_name: Der Name der Tabelle, in die Sie Daten laden.
• path_to_source: Der Speicherort der CSV- oder JSON-Datendatei auf Ihrem lokalen Rechner oder in Cloud Storage.
• schema: Die Inline-Schemadefinition.

Beispiel:

Geben Sie den folgenden Befehl ein, um Daten aus einer lokalen CSV-Datei namens myfile.csv in mydataset.mytable in Ihrem Standardprojekt zu laden. Das Schema wird inline angegeben.

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

Unter Einführung in das Laden von Daten finden Sie weitere Informationen dazu.

Wenn Sie beim Erstellen einer leeren Tabelle eine Inline-Schemadefinition angeben, geben Sie den Befehl bq mk mit dem Flag --table oder -t ein. Wenn Sie eine Tabelle in einem anderen Projekt als dem Standardprojekt erstellen, fügen Sie dem Befehl die Projekt-ID im folgenden Format hinzu: project_id:dataset.table.

bq mk --table project_id:dataset.table schema

Dabei gilt:

• project_id: Ihre Projekt-ID.
• dataset: ein Dataset in Ihrem Projekt.
• table: Der Name der Tabelle, die Sie erstellen.
• schema: Eine Inline-Schemadefinition.

Mit dem folgenden Befehl wird beispielsweise eine leere Tabelle mit dem Namen mytable in Ihrem Standardprojekt erstellt. Das Schema wird inline angegeben.

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

Weitere Informationen zum Erstellen einer leeren Tabelle finden Sie unter Leere Tabelle mit einer Schemadefinition erstellen.

C#

So geben Sie das Schema einer Tabelle an, wenn Sie Daten in eine Tabelle laden:

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der C#-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery C# API.

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

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

So geben Sie das Schema an, wenn Sie eine leere Tabelle erstellen:

using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

So geben Sie das Schema einer Tabelle an, wenn Sie Daten in eine Tabelle laden:

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Go-Einrichtungsanleitung 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"
)

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(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.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	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
}

So geben Sie das Schema an, wenn Sie eine leere Tabelle erstellen:

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

So geben Sie das Schema einer Tabelle an, wenn Sie Daten in eine Tabelle laden:

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Java-Einrichtungsanleitung 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.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadJsonFromGCS() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON 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("Json 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());
    }
  }
}

So geben Sie das Schema an, wenn Sie eine leere Tabelle erstellen:

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Python

Wenn Sie Daten in eine Tabelle laden, geben Sie im Attribut LoadJobConfig.schema das entsprechende Tabellenschema an.

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Python-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

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

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    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))

Wenn Sie eine leere Tabelle erstellen, konfigurieren Sie zum Angeben eines Schemas das Attribut Table.schema.

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"

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

JSON-Schemadatei angeben

Wenn Sie möchten, können Sie das Schema mit einer JSON-Schemadatei angeben, anstatt eine Inline-Schemadefinition zu verwenden. Eine JSON-Schemadatei besteht aus einem JSON-Array mit folgendem Inhalt:

• Name der Spalte
• Datentyp der Spalte
• Optional: Modus der Spalte (bei fehlender Angabe wird standardmäßig NULLABLE verwendet)
• Optional: Felder der Spalte, wenn es sich um einen STRUCT-Typ handelt
• (Optional) Beschreibung der Spalte
• Optional: Richtlinien-Tags der Spalte, die für die Zugriffssteuerung auf Feldebene verwendet werden
• Optional: Die maximale Länge der Werte in der Spalte für die Typen STRING und BYTES
• Optional: Die Genauigkeit der Spalte für die Typen NUMERIC und BIGNUMERIC
• Optional: Die Skalierung der Spalte für die Typen NUMERIC und BIGNUMERIC
• Optional: Die Sortierung der Spalte für STRING-Typen
• Optional: Standardwert der Spalte
• Optional: Der Rundungsmodus der Spalte, wenn die Spalte ein Typ NUMERIC oder BIGNUMERIC ist

Hinweis: Sie können auch das JSON-Array, das Sie in Ihrer Schemadatei erstellen, über die Google Cloud Console Als Text bearbeiten. Außerdem kann es als Ausgangspunkt für die Konfiguration des Attributs schema in der API verwendet werden.

JSON-Schemadatei erstellen

Geben Sie zum Erstellen einer JSON-Schemadatei für jede Spalte einen TableFieldSchema ein. Die Felder name und type sind Pflichtfelder. Alle anderen sind optional.

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

Wenn die Spalte ein RANGE<T>-Typ ist, verwenden Sie das Feld rangeElementType, um T zu beschreiben. Dabei gilt: T muss DATE, DATETIME oder TIMESTAMP sein.

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

Das JSON-Array wird durch die eckigen Klammern [] gekennzeichnet. Jeder Spalteneintrag muss durch ein Komma getrennt sein: },.

So schreiben Sie ein vorhandenes Tabellenschema in eine lokale Datei:

bq

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

Dabei gilt:

• project_id: Ihre Projekt-ID.
• dataset: ein Dataset in Ihrem Projekt.
• table ist der Name eines vorhandenen Tabellenschemas.
• path_to_file: der Speicherort der lokalen Datei, in die Sie das Tabellenschema schreiben.

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.

Rufen Sie zum Schreiben einer JSON-Schemadatei aus einer Tabelle mithilfe der Python-Clientbibliothek die Methode Client.schema_to_json auf.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

Sie können die Ausgabedatei als Ausgangspunkt für Ihre eigene JSON-Schemadatei verwenden. Wenn Sie diesen Ansatz verwenden, achten Sie darauf, dass die Datei nur das JSON-Array enthält, das das Schema der Tabelle repräsentiert.

Beispielsweise stellt das folgende JSON-Array ein einfaches Tabellenschema dar. Dieses Schema hat drei Spalten: qtr (REQUIRED STRING) rep (NULLABLE STRING) und sales (NULLABLE FLOAT).

[
  {
    "name": "qtr",
    "type": "STRING",
    "mode": "REQUIRED",
    "description": "quarter"
  },
  {
    "name": "rep",
    "type": "STRING",
    "mode": "NULLABLE",
    "description": "sales representative"
  },
  {
    "name": "sales",
    "type": "FLOAT",
    "mode": "NULLABLE",
    "defaultValueExpression": "2.55"
  }
]

JSON-Schemadatei verwenden

Nachdem Sie die JSON-Schemadatei erstellt haben, können Sie sie mit dem bq-Befehlszeilentool angeben. In der Google Cloud Console oder der API kann keine Schemadatei verwendet werden.

Geben Sie die Schemadatei an:

• Verwenden Sie den Befehl bq load, wenn Sie die Daten laden.
• Verwenden Sie den Befehl bq mk, wenn Sie eine leere Tabelle erstellen möchten.

Wenn Sie eine JSON-Schemadatei bereitstellen, muss sie an einem lokal lesbaren Ort gespeichert werden. Sie können keine JSON-Schemadatei angeben, die in Cloud Storage oder Google Drive gespeichert ist.

Schemadatei beim Laden von Daten angeben

So laden Sie Daten in eine Tabelle mithilfe einer JSON-Schemadefinition:

bq

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

Dabei gilt:

• location: Name Ihres Standorts. 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: NEWLINE_DELIMITED_JSON oder CSV.
• project_id: Ihre Projekt-ID.
• dataset: Das Dataset mit der Tabelle, in die Sie Daten laden.
• table: Der Name der Tabelle, in die Sie Daten laden.
• path_to_data_file: Der Speicherort der CSV- oder JSON-Datendatei auf Ihrem lokalen Rechner oder in Cloud Storage.
• path_to_schema_file: Der Pfad zur Schemadatei auf Ihrem lokalen Rechner.

Beispiel:

Geben Sie den folgenden Befehl ein, um Daten aus einer lokalen CSV-Datei namens myfile.csv in mydataset.mytable in Ihrem Standardprojekt zu laden. Das Schema wird im aktuellen Verzeichnis in myschema.json angegeben.

bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

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.

Rufen Sie die Methode schema_from_json auf, um ein Tabellenschema aus einer JSON-Datei mit der Python-Clientbibliothek zu laden.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
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)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

Schemadatei beim Erstellen einer Tabelle angeben

So erstellen Sie eine leere Tabelle in einem vorhandenen Dataset mithilfe einer JSON-Schemadatei:

bq

bq mk --table project_id:dataset.table path_to_schema_file

Dabei gilt:

• project_id: Ihre Projekt-ID.
• dataset: ein Dataset in Ihrem Projekt.
• table: Der Name der Tabelle, die Sie erstellen.
• path_to_schema_file: Der Pfad zur Schemadatei auf Ihrem lokalen Rechner.

Mit dem folgenden Befehl wird beispielsweise eine Tabelle mit dem Namen mytable in mydataset in Ihrem Standardprojekt erstellt. Das Schema wird im aktuellen Verzeichnis in myschema.json angegeben:

bq mk --table mydataset.mytable ./myschema.json

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.

Rufen Sie die Methode schema_from_json auf, um ein Tabellenschema aus einer JSON-Datei mit der Python-Clientbibliothek zu laden.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(f"Created table {table_id}.")

Schema in der API angeben

So geben Sie ein Tabellenschema mithilfe der API an:

• Zur Angabe eines Schemas beim Laden von Daten rufen Sie die Methode jobs.insert auf und konfigurieren das Attribut schema in der Ressource JobConfigurationLoad.

• Zur Angabe eines Schemas beim Erstellen einer Tabelle rufen Sie die Methode tables.insert auf und konfigurieren das Attribut schema in der Ressource Table.

Das Angeben eines Schemas mithilfe der API ähnelt dem Verfahren zum Erstellen einer JSON-Schemadatei.

Tabellensicherheit

Informationen zum Steuern des Zugriffs auf Tabellen in BigQuery finden Sie unter Einführung in die Tabellenzugriffssteuerung.

Nächste Schritte

• Verschachtelte und wiederkehrende Spalten in einer Schemadefinition angeben
• Schemas automatisch erkennen
• Daten in BigQuery laden
• Tabellen erstellen und verwenden