BigLake-Tabellen in Cloud Storage erstellen

Console

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

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

3. Maximieren Sie die Option more_vert Aktionen und klicken Sie auf Tabelle erstellen.

4. Geben Sie im Bereich Quelle die folgenden Details an:

   1. Wählen Sie unter Tabelle erstellen aus die Option Google Cloud Storage aus.

   2. Wählen Sie unter Datei aus GCS-Bucket auswählen oder URI-Muster auswählen einen Bucket und eine Datei aus, die verwendet werden sollen, oder geben Sie den Pfad im Format gs://bucket_name/[folder_name/]file_name ein.

      In der Google Cloud Console können Sie nicht mehrere URIs angeben. Sie können jedoch mehrere Dateien auswählen, indem Sie ein Platzhalterzeichen (*) angeben. Beispiel: gs://mybucket/file_name*. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

      Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die von Ihnen erstellte Tabelle enthält.

   3. Wählen Sie bei Dateiformat das Format aus, das zu Ihrer Datei passt.

5. Geben Sie im Bereich Ziel die folgenden Details an:

   1. Wählen Sie unter Projekt das Projekt aus, in dem die Tabelle erstellt werden soll.

   2. Wählen Sie unter Dataset das Dataset aus, in dem die Tabelle erstellt werden soll.

   3. Geben Sie unter Tabelle den Namen der Tabelle ein, die Sie in BigQuery erstellen.

   4. Wählen Sie als Tabellentyp die Option Externe Tabelle aus.

   5. Wählen Sie BigLake-Tabelle mit einer Cloud-Ressourcenverbindung erstellen aus.

   6. Wählen Sie unter Verbindungs-ID die Verbindung aus, die Sie zuvor erstellt haben.

6. Im Abschnitt Schema können Sie entweder die automatische Schemaerkennung aktivieren oder ein Schema manuell angeben, wenn Sie eine Quelldatei haben. Wenn Sie keine Quelldatei haben, müssen Sie ein Schema manuell angeben.

   • Klicken Sie auf die Option Automatisch erkennen, um die automatische Schemaerkennung zu aktivieren.

   • Wenn Sie ein Schema manuell angeben möchten, klicken Sie das Kästchen Automatisch erkennen nicht an. Klicken Sie auf Als Text bearbeiten und geben Sie das Tabellenschema als JSON-Array ein.

7. Wenn Sie Zeilen mit zusätzlichen Spaltenwerten Zeilen ignorieren möchten, die nicht mit dem Schema übereinstimmen, maximieren Sie den Abschnitt Erweiterte Optionen und wählen Sie Unbekannte Werte aus.

8. Klicken Sie auf Tabelle erstellen.

Nachdem die permanente Tabelle erstellt wurde, können Sie die Tabelle wie eine native BigQuery-Tabelle abfragen. Nach Abschluss der Abfrage können Sie die Ergebnisse als CSV- oder JSON-Dateien exportieren oder als Tabelle bzw. in Google Tabellen speichern.

SQL

