Python için Databricks SQL Bağlayıcısı

Python için Databricks SQL Bağlayıcısı, Azure Databricks çok amaçlı işlem ve Databricks SQL ambarlarında SQL komutlarını çalıştırmak için Python kodunu kullanmanıza olanak tanıyan bir Python kitaplığıdır. Python için Databricks SQL Bağlayıcısı'nı ayarlamak ve kullanmak , pyodbc gibi benzer Python kitaplıklarından daha kolaydır. Bu kitaplık , PEP 249 – Python Veritabanı API Belirtimi v2.0'a uyar.

Önemli

Python sürüm 3.0.0 ve üzeri için Databricks SQL Bağlayıcısı, SQL eklemesini engelleyen ve sorgu performansını geliştirebilen yerel parametreli sorgu yürütmeyi destekler. Önceki sürümler SQL eklemesinden güvenli olmayan ve diğer dezavantajları olan satır içi parametreli yürütmeyi kullanıyordu. Daha fazla bilgi için bkz. Yerel Parametreleri Kullanma.

Python için Databricks SQL Bağlayıcısı, Azure Databricks için SQLAlchemy diyalektini de destekler, ancak bu özellikleri kullanmak için yüklenmesi gerekir. Bkz. Azure Databricks ile SQLAlchemy kullanma.

Gereksinimler

• Python 3.8 ve üzerini çalıştıran bir geliştirme makinesi.
• Databricks, Venv tarafından sağlanan ve Python ile birlikte gelenler gibi Python sanal ortamlarını kullanmanızı önerir. Sanal ortamlar, Python'ın doğru sürümlerini ve Python için Databricks SQL Bağlayıcısı'nı birlikte kullandığınızdan emin olmanıza yardımcı olur. Sanal ortamların ayarlanması ve kullanılması bu makalenin kapsamı dışındadır. Daha fazla bilgi için bkz. Sanal ortam oluşturma.
• Var olan bir çok amaçlı işlem veya SQL ambarı.

Kullanmaya başlama

1. Python için Databricks SQL Bağlayıcısı'nı yükleyin. PyArrow , Python için Databricks SQL Bağlayıcısı'nın isteğe bağlı bir bağımlılığıdır ve bağlayıcının 4.0.0 ve üzeri sürümlerinde varsayılan olarak yüklenmez. PyArrow yüklü değilse CloudFetch ve diğer Apache Arrow işlevleri gibi özellikler kullanılamaz ve bu da büyük hacimli verilerin performansını etkileyebilir.

   • Yalın bağlayıcıyı yüklemek için şunu kullanın:

     pip install databricks-sql-connector
     

   • PyArrow da dahil olmak üzere bağlayıcının tamamını yüklemek için şunu kullanın:

     pip install databricks-sql-connector[pyarrow]
     

2. Kullanmak istediğiniz çok amaçlı işlem veya SQL ambarı için aşağıdaki bilgileri toplayın:

   Çok amaçlı işlem

   • Çok amaçlı işlem için sunucu ana bilgisayar adı. Bunu, çok amaçlı işlem için sekmesindeki > değerinden alabilirsiniz.
   • Çok amaçlı hesaplamanın HTTP yolu. Bunu, çok amaçlı işlem için sekmesindeki > değerinden alabilirsiniz.

   Not

   SQL bağlayıcısı, iş yükü hesaplamasına bağlanmayı desteklemez.

   SQL ambarı

   • SQL ambarının sunucu adı. Bunu SQL ambarınızın Bağlantı Ayrıntıları sekmesindeki Sunucu Ana Bilgisayar Adı değerinden alabilirsiniz.
   • SQL ambarının HTTP yolu. Bunu SQL ambarınızın Bağlantı Ayrıntıları sekmesindeki HTTP Yolu değerinden alabilirsiniz.

Kimlik Doğrulaması

Python için Databricks SQL Bağlayıcısı aşağıdaki Azure Databricks kimlik doğrulama türlerini destekler:

• Databricks kişisel erişim anahtarı kimlik doğrulaması
• Microsoft Entra Id belirteci kimlik doğrulaması
• OAuth makineden makineye (M2M) kimlik doğrulaması
• OAuth kullanıcıdan makineye (U2M) kimlik doğrulaması

