Traitement des réponses

Cette rubrique explique comment traiter une réponse de l’API SQL.

Dans ce chapitre :

Compréhension du flux d’exécution

Par défaut, Snowflake exécute l’instruction de manière synchrone et renvoie l’un des codes de réponse, présentés dans l’organigramme ci-dessous :

Organigramme pour la soumission d'une instruction pour exécution

Comme le montre l’organigramme ci-dessus :

  • Si vous avez soumis une seule instruction qui a été exécutée avec succès, Snowflake renvoie le code de réponse HTTP 200 et les lignes des résultats dans un objet ResultSet.

    Utilisez l’objet ResultSet pour récupérer les résultats.

  • Si vous avez soumis plusieurs instructions dans une seule requête et que la requête a été traitée avec succès, Snowflake renvoie le code de réponse HTTP 200 et un objet ResultSet.

    L’objet ResultSet ne contient aucune ligne des résultats. Au lieu de cela, le champ data contient simplement le message « Plusieurs instructions exécutées avec succès ».

    Pour récupérer les données, vous devez récupérer les handles des instructions individuelles dans la requête à partir du champ statementHandles. Pour chaque handle d’instruction, envoyez une requête pour vérifier le statut de l’exécution de l’instruction. Voir Vérification du statut de l’exécution de l’instruction et récupération des données.

    Pour avoir plus d’informations sur comment gérer une réponse pour une requête qui spécifie plusieurs instructions SQL, voir Obtention des résultats pour chaque instruction SQL dans la requête.

  • Si l’exécution de l’instruction prend plus de 45 secondes ou si vous avez spécifié que l’instruction devait être exécutée de manière asynchrone, Snowflake renvoie le code de réponse HTTP 202 avec un objet QueryStatus.

    Vous pouvez envoyer une requête au point de terminaison spécifié par le champ statementStatusUrl dans l’objet QueryStatus pour vérifier le statut de l’exécution de l’instruction. Voir Vérification du statut de l’exécution de l’instruction et récupération des données.

    Si vous souhaitez annuler l’exécution de l’instruction, vous pouvez envoyer une demande au /api/v2/statements/statementHandle/cancel à l’aide de l’handle d’instruction du champ statementHandle dans l’objet QueryStatus. Voir Annulation de l’exécution d’une instruction SQL.

Vérification du statut de l’exécution de l’instruction et récupération des données

Parfois, il est nécessaire d’envoyer une requête pour vérifier le statut de l’exécution d’une instruction :

  • Lorsque vous soumettez une instruction SQL pour exécution, Snowflake renvoie un code de réponse 202 si l’exécution de l’instruction n’est pas encore terminée ou si vous avez soumis une requête asynchrone.

    Pour voir si l’exécution de l’instruction est terminée, vous devez envoyer une requête pour vérifier le statut de l’instruction.

  • Si vous avez soumis plusieurs instructions SQL dans une seule requête, vous obtenez les résultats de chaque instruction individuelle en envoyant une requête visant à vérifier le statut de l’instruction.

Dans les deux cas, vous envoyez une requête GET vers le point de terminaison /api/v2/statements/ et joignez l’handle d’instruction à la fin du chemin d’URL comme paramètre de chemin. Voir GET /api/v2/statements/{statementHandle} pour plus de détails.

GET /api/v2/statements/{statementHandle}
Copy

{statementHandle} est le handle de l’instruction que vous voulez vérifier. Pour obtenir l’handle d’instruction :

  • Si vous recevez une réponse avec un code 202, le corps de la réponse inclut un objet QueryStatus. Vous pouvez obtenir l’handle d’instruction à partir du champ statementHandle de cet objet.

    Notez que vous pouvez aussi obtenir l’URL complète de la requête à partir du champ statementStatusUrl de cet objet.

    {
      "code": "090001",
      "sqlState": "00000",
      "message": "successfully executed",
      "statementHandle": "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
      "statementStatusUrl": "/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
    }
    
    Copy
  • Si vous avez soumis une requête contenant plusieurs instructions SQL, le corps de la réponse inclut un objet ResultSet qui contient un champ statementHandles. Vous pouvez obtenir les handles des instructions individuelles à partir de ce champ.

    {
      ...
      "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
      ...
    }
    
    Copy

Par exemple, la commande curl suivante vérifie le statut de l’instruction avec le handle e4ce975e-f7ff-4b5e-b15e-bf25f59371ae :

curl -i -X GET \
    -H "Authorization: Bearer <jwt>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    "https://<account_identifier>.snowflakecomputing.com/api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
Copy

où :

Lorsque vous envoyez une requête pour vérifier le statut, Snowflake renvoie l’un des codes de réponse, présentés dans l’organigramme ci-dessous :

