API SQL Snowflake: mudanças no processo de envio de instruções SQL

Neste lançamento, API SQL Snowflake introduz mudanças destinadas a melhorar a eficiência do processamento da API SQL.

Como parte dessas mudanças, algumas funcionalidades estão sendo descontinuadas, conforme descrito neste artigo:

Habilitando a nova funcionalidade da API SQL

Para ativar a nova funcionalidade da API SQL para uma determinada solicitação, defina o formato do campo de resultSetMetaData como jsonv2, conforme mostrado no exemplo a seguir:

{
  "statement": "select * from mytable",
  "resultSetMetaData": {
     "format": "jsonv2"
    },
  ...
 }
Copy

Para usar a funcionalidade obsoleta para processar resultados, omita o campo resultSetMetaData ou defina o campo de formato como json.

  • Observação: no futuro, a API SQL usará esta nova funcionalidade por padrão. Quando a API SQL for lançada para disponibilidade geral (GA), a funcionalidade obsoleta não terá mais suporte.

Funcionalidade alterada e obsoleta

A API SQL Snowflake não retorna mais dados em páginas de tamanho consistente. Em vez disso, a API SQL retorna partições, que são partes físicas únicas de dados. O tamanho de cada partição é variável e determinado automaticamente por Snowflake no tempo de execução.

Com essas alterações:

  • Você não pode mais especificar o parâmetro <>nullable em uma solicitação GET. Ele só pode ser especificado em uma solicitação POST para enviar uma instrução SQL para execução.

    Por exemplo:

    POST /api/statements?nullable=false

  • O parâmetro pageSize está obsoleto. Snowflake retorna uma partição de dados em cada resposta e determina o tamanho dessa partição. O tamanho de uma partição é variável e se baseia na quantidade de dados devolvidos pelo Snowflake para uma determinada consulta SQL.

  • O parâmetro página é substituído pelo parâmetro partição. Em vez de usar o parâmetro página para especificar a próxima página de dados a ser retornada, use o parâmetro partição para especificar a próxima partição de dados a ser retornada.

    Depois de receber a resposta contendo a primeira partição de dados, você pode obter o restante das partições enviando solicitações com partição=<número_da_partição>, onde <número_da_partição> identifica a partição de dados a ser retornada. O número da partição 0 identifica a primeira partição de dados, que é retornada na solicitação inicial.

    Por exemplo, depois de receber a primeira partição de dados, você pode obter a segunda partição de dados enviando uma solicitação com o parâmetro partição definido como 1:

    GET /api/statements/<handle>?partition=1

  • Ao enviar uma solicitação para executar uma consulta, a resposta inclui metadados que descrevem como os dados são particionados entre as respostas, bem como a primeira partição de dados.

    O corpo dessa resposta inclui um campo partitionInfo. Este campo contém uma matriz de objetos e cada uma delas descreve uma partição de dados. Esse primeiro objeto descreve a partição de dados retornados nessa resposta. O restante dos objetos descreve as partições adicionais que você pode recuperar enviando solicitações subsequentes com partition=<número_da_partição>.

    Cada objeto na matriz especifica o número de linhas e o tamanho de uma partição. Seu aplicativo pode usar esses metadados de partição para determinar como lidar com as partições retornadas para solicitações subsequentes.

    O exemplo a seguir mostra uma parte da resposta:

     {
 "resultSetMetaData": {
  "numRows: 1300,
  "format": "jsonv2"
  "rowType": {
    ... // column metadata. No change
  },
  "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 47387,
      "uncompressedSize": 76483423,
      "compressedSize": 4342748
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
  }]
},
"data": [
  ["customer1", 1234 A Avenue", "98765", "2021-01-20
  12:34:56.03459878"],
  ["customer2", 987 B Street", "98765", "2020-05-31
  01:15:43.765432134"],
  ["customer3", 8777 C Blvd", "98765", "2019-07-01
  23:12:55.123467865"],
  ["customer4", 64646 D Circle", "98765", "2021-08-03
  13:43:23.0"]
]
}
    Copy

  • Neste exemplo:

    • O primeiro objeto no campo partitionInfo descreve a partição de dados no campo de dados desta resposta.

    • O segundo objeto descreve a segunda partição de dados, que contém 47.387 linhas e que você pode recuperar enviando a solicitação GET /api/statements/<handle>?partition=1.

    • O terceiro objeto descreve a terceira partição de dados, que contém 47.386 linhas e que você pode recuperar enviando a solicitação GET /api/statements/<handle>?partition=2.

  • As partições adicionais são retornadas em formato compactado. Na resposta de uma solicitação GET /api/statements/<handle>?partition=<número_da_partição>, o corpo contém dados JSON em formato compactado (usando gzip).

    A resposta inclui a codificação de conteúdo do cabeçalho HTTP: gzip, que indica que o corpo da resposta está compactado.

    Essas respostas não contêm nenhum metadado. Os metadados para todas as partições são fornecidos na primeira partição descompactada.

  • Os campos obsoletos page, pageSize e numPages não estão mais incluídos no objeto resultSetMetaData no corpo da resposta.

    Com a nova funcionalidade, a API SQL não retorna mais dados em páginas. Em vez disso, a API SQL retorna dados em partições, e você usa o campo partitionInfo no objeto resultSetMetaData para determinar o número de partições e o número de linhas em cada partição.

  • Os números das linhas não estão mais inclusos no conjunto de resultados.

    Para incluir números de linha na resposta, chame a função de janela SEQUENCE ou ROW_NUMBER em sua consulta para gerar os números de linha.

  • Os valores booleanos agora são retornados como true ou false, em vez de 1 ou 0.

Linguagem: Português