Odczytywanie tabel delty przy użyciu programu UniForm z klientami góry lodowej

Artykuł
09/28/2024

Format uniwersalny usługi Delta Lake (UniForm) umożliwia odczytywanie tabel delty z klientami czytnika Góry lodowej. Ta funkcja wymaga środowiska Databricks Runtime 14.3 LTS lub nowszego.

Ważne

Aby uzyskać dokumentację starszej funkcji tabeli UniForm, zobacz Legacy UniForm IcebergCompatV1 IcebergCompatV1.

Połączenie zewnętrzne można skonfigurować tak, aby katalog aparatu Unity działał jako wykaz gór lodowych. Zobacz Odczyt przy użyciu punktu końcowego wykazu góry lodowej wykazu aparatu Unity.

UniForm Iceberg używa standardu Zstandard zamiast Snappy jako kodera kompresji dla bazowych plików danych Parquet.

Uwaga

Generowanie metadanych UniForm jest uruchamiane asynchronicznie na obliczeniach używanych do zapisywania danych w tabelach delty, co może zwiększyć użycie zasobów sterownika.

Jak działa uniform?

Aplikacja UniForm korzysta z faktu, że usługa Delta Lake i Iceberg składają się z plików danych Parquet i warstwy metadanych. Aplikacja UniForm automatycznie generuje asynchroniczne metadane góry lodowej bez ponownego zapisywania danych, dzięki czemu klienci góry lodowej mogą odczytywać tabele delty. Pojedyncza kopia plików danych obsługuje wiele formatów.

Wymagania

Aby włączyć Platformę Lodowa UniForm, należy spełnić następujące wymagania:

Tabela delty musi być zarejestrowana w wykazie aparatu Unity. Obsługiwane są zarówno tabele zarządzane, jak i zewnętrzne.
Tabela musi mieć włączone mapowanie kolumn. Zobacz Zmienianie nazwy i usuwanie kolumn za pomocą mapowania kolumn usługi Delta Lake.
Tabela delty musi mieć minReaderVersion>wartość = 2 i minWriterVersion>= 7. Zobacz artykuł Jak usługa Azure Databricks zarządza zgodnością funkcji usługi Delta Lake?.
Zapisy w tabeli muszą używać środowiska Databricks Runtime 14.3 LTS lub nowszego.

Uwaga

Nie można włączyć wektorów usuwania w tabeli z włączonym UniForm Iceberg.

Służy REORG do wyłączania i przeczyszczania wektorów usuwania podczas włączania UniForm Iceberg w istniejącej tabeli z włączonymi wektorami usuwania. Zobacz Włączanie lub uaktualnianie przy użyciu funkcji REORG.

Włączanie góry lodowej UniForm

Ważne

Włączenie funkcji Delta UniForm ustawia funkcję IcebergCompatV2tabeli delty , funkcję protokołu zapisu. Tylko klienci, którzy obsługują tę funkcję tabeli, mogą zapisywać dane w tabelach z obsługą funkcji UniForm. Musisz użyć środowiska Databricks Runtime 14.3 LTS lub nowszego, aby zapisać dane w tabelach delty z włączoną tą funkcją.

Możesz wyłączyć funkcję UniForm, usuwając resetowanie delta.universalFormat.enabledFormats właściwości tabeli. Nie można cofnąć uaktualnień do wersji protokołu zapisywania i czytnika usługi Delta Lake.

Aby włączyć Górę Lodowa UniForm, należy ustawić następujące właściwości tabeli:

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

Po pierwszym włączeniu funkcji UniForm rozpoczyna się asynchroniczne generowanie metadanych. To zadanie musi zostać ukończone, zanim klienci zewnętrzni będą mogli wykonywać zapytania dotyczące tabeli przy użyciu góry lodowej. Zobacz Sprawdzanie stanu generowania metadanych góry lodowej.

Aby uzyskać listę ograniczeń, zobacz Ograniczenia.

Włącz podczas tworzenia tabeli

Aby można było używać góry lodowej UniForm, należy włączyć mapowanie kolumn. Dzieje się tak automatycznie w przypadku włączenia góry lodowej UniForm podczas tworzenia tabeli, jak w poniższym przykładzie:

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

Włącz przez zmianę istniejącej tabeli

W środowisku Databricks Runtime 15.4 LTS lub nowszym można włączyć lub uaktualnić platformę Lodową UniForm w istniejącej tabeli przy użyciu następującej składni:

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

Włączanie lub uaktualnianie przy użyciu polecenia `REORG`

Możesz użyć REORG polecenia , aby włączyć górę lodowa UniForm i przepisać bazowe pliki danych, jak w poniższym przykładzie:

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

Użyj REORG , jeśli którekolwiek z następujących elementów ma wartość true:

Tabela ma włączone wektory usuwania.
Wcześniej włączono wersję Platformy IcebergCompatV1 Lodowej UniForm.
Musisz przeczytać z aparatów góry lodowej, które nie obsługują plików Parquet w stylu Hive, takich jak Atena lub Redshift.

Kiedy uniform generuje metadane góry lodowej?

Usługa Azure Databricks wyzwala asynchronicznie generowanie metadanych po zakończeniu transakcji zapisu usługi Delta Lake. Ten proces generowania metadanych używa tych samych obliczeń, które zakończyły transakcję delta.

Uwaga

Możesz również ręcznie wyzwolić generowanie metadanych góry lodowej. Zobacz Ręczne wyzwalanie konwersji metadanych góry lodowej.

Aby uniknąć opóźnień zapisu skojarzonych z generowaniem metadanych, tabele delty z częstymi zatwierdzeniami mogą grupować wiele zatwierdzeń różnicowych w jedno zatwierdzenie metadanych góry lodowej.

Usługa Delta Lake zapewnia, że w dowolnym momencie w danym zasobie obliczeniowym trwa tylko jeden proces generowania metadanych. Zatwierdzenia, które wyzwoliłyby drugi współbieżny proces generowania metadanych pomyślnie zatwierdzić funkcję delta, ale nie wyzwalają asynchronicznego generowania metadanych góry lodowej. Zapobiega to kaskadowemu opóźnieniu generowania metadanych dla obciążeń z częstymi zatwierdzeniami (od sekund do minut między zatwierdzeniami).

Zobacz wersje tabel Delta i Iceberg.

Wersje tabeli Delta i Góry Lodowej

Usługa Delta Lake i Iceberg umożliwiają wykonywanie zapytań dotyczących podróży w czasie przy użyciu wersji tabeli lub sygnatur czasowych przechowywanych w metadanych tabeli.

Ogólnie rzecz biorąc, wersje tabeli delty nie są wyrównane do wersji góry lodowej za pomocą znacznika czasu zatwierdzenia lub identyfikatora wersji. Aby sprawdzić, która wersja tabeli delty dana wersja tabeli Góry lodowej odpowiada, możesz użyć odpowiednich właściwości tabeli. Zobacz Sprawdzanie stanu generowania metadanych góry lodowej.

Sprawdzanie stanu generowania metadanych góry lodowej

Aplikacja UniForm dodaje następujące pola do metadanych wykazu aparatu Unity i tabeli Góry lodowej w celu śledzenia stanu generowania metadanych:

Pole metadanych	opis
`converted_delta_version`	Najnowsza wersja tabeli delty, dla której pomyślnie wygenerowano metadane góry lodowej.
`converted_delta_timestamp`	Sygnatura czasowa najnowszego zatwierdzenia delty, dla którego metadane góry lodowej zostały pomyślnie wygenerowane.

W usłudze Azure Databricks możesz przejrzeć te pola metadanych, wykonując jedną z następujących czynności:

Przejrzyj sekcję zwróconą Delta Uniform Iceberg przez DESCRIBE EXTENDED table_nameelement .
Przeglądanie metadanych tabeli za pomocą Eksploratora wykazu.
Uzyskiwanie tabeli przy użyciu interfejsu API REST.

Zapoznaj się z dokumentacją klienta czytelnika platformy Iceberg, aby dowiedzieć się, jak przeglądać właściwości tabeli poza usługą Azure Databricks. W przypadku systemu operacyjnego Apache Spark można zobaczyć te właściwości przy użyciu następującej składni:

SHOW TBLPROPERTIES <table-name>;

Ręczne wyzwalanie konwersji metadanych góry lodowej

Możesz ręcznie wyzwolić generowanie metadanych góry lodowej dla najnowszej wersji tabeli delty. Ta operacja jest uruchamiana synchronicznie, co oznacza, że po zakończeniu spis dostępny w Iceberg odzwierciedla najnowszą wersję tabeli delty dostępnej po rozpoczęciu procesu konwersji.

Ta operacja nie powinna być konieczna w normalnych warunkach, ale może pomóc, jeśli wystąpią następujące kwestie:

Klaster kończy się, zanim automatyczne generowanie metadanych zakończy się pomyślnie.
Błąd lub niepowodzenie zadania przerywa generowanie metadanych.
Klient, który nie obsługuje gneration metadanych UniForm Iceberg zapisuje w tabeli delty.

Użyj następującej składni, aby ręcznie wyzwolić generowanie metadanych góry lodowej:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Zobacz NAPRAWIANIE TABELI.

Odczytywanie przy użyciu ścieżki JSON metadanych

Niektórzy klienci góry lodowej wymagają podania ścieżki do plików metadanych w wersji w celu zarejestrowania zewnętrznych tabel góry lodowej. Za każdym razem, gdy aplikacja UniForm konwertuje nową wersję tabeli delta na górę lodową, tworzy nowy plik JSON metadanych.

Klienci korzystający ze ścieżek JSON metadanych do konfigurowania góry lodowej obejmują bigquery. Aby uzyskać szczegółowe informacje o konfiguracji, zapoznaj się z dokumentacją klienta czytnika góry lodowej.

Usługa Delta Lake przechowuje metadane góry lodowej w katalogu tabeli przy użyciu następującego wzorca:

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

W usłudze Azure Databricks możesz przejrzeć tę lokalizację metadanych, wykonując jedną z następujących czynności:

Przejrzyj sekcję zwróconą Delta Uniform Iceberg przez DESCRIBE EXTENDED table_nameelement .
Przeglądanie metadanych tabeli za pomocą Eksploratora wykazu.
Za pomocą następującego polecenia z interfejsem API REST:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

Odpowiedź zawiera następujące informacje:

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

Ważne

Klienci czytnika Iceberg oparte na ścieżkach mogą wymagać ręcznego aktualizowania i odświeżania ścieżek JSON metadanych w celu odczytu bieżących wersji tabeli. Użytkownicy mogą napotkać błędy podczas wykonywania zapytań dotyczących tabel Góry lodowej przy użyciu nieaktualnych wersji, ponieważ pliki danych Parquet są usuwane z tabeli delty za pomocą polecenia VACUUM.

Odczytywanie przy użyciu punktu końcowego wykazu góry lodowej wykazu aparatu Unity

Niektórzy klienci góry lodowej mogą łączyć się z katalogiem REST góry lodowej. Wykaz aparatu Unity udostępnia implementację interfejsu API katalogu REST platformy Iceberg tylko do odczytu dla tabel delty z włączoną funkcją UniForm przy użyciu punktu końcowego /api/2.1/unity-catalog/iceberg. Zobacz specyfikację interfejsu API REST Iceberg, aby uzyskać szczegółowe informacje na temat korzystania z tego interfejsu API REST.

Klienci znani z obsługi interfejsu API wykazu Góry Lodowej obejmują platformy Apache Spark, Flink i Trino. Aby uzyskać szczegółowe informacje o konfiguracji, zapoznaj się z dokumentacją klienta czytnika góry lodowej.

Uwierzytelnianie i autoryzacja

Istnieją dwa wymagania dotyczące uzyskiwania dostępu do danych zarejestrowanych w wykazie aparatu Unity przy użyciu punktu końcowego api/2.1/unity-catalog/iceberg z usług zewnętrznych:

Uwierzytelnianie przy użyciu protokołu OAuth lub osobistego tokenu dostępu usługi Databricks. Zobacz Uwierzytelnianie dostępu do zasobów usługi Azure Databricks.
Włącz dostęp do danych zewnętrznych dla magazynu metadanych. Ogranicza to dostęp do użytkowników, którzy mają EXTERNAL USE SCHEMA uprawnienia do schematu odczytywanego przez interfejs API. Zobacz Kontrola dostępu zewnętrznego do danych w wykazie aparatu Unity.

Przykład konfiguracji platformy Apache Spark

Poniżej przedstawiono przykład ustawień używanych do konfigurowania systemu operacyjnego Apache Spark w celu odczytania aplikacji UniForm jako góry lodowej:

"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>"

Zastąp pełny adres URL obszaru roboczego, w którym wygenerowano osobisty token dostępu dla elementu <api-root>.

Podczas wykonywania zapytań dotyczących tabel w wykazie aparatu Unity przy użyciu konfiguracji platformy Spark należy pamiętać o następujących kwestiach:

