Udostępnij za pośrednictwem

Starsza wersja UniForm IcebergCompatV1

  • Artykuł

Ważne

Ta dokumentacja została wycofana i może nie zostać zaktualizowana. Produkty, usługi lub technologie wymienione w tej zawartości nie są już obsługiwane. Zobacz Używanie programu UniForm do odczytywania tabel delty z klientami góry lodowej.

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej w środowisku Databricks Runtime 13.2 lub nowszym.

Format uniwersalny usługi Delta (UniForm) umożliwia odczytywanie tabel delty z klientami czytnika Góry lodowej.

Aplikacja UniForm korzysta z faktu, że zarówno usługa Delta Lake, jak 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 tak, jakby były tabelami góry lodowej. Pojedyncza kopia plików danych obsługuje oba formaty.

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.

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.

Wymagania

Aby włączyć aplikację UniForm, musisz spełnić następujące wymagania:

Włączanie funkcji Delta UniForm

Ważne

Włączenie funkcji Delta UniForm ustawia funkcję IcebergCompatV1tabeli 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 w wersji 13.2 lub nowszej, 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 wyłączyć mapowania kolumn po jej włączeniu, a nie można cofnąć uaktualnień do wersji czytnika i protokołu zapisywania usługi Delta Lake.

Poniższa właściwość tabeli umożliwia obsługę aplikacji UniForm dla góry lodowej. iceberg jest jedyną prawidłową wartością.

'delta.universalFormat.enabledFormats' = 'iceberg'

Należy również włączyć mapowanie kolumn i IcebergCompatV1 użyć funkcji UniForm. Są one ustawiane automatycznie, jeśli włączysz funkcję UniForm podczas tworzenia tabeli, jak w poniższym przykładzie:

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

Jeśli tworzysz nową tabelę z instrukcją CTAS, musisz ręcznie określić mapowanie kolumn, jak w poniższym przykładzie:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

Jeśli zmieniasz istniejącą tabelę, musisz określić wszystkie te właściwości, jak w poniższym przykładzie:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = '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.

Uwaga

Jeśli planujesz używać trybu BigQuery jako klienta czytnika góry lodowej, musisz ustawić true wartość spark.databricks.delta.write.dataFilesToSubdir w usłudze Azure Databricks, aby spełnić wymagania bigquery dotyczące układu danych.

Zobacz Ograniczenia.

Kiedy uniform generuje metadane góry lodowej?

Usługa Azure Databricks wyzwala asynchronicznie generowanie metadanych góry lodowej po zakończeniu transakcji zapisu usługi Delta Lake przy użyciu tego samego obliczenia, które zakończyło transakcję delty. 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 góry lodowej, tabele delty z częstymi zatwierdzeniami mogą wiązać wiele zatwierdzeń różnicowych w jednym zatwierdzeniu góry lodowej.

Usługa Delta Lake zapewnia, że w dowolnym momencie trwa tylko jeden proces generowania metadanych góry lodowej. Zatwierdzenia, które wyzwoliłyby drugi równoczesny proces generowania metadanych góry lodowej, zostaną pomyślnie zatwierdzony w funkcji Delta, ale nie będą wyzwalać 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.

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 przy użyciu Eksploratora wykazu. Te pola i wartości są również zwracane podczas korzystania z interfejsu API REST w celu uzyskania tabeli.

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

Ścieżkę tego pliku można znaleźć przy użyciu Eksploratora wykazu. W przypadku tabel z włączoną funkcją UniForm szczegóły tabeli delty zawierają pole lokalizacji metadanych Góry lodowej.

Możesz również użyć interfejsu API REST, aby uzyskać wszystkie szczegóły tabeli, w tym lokalizację metadanych. Użyj następującego polecenia:

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. Należy skonfigurować dostęp do bazowego magazynu obiektów w chmurze zawierającego tabelę delta z włączoną funkcją UniForm. Aby uzyskać szczegółowe informacje o konfiguracji, zapoznaj się z dokumentacją klienta czytnika góry lodowej.

Musisz wygenerować i skonfigurować osobisty token dostępu usługi Azure Databricks, aby umożliwić innym usługom łączenie się z wykazem aparatu Unity. Zobacz Uwierzytelnianie dostępu do zasobów usługi Azure Databricks.

Poniżej przedstawiono przykład ustawień 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.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"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.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

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

Uwaga

Podczas wykonywania zapytań dotyczących tabel w wykazie aparatu Unity przy użyciu tej metody identyfikatory obiektów używają następującego wzorca:

unity.<catalog-name>.<schema-name>.<table-name>

Ten wzorzec używa tej samej trójwarstwowej nazwy, która występuje w katalogu aparatu Unity, ale dodaje dodatkowy prefiks unity.

Wersje tabeli Delta i Góry Lodowej

Zarówno usługa Delta Lake, jak 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 Iceberg i Delta nie są wyrównane przez znacznik czasu zatwierdzenia lub identyfikator wersji. Jeśli chcesz sprawdzić, która wersja tabeli delty dana wersja tabeli Góry lodowej odpowiada, możesz użyć odpowiednich właściwości tabeli ustawionych w tabeli Góry lodowej. Zobacz Sprawdzanie stanu generowania metadanych góry lodowej.

Ograniczenia

Istnieją następujące ograniczenia:

  • 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ą LISTtypów , MAPi VOID .
  • 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.
  • Klienci czytników góry lodowej w wersji 1.2.0 i poniżej nie obsługują INT96 typu znacznika czasu napisanego przez platformę Apache Spark. Użyj następującego kodu w notesach, które zapisują w tabelach UniForm, aby uniknąć tego ograniczenia: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • Publiczna wersja zapoznawcza punktu końcowego Platformy Lodowej wykazu aparatu Unity nie jest przeznaczona dla obciążeń produkcyjnych na dużą skalę. Jeśli przekroczysz próg 5 zapytań na sekundę, może wystąpić ograniczenie szybkości.

Następujące funkcje usługi Delta Lake działają dla klientów usługi Delta, gdy funkcja UniForm jest włączona, ale nie ma obsługi w środowisku Iceberg:

  • Zmienianie źródła danych
  • Udostępnianie różnicowe