Daten im CSV-Format importieren und exportieren

Auf dieser Seite wird beschrieben, wie Sie Daten aus Spanner in CSV-Dateien exportieren oder Daten aus CSV-Dateien in eine Spanner-Datenbank importieren.

Der Vorgang verwendet Dataflow. Sie können Daten aus Spanner in einen Cloud Storage-Bucket exportieren oder aus einem Cloud Storage-Bucket, der eine JSON-Manifestdatei und eine Reihe von CSV-Dateien enthält, in Spanner importieren.

Hinweise

Zum Importieren oder Exportieren einer Spanner-Datenbank müssen Sie zuerst die Spanner, Cloud Storage, Compute Engine und Dataflow APIs aktivieren:

Aktivieren Sie die APIs

Außerdem brauchen Sie ein ausreichend großes Kontingent und die erforderlichen IAM-Berechtigungen.

Kontingentanforderungen

Für Import- oder Exportjobs gelten folgende Kontingentanforderungen:

  • Spanner: Sie müssen genügend Computing-Kapazität haben, um die zu importierende Datenmenge zu unterstützen. Für den Import oder Export einer Datenbank ist keine zusätzliche Rechenkapazität erforderlich. Allerdings benötigen Sie möglicherweise weitere Rechenkapazität, damit der Job in angemessener Zeit abgeschlossen werden kann. Weitere Informationen finden Sie unter Jobs optimieren.
  • Cloud Storage: Zum Importieren benötigen Sie einen Bucket mit Ihren zuvor exportierten Dateien. Zum Exportieren müssen Sie einen Bucket für die exportierten Dateien erstellen, sofern noch keiner vorhanden ist. Das ist in der Google Cloud Console möglich – entweder über die Cloud Storage-Seite oder beim Erstellen des Exports auf der Spanner-Seite. Für den Bucket muss keine Größe festgelegt werden.
  • Dataflow: Für Importjobs gelten die gleichen Compute Engine-Kontingente für CPU, Laufwerksnutzung und IP-Adressen wie für andere Dataflow-Jobs.
  • Compute Engine: Bevor Sie den Import- oder Exportjob ausführen, müssen Sie Kontingente für Compute Engine einrichten, die von Dataflow verwendet werden. Diese Kontingente stellen die maximale Anzahl an Ressourcen dar, die Dataflow für Ihren Job verwenden darf. Empfohlene Anfangswerte sind:

    • CPUs: 200
    • Verwendete IP-Adressen: 200
    • Nichtflüchtiger Standardspeicher: 50 TB

    Sie müssen in der Regel keine weiteren Anpassungen vornehmen. Dataflow bietet Autoscaling, sodass Sie nur für die Ressourcen zahlen, die beim Import oder Export tatsächlich verwendet werden. Wenn Ihr Job mehr Ressourcen verwenden kann, ist in der Dataflow-UI ein Warnsymbol zu sehen. Der Job sollte trotz dieses Warnsymbols beendet werden.

IAM-Anforderungen

Für das Importieren oder Exportieren einer Datenbank benötigen Sie außerdem IAM-Rollen mit ausreichenden Berechtigungen, um alle Dienste nutzen zu können, die für einen Import- oder Exportjob erforderlich sind. Informationen zum Gewähren von Rollen und Berechtigungen finden Sie unter IAM-Rollen anwenden.

Zum Importieren oder Exportieren einer Datenbank benötigen Sie die folgenden Rollen:

Spanner-Daten in CSV-Dateien exportieren

Wenn Sie Daten aus Spanner in CSV-Dateien in Cloud Storage exportieren möchten, folgen Sie der Anleitung zum Ausführen eines Jobs über die Google Cloud CLI mit der Vorlage „Spanner zu Cloud Storage Text“.

Weitere Informationen finden Sie in diesem Dokument auch zum Ansehen oder Fehlerbeheben von Jobs, zum Optimieren langsamer Jobs und zu Faktoren, die die Jobleistung beeinflussen.

Daten aus CSV-Dateien in Spanner importieren

Der Vorgang zum Importieren von Daten aus CSV-Dateien umfasst die folgenden Schritte:

  1. Exportieren Sie Ihre Daten in CSV-Dateien und speichern Sie diese Dateien in Cloud Storage. Fügen Sie keine Headerzeile ein.
  2. Erstellen Sie eine JSON-Manifestdatei und speichern Sie die Datei zusammen mit Ihren CSV-Dateien.
  3. Erstellen Sie leere Zieltabellen in Ihrer Spanner-Datenbank oder achten Sie darauf, dass die Datentypen für Spalten in den CSV-Dateien mit den entsprechenden Spalten in den vorhandenen Tabellen übereinstimmen.
  4. Führen Sie den Importjob aus.

