Enviar uma solicitação para executar instruções SQL¶

Como configurar a solicitação¶

Na URL de solicitação, você pode definir parâmetros de consulta para:

• Especifique uma ID de solicitação que distingue essa solicitação de outras solicitações.

• Execute a instrução de forma assíncrona.

Para o corpo da solicitação, defina os seguintes campos:

• Defina o campo statement para a instrução SQL que você deseja executar. Por exemplo:

  {
    "statement": "select * from my_table",
    ...
  }
  

  Copy

  Se você quiser apresentar várias instruções em uma única solicitação, use um ponto-e-vírgula (;) entre as instruções. Consulte Envio de múltiplas instruções SQL em apenas uma solicitação para obter mais detalhes.

• Se você incluir variáveis de vinculação (placeholders ?) na instrução, defina o campo bindings como um objeto que especifique os valores e tipos de dados do Snowflake correspondentes para cada variável.

  Para obter mais detalhes, consulte Como usar variáveis de vinculação em uma instrução.

• Para especificar o warehouse, banco de dados, esquema e função a usar, defina os campos warehouse, database, schema e role.

  Os valores nesses campos diferenciam entre maiúsculas e minúsculas.

  Se você omitir esses campos, a API do SQL utilizará os valores das propriedades correspondentes para o usuário (isso é, as propriedades DEFAULT_WAREHOUSE, DEFAULT_NAMESPACE e DEFAULT_ROLE do usuário).

• Para definir um tempo limite para a execução da instrução, defina o campo timeout com o número máximo de segundos a esperar. Se o campo timeout não estiver definido, será usado o tempo limite especificado pelo parâmetro STATEMENT_TIMEOUT_IN_SECONDS.

Exemplo de uma solicitação¶

Por exemplo, o seguinte comando curl envia uma instrução SQL para execução. O exemplo usa o arquivo request-body.json para especificar o corpo da solicitação.

curl -i -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt>" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    -d "@request-body.json" \
    "https://<account_identifier>.snowflakecomputing.com/api/v2/statements"

onde:

• jwt é o JWT que você gerou para a autenticação.

• myApplicationName é um exemplo de um identificador para seu aplicativo.

• account_identifier é seu identificador da conta.

Neste exemplo, request-body.json contém o corpo da solicitação:

{
  "statement": "select * from T where c1=?",
  "timeout": 60,
  "database": "TESTDB",
  "schema": "TESTSCHEMA",
  "warehouse": "TESTWH",
  "role": "TESTROLE",
  "bindings": {
    "1": {
      "type": "FIXED",
      "value": "123"
    }
  }
}

No corpo da solicitação no exemplo acima:

• O campo statement especifica a instrução SQL a ser executada.

  A instrução inclui uma variável de vinculação (o ponto de interrogação em "cl=?"), que é avaliada como a primeira vinculação ("1") especificada no campo bindings.

• O campo timeout especifica que o servidor permite 60 segundos para que a instrução seja executada.

• Os campos database, schema, warehouse e role especificam que a o banco de dados TESTDB, o esquema TESTSCHEMA, o warehouse TESTWH e a função TESTROLE devem ser usadas ao executar a instrução.

Como usar variáveis de vinculação em uma instrução¶

Se você quiser usar variáveis de vinculação (placeholders ?) na instrução, use o campo bindings para especificar os valores que devem ser inseridos.

Defina este campo como um objeto JSON que especifique o tipo de dados do Snowflake e valor para cada variável de vinculação.

...
"statement": "select * from T where c1=?",
...
"bindings": {
  "1": {
    "type": "FIXED",
    "value": "123"
  }
},
...

Escolha o tipo de vinculação que corresponde ao tipo do valor que você está vinculando. Por exemplo, se o valor for uma cadeia de caracteres representando uma data (por exemplo, 2021-04-15) e você quiser inserir o valor em uma coluna DATE, use o tipo de vinculação TEXT.

A tabela a seguir especifica os valores do campo type que você pode usar para vincular a diferentes tipos de dados do Snowflake para esta versão preliminar.

• A primeira coluna à esquerda especifica os tipos de vinculação que você pode usar.

• O resto das colunas especificam o tipo de dados do Snowflake da coluna onde você pretende inserir os dados.

• Cada célula especifica o tipo de valor que você pode usar com um tipo de vinculação para inserir dados em uma coluna de um determinado tipo de dados do Snowflake.

  Se a célula para um tipo de vinculação e tipo de dados do Snowflake estiver vazia, não será possível usar o tipo de vinculação especificado para inserir dados em uma coluna desse tipo de dados do Snowflake.

Observe o seguinte:

• Os valores das variáveis de vinculação devem ser cadeias de caracteres (por exemplo, "1.0" para o valor 1.0).

• Ao utilizar o tipo de vinculação DATE, especifique o número de milissegundos desde a época.

• Ao utilizar o tipo de vinculação TIME ou TIMESTAMP*, especifique o número de nanossegundos desde a época.

• Ao utilizar o tipo de vinculação TIMESTAMP_TZ, especifique o número de nanossegundos desde a época, seguido por um espaço e a diferença de fuso horário em minutos (por exemplo, 1616173619000000000 960).

• Ao utilizar o tipo de vinculação TEXT:

  • Para inserir dados em uma coluna DATE, você pode usar qualquer formato de data que seja suportado pela detecção AUTO.

  • Para inserir dados em uma coluna TIME, você pode usar qualquer formato de tempo que seja suportado pela detecção AUTO.

  • Para inserir dados em uma coluna TIMEZONE*, você pode usar qualquer formato de data-hora que seja suportado pela detecção AUTO.

Se o valor estiver em um formato não suportado pelo Snowflake, a API retornará um erro:

{
  code: "100037",
  message: "<bind type> value '<value>' is not recognized",
  sqlState: "22018",
  statementHandle: "<ID>"
}

Envio de solicitações simultâneas¶

A API do SQL no Snowflake oferece suporte para o envio de solicitações simultâneas ao servidor. Os limites de simultaneidade da API são determinados pelos limites de simultaneidade impostos pelo Snowflake.

Dependendo da carga atual do servidor, você pode ter um erro HTTP 429, que indica que o servidor está recebendo solicitações demais no momento.

Para garantir que seu aplicativo trate corretamente os erros 429, insira as solicitações simultâneas dentro de uma lógica de nova tentativa.

Como reenviar uma solicitação para executar instruções SQL¶

Em alguns casos, pode não estar claro se o Snowflake executou a instrução SQL em uma solicitação à API (por exemplo, devido a um erro na rede ou a um timeout). Você pode optar por reenviar a mesma solicitação ao Snowflake novamente caso o Snowflake não tenha executado a instrução.

Entretanto, se o Snowflake já tiver executado a instrução na solicitação inicial e você reenviar a solicitação, a instrução será executada duas vezes. Para alguns tipos de solicitações, a execução repetida da mesma instrução pode ter consequências não intencionais (por exemplo, a inserção de dados duplicados em uma tabela).

Para evitar que o Snowflake execute a mesma instrução duas vezes quando você reenvia uma solicitação, você pode usar uma ID de solicitação para distinguir sua solicitação de outras. Se você especificar a mesma ID de solicitação na solicitação inicial junto com o parâmetro retry=true na solicitação reenviada, o Snowflake não executará a instrução novamente se a instrução já tiver sido executada com sucesso.

Para especificar uma ID de solicitação, gere um identificador único universal (UUID). Depois disso, você poderá incluir esse identificador no parâmetro de consulta requestId. Você também deve especificar o parâmetro retry=true como parte da solicitação, como mostrado no exemplo a seguir.

POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1

Se o Snowflake não processar uma solicitação, você poderá enviar a mesma solicitação novamente com a mesma ID de solicitação. Usar a mesma ID de solicitação indica ao servidor que você está enviando a mesma solicitação novamente.