Databricks SQL Connector ل Python

مقالة
10/10/2024

Databricks SQL Connector ل Python هو مكتبة Python التي تسمح لك باستخدام تعليمة Python البرمجية لتشغيل أوامر SQL على مجموعات Azure Databricks ومستودعات Databricks SQL. يعد Databricks SQL Connector ل Python أسهل في الإعداد والاستخدام من مكتبات Python المماثلة مثل pyodbc. تتبع هذه المكتبة PEP 249 – Python Database API Specification v2.0.

إشعار

يتضمن موصل Databricks SQL ل Python أيضا لهجة SQLAlchemy ل Azure Databricks. راجع استخدام SQLAlchemy مع Azure Databricks.

المتطلبات

جهاز تطوير يقوم بتشغيل Python >=3.8 و <=3.11.
توصي Databricks باستخدام بيئات Python الظاهرية، مثل تلك التي يوفرها venv المضمنة مع Python. تساعد البيئات الظاهرية على التأكد من أنك تستخدم الإصدارات الصحيحة من Python وموصل Databricks SQL ل Python معا. إعداد البيئات الظاهرية واستخدامها خارج نطاق هذه المقالة. لمزيد من المعلومات، راجع إنشاء بيئات ظاهرية.
نظام مجموعة موجود أو مستودع SQL.

الشروع في العمل

قم بتثبيت Databricks SQL Connector لمكتبة Python على جهاز التطوير الخاص بك عن طريق تشغيل pip install databricks-sql-connector أو python -m pip install databricks-sql-connector.
اجمع المعلومات التالية لنظام المجموعة أو مستودع SQL الذي تريد استخدامه:

نظام المجموعة
- اسم مضيف الخادم للمجموعة. يمكنك الحصول على هذا من قيمة Server Hostname في علامة التبويب Advanced Options > JDBC/ODBC للمجموعة الخاصة بك.
- مسار HTTP للمجموعة. يمكنك الحصول على هذا من قيمة مسار HTTP في علامة التبويب خيارات > متقدمة JDBC/ODBC للمجموعة الخاصة بك.
مستودع SQL
- اسم مضيف الخادم لمستودع SQL. يمكنك الحصول على هذا من قيمة Server Hostname في علامة التبويب Connection Details لمستودع SQL.
- مسار HTTP لمستودع SQL. يمكنك الحصول على هذا من قيمة مسار HTTP في علامة التبويب تفاصيل الاتصال لمستودع SQL الخاص بك.

المصادقة

يدعم Databricks SQL Connector ل Python أنواع مصادقة Azure Databricks التالية:

مصادقة رمز الوصول الشخصي ل Databricks
مصادقة الرمز المميز لمعرف Microsoft Entra
مصادقة OAuth من جهاز إلى جهاز (M2M)
مصادقة OAuth من مستخدم إلى جهاز (U2M)

لا يدعم موصل Databricks SQL ل Python بعد أنواع مصادقة Azure Databricks التالية:

مصادقة رمز الوصول الشخصي ل Databricks

لاستخدام Databricks SQL Connector ل Python مع مصادقة رمز الوصول الشخصي Azure Databricks، يجب أولا إنشاء رمز مميز للوصول الشخصي ل Azure Databricks، كما يلي:

في مساحة عمل Azure Databricks، انقر فوق اسم مستخدم Azure Databricks في الشريط العلوي، ثم حدد الإعدادات من القائمة المنسدلة.
انقر فوق المطور.
إلى جانب رموز الوصول المميزة، انقر فوق إدارة.
النقر على Generate new token.
(اختياري) أدخل تعليقا يساعدك على تحديد هذا الرمز المميز في المستقبل، وتغيير العمر الافتراضي للرمز المميز وهو 90 يوما. لإنشاء رمز مميز بدون مدة بقاء (غير مستحسن)، اترك مربع مدة البقاء (أيام) فارغا (فارغ).
انقر فوق "Generate".
انسخ الرمز المميز المعروض إلى موقع آمن، ثم انقر فوق تم.

إشعار

تأكد من حفظ الرمز المميز المنسخ في موقع آمن. لا تشارك الرمز المميز المنسخ مع الآخرين. إذا فقدت الرمز المميز المنسخ، فلا يمكنك إعادة إنشاء نفس الرمز المميز بالضبط. بدلا من ذلك، يجب تكرار هذا الإجراء لإنشاء رمز مميز جديد. إذا فقدت الرمز المميز الذي تم نسخه، أو كنت تعتقد أنه تم اختراق الرمز المميز، فإن Databricks يوصي بشدة بحذف هذا الرمز المميز على الفور من مساحة العمل الخاصة بك عن طريق النقر فوق أيقونة سلة المهملات (إبطال) بجوار الرمز المميز في صفحة رموز Access المميزة .

إذا لم تتمكن من إنشاء الرموز المميزة أو استخدامها في مساحة العمل الخاصة بك، فقد يرجع ذلك إلى قيام مسؤول مساحة العمل بتعطيل الرموز المميزة أو عدم منحك الإذن لإنشاء الرموز المميزة أو استخدامها. راجع مسؤول مساحة العمل أو المواضيع التالية:

لمصادقة Databricks SQL Connector ل Python، استخدم القصاصة البرمجية التالية. تفترض هذه القصاصة البرمجية أنك قمت بتعيين متغيرات البيئة التالية:

DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
DATABRICKS_TOKEN، قم بتعيين إلى رمز الوصول الشخصي Azure Databricks.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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 من جهاز إلى جهاز (M2M)

يدعم Databricks SQL Connector لإصدارات Python 2.7.0 والإصدارات الأحدث مصادقة OAuth من جهاز إلى جهاز (M2M). يجب عليك أيضا تثبيت Databricks SDK ل Python 0.18.0 أو أعلى (على سبيل المثال عن طريق تشغيل pip install databricks-sdk أو python -m pip install databricks-sdk).

لاستخدام Databricks SQL Connector ل Python مع مصادقة OAuth M2M، يجب عليك القيام بما يلي:

إنشاء كيان خدمة Azure Databricks في مساحة عمل Azure Databricks، وإنشاء سر OAuth لكيان الخدمة هذا.

لإنشاء كيان الخدمة وسر OAuth الخاص به، راجع مصادقة الوصول إلى Azure Databricks باستخدام كيان خدمة باستخدام OAuth (OAuth M2M). دون ملاحظة عن قيمة UUID أو Application ID الخاصة بكيان الخدمة، والقيمة السرية لسر OAuth الخاص بكيان الخدمة.
امنح كيان الخدمة هذا حق الوصول إلى نظام المجموعة أو المستودع الخاص بك.

لمنح كيان الخدمة حق الوصول إلى نظام المجموعة أو المستودع، راجع حساب الأذونات أو إدارة مستودع SQL.

DATABRICKS_SERVER_HOSTNAME تعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
DATABRICKS_CLIENT_ID، قم بتعيين إلى قيمة UUID أو معرف التطبيق الخاصة بكيان الخدمة.
DATABRICKS_CLIENT_SECRET، قم بتعيين إلى القيمة السرية لسر OAuth الخاص بكيان الخدمة.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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

لاستخدام Databricks SQL Connector ل Python مع مصادقة الرمز المميز لمعرف Microsoft Entra، يجب توفير Databricks SQL Connector ل Python مع الرمز المميز لمعرف Microsoft Entra. لإنشاء رمز مميز للوصول إلى معرف Microsoft Entra، قم بما يلي:

بالنسبة لمستخدم Azure Databricks، يمكنك استخدام Azure CLI. راجع الحصول على الرموز المميزة لمعرف Microsoft Entra للمستخدمين باستخدام Azure CLI.
للحصول على أساس خدمة معرف Microsoft Entra، راجع الحصول على رمز مميز للوصول إلى معرف Microsoft Entra باستخدام Azure CLI. لإنشاء كيان خدمة مدار من Microsoft Entra ID، راجع إدارة كيانات الخدمة.

الرموز المميزة لمعرف Microsoft Entra لها عمر افتراضي يبلغ حوالي ساعة واحدة. لإنشاء رمز مميز جديد لمعرف Microsoft Entra، كرر هذه العملية.

قم بتعيين DATABRICKS_SERVER_HOSTNAME إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
تعيين DATABRICKS_HTTP_PATH إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
قم بتعيين DATABRICKS_TOKEN إلى الرمز المميز لمعرف Microsoft Entra.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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 من مستخدم إلى جهاز (U2M)

يدعم Databricks SQL Connector لإصدارات Python 2.7.0 والإصدارات الأحدث مصادقة OAuth من مستخدم إلى جهاز (U2M). يجب عليك أيضا تثبيت Databricks SDK ل Python 0.19.0 أو أعلى (على سبيل المثال عن طريق تشغيل pip install databricks-sdk أو python -m pip install databricks-sdk).

لمصادقة Databricks SQL Connector ل Python باستخدام مصادقة OAuth U2M، استخدم القصاصة البرمجية التالية. تستخدم مصادقة OAuth U2M تسجيل الدخول البشري في الوقت الحقيقي والموافقة على مصادقة حساب مستخدم Azure Databricks الهدف. تفترض هذه القصاصة البرمجية أنك قمت بتعيين متغيرات البيئة التالية:

قم بتعيين DATABRICKS_SERVER_HOSTNAME إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
تعيين DATABRICKS_HTTP_PATH إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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

الأمثلة

توضح أمثلة التعليمات البرمجية التالية كيفية استخدام Databricks SQL Connector ل Python للاستعلام عن البيانات وإدراجها، والاستعلام عن بيانات التعريف، وإدارة المؤشرات والاتصالات، وتكوين التسجيل.

إشعار

توضح أمثلة التعليمات البرمجية التالية كيفية استخدام رمز وصول شخصي Azure Databricks للمصادقة. لاستخدام أنواع مصادقة Azure Databricks الأخرى المتوفرة بدلا من ذلك، راجع المصادقة.

يسترد server_hostnamehttp_pathمثال التعليمات البرمجية هذا قيم متغيرات الاتصال و و من access_token متغيرات البيئة هذه:

DATABRICKS_SERVER_HOSTNAME، الذي يمثل قيمة Server Hostname من المتطلبات.
DATABRICKS_HTTP_PATH، الذي يمثل قيمة مسار HTTP من المتطلبات.
DATABRICKS_TOKEN، الذي يمثل رمز الوصول المميز الخاص بك من المتطلبات.

يمكنك استخدام أساليب أخرى لاسترداد قيم متغيرات الاتصال هذه. استخدام متغيرات البيئة هو نهج واحد فقط بين العديد من.

بيانات الاستعلام
إدراج بيانات
بيانات تعريف الاستعلام
إدارة المؤشرات والاتصالات
إدارة الملفات في وحدات تخزين كتالوج Unity
تكوين التسجيل

بيانات الاستعلام

يوضح مثال التعليمات البرمجية التالي كيفية استدعاء Databricks SQL Connector ل Python لتشغيل أمر SQL أساسي على نظام مجموعة أو مستودع SQL. يقوم هذا الأمر بإرجاع أول صفين من trips الجدول في مخطط الكتالوج nyctaxi samples.

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)

إدراج بيانات

يوضح المثال التالي كيفية إدراج كميات صغيرة من البيانات (آلاف الصفوف):

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)

بالنسبة إلى كميات كبيرة من البيانات، يجب أولا تحميل البيانات إلى التخزين السحابي ثم تنفيذ الأمر COPY INTO .

بيانات تعريف الاستعلام

هناك أساليب مخصصة لاسترداد بيانات التعريف. يسترد المثال التالي بيانات التعريف حول الأعمدة في نموذج جدول:

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

إدارة المؤشرات والاتصالات

من أفضل الممارسات إغلاق أي اتصالات ومؤشرات لم تعد قيد الاستخدام. هذا يحرر الموارد على مجموعات Azure Databricks ومستودعات Databricks SQL.

يمكنك استخدام مدير سياق (بناء الجملة with المستخدم في الأمثلة السابقة) لإدارة الموارد، أو استدعاء 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

يمكنك Databricks SQL Connector من كتابة الملفات المحلية إلى وحدات تخزين كتالوج Unity، وتنزيل الملفات من وحدات التخزين، وحذف الملفات من وحدات التخزين، كما هو موضح في المثال التالي:

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

تكوين التسجيل

يستخدم Databricks SQL Connector وحدة تسجيل Python القياسية. يمكنك تكوين مستوى التسجيل على غرار ما يلي:

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

الاختبار

لاختبار التعليمات البرمجية الخاصة بك، استخدم أطر عمل اختبار Python مثل pytest. لاختبار التعليمات البرمجية الخاصة بك في ظل ظروف محاكاة دون استدعاء نقاط نهاية Azure Databricks REST API أو تغيير حالة حسابات Azure Databricks أو مساحات العمل الخاصة بك، يمكنك استخدام مكتبات محاكاة Python مثل unittest.mock.

على سبيل المثال، بالنظر إلى الملف التالي المسمى helpers.py الذي يحتوي على get_connection_personal_access_token دالة تستخدم رمز وصول شخصي Azure Databricks لإرجاع اتصال بمساحة عمل Azure Databricks، ودالة select_nyctaxi_trips تستخدم الاتصال للحصول على العدد المحدد لصفوف البيانات من trips الجدول في مخطط الكتالوج samples nyctaxi :

# helpers.py

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

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

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

وبالنظر إلى الملف التالي المسمى main.py 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)

يختبر الملف التالي المسمى test_helpers.py ما إذا كانت الدالة select_nyctaxi_trips ترجع الاستجابة المتوقعة. بدلا من إنشاء اتصال حقيقي بمساحة العمل الهدف، يقوم هذا الاختبار بالسخرية من كائن Connection . كما يسخر الاختبار من بعض البيانات التي تتوافق مع المخطط والقيم الموجودة في البيانات الحقيقية. يقوم الاختبار بإرجاع البيانات المقلدة من خلال الاتصال الوهمي ثم يتحقق مما إذا كانت إحدى قيم صفوف البيانات المقلدة تطابق القيمة المتوقعة.

# 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 تحتوي على عبارة SELECT وبالتالي لا تغير حالة trips الجدول، فإن الاستنساخ غير مطلوب مطلقا في هذا المثال. ومع ذلك، يمكنك الاستنساخ من تشغيل الاختبارات بسرعة دون انتظار إجراء اتصال فعلي بمساحة العمل. كما يمكنك الاستنساخ من إجراء اختبارات محاكاة عدة مرات للوظائف التي قد تغير حالة الجدول، مثل INSERT INTOو UPDATEو DELETE FROM.

الحزمة

databricks-sql-connector

الاستخدام: pip install databricks-sql-connector

راجع أيضا databricks-sql-connector في فهرس حزمة Python (PyPI).

الوحدة النمطية

databricks.sql

الاستخدام: from databricks import sql

الفصول

تتضمن الفئات المحددة ما يلي:

الفصول
`Connection` جلسة عمل على مورد حساب Azure Databricks.
`Cursor` آلية للاجتياز عبر سجلات البيانات.
`Row` صف بيانات في نتيجة استعلام SQL.

`Connection` فصل

لإنشاء كائن Connection ، قم باستدعاء databricks.sql.connect الأسلوب باستخدام المعلمات التالية:

المعلمات
`server_hostname` النوع: `str` اسم مضيف الخادم للمجموعة أو مستودع SQL. للحصول على اسم مضيف الخادم، راجع الإرشادات الواردة سابقا في هذه المقالة. هذه المعلمة مطلوبة. مثال: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` النوع: `str` مسار HTTP للمجموعة أو مستودع SQL. للحصول على مسار HTTP، راجع الإرشادات الواردة سابقا في هذه المقالة. هذه المعلمة مطلوبة. مثال: `sql/protocolv1/o/1234567890123456/1234-567890-test123` لنظام مجموعة. `/sql/1.0/warehouses/a1b234c567d8e9fa` لمستودع SQL.
`access_token`, `auth_type` النوع: `str` معلومات حول إعدادات مصادقة Azure Databricks. للحصول على التفاصيل، راجع المصادقة.
`session_configuration` النوع: `dict[str, Any]` قاموس معلمات تكوين جلسة Spark. تعيين تكوين يعادل استخدام `SET key=val` أمر SQL. قم بتشغيل أمر `SET -v` SQL للحصول على قائمة كاملة بالتكوينات المتوفرة. الإعدادات الافتراضية لـ `None`. هذه المعلمة اختيارية. مثال: `{"spark.sql.variable.substitute": True}`
`http_headers` النوع: `List[Tuple[str, str]]]` أزواج إضافية (مفتاح، قيمة) لتعيينها في رؤوس HTTP على كل طلب RPC يقوم به العميل. لن يقوم الاستخدام النموذجي بتعيين أي رؤوس HTTP إضافية. الإعدادات الافتراضية لـ `None`. هذه المعلمة اختيارية. منذ الإصدار 2.0
`catalog` النوع: `str` الكتالوج الأولي لاستخدامه للاتصال. الإعدادات الافتراضية ل `None` (في هذه الحالة سيتم استخدام الكتالوج الافتراضي، عادة `hive_metastore`). هذه المعلمة اختيارية. منذ الإصدار 2.0
`schema` النوع: `str` المخطط الأولي لاستخدامه للاتصال. الإعدادات الافتراضية إلى `None` (وفي هذه الحالة سيتم استخدام المخطط `default` الافتراضي). هذه المعلمة اختيارية. منذ الإصدار 2.0
`use_cloud_fetch` النوع: `bool` `True` لإرسال طلبات الإحضار مباشرة إلى مخزن عناصر السحابة لتنزيل مجموعات من البيانات. `False` (الافتراضي) لإرسال طلبات الإحضار مباشرة إلى Azure Databricks. إذا `use_cloud_fetch` تم تعيين إلى `True` ولكن تم حظر الوصول إلى الشبكة، فستفشل طلبات الإحضار. منذ الإصدار 2.8

تتضمن الأساليب المحددة Connection ما يلي:

الأساليب
`close` إغلاق الاتصال بقاعدة البيانات وإصدار كافة الموارد المقترنة على الخادم. أي استدعاءات إضافية لهذا الاتصال ستطرح `Error`. لا توجد معلمات. لا توجد قيمة إرجاع.
`cursor` إرجاع كائن جديد `Cursor` يمكن الاجتياز عبر السجلات في قاعدة بيانات. لا توجد معلمات.

`Cursor` فصل

لإنشاء كائن Cursor ، قم باستدعاء Connection أسلوب الفئة cursor .

تتضمن السمات المحددة Cursor ما يلي:

السمات

السمات
`arraysize` يستخدم مع `fetchmany` الأسلوب ، يحدد حجم المخزن المؤقت الداخلي، وهو أيضا عدد الصفوف التي يتم جلبها فعليا من الخادم في كل مرة. القيمة الافتراضية هي `10000`. للحصول على نتائج ضيقة (النتائج التي لا يحتوي فيها كل صف على الكثير من البيانات)، يجب زيادة هذه القيمة للحصول على أداء أفضل. الوصول للقراءة والكتابة.
`description` يحتوي على Python `list` من `tuple` الكائنات. يحتوي كل عنصر من هذه `tuple` الكائنات على 7 قيم، مع أول عنصرين من كل `tuple` عنصر يحتوي على معلومات تصف عمود نتيجة واحدة كما يلي: - `name`: اسم العمود. - `type_code`: سلسلة تمثل نوع العمود. على سبيل المثال، سيكون لعمود عدد صحيح رمز نوع من `int`. لا يتم تنفيذ العناصر ال 5 المتبقية من كل عنصر من 7 عناصر `tuple` ، ولا يتم تعريف قيمها. عادة ما يتم إرجاعها ك 4 `None` القيم متبوعة بقيمة واحدة `True` . الوصول للقراءة فقط.

arraysize

يستخدم مع fetchmany الأسلوب ، يحدد حجم المخزن المؤقت الداخلي، وهو أيضا عدد الصفوف التي يتم جلبها فعليا من الخادم في كل مرة. القيمة الافتراضية هي 10000. للحصول على نتائج ضيقة (النتائج التي لا يحتوي فيها كل صف على الكثير من البيانات)، يجب زيادة هذه القيمة للحصول على أداء أفضل.

الوصول للقراءة والكتابة.

description

يحتوي على Python list من tuple الكائنات. يحتوي كل عنصر من هذه tuple الكائنات على 7 قيم، مع أول عنصرين من كل tuple عنصر يحتوي على معلومات تصف عمود نتيجة واحدة كما يلي:

- name: اسم العمود.
- type_code: سلسلة تمثل نوع العمود. على سبيل المثال، سيكون لعمود عدد صحيح رمز نوع من int.

لا يتم تنفيذ العناصر ال 5 المتبقية من كل عنصر من 7 عناصر tuple ، ولا يتم تعريف قيمها. عادة ما يتم إرجاعها ك 4
None القيم متبوعة بقيمة واحدة True .

الوصول للقراءة فقط.

تتضمن الأساليب المحددة Cursor ما يلي:

الأساليب
`cancel` يقطع تشغيل أي استعلام قاعدة بيانات أو أمر بدأه المؤشر. لتحرير الموارد المقترنة على الخادم، اتصل ب `close` الأسلوب بعد استدعاء `cancel` الأسلوب . لا توجد معلمات. لا توجد قيمة إرجاع.
`close` إغلاق المؤشر وإصدار الموارد المقترنة على الخادم. قد يؤدي إغلاق مؤشر مغلق بالفعل إلى حدوث خطأ. لا توجد معلمات. لا توجد قيمة إرجاع.
`execute` إعداد استعلام أو أمر قاعدة بيانات ثم تشغيله. لا توجد قيمة إرجاع. المعلمات: `operation` النوع: `str` الاستعلام أو الأمر للتحضير ثم التشغيل. هذه المعلمة مطلوبة. مثال بدون المعلمة `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` مثال مع المعلمة `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` النوع: القاموس سلسلة من المعلمات لاستخدامها مع المعلمة `operation` . هذه المعلمة اختيارية. الافتراضي هو `None`.
`executemany` يقوم بإعداد ثم تشغيل استعلام قاعدة بيانات أو أمر باستخدام كافة تسلسلات المعلمات في الوسيطة `seq_of_parameters` . يتم الاحتفاظ بمجموعة النتائج النهائية فقط. لا توجد قيمة إرجاع. المعلمات: `operation` النوع: `str` الاستعلام أو الأمر للتحضير ثم التشغيل. هذه المعلمة مطلوبة. `seq_of_parameters` النوع: `list` من `dict` تسلسل من العديد من مجموعات قيم المعلمات لاستخدامها مع `operation` البارامتر. هذه المعلمة مطلوبة.
`catalogs` تنفيذ استعلام بيانات التعريف حول الكتالوجات. يجب بعد ذلك إحضار النتائج الفعلية باستخدام `fetchmany` أو `fetchall`. تتضمن الحقول المهمة في مجموعة النتائج ما يلي: - اسم الحقل: `TABLE_CAT`. النوع: `str`. اسم الكتالوج. لا توجد معلمات. لا توجد قيمة إرجاع. منذ الإصدار 1.0
`schemas` تنفيذ استعلام بيانات التعريف حول المخططات. يجب بعد ذلك إحضار النتائج الفعلية باستخدام `fetchmany` أو `fetchall`. تتضمن الحقول المهمة في مجموعة النتائج ما يلي: - اسم الحقل: `TABLE_SCHEM`. النوع: `str`. اسم المخطط. - اسم الحقل: `TABLE_CATALOG`. النوع: `str`. الكتالوج الذي ينتمي إليه المخطط. لا توجد قيمة إرجاع. منذ الإصدار 1.0 المعلمات: `catalog_name` النوع: `str` اسم كتالوج لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `schema_name` النوع: `str` اسم مخطط لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية.
`tables` تنفيذ استعلام بيانات التعريف حول الجداول وطرق العرض. يجب بعد ذلك إحضار النتائج الفعلية باستخدام `fetchmany` أو `fetchall`. تتضمن الحقول المهمة في مجموعة النتائج ما يلي: - اسم الحقل: `TABLE_CAT`. النوع: `str`. الكتالوج الذي ينتمي إليه الجدول. - اسم الحقل: `TABLE_SCHEM`. النوع: `str`. المخطط الذي ينتمي إليه الجدول. - اسم الحقل: `TABLE_NAME`. النوع: `str`. اسم الجدول. - اسم الحقل: `TABLE_TYPE`. النوع: `str`. نوع العلاقة، على سبيل المثال `VIEW` أو `TABLE` (ينطبق على Databricks Runtime 10.4 LTS وما فوق بالإضافة إلى Databricks SQL؛ ترجع الإصدارات السابقة من Databricks Runtime سلسلة فارغة). لا توجد قيمة إرجاع. منذ الإصدار 1.0 المعلمات `catalog_name` النوع: `str` اسم كتالوج لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `schema_name` النوع: `str` اسم مخطط لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `table_name` النوع: `str` اسم جدول لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `table_types` النوع: `List[str]` قائمة أنواع الجداول المراد مطابقتها، على سبيل المثال `TABLE` أو `VIEW`. هذه المعلمة اختيارية.
`columns` تنفيذ استعلام بيانات التعريف حول الأعمدة. يجب بعد ذلك إحضار النتائج الفعلية باستخدام `fetchmany` أو `fetchall`. تتضمن الحقول المهمة في مجموعة النتائج ما يلي: - اسم الحقل: `TABLE_CAT`. النوع: `str`. الكتالوج الذي ينتمي إليه العمود. - اسم الحقل: `TABLE_SCHEM`. النوع: `str`. المخطط الذي ينتمي إليه العمود. - اسم الحقل: `TABLE_NAME`. النوع: `str`. اسم الجدول الذي ينتمي إليه العمود. - اسم الحقل: `COLUMN_NAME`. النوع: `str`. اسم العمود. لا توجد قيمة إرجاع. منذ الإصدار 1.0 المعلمات: `catalog_name` النوع: `str` اسم كتالوج لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `schema_name` النوع: `str` اسم مخطط لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `table_name` النوع: `str` اسم جدول لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية. `column_name` النوع: `str` اسم عمود لاسترداد معلومات عنه. `%` يتم تفسير الحرف على أنه حرف بدل. هذه المعلمة اختيارية.
`fetchall` يحصل على كافة الصفوف (أو كافة الصفوف المتبقية) للاستعلام. لا توجد معلمات. إرجاع كافة صفوف الاستعلام (أو كافة الصفوف المتبقية) ك Python `list` `Row` الكائنات. `Error` يطرح إذا لم يرجع الاستدعاء السابق إلى `execute` الأسلوب أي بيانات أو لم يتم إجراء أي `execute` استدعاء بعد.
`fetchmany` الحصول على الصفوف التالية من استعلام. إرجاع ما يصل إلى `size` (أو السمة `arraysize` إذا `size` لم يتم تحديدها) للصفوف التالية من استعلام ك Python `list` للكائنات `Row` . إذا كان هناك أقل من `size` الصفوف المتبقية ليتم إحضارها، إرجاع كافة الصفوف المتبقية. `Error` يطرح إذا لم يرجع الاستدعاء السابق إلى `execute` الأسلوب أي بيانات أو لم يتم إجراء أي `execute` استدعاء بعد. المعلمات: `size` النوع: `int` عدد الصفوف التالية التي يجب الحصول عليها. هذه المعلمة اختيارية. إذا لم يتم تحديدها، يتم استخدام قيمة السمة `arraysize` . مثال: `cursor.fetchmany(10)`
`fetchone` يحصل على الصف التالي من مجموعة البيانات. لا توجد معلمات. إرجاع الصف التالي من مجموعة البيانات كتسلسل واحد ك Python `tuple` أو إرجاع `None` إذا لم يكن هناك المزيد من البيانات المتوفرة. `Error` يطرح إذا لم يرجع الاستدعاء السابق إلى `execute` الأسلوب أي بيانات أو لم يتم إجراء أي `execute` استدعاء بعد.
`fetchall_arrow` يحصل على كافة الصفوف (أو كافة الصفوف المتبقية) من استعلام، ككائن PyArrow `Table` . يجب استخدام `fetchmany_arrow` الاستعلامات التي ترجع كميات كبيرة جدا من البيانات بدلا من ذلك لتقليل استهلاك الذاكرة. لا توجد معلمات. إرجاع كافة صفوف الاستعلام (أو كافة الصفوف المتبقية) كجدول PyArrow. `Error` يطرح إذا لم يرجع الاستدعاء السابق إلى `execute` الأسلوب أي بيانات أو لم يتم إجراء أي `execute` استدعاء بعد. منذ الإصدار 2.0
`fetchmany_arrow` يحصل على الصفوف التالية من استعلام ككائن PyArrow `Table` . إرجاع ما يصل إلى الوسيطة `size` (أو السمة `arraysize` إذا `size` لم يتم تحديدها) للصفوف التالية من استعلام ك Python PyArrow `Table` كائن. `Error` يطرح إذا لم يرجع الاستدعاء السابق إلى `execute` الأسلوب أي بيانات أو لم يتم إجراء أي `execute` استدعاء بعد. منذ الإصدار 2.0 المعلمات: `size` النوع: `int` عدد الصفوف التالية التي يجب الحصول عليها. هذه المعلمة اختيارية. إذا لم يتم تحديدها، يتم استخدام قيمة السمة `arraysize` . مثال: `cursor.fetchmany_arrow(10)`

`Row` فصل

فئة الصف هي بنية بيانات تشبه المجموعة التي تمثل صف نتيجة فردي. إذا كان الصف يحتوي على عمود بالاسم "my_column"، يمكنك الوصول إلى "my_column" حقل عبر row row.my_column. يمكنك أيضا استخدام المؤشرات الرقمية للوصول إلى الحقول، على سبيل المثال row[0]. إذا لم يكن اسم العمود مسموحا به كاسم أسلوب سمة (على سبيل المثال، يبدأ برقم)، فيمكنك الوصول إلى الحقل ك row["1_my_column"].

منذ الإصدار 1.0

تتضمن الأساليب المحددة Row ما يلي:

| asDict

إرجاع تمثيل قاموس للصف، الذي تمت فهرسته بواسطة أسماء الحقول. إذا كانت هناك أسماء حقول مكررة، إرجاع أحد الحقول المكررة (ولكن واحد فقط) في القاموس. الحقل المكرر الذي يتم إرجاعه غير معرف.

لا توجد معلمات.

إرجاع أحد dict الحقول. |

نوع التحويلات

يعين الجدول التالي أنواع بيانات Apache Spark SQL إلى مكافئات نوع بيانات Python.

نوع بيانات Apache Spark SQL	نوع بيانات 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`

استكشاف الأخطاء وإصلاحها

`tokenAuthWrapperInvalidAccessToken: Invalid access token` رسالة

المشكلة: عند تشغيل التعليمات البرمجية الخاصة بك، سترى رسالة مشابهة ل Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

السبب المحتمل: القيمة التي تم تمريرها إلى access_token ليست رمز وصول شخصي صالح ل Azure Databricks.

الإصلاح الموصى به: تحقق من صحة القيمة التي تم تمريرها إلى access_token وحاول مرة أخرى.

`gaierror(8, 'nodename nor servname provided, or not known')` رسالة

المشكلة: عند تشغيل التعليمات البرمجية الخاصة بك، سترى رسالة مشابهة ل Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

السبب المحتمل: القيمة التي تم تمريرها إلى server_hostname ليست اسم المضيف الصحيح.

الإصلاح الموصى به: تحقق من صحة القيمة التي تم تمريرها إلى server_hostname وحاول مرة أخرى.

لمزيد من المعلومات حول العثور على اسم مضيف الخادم، راجع الحصول على تفاصيل الاتصال لمورد حساب Azure Databricks.

`IpAclError` رسالة

المشكلة: عند تشغيل التعليمات البرمجية الخاصة بك، سترى الرسالة Error during request to server: IpAclValidation عند محاولة استخدام الموصل على دفتر ملاحظات Azure Databricks.

السبب المحتمل: قد يكون لديك قائمة السماح ب IP ممكنة لمساحة عمل Azure Databricks. مع إدخال قائمة السماح ب IP، لا يسمح بالاتصالات من مجموعات Spark مرة أخرى إلى مستوى التحكم بشكل افتراضي.

الإصلاح الموصى به: اطلب من المسؤول إضافة الشبكة الفرعية لمستوى الحوسبة إلى قائمة السماح ب IP.

الموارد الإضافية

لمزيد من المعلومات، راجع:

Databricks SQL Connector لمستودع Python على GitHub
أنواع البيانات
الأنواع المضمنة (ل boolوbytearrayfloatint) strعلى موقع Python على الويب
التاريخ والوقت (ل datetime.date و datatime.datetime) على موقع Python على الويب
رقم عشري (ل decimal.Decimal) على موقع Python على الويب
الثوابت المضمنة (ل NoneType) على موقع Python على الويب

مشاركة عبر

Databricks SQL Connector ل Python

المتطلبات

الشروع في العمل

نظام المجموعة

مستودع SQL

المصادقة

مصادقة رمز الوصول الشخصي ل Databricks

مصادقة OAuth من جهاز إلى جهاز (M2M)

مصادقة الرمز المميز لمعرف Microsoft Entra

مصادقة OAuth من مستخدم إلى جهاز (U2M)

الأمثلة

بيانات الاستعلام

إدراج بيانات

بيانات تعريف الاستعلام

إدارة المؤشرات والاتصالات

إدارة الملفات في وحدات تخزين كتالوج Unity

تكوين التسجيل

الاختبار

مرجع واجهة برمجة التطبيقات

الحزمة

الوحدة النمطية

الفصول

`Connection` فصل

`Cursor` فصل

`Row` فصل

نوع التحويلات

استكشاف الأخطاء وإصلاحها

`tokenAuthWrapperInvalidAccessToken: Invalid access token` رسالة

`gaierror(8, 'nodename nor servname provided, or not known')` رسالة

`IpAclError` رسالة

الموارد الإضافية

الملاحظات

الموارد الإضافية

مشاركة عبر

Databricks SQL Connector ل Python

المتطلبات

الشروع في العمل

نظام المجموعة

مستودع SQL

المصادقة

مصادقة رمز الوصول الشخصي ل Databricks

مصادقة OAuth من جهاز إلى جهاز (M2M)

مصادقة الرمز المميز لمعرف Microsoft Entra

مصادقة OAuth من مستخدم إلى جهاز (U2M)

الأمثلة

بيانات الاستعلام

إدراج بيانات

بيانات تعريف الاستعلام

إدارة المؤشرات والاتصالات

إدارة الملفات في وحدات تخزين كتالوج Unity

تكوين التسجيل

الاختبار

مرجع واجهة برمجة التطبيقات

الحزمة

الوحدة النمطية

الفصول

Connection فصل

Cursor فصل

Row فصل

نوع التحويلات

استكشاف الأخطاء وإصلاحها

tokenAuthWrapperInvalidAccessToken: Invalid access token رسالة

gaierror(8, 'nodename nor servname provided, or not known') رسالة

IpAclError رسالة

الموارد الإضافية

الملاحظات

الموارد الإضافية

`Connection` فصل

`Cursor` فصل

`Row` فصل

`tokenAuthWrapperInvalidAccessToken: Invalid access token` رسالة

`gaierror(8, 'nodename nor servname provided, or not known')` رسالة

`IpAclError` رسالة