CLI SQL Databricks

Article
05/14/2024

Notes

Cet article couvre l’interface CLI Databricks SQL, qui est fournie en l’état et qui n’est pas prise en charge par Databricks par le biais des canaux de support technique client. Pour toute question ou demande de fonctionnalité, vous pouvez utiliser 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 requêtes SQL sur vos entrepôts Databricks SQL existants à partir de votre terminal ou de l’invite de commandes Windows au lieu d’emplacements tels que l’éditeur Databricks SQL ou un notebook Azure Databricks. À partir de la ligne de commande, vous obtenez des fonctionnalités de productivité telles que les suggestions et la mise en surbrillance de la syntaxe.

Spécifications

Au moins un entrepôt Databricks SQL. Créez un entrepôt si vous n’en avez pas déjà un.
Python 3.7 ou version ultérieure. Pour vérifier si Python est installé, exécutez la commande python --version à partir de votre terminal ou de l’invite de commandes. (Sur certains systèmes, vous devrez peut-être entrer python3 à la place.) Installez Python s’il n’est pas déjà installé.
pip, le programme d’installation de package pour Python. Les versions plus récentes du pip d’installation de Python par défaut. Pour vérifier si pip est installé, exécutez la commande pip --version à partir de votre terminal ou de l’invite de commandes. (Sur certains systèmes, vous devrez peut-être entrer pip3 à la place.) Installez pip s’il n’est pas déjà installé.
(Facultatif) Un utilitaire permettant de créer et de gérer des environnements virtuels Python, tels que venv. Les environnements virtuels vous permettent de vous assurer que vous utilisez les versions appropriées de Python et de l’interface CLI SQL Databricks ensemble. La configuration et l’utilisation des environnements virtuels n’entrent pas dans le cadre de cet article. Pour plus d’informations, consultez Création d’environnements virtuels.

Installez la CLI SQL Databricks

Une fois que vous avez satisfait aux exigences, installez le package CLI SQL Databricks à partir de l’index d’empaquetage Python (PyPI). Vous pouvez utiliser pip pour installer le package CLI Databricks SQL à partir de PyPI en exécutant pip avec l’une des commandes suivantes.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

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

pip install databricks-sql-cli --upgrade

# Or...

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

Pour vérifier la version installée de l’interface CLI Databricks SQL, exécutez pip avec l’une des commandes suivantes.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Authentification

Pour vous authentifier, vous devez fournir à l’interface CLI Databricks SQL les détails de connexion de votre entrepôt. Plus précisément, vous avez besoin des valeurs Nom d’hôte du serveur et Chemin d’accès HTTP. Vous devez également fournir à l’interface CLI Databricks SQL les informations d’identification d’authentification appropriées.

L’interface CLI Databricks SQL prend en charge l’authentification par jeton d’accès personnel Databricks. Les jetons Microsoft Entra ID (anciennement Azure Active Directory) ne sont pas pris en charge.

Pour utiliser l’authentification par jeton d’accès personnel Azure Databricks, créez un jeton d’accès personnel comme suit :

Dans votre espace de travail Azure Databricks, cliquez sur votre nom d’utilisateur Azure Databricks dans la barre supérieure, puis sélectionnez Paramètres dans la liste déroulante.
Cliquez sur Développeur.
À côté de Jetons d’accès, cliquez sur Gérer.
Cliquez sur Générer un nouveau jeton.
(Facultatif) Entrez un commentaire qui vous aide à identifier ce jeton à l’avenir et modifiez sa durée de vie par défaut (90 jours). Pour créer un jeton sans durée de vie (non recommandé), laissez vide la zone Durée de vie (en jours).
Cliquez sur Générer.
Copiez le jeton affiché dans un emplacement sécurisé, puis cliquez sur Terminé.

Remarque

Veillez à enregistrer le jeton copié dans un emplacement sécurisé. Ne partagez pas votre jeton copié avec d'autres. Si vous le perdez, vous ne pouvez pas régénérer exactement le même. Vous devez donc répéter cette procédure pour créer un jeton. Si vous perdez le jeton copié ou si vous pensez que le jeton a été compromis, Databricks vous recommande vivement de supprimer immédiatement ce jeton de votre espace de travail en cliquant sur l’icône de la corbeille (Révoquer) à côté du jeton de la page Jetons d’accès.

Si vous n'êtes pas en mesure de créer ou d'utiliser des jetons dans votre espace de travail, cela peut être dû au fait que votre administrateur d'espace de travail a désactivé les jetons ou ne vous a pas donné l'autorisation de créer ou d'utiliser des jetons. Consultez votre administrateur d'espace de travail ou les personnes suivantes :

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

Dans le fichier de paramètres dbsqlclirc dans son emplacement par défaut (ou en spécifiant un autre fichier de paramètres via l’option --clirc chaque fois que vous exécutez une commande avec l’interface CLI SQL Databricks). Consultez Fichier de paramètres.
En définissant les variables d’environnement DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH et DBSQLCLI_ACCESS_TOKEN. Consultez Variables d’environnement.
En spécifiant les options --hostname, --http-path et--access-token chaque fois que vous exécutez une commande avec l’interface CLI SQL Databricks. Consultez Options de commande.

Notes

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 :

Les options --hostname, --http-path et --access-token.
Les variables d’environnement DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH et DBSQLCLI_ACCESS_TOKEN.
Le fichier de paramètres dbsqlclirc dans son emplacement par défaut (ou un autre fichier de paramètres spécifié par l’option --clirc).

Fichier de paramètres

Pour utiliser le fichier de paramètres dbsqlclirc afin de fournir à l’interface CLI Databricks SQL des détails d’authentification pour votre entrepôt Databricks SQL, exécutez l’interface CLI Databricks SQL pour la première fois, comme suit :

