Mengakses tabel Databricks dari klien Delta

Halaman ini menjelaskan cara menggunakan Unity REST API untuk membuat, membaca, dan menulis ke Tabel terkelola Dan eksternal Unity Catalog dari klien Delta eksternal. Untuk daftar lengkap integrasi yang didukung, lihat Integrasi Katalog Unity.

Saran

Untuk informasi tentang cara membaca data Azure Databricks menggunakan Microsoft Fabric, lihat Gunakan Microsoft Fabric untuk membaca data yang terdaftar di Katalog Unity.

Membuat, membaca, dan menulis menggunakan Unity REST API

Penting

Membuat dan menulis ke tabel yang dikelola Unity Catalog dari klien Delta sedang dalam tahap Beta. Dukungan klien eksternal terbatas.

Unity REST API menyediakan klien eksternal membuat, membaca, dan menulis akses ke tabel yang terdaftar ke Katalog Unity. Konfigurasikan akses menggunakan URL ruang kerja sebagai titik akhir. Jenis tabel berikut ini dapat diakses:

Jenis tabel Read Menulis Buat
Delta yang Dikelola Yes Ya* Ya*
Delta Eksternal Yes Yes Yes

* Didukung untuk tabel Delta terkelola dengan komit katalog.

Persyaratan

Azure Databricks mendukung akses Unity REST API ke tabel sebagai bagian dari Unity Catalog. Anda harus memiliki Katalog Unity yang diaktifkan di ruang kerja Anda untuk menggunakan endpoint ini.

Anda juga harus menyelesaikan langkah-langkah konfigurasi berikut untuk mengonfigurasi akses ke tabel dari klien Delta menggunakan Unity REST API:

Keterbatasan

  • Akses eksternal ke tabel UniForm dengan IcebergCompatV3 saat ini tidak didukung. Setelah menulis secara eksternal ke tabel UniForm, Anda harus menjalankan MSCK REPAIR TABLE di Databricks untuk menghasilkan metadata Iceberg.
  • Perubahan skema (misalnya, ALTER TABLE), pembaruan properti tabel, dan perubahan fitur tabel saat ini tidak didukung pada tabel terkelola dari klien eksternal.
  • Klien eksternal tidak dapat melakukan operasi pemeliharaan tabel, seperti OPTIMIZE, , VACUUMdan ANALYZE, pada tabel Delta terkelola.
  • Klien eksternal tidak dapat membuat kloning dangkal.
  • Klien eksternal tidak dapat membuat tabel dengan kolom yang dihasilkan, kolom default, atau kolom batasan.
  • Saat membuat tabel eksternal, Azure Databricks merekomendasikan penggunaan Apache Spark untuk memastikan bahwa definisi kolom dalam format yang kompatibel dengan Apache Spark. API tidak memvalidasi kebenaran spesifikasi kolom. Jika spesifikasi tidak kompatibel dengan Apache Spark, maka Databricks Runtime mungkin tidak dapat membaca tabel.

Mengakses tabel Delta dengan Apache Spark menggunakan autentikasi PAT

Konfigurasi berikut diperlukan untuk membaca atau menulis ke tabel Delta terkelola dan eksternal Unity Catalog menggunakan Apache Spark dengan autentikasi PAT:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Ganti variabel berikut:

  • <uc-catalog-name>: Nama katalog di Unity Catalog yang berisi tabel Anda.
  • <token>: Token akses pribadi (PAT) untuk pengguna utama yang mengonfigurasi integrasi.
  • <workspace-url>: URL Azure Databricks workspace, termasuk ID ruang kerja. Contohnya, adb-1234567890123456.12.azuredatabricks.net.

Nota

Versi paket yang ditunjukkan di atas adalah yang terbaru berdasarkan pembaruan terakhir halaman ini. Versi yang lebih baru mungkin tersedia. Verifikasi bahwa versi paket kompatibel dengan versi Spark Anda.

Untuk detail tambahan tentang mengonfigurasi Apache Spark untuk penyimpanan objek cloud, lihat dokumentasi OSS Katalog Unity.

Penting

Databricks Runtime 16.4 ke atas diperlukan untuk membaca dari, menulis ke, atau membuat tabel dengan commit katalog diaktifkan. Databricks Runtime 18.0 ke atas diperlukan untuk mengaktifkan atau menonaktifkan penerapan katalog pada tabel yang ada.

Untuk membuat tabel Delta terkelola dengan komitmen katalog, gunakan SQL berikut:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

Untuk membuat tabel Delta eksternal, gunakan SQL berikut:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

Mengakses tabel Delta dengan Apache Spark menggunakan autentikasi OAuth

Azure Databricks juga mendukung autentikasi mesin-ke-mesin (M2M) OAuth. OAuth secara otomatis menangani token dan perpanjangan kredensial untuk autentikasi Katalog Unity.

Autentikasi OAuth untuk klien Spark eksternal memerlukan:

Konfigurasi berikut diperlukan untuk membuat, membaca, atau menulis ke tabel terkelola Unity Catalog dan tabel Delta eksternal dengan Apache Spark menggunakan autentikasi OAuth:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Ganti variabel berikut:

  • <workspace-url>: URL Azure Databricks workspace, termasuk ID ruang kerja. Contohnya, adb-1234567890123456.12.azuredatabricks.net.

Nota

Versi paket yang ditunjukkan di atas adalah yang terbaru berdasarkan pembaruan terakhir halaman ini. Versi yang lebih baru mungkin tersedia. Verifikasi bahwa versi paket kompatibel dengan versi Spark Anda.

Membuat tabel Delta menggunakan API

Untuk membuat tabel Delta eksternal menggunakan REST API Katalog Unity, ikuti langkah-langkah berikut:

Langkah 1: Buat permintaan POST ke Api Buat Tabel

Gunakan permintaan API berikut untuk mendaftarkan metadata tabel di Unity Catalog:

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

Ganti variabel berikut:

  • <workspace-url>: URL ruang kerja Azure Databricks
  • <token>: Token untuk perwakilan yang melakukan panggilan API
  • <uc-catalog-name>: Nama katalog di Unity Catalog yang akan berisi tabel eksternal
  • <schema-name>: Nama skema dalam katalog tempat tabel akan dibuat
  • <table-name>: Nama tabel eksternal
  • <path>: Jalur yang sepenuhnya memenuhi syarat ke data tabel

Langkah 2: Menginisialisasi lokasi tabel Delta

Panggilan API di atas mendaftarkan tabel di :[UC], tetapi tidak membuat file Delta di lokasi penyimpanan. Untuk menginisialisasi lokasi tabel, tulis tabel Delta kosong menggunakan Spark:

Skema yang digunakan dalam langkah ini harus sama persis dengan definisi kolom yang disediakan dalam permintaan API.


from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")

Nota

Api Buat Tabel untuk klien eksternal memiliki batasan berikut:

  • Hanya tabel Delta eksternal yang didukung ("table_type": "EXTERNAL" dan "data_source_format": "DELTA").
  • Hanya bidang berikut yang diizinkan:
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • Masker kolom tidak didukung.
  • Last updated on