Python için Databricks SQL Bağlayıcısı henüz aşağıdaki Azure Databricks kimlik doğrulama türlerini desteklemez:

• Azure yönetilen kimlikleriyle kimlik doğrulayın
• Microsoft Entra hizmet sorumlularıyla kimlik doğrulaması
• Azure CLI ile kimlik doğrulaması

Databricks kişisel erişim jetonu kimlik doğrulaması

Python için Databricks SQL Bağlayıcısı'nı Azure Databricks kişisel erişim belirteci kimlik doğrulamasıyla kullanmak için önce bir Azure Databricks kişisel erişim belirteci oluşturmanız gerekir. Bunu yapmak için Çalışma alanı kullanıcıları için kişisel erişim belirteçleri oluşturma'daki adımları izleyin.

Python için Databricks SQL Bağlayıcısı'nın kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAMEdeğerini, çok amaçlı işlem veya SQL ambarınız için Sunucu Ana Bilgisayar İsmi olarak ayarlayın.
• DATABRICKS_HTTP_PATH, tüm amaçlara uygun işlem veya SQL ambarınız için HTTP Yolu değerine ayarlayın.
• DATABRICKS_TOKEN, Azure Databricks kişisel erişim belirteci olacak şekilde ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

OAuth makineler arası (M2M) kimlik doğrulaması

Python sürümleri 2.7.0 ve üzeri için Databricks SQL Bağlayıcısı , OAuth makineden makineye (M2M) kimlik doğrulamasını destekler. Ayrıca Python için 0.18.0 veya üzeri Databricks SDK'sını yüklemeniz gerekir (örneğin, veya pip install databricks-sdk çalıştırarak).

Python için Databricks SQL Bağlayıcısı'nı OAuth M2M kimlik doğrulamasıyla kullanmak için aşağıdakileri yapmanız gerekir:

1. Azure Databricks çalışma alanınızda bir Azure Databricks hizmet yetkilisi oluşturun ve bu hizmet yetkilisi için bir OAuth gizli anahtarı oluşturun.

   Hizmet sorumlusunu ve OAuth gizli dizisini oluşturmak için bkz. OAuth ile Azure Databricks'e hizmet sorumlusu erişimi yetkilendirme. Hizmet prensibinin UUID veya Uygulama Kimliği değerini ve hizmet prensibinin OAuth gizli anahtarı için Gizli Anahtar değerini not edin.

2. Hizmet hesabına çok amaçlı işlem veya veri ambarınıza erişim izni verin.

   Hizmet sorumlusuna çok amaçlı işlem veya ambarınıza erişim vermek için bkz. İşlem izinleri veya SQL ambarını yönetme.

Python için Databricks SQL Bağlayıcısı'nın kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAME değerini, çok amaçlı işlem veya SQL ambarınız için Sunucu Ana Bilgisayar adı değerine ayarlayın.
• DATABRICKS_HTTP_PATH, tüm amaçlara uygun işlem veya SQL ambarınız için HTTP Yolu değerine ayarlayın.
• DATABRICKS_CLIENT_IDdeğerini hizmet sorumlusunun UUID veya Uygulama Kimliği değerine ayarlayın.
• DATABRICKS_CLIENT_SECRET, hizmet principal'inin OAuth gizli anahtarı için Gizli değerine ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

Microsoft Entra ID jeton kimlik doğrulaması

Python için Databricks SQL Bağlayıcısı'nı Microsoft Entra ID belirteci kimlik doğrulamasıyla kullanmak için Microsoft Entra ID belirteciyle Python için Databricks SQL Bağlayıcısı'nı sağlamanız gerekir. Microsoft Entra ID erişim belirteci oluşturmak için aşağıdakileri yapın:

• Azure Databricks kullanıcısı için Azure CLI'yı kullanabilirsiniz. Bkz. Microsoft Entra Id belirteçlerini el ile alma.
• Microsoft Entra ID hizmet sorumlusu için bkz. Hizmet sorumluları için belirteçleri alma. Microsoft Entra Id yönetilen hizmet sorumlusu oluşturmak için bkz. Hizmet sorumluları.

