Geclusterte Tabellen erstellen und verwenden

In diesem Dokument wird beschrieben, wie geclusterte Tabellen in BigQuery erstellt und verwendet werden. Eine Übersicht über die Unterstützung für geclusterte Tabellen in BigQuery finden Sie unter Einführung in geclusterte Tabellen.

Einschränkungen

Geclusterte Tabellen in BigQuery unterliegen den folgenden Einschränkungen:

  • Nur Standard-SQL wird zum Abfragen von geclusterten Tabellen und zum Schreiben von Abfrageergebnissen in geclusterte Tabellen unterstützt.
  • Sie können Clustering-Spalten nur angeben, wenn eine Tabelle erstellt wird.
  • Nachdem eine geclusterte Tabelle erstellt wurde, können die Clustering-Spalten nicht mehr geändert werden.
  • Clustering-Spalten müssen Spalten der obersten Ebene sein, die nicht wiederholt werden. Sie müssen einem der folgenden Datentypen entsprechen:

    • DATE
    • BOOL
    • GEOGRAPHY
    • INT64
    • NUMERIC
    • STRING
    • TIMESTAMP

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

  • Sie können bis zu vier Clustering-Spalten angeben.

  • Wenn für das Clustering Spalten vom Typ STRING genutzt werden, verwendet BigQuery nur die ersten 1.024 Zeichen, um die Daten zu clustern. Die Werte in den Spalten können jedoch aus mehr als 1.024 Zeichen bestehen.

Geclusterte Tabellen erstellen

So können Sie eine geclusterte Tabelle in BigQuery erstellen:

Tabellennamen

Wenn Sie eine Tabelle in BigQuery erstellen, muss der Tabellenname pro Dataset eindeutig sein. Der Tabellenname kann:

  • Bis zu 1.024 Zeichen enthalten
  • Buchstaben (groß-/kleingeschrieben), Ziffern und Unterstriche enthalten

Erforderliche Berechtigungen

Zum Erstellen einer Tabelle benötigen Sie mindestens die folgenden Berechtigungen:

  • bigquery.tables.create-Berechtigungen, um die Tabelle zu erstellen
  • bigquery.tables.updateData, um Daten mit einem Ladejob, Abfragejob oder Kopierjob in die Tabelle zu schreiben
  • bigquery.jobs.create, um einen Abfragejob, Ladejob oder Kopierjob auszuführen, der Daten in die Tabelle schreibt

Möglicherweise sind zusätzliche Berechtigungen wie bigquery.tables.getData erforderlich, um auf die Daten zuzugreifen, die Sie in die Tabelle schreiben.

Diese vordefinierten Cloud IAM-Rollen enthalten die Berechtigungen bigquery.tables.create und bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Die folgenden vordefinierten Cloud IAM-Rollen enthalten Berechtigungen des Typs bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Wenn ein Nutzer mit Berechtigungen vom Typ bigquery.datasets.create ein Dataset erstellt, hat er dafür außerdem bigquery.dataOwner-Zugriff. Mit bigquery.dataOwner-Zugriff haben Nutzer die Möglichkeit, im Dataset Tabellen zu erstellen und zu aktualisieren.

Weitere Informationen zu Cloud IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Leere geclusterte Tabelle mit einer Schemadefinition erstellen

Clustering-Spalten werden beim Erstellen einer Tabelle in BigQuery angegeben. Nachdem die Tabelle erstellt wurde, können Sie die Clustering-Spalten auch wieder ändern. Weitere Informationen dazu finden Sie unter Clustering-Spezifikation ändern.

Clustering-Spalten müssen Spalten der obersten Ebene sein, die nicht wiederholt werden. Sie müssen außerdem einem der folgenden einfachen Datentypen entsprechen:

  • DATE
  • BOOLEAN
  • GEOGRAPHY
  • INTEGER
  • NUMERIC
  • STRING
  • TIMESTAMP

Sie können bis zu vier Clustering-Spalten angeben. Wenn Sie mehrere Spalten angeben, wird anhand der Reihenfolge der Spalten festgelegt, wie die Daten sortiert werden. Wenn die Tabelle beispielsweise nach den Spalten a, b und c geclustert ist, werden die Daten in der gleichen Reihenfolge sortiert – zuerst nach Spalte a, dann nach Spalte b und dann nach Spalte c. Als Best Practice sollte die am häufigsten gefilterte oder aggregierte Spalte möglichst an erster Stelle stehen.

Die Reihenfolge Ihrer Clustering-Spalten wirkt sich auch auf die Abfrageleistung und die Preise aus. Weitere Informationen zu Best Practices für Abfragen von geclusterten Tabellen finden Sie unter Geclusterte Tabellen abfragen.

So erstellen Sie eine leere geclusterte Tabelle mit einer Schemadefinition:

Console

  1. Wechseln Sie in der Google Cloud Console zur BigQuery-Web-UI.

    Zur BigQuery-Web-UI

  2. Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.

  3. Klicken Sie auf der rechten Seite des Fensters im Detailbereich auf Tabelle erstellen.

    Schaltfläche

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

    Option

  5. Unter Ziel:

    • Wählen Sie unter Dataset-Name das entsprechende Dataset aus und geben Sie im Feld Tabellenname den Namen der zu erstellenden Tabelle ein.
    • Achten Sie darauf, dass der Tabellentyp auf Native Tabelle eingestellt ist.
  6. Geben Sie unter Schema die Schemadefinition ein.

    • So können Sie Schemainformationen manuell eingeben:

      • Klicken Sie auf Als Text bearbeiten und geben Sie das Tabellenschema als JSON-Array ein.

      • Geben Sie das Schema mit Feld hinzufügen manuell ein.

  7. Optional: Wählen Sie unter Partitions- und Clustereinstellungen die Option Nach Feld partitionieren aus und wählen Sie die Spalte DATE oder TIMESTAMP aus. Diese Option ist nicht verfügbar, wenn das Schema keine Spalte des Typs DATE oder TIMESTAMP enthält.

    Wählen Sie Nach Aufnahmezeit partitionieren aus, um eine nach Aufnahmezeit partitionierte Tabelle zu erstellen.

  8. Optional: Klicken Sie unter Partitionierungsfilter auf das Kästchen Partitionsfilter anfordern, damit Nutzer eine WHERE-Klausel zur Angabe der abzufragenden Partitionen einfügen müssen. Das Anfordern eines Partitionsfilters kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Partitionierte Tabellen abfragen.

  9. Geben Sie unter Clustering-Reihenfolge zwischen ein und vier kommagetrennte Spaltennamen ein.

  10. Optional: Klicken Sie auf Erweiterte Optionen und dann unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel beibehalten, verschlüsselt BigQuery inaktive Daten.

  11. Klicken Sie auf Tabelle erstellen.

Klassische UI

  1. Rufen Sie die klassische BigQuery-Web-UI auf.

    Zur klassischen 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. Klicken Sie auf der Seite Create Table (Tabelle erstellen) im Abschnitt Source Data (Quelldaten) auf Create empty table (Leere Tabelle erstellen).

  4. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Zieltabelle so vor:

    • Wählen Sie für Tabellenname das entsprechende Dataset aus und geben Sie im Namensfeld für die Tabelle den Namen der Tabelle ein, die Sie in BigQuery erstellen.
    • Achten Sie darauf, dass der Tabellentyp auf Native Tabelle eingestellt ist.
  5. Führen Sie im Abschnitt Schema eine manuelle Eingabe der Schemadefinition aus.

    • So können Sie Schemainformationen manuell eingeben:

      • Klicken Sie auf Edit as text (Als Text bearbeiten) und geben Sie das Tabellenschema als JSON-Array ein.

      • Geben Sie das Schema mit Add Field (Feld hinzufügen) ein.

  6. Unter Options (Optionen):

    • Klicken Sie unter Partitionierungstyp auf Keiner und wählen Sie Tag aus.
    • Wählen Sie für das Partitioning Field (Partitionierungsfeld) eine der folgenden Optionen aus:
      • Wählen Sie timestamp aus, um eine Tabelle zu erstellen, die nach einer Spalte vom Typ DATE oder TIMESTAMP partitioniert ist.
      • Wählen Sie _PARTITIONTIME aus, um eine nach Aufnahmezeit partitionierte Tabelle zu erstellen.
    • Geben Sie für Clustering Fields (Clustering-Felder) zwischen einem und vier Feldnamen ein.
    • Übernehmen Sie im Feld Destination encryption die Option Default. Dieses Attribut gilt für vom Kunden verwaltete Verschlüsselungsschlüssel. BigQuery verschlüsselt standardmäßig inaktive Kundendaten.

      Details zu partitionierten Tabellen

  7. Klicken Sie auf Tabelle erstellen.