Identyfikatory obiektów używają wzorca unity.<schema-name>.<table-name>.

Ten wzorzec używa tej samej trójwarstwowej przestrzeni nazw, która jest używana w wykazie aparatu Unity, ale z nazwą wykazu zastąpioną przez unity.
Potrzebujesz "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" tylko wtedy, gdy używasz procedur składowanych specyficznych dla góry lodowej.
Jeśli używasz dostawcy usług w chmurze do magazynowania, musisz dodać pliki jar pakietu Iceberg specyficzne dla chmury jako pakiety spark:
- 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>
Aby uzyskać szczegółowe informacje, zobacz dokumentację integracji platformy Iceberg AWS dla platformy Spark.

Przykład narzędzia curl interfejsu API REST

Możesz również użyć wywołania interfejsu API REST, takiego jak w tym przykładzie curl, aby załadować tabelę:

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>

Następnie powinna zostać wyświetlona odpowiedź podobna do następującej:

{
  "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>"
  }
}

Uwaga

Pole expires-at-ms w odpowiedzi wskazuje czas wygaśnięcia poświadczeń i ma domyślny czas wygaśnięcia jednej godziny. Aby uzyskać lepszą wydajność, klient buforuje poświadczenia do momentu wygaśnięcia przed zażądaniem nowego.

Ograniczenia

Istnieją następujące ograniczenia dotyczące wszystkich tabel UniForm:

Funkcja UniForm nie działa w tabelach z włączonymi wektorami usuwania. Zobacz Co to są wektory usuwania?.
Tabele różnicowe z włączonym funkcją UniForm nie obsługują VOID typów.
Klienci góry lodowej mogą odczytywać tylko z uniformu. Zapisy nie są obsługiwane.
Klienci czytelników góry lodowej mogą mieć indywidualne ograniczenia, niezależnie od UniForm. Zapoznaj się z dokumentacją wybranego klienta.
Adresaci funkcji Udostępniania różnicowego mogą odczytywać tabelę tylko jako delta, nawet jeśli jest włączona funkcja UniForm.
Niektóre funkcje tabel usługi Delta Lake używane przez górę lodowa UniForm nie są obsługiwane przez niektórych klientów czytnika funkcji delta sharing. Zobacz Co to jest udostępnianie różnicowe?.

Źródło danych zmian działa dla klientów różnicowych, gdy aplikacja UniForm jest włączona, ale nie ma obsługi w górach lodowych.

Udostępnij za pośrednictwem

Odczytywanie tabel delty przy użyciu programu UniForm z klientami góry lodowej

Jak działa uniform?

Wymagania

Włączanie góry lodowej UniForm

Włącz podczas tworzenia tabeli

Włącz przez zmianę istniejącej tabeli

Włączanie lub uaktualnianie przy użyciu polecenia `REORG`

Kiedy uniform generuje metadane góry lodowej?

Wersje tabeli Delta i Góry Lodowej

Sprawdzanie stanu generowania metadanych góry lodowej

Ręczne wyzwalanie konwersji metadanych góry lodowej

Odczytywanie przy użyciu ścieżki JSON metadanych

Odczytywanie przy użyciu punktu końcowego wykazu góry lodowej wykazu aparatu Unity

Uwierzytelnianie i autoryzacja

Przykład konfiguracji platformy Apache Spark

Przykład narzędzia curl interfejsu API REST

Ograniczenia

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Odczytywanie tabel delty przy użyciu programu UniForm z klientami góry lodowej

Jak działa uniform?

Wymagania

Włączanie góry lodowej UniForm

Włącz podczas tworzenia tabeli

Włącz przez zmianę istniejącej tabeli

Włączanie lub uaktualnianie przy użyciu polecenia REORG

Kiedy uniform generuje metadane góry lodowej?

Wersje tabeli Delta i Góry Lodowej

Sprawdzanie stanu generowania metadanych góry lodowej

Ręczne wyzwalanie konwersji metadanych góry lodowej

Odczytywanie przy użyciu ścieżki JSON metadanych

Odczytywanie przy użyciu punktu końcowego wykazu góry lodowej wykazu aparatu Unity

Uwierzytelnianie i autoryzacja

Przykład konfiguracji platformy Apache Spark

Przykład narzędzia curl interfejsu API REST

Ograniczenia

Opinia

Dodatkowe zasoby

Włączanie lub uaktualnianie przy użyciu polecenia `REORG`