Microsoft Entra Id belirteçlerinin varsayılan ömrü yaklaşık 1 saattir. Yeni bir Microsoft Entra Id belirteci oluşturmak için bu işlemi yineleyin.

Python için Databricks SQL Bağlayıcısı'nın kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAME tüm amaçlı işlem veya SQL ambarınız için Sunucu Ana Bilgisayar Adı değerine ayarlayın.
• DATABRICKS_HTTP_PATH değerini tüm amaçlı işlem veya SQL ambarınız için HTTP Yolu olarak ayarlayın.
• DATABRICKS_TOKEN'ı Microsoft Entra ID belirtecine ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

OAuth kullanıcıdan makineye (U2M) kimlik doğrulaması

Python sürümleri 2.7.0 ve üzeri için Databricks SQL Bağlayıcısı , OAuth kullanıcıdan makineye (U2M) kimlik doğrulamasını destekler. Python 0.19.0 veya üzeri için Databricks SDK'sını da yüklemeniz gerekir (örneğin, veya pip install databricks-sdkkomutunu çalıştırarakpython -m pip install databricks-sdk).

Python için Databricks SQL Bağlayıcısı'nın kimliğini OAuth U2M kimlik doğrulamasıyla doğrulamak için aşağıdaki kod parçacığını kullanın. OAuth U2M kimlik doğrulaması, hedef Azure Databricks kullanıcı hesabının kimliğini doğrulamak için gerçek zamanlı insan oturum açma ve onay kullanır. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAME tüm amaçlı işlem veya SQL ambarınız için Sunucu Ana Bilgisayar Adı değerine ayarlayın.
• DATABRICKS_HTTP_PATH değerini tüm amaçlı işlem veya SQL ambarınız için HTTP Yolu olarak ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

Örnekler

Aşağıdaki kod örneklerinde Verileri sorgulamak ve eklemek, meta verileri sorgulamak, imleçleri ve bağlantıları yönetmek, Unity Kataloğu'ndaki dosyaları yönetmek ve günlüğü yapılandırmak için Python için Databricks SQL Bağlayıcısı'nın nasıl kullanılacağı gösterilmektedir.

Not

Aşağıdaki kod örneklerinde kimlik doğrulaması için Azure Databricks kişisel erişim belirtecinin nasıl kullanılacağı gösterilmektedir. Farklı bir kimlik doğrulama türü kullanmak için bkz. Kimlik doğrulaması.

Bu kod örneği, bu ortam değişkenlerinden server_hostname, http_pathve access_token bağlantı değişkeni değerlerini alır:

• DATABRICKS_SERVER_HOSTNAME, gereksinimlerden Sunucu Ana Bilgisayar Adı değerini temsil eder.
• DATABRICKS_HTTP_PATH, gereksinimlerden HTTP Yolu değerini temsil eder.
• DATABRICKS_TOKEN, gereksinimlerden gelen erişim belirtecinizi temsil eder.

User-Agent'i ayarla

Aşağıdaki kod örneğinde, kullanım izleme için User-Agent uygulama product_name nasıl ayarlanacağı gösterilmektedir.

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)

Verileri sorgulama

Aşağıdaki kod örneği, tüm amaçlı işlem veya SQL ambarı üzerinde temel bir SQL komutu çalıştırmak üzere Python için Databricks SQL Bağlayıcısı'nın nasıl çağrılduğunu gösterir. Bu komut, kataloğun trips şemasındaki tablodan samplesnyctaxi ilk iki satırı döndürür.

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)

Sorgu etiketleri

Önemli

Bu özellik, Özel Önizleme sürümündedir. Erişim istemek için hesap ekibinize başvurun.

Aşağıdaki örnekte, izleme ve analiz amacıyla SQL sorgularınıza anahtar-değer etiketlerinin nasıl ekleneceği gösterilmektedir. Sorgu etiketleri tabloda görünür system.query.history .

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)

Veri ekleme

Aşağıdaki örnekte az miktarda verinin (binlerce satır) nasıl ekleyebileceğiniz gösterilmektedir:

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)

Büyük miktarda veri için önce verileri bulut depolama alanına yüklemeniz ve ardından COPY INTO komutunu yürütmeniz gerekir.

