Daten nach Spanner exportieren (umgekehrte ETL)

In diesem Dokument wird beschrieben, wie Sie einen Workflow für Reverse Extrahieren, Transformieren und Laden (Reverse ETL) von BigQuery nach Spanner einrichten. Dazu verwenden Sie die Anweisung EXPORT DATA, um Daten aus BigQuery-Datenquellen, einschließlich Iceberg-Tabellen, in eine Spanner-Tabelle zu exportieren.

Dieser umgekehrte ETL-Workflow kombiniert Analysefunktionen in BigQuery mit niedriger Latenz und hohem Durchsatz in Spanner. Mit diesem Workflow können Sie Daten für Anwendungsnutzer bereitstellen, ohne dabei Kontingente und Limits in BigQuery aufzubrauchen.

Hinweis

• Erstellen Sie eine Spanner-Datenbank mit einer Tabelle, in der die exportierten Daten empfangen werden.

• Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.

• Erstellen Sie eine Reservierung für Enterprise oder eine höhere Stufe. Sie können die BigQuery-Verarbeitungskosten senken, wenn Sie einmalige Exporte nach Spanner ausführen, indem Sie eine Baseline-Slotkapazität von null festlegen und Autoscaling aktivieren.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Exportieren von BigQuery-Daten nach Spanner benötigen:

• Daten aus einer BigQuery-Tabelle exportieren: BigQuery-Datenbetrachter (roles/bigquery.dataViewer)
• Extrahierungsjob ausführen: BigQuery-Nutzer (roles/bigquery.user)
• Parameter der Spanner-Instanz prüfen: Cloud Spanner-Betrachter (roles/spanner.viewer)
• Daten in eine Spanner-Tabelle schreiben: Cloud Spanner-Datenbank-Nutzer (roles/spanner.databaseUser)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Beschränkungen

• Diese Funktion wird in Assured Workloads nicht unterstützt.

• Für die folgenden BigQuery-Datentypen gibt es keine Entsprechungen in Spanner und werden nicht unterstützt:

• Die maximale Größe einer exportierten Zeile darf 1 MiB nicht überschreiten.

• Spanner erzwingt während des Exports die referenzielle Integrität. Wenn die Zieltabelle einer anderen Tabelle untergeordnet ist (INTERLEAVE IN PARENT) oder wenn die Zieltabelle Fremdschlüsseleinschränkungen hat, werden die Fremdschlüssel und der übergeordnete Schlüssel während des Exports geprüft. Wenn eine exportierte Zeile in eine Tabelle mit INTERLEAVE IN PARENT geschrieben wird und die übergeordnete Zeile nicht vorhanden ist, schlägt der Export fehl und es wird die Meldung „Übergeordnete Zeile fehlt. Zeile kann nicht geschrieben werden“ angegeben. Wenn die exportierte Zeile in eine Tabelle mit Fremdschlüsseleinschränkungen geschrieben wird und auf einen nicht vorhandenen Schlüssel verweist, schlägt der Export mit dem Fehler „Fremdschlüsseleinschränkung verletzt“ fehl. Wenn Sie in mehrere Tabellen exportieren, sollten Sie den Export so sequenzieren, dass die referenzielle Integrität erhalten bleibt. Das bedeutet in der Regel, dass übergeordnete Tabellen und Tabellen, auf die über Fremdschlüssel verwiesen wird, vor Tabellen exportiert werden müssen, die auf diese verweisen.

  Wenn die Tabelle, die das Ziel des Exports ist, Fremdschlüsseleinschränkungen hat oder eine untergeordnete Tabelle einer anderen Tabelle ist (INTERLEAVE IN PARENT), muss die übergeordnete Tabelle vor dem Export der untergeordneten Tabelle ausgefüllt werden und alle entsprechenden Schlüssel enthalten. Wenn Sie versuchen, eine untergeordnete Tabelle zu exportieren, während eine übergeordnete Tabelle nicht alle relevanten Schlüssel enthält, schlägt der Export fehl.

