Aktivieren Sie den externen Datenzugriff für Streamingtabellen und materialisierte Ansichten.

Wenn Sie den externen Datenzugriff auf den Unity-Katalog aktiviert haben, können Sie externe Datenzugriffe zu pipeline-verwalteten und eigenständigen materialisierten Ansichten und Streaming-Tabellen hinzufügen. Dadurch können externe Delta- und Iceberg-Clients über die Unity-Katalog- und Iceberg-Katalog-REST-APIs auf Ihre Datasets zugreifen, ohne dass eine vollständige Datenkopie erforderlich ist.

Der externe Datenzugriff funktioniert für Datensätze, die von Lakeflow-Pipelines verwaltet werden, sowie für eigenständige materialisierte Ansichten und Streaming-Tabellen.

Fähigkeiten

Durch externe Datenzugriffe werden dieselben Daten bereitgestellt, die in Azure Databricks für pipeline-verwaltete und eigenständige materialisierte Ansichten und Streaming-Tabellen verfügbar sind, ohne eine Duplikatur der Daten zu erstellen. Dies bietet die folgenden Merkmale für Leistung und Funktionalität:

  • Es ist keine Datenkopie erforderlich: Externer Zugriff ist aktiviert, ohne das vollständige Dataset zu duplizieren.
  • Externer Zugriff über APIs: Lesen Sie materialisierte Ansichten und Streamingtabellen mithilfe von Delta Lake- oder Iceberg-APIs.
  • Read-after-write-Konsistenz: Externe Leser können nach einer Aktualisierung des Datensatzes auf aktuelle Daten zugreifen, wodurch sichergestellt wird, dass keine veralteten Daten vorliegen. Updates sind sofort nach der Aktualisierung verfügbar.
  • Einzelnes Tabellenobjekt: Datasets werden extern als verwaltete Tabellen mit demselben Namen wie das Quelldatenset in Unity-Katalog-APIs angezeigt.
  • Niedrige Kosten: Da das vollständige Dataset nicht kopiert wird, ist der Aufwand für die Bereitstellung externer Zugriffe gering.

Requirements

Die Anforderungen für Ihre Datasets sind:

  • Unity-Katalog: Ihre Streamingtabellen und materialisierten Ansichten müssen Unity-Katalog verwenden.
  • Databricks Runtime-Version: Sie müssen Databricks Runtime 17.3 und höher verwenden.
  • Standard-Veröffentlichungsmodus: Externe Lesbarkeit wird nur im Standard-Veröffentlichungsmodus unterstützt. Um externe Lesbarkeit zu nutzen, übergehe in den Standard-Veröffentlichungsmodus. Funktionen, die von externen Metadaten abhängen, wie etwa der materialisierten Ansicht (CDF), funktionieren im Legacy-Publishing-Modus.

Die Anforderungen für Ihre Clients sind:

  • Delta-API-Version: Der Client muss Delta Lake-APIs 4.0.0 oder höher unterstützen, einschließlich Löschvektoren, und muss die Unity-Katalogkatalog-APIs für den Zugriff verwenden.
  • Iceberg-API-Version: Alternativ kann der Client mithilfe von Iceberg-Katalog-APIs zugreifen, die die Iceberg v3-Spezifikation unterstützen.
  • Unity-Katalogberechtigungen: Der Prinzipal, der extern auf die Datensätze zugreift, muss über die EXTERNAL-USE SCHEMABerechtigung für das Schema und über die SELECT Berechtigung für die Tabelle verfügen.

Note

Wenn Ihr Client diese Anforderungen nicht unterstützt, können Sie auch den Kompatibilitätsmodus verwenden, der alle Delta- und Iceberg-Clients unterstützt, aber eine vollständige Kopie des Datasets erstellt.

So aktivieren Sie den Zugriff für ein Dataset

