Delen via

UniForm gebruiken om Delta-tabellen te lezen met Iceberg-clients

  • Artikel

Met Delta Lake Universal Format (UniForm) kunt u Delta-tabellen lezen met Iceberg reader-clients. Voor deze functie is Databricks Runtime 14.3 LTS of hoger vereist.

Belangrijk

Zie Legacy UniForm IcebergCompatV1 voor documentatie voor de verouderde UniForm-tabelfunctie.IcebergCompatV1

U kunt een externe verbinding configureren om Unity Catalog als een Iceberg-catalogus te laten fungeren. Zie Lezen met behulp van het eindpunt van de Unity Catalog Iceberg-catalogus.

UniForm Iceberg gebruikt Zstandard in plaats van Snappy als de compressiecodec voor onderliggende Parquet-gegevensbestanden.

Notitie

Het genereren van UniForm-metagegevens wordt asynchroon uitgevoerd op de berekening die wordt gebruikt voor het schrijven van gegevens naar Delta-tabellen, waardoor het resourcegebruik van het stuurprogramma kan toenemen.

Hoe werkt UniForm?

UniForm maakt gebruik van het feit dat Delta Lake en Iceberg bestaan uit Parquet-gegevensbestanden en een metagegevenslaag. UniForm genereert automatisch icebergmetagegevens asynchroon, zonder gegevens te herschrijven, zodat Iceberg-clients Delta-tabellen kunnen lezen. Eén kopie van de gegevensbestanden heeft meerdere indelingen.

Vereisten

Als u UniForm Iceberg wilt inschakelen, moet aan de volgende vereisten worden voldaan:

Notitie

U kunt verwijderingsvectoren niet inschakelen voor een tabel waarvoor UniForm Iceberg is ingeschakeld.

Gebruik REORG deze optie om verwijderingsvectoren uit te schakelen en leeg te maken terwijl UniForm Iceberg op een bestaande tabel wordt ingeschakeld met verwijderingsvectoren ingeschakeld. Zie Inschakelen of upgraden met BEHULP van REORG.

UniForm Iceberg inschakelen

Belangrijk

Als u Delta UniForm inschakelt, wordt de deltatabelfunctie IcebergCompatV2ingesteld, een functie voor schrijfprotocollen. Alleen clients die deze tabelfunctie ondersteunen, kunnen schrijven naar tabellen met UniForm-functionaliteit. U moet Databricks Runtime 14.3 LTS of hoger gebruiken om naar Delta-tabellen te schrijven waarvoor deze functie is ingeschakeld.

U kunt UniForm uitschakelen door de delta.universalFormat.enabledFormats tabeleigenschap uit te schakelen. Upgrades naar delta lake-lezer- en schrijfprotocolversies kunnen niet ongedaan worden gemaakt.

U moet de volgende tabeleigenschappen instellen om UniForm Iceberg in te schakelen:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

Wanneer u UniForm voor het eerst inschakelt, wordt het genereren van asynchrone metagegevens gestart. Deze taak moet worden voltooid voordat externe clients een query kunnen uitvoeren op de tabel met behulp van Iceberg. Zie De status van het genereren van IJsberg-metagegevens controleren.

Zie Beperkingen voor een lijst met beperkingen.

Inschakelen tijdens het maken van een tabel

Kolomtoewijzing moet zijn ingeschakeld om UniForm Iceberg te kunnen gebruiken. Dit gebeurt automatisch als u UniForm Iceberg inschakelt tijdens het maken van de tabel, zoals in het volgende voorbeeld:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Inschakelen door een bestaande tabel te wijzigen

In Databricks Runtime 15.4 LTS en hoger kunt u UniForm Iceberg in- of upgraden op een bestaande tabel met behulp van de volgende syntaxis:

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Inschakelen of upgraden met REORG

U kunt UniForm Iceberg inschakelen REORG en onderliggende gegevensbestanden herschrijven, zoals in het volgende voorbeeld:

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

Gebruik REORG deze optie als een van de volgende waar is:

  • In de tabel zijn verwijderingsvectoren ingeschakeld.
  • U hebt eerder de IcebergCompatV1 versie van UniForm Iceberg ingeschakeld.
  • U moet lezen uit Iceberg-engines die geen Ondersteuning bieden voor Parquet-bestanden in Hive-stijl, zoals Athene of Redshift.

Wanneer genereert UniForm icebergmetagegevens?

Azure Databricks activeert het genereren van metagegevens asynchroon nadat een Delta Lake-schrijftransactie is voltooid. Dit proces voor het genereren van metagegevens maakt gebruik van dezelfde berekening die de Delta-transactie heeft voltooid.

Notitie

U kunt ook het genereren van iceberg-metagegevens handmatig activeren. Zie Handmatig conversie van iceberg-metagegevens activeren.

Om schrijflatenties te voorkomen die zijn gekoppeld aan het genereren van metagegevens, kunnen Delta-tabellen met frequente doorvoeringen meerdere Delta-doorvoeringen groeperen in één doorvoering naar Iceberg-metagegevens.

Delta Lake zorgt ervoor dat slechts één proces voor het genereren van metagegevens op elk moment wordt uitgevoerd op een bepaalde rekenresource. Doorvoeringen die een tweede gelijktijdig proces voor het genereren van metagegevens activeren, worden doorgevoerd in Delta, maar activeren geen asynchrone IJsberg-metagegevensgeneratie. Dit voorkomt trapsgewijze latentie voor het genereren van metagegevens voor workloads met frequente doorvoeringen (seconden tot minuten tussen doorvoeringen).

Zie Delta- en Iceberg-tabelversies.

Delta- en Iceberg-tabelversies

Delta Lake en Iceberg staan query's voor tijdreizen toe met behulp van tabelversies of tijdstempels die zijn opgeslagen in tabelmetagegevens.

In het algemeen worden deltatabelversies niet uitgelijnd op Iceberg-versies door de tijdstempel voor doorvoeren of de versie-id. Als u wilt controleren met welke versie van een Delta-tabel een bepaalde versie van een Iceberg-tabel overeenkomt, kunt u de bijbehorende tabeleigenschappen gebruiken. Zie De status van het genereren van IJsberg-metagegevens controleren.

Status van het genereren van IJsberg-metagegevens controleren

UniForm voegt de volgende velden toe aan metagegevens van de Unity Catalog- en Iceberg-tabel om de status van het genereren van metagegevens bij te houden:

Metagegevensveld Beschrijving
converted_delta_version De nieuwste versie van de Delta-tabel waarvoor iceberg-metagegevens zijn gegenereerd.
converted_delta_timestamp De tijdstempel van de meest recente Delta-doorvoer waarvoor iceberg-metagegevens zijn gegenereerd.

In Azure Databricks kunt u deze metagegevensvelden controleren door een van de volgende handelingen uit te voeren:

  • Delta Uniform Iceberg De sectie controleren die wordt geretourneerd door DESCRIBE EXTENDED table_name.
  • Tabelmetagegevens controleren met Catalog Explorer.
  • Gebruik de REST API om een tabel op te halen.

Raadpleeg de documentatie voor uw Iceberg-lezerclient voor het controleren van tabeleigenschappen buiten Azure Databricks. Voor OSS Apache Spark ziet u deze eigenschappen met behulp van de volgende syntaxis:

SHOW TBLPROPERTIES <table-name>;

Iceberg-metagegevensconversie handmatig activeren

U kunt het genereren van metagegevens van Iceberg handmatig activeren voor de nieuwste versie van de Delta-tabel. Deze bewerking wordt synchroon uitgevoerd, wat betekent dat de inhoud van de tabel die beschikbaar is in Iceberg, overeenkomt met de nieuwste versie van de Delta-tabel die beschikbaar is wanneer het conversieproces is gestart.

Deze bewerking moet niet nodig zijn onder normale omstandigheden, maar kan helpen als u het volgende tegenkomt:

  • Een cluster wordt beëindigd voordat het automatisch genereren van metagegevens slaagt.
  • Een fout of taakfout onderbreekt het genereren van metagegevens.
  • Een client die geen ondersteuning biedt voor gneration van UniForm Iceberg-metagegevens naar de Delta-tabel.

Gebruik de volgende syntaxis om het genereren van metagegevens van Iceberg handmatig te activeren:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Zie REPAIR TABLE.

Lezen met behulp van een JSON-pad voor metagegevens

Voor sommige Iceberg-clients moet u een pad naar bestanden met geversiede metagegevens opgeven om externe Iceberg-tabellen te registreren. Telkens wanneer UniForm een nieuwe versie van de Delta-tabel converteert naar Iceberg, wordt er een nieuw JSON-bestand met metagegevens gemaakt.

Clients die JSON-paden voor metagegevens gebruiken voor het configureren van Iceberg, omvatten BigQuery. Raadpleeg de documentatie voor de Iceberg Reader-client voor configuratiedetails.

Delta Lake slaat icebergmetagegevens op onder de tabelmap, met behulp van het volgende patroon:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

In Azure Databricks kunt u deze metagegevenslocatie controleren door een van de volgende handelingen uit te voeren:

  • Delta Uniform Iceberg De sectie controleren die wordt geretourneerd door DESCRIBE EXTENDED table_name.
  • Tabelmetagegevens controleren met Catalog Explorer.
  • Gebruik de volgende opdracht met de REST API:
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

Het antwoord bevat de volgende informatie:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Belangrijk

Op pad gebaseerde Iceberg-lezerclients vereisen mogelijk handmatig het bijwerken en vernieuwen van JSON-paden voor metagegevens om de huidige tabelversies te lezen. Gebruikers kunnen fouten tegenkomen bij het uitvoeren van query's op Iceberg-tabellen met verouderde versies, omdat Parquet-gegevensbestanden worden verwijderd uit de Delta-tabel met VACUUM.

Lezen met het Unity Catalog Iceberg-cataloguseindpunt

Sommige Iceberg-clients kunnen verbinding maken met een Iceberg REST-catalogus. Unity Catalog biedt een alleen-lezen implementatie van de Iceberg REST-catalogus-API voor Delta-tabellen waarvoor UniForm is ingeschakeld met behulp van het eindpunt /api/2.1/unity-catalog/iceberg. Zie de iceberg REST API-specificatie voor meer informatie over het gebruik van deze REST API.

Clients die bekend zijn om de Iceberg-catalogus-API te ondersteunen, zijn Apache Spark, Flink en Trino. Raadpleeg de documentatie voor de Iceberg Reader-client voor configuratiedetails.

Verificatie en autorisatie

Er zijn twee vereisten voor toegang tot gegevens die zijn geregistreerd in Unity Catalog met behulp van het api/2.1/unity-catalog/iceberg eindpunt van externe services:

Voorbeeld van Apache Spark-configuratie

Hier volgt een voorbeeld van de instellingen die worden gebruikt om OSS Apache Spark te configureren voor het lezen van UniForm als Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.type": "rest",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token": "<your_personal_access_token>",
"spark.sql.catalog.unity.warehouse": "<uc_catalog_name>"

Vervang de volledige URL van de werkruimte waarin u het persoonlijke toegangstoken hebt gegenereerd voor <api-root>.

Wanneer u query's uitvoert op tabellen in Unity Catalog met behulp van Spark-configuraties, moet u rekening houden met het volgende:

  • Object-id's maken gebruik van het patroon unity.<schema-name>.<table-name>.

    Dit patroon maakt gebruik van dezelfde naamruimte met drie lagen die wordt gebruikt in Unity Catalog, maar door de catalogusnaam vervangen door unity.

  • U hebt alleen nodig "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" als u icebergspecifieke opgeslagen procedures uitvoert.

  • Als u een cloudprovider voor opslag gebruikt, moet u de cloudspecifieke Iceberg-bundel-JAR's toevoegen als spark-pakketten:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Zie de documentatie voor de Iceberg AWS-integratie voor Spark voor meer informatie.

Voorbeeld van REST API curl

U kunt ook een REST API-aanroep zoals in dit curl-voorbeeld gebruiken om een tabel te laden:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Vervolgens ontvangt u een antwoord dat er als volgt uitziet:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Notitie

Het expires-at-ms veld in het antwoord geeft de verlooptijd van de referenties aan en heeft een standaardverlooptijd van één uur. Voor betere prestaties moet de client de referenties in de cache opslaan tot de vervaltijd voordat u een nieuwe aanvraagt.

Beperkingen

De volgende beperkingen gelden voor alle UniForm-tabellen:

  • UniForm werkt niet op tabellen waarvoor verwijderingsvectoren zijn ingeschakeld. Zie Wat zijn verwijderingsvectoren?
  • Delta-tabellen waarvoor UniForm is ingeschakeld, bieden geen ondersteuning voor VOID typen.
  • Iceberg-clients kunnen alleen lezen van UniForm. Schrijfbewerkingen worden niet ondersteund.
  • IJsberglezers kunnen afzonderlijke beperkingen hebben, ongeacht UniForm. Raadpleeg de documentatie voor de door u gekozen client.
  • De ontvangers van Delta Sharing kunnen de tabel alleen lezen als Delta, zelfs als UniForm is ingeschakeld.
  • Sommige Delta Lake-tabelfuncties die door UniForm Iceberg worden gebruikt, worden niet ondersteund door sommige Delta Sharing-lezersclients. Zie Wat is Delta Sharing?

Change Data Feed werkt voor Delta-clients wanneer UniForm is ingeschakeld, maar heeft geen ondersteuning in Iceberg.