Sorgu meta verileri

Meta verileri almak için ayrılmış yöntemler vardır. Aşağıdaki örnek, örnek tablodaki sütunlar hakkındaki meta verileri alır:

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())

İmleçleri ve bağlantıları yönetme

Artık kullanımda olmayan bağlantıları ve imleçleri kapatmak en iyi yöntemdir. Bu, Azure Databricks genel amaçlı hesaplama ve Databricks SQL depo alanlarındaki kaynakları serbest bırakır.

Kaynakları yönetmek için bağlam yöneticisini ( with önceki örneklerde kullanılan söz dizimi) kullanabilir veya açıkça çağırabilirsiniz 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()

Unity Kataloğu birimlerinde dosyaları yönetme

Databricks SQL Bağlayıcısı, aşağıdaki örnekte gösterildiği gibi Unity Kataloğu birimlerine yerel dosyalar yazmanızı, birimlerden dosya indirmenizi ve birimlerden dosya silmenizi sağlar:

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'"
    )

Günlük kaydetmeyi yapılandırma

Databricks SQL Bağlayıcısı, Python'ın standart günlük modülünü kullanır. Aşağıdaki örnek günlük düzeyini yapılandırarak bir hata ayıklama günlüğü oluşturur:

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()

Test Etme

Kodunuzu test etmek için pytest gibi Python test çerçevelerini kullanın. Azure Databricks REST API uç noktalarını çağırmadan veya Azure Databricks hesaplarınızın veya çalışma alanlarınızın durumunu değiştirmeden kodunuzu sanal koşullar altında test etmek için unittest.mock gibi sahte Python kitaplıklarını kullanabilirsiniz.

Örneğin, Azure Databricks kişisel erişim belirtecini kullanarak Azure Databricks çalışma alanına bağlantı döndüren bir helpers.py işlevi ve bağlantıyı kullanarak katalogdaki get_connection_personal_access_token şeması içindeki select_nyctaxi_trips tablodan belirtilen sayıda veri satırını alan bir trips işlevi içeren samples adlı aşağıdaki dosya:

# 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

Adı main.py olan ve get_connection_personal_access_token ile select_nyctaxi_trips işlevlerini çağıran aşağıdaki dosya göz önüne alındığında:

# 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)

Adlı aşağıdaki dosya test_helpers.py , işlevin select_nyctaxi_trips beklenen yanıtı döndürip döndürmediğini sınar. Bu test, hedef çalışma alanına gerçek bir bağlantı oluşturmak yerine bir Connection nesnesini taklit eder. Test ayrıca şemaya ve gerçek verilerdeki değerlere uyan bazı verileri taklit eder. Test, sahte bağlantı üzerinden sahte verileri döndürür ve ardından sahte veri satırlarından birinin değerlerinin beklenen değerle eşleşip eşleşmediğini denetler.

# 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 işlevi bir SELECT deyimi içerdiğinden ve bu nedenle trips tablosunun durumunu değiştirmediğinden, bu örnekte nesne taklit etme kesinlikle gerekli değildir. Ancak mock nesneler, çalışma alanıyla gerçek bir bağlantının kurulmasını beklemeden testlerinizi hızlı bir şekilde çalıştırmanızı sağlar. Ayrıca, sahtecilik, bir tablonun durumunu değiştirebilecek INSERT INTO, UPDATE ve DELETE FROM gibi işlevler için simülasyon testlerini birden çok kez çalıştırmanıza olanak tanır.

API referansı

Bu bölüm paket için databricks-sql-connector API başvurusu içerir. Python Paket Dizini'nde (PyPI) databricks-sql-connector bölümüne bakın.

Modül

databricks.sql Paketin databricks-sql-connector modülü, SQL ambarı ile bağlantı başlatma yöntemini içerir.

connect yöntemi

SQL ambarı bağlantısını başlatır. Bir Bağlantı nesnesi döndürür.

