مشاركة عبر

Databricks SQL CLI

  • مقالة

إشعار

تغطي هذه المقالة Databricks SQL CLI، والتي يتم توفيرها كما هي ولا تدعمها Databricks من خلال قنوات الدعم التقني للعملاء. يمكن توصيل الأسئلة وطلبات الميزات من خلال صفحة المشكلات في مستودع databricks/databricks-sql-cli على GitHub.

تمكنك واجهة سطر أوامر Databricks SQL (Databricks SQL CLI) من تشغيل استعلامات SQL على مستودعات Databricks SQL الموجودة لديك من الوحدة الطرفية أو موجه أوامر Windows بدلا من مواقع مثل محرر Databricks SQL أو دفتر ملاحظات Azure Databricks. من سطر الأوامر، يمكنك الحصول على ميزات الإنتاجية مثل الاقتراحات وتمييز بناء الجملة.

المتطلبات

  • مستودع Databricks SQL واحد على الأقل. أنشئ مستودعا، إذا لم يكن لديك مستودع بالفعل.
  • Python 3.7 أو أعلى. للتحقق مما إذا كان Python مثبتا لديك، قم بتشغيل الأمر python --version من المحطة الطرفية أو موجه الأوامر. (في بعض الأنظمة، قد تحتاج إلى إدخال python3 بدلا من ذلك.) قم بتثبيت Python، إذا لم يكن مثبتا لديك بالفعل.
  • pip، مثبت الحزمة ل Python. تثبيت الإصدارات الأحدث من Python pip بشكل افتراضي. للتحقق مما إذا كنت قد قمت pip بتثبيته، قم بتشغيل الأمر pip --version من المحطة الطرفية أو موجه الأوامر. (في بعض الأنظمة، قد تحتاج إلى إدخال pip3 بدلا من ذلك.) تثبيت pip، إذا لم يكن لديك مثبتا بالفعل.
  • (اختياري) أداة مساعدة لإنشاء وإدارة بيئات Python الظاهرية، مثل venv. تساعد البيئات الظاهرية على ضمان استخدام الإصدارات الصحيحة من Python وDatabricks SQL CLI معا. إعداد البيئات الظاهرية واستخدامها خارج نطاق هذه المقالة. لمزيد من المعلومات، راجع إنشاء بيئات ظاهرية.

تثبيت Databricks SQL CLI

بعد تلبية المتطلبات، قم بتثبيت حزمة Databricks SQL CLI من فهرس حزم Python (PyPI). يمكنك استخدام pip لتثبيت حزمة Databricks SQL CLI من PyPI عن طريق تشغيل pip بأحد الأوامر التالية.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

لترقية إصدار مثبت مسبقا من Databricks SQL CLI، قم بتشغيل pip بأحد الأوامر التالية.

pip install databricks-sql-cli --upgrade

# Or...

python -m pip install databricks-sql-cli --upgrade

للتحقق من الإصدار المثبت من Databricks SQL CLI، قم بتشغيل pip بأحد الأوامر التالية.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

المصادقة

للمصادقة، يجب عليك تزويد Databricks SQL CLI بتفاصيل اتصال المستودع الخاص بك. على وجه التحديد، تحتاج إلى قيم اسم مضيف الخادم ومسار HTTP. يجب عليك أيضا منتج Databricks SQL CLI ببيانات اعتماد المصادقة المناسبة.

يدعم Databricks SQL CLI مصادقة رمز الوصول الشخصي Databricks. الرموز المميزة لمعرف Microsoft Entra غير مدعومة.

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

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

إشعار

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

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

يمكنك توفير معلومات المصادقة هذه إلى Databricks SQL CLI بعدة طرق:

  • في dbsqlclirc ملف الإعدادات في موقعه الافتراضي (أو عن طريق تحديد ملف إعدادات بديل من خلال الخيار في --clirc كل مرة تقوم فيها بتشغيل أمر باستخدام Databricks SQL CLI). راجع ملف الإعدادات.
  • عن طريق تعيين DBSQLCLI_HOST_NAMEDBSQLCLI_HTTP_PATH متغيرات البيئة وDBSQLCLI_ACCESS_TOKEN. راجع متغيرات البيئة.
  • عن طريق تحديد --hostnameالخيارات و --http-pathو في --access-token كل مرة تقوم فيها بتشغيل أمر باستخدام Databricks SQL CLI. راجع خيارات الأمر.