Verwenden Sie die DDL-Anweisung CREATE EXTERNAL TABLE. Sie können das Schema explizit angeben oder die automatische Schemaerkennung verwenden, um das Schema aus den externen Daten abzuleiten.

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

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
     OPTIONS (
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'[,...]],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );

   Dabei gilt:

   • PROJECT_ID: der Name Ihres Projekts, in dem Sie die Tabelle erstellen möchten, z. B. myproject
   • DATASET: der Name des BigQuery-Datasets, in dem Sie die Tabelle erstellen möchten, z. B. mydataset
   • EXTERNAL_TABLE_NAME: der Name der Tabelle, die Sie erstellen möchten, z. B. mytable
   • REGION: Die Region, die die Verbindung enthält, z. B. us.
   • CONNECTION_ID: die Verbindungs-ID, z. B. myconnection

     Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

   • TABLE_FORMAT: das Format der Tabelle, die Sie erstellen möchten, z. B. PARQUET

     Weitere Informationen zu unterstützten Formaten finden Sie unter Einschränkungen.

   • BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die Daten für die externe Tabelle im Format ['gs://bucket_name/[folder_name/]file_name'] enthält.

     Sie können mehrere Dateien aus dem Bucket auswählen, indem Sie im Pfad ein Sternchenzeichen (*) angeben. Beispiel: ['gs://mybucket/file_name*']. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

     Sie können mehrere Buckets für die Option uris angeben, indem Sie mehrere Pfade angeben.

     Die folgenden Beispiele zeigen gültige uris-Werte:

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     Wenn Sie uris-Werte angeben, die auf mehrere Dateien abzielen, müssen alle diese Dateien ein kompatibles Schema verwenden.

     Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

   • STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die BigLake-Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

     Geben Sie zum Aktivieren des Metadaten-Cachings für das Intervallliteral einen Wert zwischen 30 Minuten und 7 Tagen an. Beispiel: Geben Sie INTERVAL 4 HOUR für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

   • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

     Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den Systemvorgang BQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

     Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

3. Klicken Sie auf play_circle Ausführen.

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

bq

Option 1: Tabellendefinitionsdatei

Verwenden Sie den Befehl bq mkdef, um eine Tabellendefinitionsdatei zu erstellen, und übergeben Sie dann den Dateipfad an den bq mk-Befehl so:

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

Ersetzen Sie Folgendes:

• CONNECTION_ID: die Verbindungs-ID, z. B. myconnection

  Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

• SOURCE_FORMAT: das Format der externen Datenquelle. Beispiel: PARQUET.

• BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die Daten für die Tabelle im Format gs://bucket_name/[folder_name/]file_pattern enthält.

  Sie können mehrere Dateien aus dem Bucket auswählen, indem Sie im file_pattern ein Sternchenzeichen (*) angeben. Beispiel: gs://mybucket/file00*.parquet Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

  Sie können mehrere Buckets für die Option uris angeben, indem Sie mehrere Pfade angeben.

  Die folgenden Beispiele zeigen gültige uris-Werte:

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Wenn Sie uris-Werte angeben, die auf mehrere Dateien abzielen, müssen alle diese Dateien ein kompatibles Schema verwenden.

  Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

• DEFINITION_FILE: der Pfad zur Tabellendefinitionsdatei auf Ihrem lokalen Rechner.

• STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die BigLake-Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

  Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

  Geben Sie zum Aktivieren des Metadaten-Cachings einen Intervallwert zwischen 30 Minuten und 7 Tagen unter Verwendung des in der INTERVAL-Datentypdokumentation beschriebenen Formats Y-M D H:M:S. Beispiel: Geben Sie 0-0 0 4:0:0 für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

• DATASET: der Name des BigQuery-Datasets, in dem Sie eine Tabelle erstellen möchten, z. B. mydataset

• EXTERNAL_TABLE_NAME: der Name der Tabelle, die Sie erstellen möchten, z. B. mytable

• SCHEMA: das Schema für die BigLake-Tabelle

Beispiel:

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

Um die automatische Schemaerkennung zu verwenden, geben Sie im mkdef-Befehl das --autodetect=true-Flag an und lassen das Schema weg:

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

Option 2: Inline-Tabellendefinition

Anstatt eine Tabellendefinitionsdatei zu erstellen, können Sie die Tabellendefinition direkt an den bq mk-Befehl übergeben: Verwenden Sie den Decorator @connection, um die Verbindung anzugeben, die am Ende des Parameters --external_table_definition verwendet werden soll.

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

Dabei gilt:

• SOURCE_FORMAT: das Format der externen Datenquelle

  Beispiel: CSV.

• BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die Daten für die Tabelle im Format gs://bucket_name/[folder_name/]file_pattern enthält.

  Sie können mehrere Dateien aus dem Bucket auswählen, indem Sie im file_pattern ein Sternchenzeichen (*) angeben. Beispiel: gs://mybucket/file00*.parquet Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

  Sie können mehrere Buckets für die Option uris angeben, indem Sie mehrere Pfade angeben.

  Die folgenden Beispiele zeigen gültige uris-Werte:

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Wenn Sie uris-Werte angeben, die auf mehrere Dateien abzielen, müssen alle diese Dateien ein kompatibles Schema verwenden.

  Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

• PROJECT_ID: der Name Ihres Projekts, in dem Sie die Tabelle erstellen möchten, z. B. myproject

• REGION: die Region, die die Verbindung enthält, us

• CONNECTION_ID: die Verbindungs-ID, z. B. myconnection

  Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

• DATASET_NAME: der Name des Datasets, in dem Sie die BigLake-Tabelle erstellen möchten

• TABLE_NAME: der Name der BigLake-Tabelle

• SCHEMA: das Schema für die BigLake-Tabelle

Beispiel:

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Rufen Sie die API-Methode tables.insert auf und erstellen Sie eine ExternalDataConfiguration in der Ressource Table, die Sie übergeben.

Geben Sie das Attribut schema an oder setzen Sie das Attribut autodetect auf true, um die automatische Schemaerkennung für unterstützte Datenquellen zu aktivieren.

Geben Sie das Attribut connectionId an, um die Verbindung zu identifizieren, die für die Verbindung mit Cloud Storage verwendet werden soll.

Terraform

In diesem Beispiel wird eine BigLake-Tabelle für nicht partitionierte Daten erstellt.

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

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.

Cloud Shell vorbereiten

1. Rufen Sie Cloud Shell auf.

2. Legen Sie das Google Cloud-Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

   Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

   Kopieren Sie den Beispielcode in das neu erstellte main.tf.

   Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
4. Speichern Sie die Änderungen.
5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich.

   terraform init

   Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden:

   terraform init -upgrade

Änderungen anwenden

1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen:

   terraform plan

   Korrigieren Sie die Konfiguration nach Bedarf.

2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein:

   terraform apply

   Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

3. Öffnen Sie Ihr Google Cloud-Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

Console

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

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

3. Klicken Sie auf more_vert Aktionen ansehen und dann auf Tabelle erstellen. Der Bereich Tabelle erstellen wird geöffnet.

4. Geben Sie im Bereich Quelle die folgenden Details an:

   1. Wählen Sie unter Tabelle erstellen aus die Option Google Cloud Storage aus.

   2. Geben Sie den Pfad zum Ordner mit Platzhaltern an. Beispiel: my_bucket/my_files* Der Ordner muss sich am selben Standort wie das Dataset befinden, das die Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten.

   3. Wählen Sie in der Liste Dateiformat den Dateityp aus.

   4. Klicken Sie auf das Kästchen Quelldatenpartitionierung und geben Sie die folgenden Details an:

      1. Geben Sie unter Quell-URI-Präfix auswählen das URI-Präfix ein. Beispiel: gs://my_bucket/my_files.
      2. Optional: Wenn Sie einen Partitionsfilter für alle Abfragen für diese Tabelle benötigen, klicken Sie das Kästchen Partitionsfilter anfordern an. Der Partitionsfilter, den Sie dadurch obligatorisch machen, kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Prädikatfilter für Partitionsschlüssel in Abfragen erforderlich.

      3. Wählen Sie im Bereich Partitionsinferenzmodus eine der folgenden Optionen aus:

         • Typen automatisch ableiten: Legen Sie den Erkennungsmodus des Partitionsschemas auf AUTO fest.
         • Alle Spalten sind Strings: Legen Sie den Modus für die Erkennung des Partitionsschemas auf STRINGS fest.
         • Eigene bereitstellen: Legen Sie den Erkennungsmodus für das Partitionsschema auf CUSTOM fest und geben Sie die Schemainformationen für die Partitionierungsschlüssel manuell ein. Weitere Informationen finden Sie unter Benutzerdefiniertes Partitionierungsschlüsselschema bereitstellen.

5. Geben Sie im Bereich Ziel die folgenden Details an:

   1. Wählen Sie unter Projekt das Projekt aus, in dem Sie die Tabelle erstellen möchten.
   2. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
   3. Geben Sie unter Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
   4. Wählen Sie als Tabellentyp die Option Externe Tabelle aus.
   5. Klicken Sie auf das Kästchen BigLake-Tabelle mit einer Cloud-Ressourcenverbindung erstellen.
   6. Wählen Sie unter Verbindungs-ID die Verbindung aus, die Sie zuvor erstellt haben.

6. Im Abschnitt Schema können Sie entweder die automatische Schemaerkennung aktivieren oder ein Schema manuell angeben, wenn Sie eine Quelldatei haben. Wenn Sie keine Quelldatei haben, müssen Sie ein Schema manuell angeben.

   • Klicken Sie auf die Option Automatisch erkennen, um die automatische Schemaerkennung zu aktivieren.

   • Wenn Sie ein Schema manuell angeben möchten, klicken Sie das Kästchen Automatisch erkennen nicht an. Klicken Sie auf Als Text bearbeiten und geben Sie das Tabellenschema als JSON-Array ein.

7. Wenn Sie Zeilen mit zusätzlichen Spaltenwerten Zeilen ignorieren möchten, die nicht mit dem Schema übereinstimmen, maximieren Sie den Abschnitt Erweiterte Optionen und wählen Sie Unbekannte Werte aus.

8. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung CREATE EXTERNAL TABLE:

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

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE',
     format ="TABLE_FORMAT"
   );

   Ersetzen Sie Folgendes:

   • PROJECT_ID: der Name Ihres Projekts, in dem Sie die Tabelle erstellen möchten, z. B. myproject
   • DATASET: der Name des BigQuery-Datasets, in dem Sie die Tabelle erstellen möchten, z. B. mydataset
   • EXTERNAL_TABLE_NAME: der Name der Tabelle, die Sie erstellen möchten, z. B. mytable
   • PARTITION_COLUMN: der Name der Partitionierungsspalte.
   • PARTITION_COLUMN_TYPE: der Typ der Partitionierungsspalte
   • REGION: die Region, die die Verbindung enthält, z. B. us
   • CONNECTION_ID: die Verbindungs-ID, z. B. myconnection

     Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

   • HIVE_PARTITION_URI_PREFIX: Hive-Partitionierungs-Präfix, z. B. gs://mybucket/
   • FILE_PATH: Pfad zur Datenquelle für die externe Tabelle, die Sie erstellen möchten, z. B. gs://mybucket/*.parquet
   • STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die BigLake-Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

     Geben Sie zum Aktivieren des Metadaten-Cachings für das Intervallliteral einen Wert zwischen 30 Minuten und 7 Tagen an. Beispiel: Geben Sie INTERVAL 4 HOUR für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

   • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

     Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den Systemvorgang BQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

     Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

   • TABLE_FORMAT: das Format der Tabelle, die Sie erstellen möchten, z. B. PARQUET

3. Klicken Sie auf play_circle Ausführen.

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

Beispiele

Im folgenden Beispiel wird eine BigLake-Tabelle über partitionierte Daten erstellt, wobei:

• Das Schema wird automatisch erkannt.
• Das Veralterungsintervall für Metadaten-Caches beträgt 1 Tag.
• Der Metadaten-Cache wird automatisch aktualisiert.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

Im folgenden Beispiel wird eine BigLake-Tabelle über partitionierte Daten erstellt, wobei:

• Das Schema ist angegeben.
• Das Intervall für die Metadatenveralterung für die Tabelle beträgt 8 Stunden.
• Der Metadaten-Cache muss manuell aktualisiert werden.

CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

bq

Verwenden Sie zuerst den Befehl bq mkdef, um eine Tabellendefinitionsdatei zu erstellen:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_URIS > DEFINITION_FILE

Ersetzen Sie Folgendes:

• SOURCE_FORMAT: das Format der externen Datenquelle Beispiel: CSV.
• REGION: Die Region, die die Verbindung enthält, z. B. us.

• CONNECTION_ID: die Verbindungs-ID, z. B. myconnection

  Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist die Verbindungs-ID der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

• PARTITIONING_MODE: der Hive-Partitionierungsmodus. Verwenden Sie einen der folgenden Werte:

  • AUTO: Schlüsselnamen und -typen automatisch erkennen.
  • STRINGS: Schlüsselnamen automatisch in Strings konvertieren.
  • CUSTOM: Schlüsselschema im Präfix des Quell-URI codieren.

• GCS_URI_SHARED_PREFIX: das Präfix des Quell-URI.

• BOOLEAN gibt an, ob ein Prädikatfilter zum Zeitpunkt der Abfrage erforderlich ist. Dieses Flag ist optional. Der Standardwert ist false.

• CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Sie müssen dieses Flag nur angeben, wenn Sie auch das Flag --max_staleness im nachfolgenden Befehl bq mk verwenden möchten, um das Metadaten-Caching zu aktivieren. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

  Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

  Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

  Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

• GCS_URIS: der Pfad zum Cloud Storage-Ordner im Platzhalterformat.

• DEFINITION_FILE: der Pfad zur Tabellendefinitionsdatei auf Ihrem lokalen Rechner.

Wenn PARTITIONING_MODE den Wert CUSTOM hat, fügen Sie das Partitionsschlüsselschema im Präfix des Quell-URI im folgenden Format ein:

--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Verwenden Sie nach dem Erstellen der Tabellendefinitionsdatei den Befehl bq mk, um die BigLake-Tabelle zu erstellen:

bq mk --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

Ersetzen Sie Folgendes:

• DEFINITION_FILE: der Pfad zur Tabellendefinitionsdatei.

• STALENESS_INTERVAL: gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die BigLake-Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit sie vom Vorgang verwendet werden können. Wenn Sie dieses Flag angeben, müssen Sie im vorherigen Befehl bq mkdef auch einen Wert für das Flag --metadata_cache_mode angegeben haben. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

  Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

  Geben Sie zum Aktivieren des Metadaten-Cachings einen Intervallwert zwischen 30 Minuten und 7 Tagen unter Verwendung des in der INTERVAL-Datentypdokumentation beschriebenen Formats Y-M D H:M:S. Beispiel: Geben Sie 0-0 0 4:0:0 für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

