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

Python için Databricks SQL Bağlayıcısı, Azure Databricks kümelerinde 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.

Not

Python için Databricks SQL Bağlayıcısı, Azure Databricks için sqlalchemy diyalektini de içerir. Bkz . Azure Databricks ile SQLAlchemy kullanma.

Gereksinimler

• Python >=3.8 ve <=3.11 ç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.
• Mevcut bir küme veya SQL ambarı.

Kullanmaya başlayın

• veya python -m pip install databricks-sql-connectorkomutunu çalıştırarak pip install databricks-sql-connector geliştirme makinenize Python kitaplığı için Databricks SQL Bağlayıcısı'nı yükleyin.

• Kullanmak istediğiniz küme veya SQL ambarı için aşağıdaki bilgileri toplayın:

  Küme

  • Kümenin sunucu ana bilgisayar adı. Bunu, kümenizin Gelişmiş Seçenekler > JDBC/ODBC sekmesindeki Sunucu Ana Bilgisayar adı değerinden alabilirsiniz.
  • Kümenin HTTP yolu. Bunu kümenizin Gelişmiş Seçenekler > JDBC/ODBC sekmesindeki HTTP Yolu değerinden alabilirsiniz.

  SQL ambarı

  • SQL ambarının sunucu konak 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 belirteci 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 kimlikleri kimlik doğrulaması
• MS Entra hizmet sorumlusu kimlik doğrulaması
• Azure CLI kimlik doğrulaması

Databricks kişisel erişim belirteci 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 aşağıdaki gibi bir Azure Databricks kişisel erişim belirteci oluşturmanız gerekir:

1. Azure Databricks çalışma alanınızda üst çubukta Azure Databricks kullanıcı adınıza tıklayın ve açılan listeden Ayarlar'ı seçin.
2. Geliştirici'ye tıklayın.
3. Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
4. Yeni belirteç oluştur'a tıklayın.
5. (İsteğe bağlı) Gelecekte bu belirteci tanımlamanıza yardımcı olacak bir açıklama girin ve belirtecin varsayılan 90 günlük ömrünü değiştirin. Yaşam süresi olmayan bir belirteç oluşturmak için (önerilmez), Yaşam Süresi (gün) kutusunu boş (boş) bırakın.
6. Generate (Oluştur) düğmesine tıklayın.
7. Görüntülenen belirteci güvenli bir konuma kopyalayın ve bitti'ye tıklayın.

Not

Kopyalanan belirteci güvenli bir konuma kaydettiğinizden emin olun. Kopyalanan belirtecinizi başkalarıyla paylaşmayın. Kopyalanan belirteci kaybederseniz, tam olarak aynı belirteci yeniden oluşturamazsınız. Bunun yerine, yeni bir belirteç oluşturmak için bu yordamı yinelemeniz gerekir. Kopyalanan belirteci kaybederseniz veya belirtecin gizliliğinin ihlal edildiğini düşünüyorsanız Databricks, Erişim belirteçleri sayfasındaki belirtecin yanındaki çöp kutusu (İptal Et) simgesine tıklayarak bu belirteci çalışma alanınızdan hemen silmenizi kesinlikle önerir.

Çalışma alanınızda belirteç oluşturamıyor veya kullanamıyorsanız, bunun nedeni çalışma alanı yöneticinizin belirteçleri devre dışı bırakmış olması veya size belirteç oluşturma veya kullanma izni vermemiş olması olabilir. Çalışma alanı yöneticinize veya aşağıdaki konulara bakın:

