API de ejecución de instrucciones: ejecución de SQL en almacenes

Importante

Para acceder a las API REST de Databricks, debe autenticarse.

En este tutorial se muestra cómo usar Databricks SQL Statement Execution API 2.0 para ejecutar instrucciones SQL desde Almacenes SQL de Databricks.

Para ver la referencia de Databricks SQL Statement Execution API 2.0, consulte Ejecución de instrucciones.

Antes de empezar

Antes de comenzar este tutorial, asegúrese de que dispone de lo siguiente:

• La CLI de Databricks, versión 0.205 o posterior, o curl, como se indica a continuación:

  • La CLI de Databricks es una herramienta de línea de comandos para enviar y recibir solicitudes y respuestas de la API REST de Databricks. Si utiliza la versión 0.205 o superior de la CLI de Databricks, debe configurarse para autenticarse con el área de trabajo de Azure Databricks. Consulte Instalación o actualización de la CLI de Databricks y Autenticación para la CLI de Databricks.

    Por ejemplo, para autenticarse con la autenticación de token de acceso personal de Databricks, siga los pasos descritos en Creación de tokens de acceso personal para usuarios del área de trabajo.

    Y, a continuación, para usar la CLI de Databricks para crear un perfil de configuración de Azure Databricks para el token de acceso personal, haga lo siguiente:

    Nota:

    En el procedimiento siguiente se usa la CLI de Databricks para crear un perfil de configuración de Azure Databricks con el nombre DEFAULT. Si ya tiene un perfil de configuración DEFAULT, este procedimiento sobrescribe el perfil de configuraciónDEFAULT existente.

    Para comprobar si ya tiene un DEFAULT perfil de configuración y para ver la configuración de este perfil si existe, use la CLI de Databricks para ejecutar el comando databricks auth env --profile DEFAULT.

    Para crear un perfil de configuración con un nombre distinto de DEFAULT, reemplace la parte DEFAULT de --profile DEFAULT en el siguiente comando databricks configure por un nombre diferente para el perfil de configuración.

    1. Use la CLI de Databricks para crear un perfil de configuración de Azure Databricks denominado DEFAULT que usa la autenticación de token de acceso personal de Azure Databricks. Para ello, ejecute el siguiente comando:

       databricks configure --profile DEFAULT
       

    2. En el aviso Host de Databricks, introduzca la dirección URL por área de trabajo de Azure Databricks, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net.

    3. En el indicador Token Personal de Acceso, escriba el token personal de acceso de Azure Databricks para su área de trabajo.

    En los ejemplos de la CLI de Databricks de este tutorial, tenga en cuenta lo siguiente:

    • En este tutorial se supone que tiene una variable de entorno DATABRICKS_SQL_WAREHOUSE_ID en la máquina de desarrollo local. Esta variable de entorno representa el identificador del almacén de Databricks SQL. Este identificador es la cadena de letras y números siguientes /sql/1.0/warehouses/ en el campo ruta de acceso HTTP del almacén. Para obtener información sobre cómo obtener el valor de la ruta de acceso HTTP del almacenamiento, consulte Obtención de detalles de conexión para un recurso de proceso de Azure Databricks.
    • Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, reemplace \ por ^ y reemplace ${...} por %...%.
    • Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, en declaraciones de documento JSON, reemplace el ' de apertura y cierre por " y reemplace el " interior por \".

  • curl es una herramienta de línea de comandos para enviar y recibir solicitudes y respuestas de la API REST. Consulte también Instalar curl. O bien, adapte los ejemplos de curl este tutorial para su uso con herramientas similares, como HTTPie.

    En los ejemplos de este tutorial curl, tenga en cuenta lo siguiente:

    • En lugar de --header "Authorization: Bearer ${DATABRICKS_TOKEN}", puede usar un archivo .netrc . Si usa un archivo .netrc, reemplace --header "Authorization: Bearer ${DATABRICKS_TOKEN}" por --netrc.
    • Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, reemplace \ por ^ y reemplace ${...} por %...%.
    • Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, en declaraciones de documento JSON, reemplace el ' de apertura y cierre por " y reemplace el " interior por \".

    Para los ejemplos de curl de este tutorial, se asume que dispones de las siguientes variables de entorno en tu máquina de desarrollo local.

    • DATABRICKS_HOST, que representa el nombre de la instancia del área de trabajo, por ejemplo adb-1234567890123456.7.azuredatabricks.net, para el área de trabajo de Azure Databricks.
    • DATABRICKS_TOKEN, que representa un token de acceso personal de Azure Databricks para el usuario del área de trabajo de Azure Databricks.
    • DATABRICKS_SQL_WAREHOUSE_ID, que representa el identificador de almacén de Databricks SQL. Este identificador es la cadena de letras y números siguientes /sql/1.0/warehouses/ en el campo ruta de acceso HTTP del almacén. Para obtener información sobre cómo obtener el valor de la ruta de acceso HTTP del almacenamiento, consulte Obtención de detalles de conexión para un recurso de proceso de Azure Databricks.

    Nota:

    Como procedimiento recomendado de seguridad, al autenticarse con herramientas automatizadas, sistemas, scripts y aplicaciones, Databricks recomienda usar tokens de acceso personales que pertenecen a entidades de servicio en lugar de usuarios del área de trabajo. Para crear tokens para entidades de servicio, consulte Administración de tokens para una entidad de servicio.

    Para crear un token de acceso personal de Azure Databricks, siga los pasos descritos en Creación de tokens de acceso personal para los usuarios del área de trabajo.

    Advertencia

    Databricks no recomienda codificar de forma rígida información en los scripts, ya que esta información confidencial se puede ver expuesta en texto sin formato a través de sistemas de control de versiones. En su lugar, Databricks recomienda usar enfoques como las variables de entorno que establezca en la máquina de desarrollo. Quitar esta información codificada de forma rígida de los scripts ayuda a hacer que esos scripts también sean más portátiles.

• En este tutorial se da por supuesto que también tiene jq, un procesador de línea de comandos para consultar las cargas de respuesta JSON, que la API de ejecución de instrucciones SQL de Databricks le devuelve después de cada llamada que realice a la misma. Consulte Descargar jq.

• Debe tener al menos una tabla en la que puede ejecutar instrucciones SQL. Este tutorial se basa en la tabla lineitem del esquema tpch (también conocida como base de datos) en el catálogo samples. Si no tiene acceso a este catálogo, esquema o tabla desde el área de trabajo, sustituya por el suyo propio en este tutorial.

Paso 1: Ejecutar una instrucción SQL y guardar el resultado de los datos como JSON

Ejecute el siguiente comando, que hace lo siguiente:

1. Utilice el almacén SQL especificado, junto con el token especificado si está utilizandocurl, para consultar tres columnas de las dos primeras filas de la tabla lineitem en el esquema tcph dentro del catálogosamples.
2. Guarda la carga de respuesta en formato JSON en un archivo denominado sql-execution-response.json dentro del directorio de trabajo actual.
3. Imprima el contenido del archivo sql-execution-response.json.
4. Establece una variable de entorno local denominada SQL_STATEMENT_ID. Esta variable contiene el identificador de la instrucción SQL correspondiente. Puede usar este identificador de instrucción SQL para obtener información sobre esa instrucción más adelante según sea necesario, que se muestra en el paso 2. También puede ver esta instrucción SQL y obtener su identificador de instrucción en la sección de historial de consultas de la consola SQL de Databricks, o llamando a la API de Historial de Consultas.
5. Establece una variable de entorno local adicional denominada NEXT_CHUNK_EXTERNAL_LINK que contiene un fragmento de dirección URL de API para obtener el siguiente fragmento de datos JSON. Si los datos de respuesta son demasiado grandes, la API de ejecución de sentencias SQL de Databricks proporciona la respuesta en fragmentos. Puede usar este fragmento de dirección URL de API para obtener el siguiente fragmento de datos, que se muestra en el paso 2. Si no hay ningún fragmento siguiente, esta variable de entorno se establece en null.
6. Imprime los valores de las variables de entorno SQL_STATEMENT_ID y NEXT_CHUNK_INTERNAL_LINK.

CLI de Databricks

databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

En la solicitud anterior:

• Las consultas con parámetros constan del nombre de cada parámetro de consulta precedido por dos puntos (por ejemplo, :extended_price) con un objeto coincidente name y value en la parameters matriz. También se puede especificar un valor opcional type, con el valor predeterminado de STRING si no se especifica.

  Advertencia

  Databricks recomienda encarecidamente usar parámetros como procedimiento recomendado para las instrucciones SQL.

  Si usa Databricks SQL Statement Execution API con una aplicación que genera SQL dinámicamente, esto puede provocar ataques por inyección de código SQL. Por ejemplo, si genera código SQL basado en las selecciones de un usuario en una interfaz de usuario y no toma medidas adecuadas, un atacante podría insertar código SQL malintencionado para cambiar la lógica de la consulta inicial, leyendo, cambiando o eliminando datos confidenciales.

  Las consultas con parámetros ayudan a protegerse frente a ataques por inyección de código SQL mediante el control de argumentos de entrada por separado del resto del código SQL e interpretando estos argumentos como valores literales. Los parámetros también ayudan con la reutilización del código.

• De forma predeterminada, los datos devueltos están en formato de matriz JSON y la ubicación predeterminada para cualquiera de los resultados de datos de la instrucción SQL se encuentra dentro de la carga de respuesta. Para que este comportamiento sea explícito, agregue "format":"JSON_ARRAY","disposition":"INLINE" a la carga de la solicitud. Si intenta devolver resultados de datos mayores de 25 MiB en la carga de respuesta, se devuelve un estado de error y se cancela la instrucción SQL. Para resultados de datos superiores a 25 MiB, puede utilizar vínculos externos en lugar de intentar devolverlos en la carga útil de la respuesta, lo que se demuestra en el paso 3.

• El comando almacena el contenido de la carga de respuesta en un archivo local. La API de ejecución de sentencias SQL de Databricks no admite directamente el almacenamiento local de datos.

• De forma predeterminada, después de 10 segundos, si la instrucción SQL aún no ha terminado de ejecutarse a través del almacenamiento, la API de ejecución de instrucciones SQL de Databricks devuelve solo el identificador de instrucción SQL y su estado actual, en lugar del resultado de la instrucción. Para cambiar este comportamiento, agregue "wait_timeout" a la solicitud y configure a "<x>s", donde <x> puede estar entre 5 y 50 segundos inclusive, por ejemplo "50s". Para devolver el identificador de instrucción SQL y su estado actual inmediatamente, establezca wait_timeout en 0s.

• De forma predeterminada, la instrucción SQL continúa ejecutándose si se alcanza el período de tiempo de espera. Para cancelar una instrucción SQL si se alcanza el período de tiempo de espera, agregue "on_wait_timeout":"CANCEL" a la carga de la solicitud.

• Para limitar el número de bytes devueltos, agregue "byte_limit" a la solicitud y establézcalo en el número de bytes, por ejemplo 1000.

• Para limitar el número de filas devueltas, en lugar de agregar una cláusula LIMIT a statement, puede agregar "row_limit" a la solicitud y establecerla en el número de filas, por ejemplo "statement":"SELECT * FROM lineitem","row_limit":2.

• Si el resultado es mayor que el especificado byte_limit o row_limit, el campo truncated se establece true en la carga de respuesta.