dbsqlcli

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

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

Défilez jusqu’à la section suivante :

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

Supprimez les quatre caractères #, et :
1. En regard de host_name, entrez la valeur Nom d’hôte du serveur de votre entrepôt issue des exigences entre les caractères "".
2. En regard de http_path, entrez la valeur Chemin HTTP de votre entrepôt issue des exigences entre les caractères "".
3. En regard de access_token, entrez la valeur de votre jeton d’accès personnel à partir des exigences entre les caractères "".
Par exemple :
```
[credentials]
host_name = "adb-12345678901234567.8.azuredatabricks.net"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"
```
Enregistrez le fichier dbsqlclirc.

Sinon, au lieu d’utiliser le fichier dbsqlclirc à son emplacement par défaut, vous pouvez spécifier un fichier dans un autre emplacement en ajoutant l’option de commande --clirc et le chemin d’accès au fichier de remplacement. Le contenu de ce fichier de remplacement doit être conforme à la syntaxe précédente.

Variables d'environnement

Pour utiliser les variables d’environnement DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH et DBSQLCLI_ACCESS_TOKEN afin de fournir à l’interface CLI Databricks SQL des détails d’authentification pour votre entrepôt Databricks SQL, procédez comme suit :

Unix, Linux et 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, entrez les commandes suivantes dans le fichier de démarrage de votre interpréteur de commandes, puis redémarrez votre terminal. Dans les commandes suivantes, remplacez les valeurs :

DBSQLCLI_HOST_NAME par la valeur Nom d’hôte du serveur de votre entrepôt issue des exigences.
DBSQLCLI_HTTP_PATH par la valeur Chemin HTTP de votre entrepôt issue des exigences.
DBSQLCLI_ACCESS_TOKEN par la valeur de votre jeton d’accès personnel à partir des exigences.

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

Windows

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

DBSQLCLI_HOST_NAME par la valeur Nom d’hôte du serveur de votre entrepôt issue des exigences.
DBSQLCLI_HTTP_PATH par la valeur Chemin HTTP de votre entrepôt issue des exigences.
DBSQLCLI_ACCESS_TOKEN par la valeur de votre jeton d’accès personnel à partir des exigences.

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
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 commandes, exécutez les commandes suivantes, puis redémarrez votre invite de commandes en remplaçant les valeurs :

DBSQLCLI_HOST_NAME par la valeur Nom d’hôte du serveur de votre entrepôt issue des exigences.
DBSQLCLI_HTTP_PATH par la valeur Chemin HTTP de votre entrepôt issue des exigences.
DBSQLCLI_ACCESS_TOKEN par la valeur de votre jeton d’accès personnel à partir des exigences.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
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 afin de fournir à l’interface CLI Databricks SQL des détails d’authentification pour votre entrepôt Databricks SQL, procédez comme suit :

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

Spécifiez l’option --hostname et la valeur Nom d’hôte du serveur de votre entrepôt issue des exigences.
Spécifiez l’option --http-path et la valeur Chemin HTTP de votre entrepôt issue des exigences.
Spécifiez l’option --access-token et la valeur de votre jeton d’accès personnel à partir des exigences.

Par exemple :

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

Sources de requête

L’interface CLI SQL Databricks vous permet d’exécuter des requêtes de la manière suivante :

À partir d’une chaîne de requête.
À partir d’un fichier.
Par le biais d’une approche REPL (Read-Evaluate-Print Loop). Cette approche fournit des suggestions à mesure que vous tapez.

Chaîne de requête

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

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

Sortie :

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

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

Sortie :

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 la liste des valeurs de format de sortie disponibles, consultez les commentaires du paramètre table_format dans le fichier dbsqlclirc.

Fichier

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

dbsqlcli -e my-query.sql

Contenu de l’exemple de fichier my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

Sortie :

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

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

Sortie :

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 la liste des valeurs de format de sortie disponibles, consultez les commentaires du paramètre table_format dans le fichier dbsqlclirc.

REPL

Pour entrer en mode REPL (Read-Evaluate-Print Loop) limité à la base de données par défaut, exécutez la commande suivante :

dbsqlcli

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

dbsqlcli <database-name>

Par exemple :

dbsqlcli default

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

exit

En mode REPL, vous pouvez utiliser les caractères et clés suivants :

Utilisez le point-virgule (;) pour mettre fin à 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 vers le haut et vers le bas pour parcourir les suggestions.
Utilisez la flèche vers la droite pour terminer la suggestion mise en surbrillance.

Par exemple :

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

Logging

L’interface CLI SQL Databricks consigne ses messages dans le fichier ~/.dbsqlcli/app.log par défaut. Pour modifier ce nom de fichier ou cet emplacement, modifiez la valeur du paramètre log_file dans le fichier de paramètres dbsqlclirc.

Par défaut, les messages sont enregistrés au niveau INFO (et les niveaux inférieurs) du journal. Pour modifier ce niveau de journal, modifiez la valeur du paramètre log_level dans le fichier du paramètre dbsqlclirc. Les valeurs de niveau journal disponibles comprennent CRITICAL, ERROR, WARNING, INFO et DEBUG. Elles sont évaluées dans cet ordre. NONE désactive la journalisation.

Partage via

CLI SQL Databricks

Spécifications

Installez la CLI SQL Databricks

Authentification

Fichier de paramètres

Variables d'environnement

Unix, Linux et macOS

Windows

Options de commande

Sources de requête

Chaîne de requête

Fichier

REPL

Logging

Ressources supplémentaires

Commentaires

Commentaires

Ressources supplémentaires