• Çalışma alanı için kişisel erişim belirteci kimlik doğrulamasını etkinleştirme veya devre dışı bırakma
• Kişisel erişim belirteci izinleri

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 kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayın.
• DATABRICKS_TOKEN, Azure Databricks kişisel erişim 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 makineden makineye (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 0.18.0 veya üzeri için Databricks SDK'sını da yüklemeniz gerekir (örneğin, veya python -m pip install databricks-sdkkomutunu çalıştırarakpip install databricks-sdk).

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 sorumlusu oluşturun ve bu hizmet sorumlusu için bir OAuth gizli dizisi oluşturun.

   Hizmet sorumlusunu ve OAuth gizli dizisini oluşturmak için bkz . OAuth (OAuth M2M) kullanarak hizmet sorumlusuyla Azure Databricks'e erişimin kimliğini doğrulama. Hizmet sorumlusunun UUID veya Uygulama Kimliği değerini ve hizmet sorumlusunun OAuth gizli dizisi için Gizli dizi değerini not edin.

2. Bu hizmet sorumlusuna kümenize veya ambarınıza erişim verin.

   Hizmet sorumlusuna kümenize 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_HOSTNAMEdeğerini kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayın.
• DATABRICKS_CLIENT_IDdeğerini hizmet sorumlusunun UUID veya Uygulama Kimliği değerine ayarlayın.
• DATABRICKS_CLIENT_SECRET, hizmet sorumlusunun OAuth gizli dizisi için Gizli dizi 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 belirteci 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 . Azure CLI kullanarak kullanıcılar için Microsoft Entra ID belirteçlerini alma.
• Microsoft Entra ID hizmet sorumlusu için bkz . Azure CLI ile Microsoft Entra ID erişim belirteci alma. Microsoft Entra Id yönetilen hizmet sorumlusu oluşturmak için bkz . Hizmet sorumlularını yönetme.

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:

• Kümeniz veya SQL ambarınız için Sunucu Ana Bilgisayar Adı değerine ayarlayınDATABRICKS_SERVER_HOSTNAME.
• Kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayınDATABRICKS_HTTP_PATH.
• Microsoft Entra Id belirtecine ayarlayın DATABRICKS_TOKEN .

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 python -m pip install databricks-sdkkomutunu çalıştırarakpip 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:

• Kümeniz veya SQL ambarınız için Sunucu Ana Bilgisayar Adı değerine ayarlayınDATABRICKS_SERVER_HOSTNAME.
• Kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayınDATABRICKS_HTTP_PATH.

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 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. Bunun yerine diğer kullanılabilir Azure Databricks kimlik doğrulama türlerini kullanmak için bkz . Kimlik doğrulaması.

Bu kod örneği, bu ortam değişkenlerinden , server_hostnamehttp_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 erişim belirtecinizi temsil eder.

Bu bağlantı değişkeni değerlerini almak için diğer yaklaşımları kullanabilirsiniz. Ortam değişkenlerini kullanmak, birçok yaklaşım arasında yalnızca bir yaklaşımdır.

• Sorgu verileri
• Veri ekleme
• Sorgu meta verileri
• İmleçleri ve bağlantıları yönetme
• Unity Kataloğu birimlerindeki dosyaları yönetme
• Günlüğü yapılandırma

Verileri sorgulama

Aşağıdaki kod örneği, bir kümede veya SQL ambarı üzerinde temel bir SQL komutu çalıştırmak üzere Python için Databricks SQL Bağlayıcısı'nı çağırmayı gösterir. Bu komut, kataloğun nyctaxi şemasındaki tablodan trips samples 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)

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

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 kümelerinde ve Databricks SQL ambarlarında kaynakları serbesttir.

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

Günlük kaydetmeyi yapılandırma

Databricks SQL Bağlayıcısı, Python'ın standart günlük modülünü kullanır. Günlüğe kaydetme düzeyini aşağıdakine benzer şekilde yapılandırabilirsiniz:

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 çalışma alanına bağlantı döndürmek için Azure Databricks kişisel erişim belirtecini kullanan bir işlevi ve katalog nyctaxi şemasındaki samples tablodan belirtilen sayıda veri satırını trips almak için bağlantıyı kullanan bir select_nyctaxi_trips işlevi içeren get_connection_personal_access_token aşağıdaki dosya helpers.py göz önünde bulundurulduğunda:

# 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

Ve adlı ve işlevlerini çağıran aşağıdaki dosya main.py göz önünde bulundurulduğunda get_connection_personal_access_token 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)

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 nesneyle dalga geçer. Test ayrıca şemaya ve gerçek verilerdeki değerlere uyan bazı verilerle dalga geçer. 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 İşlev bir SELECT deyim içerdiğinden ve bu nedenle tablonun durumunu trips değiştirmediğinden, bu örnekte sahte işlem yapmak kesinlikle gerekli değildir. Ancak sahte işlem, çalışma alanıyla gerçek bir bağlantının yapılmasını beklemeden testlerinizi hızlı bir şekilde çalıştırmanızı sağlar. Ayrıca sahte işlem, bir tablonun durumunu değiştirebilecek , UPDATEve DELETE FROMgibi INSERT INTOişlevler için simülasyon testlerini birden çok kez çalıştırmanıza olanak tanır.

API başvurusu

• Paket
• Modül
• Sınıflar
• Connection sınıfı
• Cursor sınıfı
• Row sınıfı
• Tür dönüştürmeleri

Paket

databricks-sql-connector

Kullanım: pip install databricks-sql-connector

Ayrıca bkz. Python Paket Dizini'nde (PyPI) databricks-sql-connector .

Modül

databricks.sql

Kullanım: from databricks import sql

Sınıflar

Seçili sınıflar şunları içerir:

Sınıflar
Connection Azure Databricks işlem kaynağında oturum.
Cursor Veri kayıtları üzerinden geçiş için bir mekanizma.
Row SQL sorgu sonucundaki bir veri satırı.

Connection sınıfı

Nesne Connection oluşturmak için aşağıdaki parametrelerle yöntemini çağırın databricks.sql.connect :

Parametreler
server_hostname Tür: str Küme veya SQL ambarı için sunucu ana bilgisayar adı. Sunucu ana bilgisayar adını almak için bu makalenin önceki bölümlerindeki yönergelere bakın. Bu parametre zorunludur. Örnek: adb-1234567890123456.7.azuredatabricks.net
http_path Tür: str Kümenin veya SQL ambarının HTTP yolu. HTTP yolunu almak için bu makalenin önceki bölümlerindeki yönergelere bakın. Bu parametre zorunludur. Örnek: sql/protocolv1/o/1234567890123456/1234-567890-test123 bir küme için. /sql/1.0/warehouses/a1b234c567d8e9fa bir SQL ambarı için.
access_token, auth_type Tür: str Azure Databricks kimlik doğrulama ayarları hakkında bilgi. Ayrıntılar için bkz . Kimlik doğrulaması.
session_configuration Tür: 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ğeridir None. Bu parametre isteğe bağlıdır. Örnek: {"spark.sql.variable.substitute": True}
http_headers Tür: List[Tuple[str, str]]] İstemcinin yaptığı her RPC isteğinde HTTP üst bilgilerinde ayarlanacağı ek (anahtar, değer) çiftleri. Tipik kullanım, ek HTTP üst bilgisi ayarlamaz. varsayılan değeridir None. Bu parametre isteğe bağlıdır. Sürüm 2.0'dan itibaren
catalog Tür: str Bağlantı için kullanılacak ilk katalog. varsayılan değeridir None (bu durumda varsayılan katalog, genellikle hive_metastorekullanılır). Bu parametre isteğe bağlıdır. Sürüm 2.0'dan itibaren
schema Tür: str Bağlantı için kullanılacak ilk şema. varsayılan değeridir None (bu durumda varsayılan şema default kullanılır). Bu parametre isteğe bağlıdır. Sürüm 2.0'dan itibaren
use_cloud_fetch Tür: bool True veri öbeklerini indirmek üzere doğrudan bulut nesne deposuna getirme istekleri göndermek için. False (varsayılan), getirme isteklerini doğrudan Azure Databricks'e göndermek için. olarak ayarlanırsa True ancak ağ erişimi engellenirse use_cloud_fetch getirme istekleri başarısız olur. Sürüm 2.8'den itibaren

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

Yöntemler
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ı sağlayan yeni Cursor bir nesne döndürür. Parametre yoktur.

