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-, Cloud Firestore- oder Cloud Datastore-Exportdateien laden, wird das Schema automatisch aus den selbstbeschreibenden Quelldaten abgerufen.

Sie können das Schema einer Tabelle so angeben:

  • Geben Sie das Schema manuell an:
    • Mit der GCP Console
    • Mit der klassischen BigQuery-Web-UI
    • Inline mit der Befehlszeile
  • 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 für Spalten auch optional eine Beschreibung und einen Modus angeben.

Spaltennamen

Ein Spaltenname darf nur Buchstaben (a–z, A–Z), Ziffern (0–9) und Unterstriche (_) enthalten und muss mit einem Buchstaben oder einem Unterstrich beginnen. Die maximale Länge des Spaltennamens beträgt 128 Zeichen. In Spaltennamen darf keines der folgenden Präfixe verwendet werden:

  • _TABLE_
  • _FILE_
  • _PARTITION

Mehrere identische Spaltennamen sind auch bei unterschiedlicher Groß-/Kleinschreibung nicht zulässig. So wird beispielsweise der Spaltenname Column1 als identisch mit dem Spaltennamen column1 angesehen.

Spaltenbeschreibungen

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

Standard-SQL-Datentypen

Bei BigQuery-Standard-SQL können Sie in Ihrem Schema die folgenden Datentypen angeben. Der Datentyp ist erforderlich.

Datentyp Beschreibung
Ganzzahl Numerische Werte ohne Bruchkomponenten
Gleitkomma Angenäherte numerische Werte mit Bruchkomponenten
Numerisch Exakte numerische Werte mit Bruchkomponenten
Boolean TRUE oder FALSE (Groß-/Kleinschreibung wird nicht berücksichtigt)
String Zeichendaten (Unicode) mit variabler Länge
Byte Binärdaten mit variabler Länge
Datum Ein logisches Kalenderdatum
Datum/Uhrzeit Jahr, Monat, Tag, Stunde, Minute, Sekunde und Sekundenbruchteil
Zeit Uhrzeit, unabhängig von einem bestimmten Datum
Zeitstempel Absoluter Zeitpunkt, auf die Mikrosekunde genau
Struct (Datensatz) Container mit geordneten Feldern, jeweils mit einem Typ (erforderlich) und einem Feldnamen (optional)
Geografie Ein Punktsatz auf der Erdoberfläche (eine Menge von Punkten, Linien und Polygonen auf dem WGS-84-Referenzsphäroid mit geodätischen Kanten)

Weitere Informationen zu Datentypen in Standard-SQL finden Sie unter Standard-SQL-Datentypen.

Sie können auch einen Arraytyp deklarieren, wenn Sie Daten abfragen. Weitere Informationen dazu finden Sie unter Mit Arrays 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 (Nullable) Spalte erlaubt NULL-Werte (Standard)
Erforderlich (Required) NULL-Werte sind nicht zulässig
Wiederholt (Repeated) Spalte enthält ein Array mit Werten des angegebenen Typs

Weitere Informationen zu den Modi finden Sie unter mode im TableFieldSchema.

Schemas manuell angeben

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

So geben Sie ein Tabellenschema manuell an:

Console

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

  1. Rufen Sie in der GCP Console die BigQuery-Web-UI auf.
    GCP Console aufrufen

  2. Wählen Sie im Bereich Ressourcen des Navigationsbereichs ein Dataset aus.

  3. Klicken Sie rechts im Fenster auf Create table (Tabelle erstellen).

    Tabelle erstellen

  4. Wählen Sie auf der Seite Create table (Tabelle erstellen) im Abschnitt Source (Quelle) die Option Empty table (Leere Tabelle) aus.

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

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

      Dataset auswählen

    • Geben Sie im Feld Table name (Tabellenname) den Namen der Tabelle ein, die Sie in BigQuery erstellen.

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

  6. Geben Sie im Abschnitt Schema die Schemadefinition ein.

    • Option 1: Verwenden Sie Add field (Feld hinzufügen) und geben Sie für jedes Feld den Namen, den Typ und den Modus an. In der BigQuery-Web-UI können Sie keine Feldbeschreibung einfügen, wenn Sie die Option Add field (Feld hinzufügen) verwenden. Sie können aber manuell Feldbeschreibungen in der UI hinzufügen, nachdem Sie die Daten geladen haben.
    • Option 2: Klicken Sie auf Edit as text (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.
  7. Klicken Sie auf Create Table (Tabelle erstellen).

Klassische UI

In der BigQuery-Web-UI können Sie mithilfe der Option Add field (Feld hinzufügen) oder der Option Edit as Text (Als Text bearbeiten) ein Schema angeben.

  1. BigQuery-Web-UI öffnen

    Zur BigQuery-Web-UI

  2. Klicken Sie im Navigationsbereich neben dem Dataset-Namen auf den Abwärtspfeil Abwärtspfeilsymbol und anschließend auf Create new table (Neue Tabelle erstellen).

  3. Gehen Sie auf der Seite Tabelle erstellen so vor:

    • Klicken Sie unter Source Data (Quelldaten) auf Create from source (Aus Quelle erstellen), wenn Sie Daten laden, oder klicken Sie auf Create empty table (Leere Tabelle erstellen).
    • Wählen Sie unter Destination Table (Zieltabelle) das Dataset aus und geben Sie in das Feld Destination table name (Name der Zieltabelle) den Namen der Tabelle ein.
    • Wählen Sie unter Schema eine der folgenden Optionen aus, um ein Schema manuell anzugeben:

      • Option 1: Verwenden Sie Add field (Feld hinzufügen) und geben Sie für jedes Feld den Namen, den Typ und den Modus an. In der BigQuery-Web-UI können Sie keine Feldbeschreibung einfügen, wenn Sie die Option Feld hinzufügen verwenden. Sie können aber manuell Feldbeschreibungen einfügen, nachdem Sie die Daten geladen haben.

        Schema über "Feld hinzufügen" hinzufügen

      • Option 2: Klicken Sie auf Edit as Text (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.

        Schema als JSON-Array hinzufügen

    • Klicken Sie auf Create Table (Tabelle erstellen).

Befehlszeile

Geben Sie das Schema inline im Format field:data_type,field:data_type an. Verwenden Sie dabei die folgenden Befehle:

  • Befehl load, wenn Sie Daten laden
  • Befehl mk, wenn Sie eine leere Tabelle erstellen

Wenn Sie das Schema in der Befehlszeile angeben, können Sie den Typ RECORD (STRUCT) und die Spaltenbeschreibung nicht einfügen. Außerdem ist es dann nicht möglich, den Modus der Spalte anzugeben. Alle Modi sind standardmäßig auf NULLABLE festgelegt. Wenn Sie Beschreibungen, Modi und den Typ RECORD mit angeben möchten, stellen Sie stattdessen eine JSON-Schemadatei bereit.

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: Sie können das Flag --location angeben und als Wert Ihren Standort festlegen.

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

Dabei gilt:

  • location ist der Name Ihres Standorts. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, legen Sie für das Flag den Wert asia-northeast1 fest. Mit der Datei ".bigqueryrc" können Sie einen Standardwert für den Standort festlegen.
  • format ist NEWLINE_DELIMITED_JSON oder CSV.
  • project_id:dataset.table_name ist die Projekt-ID.
  • project_id:dataset.table_name ist das Dataset, das die Tabelle enthält, in die Sie Daten laden.
  • project_id:dataset.table_name ist der Name der Tabelle, in die Sie Daten laden.
  • path_to_source ist der Speicherort der CSV- oder JSON-Datendatei auf Ihrem lokalen Rechner oder in Cloud Storage.
  • schema ist 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 manuell inline angegeben.

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

Weitere Informationen zum Laden von Daten in BigQuery finden Sie unter Einführung in das Laden von Daten.

Wenn Sie beim Erstellen einer leeren Tabelle eine Inline-Schemadefinition angeben, geben Sie den Befehl mk mit dem Flag --table oder -t ein. Wenn Sie eine Tabelle in einem Projekt erstellen, das nicht Ihr Standardprojekt ist, 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 ist die Projekt-ID.
  • dataset ist ein Dataset in Ihrem Projekt.
  • table ist der Name der Tabelle, die Sie erstellen.
  • schema ist eine Inline-Schemadefinition.

Mit dem folgenden Befehl wird im Standardprojekt eine leere Tabelle namens mytable erstellt. Das Schema wird manuell 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:


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.PollUntilCompleted();  // 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 ein Schema an, wenn Sie eine leere Tabelle erstellen:


using Google.Cloud.BigQuery.V2;
using System;

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:

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Python

Wenn Sie Daten in eine Tabelle laden, konfigurieren Sie zum Angeben des Tabellenschemas das Attribut LoadJobConfig.schema.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
job_config.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,
    dataset_ref.table("us_states"),
    location="US",  # Location must match that of the destination dataset.
    job_config=job_config,
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
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

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

# TODO(developer): 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"

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

JSON-Schemadatei angeben

Wenn Sie das Schema nicht manuell angeben möchten, können Sie eine JSON-Schemadatei für die Verwendung mit der CLI erstellen. Eine JSON-Schemadatei besteht aus einem JSON-Array, das Folgendes enthält:

JSON-Schemadatei erstellen

Um eine JSON-Schemadatei zu erstellen, geben Sie Folgendes mithilfe eines geeigneten Texteditors ein:

[
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 },
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 }
]

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

