Bagikan melalui

Konektor Databricks SQL untuk Python

Konektor SQL Databricks untuk Python adalah pustaka Python yang memungkinkan Anda menggunakan kode Python untuk menjalankan perintah SQL pada komputasi serba guna 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 SPESIFIKASI API Database PEP 249 – Python v2.0.

Penting

Konektor SQL Databricks untuk Python versi 3.0.0 ke atas mendukung eksekusi kueri berparameter asli, yang mencegah injeksi SQL dan dapat meningkatkan performa kueri. Versi sebelumnya menggunakan eksekusi berparameter sebaris, yang tidak aman dari injeksi SQL dan memiliki kelemahan lain. Untuk informasi selengkapnya, lihat Menggunakan Parameter Asli.

Konektor SQL Databricks untuk Python juga mendukung dialek SQLAlchemy untuk Azure Databricks, tetapi harus diinstal untuk menggunakan fitur-fitur ini. Lihat Menggunakan SQLAlchemy dengan Azure Databricks.

Persyaratan

  • Mesin pengembangan yang menjalankan Python 3.8 ke atas.
  • 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.
  • Komputer serbaguna atau gudang data SQL yang ada.

Mulai

  1. Instal Konektor SQL Databricks untuk Python. PyArrow adalah dependensi opsional dari Konektor SQL Databricks untuk Python dan tidak diinstal secara default dalam versi 4.0.0 ke atas konektor. Jika PyArrow tidak diinstal, fitur seperti CloudFetch dan fungsionalitas Apache Arrow lainnya tidak tersedia, yang dapat memengaruhi performa untuk data dalam volume besar.

    • Untuk memasang lean connector, gunakan:

      pip install databricks-sql-connector

    • Untuk menginstal konektor lengkap, termasuk PyArrow, gunakan:

      pip install databricks-sql-connector[pyarrow]

  2. Kumpulkan informasi berikut untuk komputasi semua tujuan atau gudang SQL yang ingin Anda gunakan:

    Komputasi serba guna

    • Nama host server komputasi semua tujuan. Anda bisa mendapatkan ini dari nilai Nama Host Server di tab Opsi > Tingkat Lanjut JDBC/ODBC untuk komputasi serba guna Anda.
    • Jalur HTTP dari komputasi serbaguna. Anda bisa mendapatkan ini dari nilai Jalur HTTP di tab Opsi > Lanjutan JDBC/ODBC untuk komputasi serba guna Anda.

    Catatan

    Konektor SQL tidak mendukung koneksi ke komputasi pekerjaan.

    Gudang SQL

    • Nama host server gudang SQL. Anda bisa mendapatkan ini dari nilai Nama Host Server di tab Detail Koneksi untuk gudang SQL Anda.
    • Jalur HTTP dari SQL warehouse. Anda bisa mendapatkan ini dari nilai Jalur HTTP di tab Detail Koneksi untuk gudang SQL Anda.

Autentikasi

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

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. Untuk melakukannya, ikuti langkah-langkah dalam Membuat token akses pribadi untuk pengguna ruang kerja.

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 komputasi umum atau penyimpanan SQL Anda.
  • DATABRICKS_HTTP_PATH, diatur ke nilai Jalur HTTP untuk komputasi serbaguna 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:

  1. 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 Mengotorisasi akses perwakilan layanan ke Azure Databricks dengan OAuth. Catat nilai UUID atau ID Aplikasi dari perwakilan layanan, serta nilai Rahasia untuk rahasia OAuth perwakilan layanan.

  2. Berikan akses utama layanan tersebut ke komputasi atau gudang serba guna Anda.

    Untuk memberikan akses utama layanan ke komputasi atau gudang serba guna 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 diatur ke nilai Nama Host Server untuk komputasi serbaguna atau gudang data SQL Anda.
  • DATABRICKS_HTTP_PATH, diatur ke nilai Jalur HTTP untuk komputasi serbaguna atau gudang SQL Anda.
  • DATABRICKS_CLIENT_ID, atur ke nilai UUID atau ID Aplikasi perwakilan layanan.
  • DATABRICKS_CLIENT_SECRET, tetapkan ke nilai Rahasia untuk kunci rahasia OAuth dari 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 Entra ID Microsoft

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:

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 Hostname Server untuk komputasi serba guna atau gudang SQL.
  • Setel DATABRICKS_HTTP_PATH ke nilai Jalur HTTP untuk komputasi serbaguna atau penyimpanan SQL Anda.
  • Atur DATABRICKS_TOKEN menjadi 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 proses masuk dan persetujuan real-time oleh manusia untuk mengesahkan akun pengguna target Azure Databricks. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

  • Atur DATABRICKS_SERVER_HOSTNAME ke nilai Hostname Server untuk komputasi serba guna atau gudang SQL.
  • Setel DATABRICKS_HTTP_PATH ke nilai Jalur HTTP untuk komputasi serbaguna atau penyimpanan 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 untuk mengkueri dan menyisipkan data, metadata kueri, mengelola kursor dan koneksi, mengelola file di Katalog Unity, dan mengonfigurasi pengelogan.

