Compartir a través de

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

  • Artículo

Importante

Para acceder a las API REST de Databricks, es preciso autenticarse.

Este tutorial le muestra cómo usar la API de ejecución de instrucciones SQL 2.0 de Databricks para ejecutar instrucciones SQL desde almacenes de Databricks SQL.

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 Tokens de acceso personal de Azure Databricks para los 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 siguiente procedimiento 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 perfil de configuración DEFAULT y para ver esta configuración de 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 use la autenticación de token de acceso personal de Azure Databricks. Para ello, ejecute el siguiente comando:

        databricks configure --profile DEFAULT

      2. En el símbolo del sistema Host de Databricks, escriba la dirección URL por área de trabajo de Azure Databricks, por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net.

      3. En el símbolo del sistema Token de acceso personal, escriba el token de acceso personal de Azure Databricks para el á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 Id. 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 HTTP de su almacén, consulte Obtener detalles de conexión para un recurso informático 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 Instalación de curl. Como alternativa, puede adaptar los ejemplos de curl de este tutorial para su uso con herramientas similares, como HTTPie.

      En los ejemplos curl de este tutorial, 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 \".

      Además, en los ejemplos curl de este tutorial, en este tutorial se asume que tiene las siguientes variables de entorno en la máquina de desarrollo local:

      Nota:

      Como procedimiento recomendado de seguridad, cuando se autentique con herramientas, sistemas, scripts y aplicaciones automatizados, Databricks recomienda usar los tokens de acceso personal pertenecientes a las entidades de servicio en lugar de a los usuarios del área de trabajo. Para crear tókenes para entidades de servicio, consulte Administración de tokens de acceso para una entidad de servicio.

      Para crear un token de acceso personal de Azure Databricks, siga los pasos de los tokens de acceso personal de Azure Databricks 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.

  • Este tutorial asume que también tiene jq, un procesador de línea de comandos para consultar cargas útiles de respuesta JSON, que la API de ejecución de sentencias SQL de Databricks devuelve después de cada llamada realizada a la API de ejecución de sentencias SQL de Databricks. 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 desde la sección Historial de consultas de la consola de Databricks SQL o llamando a Query History API.
  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

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

curl

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 de dos puntos (por ejemplo, :extended_price) con un objeto name y value correspondiente en la matriz parameters. 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 manera predeterminada, después de 10 segundos, si la sentencia SQL aún no ha terminado de ejecutarse a través del almacén, la API de ejecución de sentencias SQL de Databricks solo devuelve el ID de la sentencia SQL y su estado actual, en lugar del resultado de la sentencia. 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 tendrá este aspecto en su lugar:

{
  "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, mediante la ejecución de SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), los datos de resultado se fragmentan y tienen este aspecto en su lugar. 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 Historial de consultas de la consola de Databricks SQL o mediante la llamada a Query History API. 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

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

curl

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

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

curl

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 identificador de esa instrucción para obtener su estado actual o para capturar más fragmentos.

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 URL apuntan al DBFS interno del área de trabajo, donde se almacenan temporalmente los fragmentos de resultados.

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

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

curl

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 comando siguiente.

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'

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

curl

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 comando curl, mediante la URL del objeto external_link 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 del manifiesto de la carga de respuesta para cualquier fragmento disponible si hay varios 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'

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

curl

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:

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 '{}'

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

curl

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 llamadores de la API de ejecución de instrucciones 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 ID (anteriormente Azure Active Directory) que se asigna a un usuario que tiene derecho a usar Databricks SQL. El usuario debe tener acceso CAN USE para el almacén SQL específico que se utiliza, y el acceso puede restringirse 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 Unity Catalog para obtener más detalles). Esto también significa que solo el usuario que ejecuta una sentencia puede realizar solicitudes de obtención de los resultados de la sentencia.

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.