Sie können ein vorhandenes Tabellenschema in eine lokale Datei schreiben, indem Sie den folgenden Befehl eingeben:

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

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.

Zum Beispiel repräsentiert das folgende JSON-Array ein grundlegendes Tabellenschema. Dieses Schema hat drei Spalten: qtr (REQUIRED STRING), rep (NULLABLE STRING) und sales (NULLABLE FLOAT).

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

JSON-Schemadatei verwenden

Nachdem Sie die JSON-Schemadatei erstellt haben, können Sie sie in der Befehlszeile angeben. In der GCP Console, der klassischen BigQuery-Web-UI oder der API können Sie keine Schemadatei verwenden.

Stellen Sie die Schemadatei manuell mithilfe der folgenden Befehle bereit:

  • Befehl load, wenn Sie Daten laden
  • Befehl mk, wenn Sie eine leere Tabelle erstellen

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

Mit dem folgenden Befehl werden Daten mithilfe der Schemadefinition in einer JSON-Datei in eine Tabelle geladen:

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

Dabei gilt:

  • location ist der Name Ihres Standorts. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, legen Sie für das Flag den Wert asia-northeast1 fest. Mit der Datei ".bigqueryrc" können Sie einen Standardwert für den Standort festlegen.
  • format ist NEWLINE_DELIMITED_JSON oder CSV.
  • project_id ist die Projekt-ID.
  • dataset ist das Dataset mit der Tabelle, in die Sie Daten laden.
  • table ist der Name der Tabelle, in die Sie Daten laden.
  • path_to_data_file ist der Speicherort der CSV- oder JSON-Datendatei auf Ihrem lokalen Rechner oder in Cloud Storage.
  • path_to_schema_file ist 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 ist in myschema.json angegeben:

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

Schemadatei beim Erstellen einer Tabelle angeben

Mit dem folgenden Befehl wird eine leere Tabelle in einem vorhandenen Dataset unter Verwendung der Schemadefinition in einer JSON-Datei erstellt:

bq mk --table project_id:dataset.table path_to_schema_file

Dabei gilt:

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

Mit dem folgenden Befehl wird in mydataset in Ihrem Standardprojekt eine Tabelle namens mytable erstellt. Das Schema ist in myschema.json angegeben:

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

Schema in der API angeben

So geben Sie ein Tabellenschema mithilfe der API an:

  • Rufen Sie zur Angabe eines Schemas beim Laden von Daten die Methode jobs.insert auf und konfigurieren Sie das Attribut schema in der Konfiguration des load-Jobs.
  • Zur Angabe eines Schemas beim Erstellen einer Tabelle rufen Sie die Methode tables.insert auf und konfigurieren das Attribut schema in der Tabellenressource.

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

Weitere Informationen

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...