Externe Lineage¶

Workflow mit externer Lineage¶

Die Implementierung einer externen Lineage für ein Datentool besteht aus den folgenden Aufgaben:

1. Erteilen der erforderlichen Berechtigungen für den Benutzer, der sich bei dem externen Lineage-Endpunkt authentifiziert.

2. Konfigurieren Ihres Datentools, um OpenLineage-Ereignisse an den Snowflake-REST-Endpunkt zu senden.

3. Wählen Sie eine Authentifizierungsmethode aus, die für Snowflake REST APIs funktioniert, und konfigurieren Sie dann Ihr Datentool so, dass es diese zur Authentifizierung seiner Anfragen an den externen Herkunftsendpunkt verwendet.

4. Verwenden Sie Ihr Datentool wie gewohnt. OpenLineage-Ereignisse werden automatisch an Snowflake gesendet und im nativen Lineage-Diagramm in der Snowsight angezeigt.

Wenn Sie den Endpunkt der externen Herkunft testen möchten, bevor Sie ein Datentool für die Ausgabe von OpenLineage-Ereignissen konfigurieren, lesen Sie Senden von manuellen Anfragen, um die Herkunft festzustellen.

Anzeigen der Datenherkunft¶

Um die Datenherkunft in der Snowsight anzuzeigen, führen Sie die folgenden Schritte aus:

1. Melden Sie sich bei Snowsight mit den erforderlichen Berechtigungen an.

2. Wählen Sie im Navigationsmenü Catalog » Database Explorer und dann ein unterstütztes Objekt aus, wie z. B. eine Tabelle oder Ansicht.

3. Wählen Sie die Registerkarte Lineage aus.

Wenn ein Datentool Herkunftsinformationen an Snowflake sendet, werden externe Objekte im Lineage-Diagramm der Snowsight angezeigt und als externe Knoten gekennzeichnet. Beispiel:

Sie können ein externes Objekt oder die Linie auswählen, die die Objekte verbindet, um zusätzliche Informationen zu erhalten, genau wie bei der nativen Lineage.

Snowflake-Berechtigungen erteilen¶

Nachdem eine REST-Anforderung authentifiziert wurde, prüfen Sie, ob der mit der Anfrage verbundene Benutzer berechtigt ist, die externe Lineage zu verwenden. Der mit der Anfrage verbundene Benutzer muss eine Rolle haben, der die Berechtigung INGEST LINEAGE für das Konto zugewiesen ist.

Angenommen, Sie möchten Anfragen vom Dienstbenutzer dbt_integration_user senden, die in der Snowsight Lineage angezeigt werden sollen. Führen Sie als Administrator die folgenden Befehle aus, um eine dedizierte Rolle zu erstellen, dieser Rolle die erforderlichen Berechtigungen zu erteilen und dann dem Benutzer die Rolle zuzuweisen:

CREATE ROLE dbt_lineage_role;
GRANT INGEST LINEAGE ON ACCOUNT TO ROLE dbt_lineage_role;
GRANT ROLE dbt_lineage_role TO USER dbt_integration_user;

Datentool konfigurieren¶

Die folgenden Abschnitte enthalten grundlegende Anweisungen zur Verwendung der externen Lineage- mit dbt und Apache AirFlow.

• Konfigurieren von dbt, um Lineage-Daten an Snowflake zu senden

• Konfigurieren von Airflow, um Lineage-Daten an Snowflake zu senden

Auswählen einer Authentifizierungsmethode¶

Snowflake bietet mehrere Möglichkeiten, Anforderungen an einen Snowflake-REST-Endpunkt zu authentifizieren, wie er von der externen Lineage verwendet wird. Eine vollständige Liste der Authentifizierungsmethoden finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.

Nachdem Sie Ihre bevorzugte Authentifizierungsmethode ausgewählt haben, müssen Sie ein Sicherheitstoken für einen bestimmten Benutzer erzeugen. Das Token wird verwendet, um einen Benutzer mit der REST-Anforderung zu verknüpfen, sodass Snowflake den Benutzer authentifizieren und überprüfen kann, ob der Benutzer autorisiert ist, externe Lineage zu verwenden.

Nachdem Sie einem Benutzer in Snowflake erfolgreich ein Sicherheitstoken zugeordnet haben, müssen Sie Ihr Datentool so konfigurieren, dass es seine Anforderungen mit diesem Token authentifiziert. Wenn Sie z. B. eine YAML-Konfigurationsdatei verwenden, um OpenLineage-Transportvariablen festzulegen, verwenden Sie den folgenden Code, um das Sicherheitstoken anzugeben, das im Header der Anforderung gesendet wird:

transport:
   auth:
      type: api_key
      apiKey: eyJ0eXAiOiJKV1QiLsecuritytoken...

