API SQL de Snowflake : changements apportés au processus de soumission des instructions SQL

Avec cette version, l’API SQL Snowflake introduit des changements destinés à améliorer l’efficacité du traitement de l’API SQL.

Dans le cadre de ces changements, certaines fonctionnalités sont devenus obsolètes, comme indiqué dans cet article :

Activation de la nouvelle fonctionnalité API SQL

Pour activer la nouvelle fonctionnalité API SQL pour une requête donnée, définissez le champ format de resultSetMetaData sur jsonv2 comme indiqué dans l’exemple suivant :

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

Pour utiliser la fonctionnalité obsolète pour le traitement des résultats, omettez le champ resultSetMetaData ou attribuez au champ format sur json.

  • Remarque : à l’avenir, les API SQL utiliseront cette nouvelle fonctionnalité par défaut. Lorsque l’API SQL sera publiée en disponibilité générale (GA), la fonctionnalité obsolète ne sera plus prise en charge.

Fonctionnalités modifiées et obsolètes

L’API SQL Snowflake ne renvoie plus de données dans des pages de taille cohérente. Au lieu de cela, l’API SQL renvoie des partitions, qui sont des morceaux physiques individuels de données. La taille de chaque partition est variable et déterminée automatiquement par Snowflake au moment de l’exécution.

Avec ces changements :

  • Vous ne pouvez plus spécifier le paramètre annulable <> dans une requête GET. Il ne peut être spécifié que dans une requête POST pour soumettre une instruction SQL à l’exécution.

    Par exemple :

    POST /api/statements?nullable=false

  • Le paramètre pageSize est obsolète. Snowflake renvoie une partition de données dans chaque réponse et Snowflake détermine la taille de la partition qui est renvoyée. La taille d’une partition est variable et est basée sur la quantité de données retournées par Snowflake pour une requête SQL particulière.

  • Le paramètre page est remplacé par le paramètre partition. Plutôt que d’utiliser le paramètre page pour spécifier la prochaine page de données à renvoyer, utilisez le paramètre de partition pour spécifier la prochaine partition de données à renvoyer.

    Après avoir reçu la réponse contenant la première partition de données, vous pouvez obtenir le reste des partitions en soumettant des requêtes avec partition=<numéro_partition>, où <numéro_partition> identifie la partition de données à retourner. Le numéro de partition 0 identifie la première partition de données, qui est retournée dans la requête initiale.

    Par exemple, après avoir reçu la première partition de données, vous pouvez obtenir la deuxième partition de données en soumettant une requête avec le paramètre de partition défini sur 1 :

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

  • Lorsque vous soumettez une demande d’exécution d’une requête, la réponse comprend des métadonnées qui décrivent la manière dont les données sont partitionnées entre les réponses ainsi que la première partition des données.

    Le corps de cette réponse comprend un champ partitionInfo. Ce champ contient un tableau d’objets, dont chacun décrit une partition de données. Ce premier objet décrit la partition de données retournées dans cette réponse. Le reste des objets décrit les partitions supplémentaires que vous pouvez récupérer en soumettant des requêtes ultérieures avec partition=<numéro_partition>.

    Chaque objet du tableau indique le nombre de lignes et la taille d’une partition. Votre application peut utiliser ces métadonnées de partition pour déterminer comment traiter les partitions renvoyées pour les requêtes suivantes.

    L’exemple suivant montre une partie de la réponse :

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

  • Dans cet exemple :

    • Le premier objet du champ partitionInfo décrit la partition de données du champ de données de cette réponse.

    • Le deuxième objet décrit la deuxième partition de données, qui contient 47 387 lignes et que vous pouvez récupérer en envoyant la requête GET /api/statements/<handle>?partition=1.

    • Le troisième objet décrit la troisième partition de données, qui contient 47 386 lignes et que vous pouvez récupérer en envoyant la requête GET /api/statements/<handle>?partition=2.

  • Les partitions supplémentaires sont renvoyées dans un format compressé. Dans la réponse à une requête GET /api/statements/<traiter>?partition=<numéro_partition> , le corps contient des données JSON sous forme compressée (à l’aide de gzip).

    La réponse comprend l’en-tête HTTP Content-Encoding: gzip, qui indique que le corps de la réponse est compressé.

    Ces réponses ne contiennent pas de métadonnées. Les métadonnées de toutes les partitions sont fournies dans la première partition, non compressée.

  • Les champs page, pageSize, et numPages obsolètes ne sont plus inclus dans l’objet resultSetMetaData du corps de la réponse.

    Avec la nouvelle fonctionnalité, l’API SQL ne renvoie plus les données dans les pages. Au lieu de cela, l’API SQL renvoie des données dans des partitions et vous utilisez le champ partitionInfo de l’objet resultSetMetaData pour déterminer le nombre de partitions et le nombre de lignes dans chaque partition.

  • Les numéros de lignes ne sont plus inclus dans le jeu de résultats.

    Pour inclure les numéros de ligne dans la réponse, appelez la fonction de fenêtre SEQUENCE ou ROW_NUMBER dans votre requête pour générer les numéros de ligne.

  • Les valeurs booléennes sont désormais renvoyées sous forme de vrai ou de faux, plutôt que sous forme de 1 ou de 0.

Langage: Français