Nachdem die Tabelle erstellt wurde, können Sie die Ablaufzeit der Tabelle, die Beschreibung und die Labels der geclusterten Tabelle ändern. Nachdem eine Tabelle mit der BigQuery-Web-UI erstellt wurde, können Sie keine Ablaufzeit für die Partition mehr einfügen.

bq

Verwenden Sie den Befehl mk mit den folgenden Flags:

  • --table (oder die Tastenkombination -t).
  • --schema. Sie können die Schemadefinition der Tabelle inline oder über eine JSON-Schemadatei bereitstellen.
  • --clustering_fields. Sie können bis zu vier Clustering-Spalten angeben.

Zu den optionalen Parametern gehören --expiration, --description, --time_partitioning_type, --time_partitioning_field, --time_partitioning_expiration, --destination_kms_key und --label.

Wenn Sie eine Tabelle in einem anderen Projekt als dem Standardprojekt erstellen, fügen Sie dem Dataset die Projekt-ID im folgenden Format hinzu: project_id:dataset.

--destination_kms_key wird hier nicht erläutert. Weitere Informationen zu --destination_kms_key finden Sie unter Vom Kunden verwaltete Verschlüsselungsschlüssel.

Geben Sie den folgenden Befehl ein, um eine leere geclusterte Tabelle mit einer Schemadefinition zu erstellen:

bq mk \
--table \
--expiration INTEGER1 \
--schema SCHEMA \
--time_partitioning_type=DAY \
--time_partitioning_field PARTITION_COLUMN \
--clustering_fields CLUSTER_COLUMNS \
--time_partitioning_expiration INTEGER2 \
--description "DESCRIPTION" \
--label KEY:VALUE,KEY:VALUE \
PROJECT_ID:DATASET.TABLE

Ersetzen Sie Folgendes:

  • INTEGER1: die Standardlebensdauer der Tabelle in Sekunden. Der Mindestwert beträgt 3.600 Sekunden bzw. eine Stunde. Die Ablaufzeit entspricht der aktuellen UTC-Zeit plus dem ganzzahligen Wert. Wenn Sie die Ablaufzeit beim Erstellen einer zeitpartitionierten Tabelle festlegen, wird die Standardeinstellung des Datasets für die Ablaufzeit der Tabelle ignoriert. Bei Angabe dieses Werts werden die Tabelle und alle Partitionen zur festgelegten Zeit gelöscht.
  • SCHEMA: eine Inline-Schemadefinition im Format COLUMN:DATA_TYPE,COLUMN:DATA_TYPE oder der Pfad zur JSON-Schemadatei auf Ihrem lokalen Computer.
  • PARTITION_COLUMN: der Name der Spalte TIMESTAMP oder DATE, die zum Erstellen einer partitionierten Tabelle verwendet wird. Wenn Sie eine partitionierte Tabelle erstellen, müssen Sie das Flag --time_partitioning_type=DAY nicht angeben.
  • CLUSTER_COLUMNS: eine durch Kommas getrennte Liste mit bis zu vier Clustering-Spalten. Die Liste darf keine Leerzeichen enthalten.
  • INTEGER2: die Standardlebensdauer in Sekunden für die Partitionen der Tabelle. Es gibt keinen Mindestwert. Die Ablaufzeit entspricht dem Datum der Partition plus dem ganzzahligen Wert. Der Ablauf der Partition ist unabhängig vom Ablauf der Tabelle, hat jedoch keinen Vorrang. Wenn Sie einen Partitionsablauf festlegen, der länger als der Ablauf der Tabelle ist, hat der Ablauf der Tabelle Vorrang.
  • DESCRIPTION: eine Beschreibung der Tabelle in Anführungszeichen.
  • KEY:VALUE: das Schlüssel/Wert-Paar, das ein Label darstellt. Mit einer durch Kommas getrennten Liste können Sie mehrere Labels eingeben.
  • PROJECT_ID: Ihre Projekt-ID.
  • DATASET: ein Dataset in Ihrem Projekt.
  • TABLE: der Name der partitionierten Tabelle, die Sie 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. Als Modus ist standardmäßig NULLABLE eingestellt. Wenn Sie Beschreibungen, Modi und RECORD-Typen einbinden möchten, müssen Sie stattdessen eine JSON-Schemadatei bereitstellen.

Beispiele:

Mit dem folgenden Befehl können Sie eine geclusterte Tabelle mit dem Namen myclusteredtable in mydataset in Ihrem Standardprojekt erstellen. Die Tabelle ist eine partitionierte Tabelle (partitioniert nach einer Spalte vom Typ TIMESTAMP). Die Ablaufzeit der Partitionierung ist auf 86.400 Sekunden (1 Tag) gesetzt. Die Ablaufzeit der Tabelle ist auf 2.592.000 Sekunden (ein Monat mit 30 Tagen) gesetzt. Die Beschreibung ist auf This is my clustered table und das Label auf organization:development eingestellt. Bei dem Befehl wird das Kürzel -t anstelle von --table verwendet.

So wird das Schema inline angegeben: timestamp:timestamp,customer_id:string,transaction_amount:float. Das angegebene Clustering-Feld customer_id wird verwendet, um die Partitionen zu clustern.

bq mk -t \
--expiration 2592000 \
--schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
--time_partitioning_field timestamp \
--clustering_fields customer_id \
--time_partitioning_expiration 86400  \
--description "This is my clustered table" \
--label org:dev \
mydataset.myclusteredtable

Geben Sie den folgenden Befehl ein, um eine geclusterte Tabelle mit dem Namen myclusteredtable in myotherproject und nicht in Ihrem Standardprojekt zu erstellen. Die Tabelle ist eine nach Aufnahmezeit partitionierte Tabelle. Die Ablaufzeit der Partitionierung ist auf 259.200 Sekunden (drei Tage), die Beschreibung auf This is my partitioned table und das Label auf organization:development gesetzt. Bei dem Befehl wird das Kürzel -t anstelle von --table verwendet. Dieser Befehl gibt keine Tabellenablaufzeit an. Wenn im Dataset ein Standardablaufwert für Tabellen festgelegt ist, wird dieser angewendet. Wenn im Dataset kein Standardablaufwert für Tabellen festgelegt ist, läuft die Tabelle nie ab, die Partitionen jedoch nach drei Tagen.

Das Schema wird in einer lokalen JSON-Datei angegeben: /tmp/myschema.json. Das Feld customer_id dient zum Clustern der Partitionen.

bq mk -t \
--expiration 2592000 \
--schema /tmp/myschema.json \
--time_partitioning_type=DAY \
--clustering_fields=customer_id \
--time_partitioning_expiration 86400  \
--description "This is my partitioned table" \
--label org:dev \
myotherproject:mydataset.myclusteredtable

Nachdem eine Tabelle erstellt wurde, können Sie die Ablaufzeit der Tabelle, die Ablaufzeit der Partition, die Beschreibung und die Labels der partitionierten Tabelle ändern.

API

Rufen Sie die Methode tables.insert mit einer definierten Tabellenressource auf, die die Attribute timePartitioning, clustering.fields und schema festlegt.

Go

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