Schritt 1: Daten aus einer Nicht-Spanner-Datenbank in CSV-Dateien exportieren

Beim Importieren werden Daten aus CSV-Dateien, die sich in einem Cloud Storage-Bucket befinden, geholt. Sie können Daten aus jeder Quelle im CSV-Format exportieren.

Beachten Sie beim Exportieren Ihrer Daten folgende Punkte:

  • Zu importierende Textdateien müssen im CSV-Format vorliegen.
  • Die Daten müssen einem der folgenden Typen entsprechen:

GoogleSQL

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea
  • Beim Exportieren der CSV-Dateien müssen Sie Metadaten weder hinzufügen noch generieren.

  • Für Ihre Dateien müssen keine bestimmten Namenskonventionen eingehalten werden.

Wenn Sie Ihre Dateien nicht direkt nach Cloud Storage exportieren, müssen Sie die CSV-Dateien in einen Cloud Storage-Bucket hochladen.

Schritt 2: JSON-Manifestdatei erstellen

Außerdem müssen Sie eine Manifestdatei mit einer JSON-Beschreibung der zu importierenden Dateien erstellen und in demselben Cloud Storage-Bucket speichern, in dem Sie Ihre CSV-Dateien gespeichert haben. Diese Manifestdatei enthält ein tables-Array, in dem Name und Speicherort der Datendatei für jede Tabelle aufgeführt sind. Die Datei gibt auch den Dialekt der empfangenden Datenbank an. Wenn der Dialekt weggelassen wird, wird standardmäßig GoogleSQL verwendet.

Das Format der Manifestdatei entspricht dem folgenden Nachrichtentyp, der hier im Protokollpufferformat dargestellt wird:

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

Das folgende Beispiel zeigt eine Manifestdatei zum Importieren von Tabellen mit den Namen Albums und Singers in eine Datenbank mit GoogleSQL-Dialekt. Die Tabelle Albums verwendet das Spaltenschema, das der Job aus der Datenbank abruft. Die Tabelle Singers verwendet das Schema, das in der Manifestdatei angegeben ist:

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

Schritt 3: Tabelle für die Spanner-Datenbank erstellen

Bevor Sie den Import ausführen, müssen Sie die Zieltabellen in der Spanner-Datenbank erstellen. Wenn die Spanner-Zieltabelle bereits ein Schema hat, müssen alle in der Manifestdatei angegebenen Spalten dieselben Datentypen haben wie die entsprechenden Spalten im Schema der Zieltabelle.

Wir empfehlen, sekundäre Indexe, Fremdschlüssel und Änderungsstreams nach dem Import der Daten in Spanner und nicht beim ersten Erstellen der Tabelle zu erstellen. Wenn Ihre Tabelle diese Strukturen bereits enthält, sollten Sie sie löschen und nach dem Import der Daten neu erstellen.

Schritt 4: Dataflow-Importjob mit gcloud ausführen

Folgen Sie der Anleitung zum Ausführen eines Importjobs über die Google Cloud CLI mit der Vorlage „Cloud Storage Text für Spanner“, um den Importjob zu starten.

Nachdem Sie einen Importjob gestartet haben, können Sie in der Google Cloud Console Details zum Job aufrufen.

Fügen Sie nach Abschluss des Importjobs alle erforderlichen sekundären Indexe, Fremdschlüssel und Änderungsstreams hinzu.

Region für den Importjob auswählen

Sie können je nach Standort Ihres Cloud Storage-Bucket eine andere Region auswählen. Wählen Sie eine Region aus, die dem Standort Ihres Cloud Storage-Bucket entspricht, um Gebühren für ausgehenden Datenverkehr zu vermeiden.

  • Wenn der Standort Ihres Cloud Storage-Bucket eine Region ist, können Sie von der kostenlosen Netzwerknutzung profitieren. Dazu wählen Sie dieselbe Region auch für den Importjob aus, vorausgesetzt, diese Region ist verfügbar.

  • Wenn der Speicherort Ihres Cloud Storage-Bucket zwei Regionen ist, können Sie von der kostenlosen Netzwerknutzung profitieren. Dazu wählen Sie eine der beiden Regionen aus, aus denen die Dual-Region für Ihren Importjob besteht, vorausgesetzt, eine der Regionen ist verfügbar.

  • Wenn für Ihren Importjob keine Region mit demselben Standort verfügbar ist oder wenn der Standort Ihres Cloud Storage-Bucket multiregional ist, fallen Gebühren für die ausgehende Datenübertragung an. Wählen Sie anhand der Preise für die Datenübertragung von Cloud Storage eine Region aus, in der die niedrigsten Gebühren für die Datenübertragung anfallen.

