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:

• Verwenden Sie die Google Cloud Konsole.
• 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. 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.

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.

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.

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:

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

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

bq mk --table project_id:dataset.table schema

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

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}");
    }
}

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

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
}

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
}

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());
    }
  }
}

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());
    }
  }
}

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

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

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 show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

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 --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

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

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 mk --table project_id:dataset.table path_to_schema_file

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

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 Zugriff auf Ressourcen mit IAM steuern.

Nächste Schritte

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