• Ein BigQuery-Job, z. B. ein Extrahierungsjob in Spanner, hat eine maximale Dauer von 6 Stunden. Informationen zur Optimierung großer Extraktionsjobs finden Sie unter Exportoptimierung. Alternativ können Sie die Eingabe in einzelne Datenblöcke aufteilen, die als einzelne Extraktionsjobs exportiert werden können.

• Exporte nach Spanner werden nur für die Versionen BigQuery Enterprise oder Enterprise Plus unterstützt. BigQuery Standard und On-Demand-Computing werden nicht unterstützt.

• Sie können keine kontinuierlichen Abfragen verwenden, um Daten in Spanner-Tabellen mit automatisch generierten Primärschlüsseln zu exportieren.

• Sie können keine kontinuierlichen Abfragen verwenden, um Daten in Spanner-Tabellen in einer Datenbank im PostgreSQL-Dialekt zu exportieren.

• Wenn Sie kontinuierliche Abfragen zum Exportieren in eine Spanner-Tabelle verwenden, achten Sie darauf, dass Sie einen Primärschlüssel auswählen, der in Ihrer BigQuery-Tabelle keiner monoton steigenden Ganzzahl entspricht. Dies kann zu Leistungsproblemen beim Export führen. Informationen zu Primärschlüsseln in Spanner und Möglichkeiten zur Behebung dieser Leistungsprobleme finden Sie unter Primärschlüssel auswählen.

Exporte mit der Option spanner_options konfigurieren

Mit der Option spanner_options können Sie eine Spanner-Zieldatenbank und -tabelle angeben. Die Konfiguration wird in Form eines JSON-Strings ausgedrückt, wie im folgenden Beispiel gezeigt:

EXPORT DATA OPTIONS(
   uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
   spanner_options = """{
      "table": "TABLE_NAME",
      "change_timestamp_column": "CHANGE_TIMESTAMP",
      "priority": "PRIORITY",
      "tag": "TAG",
   }"""
)

Ersetzen Sie Folgendes:

• PROJECT_ID: Der Name Ihres Cloud de Confiance -Projekts.
• INSTANCE_ID: der Name Ihrer Datenbankinstanz
• DATABASE_ID: der Name Ihrer Datenbank
• TABLE_NAME: der Name einer vorhandenen Zieltabelle
• CHANGE_TIMESTAMP: der Name der Spalte vom Typ TIMESTAMP in der Ziel-Spanner-Tabelle. Diese Option wird beim Exportieren verwendet, um den Zeitstempel der letzten Zeilenaktualisierung zu erfassen. Wenn diese Option angegeben ist, wird beim Export zuerst die Zeile in der Spanner-Tabelle gelesen, um sicherzustellen, dass nur die letzte Zeilenaktualisierung geschrieben wird. Wir empfehlen, beim Ausführen eines kontinuierlichen Exports eine Spalte vom Typ TIMESTAMP anzugeben, wenn die Reihenfolge der Änderungen an Zeilen mit demselben Primärschlüssel wichtig ist.
• PRIORITY (optional): Priorität der Schreibanfragen Zulässige Werte: LOW, MEDIUM, HIGH Standardwert: MEDIUM
• TAG (optional): Anfrage-Tag, um den Exporter-Traffic im Spanner-Monitoring zu identifizieren. Standardwert: bq_export

Anforderungen für Exportabfragen

Für den Export von Abfrageergebnissen nach Spanner müssen die Ergebnisse die folgenden Voraussetzungen erfüllen:

• Alle Spalten in der Ergebnismenge müssen in der Zieltabelle vorhanden sein und ihre Typen müssen übereinstimmen oder konvertierbar sein.
• Die Ergebnismenge muss alle NOT NULL-Spalten für die Zieltabelle enthalten.
• Spaltenwerte dürfen die Spanner-Datengrößenlimits in Tabellen nicht überschreiten.
• Nicht unterstützte Spaltentypen müssen vor dem Export in Spanner in einen der unterstützten Typen konvertiert werden.

Typkonvertierungen

Zur Vereinfachung wendet der Spanner-Exporter automatisch die folgenden Typkonvertierungen an:

Daten exportieren

Mit der Anweisung EXPORT DATA können Sie Daten aus einer BigQuery-Tabelle in eine Spanner-Tabelle exportieren.

Im folgenden Beispiel werden ausgewählte Felder aus einer Tabelle mit dem Namen mydataset.table1 exportiert:

EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME" }"""
)
AS SELECT * FROM mydataset.table1;

Ersetzen Sie Folgendes:

• PROJECT_ID: Der Name Ihres Cloud de Confiance -Projekts
• INSTANCE_ID: der Name Ihrer Datenbankinstanz
• DATABASE_ID: der Name Ihrer Datenbank
• TABLE_NAME: der Name einer vorhandenen Zieltabelle

Mehrere Ergebnisse mit demselben rowkey-Wert exportieren

Wenn Sie ein Ergebnis exportieren, das mehrere Zeilen mit demselben rowkey-Wert enthält, enden die in Spanner geschriebenen Werte in derselben Spanner-Zeile. Im durch den Export erstellten Spanner-Zeilensatz ist nur eine übereinstimmende BigQuery-Zeile enthalten (es kann nicht garantiert werden, welche).

Mit einer CLOUD_RESOURCE-Verbindung exportieren

Sie können Schreibberechtigungen für eine CLOUD_RESOURCE-Verbindung für BigQuery delegieren, um Exporte auszuführen, ohne einem Nutzer direkten Zugriff auf die Spanner-Datenbank zu gewähren.

Führen Sie vor dem Exportieren in Spanner mit einer CLOUD_RESOURCE-Verbindung die folgenden Schritte aus:

Verbindung herstellen

Sie können eine CLOUD_RESOURCE-Verbindung erstellen oder eine vorhandene verwenden, um eine Verbindung zu Spanner herzustellen.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

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

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Öffnen Sie die Verbindung, nachdem Sie sie erstellt haben. Kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID. Sie benötigen diese ID, wenn Sie Berechtigungen für die Verbindung konfigurieren. Wenn Sie eine Verbindungsressource erstellen, erstellt BigQuery ein eindeutiges Systemdienstkonto und ordnet es der Verbindung zu.

Zugriff einrichten

Sie müssen dem Dienstkonto, das mit der neuen Verbindung verknüpft ist, Schreibzugriff auf Ihre Spanner-Instanz oder -Datenbank gewähren. Wir empfehlen, die vordefinierte IAM-Rolle Cloud Spanner Database User (roles/spanner.databaseUser) zu verwenden. Für diese Schritte benötigen Sie die Dienstkonto-ID, die Sie beim Erstellen der Verbindung kopiert haben.

So gewähren Sie Zugriff auf Rollen auf Datenbankebene für das Dienstkonto:

1. Rufen Sie die Seite „Spanner-Instanzen“ auf.

   Zur Seite "Instanzen"

2. Klicken Sie auf den Namen der Instanz, die die Datenbank enthält.

3. Klicken Sie auf dem Tab Übersicht auf das Kästchen Ihrer Datenbank.

4. Das Dialogfeld Infofeld wird angezeigt. Klicken Sie auf Hauptkonto hinzufügen.

5. Geben Sie für Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.

6. Wählen Sie im Feld Rolle auswählen eine Rolle mit spanner.databases.write-Berechtigungen aus. Wir empfehlen die Verwendung der Rolle Cloud Spanner-Datenbanknutzer.

7. Klicken Sie auf Speichern.

Export über die CLOUD_RESOURCE-Verbindung ausführen

Nachdem die Verbindung hergestellt und der entsprechende Zugriff darauf gewährt wurde, können Sie den Export über die CLOUD_RESOURCE-Verbindung ausführen. Das folgende Beispiel zeigt einen EXPORT-Befehl, der Daten über eine CLOUD_RESOURCE-Verbindung exportiert.