Jobs in der Dataflow-UI ansehen oder Fehler beheben

Nachdem Sie einen Import- oder Exportjob gestartet haben, können Sie in der Google Cloud Console im Abschnitt „Dataflow“ Details zum Job, einschließlich Logs, ansehen.

Dataflow-Jobdetails ansehen

So rufen Sie Details zu allen Import-/Exportjobs auf, die Sie in der letzten Woche ausgeführt haben, einschließlich aller derzeit ausgeführten Jobs:

  1. Wechseln Sie zur Seite Datenbanküberblick für die Datenbank.
  2. Klicken Sie im linken Bereich auf den Menüpunkt Import/Export. Auf der Datenbankseite Import/Export wird eine Liste der letzten Jobs angezeigt.
  3. Klicken Sie auf der Seite Import/Export der Datenbank in der Spalte Dataflow-Jobname auf den Jobnamen:

    Statusmeldung für laufende Jobs

    In der Google Cloud Console werden Details zum Dataflow-Job angezeigt.

So rufen Sie einen Job auf, den Sie vor mehr als einer Woche ausgeführt haben:

  1. Rufen Sie in der Google Cloud Console die Seite „Dataflow-Jobs“ auf.

    Zur Jobseite

  2. Suchen Sie den Job in der Liste und klicken Sie auf seinen Namen.

    In der Google Cloud Console werden Details zum Dataflow-Job angezeigt.

Dataflow-Logs für den Job ansehen

Rufen Sie wie oben beschrieben die Detailseite des Jobs auf und klicken Sie rechts neben dem Jobnamen auf Logs, um die Logs eines Dataflow-Jobs anzusehen.

Wenn ein Job fehlschlägt, suchen Sie in den Logs nach Fehlern. Falls Fehler aufgetreten sind, ist neben Logs die Fehleranzahl zu sehen:

Beispiel für Fehleranzahl neben der Schaltfläche "Logs"

So sehen Sie sich Jobfehler genauer an:

  1. Klicken Sie auf die Fehleranzahl neben Logs.

    In der Google Cloud Console werden die Logs des Jobs angezeigt. Unter Umständen müssen Sie scrollen, um die Fehler einzublenden.

  2. Suchen Sie nach Einträgen mit dem Fehlersymbol Fehlersymbol.

  3. Klicken Sie auf einen Logeintrag, um ihn zu maximieren.

Weitere Informationen zur Fehlerbehebung bei Dataflow-Jobs finden Sie unter Pipelinefehler beheben.

Fehlgeschlagene Import- oder Exportjobs beheben

Wenn in Ihren Joblogs die folgenden Fehler angezeigt werden:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Prüfen Sie in der Google Cloud Console auf dem Tab Monitoring der Spanner-Datenbank die Lese-/Schreiblatenz von 99%. Wenn hohe (mehrere Sekunde-)Werte angezeigt werden, bedeutet dies, dass die Instanz überlastet ist und Lese-/Schreibvorgänge ein Zeitlimit verursachen und fehlschlagen.

Eine Ursache für die hohe Latenz ist, dass der Dataflow-Job mit zu vielen Workern ausgeführt wird und die Spanner-Instanz zu stark belastet.

So geben Sie ein Limit für die Anzahl der Dataflow-Worker an:
  • Wenn Sie die Dataflow Console verwenden, befindet sich der Parameter Max. Worker im Abschnitt Optionale Parameter auf der Seite Job aus Vorlage erstellen.

  • Wenn Sie gcloud verwenden, geben Sie das Argument max-workers an. Beispiel:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Text_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
    

Langsam laufende Import- oder Exportjobs optimieren

Wenn Sie die Vorschläge für die Anfangseinstellungen befolgt haben, sollten in der Regel keine weiteren Anpassungen nötig sein. Falls der Job jedoch langsam ausgeführt wird, können Sie einige andere Optimierungen versuchen:

  • Job- und Datenspeicherort optimieren: Führen Sie den Dataflow-Job in derselben Region aus, in der sich die Spanner-Instanz und der Cloud Storage-Bucket befinden.

  • Ausreichende Dataflow-Ressourcen prüfen: Wenn die entsprechenden Compute Engine-Kontingente die Ressourcen Ihres Dataflow-Jobs einschränken, werden auf der Dataflow-Seite des Jobs in der Google Cloud Console ein Warnsymbol Warnungssymbol und Logeinträge angezeigt:

    Screenshot der Kontingentlimitwarnung

    In diesem Fall kann das Erhöhen der Kontingente für CPUs, verwendete IP-Adressen und nichtflüchtigen Standardspeicher die Ausführungszeit des Jobs verkürzen, aber auch höhere Compute Engine-Gebühren zur Folge haben.

  • Spanner-CPU-Auslastung prüfen: Wenn die CPU-Auslastung für die Instanz über 65 % liegt, können Sie die Rechenkapazität in dieser Instanz erhöhen. Durch die Kapazität werden zusätzliche Spanner-Ressourcen hinzugefügt und der Job sollte beschleunigt werden, es entstehen aber höhere Kosten für Spanner.

Faktoren, die sich auf die Leistung von Import- oder Exportjobs auswirken

Die Zeit für einen Import- oder Exportjob wird von mehreren Faktoren beeinflusst.

  • Größe der Spanner-Datenbank: Die Verarbeitung von mehr Daten erfordert mehr Zeit und Ressourcen.

  • Spanner-Datenbankschema, einschließlich:

    • Die Anzahl der Tabellen
    • Die Größe der Zeilen
    • Anzahl der sekundären Indexe
    • Anzahl der Fremdschlüssel
    • Die Anzahl der Änderungsstreams

  • Datenspeicherort: Daten werden mit Dataflow zwischen Spanner und Cloud Storage übertragen. Idealerweise befinden sich alle drei Komponenten in derselben Region. Wenn das nicht der Fall ist, dauert das regionsübergreifende Verschieben der Daten länger.

  • Anzahl der Dataflow-Worker: Optimale Dataflow-Worker sind für eine gute Leistung erforderlich. Mithilfe von Autoscaling wählt Dataflow die Anzahl der Worker für einen Job abhängig vom Arbeitsumfang aus. Diese Anzahl wird jedoch durch die Kontingente für CPUs, verwendete IP-Adressen und nichtflüchtigen Standardspeicher begrenzt. In der Dataflow-UI ist ein Warnsymbol zu sehen, wenn Kontingentobergrenzen erreicht werden. In diesem Fall dauert die Verarbeitung länger, aber der Job sollte dennoch abgeschlossen werden. Das Autoscaling kann Spanner überlasten, was zu Fehlern führen kann, wenn große Datenmengen importiert werden müssen.

  • Bestehende Auslastung von Spanner: Ein Importjob stellt eine erhebliche CPU-Last für eine Spanner-Instanz dar. Ein Exportjob stellt in der Regel eine geringe Last für eine Spanner-Instanz dar. Wenn die Instanz jedoch bereits eine erhebliche bestehende Auslastung aufweist, wird der Job langsamer ausgeführt.

  • Menge der Spanner-Rechenkapazität: Wenn die CPU-Auslastung für die Instanz über 65 % liegt, wird der Job langsamer ausgeführt.

Worker für gute Importleistung abstimmen

Beim Starten eines Spanner-Importjobs müssen Dataflow-Worker auf einen optimalen Wert für eine gute Leistung festgelegt werden. Zu viele Worker überlasten Spanner und zu wenige Worker führen zu einer überfordernden Importleistung.

Die maximale Anzahl von Workern hängt stark von der Datengröße ab. Idealerweise sollte die gesamte Spanner-CPU-Auslastung zwischen 70% und 90 % liegen. Dies sorgt für ein ausgewogenes Verhältnis zwischen Spanner-Effizienz und fehlerfreiem Jobabschluss.

Um dieses Nutzungsziel in den meisten Schemas und Szenarien zu erreichen, empfehlen wir eine maximale Anzahl von Worker-vCPUs, die zwischen dem 4- und 6-Fachen der Anzahl von Spanner-Knoten liegt.

Für eine Spanner-Instanz mit 10 Knoten und n1-standard-2-Workern würden Sie beispielsweise die maximale Anzahl der Worker auf 25 festlegen, sodass 50 vCPUs entstehen.