Mengakses tabel Azure Databricks dari klien Apache Iceberg

Penting

Unity Catalog Apache Iceberg REST Catalog API berada di Pratinjau Publik di Databricks Runtime 16.4 LTS dan versi yang lebih baru. Titik akhir ini direkomendasikan untuk membaca dan menulis tabel dari klien Iceberg.

Katalog Unity juga memiliki endpoint Iceberg REST Catalog API yang hanya-baca. Ini adalah titik akhir warisan. Lihat Membaca tabel Databricks dari klien Apache Iceberg (warisan).

Katalog REST Apache Iceberg memungkinkan klien yang didukung, seperti Apache Spark, Apache Flink, dan Trino, membaca dari dan menulis ke tabel Iceberg yang terdaftar di Unity Catalog di Azure Databricks.

Untuk daftar lengkap integrasi yang didukung, lihat Integrasi Katalog Unity.

Menggunakan titik akhir katalog Unity Catalog Iceberg

Unity Catalog menyediakan implementasi spesifikasi Iceberg REST catalog API.

Konfigurasikan akses menggunakan titik akhir /api/2.1/unity-catalog/iceberg-rest. Lihat spesifikasi Iceberg REST API untuk detail tentang penggunaan REST API ini.

Nota

Azure Databricks telah memperkenalkan penyediaan kredensial untuk beberapa klien pembaca Iceberg. Databricks merekomendasikan penggunaan kredensial vending untuk mengontrol akses ke lokasi penyimpanan cloud untuk sistem yang didukung. Lihat Penyediaan kredensial Katalog Unity untuk akses sistem eksternal dan mengakses tabel Iceberg menggunakan sistem eksternal.

Jika penyediaan kredensial otomatis tidak didukung untuk klien Anda, Anda harus mengonfigurasi akses dari klien ke lokasi penyimpanan yang mengandung file dan metadata untuk tabel Delta atau Iceberg. Lihat dokumentasi untuk klien Iceberg Anda untuk detail konfigurasi.

Persyaratan

Azure Databricks mendukung akses katalog Iceberg REST ke tabel sebagai bagian dari Unity Catalog. Anda harus memiliki Katalog Unity yang diaktifkan di ruang kerja Anda untuk menggunakan endpoint ini. Jenis tabel berikut dapat diakses menggunakan Iceberg REST Catalog:

Topik Bacalah Menulis
Gunung Es Terkelola Ya Ya
Gunung Es Asing Ya Tidak.
Delta yang Dikelola (dengan fitur pembacaan Iceberg diaktifkan) Ya Tidak.
Delta Eksternal (dengan pembacaan Iceberg diaktifkan) Ya Tidak.

Tabel Iceberg asing tidak di-refresh secara otomatis saat menggunakan Iceberg REST Catalog API untuk membaca tabel. Untuk menyegarkan, Anda harus menjalankan REFRESH FOREIGN TABLE untuk membaca rekam jepret terbaru. Pendistribusian kredensial pada tabel Foreign Iceberg tidak didukung.

Nota

Anda harus mengonfigurasi tabel Delta agar dapat diakses menggunakan Iceberg REST Catalog API. Lihat Baca tabel Delta dengan klien Iceberg.

Anda harus menyelesaikan langkah-langkah konfigurasi berikut untuk mengonfigurasi akses untuk membaca dari atau menulis ke tabel Azure Databricks dari klien Iceberg menggunakan katalog Iceberg REST:

Nota

Spesifikasi Iceberg tidak mengizinkan file data duplikat dalam satu rekam jepret tabel. Untuk mencegah hal ini, ketika terdeteksi, Unity Catalog memblokir mesin eksternal untuk menerapkan file data duplikat ke tabel.

Menggunakan tabel Iceberg dengan Apache Spark

Berikut ini adalah contoh cara mengonfigurasi Apache Spark untuk mengakses tabel Azure Databricks melalui Iceberg REST Catalog API menggunakan autentikasi OAuth:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

Ganti variabel berikut:

  • <uc-catalog-name>: Nama katalog di Unity Catalog yang berisi tabel Anda.
  • <spark-catalog-name>: Nama yang ingin Anda tetapkan katalog dalam sesi Spark Anda.
  • <oauth_client_id>: ID klien OAuth untuk prinsipal autentikasi.
  • <oauth_client_secret>: Rahasia klien OAuth untuk prinsipal autentikasi.

Dengan konfigurasi ini, Anda dapat mengkueri tabel di Unity Catalog menggunakan Apache Spark. Untuk mengakses tabel di beberapa katalog, Anda harus mengonfigurasi setiap katalog secara terpisah.

Saat Anda mengkueri tabel di Unity Catalog menggunakan konfigurasi Spark, ingatlah hal berikut:

  • Anda memerlukan "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" hanya jika Anda menjalankan prosedur tersimpan yang khusus untuk Iceberg .

  • Azure Databricks menggunakan penyimpanan objek cloud untuk semua tabel. Anda harus menambahkan JAR iceberg-spark-runtime sebagai paket 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>

    Untuk detailnya, lihat dokumentasi untuk integrasi Iceberg AWS untuk Spark.

    Nota

    Konfigurasi ini tidak diperlukan saat mengakses tabel Iceberg dari Azure Databricks. Memuat JAR Iceberg eksternal ke kluster Azure Databricks tidak didukung.

Mengakses tabel Azure Databricks dengan Snowflake

Snowflake menyediakan dua opsi untuk mengakses tabel melalui katalog Iceberg REST: menggunakan database yang ditautkan katalog Snowflake, atau menggunakan tabel eksternal.

Untuk kedua opsi, pertama-tama konfigurasikan integrasi katalog Snowflake. Azure Databricks mendukung metode autentikasi berikut untuk integrasi katalog Snowflake:

  • Token pembawa: Menggunakan token akses pribadi (PAT) Azure Databricks atau token OAuth. Didukung di semua cloud.
  • Principal Layanan Entra OAuth (khusus Azure): Menggunakan prinsipal layanan Microsoft Entra ID untuk mengautentikasi langsung terhadap endpoint token Entra.

Untuk detail selengkapnya tentang opsi autentikasi Snowflake untuk integrasi katalog REST, lihat dokumentasi Snowflake.

Snowflake dengan autentikasi token pembawa

Contoh berikut mengonfigurasi integrasi katalog Snowflake menggunakan token pembawa. Anda dapat menggunakan token akses pribadi (PAT) Azure Databricks atau token OAuth yang dihasilkan dari perwakilan layanan Azure Databricks. Untuk detail tentang pembuatan token OAuth, lihat Mengotorisasi akses perwakilan layanan ke Azure Databricks dengan OAuth.

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  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',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Ganti variabel berikut:

  • <catalog-integration-name>: Nama yang ingin Anda tetapkan untuk katalog yang terdaftar di Snowflake.
  • <uc-schema-name>: Nama skema di Unity Catalog yang perlu Anda akses.
  • <uc-catalog-name>: Nama katalog di Unity Catalog yang perlu Anda akses.
  • <workspace-url>: URL ruang kerja Azure Databricks. Misalnya, https://cust-success.cloud.databricks.com atau https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Token akses pribadi (PAT) untuk pengguna utama yang mengonfigurasi integrasi.

Snowflake dengan OAuth perwakilan layanan Entra

Di Azure, integrasi katalog Snowflake yang menggunakan prinsip layanan yang didukung oleh Entra tidak dapat menggunakan titik akhir token OIDC Azure Databricks (<workspace-url>/oidc/v1/token). Sebagai gantinya, Anda harus mengautentikasi langsung terhadap titik akhir token Microsoft Entra. Ini berbeda dari pendekatan OAuth yang digunakan untuk klien Iceberg lainnya (seperti Apache Spark) di Azure.

Nota

Dokumentasi Snowflake mungkin menunjukkan bahwa ID Entra tidak didukung. Konfigurasi di bawah ini menggunakan Entra OAuth yang menargetkan cakupan sumber daya Azure Databricks dan merupakan jalur yang didukung untuk membaca Katalog Unity dari Snowflake di Azure.

Sebelum mulai, pastikan bahwa Anda memiliki:

Jalankan SQL berikut di Snowflake:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