• DATASET_NAME: der Name des Datasets, das die Tabelle enthält

• TABLE_NAME: Der Name der Tabelle, die Sie erstellen.

• SCHEMA: gibt einen Pfad zu einer JSON-Schemadatei oder das Schema im Format field:data_type,field:data_type,... an. Wenn Sie die automatische Schemaerkennung verwenden möchten, lassen Sie dieses Argument weg.

Beispiele

Im folgenden Beispiel wird der Hive-Partitionierungsmodus AUTO verwendet. Außerdem wird der Metadaten-Cache auf ein 12-Stunden-Veralterungsintervall eingestellt und automatisch aktualisiert:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

Im folgenden Beispiel wird der Hive-Partitionierungsmodus STRING verwendet:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

Im folgenden Beispiel wird der Hive-Partitionierungsmodus CUSTOM verwendet:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Wenn Sie die Hive-Partitionierung mithilfe der BigQuery API festlegen möchten, fügen Sie das hivePartitioningOptions-Objekt in das ExternalDataConfiguration-Objekt ein, wenn Sie die Tabellendefinitionsdatei erstellen. Zum Erstellen einer BigLake-Tabelle müssen Sie auch einen Wert für das Feld connectionId angeben.

Wenn Sie das Feld hivePartitioningOptions.mode auf CUSTOM festlegen, müssen Sie das Schema für den Partitionierungsschlüssel im Feld hivePartitioningOptions.sourceUriPrefix folgendermaßen codieren: gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Wenn Sie die Verwendung eines Prädikatfilters zum Zeitpunkt der Abfrage erzwingen möchten, legen Sie das Feld hivePartitioningOptions.requirePartitionFilter auf true fest.