Weitere Methoden zum Angeben eines Sicherheitstokens finden Sie in der OpenLineage-Dokumentation zu Ihrem Datentool.

Senden von manuellen Anfragen, um die Herkunft festzustellen¶

Die externe Herkunft (Lineage) funktioniert durch Akzeptieren von JSON-Nutzlasten, die der OpenLineage-Spezifikation für COMPLETE-Ereignisse entsprechen. Bei der Integration in ein Datentool gibt das Tool diese COMPLETE-Ereignisse aus. Sie können aber auch ein COMPLETE-Ereignis konstruieren und es dann mit einem beliebigen Tool oder einer Sprache senden, die POST-Anforderungen an einen Endpunkt senden kann.

Eine gültige Anforderung besteht aus der folgenden Methode: Basis-URL und Endpunkt:

POST https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Dabei ist account_identifier der Kontobezeichner Ihres Snowflake-Kontos.

Das folgende Beispiel zeigt, wie Sie curl verwenden, um Herkunftsinformationen an die externe Lineage zu senden:

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLsecuritytoken..." \
 -H "Accept: application/json" \
 -H "User-Agent: myApplicationName/1.0" \
 -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
 -d "@request_body.json" \
 "https://MYORG-DEV_ACCOUNT.snowflakecomputing.com/api/v2/lineage/external-lineage"

Dabei entspricht request_body.json der OpenLineage-Spezifikation für COMPLETE-Ereignisse. Weitere Informationen zur JSON-Nutzlast finden Sie unter Nutzdatenanforderungen.

{
   "eventType": "COMPLETE",
   "eventTime": "2025-03-12T06:51:12.000Z",
   "job": {"namespace": "exampleNamespace", "name": "exampleJob"},
   "run": {"runId": "123e4567-e89b-12d3-a456-426614174000"},
   "producer": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
   "schemaURL": "https://openlineage.io/spec/0-0-1/OpenLineage.json",
   "inputs": [{"namespace": "snowflake://AXORG-AX_TEST_PP8", "name": "OL_TEST.OL_TEST_SCH.TEST_DEMO"}],
   "outputs": [{"namespace": "postgres://localhost:5432", "name": "PDB.SCH.OUTPUT"}]
}

"outputs": [
    {
        "namespace": "postgres://db.company.com:5432",
        "name": "db.schema.view",
        "facets": {"datasetType": {"datasetType": "VIEW"}},
    },
],

Senden von Anforderungen zum Entfernen der Lineage¶

Sie können eine DELETE-Anforderung an den externen Lineage-Endpunkt senden, um die Herkunft zu entfernen, die zwischen einem Snowflake-Objekt und einem externen Objekt hergestellt wurde.

• Um die Lineage zwischen dem Quellobjekt und dem Zielobjekt zu unterbrechen, verwenden Sie URL-Abfrageparameter, um Details zu den beiden Objekten anzugeben.

• Um die Lineage zwischen einem Objekt und allen seinen nachgelagerten Objekten zu unterbrechen, geben Sie das Quellobjekt ohne Angabe eines Zielobjekts an.

• Um ein Zielobjekt aus dem Lineage-Diagramm zu entfernen, unabhängig davon, wie viele Objekte sich vorgelagert befinden, geben Sie das Zielobjekt ohne Angabe eines Quellobjekts an.

Eine gültige Anfrage zum Entfernen der Lineage besteht aus der folgenden Methode: Basis-URL und Endpunkt:

DELETE https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Einschränkungen und Hinweise¶

• Ein Snowflake-Objekt muss entweder INPUT oder OUTPUT eines COMPLETE-Ereignisses sein. Das heißt, die externe Lineage erfasst keine Herkunftsereignisse, wenn weder die Eingabedaten noch die Ausgabedaten ein Snowflake-Objekt sind.

• Snowflake unterstützt nicht OpenLineage Version 2.

• Die Aufbewahrungsfrist für externe Lineage-Ereignisse beträgt ein Jahr.

• Snowflake erkennt nur COMPLETE Lineage-Ereignisse. Alle anderen Ereignisse, die von einem Datentool ausgegeben werden, werden ignoriert.

• Die Lineage aus externen Quellen erscheint nicht in der Ausgabe der GET_LINEAGE-Funktion.

• Die externe Lineage unterstützt nicht die Lineage von Spalten.

• Der vollqualifizierte Name eines Datensets – d. h. die Eingabe oder Ausgabe – darf 1.000 Zeichen nicht überschreiten.

• Sie können nicht mehr als 10.000 Ereignisse in demselben Konto speichern. Wenn Sie dieses Limit erreichen, müssen Sie erst Ereignisse löschen, bevor Sie neue hinzufügen.