import (
	"context"
	"fmt"
	"time"

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

// createTableClustered demonstrates creating a BigQuery table with advanced properties like
// partitioning and clustering features.
func createTableClustered(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: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	metaData := &bigquery.TableMetadata{
		Schema: sampleSchema,
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "timestamp",
			Expiration: 90 * 24 * time.Hour,
		},
		Clustering: &bigquery.Clustering{
			Fields: []string{"origin", "destination"},
		},
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
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.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class CreateClusteredTable {
  public static void runCreateClusteredTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createClusteredTable(datasetName, tableName);
  }

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

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

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

Geclusterte Tabelle aus einem Abfrageergebnis erstellen

Es gibt zwei Möglichkeiten, eine geclusterte Tabelle aus einem Abfrageergebnis zu erstellen:

Eine geclusterte Tabelle kann durch Abfrage einer partitionierten Tabelle oder einer nicht partitionierten Tabelle erstellt werden. Es ist nicht möglich, eine vorhandene Tabelle mithilfe von Abfrageergebnissen in eine geclusterte Tabelle zu ändern.

Wenn Sie eine geclusterte Tabelle aus einem Abfrageergebnis erstellen, müssen Sie Standard-SQL verwenden. Legacy-SQL wird derzeit nicht zum Abfragen geclusterter Tabellen oder zum Schreiben von Abfrageergebnissen in geclusterte Tabellen unterstützt.

Console

Sie können keine Clustering-Optionen für eine Zieltabelle angeben, wenn Sie Daten über die BigQuery-Web-UI der Konsole abfragen, außer Sie verwenden eine DDL-Anweisung. Weitere Informationen finden Sie unter DDL-Anweisungen verwenden.

Klassische UI

Sie können keine Clustering-Optionen für eine Zieltabelle angeben, wenn Sie Daten über die klassische BigQuery-Web-UI abfragen, außer Sie verwenden eine DDL-Anweisung. Weitere Informationen finden Sie unter DDL-Anweisungen verwenden.

bq

Geben Sie den folgenden Befehl ein, um eine neue geclusterte Zieltabelle aus einem Abfrageergebnis zu erstellen:

bq --location=LOCATION query \
--use_legacy_sql=false 'QUERY'

Ersetzen Sie Folgendes:

  • LOCATION: Der 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.
  • QUERY: eine Abfrage in Standard-SQL-Syntax. Derzeit können Sie kein Legacy-SQL zum Abfragen von geclusterten Tabellen oder zum Schreiben von Abfrageergebnissen in geclusterte Tabellen verwenden. Die Abfrage kann die DDL-Anweisung CREATE TABLE enthalten, mit der die Optionen zum Erstellen Ihrer geclusterten Tabelle angegeben werden. Sie können DDL anstelle der einzelnen Befehlszeilen-Flags verwenden.

Beispiele:

Mit dem folgenden Befehl schreiben Sie Abfrageergebnisse in eine Zieltabelle mit dem Namen myclusteredtable in mydataset. mydataset befindet sich in Ihrem Standardprojekt. Mit der Abfrage werden Daten aus "mytable", einer nicht partitionierten Tabelle, abgerufen. Die Spalte customer_id der Tabelle dient dazu, die Tabelle zu clustern. Die Spalte timestamp der Tabelle wird zum Erstellen einer partitionierten Tabelle verwendet.

bq query --use_legacy_sql=false \
'CREATE TABLE
   mydataset.myclusteredtable
 PARTITION BY
   DATE(timestamp)
 CLUSTER BY
   customer_id AS
 SELECT
   *
 FROM
   `mydataset.mytable`'

API

Rufen Sie zum Speichern von Abfrageergebnissen in einer geclusterten Tabelle die Methode jobs.insert auf, konfigurieren Sie einen query-Job und fügen Sie die DDL-Anweisung CREATE TABLE ein, mit der die geclusterte Tabelle erstellt wird.

Geben Sie im Abschnitt jobReference der Jobressource Ihren Standort im Attribut location an.

Geclusterte Tabelle beim Laden von Daten erstellen

Sie können eine geclusterte Tabelle erstellen, indem Sie beim Laden von Daten in eine neue Tabelle Clustering-Spalten angeben. Sie müssen keine leere Tabelle erstellen, bevor Sie die Daten laden. Sie können die geclusterte Tabelle erstellen und gleichzeitig Daten in diese Tabelle laden.

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

So definieren Sie Clustering, wenn Sie einen Ladejob definieren:

API

Wenn Sie beim Erstellen einer Tabelle über einen Ladejob die Clustering-Konfiguration definieren, können Sie die Clustering-Attribute für die Tabelle darstellen.

Go

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

import (
	"context"
	"fmt"

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

// importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
// properties.
func importClusteredTable(projectID, destDatasetID, destTableID 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/sample-transactions/transactions.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field: "timestamp",
	}
	loader.Clustering = &bigquery.Clustering{
		Fields: []string{"origin", "destination"},
	}
	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
}

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
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;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class LoadTableClustered {

  public static void runLoadTableClustered() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadTableClustered(datasetName, tableName, sourceUri);
  }

  public static void loadTableClustered(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();

      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).build());

      // 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 = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into clustered table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Data not loaded into clustered table during load job \n" + e.toString());
    }
  }
}

Zugriff auf geclusterte Tabellen steuern

Um den Zugriff auf Tabellen und Ansichten zu konfigurieren, können Sie einer Entität auf den folgenden Ebenen, geordnet vom größten zulässigen Ressourcenbereich zum kleinsten, eine IAM-Rolle zuweisen:

  • auf einer übergeordneten Ebene in der Google Cloud-Ressourcenhierarchie, z. B. der Projekt-, Ordner- oder Organisationsebene
  • auf der Dataset-Ebene
  • auf der Tabellen-/Ansichtsebene