Terraform

In diesem Beispiel wird eine BigLake-Tabelle für partitionierte Daten erstellt.

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

# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.

Cloud Shell vorbereiten

1. Rufen Sie Cloud Shell auf.

2. Legen Sie das Google Cloud-Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

   Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

   Kopieren Sie den Beispielcode in das neu erstellte main.tf.

   Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
4. Speichern Sie die Änderungen.
5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich.

   terraform init

   Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden:

   terraform init -upgrade

Änderungen anwenden

1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen:

   terraform plan

   Korrigieren Sie die Konfiguration nach Bedarf.

2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein:

   terraform apply

   Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

3. Öffnen Sie Ihr Google Cloud-Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

SQL

Verwenden Sie die DDL-Anweisung CREATE OR REPLACE EXTERNAL TABLE, um eine Tabelle zu aktualisieren:

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

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

   CREATE OR REPLACE EXTERNAL TABLE
     `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `REGION.CONNECTION_ID`
     OPTIONS(
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );

   Dabei gilt:

   • PROJECT_ID: der Name des Projekts, das die Verbindung enthält
   • DATASET: der Name des Datasets, das die Tabelle enthält
   • EXTERNAL_TABLE_NAME: der Name der Tabelle
   • REGION: die Region, die die Verbindung enthält
   • CONNECTION_ID: der Name der zu verwendenden Verbindung
   • TABLE_FORMAT: das von der Tabelle verwendete Format

     Dies kann beim Aktualisieren der Tabelle nicht geändert werden.

   • BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die Daten für die externe Tabelle im Format ['gs://bucket_name/[folder_name/]file_name'] enthält.

     Sie können mehrere Dateien aus dem Bucket auswählen, indem Sie im Pfad ein Sternchenzeichen (*) angeben. Beispiel: ['gs://mybucket/file_name*']. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

     Sie können mehrere Buckets für die Option uris angeben, indem Sie mehrere Pfade angeben.

     Die folgenden Beispiele zeigen gültige uris-Werte:

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     Wenn Sie uris-Werte angeben, die auf mehrere Dateien abzielen, müssen alle diese Dateien ein kompatibles Schema verwenden.

     Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

   • STALENESS_INTERVAL: Gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit der Vorgang sie verwenden kann.

     Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

     Geben Sie zum Aktivieren des Metadaten-Cachings für das Intervallliteral einen Wert zwischen 30 Minuten und 7 Tagen an. Beispiel: Geben Sie INTERVAL 4 HOUR für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

   • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird.

     Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

     Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den Systemvorgang BQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

     Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

3. Klicken Sie auf play_circle Ausführen.

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

bq

Verwenden Sie die Befehle bq mkdef und bq update, um eine Tabelle zu aktualisieren:

1. Generieren Sie eine externe Tabellendefinition, in der die Aspekte der zu ändernden Tabelle beschrieben werden:

   bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
   --source_format=TABLE_FORMAT \
   --metadata_cache_mode=CACHE_MODE \
   "BUCKET_PATH" > /tmp/DEFINITION_FILE

   Dabei gilt:

   • PROJECT_ID: der Name des Projekts, das die Verbindung enthält
   • REGION: die Region, die die Verbindung enthält
   • CONNECTION_ID: Name der zu verwendenden Verbindung
   • TABLE_FORMAT: das von der Tabelle verwendete Format Dies kann beim Aktualisieren der Tabelle nicht geändert werden.

   • CACHE_MODE: gibt an, ob der Metadaten-Cache automatisch oder manuell aktualisiert wird. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Legen Sie AUTOMATIC fest, damit der Metadaten-Cache in einem systemdefinierten Intervall aktualisiert wird, normalerweise zwischen 30 und 60 Minuten.

     Legen Sie MANUAL fest, wenn Sie den Metadaten-Cache nach einem von Ihnen bestimmten Zeitplan aktualisieren möchten. In diesem Fall können Sie den SystemvorgangBQ.REFRESH_EXTERNAL_METADATA_CACHE aufrufen, um den Cache zu aktualisieren.

     Sie müssen CACHE_MODE festlegen, wenn STALENESS_INTERVAL auf einen Wert größer als 0 festgelegt ist.

   • BUCKET_PATH: der Pfad zum Cloud Storage-Bucket, der die Daten für die externe Tabelle im Format gs://bucket_name/[folder_name/]file_name enthält.

     Sie können die aus dem Bucket ausgewählten Dateien einschränken, indem Sie im Pfad ein Sternchenzeichen (*) angeben. Beispiel: gs://mybucket/file_name*. Weitere Informationen finden Sie unter Unterstützung von Platzhaltern für Cloud Storage-URIs.

     Sie können mehrere Buckets für die Option uris angeben, indem Sie mehrere Pfade angeben.

     Die folgenden Beispiele zeigen gültige uris-Werte:

     • gs://bucket/path1/myfile.csv
     • gs://bucket/path1/*.csv
     • gs://bucket/path1/*,gs://bucket/path2/file00*

     Wenn Sie uris-Werte angeben, die auf mehrere Dateien abzielen, müssen alle diese Dateien ein kompatibles Schema verwenden.

     Weitere Informationen zur Verwendung von Cloud Storage-URIs in BigQuery finden Sie unter Cloud Storage-Ressourcenpfad.

   • DEFINITION_FILE: der Name der Tabellendefinitionsdatei, die Sie erstellen.

2. Aktualisieren Sie die Tabelle mit der neuen externen Tabellendefinition:

   bq update --max_staleness=STALENESS_INTERVAL \
   --external_table_definition=/tmp/DEFINITION_FILE \
   PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

   Ersetzen Sie Folgendes:

   • STALENESS_INTERVAL: Gibt an, ob im Cache gespeicherte Metadaten von Vorgängen für die Tabelle verwendet werden und wie aktuell die im Cache gespeicherten Metadaten sein müssen, damit der Vorgang sie verwenden kann. Weitere Informationen zu Überlegungen zum Metadaten-Caching finden Sie unter Leistungsmetadaten-Caching.

     Geben Sie 0 an, um das Caching von Metadaten zu deaktivieren. Das ist die Standardeinstellung.

     Geben Sie zum Aktivieren des Metadaten-Cachings einen Intervallwert zwischen 30 Minuten und 7 Tagen unter Verwendung des in der INTERVAL-Datentypdokumentation beschriebenen Formats Y-M D H:M:S. Beispiel: Geben Sie 0-0 0 4:0:0 für ein Veralterungsintervall von vier Stunden an. Mit diesem Wert verwenden Vorgänge im Zusammenhang mit der Tabelle im Cache gespeicherte Metadaten, wenn sie innerhalb der letzten vier Stunden aktualisiert wurden. Sind die im Cache gespeicherten Metadaten älter, werden für den Vorgang stattdessen Metadaten aus Cloud Storage abgerufen.

   • DEFINITION_FILE: der Name der Tabellendefinitionsdatei, die Sie erstellt oder aktualisiert haben.

   • PROJECT_ID: der Name des Projekts, das die Verbindung enthält

   • DATASET: der Name des Datasets, das die Tabelle enthält

   • EXTERNAL_TABLE_NAME: der Name der Tabelle

Beispiel

Im folgenden Beispiel wird mytable so aktualisiert, dass im Cache gespeicherte Metadaten verwendet werden, solange es in den letzten 4,5 Stunden aktualisiert wurde und auch automatisch im Cache gespeicherte Metadaten aktualisiert werden:

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

Dabei hat enable_metadata.json den folgenden Inhalt: { "metadataCacheMode": "AUTOMATIC" }