Udostępnij za pośrednictwem

Interfejs wiersza polecenia SQL usługi Databricks

  • Artykuł

Uwaga

W tym artykule opisano interfejs wiersza polecenia SQL usługi Databricks, który jest udostępniany jako i nie jest obsługiwany przez usługę Databricks za pośrednictwem kanałów pomocy technicznej klienta. Pytania i żądania funkcji można przekazać za pośrednictwem strony Problemy w repozytorium databricks/databricks-sql-cli w usłudze GitHub.

Interfejs wiersza polecenia SQL usługi Databricks (interfejs wiersza polecenia SQL usługi Databricks) umożliwia uruchamianie zapytań SQL w istniejących magazynach SQL usługi Databricks z poziomu terminalu lub wiersza polecenia systemu Windows zamiast z lokalizacji, takich jak edytor SQL usługi Databricks lub notes usługi Azure Databricks. W wierszu polecenia uzyskasz funkcje produktywności, takie jak sugestie i wyróżnianie składni.

Wymagania

  • Co najmniej jeden magazyn SQL usługi Databricks. Utwórz magazyn, jeśli jeszcze go nie masz.
  • Środowisko Python w wersji 3.7 lub nowszej. Aby sprawdzić, czy masz zainstalowany język Python, uruchom polecenie python --version z poziomu terminalu lub wiersza polecenia. (W niektórych systemach może być konieczne wprowadzenie python3 ). Zainstaluj język Python, jeśli jeszcze go nie zainstalowano.
  • , instalator pakietu dla języka Python. Nowsze wersje języka Python są pip instalowane domyślnie. Aby sprawdzić, czy zainstalowano pip polecenie, uruchom polecenie pip --version z poziomu terminalu lub wiersza polecenia. (W niektórych systemach może być konieczne wprowadzenie pip3 ). Zainstaluj narzędzie, jeśli nie masz jeszcze zainstalowanego narzędzia .
  • (Opcjonalnie) Narzędzie do tworzenia środowisk wirtualnych języka Python i zarządzania nimi, takich jak venv. Środowiska wirtualne pomagają zapewnić, że używasz poprawnych wersji języka Python i interfejsu wiersza polecenia SQL usługi Databricks. Konfigurowanie i używanie środowisk wirtualnych wykracza poza zakres tego artykułu. Aby uzyskać więcej informacji, zobacz Tworzenie środowisk wirtualnych.

Instalowanie interfejsu wiersza polecenia sql usługi Databricks

Po spełnieniu wymagań zainstaluj pakiet interfejsu wiersza polecenia SQL usługi Databricks z indeksu pakietów języka Python (PyPI). Możesz użyć pip polecenia , aby zainstalować pakiet interfejsu wiersza polecenia SQL usługi Databricks z poziomu interfejsu PyPI, uruchamiając pip jedno z następujących poleceń.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Aby uaktualnić wcześniej zainstalowaną wersję interfejsu wiersza polecenia SQL usługi Databricks, uruchom polecenie pip za pomocą jednego z następujących poleceń.

pip install databricks-sql-cli --upgrade

# Or...

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

Aby sprawdzić zainstalowaną wersję interfejsu wiersza polecenia SQL usługi Databricks, uruchom pip polecenie za pomocą jednego z następujących poleceń.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Uwierzytelnianie

Aby przeprowadzić uwierzytelnianie, musisz podać interfejs wiersza polecenia SQL usługi Databricks ze szczegółami połączenia magazynu. W szczególności potrzebne są wartości Nazwa hosta serwera i Ścieżka HTTP. Musisz również produktować interfejs wiersza polecenia SQL usługi Databricks z odpowiednimi poświadczeniami uwierzytelniania.

Interfejs wiersza polecenia SQL usługi Databricks obsługuje uwierzytelnianie osobistego tokenu dostępu usługi Databricks. Tokeny microsoft Entra ID (dawniej Azure Active Directory) nie są obsługiwane.

Aby użyć uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks, utwórz osobisty token dostępu w następujący sposób:

  1. W obszarze roboczym usługi Azure Databricks kliknij nazwę użytkownika usługi Azure Databricks na górnym pasku, a następnie wybierz pozycję Ustawienia z listy rozwijanej.
  2. Kliknij pozycję Deweloper.
  3. Obok pozycji Tokeny dostępu kliknij pozycję Zarządzaj.
  4. Kliknij pozycję Generuj nowy token.
  5. (Opcjonalnie) Wprowadź komentarz, który pomaga zidentyfikować ten token w przyszłości i zmienić domyślny okres istnienia tokenu na 90 dni. Aby utworzyć token bez okresu istnienia (niezalecane), pozostaw puste pole Okres istnienia (dni) (puste).
  6. Kliknij pozycję Generate (Generuj).
  7. Skopiuj wyświetlony token do bezpiecznej lokalizacji, a następnie kliknij przycisk Gotowe.

Uwaga

Pamiętaj, aby zapisać skopiowany token w bezpiecznej lokalizacji. Nie udostępniaj skopiowanego tokenu innym osobom. W przypadku utraty skopiowanego tokenu nie można wygenerować tego samego tokenu. Zamiast tego należy powtórzyć tę procedurę, aby utworzyć nowy token. Jeśli utracisz skopiowany token lub uważasz, że token został naruszony, usługa Databricks zdecydowanie zaleca natychmiastowe usunięcie tego tokenu z obszaru roboczego, klikając ikonę kosza (Odwołaj) obok tokenu na stronie Tokeny dostępu.

Jeśli nie możesz utworzyć lub użyć tokenów w obszarze roboczym, może to być spowodowane tym, że administrator obszaru roboczego wyłączył tokeny lub nie udzielił Ci uprawnień do tworzenia lub używania tokenów. Zobacz administratora obszaru roboczego lub następujące elementy:

Te informacje uwierzytelniania można podać w interfejsie wiersza polecenia SQL usługi Databricks na kilka sposobów:

  • W pliku ustawień w domyślnej dbsqlclirc lokalizacji (lub przez określenie pliku ustawień alternatywnych za pomocą opcji za każdym razem, gdy uruchamiasz polecenie za pomocą --clirc interfejsu wiersza polecenia SQL usługi Databricks). Zobacz Plik ustawień.
  • Ustawiając DBSQLCLI_HOST_NAMEzmienne środowiskowe i DBSQLCLI_ACCESS_TOKEN . DBSQLCLI_HTTP_PATH Zobacz Zmienne środowiskowe.
  • Określając --hostnameopcje , --http-pathi --access-token za każdym razem, gdy uruchamiasz polecenie za pomocą interfejsu wiersza polecenia SQL usługi Databricks. Zobacz Opcje poleceń.

Uwaga

Plik dbsqlclirc ustawień musi być obecny, nawet jeśli ustawisz poprzednie zmienne środowiskowe lub określ poprzednie opcje polecenia lub oba te opcje.

Za każdym razem, gdy uruchamiasz interfejs wiersza polecenia SQL usługi Databricks, szuka szczegółów uwierzytelniania w następującej kolejności i zatrzymuje się po znalezieniu pierwszego zestawu szczegółów:

  1. Opcje --hostname, --http-pathi --access-token .
  2. DBSQLCLI_HOST_NAMEZmienne środowiskowe i DBSQLCLI_ACCESS_TOKEN DBSQLCLI_HTTP_PATH .
  3. dbsqlclirc Plik ustawień w domyślnej --clirc lokalizacji (lub plik ustawień alternatywnych określony przez opcję).

Plik ustawień

Aby użyć pliku ustawień w celu udostępnienia interfejsu dbsqlclirc wiersza polecenia SQL usługi Databricks ze szczegółami uwierzytelniania dla usługi Databricks SQL Warehouse, uruchom interfejs wiersza polecenia SQL usługi Databricks po raz pierwszy w następujący sposób:

dbsqlcli

Interfejs wiersza polecenia SQL usługi Databricks tworzy plik ustawień w ~/.dbsqlcli/dbsqlclirc systemach Unix, Linux i macOS oraz w %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc systemie Windows lub %USERPROFILE%\.dbsqlcli\dbsqlclirc w systemie Windows. Aby dostosować ten plik:

  1. Użyj edytora tekstów, aby otworzyć i edytować dbsqlclirc plik.

  2. Przewiń do następującej sekcji:

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

  3. Usuń cztery # znaki i:

    1. host_nameObok pozycji wprowadź wartość nazwy hosta serwera magazynu z wymagań między znakami"".
    2. http_pathObok pozycji wprowadź wartość ścieżki HTTP magazynu z wymagań między znakami"".
    3. access_tokenObok pozycji wprowadź wartość osobistego tokenu dostępu z wymagań między znakami"".

    Na przykład:

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

  4. Zapisz plik dbsqlclirc.

Alternatywnie zamiast używać dbsqlclirc pliku w jego domyślnej lokalizacji, można określić plik w innej lokalizacji, dodając --clirc opcję polecenia i ścieżkę do pliku alternatywnego. Zawartość tego pliku alternatywnego musi być zgodna z poprzednią składnią.

Zmienne środowiskowe

Aby użyć zmiennych środowiskowych , DBSQLCLI_HTTP_PATHi DBSQLCLI_ACCESS_TOKEN w celu udostępnienia interfejsu DBSQLCLI_HOST_NAMEwiersza polecenia SQL usługi Databricks ze szczegółami uwierzytelniania dla usługi Databricks SQL Warehouse, wykonaj następujące czynności:

Unix, Linux i macOS

Aby ustawić zmienne środowiskowe tylko dla bieżącej sesji terminalu, uruchom następujące polecenia. Aby ustawić zmienne środowiskowe dla wszystkich sesji terminalu, wprowadź następujące polecenia w pliku uruchamiania powłoki, a następnie uruchom ponownie terminal. W następujących poleceniach zastąp wartość :

  • DBSQLCLI_HOST_NAMEz wartością nazwa hosta serwera magazynu z wymagań.
  • DBSQLCLI_HTTP_PATHz wartością ścieżki HTTP magazynu z wymagań.
  • DBSQLCLI_ACCESS_TOKEN z wartością osobistego tokenu dostępu z wymagań.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Aby ustawić zmienne środowiskowe tylko dla bieżącej sesji wiersza polecenia, uruchom następujące polecenia, zastępując wartość :

  • DBSQLCLI_HOST_NAMEz wartością nazwa hosta serwera magazynu z wymagań.
  • DBSQLCLI_HTTP_PATHz wartością ścieżki HTTP magazynu z wymagań.
  • DBSQLCLI_ACCESS_TOKEN z wartością osobistego tokenu dostępu z wymagań.
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Aby ustawić zmienne środowiskowe dla wszystkich sesji wiersza polecenia, uruchom następujące polecenia, a następnie uruchom ponownie wiersz polecenia, zastępując wartość :

  • DBSQLCLI_HOST_NAMEz wartością nazwa hosta serwera magazynu z wymagań.
  • DBSQLCLI_HTTP_PATHz wartością ścieżki HTTP magazynu z wymagań.
  • DBSQLCLI_ACCESS_TOKEN z wartością osobistego tokenu dostępu z wymagań.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opcje poleceń

Aby użyć opcji , --http-pathi --access-token w celu udostępnienia interfejsu --hostnamewiersza polecenia SQL usługi Databricks ze szczegółami uwierzytelniania dla usługi Databricks SQL Warehouse, wykonaj następujące czynności:

Wykonaj następujące czynności za każdym razem, gdy uruchamiasz polecenie za pomocą interfejsu wiersza polecenia SQL usługi Databricks:

  • --hostname Określ opcję i wartość nazwy hosta serwera magazynu z wymagań.
  • --http-path Określ opcję i wartość ścieżki HTTP magazynu z wymagań.
  • --access-token Określ opcję i wartość osobistego tokenu dostępu z wymagań.

Na przykład:

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

Źródła zapytań

Interfejs wiersza polecenia SQL usługi Databricks umożliwia uruchamianie zapytań na następujące sposoby:

  • Z ciągu zapytania.
  • Z pliku.
  • W podejściu rePL (read-evaluate-print loop). Takie podejście zapewnia sugestie podczas wpisywania.

Ciąg zapytania

Aby uruchomić zapytanie jako ciąg, użyj -e opcji, po której następuje zapytanie, reprezentowane jako ciąg. Na przykład:

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

Wyjście:

_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

Aby przełączyć formaty wyjściowe, użyj --table-format opcji wraz z wartością, taką jak ascii format tabeli ASCII, na przykład:

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

Wyjście:

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

Aby uzyskać listę dostępnych wartości formatu danych wyjściowych, zobacz komentarze dotyczące table_format ustawienia w dbsqlclirc pliku.

Plik

Aby uruchomić plik zawierający sql, użyj -e opcji , po której następuje ścieżka do .sql pliku. Na przykład:

dbsqlcli -e my-query.sql

Zawartość przykładowego my-query.sql pliku:

SELECT * FROM default.diamonds LIMIT 2;

Wyjście:

_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

Aby przełączyć formaty wyjściowe, użyj --table-format opcji wraz z wartością, taką jak ascii format tabeli ASCII, na przykład:

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

Wyjście:

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

Aby uzyskać listę dostępnych wartości formatu danych wyjściowych, zobacz komentarze dotyczące table_format ustawienia w dbsqlclirc pliku.

REPL

Aby wprowadzić tryb pętli REPL (read-evaluate-print loop) o określonym zakresie dla domyślnej bazy danych, uruchom następujące polecenie:

dbsqlcli

Możesz również wprowadzić tryb REPL o określonym zakresie dla określonej bazy danych, uruchamiając następujące polecenie:

dbsqlcli <database-name>

Na przykład:

dbsqlcli default

Aby zamknąć tryb REPL, uruchom następujące polecenie:

exit

W trybie REPL można użyć następujących znaków i kluczy:

  • Użyj średnika (;), aby zakończyć wiersz.
  • Przełącz tryb wielowierszowy za pomocą F3 .
  • Użyj paska spacji, aby wyświetlić sugestie w punkcie wstawiania, jeśli sugestie nie są jeszcze wyświetlane.
  • Użyj strzałek w górę i w dół, aby nawigować po sugestiach.
  • Użyj strzałki w prawo, aby ukończyć wyróżnioną sugestię.

Na przykład:

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

Rejestrowanie

Interfejs wiersza polecenia SQL usługi Databricks domyślnie rejestruje komunikaty w pliku ~/.dbsqlcli/app.log . Aby zmienić tę nazwę pliku lub lokalizację, zmień wartość log_file ustawienia w dbsqlclirc pliku ustawień.

Domyślnie komunikaty są rejestrowane na INFO poziomie dziennika i poniżej. Aby zmienić ten poziom dziennika, zmień wartość log_level ustawienia w dbsqlclirc pliku ustawień. Dostępne wartości poziomu dziennika obejmują CRITICALwartości , , ERRORWARNING, INFOi DEBUG i są oceniane w tej kolejności. NONE wyłącza rejestrowanie.

Dodatkowe zasoby