Der Zugriff über eine durch Cloud IAM geschützte Ressource ist additiv. Wenn eine Entität beispielsweise keinen Zugriff auf übergeordneter Ebene (z. B. Projektebene) hat, können Sie der Entität Zugriff auf Dataset-Ebene gewähren. Die Entität hat dann Zugriff auf die Tabellen und Ansichten im Dataset. Wenn die Entität dagegen weder Zugriff auf übergeordneter Ebene noch auf Dataset-Ebene hat, können Sie der Entität Zugriff auf Tabellen- oder Ansichtsebene gewähren.

Wenn Sie in der Google Cloud-Ressourcenhierarchie Cloud IAM-Rollen auf einer höheren Ebene zuweisen, z. B. auf Projekt-, Ordner- oder Organisationsebene, erhält die Entität Zugriff auf eine Vielzahl von Ressourcen. Wenn Sie beispielsweise einer Entität auf Projektebene eine Rolle zuweisen, erhält diese Entität Berechtigungen, die für alle Datasets im gesamten Projekt gelten.

Durch das Zuweisen einer Rolle auf Dataset-Ebene werden die Vorgänge angegeben, die eine Entität für Tabellen und Ansichten in diesem bestimmten Dataset ausführen darf, auch wenn die Entität keinen Zugriff auf einer höheren Ebene hat. Informationen zum Konfigurieren von Zugriffssteuerungen auf Dataset-Ebene finden Sie unter Zugriff auf Datasets steuern.

Durch das Zuweisen einer Rolle auf Tabellen- oder Ansichtsebene werden die Vorgänge angegeben, die eine Entität für bestimmte Tabellen und Ansichten ausführen darf, auch wenn die Entität keinen Zugriff auf einer höheren Ebene hat. Informationen zum Konfigurieren von Zugriffssteuerungen auf Tabellenebene finden Sie unter Zugriff auf Tabellen und Ansichten steuern.

Sie können auch benutzerdefinierte Cloud IAM-Rollen erstellen. Wenn Sie eine benutzerdefinierte Rolle erstellen, hängen die erteilten Berechtigungen von den spezifischen Vorgängen ab, die die Entität ausführen soll.

Sie können für eine durch Cloud IAM geschützte Ressource keine "Ablehnen"-Berechtigung festlegen.

Weitere Informationen zu Rollen und Berechtigungen finden Sie unter:

Geclusterte Tabellen verwenden

Informationen zu geclusterten Tabellen abrufen

Sie können Informationen zu Tabellen mit den folgenden Methoden abrufen:

  • Mit der Cloud Console oder der klassischen BigQuery-Web-UI
  • Mit dem Befehl bq show der Befehlszeile
  • Durch Aufrufen der API-Methode tables.get
  • Abfragen von INFORMATION_SCHEMA-Ansichten

Erforderliche Berechtigungen

Sie benötigen mindestens Berechtigungen vom Typ bigquery.tables.get, um Informationen zu Tabellen abzurufen. Die folgenden vordefinierten Cloud IAM-Rollen enthalten die Berechtigungen vom Typ bigquery.tables.get:

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

Wenn ein Nutzer mit Berechtigungen vom Typ bigquery.datasets.create ein Dataset erstellt, hat er dafür außerdem bigquery.dataOwner-Zugriff. Mit dem bigquery.dataOwner-Zugriff hat der Nutzer die Möglichkeit, Informationen über Tabellen in einem Dataset abzurufen.

Weitere Informationen zu Cloud IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Informationen zu geclusterten Tabellen abrufen

So rufen Sie Informationen zu einer geclusterten Tabelle ab:

Konsole

  1. Wechseln Sie in der Google Cloud Console zum Bereich Ressourcen. Klicken Sie auf den Dataset-Namen, um das Dataset einzublenden. Klicken Sie dann auf den Namen der Tabelle, die Sie aufrufen möchten.

  2. Klicken Sie auf Details. Auf dieser Seite werden die Details der Tabelle einschließlich der Cluster-Spalten angezeigt.

    Tabellendetails

Klassische UI

  1. Klicken Sie im Navigationsbereich auf den Abwärtspfeil Abwärtspfeilsymbol links neben dem Dataset, um es einzublenden, oder doppelklicken Sie auf den Dataset-Namen. Hierdurch werden die Tabellen und Ansichten im Dataset angezeigt.

  2. Klicken Sie auf den Tabellennamen.

  3. Klicken Sie auf Details. Auf der Seite Tabellendetails werden die Details der Tabelle einschließlich der Clustering-Spalten angezeigt.

    Details zu geclusterten Tabellen

bq

Führen Sie den Befehl bq show aus, um alle Tabelleninformationen aufzurufen. Verwenden Sie das Flag --schema, wenn nur Informationen zum Tabellenschema angezeigt werden sollen. Mit dem Flag --format kann die Ausgabe gesteuert werden.

Wenn Sie Informationen zu einer Tabelle in einem anderen Projekt als Ihrem Standardprojekt abrufen, fügen Sie dem Dataset die Projekt-ID im folgenden Format hinzu: project_id:dataset

bq show \
--schema \
--format=prettyjson \
PROJECT_ID:DATASET.TABLE

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID
  • DATASET: der Name des Datasets
  • TABLE: der Name der Tabelle

Beispiele:

Geben Sie den folgenden Befehl ein, um alle Informationen zu myclusteredtable in mydataset aufzurufen. mydataset in Ihrem Standardprojekt.

bq show --format=prettyjson mydataset.myclusteredtable

Die Ausgabe sollte so in etwa aussehen:

{
  "clustering": {
    "fields": [
      "customer_id"
    ]
  },
...
}

API

Mithilfe der Methode bigquery.tables.get geben Sie alle relevanten Parameter an.

SQL

Bei geclusterten Tabellen können Sie in der Ansicht INFORMATION_SCHEMA.COLUMNS die Spalte CLUSTERING_ORDINAL_POSITION abfragen, um Informationen über die Clustering-Spalten einer Tabelle abzurufen.

-- Set up a table with clustering.
CREATE TABLE myDataset.data (column1 INT64, column2 INT64)
PARTITION BY _PARTITIONDATE
CLUSTER BY column1, column2;

-- This query returns 1 for column1 and 2 for column2.
SELECT column_name, clustering_ordinal_position
FROM myDataset.INFORMATION_SCHEMA.COLUMNS;

Weitere Tabellenmetadaten sind über die Ansichten TABLES, TABLE_OPTIONS, COLUMNS und COLUMN_FIELD_PATH in INFORMATION_SCHEMA verfügbar.

Geclusterte Tabellen in einem Dataset auflisten

Mithilfe der folgenden Ansätze können Sie geclusterte Tabellen in Datasets auflisten:

  • Mit der Cloud Console oder der klassischen BigQuery-Web-UI
  • Mit dem Befehl bq ls der Befehlszeile
  • Durch Aufrufen der API-Methode tables.list
  • Mit den Clientbibliotheken
  • Durch Abfragen der Spalte CLUSTERING_ORDINAL_POSITION in der Ansicht INFORMATION_SCHEMA.COLUMNS

Die Berechtigungen und die Vorgehensweise zum Auflisten von geclusterten Tabellen sind dieselben wie für partitionierte Tabellen. Weitere Informationen zum Auflisten von Tabellen finden Sie unter Partitionierte Tabellen in einem Dataset auflisten.

Clustering-Spezifikation ändern

Tabellen-Clustering-Spezifikationen können durch Aufrufen der Methode tables.update oder tables.patch geändert oder entfernt werden. Die Gruppe geclusterter Spalten in einer geclusterten Tabelle lässt sich auch in eine andere Gruppe von Spalten ändern. Diese Methode zum Aktualisieren der Gruppe von Clustering-Spalten eignet sich am besten für Tabellen mit kontinuierlichen Streaming-Insert-Anweisungen, da diese auf anderem Wege nicht so einfach ausgetauscht werden können.

Wenn eine nicht geclusterte Tabelle in eine geclusterte Tabelle umgewandelt oder die Gruppe geclusterter Spalten geändert wird, funktioniert das automatische Re-Clustering nur ab diesem Zeitpunkt. Beispiel: Eine nicht geclusterte 1-PB-Tabelle, die mit tables.update in eine geclusterte Tabelle umgewandelt wird, hat weiterhin 1 PB an nicht geclusterten Daten. Das automatische Re-Clustering gilt nur für neue Daten, die nach der Aktualisierung per Commit in die Tabelle übernommen werden.

Tipp