إشعار

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

كلما قمت بتشغيل Databricks SQL CLI، فإنه يبحث عن تفاصيل المصادقة بالترتيب التالي ويتوقف عند العثور على المجموعة الأولى من التفاصيل:

  1. --hostname--http-pathالخيارات و و--access-token.
  2. DBSQLCLI_HOST_NAMEDBSQLCLI_HTTP_PATH متغيرات البيئة و وDBSQLCLI_ACCESS_TOKEN.
  3. dbsqlclirc ملف الإعدادات في موقعه الافتراضي (أو ملف إعدادات بديل يحدده --clirc الخيار).

ملف الإعدادات

لاستخدام dbsqlclirc ملف الإعدادات لتزويد Databricks SQL CLI بتفاصيل المصادقة لمستودع Databricks SQL، قم بتشغيل Databricks SQL CLI لأول مرة، كما يلي:

dbsqlcli

يقوم Databricks SQL CLI بإنشاء ملف إعدادات لك، في ~/.dbsqlcli/dbsqlclirc Unix وLinux وmacOS وفي %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc أو %USERPROFILE%\.dbsqlcli\dbsqlclirc على Windows. لتخصيص هذا الملف:

  1. استخدم محرر نص لفتح الملف وتحريره dbsqlclirc .

  2. قم بالتمرير إلى القسم التالي:

    # [credentials]
# host_name = ""
# http_path = ""
# access_token = ""

  3. قم بإزالة الأحرف الأربعة # ، و:

    1. بجوار host_name، أدخل قيمة اسم مضيف خادم المستودع الخاص بك من المتطلبات بين الأحرف"".
    2. بجوار http_path، أدخل قيمة مسار HTTP للمستودع الخاص بك من المتطلبات بين الأحرف"".
    3. بجوار access_token، أدخل قيمة الرمز المميز للوصول الشخصي من المتطلبات بين الأحرف "" .

    على سبيل المثال:

    [credentials]
host_name = "adb-12345678901234567.8.azuredatabricks.net"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"

  4. احفظ الملف dbsqlclirc.

بدلا من ذلك، بدلا من استخدام dbsqlclirc الملف في موقعه الافتراضي، يمكنك تحديد ملف في موقع مختلف عن طريق إضافة --clirc خيار الأمر والمسار إلى الملف البديل. يجب أن تتوافق محتويات هذا الملف البديل مع بناء الجملة السابق.

متغيرات البيئة

لاستخدام DBSQLCLI_HOST_NAMEDBSQLCLI_HTTP_PATHمتغيرات البيئة و و DBSQLCLI_ACCESS_TOKEN لتزويد Databricks SQL CLI بتفاصيل المصادقة لمستودع Databricks SQL، قم بما يلي:

Unix وLinux وmacOS

لتعيين متغيرات البيئة لجلسة المحطة الطرفية الحالية فقط، قم بتشغيل الأوامر التالية. لتعيين متغيرات البيئة لجميع جلسات المحطة الطرفية، أدخل الأوامر التالية في ملف بدء تشغيل shell ثم أعد تشغيل المحطة الطرفية. في الأوامر التالية، استبدل قيمة:

  • DBSQLCLI_HOST_NAMEمع قيمة اسم مضيف خادم المستودع الخاص بك من المتطلبات.
  • DBSQLCLI_HTTP_PATHمع قيمة مسار HTTP لمستودعك من المتطلبات.
  • DBSQLCLI_ACCESS_TOKEN مع قيمة الرمز المميز للوصول الشخصي من المتطلبات.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

لتعيين متغيرات البيئة لجلسة موجه الأوامر الحالية فقط، قم بتشغيل الأوامر التالية، واستبدل قيمة:

  • DBSQLCLI_HOST_NAMEمع قيمة اسم مضيف خادم المستودع الخاص بك من المتطلبات.
  • DBSQLCLI_HTTP_PATHمع قيمة مسار HTTP لمستودعك من المتطلبات.
  • DBSQLCLI_ACCESS_TOKEN مع قيمة الرمز المميز للوصول الشخصي من المتطلبات.:
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

لتعيين متغيرات البيئة لكافة جلسات موجه الأوامر، قم بتشغيل الأوامر التالية ثم أعد تشغيل موجه الأوامر، واستبدل قيمة:

  • DBSQLCLI_HOST_NAMEمع قيمة اسم مضيف خادم المستودع الخاص بك من المتطلبات.
  • DBSQLCLI_HTTP_PATHمع قيمة مسار HTTP لمستودعك من المتطلبات.
  • DBSQLCLI_ACCESS_TOKEN مع قيمة الرمز المميز للوصول الشخصي من المتطلبات.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

خيارات الأوامر

لاستخدام --hostname--http-pathالخيارات و و --access-token لتزويد Databricks SQL CLI بتفاصيل المصادقة لمستودع Databricks SQL، قم بما يلي:

قم بما يلي في كل مرة تقوم فيها بتشغيل أمر باستخدام Databricks SQL CLI:

  • --hostname حدد الخيار وقيمة اسم مضيف خادم المستودع الخاص بك من المتطلبات.
  • حدد الخيار وقيمة --http-path مسار HTTP للمستودع الخاص بك من المتطلبات.
  • حدد الخيار وقيمة --access-token الرمز المميز للوصول الشخصي من المتطلبات.

على سبيل المثال:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

مصادر الاستعلام

يمكنك Databricks SQL CLI من تشغيل الاستعلامات بالطرق التالية:

  • من سلسلة استعلام.
  • من ملف.
  • في نهج حلقة القراءة والتقييم والطباعة (REPL). يوفر هذا الأسلوب اقتراحات أثناء الكتابة.

سلسلة الاستعلام

لتشغيل استعلام كسلسلة، استخدم -e الخيار متبوعا بالاستعلام، ممثلا كسلسلة. على سبيل المثال:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"

إخراج:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

لتبديل تنسيقات الإخراج، استخدم --table-format الخيار مع قيمة مثل ascii تنسيق جدول ASCII، على سبيل المثال:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii

إخراج:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

للحصول على قائمة بقيم تنسيق الإخراج المتوفرة، راجع تعليقات table_format الإعداد في dbsqlclirc الملف.

الملف

لتشغيل ملف يحتوي على SQL، استخدم -e الخيار متبوعا بالمسار إلى .sql ملف. على سبيل المثال:

dbsqlcli -e my-query.sql

محتويات ملف المثال my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

إخراج:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

لتبديل تنسيقات الإخراج، استخدم --table-format الخيار مع قيمة مثل ascii تنسيق جدول ASCII، على سبيل المثال:

dbsqlcli -e my-query.sql --table-format ascii

إخراج:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

للحصول على قائمة بقيم تنسيق الإخراج المتوفرة، راجع تعليقات table_format الإعداد في dbsqlclirc الملف.

REPL

لإدخال وضع حلقة القراءة-التقييم-الطباعة (REPL) المحدد في قاعدة البيانات الافتراضية، قم بتشغيل الأمر التالي:

dbsqlcli

يمكنك أيضا إدخال وضع REPL المحدد في قاعدة بيانات معينة، عن طريق تشغيل الأمر التالي:

dbsqlcli <database-name>

على سبيل المثال:

dbsqlcli default

للخروج من وضع REPL، قم بتشغيل الأمر التالي:

exit

في وضع REPL، يمكنك استخدام الأحرف والمفاتيح التالية:

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

على سبيل المثال:

dbsqlcli default

hostname:default> SELECT * FROM diamonds LIMIT 2;

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

2 rows in set
Time: 0.703s

hostname:default> exit

تسجيل الدخول

يسجل Databricks SQL CLI رسائله إلى الملف ~/.dbsqlcli/app.log بشكل افتراضي. لتغيير اسم الملف أو الموقع هذا، قم بتغيير قيمة log_file الإعداد في dbsqlclirc ملف الإعدادات.

بشكل افتراضي، يتم تسجيل الرسائل على INFO مستوى السجل وما دونه. لتغيير مستوى السجل هذا، قم بتغيير قيمة log_level الإعداد في dbsqlclirc ملف الإعدادات. تتضمن CRITICALقيم مستوى السجل المتوفرة و WARNINGERRORINFOو و و DEBUG و يتم تقييمها بهذا الترتيب. NONE يعطل التسجيل.

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