CLI SQL Databricks

Article
11/16/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 SQL Databricks prend en charge les jetons d’accès personnels Databricks (PAT). Pour utiliser l’authentification PAT Azure Databricks, vous devez créer un jeton d’accès personnel. Pour plus d’informations sur ce processus, consultez l’authentification par jeton d’accès personnel Azure Databricks.

Les jetons Microsoft Entra ID ne sont pas pris en charge.

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.

Partager 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

Ressources supplémentaires