Es gibt zwei Schritte, um den externen Zugriff auf einen Datensatz zu ermöglichen.

  1. Externe Metadaten entweder über die Pipeline-Konfiguration oder eine Tabelleneigenschaft aktivieren. Die Einstellung auf Tabellenebene hat Vorrang vor der Pipeline-Konfiguration, wenn beide festgelegt sind, und wird sowohl für pipelineverwaltete als auch für eigenständige Streaming-Tabellen und materialisierte Ansichten unterstützt.

    • Pipeline-Konfiguration: Setzen pipelines.externalMetadata.enabled Sie auf true um externe Metadaten für alle Datensätze in der Pipeline zu aktivieren. Eigenständige materialisierte Views und Streaming-Tabellen, die mit Databricks SQL erstellt wurden, haben keine Pipeline-Konfiguration; Verwenden Sie stattdessen eine Tabelleneigenschaft.

      Benutzeroberfläche für Pipelineeinstellungen

      In den Pipeline-Einstellungen führen Sie die folgenden Schritte durch:

      1. Öffnen Sie Ihre Pipeline, und klicken Sie auf "Einstellungen".
      2. Fügen Sie unter "Konfiguration" ein Schlüssel-Wert-Paar hinzu: Schlüsselpipelines.externalMetadata.enabled, Werttrue.
      3. Klicke auf Speichern.

      Pipeline-Konfiguration JSON

      Fügen Sie im configuration Abschnitt Ihrer Pipeline-JSON Folgendes hinzu:

      {
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

    • Tabelleneigenschaft: Füge die folgende Eigenschaft zur Streaming-Tabelle oder der materialisierten Ansichtsdefinition hinzu. Informationen zu Lakeflow Connect Pipelines finden Sie unter Delta-Tabelleneigenschaften festlegen.

      CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')

    Führen Sie nach dem Speichern der Konfiguration die Pipeline aus, oder starten Sie sie neu, um die Änderungen anzuwenden:

    • Ausgelöste Pipelines: Die Pipeline einmal ausführen.
    • Kontinuierliche Pipelines: Beenden Sie die Pipeline und starten Sie sie neu.

    Verwenden Sie für eigenständige Databricks-SQL-Objekte CREATE OR REPLACE MATERIALIZED VIEW oder CREATE OR REFRESH STREAMING TABLE mit der Tabelleneigenschaft. Die Anweisung zum Erstellen oder Aktualisieren wendet die Eigenschaft an.

  2. Wenn Sie planen, den Datensatz mit einem modernen Iceberg-Client zu lesen, fügen Sie zusätzlich zur externen Metadaten-Eigenschaft die folgenden UniForm Iceberg V3-Eigenschaften hinzu. Informationen zu Lakeflow Connect Pipelines finden Sie unter Delta-Tabelleneigenschaften festlegen.

    Eigentum Verwendung
    'pipelines.externalMetadata.enabled' = 'true' Aktiviere den externen Zugriff für die Tabelle. Diese Tabellen-Einstellung hat Vorrang gegenüber der Pipeline-Konfiguration, wenn beide gesetzt sind.
    'delta.columnMapping.mode' = 'name' Für Iceberg ist die Spaltenzuordnung erforderlich.
    'delta.enableRowTracking' = 'true' Zeilenverfolgung für Iceberg-Lesevorgänge aktivieren.
    'delta.universalFormat.enabledFormats' = 'iceberg' Aktivieren Sie Iceberg-Lesevorgänge.
    'delta.enableIcebergCompatV3' = 'true' Verwende Iceberg V3 für Iceberg-Lesungen. 
    CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

    Für materialisierte Ansichten kannst du stattdessen die entsprechende USING ICEBERG Syntax verwenden.

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    Für pipeline-verwaltete Datensätze verwenden Sie die oben genannten Pipeline-Update-Anweisungen, um die Iceberg-Eigenschaften anzuwenden. Für eigenständige Databricks-SQL-Objekte führe die Objektdefinition mit den aktualisierten Eigenschaften erneut aus. Verwenden Sie CREATE OR REPLACE MATERIALIZED VIEW für eine materialisierte Ansicht oder CREATE OR REFRESH STREAMING TABLE für eine Streaming-Tabelle. Um die Eigenschaften Ihres Datensatzes zu sehen, verwenden Sie die DESCRIBE DETAIL oder DESCRIBE EXTENDED SQL-Anweisungen.

Fehlerbehebung des externen Datenzugriffs

Wenn Sie denken, dass die externen Metadaten veraltet sind, kann ein Principal mit dem MODIFY Privileg in der Tabelle manuell das Metadaten-Update auf der Shared-Cluster-Berechnung mit Databricks Runtime 17.3 oder höher auslösen:

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

Sie können das Vorhandensein der Eisberg-Metadaten in der Catalog Explorer UI auf der Tabelleninformationsseite überprüfen. Alternativ können folgende Befehle im SQL-Editor oder in einem Azure Databricks-Notebook ausgeführt werden:

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

Für eine Streaming-Tabelle vergleichen Sie die Iceberg-Metadaten-Version mit der neuesten Streaming-Tabelle-Version. Der Versionsvergleich für materialisierte Ansichten ist noch nicht verfügbar.

Lesen von Daten aus externen Clients

Die folgenden Abschnitte bieten Beispiele, wie man den Datensatz aus verschiedenen Clients und Umgebungen lesen kann.

Für Einrichtungsdetails siehe Delta-Client-Zugriff und Iceberg-Client-Zugriff.

Verwenden der Unity-REST-API mit dem Spark Delta Reader

Verwenden Sie Apache Spark™, Version 4.0 oder höher. Sie können es von https://spark.apache.org/downloads.html herunterladen.

  1. Führen Sie basierend auf Ihrem Cloudanbieter den folgenden Befehl aus, um eine Spark SQL-Shell mit Delta 4.0 und Unity Catalog zu starten.

    AWS

    bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

    Azure

    bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

    GCP

    bin/spark-sql \
    --packages io.unitycatalog:unitycatalog-spark_2.13:0.3.1  \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

  2. Über die SQL-Shell können Sie jetzt mit Spark SQL auf Ihr Dataset zugreifen. Beispiel:

    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Verwenden des Snowflake Iceberg Reader

Innerhalb von Snowflake können Sie den Iceberg Reader verwenden. Dies erfordert Iceberg v3-Unterstützung in Snowflake.

  1. Richten Sie den Iceberg REST-Katalog in Snowflake ein.

    CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-table-name>';

  2. Greifen Sie über Snowflake SQL auf Ihren Datensatz zu.

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

Verwenden des Iceberg REST-Katalogs mit Spark Iceberg Reader

Verwenden Sie Apache Spark™, Version 4.0 oder höher. Sie können es von https://spark.apache.org/downloads.html herunterladen.

  1. Führen Sie in AWS den folgenden Befehl aus, um eine Spark SQL-Shell mit Iceberg v3 zu starten.

    bin/spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
  --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
  --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
  --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
  --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
  --conf spark.sql.iceberg.vectorization.enabled=false

  2. Greifen Sie über Spark SQL auf Ihr Dataset zu.

    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Migrieren aus dem Kompatibilitätsmodus

Wenn Sie derzeit einen Datensatz im Kompatibilitätsmodus freigeben, können Sie zur Verwendung von externem Datenzugriff migrieren.

  1. Aktivieren Sie diese Funktion, indem Sie die Schritte unter So aktivieren Sie den Zugriff für ein Dataset befolgen.
  2. Kompatibilitätsmodus deaktivieren. Siehe "Kompatibilitätsmodus deaktivieren"

Einschränkungen

Im Folgenden finden Sie bekannte Einschränkungen beim Zugriff auf externe Daten für Streamingtabellen und materialisierte Ansichten.

  • Externe Schreibvorgänge: Externe Schreibvorgänge in Pipeline-Datasets werden nicht unterstützt.
  • Path-Based Access: Externe Leser, die pfadbasierten Zugriff erfordern (direktes Lesen über einen Speicherort anstelle der UC-API-Schnittstelle) werden nicht unterstützt. Um den pfadbasierten Zugriff zu unterstützen, können Sie den Kompatibilitätsmodus verwenden, der pfadbasierten Zugriff unterstützt, erfordert jedoch eine vollständige Kopie des Datasets.
  • Sicherheitsfunktionen:Sicherheit auf Zeilenebene oder Maskierung auf Spaltenebene werden bei externen Lesevorgängen nicht unterstützt.
  • Zeitreisen:Zeitreisen über diese Funktion werden nicht unterstützt.
  • Katalog-Commits (Beta):Katalog-Commits sind nicht mit externem Datenzugriff kompatibel. Um externe Datenzugriffe auf einer Streaming-Tabelle oder einer materialisierten Ansicht zu nutzen, müssen Sie zunächst die Katalog-Comits deaktivieren.
  • Fabric: Das Lesen von Microsoft Fabric wird nicht unterstützt.
  • Last updated on