Parametre	Türü	Description
server_hostname	str	Gerekli. Çok amaçlı işlem veya SQL ambarı için sunucu ana bilgisayar adı, örneğin adb-1234567890123456.7.azuredatabricks.net. Sunucu ana bilgisayar adını almak için Başlarken'deki yönergelere bakın.
http_path	str	Gerekli. Çok amaçlı işlem veya SQL ambarının HTTP yolu; örneğin sql/protocolv1/o/1234567890123456/1234-567890-test123 , tüm amaçlı işlem veya /sql/1.0/warehouses/a1b234c567d8e9fa SQL ambarı için. HTTP yolunu almak için Başlarken başlığındaki yönergelere bakın.
access_token, auth_type, credentials_provider, password, , username	str	Azure Databricks kimlik doğrulama ayarları hakkında bilgi. Ayrıntılar için bkz. Kimlik doğrulaması.
session_configuration	dict[str, Any]	Spark oturumu yapılandırma parametrelerinin sözlüğü. Yapılandırmayı ayarlamak, SQL komutunu kullanmaya SET key=val eşdeğerdir. Kullanılabilir yapılandırmaların tam listesini almak için SQL komutunu SET -v çalıştırın. Varsayılan değer None olarak ayarlanır. Örnek: {"spark.sql.variable.substitute": True}
http_headers	List[Tuple[str, str]]]	Optional. İstemcinin yaptığı her RPC isteğinde HTTP başlıklarına eklenmesi gereken ek (anahtar, değer) çiftleri. Tipik kullanım, ek HTTP üst bilgisi ayarlamaz. Varsayılan değer None olarak ayarlanır.
catalog	str	Optional. Bağlantı için kullanılacak ilk katalog. varsayılan değeridir None (bu durumda varsayılan katalog genellikle hive_metastore kullanılır).
schema	str	Optional. Bağlantı için kullanılacak ilk şema. Varsayılan olarak None (bu durumda varsayılan şema default kullanılır). Sürüm 2.0'dan itibaren
use_cloud_fetch	bool	Optional. Veri öbeklerini indirmek için doğrudan bulut nesne deposuna getirme istekleri gönderip gönderilmeyeceği. Varsayılan değer True olarak ayarlanır. False ayarlayarak getirme isteklerini doğrudan Azure Databricks'e gönderin. use_cloud_fetch True olarak ayarlandıysa ancak ağ erişimi engellendiyse, getirme istekleri başarısız olur. Sürüm 2.8'den itibaren
user_agent_entry	str	Optional. Kullanım izleme amacıyla HTTP isteği başlığına eklenecek User-Agent girişi. Varsayılan değer PyDatabricksSqlConnector olarak ayarlanır.

Connection sınıf

İşlem veya SQL ambarı bağlantısını temsil eder.

Yöntemler

Connection sınıfı aşağıdaki yöntemleri sağlar.

Yöntem	Description
close	Veritabanı bağlantısını kapatır ve ilişkili tüm kaynakları sunucuda serbest bırakır. Bu bağlantıya yapılan ek çağrılar bir Erroroluşturur. Parametre yoktur. Dönüş değeri yok.
cursor	Veritabanındaki kayıtlar üzerinde dolaşmayı etkinleştiren yeni bir İmleç nesnesi döndürür. Parametre yoktur.

Cursor sınıf

Veri kayıtları üzerinden geçiş için bir mekanizmayı temsil eder.

Nesne Cursor oluşturmak için cursor yöntemini çağırın.

Özellikler

Seçili Cursor öznitelikler şunları içerir:

Özellik	Description
arraysize	fetchmany yöntemiyle kullanıldığında, iç arabellek boyutunu belirtir ve bu, sunucudan bir seferde gerçekte kaç satırın getirildiğini gösterir. Varsayılan değer şudur: 10000. Dar sonuçlar için (her satırın çok fazla veri içermediği sonuçlar) daha iyi performans için bu değeri artırmanız gerekir. Okuma-yazma erişimi.
description	Python ile ilgili listtuple nesnelerini içerir. Bu tuple nesnelerin her biri 7 değer içerir ve her tuple nesnesinin ilk 2 öğesi aşağıdaki gibi tek bir sonuç sütununu açıklayan bilgiler içerir: name: Sütunun adı. type_code: Sütunun türünü temsil eden bir dize. Örneğin, bir tamsayı sütunu inttüründe bir koda sahip olur. Her 7 öğeli tuple nesnesinin kalan 5 öğesi uygulanmaz ve değerleri tanımlanmaz. Bunlar genellikle 4 None değer ve ardından tek True bir değer olarak döndürülür. Yalnızca okunabilir erişim.

