Compartir a través de

CLI de Databricks SQL

  • Artículo

Nota:

Este artículo trata sobre CLI de Databricks SQL que proporciona tal cual y no tiene soporte técnico de Databricks mediante los canales de soporte técnico al cliente. Las preguntas y las solicitudes de características se pueden comunicar mediante la página Problemas del repositorio databricks/databricks-sql-cli de GitHub.

La interfaz de la línea de comandos de Databricks SQL (CLI de Databricks SQL) permite ejecutar consultas SQL en los almacenes de Databricks SQL existentes desde el terminal o el símbolo del sistema de Windows en lugar de desde ubicaciones como el editor de Databricks SQL o un cuaderno de Azure Databricks. Desde la línea de comandos, dispondrá de características de productividad como sugerencias y resaltado de sintaxis.

Requisitos

  • Al menos un almacén de Databricks SQL. Cree un almacén si aún no tiene uno.
  • Python 3.7 o versiones posteriores. Para comprobar si tiene Python instalado, ejecute el comando python --version desde el terminal o el símbolo del sistema. (En algunos sistemas, es posible que tenga que escribir python3 en su lugar). Instale Python si aún no lo tiene instalado.
  • pip, el instalador de paquetes pip de Python. Las versiones más recientes de Python instalan pip de manera predeterminada. Para comprobar si tiene pip instalado, ejecute el comando pip --version desde el terminal o el símbolo del sistema. (En algunos sistemas, es posible que tenga que escribir pip3 en su lugar). Instale pip si aún no lo tiene instalado.
  • (Opcional) Una utilidad para crear y administrar entornos virtuales de Python, como venv. Los entornos virtuales ayudan a garantizar que usa las versiones correctas de Python y la CLI de Databricks SQL juntos. La configuración y el uso de entornos virtuales están fuera del ámbito de este artículo. Para más información, consulte Creación de entornos virtuales.

Instalación de la CLI de Databricks SQL

Cuando cumpla los requisitos, instale el paquete de la CLI de Databricks SQL desde el índice de empaquetado de Python (PyPI). Puede usar pip para instalar el paquete de la CLI de Databricks SQL desde PyPI mediante la ejecución de pip con uno de los comandos siguientes.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Para actualizar una versión instalada anteriormente de la CLI de Databricks SQL, ejecute pip con uno de los comandos siguientes.

pip install databricks-sql-cli --upgrade

# Or...

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

Para comprobar la versión instalada de la CLI de Databricks SQL, ejecute pip con uno de los siguientes comandos.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autenticación

Para autenticarse, debe proporcionar la CLI de Databricks SQL con los detalles de conexión del almacenamiento. Específicamente, necesitará los valores del nombre de host del servidor y la ruta de acceso HTTP. También debe generar la CLI de Databricks SQL con las credenciales de autenticación adecuadas.

La CLI de Databricks SQL admite la autenticación de token de acceso personal de Databricks. No se admiten tokens de Microsoft Entra ID.

Para usar la autenticación de token de acceso personal de Azure Databricks, cree un token de acceso personal como se indica a continuación:

  1. En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario en la barra superior y seleccione Configuración en la lista desplegable.
  2. Haga clic en Desarrollador.
  3. Junto a Tokens de acceso, haga clic en Administrar.
  4. Haga clic en Generate new token (Generar nuevo token).
  5. (Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
  6. Haga clic en Generar.
  7. Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.

Nota:

Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.

Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o los siguientes temas:

Puede proporcionar esta información de autenticación a la CLI de Databricks SQL de varias maneras:

  • En el archivo de configuración dbsqlclirc en su ubicación predeterminada (o especificando un archivo de configuración alternativo mediante la opción --clirc cada vez que ejecute un comando con la CLI de Databricks SQL). Consulte Archivo de configuración.
  • Mediante el establecimiento de las variables de entorno DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH y DBSQLCLI_ACCESS_TOKEN. Consulte Variables de entorno.
  • Mediante la especificación de las opciones --hostname, --http-path y --access-token cada vez que ejecute un comando con la CLI de Databricks SQL. Consulte Opciones de comandos.

Nota:

El archivo de configuración dbsqlclirc debe estar presente, incluso si establece las variables de entorno anteriores o especifica las opciones de comando anteriores o ambas.

Cada vez que ejecute la CLI de Databricks SQL, esta busca los detalles de autenticación en el orden siguiente y se detiene cuando encuentra el primer conjunto de detalles:

  1. Las opciones --hostname, --http-path y --access-token.
  2. Las variables de entorno DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH y DBSQLCLI_ACCESS_TOKEN.
  3. El archivo de configuración dbsqlclirc en su ubicación predeterminada (o un archivo de configuración alternativo especificado mediante la opción --clirc).

Archivo de configuración

Para usar el archivo de configuración dbsqlclirc para proporcionar a la CLI de Databricks SQL los detalles de autenticación del almacén de Databricks SQL, ejecute la CLI de Databricks SQL por primera vez, como se indica a continuación:

dbsqlcli

La CLI de Databricks SQL crea un archivo de configuración automáticamente, en ~/.dbsqlcli/dbsqlclirc para Unix, Linux y macOS, y en %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc o %USERPROFILE%\.dbsqlcli\dbsqlclirc para Windows. Para personalizar este archivo:

  1. Use un editor de texto para abrir y editar el archivo dbsqlclirc.

  2. Desplácese hasta la sección siguiente:

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

  3. Quite los cuatro caracteres # y:

    1. Junto a host_name, escriba el valor del nombre de host del servidor del almacén según los requisitos entre los caracteres "".
    2. Junto a http_path, escriba el valor de la ruta de acceso HTTP del almacén según los requisitos entre los caracteres "".
    3. Junto a access_token, escriba el valor del token de acceso personal según los requisitos entre los caracteres "".

    Por ejemplo:

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

  4. Guarde el archivo dbsqlclirc.

Como alternativa, en lugar de usar el archivo dbsqlclirc en su ubicación predeterminada, puede especificar un archivo en otra ubicación agregando la opción de comando --clirc y la ruta de acceso al archivo alternativo. El contenido de ese archivo alternativo debe ajustarse a la sintaxis anterior.

Variables de entorno

Para usar las variables de entorno DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH y DBSQLCLI_ACCESS_TOKEN para proporcionar a la CLI de Databricks SQL los detalles de autenticación del almacén de Databricks SQL, haga lo siguiente:

Unix, Linux y macOS

Para establecer las variables de entorno solo para la sesión de terminal actual, ejecute los siguientes comandos. Para establecer las variables de entorno para todas las sesiones de terminal, escriba los siguientes comandos en el archivo de inicio del shell y reinicie el terminal. En los siguientes comandos, reemplace el valor de:

  • DBSQLCLI_HOST_NAME por el valor del nombre de host del servidor del almacén según los requisitos.
  • DBSQLCLI_HTTP_PATH por el valor de la ruta de acceso HTTP del almacén según los requisitos.
  • DBSQLCLI_ACCESS_TOKEN por el valor del token de acceso personal según los requisitos.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Para establecer las variables de entorno solo para la sesión actual del símbolo del sistema, ejecute los siguientes comandos, reemplazando el valor de:

  • DBSQLCLI_HOST_NAME por el valor del nombre de host del servidor del almacén según los requisitos.
  • DBSQLCLI_HTTP_PATH por el valor de la ruta de acceso HTTP del almacén según los requisitos.
  • DBSQLCLI_ACCESS_TOKEN por el valor del token de acceso personal según los requisitos.
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Para establecer las variables de entorno para todas las sesiones del símbolo del sistema, ejecute los siguientes comandos, reinicie el símbolo del sistema y reemplace el valor de:

  • DBSQLCLI_HOST_NAME por el valor del nombre de host del servidor del almacén según los requisitos.
  • DBSQLCLI_HTTP_PATH por el valor de la ruta de acceso HTTP del almacén según los requisitos.
  • DBSQLCLI_ACCESS_TOKEN por el valor del token de acceso personal según los requisitos.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opciones de comando

Para usar las opciones --hostname, --http-path y --access-token para proporcionar a la CLI de Databricks SQL los detalles de autenticación del almacén de Databricks SQL, haga lo siguiente:

Realice lo siguiente cada vez que ejecute un comando con la CLI de Databricks SQL:

  • Especifique la opción --hostname y el valor del nombre de host del servidor del almacén según los requisitos.
  • Especifique la opción --http-path y el valor de la ruta de acceso HTTP del almacén según los requisitos.
  • Especifique la opción --access-token y el valor del token de acceso personal según los requisitos.

Por ejemplo:

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

Orígenes de consulta

La CLI de Databricks SQL le permite ejecutar consultas de las siguientes maneras:

  • Desde una cadena de consulta.
  • Desde un archivo.
  • En un enfoque de bucle read-evaluate-print (REPL). Este enfoque proporciona sugerencias a medida que escribe.

Cadena de consulta

Para ejecutar una consulta como una cadena, use la opción -e seguida de la consulta, representada como una cadena. Por ejemplo:

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

Salida:

_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

Para cambiar los formatos de salida, use la opción --table-format junto con un valor como ascii para el formato de tabla ASCII, por ejemplo:

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

Salida:

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

Para obtener una lista de los valores de formato de salida disponibles, consulte los comentarios de la configuración table_format en el archivo dbsqlclirc.

Archivo

Para ejecutar un archivo que contiene SQL, use la opción -e seguida de la ruta de acceso a un archivo .sql. Por ejemplo:

dbsqlcli -e my-query.sql

Contenido del archivo my-query.sql de ejemplo:

SELECT * FROM default.diamonds LIMIT 2;

Salida:

_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

Para cambiar los formatos de salida, use la opción --table-format junto con un valor como ascii para el formato de tabla ASCII, por ejemplo:

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

Salida:

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

Para obtener una lista de los valores de formato de salida disponibles, consulte los comentarios de la configuración table_format en el archivo dbsqlclirc.

REPL

Para especificar el modo de bucle read-evaluate-print (REPL) con ámbito en la base de datos predeterminada, ejecute el siguiente comando:

dbsqlcli

También puede especificar el modo REPL con ámbito en una base de datos específica mediante la ejecución del siguiente comando:

dbsqlcli <database-name>

Por ejemplo:

dbsqlcli default

Para salir del modo REPL, ejecute el siguiente comando:

exit

En el modo REPL, puede usar los siguientes caracteres y claves:

  • Use el punto y coma (;) para finalizar una línea.
  • Use F3 para alternar el modo de varias líneas.
  • Use la barra espaciadora para mostrar sugerencias en el punto de inserción, si aún no se muestran sugerencias.
  • Use las flechas hacia arriba y abajo para desplazarse por las sugerencias.
  • Use la flecha a la derecha para completar la sugerencia resaltada.

Por ejemplo:

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

Registro

La CLI de SQL de Databricks registra sus mensajes en el archivo ~/.dbsqlcli/app.log de manera predeterminada. Para cambiar este nombre de archivo o ubicación, cambie el valor de la log_fileconfiguración en el dbsqlclirc archivo de configuración.

De manera predeterminada, los mensajes se registran en el nivel de registro INFO y a continuación. Para cambiar este nivel de registro, cambie el valor de la configuración de log_level en el archivo de configuracióndbsqlclirc. Los valores de nivel de registro disponibles incluyen CRITICAL, ERROR, WARNING, INFO, y DEBUG se evalúan en ese orden. NONE deshabilita el registro.

Recursos adicionales