Bagikan melalui

Konektor Databricks SQL untuk Python

  • Artikel

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

    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:

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:

  1. Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
  2. Klik Pengembang.
  3. Di samping Token akses, klik Kelola.
  4. Klik Buat token baru.
  5. (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).
  6. Klik Buat.
  7. 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 berikut ini:

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:

  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 Menggunakan perwakilan layanan untuk mengautentikasi dengan Azure Databricks. Catat nilai UUID atau ID Aplikasi perwakilan layanan, dan nilai Rahasia untuk rahasia OAuth perwakilan layanan.

  2. 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 (sebelumnya Azure Active Directory)

Untuk menggunakan Konektor SQL Databricks untuk Python dengan autentikasi token ID Microsoft Entra (sebelumnya Azure Active Directory), 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 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.

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.

Referensi API

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
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: