Databricks SQL CLI

Artikel
08/29/2024

Catatan

Artikel ini membahas Databricks SQL CLI, yang disediakan apa adanya dan tidak didukung oleh Databricks melalui saluran dukungan teknis pelanggan. Pertanyaan dan permintaan fitur dapat dikomunikasikan melalui halaman Masalah repositori databricks/databricks-sql-cli di GitHub.

Antarmuka baris perintah Databricks SQL (Databricks SQL CLI) memungkinkan Anda menjalankan kueri SQL pada gudang Databricks SQL yang ada dari terminal atau Perintah Windows, bukan dari lokasi seperti editor Databricks SQL atau buku catatan Azure Databricks. Dari baris perintah, Anda mendapatkan fitur produktivitas seperti saran dan penyorotan sintaksis.

Persyaratan

Setidaknya satu gudang Databricks SQL. Buat gudang, jika Anda belum memilikinya.
Python 3.7 atau lebih tinggi. Untuk memeriksa apakah Anda telah menginstal Python, jalankan perintah python --version dari terminal atau Prompt Perintah Anda. (Pada beberapa sistem, Anda mungkin perlu memasukkan python3 sebagai gantinya.) Instal Python, jika Anda belum menginstalnya.
pip, alat penginstal paket untuk Python. Versi penginstalan pip Python yang lebih baru secara default. Untuk memeriksa apakah Anda telah pip menginstal, jalankan perintah pip --version dari terminal atau Prompt Perintah Anda. (Pada beberapa sistem, Anda mungkin perlu memasukkan pip3 sebagai gantinya.) Instal pip, jika Anda belum menginstalnya.
(Opsional) Utilitas untuk membuat dan mengelola lingkungan virtual Python, seperti venv. Lingkungan virtual membantu memastikan bahwa Anda menggunakan versi Python dan Databricks SQL CLI yang benar bersama-sama. Menyiapkan dan menggunakan lingkungan virtual berada di luar cakupan artikel ini. Untuk informasi selengkapnya, lihat Membuat Lingkungan Virtual.

Menginstal Databricks SQL CLI

Setelah Anda memenuhi persyaratan, instal paket Databricks SQL CLI dari Indeks Kemasan Python (PyPI). Anda dapat menggunakan pip untuk menginstal paket Databricks SQL CLI dari PyPI dengan menjalankan pip salah satu perintah berikut.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Untuk meningkatkan versi Databricks SQL CLI yang diinstal sebelumnya, jalankan pip dengan salah satu perintah berikut.

pip install databricks-sql-cli --upgrade

# Or...

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

Untuk memeriksa versi CLI Databricks SQL yang diinstal, jalankan pip dengan salah satu perintah berikut.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autentikasi

Untuk mengautentikasi, Anda harus menyediakan Databricks SQL CLI dengan detail koneksi gudang Anda. Secara khusus, Anda memerlukan nilai Nama host server dan jalur HTTP. Anda juga harus membuat Databricks SQL CLI dengan kredensial autentikasi yang tepat.

Databricks SQL CLI mendukung autentikasi token akses pribadi Databricks. Token ID Microsoft Entra tidak didukung.

Untuk menggunakan autentikasi token akses pribadi Azure Databricks, buat token akses pribadi sebagai berikut:

Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
Klik Pengembang.
Di samping Token akses, klik Kelola.
Klik Buat token baru.
(Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
Klik Buat.
Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.

Catatan

Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.

Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau topik berikut:

Anda dapat memberikan informasi autentikasi ini ke Databricks SQL CLI dengan beberapa cara:

dbsqlclirc Dalam file pengaturan di lokasi defaultnya (atau dengan menentukan file pengaturan alternatif melalui --clirc opsi setiap kali Anda menjalankan perintah dengan Databricks SQL CLI). Lihat File pengaturan.
Dengan mengatur DBSQLCLI_HOST_NAMEvariabel lingkungan , DBSQLCLI_HTTP_PATH dan DBSQLCLI_ACCESS_TOKEN . Lihat Variabel lingkungan.
Dengan menentukan --hostnameopsi , --http-path, dan --access-token setiap kali Anda menjalankan perintah dengan Databricks SQL CLI. Lihat Opsi perintah.

Catatan

File dbsqlclirc pengaturan harus ada, bahkan jika Anda mengatur variabel lingkungan sebelumnya atau menentukan opsi perintah sebelumnya atau keduanya.

Setiap kali Anda menjalankan Databricks SQL CLI, Databricks SQL CLI mencari detail autentikasi dalam urutan berikut dan berhenti saat menemukan serangkaian detail pertama:

Opsi --hostname, --http-path, dan --access-token .
Variabel DBSQLCLI_HOST_NAMElingkungan , DBSQLCLI_HTTP_PATH dan DBSQLCLI_ACCESS_TOKEN .
File dbsqlclirc pengaturan di lokasi defaultnya (atau file pengaturan alternatif yang ditentukan oleh --clirc opsi ).

File pengaturan

Untuk menggunakan dbsqlclirc file pengaturan untuk menyediakan Databricks SQL CLI dengan detail autentikasi untuk gudang Databricks SQL Anda, jalankan Databricks SQL CLI untuk pertama kalinya, sebagai berikut:

dbsqlcli

Databricks SQL CLI membuat file pengaturan untuk Anda, di ~/.dbsqlcli/dbsqlclirc Unix, Linux, dan macOS, dan di %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc atau %USERPROFILE%\.dbsqlcli\dbsqlclirc di Windows. Untuk menyesuaikan file ini:

Gunakan editor teks untuk membuka dan mengedit dbsqlclirc file.

Gulir ke bagian berikut:

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

Hapus empat # karakter, dan:
1. Di samping host_name, masukkan nilai Nama host Server gudang Anda dari persyaratan antara "" karakter.
2. Di samping http_path, masukkan nilai jalur HTTP gudang Anda dari persyaratan antara "" karakter.
3. Di samping access_token, masukkan nilai token akses pribadi Anda dari persyaratan antara "" karakter.
Contohnya:
```
[credentials]
host_name = "adb-12345678901234567.8.azuredatabricks.net"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"
```
Simpan file dbsqlclirc.

Atau, alih-alih menggunakan dbsqlclirc file di lokasi defaultnya, Anda dapat menentukan file di lokasi yang berbeda dengan menambahkan --clirc opsi perintah dan jalur ke file alternatif. Konten file alternatif tersebut harus sesuai dengan sintaks sebelumnya.

Variabel lingkungan

Untuk menggunakan DBSQLCLI_HOST_NAMEvariabel lingkungan , DBSQLCLI_HTTP_PATH, dan DBSQLCLI_ACCESS_TOKEN untuk menyediakan Databricks SQL CLI dengan detail autentikasi untuk gudang Databricks SQL Anda, lakukan hal berikut:

Unix, Linux, dan macOS

Untuk mengatur variabel lingkungan hanya untuk sesi terminal saat ini, jalankan perintah berikut. Untuk mengatur variabel lingkungan untuk semua sesi terminal, masukkan perintah berikut ke dalam file startup shell Anda lalu mulai ulang terminal Anda. Dalam perintah berikut, ganti nilai:

DBSQLCLI_HOST_NAMEdengan nilai nama host Server gudang Anda dari persyaratan.
DBSQLCLI_HTTP_PATHdengan nilai jalur HTTP gudang Anda dari persyaratan.
DBSQLCLI_ACCESS_TOKEN dengan nilai token akses pribadi Anda dari persyaratan.

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Untuk mengatur variabel lingkungan hanya untuk sesi Prompt Perintah saat ini, jalankan perintah berikut, ganti nilai:

DBSQLCLI_HOST_NAMEdengan nilai nama host Server gudang Anda dari persyaratan.
DBSQLCLI_HTTP_PATHdengan nilai jalur HTTP gudang Anda dari persyaratan.
DBSQLCLI_ACCESS_TOKEN dengan nilai token akses pribadi Anda dari persyaratan.:

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Untuk mengatur variabel lingkungan untuk semua sesi Prompt Perintah, jalankan perintah berikut lalu mulai ulang Prompt Perintah Anda, ganti nilai:

DBSQLCLI_HOST_NAMEdengan nilai nama host Server gudang Anda dari persyaratan.
DBSQLCLI_HTTP_PATHdengan nilai jalur HTTP gudang Anda dari persyaratan.
DBSQLCLI_ACCESS_TOKEN dengan nilai token akses pribadi Anda dari persyaratan.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opsi perintah

Untuk menggunakan --hostnameopsi , --http-path, dan --access-token untuk menyediakan Databricks SQL CLI dengan detail autentikasi untuk gudang Databricks SQL Anda, lakukan hal berikut:

Lakukan hal berikut setiap kali Anda menjalankan perintah dengan Databricks SQL CLI:

--hostname Tentukan opsi dan nilai Nama host Server gudang Anda dari persyaratan.
--http-path Tentukan opsi dan nilai jalur HTTP gudang Anda dari persyaratan.
Tentukan --access-token opsi dan nilai token akses pribadi Anda dari persyaratan.

Contohnya:

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

Sumber kueri

Databricks SQL CLI memungkinkan Anda menjalankan kueri dengan cara berikut:

Dari string kueri.
Dari file.
Dalam pendekatan read-evaluate-print loop (REPL). Pendekatan ini memberikan saran saat Anda mengetik.

Untai kueri

Untuk menjalankan kueri sebagai string, gunakan -e opsi diikuti oleh kueri, yang direpresentasikan sebagai string. Contohnya:

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

Output:

_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

Untuk beralih format output, gunakan --table-format opsi bersama dengan nilai seperti ascii untuk format tabel ASCII, misalnya:

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

Output:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Untuk daftar nilai format output yang tersedia, lihat komentar untuk table_format pengaturan dalam dbsqlclirc file.

File

Untuk menjalankan file yang berisi SQL, gunakan -e opsi diikuti dengan jalur ke .sql file. Contohnya:

dbsqlcli -e my-query.sql

Konten file contoh my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

Output:

_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

Untuk beralih format output, gunakan --table-format opsi bersama dengan nilai seperti ascii untuk format tabel ASCII, misalnya:

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

Output:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Untuk daftar nilai format output yang tersedia, lihat komentar untuk table_format pengaturan dalam dbsqlclirc file.

REPL

Untuk memasukkan mode loop read-evaluate-print (REPL) yang dicakup ke database default, jalankan perintah berikut:

dbsqlcli

Anda juga dapat memasukkan mode REPL yang dicakup ke database tertentu, dengan menjalankan perintah berikut:

dbsqlcli <database-name>

Contohnya:

dbsqlcli default

Untuk keluar dari mode REPL, jalankan perintah berikut:

exit

Dalam mode REPL, Anda dapat menggunakan karakter dan kunci berikut:

Gunakan titik koma (;) untuk mengakhiri garis.
Gunakan F3 untuk mengalihkan mode multibaris.
Gunakan bilah spasi untuk menampilkan saran di titik penyisipan, jika saran belum ditampilkan.
Gunakan panah atas dan bawah untuk menavigasi saran.
Gunakan panah kanan untuk menyelesaikan saran yang disorot.

Contohnya:

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

Pencatatan

Databricks SQL CLI mencatat pesannya ke file ~/.dbsqlcli/app.log secara default. Untuk mengubah nama atau lokasi file ini, ubah nilai log_file pengaturan dalam dbsqlclirc file pengaturan.

Secara default, pesan dicatat di INFO tingkat log dan di bawah ini. Untuk mengubah tingkat log ini, ubah nilai log_level pengaturan dalam dbsqlclirc file pengaturan. Nilai tingkat log yang tersedia meliputi CRITICAL, ERROR, WARNING, INFO, dan DEBUG dievaluasi dalam urutan tersebut. NONE menonaktifkan pengelogan.

Bagikan melalui

Databricks SQL CLI

Persyaratan

Menginstal Databricks SQL CLI

Autentikasi

File pengaturan

Variabel lingkungan

Unix, Linux, dan macOS

Windows

Opsi perintah

Sumber kueri

Untai kueri

File

REPL

Pencatatan

Sumber Daya Tambahan:

Saran dan Komentar

Sumber Daya Tambahan: