API de execução de instrução: Executar SQL em armazéns

  • Artigo

Importante

Para aceder às APIs REST do Databricks, tem de se autenticar.

Este tutorial mostra como usar a API de execução de instrução SQL Databricks 2.0 para executar instruções SQL de armazéns SQL Databricks.

Para exibir a referência Databricks SQL Statement Execution API 2.0, consulte Statement Execution.

Antes de começar

Antes de iniciar este tutorial, certifique-se de que tem:

  • Databricks CLI versão 0.205 ou superior ou curl, da seguinte forma:

    • A CLI do Databricks é uma ferramenta de linha de comando para enviar e receber solicitações e respostas da API REST do Databricks. Se você usar a CLI do Databricks versão 0.205 ou superior, ela deverá ser configurada para autenticação com seu espaço de trabalho do Azure Databricks. Consulte Instalar ou atualizar a CLI e a autenticação do Databricks para a CLI do Databricks.

      Por exemplo, para autenticar com a autenticação de token de acesso pessoal Databricks, crie um token de acesso pessoal da seguinte maneira:

      1. No seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
      2. Clique em Desenvolvedor.
      3. Ao lado de Tokens de acesso, clique em Gerenciar.
      4. Clique em Gerar novo token.
      5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
      6. Clique em Generate (Gerar).
      7. Copie o token exibido para um local seguro e clique em Concluído.

      Nota

      Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

      Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou os seguintes tópicos:

      E, em seguida, para usar a CLI do Databricks para criar um perfil de configuração do Azure Databricks para seu token de acesso pessoal, faça o seguinte:

      Nota

      O procedimento a seguir usa a CLI do Databricks para criar um perfil de configuração do Azure Databricks com o nome DEFAULT. Se você já tiver um perfil de DEFAULT configuração, este procedimento substituirá o perfil de configuração existente DEFAULT .

      Para verificar se você já tem um perfil de DEFAULT configuração e para exibir as configurações desse perfil, se ele existir, use a CLI do Databricks para executar o comando databricks auth env --profile DEFAULT.

      Para criar um perfil de configuração com um nome diferente DEFAULTde , substitua a DEFAULT parte do comando a seguir databricks configure por um nome diferente para o perfil de --profile DEFAULT configuração.

      1. Use a CLI do Databricks para criar um perfil de configuração do Azure Databricks chamado DEFAULT que usa a autenticação de token de acesso pessoal do Azure Databricks. Para tal, execute o seguinte comando:

        databricks configure --profile DEFAULT

      2. Para o prompt Databricks Host, insira sua URL do Azure Databricks por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net.

      3. Para o prompt Personal Access Token, insira o token de acesso pessoal do Azure Databricks para seu espaço de trabalho.

      Nos exemplos de CLI do Databricks deste tutorial, observe o seguinte:

      • Este tutorial pressupõe que você tenha uma variável DATABRICKS_SQL_WAREHOUSE_ID de ambiente em sua máquina de desenvolvimento local. Essa variável de ambiente representa a ID do seu armazém SQL Databricks. Este ID é a sequência de letras e números que segue /sql/1.0/warehouses/ no campo de caminho HTTP para o seu armazém. Para saber como obter o valor do caminho HTTP do seu depósito, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.
      • Se você usar o shell de comando do Windows em vez de um shell de comando para Unix, Linux ou macOS, substitua \ por ^, e substitua ${...} por %...%.
      • Se você usar o shell de comando do Windows em vez de um shell de comando para Unix, Linux ou macOS, em declarações de documento JSON, substitua a abertura e o fechamento ' por ", e substitua interno " por \".

    • curl é uma ferramenta de linha de comando para enviar e receber solicitações e respostas da API REST. Consulte também Instalar curl. Ou adapte os curl exemplos deste tutorial para uso com ferramentas semelhantes, como HTTPie.

      Nos exemplos deste curl tutorial, observe o seguinte:

      • Em vez de --header "Authorization: Bearer ${DATABRICKS_TOKEN}", você pode usar um arquivo .netrc . Se você usar um .netrc arquivo, substitua --header "Authorization: Bearer ${DATABRICKS_TOKEN}" por --netrc.
      • Se você usar o shell de comando do Windows em vez de um shell de comando para Unix, Linux ou macOS, substitua \ por ^, e substitua ${...} por %...%.
      • Se você usar o shell de comando do Windows em vez de um shell de comando para Unix, Linux ou macOS, em declarações de documento JSON, substitua a abertura e o fechamento ' por ", e substitua interno " por \".

      Além disso, para os curl exemplos deste tutorial, este tutorial pressupõe que você tenha as seguintes variáveis de ambiente em sua máquina de desenvolvimento local:

      • DATABRICKS_HOST, representando o nome da instância do espaço de trabalho, por exemploadb-1234567890123456.7.azuredatabricks.net, para seu espaço de trabalho do Azure Databricks.
      • DATABRICKS_TOKEN, representando um token de acesso pessoal do Azure Databricks para seu usuário do espaço de trabalho do Azure Databricks.
      • DATABRICKS_SQL_WAREHOUSE_ID, representando a ID do seu armazém SQL Databricks. Este ID é a sequência de letras e números que segue /sql/1.0/warehouses/ no campo de caminho HTTP para o seu armazém. Para saber como obter o valor do caminho HTTP do seu depósito, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.

      Nota

      Como prática recomendada de segurança, quando você se autentica com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que você use tokens de acesso pessoal pertencentes a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

      Para criar um token de acesso pessoal do Azure Databricks, faça o seguinte:

      1. No seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
      2. Clique em Desenvolvedor.
      3. Ao lado de Tokens de acesso, clique em Gerenciar.
      4. Clique em Gerar novo token.
      5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
      6. Clique em Generate (Gerar).
      7. Copie o token exibido para um local seguro e clique em Concluído.

      Nota

      Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

      Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou os seguintes tópicos:

      Aviso

      O Databricks desencoraja fortemente a codificação de informações em seus scripts, pois essas informações confidenciais podem ser expostas em texto simples por meio de sistemas de controle de versão. O Databricks recomenda que você use abordagens como variáveis de ambiente definidas em sua máquina de desenvolvimento. Remover essas informações codificadas de seus scripts ajuda a torná-los mais portáteis também.

  • Este tutorial pressupõe que você também tenha jq, um processador de linha de comando para consultar cargas úteis de resposta JSON, que a API de Execução de Instrução SQL do Databricks retorna a você após cada chamada feita para a API de Execução de Instrução SQL do Databricks. Consulte Download jq.

  • Você deve ter pelo menos uma tabela na qual possa executar instruções SQL. Este tutorial é baseado lineitem na tabela no tpch esquema (também conhecido como banco de dados) dentro do samples catálogo. Se você não tiver acesso a esse catálogo, esquema ou tabela do seu espaço de trabalho, substitua-os ao longo deste tutorial pelo seu próprio.

Etapa 1: Executar uma instrução SQL e salvar o resultado de dados como JSON

Execute o seguinte comando, que faz o seguinte:

  1. Usa o SQL warehouse especificado, juntamente com o token especificado se você estiver usando curl, para consultar três colunas das duas primeiras linhas da lineitem tabela no tcph esquema dentro do samples catálogo.
  2. Salva a carga útil de resposta no formato JSON em um arquivo nomeado sql-execution-response.json dentro do diretório de trabalho atual.
  3. Imprime o sql-execution-response.json conteúdo do arquivo.
  4. Define uma variável de ambiente local chamada SQL_STATEMENT_ID. Essa variável contém a ID da instrução SQL correspondente. Você pode usar essa ID de instrução SQL para obter informações sobre essa instrução posteriormente, conforme necessário, o que é demonstrado na Etapa 2. Você também pode exibir essa instrução SQL e obter sua ID de instrução na seção de histórico de consultas do console SQL do Databricks ou chamando a API do Histórico de Consultas.
  5. Define uma variável de ambiente local adicional chamada NEXT_CHUNK_EXTERNAL_LINK que contém um fragmento de URL de API para obter o próximo bloco de dados JSON. Se os dados de resposta forem muito grandes, a API de Execução de Instrução SQL do Databricks fornecerá a resposta em partes. Você pode usar esse fragmento de URL da API para obter o próximo bloco de dados, que é demonstrado na Etapa 2. Se não houver nenhum próximo bloco, essa variável de ambiente será definida como null.
  6. Imprime os valores das variáveis e SQL_STATEMENT_ID NEXT_CHUNK_INTERNAL_LINK de ambiente.

CLI do 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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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

No pedido anterior:

  • As consultas parametrizadas consistem no nome de cada parâmetro de consulta precedido por dois pontos (por exemplo, :extended_price) com um objeto e value name correspondência na parameters matriz. Um opcional type também pode ser especificado, com o valor padrão de STRING se não especificado.

    Aviso

    O Databricks recomenda enfaticamente que você use parâmetros como uma prática recomendada para suas instruções SQL.

    Se você usar a API de execução de instrução SQL Databricks com um aplicativo que gera SQL dinamicamente, isso pode resultar em ataques de injeção de SQL. Por exemplo, se você gerar código SQL com base nas seleções de um usuário em uma interface do usuário e não tomar as medidas apropriadas, um invasor poderá injetar código SQL mal-intencionado para alterar a lógica da consulta inicial, lendo, alterando ou excluindo dados confidenciais.

    As consultas parametrizadas ajudam a proteger contra ataques de injeções de SQL manipulando argumentos de entrada separadamente do resto do código SQL e interpretando esses argumentos como valores literais. Os parâmetros também ajudam na reutilização do código.

  • Por padrão, todos os dados retornados estão no formato de matriz JSON e o local padrão para qualquer um dos resultados de dados da instrução SQL está dentro da carga útil de resposta. Para tornar esse comportamento explícito, adicione "format":"JSON_ARRAY","disposition":"INLINE" à carga útil da solicitação. Se você tentar retornar resultados de dados maiores que 25 MiB na carga útil de resposta, um status de falha será retornado e a instrução SQL será cancelada. Para resultados de dados maiores que 25 MiB, você pode usar links externos em vez de tentar retorná-los na carga útil de resposta, o que é demonstrado na Etapa 3.

  • O comando armazena o conteúdo da carga útil de resposta em um arquivo local. O armazenamento de dados local não é suportado diretamente pela API de Execução de Instrução SQL do Databricks.

  • Por padrão, após 10 segundos, se a instrução SQL ainda não tiver terminado de ser executada pelo depósito, a API de Execução de Instrução SQL do Databricks retornará apenas a ID da instrução SQL e seu status atual, em vez do resultado da instrução. Para alterar esse comportamento, adicione "wait_timeout" à solicitação e defina-a como "<x>s", onde <x> pode ser entre 5 e 50 segundos inclusive, por exemplo "50s". Para retornar a ID da instrução SQL e seu status atual imediatamente, defina wait_timeout como 0s.

  • Por padrão, a instrução SQL continua a ser executada se o período de tempo limite for atingido. Para cancelar uma instrução SQL se o período de tempo limite for atingido, adicione "on_wait_timeout":"CANCEL" à carga útil da solicitação.

  • Para limitar o número de bytes retornados, adicione "byte_limit" à solicitação e defina-a com o número de bytes, por exemplo 1000.

  • Para limitar o número de linhas retornadas, em vez de adicionar uma LIMIT cláusula ao statement, você pode adicionar "row_limit" à solicitação e defini-la como o número de linhas, por exemplo "statement":"SELECT * FROM lineitem","row_limit":2.

  • Se o resultado for maior do que o especificado byte_limit ou , o truncated campo será definido como true na carga row_limitútil de resposta.

Se o resultado da instrução estiver disponível antes do tempo limite de espera terminar, a resposta será a seguinte:

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

Se o tempo limite de espera terminar antes que o resultado da instrução esteja disponível, a resposta terá esta aparência:

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

Se os dados de resultado da instrução forem muito grandes (por exemplo, neste caso, executando SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), os dados de resultado serão fragmentados e terão esta aparência. Observe que "...": "..." indica resultados omitidos aqui para brevidade:

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

