Validierung und Fehlerbehandlung

Unter diesem Thema wird beschrieben, wie Snowflake Connector for Kafka Daten validiert und Fehler während der Aufnahme behandelt.

Validierungsmodi

Der Konnektor unterstützt zwei Validierungsmodi, die durch die snowflake.validation-Konfigurationseigenschaft gesteuert werden.

Serverseitige Validierung (Standard)

snowflake.validation=server_side

Bei der serverseitigen Validierung werden die Daten ohne clientseitige Typprüfung an Snowflake gesendet. Das Snowflake-Backend führt die Validierung und Schema-Evolution durch, entsprechend dem Verhalten von COPY und Snowpipe.

  • Ungültige Datensätze werden in der Snowflake-Fehlertabelle erfasst, die der Zieltabelle zugeordnet ist.

  • Das DLQ wird in diesem Modus nicht für Datenaufnahmevalidierungsfehler verwendet. Verwenden Sie stattdessen Fehlertabellen. Datensätze, die von den Kafka-Konvertern nicht deserialisiert werden können (bevor sie Snowflake erreichen), werden jedoch weiterhin an DLQ weitergeleitet, sofern konfiguriert.

  • Liefert maximalen Durchsatz, indem die Validierung vom Konnektor ausgelagert wird.

  • Unterstützt sowohl den Standard-Pipe- als auch den benutzerdefinierten Pipe-Modus.

Bei Verwendung der serverseitigen Validierung:

  • Sie möchten einen maximalen Durchsatz.

  • Sie können Fehlertabellen in Snowflake verwalten.

  • Sie verwenden benutzerdefinierte Pipes für Transformationen während der Übertragung.

Clientseitige Validierung

snowflake.validation=client_side

Mit der clientseitigen Validierung validiert der Konnektor Datentypen und Schemakompatibilität, bevor Zeilen an Snowflake gesendet werden.

  • Ungültige Datensätze werden gemäß der errors.tolerance-Einstellung (siehe unten) behandelt.

  • Schemaentwicklung DDL wird vom Konnektor ausgeführt, wenn neue Felder erkannt werden.

  • Unterstützt Warteschlange für nicht zustellbare Meldungen (DLQ) für das Routing ungültiger Datensätze.

  • Funktioniert nur mit der Standard-Pipe ({tableName}-STREAMING). Wenn eine benutzerdefinierte Pipe vorhanden ist und die clientseitige Validierung aktiviert ist, schlägt der Konnektor mit ERROR_5030 fehl.

Bei Verwendung der clientseitigen Validierung:

  • Sie benötigen eine Dead Client Queue für die Fehlerbehandlung.

  • Sie migrieren von v3 und möchten ein vertrautes Verhalten.

  • Sie benötigen den Konnektor, um die Validierung zu steuern.

Fehlerbehandlung

Fehlertoleranz

Die errors.tolerance-Eigenschaft steuert, wie der Konnektor auf Fehler reagiert:

errors.tolerance=none (Standard)

Die Konnektor-Aufgabe schlägt beim ersten Fehler fehl. Wenn DLQ konfiguriert ist, wird der fehlerhafte Datensatz trotzdem an DLQ gesendet wird, bevor die Aufgabe abgebrochen wird.

errors.tolerance=all

Der Konnektor nimmt weiterhin Daten auf. Ungültige Datensätze werden an DLQ weitergeleitet (sofern konfiguriert) oder still verworfen.

Warnung

Das Festlegen von errors.tolerance=all ohne Konfiguration eines DLQ-Topics führt dazu, dass ungültige Datensätze still verworfen werden. Dies ist eine unsichere Konfiguration, die zu Datenverlusten führen kann.

Dead Letter Queue (DLQ)

Konfigurieren von DLQ:

errors.deadletterqueue.topic.name=my_topic_dlq
errors.log.enable=true

Die folgenden Datensätze werden an DLQ weitergeleitet (falls konfiguriert):

  • Konverterfehler (beide Validierungsmodi): Datensätze, die von den Kafka-Konvertern nicht deserialisiert werden können, werden unabhängig vom Validierungsmodus an DLQ gesendet. Dies gilt sowohl für errors.tolerance=none (Datensatz wird an DLQ weitergeleitet, dann schlägt der Task fehl) als auch für errors.tolerance=all (Datensatz wird an DLQ weitergeleitet, Task wird fortgesetzt).

  • Clientseitige Validierungsfehler: Datensätze, die die clientseitige Datenkonvertierung oder die Schemavalidierung nicht bestehen, werden an DLQ gesendet, wenn``snowflake.validation=client_side``.

Datensätze, die bei der serverseitigen Snowflake-Erfassung fehlschlagen, werden nicht an DLQ weitergeleitet. Verwenden Sie stattdessen Fehlertabellen.

Bemerkung

Der Konnektor bietet höchstens einmal eine Bereitstellung für Datensätze, die bei der Validierung von Fehlern auftreten. Das bedeutet, dass ein Datensatz möglicherweise unter bestimmten Fehlerbedingungen DLQ nicht erreicht.

Fehlertabellen (serverseitige Validierung)

Bei Verwendung von snowflake.validation=server_side werden Datensätze, bei denen die serverseitige Erfassung fehlschlägt (Typkonflikte, Constraint-Verletzungen), zur Überprüfung und Wiederholung in der Fehlertabelle protokolliert.

Bemerkung

Bei Tabellen, die vom Konnektor automatisch erstellt werden, sind Fehlertabellen standardmäßig aktiviert.

Weitere Informationen zu Fehlertabellen und zur Fehlerbehandlung mit Snowpipe Streaming finden Sie unter:doc:/user-guide/snowpipe-streaming/snowpipe-streaming-high-performance-error-handling.

Überprüfung des Kanalstatus (serverseitige Validierung)

Bei Verwendung der serverseitigen Validierung prüft der Konnektor den Status des Snowpipe Streaming-Kanals, bevor er Kafka-Offsets überträgt. Wenn der Kanal einen ansteigenden rows_error_count meldet:

  • Mit errors.tolerance=none: Der Konnektor löst einen schwerwiegenden Fehler aus (ERROR_5030) und die Aufgabe schlägt fehl.

  • Mit errors.tolerance=all: Der Konnektor fährt fort und protokolliert die Fehlerzahl. Datensätze nach der ungültigen Zeile können weiterhin erfasst werden. Wenn Fehlertabellen aktiviert sind, werden die ungültigen Datensätze dort gespeichert.

Mit der clientseitigen Validierung erkennt der Konnektor ungültige Datensätze, bevor er sie an Snowflake sendet. Ungültige Datensätze führen entweder zu einem sofortigen Aufgabenfehler (errors.tolerance=none) oder werden an DLQ (errors.tolerance=all) weitergeleitet.

Um fehlerhafte Datensätze bei der serverseitigen Validierung zu untersuchen, überprüfen Sie den Channel-Verlauf und verwenden Sie die in Metadaten-Offsets zum Erkennen und Wiederherstellen von Fehlern verwenden beschriebene Lückensuchtechnik. Die für die Verwendung dieser Technik benötigten Informationen zum Kafka-Offset sind in der Spalte RECORD_METADATA verfügbar.