Catatan

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

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

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

Atur User-Agent

Contoh kode berikut menunjukkan cara mengatur product_name aplikasi User-Agent untuk pelacakan penggunaan.

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"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

Menjalankan kueri data

Contoh kode berikut menunjukkan cara memanggil Konektor SQL Databricks untuk Python untuk menjalankan perintah SQL dasar pada komputasi serba guna 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)

Tag kueri

Penting

Fitur ini ada di Pratinjau Privat. Untuk meminta akses, hubungi tim akun Anda.

Contoh berikut menunjukkan cara melampirkan tag kunci-nilai ke kueri SQL Anda untuk tujuan pelacakan dan analitik. Tag kueri muncul dalam system.query.history tabel.

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"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        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)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    cursor.execute("SELECT * FROM squares LIMIT ?", [10])

    result = cursor.fetchall()

    for row in result:
      print(row)

Untuk data dalam jumlah besar, Anda harus terlebih dahulu mengunggah data ke penyimpanan cloud lalu 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. Ini membebaskan sumber daya pada komputasi serbaguna Azure Databricks dan gudang Databricks SQL.

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_allowed_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_allowed_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 '/tmp/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. Contoh berikut mengonfigurasi tingkat pengelogan dan menghasilkan log debug:

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 membuat 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 skema samples dari katalog nyctaxi.

# 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("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

Dan diberikan file berikut bernama main.py yang memanggil fungsi get_connection_personal_access_token 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 meniru objek Connection. Pengujian ini juga meniru beberapa data yang sesuai dengan skema dan nilai yang ada dalam data nyata. Pengujian mengembalikan data yang di-mock melalui koneksi yang di-mock, lalu memeriksa apakah salah satu nilai dari baris data yang di-mock 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

Karena fungsi select_nyctaxi_trips berisi pernyataan SELECT dan oleh karena itu tidak mengubah status tabel trips, tiruan tidak sepenuhnya diperlukan dalam contoh ini. Namun, mocking memungkinkan Anda menjalankan pengujian dengan cepat tanpa menunggu koneksi sebenarnya 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.

Referensi API

Bagian ini berisi referensi API untuk databricks-sql-connector paket. Lihat databricks-sql-connector di Indeks Paket Python (PyPI).

Modul

Modul databricks.sqldatabricks-sql-connector paket berisi metode untuk menginisialisasi koneksi ke gudang SQL.

metode menghubungkan

Menginisialisasi koneksi ke gudang SQL. Mengembalikan objek Koneksi.

Pengaturan Tipe Description
server_hostname str Dibutuhkan. Nama host server untuk komputasi semua tujuan atau gudang SQL, misalnya adb-1234567890123456.7.azuredatabricks.net.
Untuk mendapatkan nama host server, lihat instruksi di Memulai.
http_path str Dibutuhkan. Jalur HTTP dari komputasi semua tujuan atau gudang SQL, misalnya sql/protocolv1/o/1234567890123456/1234-567890-test123 untuk komputasi semua tujuan atau /sql/1.0/warehouses/a1b234c567d8e9fa untuk gudang SQL.
Untuk mendapatkan jalur HTTP, lihat instruksi di Memulai.
access_token auth_type credentials_provider password username str Informasi tentang pengaturan autentikasi Azure Databricks. Untuk detailnya, lihat Autentikasi.
session_configuration dict[str, Any] Kamus konfigurasi parameter sesi Spark. Mengatur konfigurasi sama dengan menggunakan perintah SQL SET key=val. Jalankan perintah SQL SET -v untuk mendapatkan daftar lengkap konfigurasi yang tersedia. Bawaan ke None.
Contoh: {"spark.sql.variable.substitute": True}
http_headers List[Tuple[str, str]]] Optional. Pasangan tambahan (kunci, nilai) yang akan diatur di header HTTP pada setiap permintaan RPC yang dibuat klien. Penggunaan umum tidak akan mengatur header HTTP tambahan. Bawaan ke None.
catalog str Optional. Katalog awal yang digunakan untuk koneksi. Default ke None (dalam hal ini katalog default, biasanya hive_metastore akan digunakan).
schema str Optional. Skema awal yang digunakan untuk koneksi. Diatur ke None (dalam hal ini, skema bawaan default akan digunakan).
Sejak versi 2.0
use_cloud_fetch bool Optional. Apakah akan mengirim permintaan pengambilan langsung ke penyimpanan objek cloud untuk mengunduh potongan data. Bawaan ke True. Atur ke False 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
user_agent_entry str Optional. Entri User-Agent untuk disertakan dalam header permintaan HTTP untuk pelacakan penggunaan. Bawaan ke PyDatabricksSqlConnector.

Connection kelas

Mewakili koneksi ke komputasi atau gudang SQL.

Metode

Kelas ini Connection menyediakan metode berikut.

Metode Description
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 dikembalikan.
cursor Mengembalikan objek Kursor baru yang memungkinkan penelusuran melalui rekaman-rekaman di dalam basis data.
Tidak ada parameter.

Cursor kelas

Mewakili mekanisme untuk melintasi rekaman data.

Untuk membuat Cursor objek, panggil cursor metode kelas Koneksi.

Atribut

Atribut yang dipilih Cursor meliputi yang berikut ini:

Attribute Description
arraysize Digunakan dengan metode fetchmany, menentukan ukuran buffer internal, yang juga menunjukkan berapa banyak baris yang benar-benar diambil dari server pada saat yang sama. 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 Terdiri dari list Python tuple objek. 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 ini.
  • type_code: String 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. Nilai biasanya akan dikembalikan sebagai 4 None nilai diikuti oleh satu True nilai. Akses baca saja.

Metode

Metode yang dipilih Cursor meliputi yang berikut ini:

Metode Description
cancel Menghentikan pelaksanaan kueri atau perintah basis data apa pun yang telah dimulai oleh kursor. Untuk merilis sumber daya terkait di server, panggil close metode setelah memanggil cancel metode .
Tidak ada parameter.
Tidak ada nilai yang dikembalikan.
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 dikembalikan.
execute Menyiapkan lalu menjalankan kueri atau perintah database.
Parameter:
  • operation:Diperlukan. Kueri atau perintah untuk dipersiapkan dan kemudian dijalankan. Jenis: str Contoh tanpa parameters parameter: cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2') Contoh dengan parameters parameter (menggunakan parameter posisi asli): cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])
  • parameters: Opsional. Urutan parameter yang akan digunakan dengan parameter operation. Default adalah None. Jenis: dictionary

Tidak ada nilai yang dikembalikan.
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.
Parameter:
  • operation:Diperlukan. Kueri atau perintah untuk dipersiapkan dan kemudian dijalankan. Jenis: str
  • seq_of_parameters:Diperlukan. Urutan banyak set nilai parameter untuk digunakan dengan operation parameter . Jenis: list dari dict

Tidak ada nilai yang dikembalikan.
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. Nama dari katalog Jenis: str

Tidak ada parameter.
Tidak ada nilai yang dikembalikan.
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. Nama skema. Jenis: str
  • Nama bidang: TABLE_CATALOG. Katalog tempat skema berada. Jenis: str

Parameter:
  • catalog_name: Opsional. Nama katalog yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • schema_name: Opsional. Nama skema yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str

Tidak ada nilai yang dikembalikan.
Sejak versi 1.0
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. Katalog tempat tabel berada. Jenis: str
  • Nama bidang: TABLE_SCHEM. Skema tempat tabel berada. Jenis: str
  • Nama bidang: TABLE_NAME. Nama dari tabel tersebut. Jenis: str
  • Nama bidang: TABLE_TYPE. 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). Jenis: str

Parameter:
  • catalog_name: Opsional. Nama katalog yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • schema_name: Opsional. Nama skema yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • table_name: Opsional. Nama tabel yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • table_types: Opsional. Daftar jenis tabel yang cocok, misalnya TABLE atau VIEW. Jenis: List[str]

Tidak ada nilai yang dikembalikan.
Sejak versi 1.0
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. Katalog tempat kolom berada. Jenis: str
  • Nama bidang: TABLE_SCHEM. Skema tempat kolom berada. Jenis: str
  • Nama bidang: TABLE_NAME. Nama tabel tempat kolom berada. Jenis: str
  • Nama bidang: COLUMN_NAME. Nama kolom. Jenis: str

Parameter:
  • catalog_name: Opsional. Nama katalog yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • schema_name: Opsional. Nama skema yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • table_name: Opsional. Nama tabel yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str
  • column_name: Opsional. Nama kolom yang akan diambil informasinya. Karakter % diinterpretasikan sebagai pengganti. Jenis: str