Yöntemler

Seçili Cursor yöntemler şunlardır:

Yöntem	Description
cancel	İmlecin başlattığı herhangi bir veritabanı sorgusunun veya komutunun çalışmasını kesintiye uğratır. İlişkili kaynakları sunucuda serbest bırakmak için önce close yöntemini, ardından cancel yöntemini çağırın. Parametre yoktur. Dönüş değeri yok.
close	İmleci kapatır ve ilişkili kaynakları sunucuda serbest bırakır. Zaten kapalı olan bir imleci kapatmak hataya neden olabilir. Parametre yoktur. Dönüş değeri yok.
execute	Bir veritabanı sorgusu veya komutu hazırlar ve çalıştırır. Parametreler: operation: Gerekli. Hazırlanıp çalıştırılacak sorgu veya komut. Tür: str Parametresi olmayan parameters örnek: cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2') parametresiyle ilgili parameters örnek (yerel konumsal parametreler kullanılarak): cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2]) parameters: İsteğe bağlı. operation parametresiyle kullanılacak parametre dizisi. Varsayılan değer: None. Tür: dictionary Dönüş değeri yok.
executemany	Bağımsız değişkendeki seq_of_parameters tüm parametre dizilerini kullanarak bir veritabanı sorgusu veya komutu hazırlar ve çalıştırır. Yalnızca son sonuç kümesi korunur. Parametreler: operation: Gerekli. Hazırlanıp çalıştırılacak sorgu veya komut. Tür: str seq_of_parameters: Gerekli. Birçok parametre değeri kümesinden oluşan bir dizisi operation parametresiyle kullanılacaktır. Türü: listdict Dönüş değeri yok.
catalogs	Kataloglar hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra fetchmany veya fetchall kullanılarak getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: Alan adı: TABLE_CAT. Kataloğun adı. Tür: str Parametre yoktur. Dönüş değeri yok. Sürüm 1.0'dan itibaren
schemas	Şemalar hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra fetchmany veya fetchall kullanılarak getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: Alan adı: TABLE_SCHEM. Şemanın adı. Tür: str Alan adı: TABLE_CATALOG. Şemanın ait olduğu katalog. Tür: str Parametreler: catalog_name: İsteğe bağlı. Hakkında bilgi almak için bir katalog adı. Karakter % joker olarak yorumlanır. Tür: str schema_name: İsteğe bağlı. Hakkında bilgi alınacak şema adı. Karakter % joker olarak yorumlanır. Tür: str Dönüş değeri yok. Sürüm 1.0'dan itibaren
tables	Tablolar ve görünümler hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra fetchmany veya fetchall kullanılarak getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: Alan adı: TABLE_CAT. Tablonun ait olduğu katalog. Tür: str Alan adı: TABLE_SCHEM. Tablonun ait olduğu şema. Tür: str Alan adı: TABLE_NAME. Tablonun adı. Tür: str Alan adı: TABLE_TYPE. İlişki türü, örneğin VIEW veya TABLE (Databricks Runtime 10.4 LTS ve üzeri ile Databricks SQL için geçerlidir; Databricks Runtime'ın önceki sürümleri boş bir dize döndürür). Tür: str Parametreler: catalog_name: İsteğe bağlı. Hakkında bilgi almak için bir katalog adı. Karakter % joker olarak yorumlanır. Tür: str schema_name: İsteğe bağlı. Hakkında bilgi alınacak şema adı. Karakter % joker olarak yorumlanır. Tür: str table_name: İsteğe bağlı. Hakkında bilgi almak için bir tablo adı. Karakter % joker olarak yorumlanır. Tür: str table_types: İsteğe bağlı. Eşleştirecek tablo türlerinin listesi, örneğin TABLE veya VIEW. Tür: List[str] Dönüş değeri yok. Sürüm 1.0'dan itibaren
columns	Sütunlar hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra fetchmany veya fetchall kullanılarak getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: Alan adı: TABLE_CAT. Sütunun ait olduğu katalog. Tür: str Alan adı: TABLE_SCHEM. Sütunun ait olduğu şema. Tür: str Alan adı: TABLE_NAME. Sütunun ait olduğu tablonun adı. Tür: str Alan adı: COLUMN_NAME. Sütunun adı. Tür: str Parametreler: catalog_name: İsteğe bağlı. Hakkında bilgi almak için bir katalog adı. Karakter % joker olarak yorumlanır. Tür: str schema_name: İsteğe bağlı. Hakkında bilgi alınacak şema adı. Karakter % joker olarak yorumlanır. Tür: str table_name: İsteğe bağlı. Hakkında bilgi almak için bir tablo adı. Karakter % joker olarak yorumlanır. Tür: str column_name: İsteğe bağlı. Hakkında bilgi almak için bir sütun adı. Karakter % joker olarak yorumlanır. Tür: str Dönüş değeri yok. Sürüm 1.0'dan itibaren
fetchall	Sorgunun tüm satırlarını (veya kalan satırların tümünü) alır. Parametre yoktur. Sorgunun tüm satırlarını (veya kalan tümünü) nesnelerin Python'ı listRow olarak döndürür. Önceki `Error` yöntemine yapılan çağrı herhangi bir veri döndürmediyse veya henüz `execute` çağrısı yapılmadıysa bir `execute` fırlatır.
fetchmany	Sorgunun sonraki satırlarını alır. Parametreler: size: İsteğe bağlı. Alınacak sonraki satırların sayısı. Belirtilmezse özniteliğinin arraysize değeri kullanılır. Tür: int. Örnek: cursor.fetchmany(10) size (veya belirtilmezse arraysize özniteliği) kadar bir sorgunun sonraki satırlarını, size nesnelerinden oluşan bir Python list olarak döndürür. Getirilecek satır sayısı azsa size kalan tüm satırlar döndürülür. Önceki `Error` yöntemine yapılan çağrı herhangi bir veri döndürmediyse veya henüz `execute` çağrısı yapılmadıysa bir `execute` fırlatır.
fetchone	Veri kümesinin sonraki satırını alır. Parametre yoktur. Veri kümesinin sonraki satırını Python tuple nesnesi olarak tek bir sıralı dizi olarak döndürür veya kullanılabilir başka veri yoksa None geri döndürür. Önceki `Error` yöntemine yapılan çağrı herhangi bir veri döndürmediyse veya henüz `execute` çağrısı yapılmadıysa bir `execute` fırlatır.
fetchall_arrow	Bir sorgunun tüm (veya kalan) satırlarını PyArrow Table nesnesi olarak alır. Çok büyük miktarda veri döndüren sorgular bunun yerine bellek tüketimini azaltmak için kullanmalıdır fetchmany_arrow . Parametre yoktur. Sorgunun tüm (veya kalan) satırlarını PyArrow tablosu olarak döndürür. Önceki `Error` yöntemine yapılan çağrı herhangi bir veri döndürmediyse veya henüz `execute` çağrısı yapılmadıysa bir `execute` fırlatır. Sürüm 2.0'dan itibaren
fetchmany_arrow	Bir sorgunun sonraki satırlarını PyArrow Table nesnesi olarak alır. Parametreler: size: İsteğe bağlı. Alınacak sonraki satırların sayısı. Belirtilmezse özniteliğinin arraysize değeri kullanılır. Tür: int. Örnek: cursor.fetchmany_arrow(10) size bağımsız değişkenine kadar (veya arraysize belirtilmemişse size özniteliğine kadar) bir sorgunun sonraki satırlarını Python PyArrow Table nesnesi olarak döndürür. Önceki `Error` yöntemine yapılan çağrı herhangi bir veri döndürmediyse veya henüz `execute` çağrısı yapılmadıysa bir `execute` fırlatır. Sürüm 2.0'dan itibaren

Row sınıf

Satır sınıfı, SQL sorgusundaki bireysel bir sonuç satırını temsil eden, demet benzeri bir veri yapısıdır. Satırda "my_column"adlı bir sütun varsa, "my_column"aracılığıyla rowrow.my_column alanına erişebilirsiniz. Ayrıca, alanlara erişmek için sayısal dizinler de kullanabilirsiniz, örneğin row[0]. Sütun adı, özellik yöntemi adı olarak izin verilmediğinde (örneğin, bir rakamla başlıyorsa), alana "row["1_my_column"]" şeklinde erişebilirsiniz.

Sürüm 1.0'dan itibaren

Seçili Row yöntemler şunlardır:

Yöntemler

Yöntem	Description
asDict	Alan adlarına göre dizinlenen satırın sözlük gösterimini döndürür. Yinelenen alan adları varsa, yinelenen alanlardan biri (ancak yalnızca biri) sözlükte döndürülür. Hangi yinelenen alanın döndürüleceği tanımlanmamıştır.

Tip dönüştürmeleri

Aşağıdaki tabloda Apache Spark SQL veri türleri Python veri türü eşdeğerleriyle eşlenmiştir.

Apache Spark SQL veri türü	Python veri türü
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

Telemetri koleksiyonu

Python için Databricks SQL Bağlayıcısı, Azure Databricks'in güvenilirliği artırmasına ve sorunları gidermesine yardımcı olmak için telemetri verilerini toplar. Telemetri varsayılan olarak etkindir ve aşağıdaki işlem verilerini toplar:

• Sürücü sürümü, Python çalışma zamanı ve işletim sistemi gibi istemci ortamı ayrıntıları
• Sürücü bağlantısı yapılandırmaları (kişisel bilgiler hariç)
• İşlem gecikmesi ölçümleri
• Satır içi JSON veya Apache Ok gibi yürütme sonucu biçimleri
• Sorgu yürütme, meta veri sorguları veya birim işlemleri gibi işlem türleri
• Hata sınıflandırma verileri
• Yeniden deneme sayıları

Önemli

Azure Databricks telemetri aracılığıyla sorgu içeriğini, sorgu sonuçlarını veya kişisel bilgileri (PII) toplamaz.

Telemetri koleksiyonunu devre dışı bırakmak için, bağlantı oluştururken parametreyi enable_telemetry olarak 0 ayarlayın.

Sorun giderme

tokenAuthWrapperInvalidAccessToken: Invalid access token İleti

Sorun: Kodunuzu çalıştırdığınızda, benzeri Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access tokenbir ileti görürsünüz.

Olası neden: access_token'ye geçirilen değer geçerli bir Azure Databricks kişisel erişim belirteci değil.

Önerilen düzeltme: geçirilen access_token değerin doğru olup olmadığını denetleyin ve yeniden deneyin.

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

Sorun: Kodunuzu çalıştırdığınızda, benzeri Error during request to server: gaierror(8, 'nodename nor servname provided, or not known')bir ileti görürsünüz.

Olası neden: server_hostname için geçirilen değerin doğru ana bilgisayar adı olmadığı.

Önerilen düzeltme: geçirilen server_hostname değerin doğru olup olmadığını denetleyin ve yeniden deneyin.

Sunucu ana bilgisayar adını bulma hakkında daha fazla bilgi için bkz. Azure Databricks işlem kaynağı için bağlantı ayrıntılarını alma.

IpAclError İleti

Sorun: Kodunuzu çalıştırdığınızda, bağlayıcıyı bir Azure Databricks not defterinde kullanmaya çalıştığınızda iletiyi Error during request to server: IpAclValidation görürsünüz.

Olası neden: Azure Databricks çalışma alanı için IP izin listesi etkinleştirilmiş olabilir. IP izin verilenler listesi ile Spark kümelerinden denetim düzlemine geri bağlantılara varsayılan olarak izin verilmez.

Önerilen düzeltme: Yöneticinizden işlem düzlemi alt ağini IP izin verme listesine eklemesini isteyin.

Ek kaynaklar

Daha fazla bilgi için bkz.

• GitHub'daki Python için Databricks SQL Bağlayıcısı deposu
• Veri türleri
• Python web sitesindeki yerleşik Türler (için bool, bytearray, float, int ve str)
• Python websitesinde datetime (datetime.date ve datatime.datetime için)
• Python web sitesinde ondalık (decimal.Decimal için)
• Python web sitesinde yerleşik Sabitler (içinNoneType)