Konektor Databricks SQL untuk Python

Artikel
10/10/2024

Konektor SQL Databricks untuk Python adalah pustaka Python yang memungkinkan Anda menggunakan kode Python untuk menjalankan perintah SQL pada kluster Azure Databricks dan gudang Databricks SQL. Konektor SQL Databricks untuk Python lebih mudah disiapkan dan digunakan daripada pustaka Python serupa seperti pyodbc. Pustaka ini mengikuti PEP 249 – Spesifikasi API Database Python v2.0.

Catatan

Konektor SQL Databricks untuk Python juga menyertakan dialek SQLAlchemy untuk Azure Databricks. Lihat Menggunakan SQLAlchemy dengan Azure Databricks.

Persyaratan

Mesin pengembangan yang menjalankan Python >=3.8 dan <=3.11.
Databricks merekomendasikan agar Anda menggunakan lingkungan virtual Python, seperti yang disediakan oleh venv yang disertakan dengan Python. Lingkungan virtual membantu memastikan bahwa Anda menggunakan versi Python yang benar dan Konektor SQL Databricks untuk Python bersama-sama. Menyiapkan dan menggunakan lingkungan virtual berada di luar cakupan artikel ini. Untuk informasi selengkapnya, lihat Membuat lingkungan virtual.
Kluster atau Gudang SQL yang sudah ada.

Memulai

Instal Konektor SQL Databricks untuk pustaka Python di komputer pengembangan Anda dengan menjalankan pip install databricks-sql-connector atau python -m pip install databricks-sql-connector.
Kumpulkan informasi berikut ini untuk kluster atau gudang SQL yang ingin digunakan:

Kluster
- Nama host server kluster. Anda bisa mendapatkan nama ini dari nilai Nama Host Server di tab Opsi Tingkat Lanjut > JDBC/ODBC kluster Anda.
- Jalur HTTP kluster. Anda bisa mendapatkan jalur ini dari nilai Jalur HTTP di tab Opsi Tingkat Lanjut > JDBC/ODBC kluster Anda.
Gudang SQL
- Nama host server gudang SQL. Anda dapat memperoleh nama ini dari nilai Nama Host Server pada tab Detail Sambungan untuk gudang SQL Anda.
- Jalur HTTP gudang SQL. Anda dapat memperoleh jalur ini dari nilai Jalur HTTP pada tab Detail Sambungan gudang SQL Anda.

Autentikasi

Konektor SQL Databricks untuk Python mendukung jenis autentikasi Azure Databricks berikut:

Autentikasi token akses pribadi Databricks
Autentikasi token ID Microsoft Entra
Autentikasi mesin-ke-mesin (M2M) OAuth
Autentikasi pengguna ke komputer (U2M) OAuth

Konektor SQL Databricks untuk Python belum mendukung jenis autentikasi Azure Databricks berikut:

Autentikasi token akses pribadi Databricks

Untuk menggunakan Konektor SQL Databricks untuk Python dengan autentikasi token akses pribadi Azure Databricks, Anda harus terlebih dahulu membuat token akses pribadi Azure Databricks, sebagai berikut:

Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
Klik Pengembang.
Di samping Token akses, klik Kelola.
Klik Buat token baru.
(Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
Klik Buat.
Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.

Catatan

Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.

Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau topik berikut:

Untuk mengautentikasi Konektor SQL Databricks untuk Python, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

DATABRICKS_SERVER_HOSTNAMEatur ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
DATABRICKS_HTTP_PATH, atur ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
DATABRICKS_TOKEN, atur ke token akses pribadi Azure Databricks.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autentikasi mesin-ke-mesin (M2M) OAuth

Konektor SQL Databricks untuk Python versi 2.7.0 ke atas mendukung autentikasi komputer-ke-mesin (M2M) OAuth. Anda juga harus menginstal Databricks SDK untuk Python 0.18.0 atau lebih tinggi (misalnya dengan menjalankan pip install databricks-sdk atau python -m pip install databricks-sdk).

Untuk menggunakan Konektor SQL Databricks untuk Python dengan autentikasi M2M OAuth, Anda harus melakukan hal berikut:

Buat perwakilan layanan Azure Databricks di ruang kerja Azure Databricks Anda, dan buat rahasia OAuth untuk perwakilan layanan tersebut.

Untuk membuat perwakilan layanan dan rahasia OAuth-nya, lihat Mengautentikasi akses ke Azure Databricks dengan perwakilan layanan menggunakan OAuth (OAuth M2M). Catat nilai UUID atau ID Aplikasi perwakilan layanan, dan nilai Rahasia untuk rahasia OAuth perwakilan layanan.
Berikan akses perwakilan layanan tersebut ke kluster atau gudang Anda.

Untuk memberikan akses perwakilan layanan ke kluster atau gudang Anda, lihat Izin komputasi atau Mengelola gudang SQL.

Untuk mengautentikasi Konektor SQL Databricks untuk Python, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

DATABRICKS_SERVER_HOSTNAME atur ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
DATABRICKS_HTTP_PATH, atur ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
DATABRICKS_CLIENT_ID, atur ke nilai UUID atau ID Aplikasi perwakilan layanan.
DATABRICKS_CLIENT_SECRET, atur ke nilai Rahasia untuk rahasia OAuth perwakilan layanan.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Autentikasi token ID Microsoft Entra

Untuk menggunakan Konektor SQL Databricks untuk Python dengan autentikasi token ID Microsoft Entra, Anda harus menyediakan Konektor SQL Databricks untuk Python dengan token ID Microsoft Entra. Untuk membuat token akses ID Microsoft Entra, lakukan hal berikut:

Untuk pengguna Azure Databricks, Anda dapat menggunakan Azure CLI. Lihat Mendapatkan token ID Microsoft Entra untuk pengguna dengan menggunakan Azure CLI.
Untuk perwakilan layanan ID Microsoft Entra, lihat Mendapatkan token akses ID Microsoft Entra dengan Azure CLI. Untuk membuat perwakilan layanan terkelola ID Microsoft Entra, lihat Mengelola perwakilan layanan.

Token ID Microsoft Entra memiliki masa pakai default sekitar 1 jam. Untuk membuat token ID Microsoft Entra baru, ulangi proses ini.

Untuk mengautentikasi Konektor SQL Databricks untuk Python, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

Atur DATABRICKS_SERVER_HOSTNAME ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
Atur DATABRICKS_HTTP_PATH ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
Atur DATABRICKS_TOKEN ke token ID Microsoft Entra.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autentikasi pengguna ke komputer (U2M) OAuth

Konektor SQL Databricks untuk Python versi 2.7.0 ke atas mendukung autentikasi pengguna-ke-mesin (U2M) OAuth. Anda juga harus menginstal Databricks SDK untuk Python 0.19.0 atau lebih tinggi (misalnya dengan menjalankan pip install databricks-sdk atau python -m pip install databricks-sdk).

Untuk mengautentikasi Konektor SQL Databricks untuk Python dengan autentikasi OAuth U2M, gunakan cuplikan kode berikut. Autentikasi OAuth U2M menggunakan masuk dan persetujuan manusia real time untuk mengautentikasi akun pengguna Azure Databricks target. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

Atur DATABRICKS_SERVER_HOSTNAME ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
Atur DATABRICKS_HTTP_PATH ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

Contoh

Contoh kode berikut menunjukkan cara menggunakan Konektor SQL Databricks untuk Python guna mengkueri dan menyisipkan data, mengkueri metadata, mengelola kursor dan koneksi, serta mengonfigurasi pengelogan.

Catatan

Contoh kode berikut menunjukkan cara menggunakan token akses pribadi Azure Databricks untuk autentikasi. Untuk menggunakan jenis autentikasi Azure Databricks lain yang tersedia, lihat Autentikasi.

Contoh kode ini mengambil nilai variabel koneksi server_hostname, http_path, dan access_token dari variabel lingkungan ini:

DATABRICKS_SERVER_HOSTNAME, yang merepresentasikan nilai Nama Host Server dari persyaratan.
DATABRICKS_HTTP_PATH, yang merepresentasikan nilai Jalur HTTP dari persyaratan.
DATABRICKS_TOKEN, yang merepresentasikan token akses Anda dari persyaratan.

Anda dapat menggunakan pendekatan lain untuk mengambil nilai variabel koneksi ini. Menggunakan variabel lingkungan hanyalah satu dari sekian banyak pendekatan.

Data kueri
Sisipkan data
Metadata kueri
Mengelola kursor dan koneksi
Mengelola file dalam volume Katalog Unity
Mengonfigurasi pengelogan

Mengkueri data

Contoh kode berikut ini menunjukkan cara untuk memanggil Konektor SQL Databricks untuk Python guna menjalankan perintah SQL dasar pada kluster atau gudang SQL. Perintah ini mengembalikan dua baris pertama dari trips tabel dalam samples skema nyctaxi katalog.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
    result = cursor.fetchall()

    for row in result:
      print(row)

Menyisipkan data

Contoh berikut menunjukkan cara menyisipkan data dalam jumlah kecil (ribuan baris):

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

    cursor.execute("SELECT * FROM squares LIMIT 10")

    result = cursor.fetchall()

    for row in result:
      print(row)

Untuk data dengan jumlah yang besar, Anda harus terlebih dahulu mengunggah data tersebut ke penyimpanan cloud dan kemudian menjalankan perintah COPY INTO.

Metadata kueri

Ada metode khusus untuk mengambil metadata. Contoh berikut mengambil metadata tentang kolom dalam tabel sampel:

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

Mengelola kursor dan koneksi

Ini adalah praktik terbaik untuk menutup koneksi dan kursor apa pun yang tidak lagi digunakan. Tindakan ini akan membebaskan sumber daya pada kluster Azure Databricks serta gudang SQL Databricks.

Anda dapat menggunakan manajer konteks (sintaks with yang digunakan dalam contoh sebelumnya) untuk mengelola sumber daya, atau secara eksplisit memanggil close:

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Mengelola file dalam volume Katalog Unity

Konektor SQL Databricks memungkinkan Anda menulis file lokal ke volume Unity Catalog, mengunduh file dari volume, dan menghapus file dari volume, seperti yang ditunjukkan dalam contoh berikut:

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allows_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allows_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/temp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

Mengonfigurasi pengelogan

Konektor SQL Databricks menggunakan modul pengelogan standar Python. Anda dapat mengonfigurasi tingkat pengelogan yang mirip dengan berikut ini:

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

Pengujian

Untuk menguji kode Anda, gunakan kerangka kerja pengujian Python seperti pytest. Untuk menguji kode Anda dalam kondisi simulasi tanpa memanggil titik akhir REST API Azure Databricks atau mengubah status akun atau ruang kerja Azure Databricks, Anda dapat menggunakan pustaka tiruan Python seperti unittest.mock.

Misalnya, mengingat file berikut bernama helpers.py yang berisi get_connection_personal_access_token fungsi yang menggunakan token akses pribadi Azure Databricks untuk mengembalikan koneksi ke ruang kerja Azure Databricks, dan select_nyctaxi_trips fungsi yang menggunakan koneksi untuk mendapatkan jumlah baris data yang ditentukan dari trips tabel dalam samples skema nyctaxi katalog:

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
  result: List[Row] = cursor.fetchall()
  return result

Dan diberikan file berikut bernama main.py yang memanggil get_connection_personal_access_token fungsi dan select_nyctaxi_trips :

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

File berikut bernama test_helpers.py menguji apakah select_nyctaxi_trips fungsi mengembalikan respons yang diharapkan. Daripada membuat koneksi nyata ke ruang kerja target, pengujian ini mengejek Connection objek. Pengujian ini juga meniru beberapa data yang sesuai dengan skema dan nilai yang ada dalam data nyata. Pengujian mengembalikan data yang ditidakan melalui koneksi yang ditidakan lalu memeriksa apakah salah satu nilai baris data yang ditidakan cocok dengan nilai yang diharapkan.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

select_nyctaxi_trips Karena fungsi berisi SELECT pernyataan dan oleh karena itu tidak mengubah status trips tabel, tiruan tidak benar-benar diperlukan dalam contoh ini. Namun, tiruan memungkinkan Anda menjalankan pengujian dengan cepat tanpa menunggu koneksi aktual dibuat dengan ruang kerja. Selain itu, mocking memungkinkan Anda menjalankan tes yang disimulasikan beberapa kali untuk fungsi yang mungkin mengubah status tabel, seperti INSERT INTO, UPDATE, dan DELETE FROM.

Paket

databricks-sql-connector

Penggunaan: pip install databricks-sql-connector

Lihat juga databricks-sql-connector di Indeks Paket Python (PyPI).

Modul

databricks.sql

Penggunaan: from databricks import sql

Kelas

Kelas yang dipilih meliputi yang berikut ini:

Kelas
`Connection` Sesi pada sumber daya komputasi Azure Databricks.
`Cursor` Mekanisme untuk melintasi rekaman data.
`Row` Baris data dalam hasil kueri SQL.

`Connection` kelas

Untuk membuat Connection objek, panggil databricks.sql.connect metode dengan parameter berikut:

Parameter
`server_hostname` Jenis: `str` Nama host server kluster atau gudang SQL. Untuk mendapatkan nama host server, lihat petunjuknya di bagian sebelumnya di artikel ini. Parameter ini diperlukan. Contoh: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Jenis: `str` Jalur HTTP kluster atau gudang SQL. Untuk mendapatkan jalur HTTP, lihat petunjuknya di bagian sebelumnya di artikel ini. Parameter ini diperlukan. Contoh: `sql/protocolv1/o/1234567890123456/1234-567890-test123` untuk kluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` untuk gudang SQL.
`access_token`, `auth_type` Jenis: `str` Informasi tentang pengaturan autentikasi Azure Databricks. Untuk detailnya, lihat Autentikasi.
`session_configuration` Jenis: `dict[str, Any]` Kamus parameter konfigurasi sesi Spark. Mengatur konfigurasi sama dengan menggunakan perintah SQL `SET key=val`. Jalankan perintah SQL `SET -v` untuk mendapatkan daftar lengkap konfigurasi yang tersedia. Default ke `None`. Parameter ini bersifat opsional. Contoh: `{"spark.sql.variable.substitute": True}`
`http_headers` Jenis: `List[Tuple[str, str]]]` Pasangan tambahan (kunci, nilai) untuk diatur di header HTTP pada setiap permintaan RPC yang dibuat klien. Penggunaan umum tidak akan mengatur header HTTP tambahan. Default ke `None`. Parameter ini bersifat opsional. Sejak versi 2.0
`catalog` Jenis: `str` Katalog awal yang digunakan untuk koneksi. Didefault ke `None` (dalam hal ini katalog default, biasanya `hive_metastore`, akan digunakan). Parameter ini bersifat opsional. Sejak versi 2.0
`schema` Jenis: `str` Skema awal yang digunakan untuk koneksi. Didefault ke `None` (dalam hal ini katalog default `default` akan digunakan). Parameter ini bersifat opsional. Sejak versi 2.0
`use_cloud_fetch` Jenis: `bool` `True` untuk mengirim permintaan pengambilan langsung ke penyimpanan objek cloud untuk mengunduh potongan data. `False` (default) untuk mengirim permintaan pengambilan langsung ke Azure Databricks. Jika `use_cloud_fetch` diatur ke `True` tetapi akses jaringan diblokir, maka permintaan pengambilan akan gagal. Sejak versi 2.8

Metode yang dipilih Connection meliputi yang berikut ini:

Metode
`close` Menutup sambungan ke database dan merilis semua sumber daya terkait di server. Setiap panggilan tambahan ke sambungan ini akan menampilkan `Error`. Tidak ada parameter. Tidak ada nilai yang ditampilkan.
`cursor` Mengembalikan objek baru `Cursor` yang memungkinkan traversal atas rekaman dalam database. Tidak ada parameter.

`Cursor` kelas

Untuk membuat Cursor objek, panggil Connection metode kelas cursor .

Atribut yang dipilih Cursor meliputi yang berikut ini:

Atribut

Atribut
`arraysize` Digunakan dengan `fetchmany` metode , menentukan ukuran buffer internal, yang juga berapa banyak baris yang benar-benar diambil dari server sekaligus. Nilai defaultnya adalah `10000`. Untuk hasil yang sempit (hasil di mana setiap baris tidak berisi banyak data), Anda harus meningkatkan nilai ini untuk performa yang lebih baik. Akses baca-tulis.
`description` Berisi `list` objek `tuple` Python. Masing-masing objek `tuple` ini berisi 7 nilai, dengan 2 item pertama dari setiap objek `tuple` yang berisikan informasi yang menggambarkan kolom hasil tunggal sebagai berikut: - `name`: Nama kolom. - `type_code`: Untai (karakter) yang mewakili jenis kolom. Misalnya, kolom bilangan bulat akan memiliki kode jenis `int`. Sisa 5 item dari setiap 7 item objek `tuple` tidak diimplementasikan, dan nilainya tidak ditentukan. Mereka biasanya akan dikembalikan sebagai 4 `None` nilai diikuti oleh satu `True` nilai. Akses baca-saja.

arraysize

Digunakan dengan fetchmany metode , menentukan ukuran buffer internal, yang juga berapa banyak baris yang benar-benar diambil dari server sekaligus. Nilai defaultnya adalah 10000. Untuk hasil yang sempit (hasil di mana setiap baris tidak berisi banyak data), Anda harus meningkatkan nilai ini untuk performa yang lebih baik.

Akses baca-tulis.

description

Berisi list objek tuple Python. Masing-masing objek tuple ini berisi 7 nilai, dengan 2 item pertama dari setiap objek tuple yang berisikan informasi yang menggambarkan kolom hasil tunggal sebagai berikut:

- name: Nama kolom.
- type_code: Untai (karakter) yang mewakili jenis kolom. Misalnya, kolom bilangan bulat akan memiliki kode jenis int.

Sisa 5 item dari setiap 7 item objek tuple tidak diimplementasikan, dan nilainya tidak ditentukan. Mereka biasanya akan dikembalikan sebagai 4
None nilai diikuti oleh satu True nilai.

Akses baca-saja.

Metode yang dipilih Cursor meliputi yang berikut ini:

Metode
`cancel` Mengganggu berjalannya kueri atau perintah database apa pun yang telah dimulai kursor. Untuk merilis sumber daya terkait di server, panggil `close` metode setelah memanggil `cancel` metode . Tidak ada parameter. Tidak ada nilai yang ditampilkan.
`close` Menutup kursor dan merilis sumber daya terkait di server. Tindakan menutup kursor yang sudah tertutup dapat menampilkan kesalahan. Tidak ada parameter. Tidak ada nilai yang ditampilkan.
`execute` Menyiapkan lalu menjalankan kueri atau perintah database. Tidak ada nilai yang ditampilkan. Parameter: `operation` Jenis: `str` Kueri atau perintah untuk menyiapkan lalu menjalankan. Parameter ini diperlukan. Contoh tanpa parameter `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Contoh dengan parameter `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Jenis: kamus Urutan parameter yang akan digunakan dengan parameter `operation`. Parameter ini bersifat opsional. Default adalah `None`.
`executemany` Menyiapkan dan kemudian menjalankan kueri atau perintah database dengan menggunakan semua urutan parameter dalam argumen `seq_of_parameters`. Hanya hasil akhir saja yang akan dipertahankan. Tidak ada nilai yang ditampilkan. Parameter: `operation` Jenis: `str` Kueri atau perintah untuk menyiapkan lalu menjalankan. Parameter ini diperlukan. `seq_of_parameters` Jenis: `list` dari `dict` Urutan banyak set nilai parameter yang akan digunakan dengan parameter `operation`. Parameter ini diperlukan.
`catalogs` Jalankan kueri metadata tentang katalog. Hasil yang sebenarnya kemudian harus diambil dengan menggunakan `fetchmany` atau `fetchall`. Bidang yang penting dalam tataan hasil meliputi: - Nama bidang: `TABLE_CAT`. Ketik: `str`. Nama katalog. Tidak ada parameter. Tidak ada nilai yang ditampilkan. Sejak versi 1.0
`schemas` Jalankan kueri metadata tentang skema. Hasil yang sebenarnya kemudian harus diambil dengan menggunakan `fetchmany` atau `fetchall`. Bidang yang penting dalam tataan hasil meliputi: - Nama bidang: `TABLE_SCHEM`. Ketik: `str`. Nama skema. - Nama bidang: `TABLE_CATALOG`. Ketik: `str`. Katalog tempat skema berada. Tidak ada nilai yang ditampilkan. Sejak versi 1.0 Parameter: `catalog_name` Jenis: `str` Nama katalog yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `schema_name` Jenis: `str` Nama skema yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional.
`tables` Jalankan kueri metadata tentang tabel dan tampilan. Hasil yang sebenarnya kemudian harus diambil dengan menggunakan `fetchmany` atau `fetchall`. Bidang yang penting dalam tataan hasil meliputi: - Nama bidang: `TABLE_CAT`. Ketik: `str`. Katalog tempat tabel berada. - Nama bidang: `TABLE_SCHEM`. Ketik: `str`. Skema tempat tabel berada. - Nama bidang: `TABLE_NAME`. Ketik: `str`. Nama tabel. - Nama bidang: `TABLE_TYPE`. Ketik: `str`. Jenis relasi, misalnya `VIEW` atau `TABLE` (berlaku untuk Databricks Runtime 10.4 LTS dan di atasnya serta untuk Databricks SQL; versi sebelumnya dari Databricks Runtime mengembalikan string kosong). Tidak ada nilai yang ditampilkan. Sejak versi 1.0 Parameter `catalog_name` Jenis: `str` Nama katalog yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `schema_name` Jenis: `str` Nama skema yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `table_name` Jenis: `str` Nama tabel yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `table_types` Jenis: `List[str]` Daftar jenis tabel yang cocok, misalnya `TABLE` atau `VIEW`. Parameter ini bersifat opsional.
`columns` Jalankan kueri metadata tentang kolom. Hasil yang sebenarnya kemudian harus diambil dengan menggunakan `fetchmany` atau `fetchall`. Bidang yang penting dalam tataan hasil meliputi: - Nama bidang: `TABLE_CAT`. Ketik: `str`. Katalog tempat kolom berada. - Nama bidang: `TABLE_SCHEM`. Ketik: `str`. Skema tempat kolom berada. - Nama bidang: `TABLE_NAME`. Ketik: `str`. Nama tabel tempat kolom berada. - Nama bidang: `COLUMN_NAME`. Ketik: `str`. Nama kolom. Tidak ada nilai yang ditampilkan. Sejak versi 1.0 Parameter: `catalog_name` Jenis: `str` Nama katalog yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `schema_name` Jenis: `str` Nama skema yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `table_name` Jenis: `str` Nama tabel yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional. `column_name` Jenis: `str` Nama kolom yang akan diambil informasinya. Karakter `%` diinterpretasikan sebagai karakter kartubebas. Parameter ini bersifat opsional.
`fetchall` Mendapatkan semua (atau seluruh sisa) baris kueri. Tidak ada parameter. Mengembalikan semua (atau semua baris kueri yang tersisa) sebagai Python `list` dari `Row` Objek. `Error` Melemparkan jika panggilan sebelumnya ke `execute` metode tidak mengembalikan data apa pun atau belum ada `execute` panggilan yang dilakukan.
`fetchmany` Mendapatkan baris kueri berikutnya. Mengembalikan hingga `size` (atau `arraysize` atribut jika `size` tidak ditentukan) dari baris kueri berikutnya sebagai Python `list` `Row` objek. Jika ada lebih sedikit dari `size` baris yang tersisa untuk diambil, semua baris yang tersisa akan dikembalikan. `Error` Melemparkan jika panggilan sebelumnya ke `execute` metode tidak mengembalikan data apa pun atau belum ada `execute` panggilan yang dilakukan. Parameter: `size` Jenis: `int` Jumlah baris berikutnya yang akan didapatkan. Parameter ini bersifat opsional. Jika tidak ditentukan, nilai atribut `arraysize` digunakan. Contoh: `cursor.fetchmany(10)`
`fetchone` Mendapatkan baris berikutnya dari himpunan data. Tidak ada parameter. Mengembalikan baris berikutnya dari himpunan data sebagai urutan tunggal sebagai Python `tuple` objek, atau mengembalikan `None` jika tidak ada lagi data yang tersedia. `Error` Melemparkan jika panggilan sebelumnya ke `execute` metode tidak mengembalikan data apa pun atau belum ada `execute` panggilan yang dilakukan.
`fetchall_arrow` Mendapatkan semua (atau seluruh sisa) baris kueri, sebagai objek `Table` PyArrow. Kueri yang mengembalikan data dalam jumlah yang sangat besar harus digunakan `fetchmany_arrow` sebagai gantinya untuk mengurangi konsumsi memori. Tidak ada parameter. Mengembalikan semua (atau semua sisa) baris kueri sebagai tabel PyArrow. `Error` Melemparkan jika panggilan sebelumnya ke `execute` metode tidak mengembalikan data apa pun atau belum ada `execute` panggilan yang dilakukan. Sejak versi 2.0
`fetchmany_arrow` Mendapatkan baris kueri berikutnya sebagai objek PyArrow `Table`. Mengembalikan hingga `size` argumen (atau `arraysize` atribut jika `size` tidak ditentukan) dari baris kueri berikutnya sebagai Python PyArrow `Table` benda. `Error` Melemparkan jika panggilan sebelumnya ke `execute` metode tidak mengembalikan data apa pun atau belum ada `execute` panggilan yang dilakukan. Sejak versi 2.0 Parameter: `size` Jenis: `int` Jumlah baris berikutnya yang akan didapatkan. Parameter ini bersifat opsional. Jika tidak ditentukan, nilai atribut `arraysize` digunakan. Contoh: `cursor.fetchmany_arrow(10)`

`Row` kelas

Kelas baris adalah struktur data seperti tuple yang mewakili baris hasil individual. Jika baris berisi kolom bernama "my_column", Anda dapat mengakses bidang "my_column" row melalui row.my_column. Anda juga dapat menggunakan indeks numerik untuk mengakses bidang, misalnya row[0]. Jika nama kolom tidak diizinkan sebagai nama metode atribut (misalnya, nama dimulai dengan digit), Anda dapat mengakses bidang sebagai row["1_my_column"].

Sejak versi 1.0

Metode yang dipilih Row meliputi:

| asDict

Mengembalikan representasi kamus baris, yang diindeks berdasarkan nama bidang. Jika ada nama bidang duplikat, salah satu bidang duplikat (hanya satu saja) akan ditampilkan dalam kamus. Bidang duplikat mana yang ditampilkan tidak ditentukan.

Tidak ada parameter.

Menampilkan dict bidang. |

Konversi jenis

Tabel berikut memetakan jenis data SQL Apache Spark ke jenis data Python yang setara.

Jenis data SQL Apache Spark	Jenis data Python
`array`	`numpy.ndarray`
`bigint`	`int`
`binary`	`bytearray`
`boolean`	`bool`
`date`	`datetime.date`
`decimal`	`decimal.Decimal`
`double`	`float`
`int`	`int`
`map`	`str`
`null`	`NoneType`
`smallint`	`int`
`string`	`str`
`struct`	`str`
`timestamp`	`datetime.datetime`
`tinyint`	`int`

Pemecahan Masalah

pesan `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Masalah: Saat Anda menjalankan kode Anda, muncul pesan yang mirip dengan Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Kemungkinan penyebab: Nilai yang diteruskan ke access_token bukanlah token akses pribadi Azure Databricks yang valid.