Organigramme permettant de vérifier le statut d'une instruction soumise à exécution

Comme le montre l’organigramme ci-dessus :

Obtention des résultats à partir de la réponse

Note

La version 5.40 de Snowflake introduit des changements dans la façon dont les données renvoyées par l’API SQL de Snowflake sont traitées, entre autres changements.

Cette section décrit comment obtenir les résultats d’une réponse en utilisant les nouvelles fonctionnalités de l’API SQL de Snowflake. Pour plus d’informations sur l’utilisation de l’ancien comportement obsolète, voir Fonctionnalité obsolète.

Si vous soumettez une instruction SQL pour exécution ou vérifiez le statut d’exécution de l’instruction, Snowflake renvoie un objet ResultSet dans le corps de la réponse si l’instruction a été exécutée avec succès.

L’API Snowflake renvoie les données dans des partitions. Snowflake détermine le nombre de partitions et la taille de chaque partition qui est retourné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.

Lorsque vous soumettez une demande, 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=partition_number.

Chaque objet du tableau spécifie 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 :

{
  "code": "090001",
  "statementHandle": "536fad38-b564-4dc5-9892-a4543504df6c",
  "sqlState": "00000",
  "message": "successfully executed",
  "createdOn": 1597090533987,
  "statementStatusUrl": "/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c",
  "resultSetMetaData" : {
    "numRows" : 50000,
    "format" : "jsonv2",
    "partitionInfo" : [ {
      "rowCount" : 12288,
      "uncompressedSize" : 124067,
      "compressedSize" : 29591
    }, {
      "rowCount" : 37712,
      "uncompressedSize" : 414841,
      "compressedSize" : 84469
    }],
  },
  "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

Obtention des métadonnées sur les résultats

Dans l’objet ResultSet renvoyé dans la réponse, le champ resultSetMetaData contient un objet ResultSet_resultSetMetaData qui décrit le jeu de résultats (par exemple, le format des résultats, le nombre de partitions renvoyées, etc.)

Obtention des métadonnées sur les colonnes retournées par l’objet ResultSet

Le champ resultSetMetaData contient des informations sur les colonnes retournées dans l’objet ResultSet.

Dans l’exemple ci-dessous, le champ rowType contient un tableau d’objets ResultSet_resultSetMetaData_rowType. Chaque objet décrit une colonne dans les résultats. Le champ type spécifie le type de données Snowflake de la colonne.

{
 "resultSetMetaData": {
  "numRows": 1300,
  "rowType": [
   {
    "name":"ROWNUM",
    "type":"FIXED",
    "length":0,
    "precision":38,
    "scale":0,
    "nullable":false
   }, {
    "name":"ACCOUNT_NAME",
    "type":"TEXT",
    "length":1024,
    "precision":0,
    "scale":0,
    "nullable":false
   }, {
    "name":"ADDRESS",
    "type":"TEXT",
    "length":16777216,
    "precision":0,
    "scale":0,
    "nullable":true
   }, {
    "name":"ZIP",
    "type":"TEXT",
    "length":100,
    "precision":0,
    "scale":0,
    "nullable":true
   }, {
    "name":"CREATED_ON",
    "type":"TIMESTAMP_NTZ",
    "length":0,
    "precision":0,
    "scale":3,
    "nullable":false
   }],
  "partitionInfo": [{
    ... // Partition metadata
  }]
 }
}
Copy

Obtention des métadonnées sur les partitions retournées par l’objet ResultSet

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 champ resultSetMetaData contient 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=partition_number.

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

  {
    "resultSetMetaData": {
    "numRows: 103477,
    "format": "jsonv2"
    "rowType": {
      ... // Column metadata.
    },
    "partitionInfo": [{
        "rowCount": 12344,
        "uncompressedSize": 14384873,
      },{
        "rowCount": 47387,
        "uncompressedSize": 76483423,
        "compressedSize": 4342748
      },{
        "rowCount": 43746,
        "uncompressedSize": 43748274,
        "compressedSize": 746323
    }]
  },
  ...
}
Copy

Dans cet exemple, le premier objet du champ partitionInfo décrit la partition des données dans le 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/v2/statements/handle?partition=1.

Le troisième objet décrit la troisième partition de données, qui contient 43 746 lignes et que vous pouvez récupérer en envoyant la requête

GET /api/v2/statements/handle?partition=2.

Obtention des données à partir des résultats

Dans l’objet ResultSet de la réponse, les résultats se trouvent dans le champ data. Le champ data contient un tableau d’un tableau de chaînes au format JSON. Par exemple :

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

Chaque tableau dans le tableau contient les données d’une ligne. Les éléments de chaque tableau représentent les données d’une ligne.

Les données du jeu de résultats sont codées en JSON, ce qui signifie que toutes les données sont exprimées sous forme de chaînes, quel que soit le type de données Snowflake de la colonne.

Par exemple, la valeur 1.0 d’une colonne NUMBER est renvoyée sous la forme de la chaîne "1.0". Autre exemple, les horodatages sont renvoyés sous la forme du nombre de nanosecondes depuis l’epoch. Par exemple, l’horodatage du jeudi 28 janvier, 2021 10:09:37.123456789 PM est renvoyé sous la forme "1611871777123456789".

Vous êtes responsable de la conversion des chaînes dans les types de données appropriés.

Snowflake renvoie les valeurs sous forme de chaînes dans les formats suivants (si aucun paramètre de format de sortie n’est spécifié dans la requête d’instruction de soumission POST) selon le type de données Snowflake :

INT / NUMBER:

Nombre décimal dans une chaîne.

FLOAT:

Entier ou flottant dans une chaîne.

VARCHAR:

Chaîne.

BINARY:

Nombre hexadécimal dans une chaîne.

BOOLEAN:

« false » ou « true » dans une chaîne.

DATE:

Valeur entière (dans une chaîne) du nombre de jours depuis l’epoch (par exemple 18262).

TIME, TIMESTAMP_LTZ, TIMESTAMP_NTZ:

Valeur flottante (avec 9 décimales) du nombre de secondes écoulées depuis l’epoch (par exemple, 82919.000000000).

TIMESTAMP_TZ:

Valeur flottante (avec 9 décimales) du nombre de secondes écoulées depuis l’epoch, suivie d’un espace et du décalage de fuseau horaire en minutes (par exemple, 1616173619000000000 960).

Récupération de partitions supplémentaires

L’API SQL Snowflake renvoie les données dans des partitions. La première partition est retournée au format JSON et contient des métadonnées sur toutes les partitions retournées pour une requête spécifique. Votre application peut utiliser ces métadonnées de partition pour déterminer comment traiter les partitions renvoyées pour les requêtes suivantes.

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=partition_number, où partition_number 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/v2/statements/<handle>?partition=1
Copy

Dans la réponse à une requête GET /api/v2/statements/<handle>?partition=partition_number 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.

Renvoi des valeurs SQL NULL en tant que chaînes

Par défaut, les valeurs SQL NULL sont retournées en tant que valeur null :

"data" : [ [ null ], ... ]
Copy

Si vous souhaitez que ces valeurs soient plutôt renvoyées sous la forme d’une chaîne "null" , définissez le paramètre de requête nullable sur false dans la requête POST pour soumettre l’instruction SQL à l’exécution. Par exemple :

POST /api/v2/statements?nullable=false
Copy

Cela renvoie des valeurs SQL NULL en tant que "null".

"data" : [ [ "null" ], ... ]
Copy

Note

Vous ne pouvez pas spécifier le paramètre nullable dans les requêtes GET pour vérifier le statut de l’instruction.

Formatage de la sortie des résultats de la requête

L’API SQL Snowflake prend en charge les paramètres de formatage de la sortie (par exemple, Paramètres de session pour les dates, heures et horodatages).

Par exemple, par défaut, une valeur DATE comme 2019-03-27 est retournée sous la forme « 17982 » (2019-03-27 correspond à 17982 jours après l’époque). Si vous spécifiez que DATE_OUTPUT_FORMAT doit être « MM/DD/YY » dans la requête :

{
  "statement": "select date_column from mytable",
  "resultSetMetaData": {
    "format": "jsonv2",
  },
  "parameters": {
    "DATE_OUTPUT_FORMAT": "MM/DD/YYYY"
  }
  ...
}
Copy

La valeur DATE est renvoyée sous la forme « 03/27/2019 ».

Dans le champ parameters du corps de la requête, vous pouvez définir les paramètres suivants qui déterminent le format de sortie des données :

  • BINARY_OUTPUT_FORMAT

  • DATE_OUTPUT_FORMAT

  • TIME_OUTPUT_FORMAT

  • TIMESTAMP_LTZ_OUTPUT_FORMAT

  • TIMESTAMP_NTZ_OUTPUT_FORMAT

  • TIMESTAMP_TZ_OUTPUT_FORMAT

  • TIMESTAMP_OUTPUT_FORMAT

  • TIMEZONE

Note

Snowflake ignore les paramètres de niveau compte et de niveau utilisateur pour ces paramètres. Afin de modifier le format des valeurs dans les résultats de l’API SQL, vous devez définir ces paramètres de sortie dans le corps de la requête.

Inclusion des numéros de ligne dans l’objet resultSet

Les numéros de lignes ne sont pas retournés 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.