Si el resultado de la instrucción está disponible antes de que finalice el tiempo de espera, la respuesta es la siguiente:

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 2,
        "row_offset": 0
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_chunk_count": 1,
    "total_row_count": 2,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      ["2", "71433.16", "1997-01-28"],
      ["7", "86152.02", "1996-01-15"]
    ],
    "row_count": 2,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Si el tiempo de espera finaliza antes de que el resultado de la instrucción esté disponible, la respuesta será así:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Si los datos de resultados de la instrucción son demasiado grandes (por ejemplo, en este caso, al ejecutar SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), los datos de resultado se fragmentan y se presentan de esta manera. Tenga en cuenta que "...": "..." indica los resultados omitidos para mayor brevedad:

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 188416,
        "row_offset": 0
      },
      {
        "chunk_index": 1,
        "row_count": 111584,
        "row_offset": 188416
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_chunk_count": 2,
    "total_row_count": 300000,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [["2", "71433.16", "1997-01-28"], ["..."]],
    "next_chunk_index": 1,
    "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
    "row_count": 188416,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Paso 2: Obtener el estado de ejecución actual de una instrucción y el resultado de los datos como JSON

Puede usar el identificador de una instrucción SQL para obtener el estado de ejecución actual de esa instrucción y, si la ejecución se realizó correctamente, el resultado de esa instrucción. Si olvida el identificador de la instrucción, puede obtenerlo desde la sección de historial de consultas de la consola de SQL de Databricks o llamando a la API de historial de consultas. Por ejemplo, podría seguir sondeando este comando, comprobando cada vez para ver si la ejecución se ha realizado correctamente.

Para obtener el estado de ejecución actual de una instrucción SQL y, si la ejecución se realizó correctamente, el resultado de esa instrucción y un fragmento de dirección URL de API para obtener cualquier fragmento siguiente de datos JSON, ejecute el siguiente comando. Este comando asume que tiene una variable de entorno en su máquina de desarrollo local llamada SQL_STATEMENT_ID, que se establece en el valor del identificador de la instrucción SQL del paso anterior. Por supuesto, puede sustituir ${SQL_STATEMENT_ID} en el siguiente comando por el identificador codificado de forma rígida de la instrucción SQL.

CLI de Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Si NEXT_CHUNK_INTERNAL_LINK se establece en un valor distinto de null, puede usarlo para obtener el siguiente fragmento de datos, etc., por ejemplo, con el siguiente comando:

CLI de Databricks

databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Puede seguir ejecutando el comando anterior, una y otra vez, para obtener el siguiente fragmento, etc. Tenga en cuenta que en cuanto se captura el último fragmento, se cierra la instrucción SQL. Después de este cierre, no puede usar el ID de la declaración para obtener su estado actual o para recuperar más datos.

Paso 3: Obtención de resultados de gran tamaño mediante enlaces externos

Esta sección muestra una configuración opcional que utiliza la disposición EXTERNAL_LINKS para recuperar grandes conjuntos de datos. La ubicación predeterminada (disposición) para los datos de resultado de la instrucción SQL es dentro de la carga útil de la respuesta, pero estos resultados están limitados a 25 MiB. Al establecer el disposition a EXTERNAL_LINKS, la respuesta contiene URLs que puede utilizar para recuperar los trozos de los datos de resultados con HTTP estándar. Las URLs apuntan al DBFS interno de su área de trabajo, donde los fragmentos del resultado se almacenan temporalmente.

Advertencia

Databricks recomienda encarecidamente que proteja las URL y los tokens devueltos por la disposición EXTERNAL_LINKS.

Cuando se utiliza la disposición EXTERNAL_LINKS, se genera una URL de firma de acceso compartido (SAS), que puede utilizarse para descargar los resultados directamente del almacenamiento Azure. Como en esta URL SAS se incluye un token SAS de corta duración, debe proteger tanto la URL SAS como el token SAS.

Dado que las URL SAS ya se generan con tokens SAS temporales incrustados, no debe establecer un encabezado Authorization en las solicitudes de descarga.

La disposición EXTERNAL_LINKS puede desactivarse a petición mediante la creación de un caso de soporte.

Consulte también Procedimientos recomendados de seguridad.

Nota:

El comportamiento y el formato de salida de la carga de respuesta, una vez establecidos para un identificador de instrucción SQL determinado, no se puede cambiar.

En este modo, la API permite almacenar datos de resultados en formato JSON (JSON), formato CSV (CSV) o formato de flecha de Apache (ARROW_STREAM), que se deben consultar por separado con HTTP. Además, al usar este modo, no es posible insertar los datos de resultado dentro de la carga de respuesta.

El siguiente comando muestra el uso EXTERNAL_LINKS y el formato de flecha de Apache. Utilice este patrón en lugar de la consulta similar demostrada en el paso 1:

CLI de Databricks

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

La respuesta es la siguiente:

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "row_count": 100000,
        "row_offset": 0
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_byte_count": 2843848,
    "total_chunk_count": 1,
    "total_row_count": 100000,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "row_count": 100000,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Si la solicitud agota el tiempo de espera, la respuesta tiene este aspecto en su lugar:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Para obtener el estado de ejecución actual de esa instrucción y, si la ejecución se realizó correctamente, el resultado de esa instrucción, ejecute el siguiente comando:

CLI de Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Si la respuesta es lo suficientemente grande (por ejemplo, en este caso, al ejecutar SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem sin límite de filas), la respuesta tendrá varios fragmentos, como en el ejemplo siguiente. Tenga en cuenta que "...": "..." indica los resultados omitidos para mayor brevedad:

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "row_count": 403354,
        "row_offset": 0
      },
      {
        "byte_count": 6282464,
        "chunk_index": 1,
        "row_count": 220939,
        "row_offset": 403354
      },
      {
        "...": "..."
      },
      {
        "byte_count": 6322880,
        "chunk_index": 10,
        "row_count": 222355,
        "row_offset": 3113156
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_byte_count": 94845304,
    "total_chunk_count": 11,
    "total_row_count": 3335511,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "next_chunk_index": 1,
        "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
        "row_count": 403354,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Para descargar los resultados del contenido almacenado, puede ejecutar el siguiente curl comando, mediante la dirección URL del external_link objeto y especificando dónde desea descargar el archivo. No incluya el token de Azure Databricks en este comando:

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

Para descargar un fragmento específico de los resultados de un contenido transmitido, puede usar uno de los siguientes:

• Valor next_chunk_index de la carga de respuesta del siguiente fragmento (si hay un fragmento siguiente).
• Uno de los índices de fragmento presentes en el manifiesto de la carga útil de la respuesta para cualquier fragmento disponible, en caso de haber múltiples fragmentos.

Por ejemplo, para obtener el fragmento con chunk_index de 10 para la respuesta anterior, ejecute el siguiente comando:

CLI de Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Nota:

La ejecución del comando anterior devuelve una nueva URL SAS.

Para descargar el fragmento almacenado, utilice la URL del objeto external_link.

Para obtener más información sobre el formato de Apache Arrow, consulte:

• Formato de streaming IPC
• Escritura y lectura del formato de streaming
• Uso de secuencias

Paso 4: Cancelar la ejecución de una instrucción SQL

Si necesita cancelar una instrucción SQL que aún no se ha realizado correctamente, ejecute el siguiente comando:

CLI de Databricks

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

Reemplace <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.

rizo

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Recomendaciones de seguridad

La API de ejecución de sentencias SQL de Databricks aumenta la seguridad de las transferencias de datos mediante el uso de cifrado de capa de transporte (TLS) de extremo a otro y credenciales de corta duración, como los tokens SAS.

Hay varias capas en este modelo de seguridad. En la capa de transporte, solo es posible llamar a la API de ejecución de instrucciones de Databricks SQL usando TLS 1.2 o superior. Además, los llamantes de la API de ejecución de declaraciones SQL de Databricks deben autenticarse con un token de acceso personal de Azure Databricks válido, un token de acceso de OAuth o un token de Microsoft Entra (anteriormente Azure Active Directory) que se asigna a un usuario que tiene el derecho de usar Databricks SQL. Este usuario debe tener acceso CAN USE para el almacenamiento SQL específico que se está usando y el acceso se puede restringir con listas de acceso IP. Esto se aplica a todas las solicitudes a la API de ejecución de sentencias SQL de Databricks. Además, para ejecutar sentencias, el usuario autenticado debe tener permiso para los objetos de datos (como tablas, vistas y funciones) que se utilizan en cada sentencia. Esto se aplica mediante los mecanismos de control de acceso existentes en Unity Catalog o mediante el uso de ACL de tablas. (Consulte Gobernanza de datos con Azure Databricks para más información). Esto también significa que solo el usuario que ejecuta una instrucción puede realizar solicitudes de captura para los resultados de la instrucción.

Databricks recomienda aplicar los siguientes procedimientos recomendados de seguridad siempre que se utilice la API de ejecución de sentencias SQL de Databricks junto con la disposición EXTERNAL_LINKS para recuperar grandes conjuntos de datos:

• Elimine el encabezado de autorización de Databricks para las solicitudes de almacenamiento de Azure.
• Protección de direcciones URL de SAS y tokens de SAS

La disposición EXTERNAL_LINKS puede desactivarse a petición mediante la creación de un caso de soporte. Para realizar esta solicitud, póngase en contacto con el equipo de la cuenta de Azure Databricks.

Elimine el encabezado de autorización de Databricks para las solicitudes de almacenamiento de Azure.

Todas las llamadas a Databricks SQL Statement Execution API que se utilicen curldeben incluirAuthorization un encabezado que contenga las credenciales de acceso a Azure Databricks. No incluya este encabezado Authorization siempre que descargue datos del almacenamiento de Azure. Este encabezado no es necesario y podría exponer involuntariamente sus credenciales de acceso a Azure Databricks.

Protección de direcciones URL de SAS y tokens de SAS

Siempre que use la disposición EXTERNAL_LINKS, se genera una URL SAS de corta duración, que la persona que llama puede utilizar para descargar los resultados directamente desde el almacenamiento Azure mediante TLS. Como un token SAS de corta duración está incrustado dentro de esta URL SAS, debe proteger tanto la URL SAS como el token SAS.