CLI Databricks SQL

important

Le Databricks SQL CLI n'est pas en cours de développement actif.

remarque

Cet article traite du CLI Databricks SQL, qui est fourni tel quel et n'est pas pris en charge par Databricks via les canaux de support technique client. Les questions et les demandes de fonctionnalités peuvent être communiquées via la page Problèmes du dépôt databricks/databricks-sql-cli sur GitHub.

L'interface de ligne de commande Databricks SQL (CLI Databricks SQL) vous permet d'exécuter des query SQL sur vos Databricks SQL SQL Warehouse existants depuis votre terminal ou l'invite de commandes Windows, plutôt que depuis des emplacements tels que l'éditeur SQL de Databricks ou un Notebook Databricks. Depuis la ligne de commande, vous disposez de fonctionnalités de productivité telles que des suggestions et la mise en surbrillance syntaxique.

Exigences

• Au moins un SQL Warehouse Databricks. Créez un warehouse, si vous n'en avez pas déjà un.
• Python 3.7 ou version ultérieure. Pour vérifier si vous avez Python installé, exécutez la commande python --version depuis votre terminal ou l'invite de commandes. (Sur certains systèmes, vous devrez peut-être saisir python3 à la place.) Installez Python, si ce n'est pas déjà fait.
• pip, l'installateur de packages pour Python. Les versions plus récentes de Python installent pip par default. Pour vérifier si vous avez installé pip, exécutez la commande pip --version depuis votre terminal ou l'invite de commandes. (Sur certains systèmes, vous devrez peut-être saisir pip3 à la place.) Installez pip, si vous ne l'avez pas déjà installé.
• (Facultatif) Un outil pour créer et gérer des environnements virtuels Python, tels que venv. Les environnements virtuels contribuent à garantir que vous utilisez les bonnes versions de Python et de l'interface CLI de Databricks SQL. La configuration et l'utilisation des environnements virtuels dépassent le cadre de cet article. Pour plus d'informations, consultez Création d'environnements virtuels.

Installer la CLI Databricks SQL

Après avoir satisfait aux exigences, installez le package CLI Databricks SQL à partir du Python Packaging Index (PyPI). Vous pouvez utiliser pip pour installer le package CLI Databricks SQL depuis PyPI en exécutant pip avec l'une des commandes suivantes.

Bash

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Pour mettre à niveau une version précédemment installée du CLI Databricks SQL, exécutez pip avec l'une des commandes suivantes.

Bash

pip install databricks-sql-cli --upgrade

# Or...

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

Pour vérifier votre version installée du CLI Databricks SQL, exécutez pip avec l'une des commandes suivantes.

Bash

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Authentification

Pour vous authentifier, vous devez fournir à l'interface CLI de Databricks SQL les détails de connexion de votre warehouse. Plus précisément, vous avez besoin des valeurs Hostname du serveur et Chemin HTTP . Vous devez également configurer l'interface CLI de Databricks SQL avec les informations d'authentification appropriées.

Le CLI Databricks SQL prend en charge deux types d’authentification Databricks : l’authentification par jeton d’accès personnel Databricks et, pour les versions 0.2.0 et ultérieures du CLI Databricks SQL, l’authentification OAuth utilisateur-à-machine (U2M). Databricks vous recommande d’utiliser OAuth pour une sécurité et une facilité d’utilisation accrues.

Pour utiliser l'authentification par jeton d'accès personnel Databricks, vous devez créer un jeton d'accès personnel. Pour plus de détails sur ce processus, consultez Authentification avec les jetons d'accès personnels Databricks (hérité).

Il n’y a aucune exigence de configuration pour utiliser l’authentification OAuth U2M.

Vous pouvez fournir ces informations d'authentification à Databricks SQL CLI de plusieurs façons :