Etapa 2: Obter o status de execução atual de uma instrução e o resultado dos dados como JSON

Você pode usar a ID de uma instrução SQL para obter o status de execução atual dessa instrução e, se a execução for bem-sucedida, o resultado dessa instrução. Se você esquecer a ID da instrução, poderá obtê-la na seção de histórico de consultas do console do Databricks SQL ou chamando a API do Histórico de Consultas. Por exemplo, você pode continuar pesquisando esse comando, verificando sempre se a execução foi bem-sucedida.

Para obter o status de execução atual de uma instrução SQL e, se a execução for bem-sucedida, o resultado dessa instrução e um fragmento de URL de API para obter qualquer próxima parte de dados JSON, execute o seguinte comando. Este comando pressupõe que você tenha uma variável de ambiente em sua máquina de desenvolvimento local chamada SQL_STATEMENT_ID, que é definida como o valor da ID da instrução SQL da etapa anterior. É claro que você pode substituir ${SQL_STATEMENT_ID} no comando a seguir pela ID codificada da instrução SQL.

CLI do 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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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

Se o NEXT_CHUNK_INTERNAL_LINK estiver definido como um não-valornull , você poderá usá-lo para obter o próximo bloco de dados e assim por diante, por exemplo, com o seguinte comando:

CLI do 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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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

Você pode continuar executando o comando anterior, repetidamente, para obter o próximo bloco, e assim por diante. Observe que assim que o último bloco é buscado, a instrução SQL é fechada. Após esse fechamento, você não pode usar o ID dessa instrução para obter seu status atual ou para buscar mais partes.

Esta seção demonstra uma configuração opcional que usa a EXTERNAL_LINKS disposição para recuperar grandes conjuntos de dados. O local padrão (disposição) para os dados de resultado da instrução SQL está dentro da carga útil de resposta, mas esses resultados são limitados a 25 MiB. Ao definir como disposition EXTERNAL_LINKS, a resposta contém URLs que você pode usar para buscar os blocos dos dados de resultados com HTTP padrão. As URLs apontam para o DBFS interno do seu espaço de trabalho, onde os blocos de resultados são armazenados temporariamente.

Aviso

O Databricks recomenda enfaticamente que você proteja as URLs e tokens retornados pela EXTERNAL_LINKS disposição.

Quando você usa a EXTERNAL_LINKS disposição, uma URL de assinatura de acesso compartilhado (SAS) é gerada, que pode ser usada para baixar os resultados diretamente do armazenamento do Azure. Como um token SAS de curta duração é incorporado nessa URL SAS, você deve proteger a URL SAS e o token SAS.

Como as URLs SAS já são geradas com tokens SAS temporários incorporados, você não deve definir um Authorization cabeçalho nas solicitações de download.

A EXTERNAL_LINKS disposição pode ser desativada mediante solicitação, criando um caso de suporte.

Consulte também Práticas recomendadas de segurança.

Nota

O formato e o comportamento da saída da carga útil de resposta, uma vez definidos para uma ID de instrução SQL específica, não podem ser alterados.

Nesse modo, a API permite armazenar dados de resultados no formato JSON (JSON), formato CSV (CSV) ou formato de seta Apache (ARROW_STREAM), que devem ser consultados separadamente com HTTP. Além disso, ao usar esse modo, não é possível inserir os dados do resultado na carga útil de resposta.

O comando a seguir demonstra o uso EXTERNAL_LINKS do formato de seta Apache. Use esse padrão em vez da consulta semelhante demonstrada na Etapa 1:

CLI do 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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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

A resposta é a seguinte:

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

Se a solicitação expirar, a resposta terá esta aparência:

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

Para obter o status de execução atual dessa instrução e, se a execução for bem-sucedida, o resultado dessa instrução, execute o seguinte comando:

CLI do Databricks

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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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'

Se a resposta for grande o suficiente (por exemplo, neste caso, executando SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem sem limite de linha), a resposta terá vários blocos, como no exemplo a seguir abaixo. Observe que "...": "..." indica resultados omitidos aqui para brevidade:

{
  "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 baixar os resultados do conteúdo armazenado, você pode executar o seguinte curl comando, usando a URL no external_link objeto e especificando onde deseja baixar o arquivo. Não inclua seu token do Azure Databricks neste comando:

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

Para baixar uma parte específica dos resultados de um conteúdo transmitido, você pode usar uma das seguintes opções:

  • O next_chunk_index valor da carga útil de resposta para a próxima parte (se houver uma próxima parte).
  • Um dos índices de bloco do manifesto da carga útil de resposta para qualquer bloco disponível se houver vários blocos.

Por exemplo, para obter o bloco com um chunk_index de 10 da resposta anterior, execute o seguinte comando:

CLI do 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'

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

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

A execução do comando anterior retorna uma nova URL SAS.

Para baixar o bloco armazenado, use a URL no external_link objeto.

Para obter mais informações sobre o formato de seta do Apache, consulte:

Etapa 4: Cancelar a execução de uma instrução SQL

Se você precisar cancelar uma instrução SQL que ainda não foi bem-sucedida, execute o seguinte comando:

CLI do Databricks

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

Substitua <profile-name> pelo nome do seu perfil de configuração do Azure Databricks para autenticação.

curl

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

Melhores práticas de segurança

A API de Execução de Instrução SQL do Databricks aumenta a segurança das transferências de dados usando criptografia TLS (Transport Layer Security) de ponta a ponta e credenciais de curta duração, como tokens SAS.

Existem várias camadas neste modelo de segurança. Na camada de transporte, só é possível chamar a API de Execução de Instrução SQL do Databricks usando TLS 1.2 ou superior. Além disso, os chamadores da API de Execução de Instrução SQL do Databricks devem ser autenticados com um token de acesso pessoal válido do Azure Databricks, token de acesso OAuth ou token Microsoft Entra ID (anteriormente Azure Ative Directory) que mapeia para um usuário que tem o direito de usar o Databricks SQL. Esse usuário deve ter acesso CAN USE para o SQL warehouse específico que está sendo usado, e o acesso pode ser restrito com listas de acesso IP. Isso se aplica a todas as solicitações para a API de execução de instrução SQL do Databricks. Além disso, para executar instruções, o usuário autenticado deve ter permissão para os objetos de dados (como tabelas, exibições e funções) que são usados em cada instrução. Isso é imposto por mecanismos de controle de acesso existentes no Unity Catalog ou usando ACLs de tabela. (Ver Governança de dados com o Unity Catalog para obter mais detalhes.) Isso também significa que apenas o usuário que executa uma instrução pode fazer solicitações de busca para os resultados da instrução.

O Databricks recomenda as seguintes práticas recomendadas de segurança sempre que você usar a API de execução de instrução SQL do Databricks juntamente com a EXTERNAL_LINKS disposição para recuperar grandes conjuntos de dados:

  • Remover o cabeçalho de autorização do Databricks para solicitações de armazenamento do Azure
  • Proteja URLs e tokens SAS

A EXTERNAL_LINKS disposição pode ser desativada mediante solicitação, criando um caso de suporte. Para fazer essa solicitação, entre em contato com sua equipe de conta do Azure Databricks.

Remover o cabeçalho de autorização do Databricks para solicitações de armazenamento do Azure

Todas as chamadas para a API de Execução de Instrução SQL do Databricks que usam curl devem incluir um Authorization cabeçalho que contenha credenciais de acesso do Azure Databricks. Não inclua esse Authorization cabeçalho sempre que baixar dados do armazenamento do Azure. Esse cabeçalho não é necessário e pode expor involuntariamente suas credenciais de acesso do Azure Databricks.

Proteja URLs e tokens SAS

Sempre que você usa a EXTERNAL_LINKS disposição, uma URL SAS de curta duração é gerada, que o chamador pode usar para baixar os resultados diretamente do armazenamento do Azure usando TLS. Como um token SAS de curta duração está incorporado nessa URL SAS, você deve proteger a URL SAS e o token SAS.