Saran perbaikan: Periksa apakah nilai yang diteruskan ke access_token sudah benar dan coba lagi.

pesan `gaierror(8, 'nodename nor servname provided, or not known')`

Masalah: Saat Anda menjalankan kode Anda, muncul pesan yang mirip dengan Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Kemungkinan penyebab: Nilai yang diteruskan ke server_hostname bukanlah nama host yang benar.

Saran perbaikan: Periksa apakah nilai yang diteruskan ke server_hostname sudah benar dan coba lagi.

Untuk informasi selengkapnya tentang menemukan nama host server, lihat Mendapatkan detail koneksi untuk sumber daya komputasi Azure Databricks.

pesan `IpAclError`

Masalah: Saat menjalankan kode, Anda akan melihat pesan Error during request to server: IpAclValidation saat mencoba menggunakan konektor di buku catatan Azure Databricks.

Kemungkinan penyebab: Anda mungkin telah mengaktifkan daftar IP yang diizinkan (IP allow listing) untuk ruang kerja Azure Databricks. Dengan daftar IP yang diizinkan, sambungan dari kluster Spark yang kembali ke sarana kontrol tidak diizinkan secara default.

Perbaikan yang disarankan: Minta administrator Anda untuk menambahkan subnet bidang komputasi ke daftar izin IP.