Cursor sınıfı

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

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

Özellikler
arraysize yöntemiyle birlikte fetchmany kullanıldığında iç arabellek boyutunu belirtir. Bu, aynı anda sunucudan gerçekte kaç satır getirildiğidir. 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 Nesnelerin Python'ını list tuple içerir. Bu tuple nesnelerin her biri 7 değer içerir ve her tuple nesnenin 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ütununun inttür kodu olacaktır. Her 7 öğeli nesnenin kalan 5 öğesi tuple uygulanmaz ve değerleri tanımlanmaz. Bunlar genellikle 4 olarak döndürülür None değerler ve ardından tek True bir değer. Salt okunur erişim.

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

Yöntemler
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 close metodu çağrıldıktan cancel sonra yöntemi. 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. Dönüş değeri yok. Parametreler: operation Tür: str Hazırlanıp çalıştırılacak sorgu veya komut. Bu parametre zorunludur. Parametresi olmayan parameters örnek: cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2' ) Parametresiyle örnek parameters : cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2', { 'pickup_zip': '10019' } ) parameters Tür: sözlük parametresiyle operation kullanılacak bir parametre dizisi. Bu parametre isteğe bağlıdır. Varsayılan değer: None.
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. Dönüş değeri yok. Parametreler: operation Tür: str Hazırlanıp çalıştırılacak sorgu veya komut. Bu parametre zorunludur. seq_of_parameters Türü: listdict ile kullanılacak çok sayıda parametre değeri kümesi dizisi operation parametre. Bu parametre zorunludur.
catalogs Kataloglar hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra veya fetchallkullanılarak fetchmany getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: - Alan adı: TABLE_CAT. Tür: str. Kataloğun adı. 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 veya fetchallkullanılarak fetchmany getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: - Alan adı: TABLE_SCHEM. Tür: str. Şemanın adı. - Alan adı: TABLE_CATALOG. Tür: str. Şemanın ait olduğu katalog. Dönüş değeri yok. Sürüm 1.0'dan itibaren Parametreler: catalog_name Tür: str Hakkında bilgi almak için bir katalog adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. schema_name Tür: str Hakkında bilgi alınacak şema adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır.
tables Tablolar ve görünümler hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra veya fetchallkullanılarak fetchmany getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: - Alan adı: TABLE_CAT. Tür: str. Tablonun ait olduğu katalog. - Alan adı: TABLE_SCHEM. Tür: str. Tablonun ait olduğu şema. - Alan adı: TABLE_NAME. Tür: str. Tablonun adı. - Alan adı: TABLE_TYPE. Tür: str. veya gibi VIEW TABLE ilişki türü (Databricks Runtime 10.4 LTS ve üzeri için olduğu gibi Databricks SQL için de geçerlidir; Databricks Runtime'ın önceki sürümleri boş bir dize döndürür). Dönüş değeri yok. Sürüm 1.0'dan itibaren Parametreler catalog_name Tür: str Hakkında bilgi almak için bir katalog adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. schema_name Tür: str Hakkında bilgi alınacak şema adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. table_name Tür: str Hakkında bilgi almak için bir tablo adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. table_types Tür: List[str] Eşleşecek tablo türlerinin listesi, örneğin TABLE veya VIEW. Bu parametre isteğe bağlıdır.
columns Sütunlar hakkında bir meta veri sorgusu yürütür. Gerçek sonuçlar daha sonra veya fetchallkullanılarak fetchmany getirilmelidir. Sonuç kümesindeki önemli alanlar şunlardır: - Alan adı: TABLE_CAT. Tür: str. Sütunun ait olduğu katalog. - Alan adı: TABLE_SCHEM. Tür: str. Sütunun ait olduğu şema. - Alan adı: TABLE_NAME. Tür: str. Sütunun ait olduğu tablonun adı. - Alan adı: COLUMN_NAME. Tür: str. Sütunun adı. Dönüş değeri yok. Sürüm 1.0'dan itibaren Parametreler: catalog_name Tür: str Hakkında bilgi almak için bir katalog adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. schema_name Tür: str Hakkında bilgi alınacak şema adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. table_name Tür: str Hakkında bilgi almak için bir tablo adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır. column_name Tür: str Hakkında bilgi almak için bir sütun adı. Karakter % joker karakter olarak yorumlanır. Bu parametre isteğe bağlıdır.
fetchall Sorgunun tüm satırlarını (veya kalan tümünü) alır. Parametre yoktur. Sorgunun tüm (veya kalan) satırlarını Python list olarak döndürür Row Nesne. Yöntemine yapılan önceki çağrı execute herhangi bir veri döndürmediyse veya henüz çağrı execute yapılmadıysa bir Error oluşturur.
fetchmany Sorgunun sonraki satırlarını alır. Bir sorgunun arraysize sonraki satırlarından en fazla size (veya belirtilmezse size özniteliğini) nesnelerin Python'ı list Row olarak döndürür. Getirilecek satır sayısı azsa size kalan tüm satırlar döndürülür. Yöntemine yapılan önceki çağrı execute herhangi bir veri döndürmediyse veya henüz çağrı execute yapılmadıysa bir Error oluşturur. Parametreler: size Tür: int Alınacak sonraki satır sayısı. Bu parametre isteğe bağlıdır. Belirtilmezse özniteliğinin arraysize değeri kullanılır. Örnek: cursor.fetchmany(10)
fetchone Veri kümesinin sonraki satırını alır. Parametre yoktur. Veri kümesinin sonraki satırını Python olarak tek bir sıra olarak döndürür tuple nesnesine tıklayın veya başka kullanılabilir veri yoksa döndürür None . Yöntemine yapılan önceki çağrı execute herhangi bir veri döndürmediyse veya henüz çağrı execute yapılmadıysa bir Error oluşturur.
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. Yöntemine yapılan önceki çağrı execute herhangi bir veri döndürmediyse veya henüz çağrı execute yapılmadıysa bir Error oluşturur. Sürüm 2.0'dan itibaren
fetchmany_arrow Bir sorgunun sonraki satırlarını PyArrow Table nesnesi olarak alır. Bir sorgunun size sonraki satırlarının bağımsız değişkenine (veya arraysize belirtilmezse size özniteliğine) Python PyArrow olarak verir Table nesne. Yöntemine yapılan önceki çağrı execute herhangi bir veri döndürmediyse veya henüz çağrı execute yapılmadıysa bir Error oluşturur. Sürüm 2.0'dan itibaren Parametreler: size Tür: int Alınacak sonraki satır sayısı. Bu parametre isteğe bağlıdır. Belirtilmezse özniteliğinin arraysize değeri kullanılır. Örnek: cursor.fetchmany_arrow(10)

Row sınıfı

Satır sınıfı, tek bir sonuç satırını temsil eden tanımlama grubu benzeri bir veri yapısıdır. Satırda adlı "my_column"bir sütun varsa, alanına row aracılığıyla row.my_columnerişebilirsiniz"my_column". Ayrıca, alanlara erişmek için sayısal dizinler de kullanabilirsiniz, örneğin row[0]. Sütun adına öznitelik yöntemi adı olarak izin verilmiyorsa (örneğin, bir rakamla başlar), alanına olarak row["1_my_column"]erişebilirsiniz.

Sürüm 1.0'dan itibaren

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

| asDict

Alan adlarından dizine alınan 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. Döndürülen yinelenen alan tanımlanmamıştır.

Parametre yoktur.

Alanlardan birini dict döndürür. |

Tür 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

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: geçirilen access_token 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: geçirilen server_hostname değer doğru ana bilgisayar adı değil.

Ö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 sitesinde yerleşik Türler (için bool, floatbytearray, , intve str)
• Python web sitesinde datetime (for datetime.date ve datatime.datetime)
• Python web sitesinde ondalık (için decimal.Decimal)
• Python web sitesinde yerleşik Sabitler (için NoneType)