Traitement des réponses¶

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 :

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}

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

où :

• jwt est le JWT que vous avez généré pour l’authentification.

• myApplicationName est un exemple d’identificateur pour votre application.

• account_identifier est votre identificateur de compte.

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 :

Comme le montre l’organigramme ci-dessus :

• Si l’instruction s’est 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 l’exécution de l’instruction n’est pas terminée, Snowflake renvoie le code de réponse HTTP 202 avec un objet QueryStatus.

  Utilisez cet objet pour vérifier le statut d’exécution de l’instruction.

• Si une erreur s’est produite lors de l’exécution de l’instruction, Snowflake renvoie le code de réponse HTTP 422 avec un objet QueryFailureStatus.

  Vous pouvez obtenir des détails sur l’erreur à partir de cet objet.

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

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

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.)

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

  {
    "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
    }]
  },
  ...
}

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"]
  ],
  ...
}

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

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 ], ... ]

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

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

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

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

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

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.