EXPORT DATA WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME` OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "SPANNER_TABLE_NAME" }"""
)
AS SELECT * FROM my_bq_dataset.table1;

Ersetzen Sie Folgendes:

• PROJECT_ID: Der Name Ihres Cloud de Confiance -Projekts.
• LOCATION: der Standort, an dem Sie die Verbindung erstellt haben, z. B. us.
• CONNECTION_NAME: Der Name der Verbindung, die zum Ausführen des Exports verwendet wird, z. B. myconnection.
• INSTANCE_ID: der Name Ihrer Spanner-Datenbankinstanz.
• DATABASE_ID: der Name Ihrer Spanner-Datenbank.
• SPANNER_TABLE_NAME: Der Name der vorhandenen Spanner-Zieltabelle.

Kontinuierlich exportieren

Eine Anleitung zum kontinuierlichen Verarbeiten einer Exportabfrage finden Sie unter Kontinuierliche Abfragen erstellen. Beispielcode ist ebenfalls verfügbar.

Exportoptimierung

Versuchen Sie Folgendes, um den Export von Datensätzen von BigQuery nach Spanner zu optimieren:

• Anzahl der Knoten in der Spanner-Zielinstanz erhöhen In den frühen Phasen des Exports führt eine Erhöhung der Anzahl der Knoten in der Instanz möglicherweise nicht sofort zu einer Steigerung des Exportdurchsatzes. Es kann zu einer leichten Verzögerung kommen, da Spanner eine lastbasierte Aufteilung durchführt. Bei der lastbasierten Aufteilung steigt der Exportdurchsatz an und stabilisiert sich. Mit der EXPORT DATA-Anweisung werden Daten in Batches zusammengefasst, um Schreibvorgänge in Spanner zu optimieren. Weitere Informationen finden Sie unter Leistungsübersicht.

• Geben Sie die Priorität HIGH in spanner_options an. Wenn für Ihre Spanner-Instanz Autoscaling aktiviert ist, können Sie mit der Einstellung der Priorität HIGH dafür sorgen, dass die CPU-Auslastung den erforderlichen Schwellenwert für das Auslösen der Skalierung erreicht. So kann der Autoscaler als Reaktion auf die Exportlast Rechenressourcen hinzufügen, was den Gesamtdurchsatz beim Export verbessern kann.

  Das folgende Beispiel zeigt einen Spanner-Exportbefehl mit der Priorität HIGH:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "TABLE_NAME", "priority": "HIGH" }"""
  )

• Vermeiden Sie die Sortierung der Abfrageergebnisse. Wenn die Ergebnismenge alle Primärschlüsselspalten enthält, sortiert der Exporter die Primärschlüssel der Zieltabelle automatisch, um Schreibvorgänge zu optimieren und Konflikte zu minimieren.

  Wenn der Primärschlüssel der Zieltabelle generierte Spalten enthält, fügen Sie die Ausdrücke der generierten Spalten der Abfrage hinzu, damit die exportierten Daten korrekt sortiert und in Batches aufgeteilt werden.

  Im folgenden Spanner-Schema sind SaleYear und SaleMonth beispielsweise generierte Spalten, die den Anfang des Spanner-Primärschlüssels bilden:

  CREATE TABLE Sales (
    SaleId STRING(36) NOT NULL,
    ProductId INT64 NOT NULL,
    SaleTimestamp TIMESTAMP NOT NULL,
    Amount FLOAT64,
    -- Generated columns
    SaleYear INT64 AS (EXTRACT(YEAR FROM SaleTimestamp)) STORED,
    SaleMonth INT64 AS (EXTRACT(MONTH FROM SaleTimestamp)) STORED,
  ) PRIMARY KEY (SaleYear, SaleMonth, SaleId);

  Wenn Sie Daten aus BigQuery in eine Spanner-Tabelle exportieren, in der generierte Spalten im Primärschlüssel verwendet werden, empfiehlt es sich, aber es ist nicht erforderlich, die Ausdrücke für diese generierten Spalten in Ihre EXPORT DATA-Abfrage aufzunehmen. So kann BigQuery die Daten richtig vorsortieren, was für das effiziente Batching und Schreiben in Cloud Spanner entscheidend ist. Die Werte für die generierten Spalten in der EXPORT DATA-Anweisung werden nicht in Spanner übernommen, da sie automatisch von Spanner generiert werden. Sie werden jedoch verwendet, um den Export zu optimieren.

  Im folgenden Beispiel werden Daten in eine Spanner-Sales-Tabelle exportiert, deren Primärschlüssel generierte Spalten verwendet. Zur Optimierung der Schreibvorgänge enthält die Abfrage EXTRACT-Ausdrücke, die den generierten Spalten SaleYear und SaleMonth entsprechen. So kann BigQuery die Daten vor dem Exportieren vorsortieren:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "Sales" }"""
  )
  AS SELECT
    s.SaleId,
    s.ProductId,
    s.SaleTimestamp,
    s.Amount,
    -- Add expressions that match the generated columns in the Spanner PK
    EXTRACT(YEAR FROM s.SaleTimestamp) AS SaleYear,
    EXTRACT(MONTH FROM s.SaleTimestamp) AS SaleMonth
  FROM my_dataset.sales_export AS s;

• Um lange laufende Jobs zu vermeiden, exportieren Sie Daten nach Partition. Sharden Sie Ihre BigQuery-Daten mit einem Partitionsschlüssel, z. B. einem Zeitstempel in Ihrer Abfrage:

  EXPORT DATA OPTIONS (
    uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
    format='CLOUD_SPANNER',
    spanner_options="""{ "table": "TABLE_NAME", "priority": "MEDIUM" }"""
  )
  AS SELECT *
  FROM 'mydataset.table1' d
  WHERE
  d.timestamp >= TIMESTAMP '2025-08-28T00:00:00Z' AND
  d.timestamp < TIMESTAMP '2025-08-29T00:00:00Z';

  So kann die Abfrage innerhalb der 6-stündigen Laufzeit des Jobs abgeschlossen werden. Weitere Informationen zu diesen Limits finden Sie unter Limits für Abfragejobs.

• Um die Leistung beim Laden von Daten zu verbessern, löschen Sie den Index in der Spanner-Tabelle, in die Daten importiert werden. Erstellen Sie sie dann nach Abschluss des Imports neu.

• Wir empfehlen, mit einem Spanner-Knoten (1.000 Prozessoreinheiten) und einer minimalen BigQuery-Slotreservierung zu beginnen. Beispiel: 100 Slots oder 0 Referenz-Slots mit Autoscaling. Bei Exporten unter 100 GB wird diese Konfiguration in der Regel innerhalb des 6-Stunden-Joblimits abgeschlossen. Bei Exporten mit mehr als 100 GB können Sie den Durchsatz erhöhen, indem Sie die Anzahl der Spanner-Knoten und BigQuery-Slotreservierungen nach Bedarf erhöhen. Der Durchsatz skaliert mit etwa 5 MiB/s pro Knoten.

Preise

Wenn Sie Daten mit der EXPORT DATA-Anweisung nach Spanner exportieren, werden Ihnen die Kosten gemäß den BigQuery-Kapazitätsrechenpreisen in Rechnung gestellt.

Wenn Sie Daten mit einer kontinuierlichen Abfrage kontinuierlich nach Spanner exportieren möchten, benötigen Sie eine Slot-Reservierung für die BigQuery Enterprise- oder Enterprise Plus-Version und eine Reservierungszuweisung mit dem CONTINUOUS-Jobtyp.

Für BigQuery-Exporte nach Spanner, die regionale Grenzen überschreiten, werden Datenextraktionsraten berechnet. Weitere Informationen finden Sie unter BigQuery-Preise. Um Gebühren für die Datenübertragung zu vermeiden, muss Ihr BigQuery-Export in derselben Region wie der Standard-Leader von Spanner ausgeführt werden.

Nachdem die Daten exportiert wurden, wird das Speichern der Daten in Spanner in Rechnung gestellt. Weitere Informationen finden Sie unter Spanner-Preise.