Sumber Daya Tambahan:

Untuk informasi selengkapnya, lihat:

Konektor SQL Databricks untuk repositori Python di GitHub
Jenis data
Jenis Bawaan (untuk bool, bytearray, float, int, dan str) di situs web Python
tanggalwaktu (untuk datetime.date dan datatime.datetime) di situs web Python
desimal (untuk decimal.Decimal) di situs web Python
Konstanta Bawaan (untuk NoneType) di situs web Python

Bagikan melalui

Konektor Databricks SQL untuk Python

Persyaratan

Memulai

Kluster

Gudang SQL

Autentikasi

Autentikasi token akses pribadi Databricks

Autentikasi mesin-ke-mesin (M2M) OAuth

Autentikasi token ID Microsoft Entra

Autentikasi pengguna ke komputer (U2M) OAuth

Contoh

Mengkueri data

Menyisipkan data

Metadata kueri

Mengelola kursor dan koneksi

Mengelola file dalam volume Katalog Unity

Mengonfigurasi pengelogan

Pengujian

Referensi API

Paket

Modul

Kelas

`Connection` kelas

`Cursor` kelas

`Row` kelas

Konversi jenis

Pemecahan Masalah

pesan `tokenAuthWrapperInvalidAccessToken: Invalid access token`

pesan `gaierror(8, 'nodename nor servname provided, or not known')`

pesan `IpAclError`

Sumber Daya Tambahan:

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Konektor Databricks SQL untuk Python

Persyaratan

Memulai

Kluster

Gudang SQL

Autentikasi

Autentikasi token akses pribadi Databricks

Autentikasi mesin-ke-mesin (M2M) OAuth

Autentikasi token ID Microsoft Entra

Autentikasi pengguna ke komputer (U2M) OAuth

Contoh

Mengkueri data

Menyisipkan data

Metadata kueri

Mengelola kursor dan koneksi

Mengelola file dalam volume Katalog Unity

Mengonfigurasi pengelogan

Pengujian

Referensi API

Paket

Modul

Kelas

Connection kelas

Cursor kelas

Row kelas

Konversi jenis

Pemecahan Masalah

pesan tokenAuthWrapperInvalidAccessToken: Invalid access token

pesan gaierror(8, 'nodename nor servname provided, or not known')

pesan IpAclError

Sumber Daya Tambahan:

Saran dan Komentar

Sumber Daya Tambahan:

`Connection` kelas

`Cursor` kelas

`Row` kelas

pesan `tokenAuthWrapperInvalidAccessToken: Invalid access token`

pesan `gaierror(8, 'nodename nor servname provided, or not known')`

pesan `IpAclError`