Tidak ada nilai yang dikembalikan.
Sejak versi 1.0
fetchall Mendapatkan semua (atau seluruh sisa) baris kueri.
Tidak ada parameter.
Mengembalikan semua (atau semua baris dari kueri yang tersisa) sebagai objek Python listRow.
Jika panggilan sebelumnya ke Error metode tidak mengembalikan data apa pun atau execute panggilan belum dilakukan, maka akan melemparkan execute.
fetchmany Mendapatkan baris-baris berikutnya dari sebuah kueri.
Parameter:
  • size: Opsional. Jumlah baris berikutnya yang akan didapatkan. Jika tidak ditentukan, nilai atribut arraysize digunakan. Ketik: int. Contoh: cursor.fetchmany(10)

Mengembalikan hingga size (atau atribut arraysize jika size tidak ditentukan) dari baris berikutnya dari sebuah kueri berupa objek list Python.
Jika ada lebih sedikit dari size baris yang tersisa untuk diambil, semua baris yang tersisa akan dikembalikan.
Jika panggilan sebelumnya ke Error metode tidak mengembalikan data apa pun atau execute panggilan belum dilakukan, maka akan melemparkan execute.
fetchone Mendapatkan baris berikutnya dari himpunan data.
Tidak ada parameter.
Mengembalikan baris berikutnya dari himpunan data sebagai urutan tunggal sebagai objek Python tuple , atau mengembalikan None jika tidak ada lagi data yang tersedia.
Jika panggilan sebelumnya ke Error metode tidak mengembalikan data apa pun atau execute panggilan belum dilakukan, maka akan melemparkan execute.
fetchall_arrow Mendapatkan semua baris (atau seluruh yang tersisa) dari sebuah kueri, sebagai objek PyArrow Table. 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.
Jika panggilan sebelumnya ke Error metode tidak mengembalikan data apa pun atau execute panggilan belum dilakukan, maka akan melemparkan execute.
Sejak versi 2.0
fetchmany_arrow Memperoleh baris-baris berikutnya dari kueri sebagai objek PyArrow Table.
Parameter:
  • size: Opsional. Jumlah baris berikutnya yang akan didapatkan. Jika tidak ditentukan, nilai atribut arraysize digunakan. Ketik: int. Contoh: cursor.fetchmany_arrow(10)

Mengembalikan data hingga size argumen (atau arraysize atribut jika size tidak ditentukan) dari baris-baris berikut dalam kueri sebagai objek Python PyArrow Table.
Jika panggilan sebelumnya ke Error metode tidak mengembalikan data apa pun atau execute panggilan belum dilakukan, maka akan melemparkan execute.
Sejak versi 2.0

Row kelas

Kelas baris adalah struktur data seperti tuple yang mewakili baris hasil individual dalam hasil kueri SQL. 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:

Metode

Metode Description
asDict Mengembalikan bentuk kamus dari 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 dikembalikan tidak ditentukan.

Konversi tipe atau 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

Koleksi telemetri

Konektor SQL Databricks untuk Python mengumpulkan data telemetri untuk membantu Azure Databricks meningkatkan keandalan dan memecahkan masalah. Telemetri diaktifkan secara default dan mengumpulkan data operasional berikut:

  • Detail lingkungan klien, seperti versi driver, runtime Python, dan sistem operasi
  • Konfigurasi koneksi driver (tidak termasuk informasi identitas pribadi)
  • Pengukuran latensi operasi
  • Format hasil eksekusi, seperti JSON sebaris atau Apache Arrow
  • Jenis operasi, seperti eksekusi kueri, kueri metadata, atau operasi volume
  • Data klasifikasi kesalahan
  • Jumlah Percobaan Ulang

Penting

Azure Databricks tidak mengumpulkan konten kueri, hasil kueri, atau informasi pengidentifikasi pribadi (PII) apa pun melalui telemetri.

Untuk menonaktifkan koleksi telemetri, atur parameter ke enable_telemetry0 saat membuat koneksi.

Pemecahan Masalah

pesan tokenAuthWrapperInvalidAccessToken: Invalid access token

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

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

Perbaikan yang disarankan: Periksa apakah nilai yang diteruskan access_token sudah benar dan coba lagi.

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

Masalah: Saat Anda menjalankan kode, Anda akan melihat 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 bukan nama host yang benar.

Perbaikan yang disarankan: Periksa apakah nilai yang diteruskan 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 mengaktifkan daftar izin IP untuk ruang kerja Azure Databricks. Dengan daftar IP yang diizinkan, sambungan dari kluster Spark kembali ke lapisan kendali 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:

  • Last updated on