• Dans le fichier de paramètres dbsqlclirc à son emplacement default (ou en spécifiant un autre fichier de paramètres via l'option --clirc chaque fois que vous exécutez une commande avec le Databricks SQL CLI). Voir Fichier de paramètres.
• Pour l'authentification par jeton d'accès personnel Databricks, en définissant les variables d'environnement DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH et DBSQLCLI_ACCESS_TOKEN. Consulter Variables d'environnement.
• Pour l'authentification Databricks OAuth U2M, en définissant les variables d'environnement DBSQLCLI_HOST_NAME et DBSQLCLI_HTTP_PATH, et en spécifiant l'option de ligne de commande --oauth ou en définissant auth_type = "databricks-oauth" dans le fichier de paramètres dbsqlclirc. Consultez Variables d'environnement.
• Pour l’authentification par jeton d'accès personnel Databricks, en spécifiant les options --hostname, --http-path et --access-token chaque fois que vous exécutez une commande avec la CLI Databricks SQL. Consultez Options de commande.
• Pour l'authentification OAuth U2M Databricks, en spécifiant les options de ligne de commande --hostname et --http-path, et en spécifiant l'option de ligne de commande --oauth ou en définissant auth_type = "databricks-oauth" dans le fichier de paramètres dbsqlclirc, chaque fois que vous exécutez une commande avec le CLI Databricks SQL. Voir Options de commande.

remarque

Le fichier de paramètres dbsqlclirc doit être présent, même si vous définissez les variables d’environnement précédentes ou spécifiez les options de commande précédentes ou les deux.

Chaque fois que vous exécutez l'interface CLI Databricks SQL, elle recherche les détails d'authentification dans l'ordre suivant et s'arrête lorsqu'elle trouve le premier ensemble de détails :

1. Les options --hostname, --http-path et --access-token ou --oauth.
2. Les variables d’environnement DBSQLCLI_HOST_NAME et DBSQLCLI_HTTP_PATH (et, pour l’authentification par jeton d’accès personnel Databricks, la variable d’environnement DBSQLCLI_ACCESS_TOKEN).
3. Le fichier de paramètres dbsqlclirc à son emplacement **default** (ou un fichier de paramètres alternatif spécifié par l'option --clirc).

Fichier de paramètres

Pour utiliser le fichier de paramètres dbsqlclirc afin de fournir au CLI Databricks SQL les détails d'authentification de votre warehouse Databricks SQL, exécutez le CLI Databricks SQL pour la première fois, comme suit :

Bash

dbsqlcli

Le CLI Databricks SQL crée un fichier de paramètres pour vous, à l'emplacement ~/.dbsqlcli/dbsqlclirc sur Unix, Linux et macOS, et à l'emplacement %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc ou %USERPROFILE%\.dbsqlcli\dbsqlclirc sur Windows. Pour personnaliser ce fichier :

1. Utilisez un éditeur de texte pour ouvrir et modifier le fichier dbsqlclirc.

2. Faites défiler jusqu'à la section suivante :

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

3. Supprimez les quatre caractères #, et :

   1. À côté de host_name, entrez la valeur Hostname du serveur de votre warehouse, à partir des exigences entre les "" caractères.

   2. À côté de http_path, saisissez la valeur du chemin HTTP de votre warehouse, à partir des exigences, entre les "" caractères.

   3. À côté de access_token, saisissez la valeur de votre jeton d'accès personnel, conformément aux exigences, entre les caractères "".

remarque

Pour l'authentification OAuth U2M Databricks, vous devez remplacer access_token par auth_type = "databricks-oauth", ou spécifier l'option de ligne de commande --oauth à chaque appel au CLI Databricks SQL.

Par exemple :

[credentials]
host_name = "dbc-a1b2345c-d6e78.cloud.databricks.com"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"

4. Enregistrez le fichier dbsqlclirc.

Alternativement, au lieu d'utiliser le fichier dbsqlclirc à son emplacement par default, vous pouvez spécifier un fichier à un emplacement différent en ajoutant l'option de commande --clirc et le chemin d'accès au fichier alternatif. Le contenu de ce fichier alternatif doit être conforme à la syntaxe précédente.

Variables d'environnement

Pour utiliser les variables d'environnement DBSQLCLI_HOST_NAME et DBSQLCLI_HTTP_PATH (et, pour l'authentification par jeton d'accès personnel Databricks, la variable d'environnement DBSQLCLI_ACCESS_TOKEN) afin de fournir les détails d'authentification de votre Databricks SQL warehouse au CLI Databricks SQL, procédez comme suit.

remarque

Pour l'authentification Databricks OAuth U2M, vous devez définir auth_type = "databricks-oauth" dans le fichier de paramètres dbsqlclirc, ou spécifier l'option de commande --oauth à chaque appel à la CLI Databricks SQL.

Unix, Linux, and macOS

Pour définir les variables d’environnement uniquement pour la session de terminal actuelle, exécutez les commandes suivantes. Pour définir les variables d'environnement pour toutes les sessions de terminal, saisissez les commandes suivantes dans le fichier de Startup de votre shell, puis redémarrez votre terminal. Dans les commandes suivantes, remplacez la valeur de :

• DBSQLCLI_HOST_NAME avec la valeur hostname du serveur de votre warehouse, à partir des exigences.
• DBSQLCLI_HTTP_PATH avec la valeur du chemin HTTP de votre warehouse à partir des exigences.
• DBSQLCLI_ACCESS_TOKEN avec la valeur de votre jeton d'accès personnel selon les exigences.

Bash

export DBSQLCLI_HOST_NAME="dbc-a1b2345c-d6e78.cloud.databricks.com"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Pour définir les variables d'environnement pour la session d'invite de commandes actuelle uniquement, exécutez les commandes suivantes en remplaçant la valeur de :

• DBSQLCLI_HOST_NAME avec la valeur hostname du serveur de votre warehouse, à partir des exigences.
• DBSQLCLI_HTTP_PATH avec la valeur du chemin HTTP de votre warehouse à partir des exigences.
• DBSQLCLI_ACCESS_TOKEN avec la valeur de votre jeton d'accès personnel issue des exigences :

Bash

set DBSQLCLI_HOST_NAME="dbc-a1b2345c-d6e78.cloud.databricks.com"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Pour définir les variables d'environnement pour toutes les sessions d'invite de commande, exécutez les commandes suivantes, puis redémarrez votre invite de commande, en remplaçant la valeur de :

• DBSQLCLI_HOST_NAME avec la valeur hostname du serveur de votre warehouse, à partir des exigences.
• DBSQLCLI_HTTP_PATH avec la valeur du chemin HTTP de votre warehouse à partir des exigences.
• DBSQLCLI_ACCESS_TOKEN avec la valeur de votre jeton d'accès personnel selon les exigences.

Bash

setx DBSQLCLI_HOST_NAME "dbc-a1b2345c-d6e78.cloud.databricks.com"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Options de commande

Pour utiliser les options --hostname, --http-path et --access-token ou --oauth afin de fournir à l'interface CLI de Databricks SQL les détails d'authentification de votre warehouse Databricks SQL, procédez comme suit :

Effectuez les opérations suivantes chaque fois que vous exécutez une commande avec la CLI Databricks SQL :

• Spécifiez l'option et --hostname la valeur **Hostname du serveur** de votre warehouse à partir des exigences.

• Spécifiez l'option --http-path et la valeur du chemin HTTP de votre warehouse à partir des exigences.

• Pour l'authentification par jeton d'accès personnel Databricks, spécifiez l'option --access-token et la valeur de votre jeton d'accès personnel à partir des exigences.

• Pour l'authentification Databricks OAuth U2M, spécifiez --oauth.

remarque

Pour l'authentification Databricks OAuth U2M, vous devez spécifier le auth_type = "databricks-oauth" dans le fichier de paramètres dbsqlclirc, ou spécifier l'option de commande --oauth à chaque appel à la Databricks SQL CLI.

Par exemple :

Pour l'authentification par jeton d'accès personnel Databricks :

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Pour l’authentification Databricks OAuth U2M :

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--oauth

Sources de requête

Le CLI Databricks SQL vous permet d'exécuter des requêtes des manières suivantes :

• Depuis une chaîne de query.
• À partir d'un fichier.
• Dans une approche de boucle lecture-évaluation-impression (REPL). Cette approche fournit des suggestions au fur et à mesure que vous tapez.

Chaîne de query

Pour exécuter une requête sous forme de chaîne, utilisez l'option -e suivie de la requête, représentée sous forme de chaîne. Par exemple :

Bash

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

Résultat :

Bash

_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

Pour changer de format de sortie, utilisez l'option --table-format avec une valeur telle que ascii pour le format de table ASCII, par exemple :

Bash

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

Résultat :

Bash

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

Pour obtenir une liste des valeurs de format de sortie disponibles, consultez les commentaires relatifs au paramètre table_format dans le fichier dbsqlclirc.

Fichier

Pour exécuter un fichier qui contient du SQL, utilisez l'option -e suivie du chemin d'accès à un fichier .sql. Par exemple :

Bash

dbsqlcli -e my-query.sql

Contenu du fichier d'exemple my-query.sql :

SQL

SELECT * FROM default.diamonds LIMIT 2;

Résultat :

Bash

_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

Pour changer de format de sortie, utilisez l'option --table-format avec une valeur telle que ascii pour le format de table ASCII, par exemple :

Bash

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

Résultat :

Bash

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

Pour obtenir une liste des valeurs de format de sortie disponibles, consultez les commentaires relatifs au paramètre table_format dans le fichier dbsqlclirc.

REPL

Pour entrer en mode de boucle lecture-évaluation-impression (REPL) dans la base de données par default, exécutez la commande suivante :

Bash

dbsqlcli

Vous pouvez également passer en mode REPL limité à une base de données spécifique, en exécutant la commande suivante :

Bash

dbsqlcli <database-name>

Par exemple :

Bash

dbsqlcli default

Pour quitter le mode REPL, exécutez la commande suivante :

Bash

exit

En mode REPL, vous pouvez utiliser les caractères et touches suivants :

• Utilisez le point-virgule (;) pour terminer une ligne.
• Utilisez F3 pour activer/désactiver le mode multiligne.
• Utilisez la barre d'espace pour afficher les suggestions au point d'insertion, si les suggestions ne sont pas déjà affichées.
• Utilisez les flèches haut et bas pour parcourir les suggestions.
• Utilisez la flèche droite pour compléter la suggestion mise en surbrillance.

Par exemple :

Bash

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

Journalisation

Le CLI Databricks SQL Log ses messages dans le fichier ~/.dbsqlcli/app.log par default. Pour modifier le nom ou l'emplacement de ce fichier, modifiez la valeur du paramètre log_file dans le fichier de paramètres dbsqlclirc.

Par défaut, les messages sont journalisés au niveau INFO et en dessous. Pour modifier ce niveau de journalisation, modifiez la valeur du paramètre log_level dans le fichier de paramètres dbsqlclirc. Les valeurs de niveau de Logs disponibles incluent CRITICAL, ERROR, WARNING, INFO et DEBUG, et sont évaluées dans cet ordre. NONE désactive la journalisation.

Ressources supplémentaires

• README de Databricks SQL CLI
• Didacticiel de l’API d’exécution des requêtes Databricks SQL