Ganti variabel berikut:

  • <catalog-integration-name>: Nama yang ingin Anda tetapkan untuk katalog yang terdaftar di Snowflake.
  • <uc-schema-name>: Nama skema di Unity Catalog yang perlu Anda akses.
  • <uc-catalog-name>: Nama katalog di Unity Catalog yang perlu Anda akses.
  • <workspace-url>: URL ruang kerja Azure Databricks. Contohnya, adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: ID penyewa Microsoft Entra Anda.
  • <entra-client-id>: ID aplikasi (klien) dari perwakilan layanan Entra.
  • <entra-client-secret>: Rahasia klien untuk perwakilan layanan Entra.

Penting

Cakupan 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default adalah ID aplikasi Azure Databricks yang telah terdaftar di Entra. Ini berbeda dari cakupan yang all-apis digunakan dengan titik akhir Azure Databricks OIDC. Menggunakan cakupan yang salah adalah penyebab umum kegagalan autentikasi saat mengonfigurasi integrasi ini.

Setelah membuat integrasi katalog, ikuti dokumentasi Snowflake untuk membuat database terkait katalog untuk mengakses tabel Anda.

Untuk informasi selengkapnya tentang membuat dan mengelola perwakilan layanan Entra untuk Azure Databricks, lihat Mengautentikasi dengan perwakilan layanan Microsoft Entra.

Nota

Snowflake tidak mendukung autentikasi Entra untuk integrasi katalog yang menggunakan jaringan privat (Azure Private Link) untuk menyambungkan ke Azure Databricks. Koneksi ke titik akhir katalog REST Azure Databricks Iceberg harus menggunakan jaringan publik saat mengautentikasi dengan prinsipal layanan Entra.

Database yang Ditautkan ke Katalog

Database yang dikaitkan dengan katalog Snowflake secara otomatis sinkron dengan Unity Catalog untuk mendeteksi skema dan tabel Iceberg. Ini menghilangkan kebutuhan akan refresh metadata manual.

Setelah mengonfigurasi integrasi katalog Snowflake, lihat dokumentasi Snowflake untuk membuat database yang terhubung ke katalog guna mengakses tabel Anda.

Penting

Mencoba menulis dari Snowflake ke tabel baca-saja Azure Databricks dapat menghasilkan kesalahan. Lihat dokumentasi Snowflake untuk operasi yang didukung.

Tabel eksternal

Atau, Anda dapat membuat tabel eksternal setelah membuat integrasi katalog Snowflake. Pendekatan ini memerlukan penyegaran metadata secara manual untuk melihat pembaruan.

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

Menggunakan tabel Azure Databricks dengan PyIceberg

Untuk menggunakan PyIceberg untuk mengakses tabel Azure Databricks, Anda harus menginstal PyIceberg dengan dependensi yang diperlukan. PyIceberg memerlukan pyarrow operasi tabel seperti membaca data dan memeriksa metadata tabel. Instal PyIceberg dengan ekstensi pyarrow.

pip install "pyiceberg[pyarrow]"

Nota

Jika Anda tidak menginstal pyarrow, operasi seperti menjelaskan atau membaca tabel gagal. Untuk daftar lengkap dependensi opsional, lihat dokumentasi PyIceberg.

Berikut ini adalah contoh pengaturan konfigurasi untuk memungkinkan PyIceberg mengakses tabel Azure Databricks dengan menyambungkan ke Iceberg REST Catalog di Unity Catalog:

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Ganti variabel berikut:

  • <uc-catalog-name>: Nama katalog di Unity Catalog yang perlu Anda akses.
  • <token>: Token akses pribadi (PAT) untuk pengguna utama yang mengonfigurasi integrasi.

Lihat dokumentasi untuk konfigurasi katalog PyIceberg REST.

Contoh penggunaan curl pada REST API

Contoh berikut curl memuat tabel menggunakan REST API:

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

Responsnya terlihat seperti ini:

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

Nota

Bidang expires-at-ms menunjukkan kapan kredensial kedaluwarsa. Waktu kedaluwarsa default adalah satu jam. Untuk performa yang lebih baik, minta klien menyimpan kredensial hingga kedaluwarsa sebelum meminta info masuk baru.

  • Last updated on