Référence de l’API SQL Snowflake

Cette rubrique documente les opérations, les requêtes et les réponses pour l’API SQL.

Dans ce chapitre :

Opérations

Soumettre une instruction SQL pour exécution

Pour soumettre une ou plusieurs instructions SQL à l’exécution, envoyez une requête POST à /api/statements. Vous pouvez spécifier que l’instruction doit être exécutée de manière asynchrone, et vous pouvez spécifier le nombre de lignes à retourner par page.

Syntaxe de la requête

POST /api/statements
(request body)

Paramètres de requête

Paramètre

Description

requestId

(Facultatif) ID unique (un UUID) de la requête API. Voir Attribution d’un ID de requête unique pour la resoumission des requêtes.

async

(Facultatif) Définissez-le sur true pour exécuter l’instruction de manière asynchrone et renvoyer le handle de l’instruction.

Si le paramètre n’est pas spécifié ou a la valeur false, une instruction est exécutée et les résultats sont renvoyés si l’exécution se termine en 45 secondes. Si l’exécution de l’instruction prend plus de temps pour finir, le handle de l’instruction est retourné.

Notez que si l’exécution de l’instruction se termine, les résultats comprennent au maximum le nombre de lignes spécifié par le paramètre pageSize. Si le champ numRows de ResultSet_resultSetMetaData indique qu’il existe des lignes de résultats supplémentaires, voir Récupération de pages supplémentaires de résultats.

pageSize

(Facultatif) Nombre de lignes à renvoyer par page. La taille de la page peut varier entre le nombre minimum (10) et le nombre maximum (10 000) de lignes par page. Par défaut, le nombre de lignes retournées varie en fonction de l’exécution de l’instruction.

Remarque : si la requête renvoie un grand nombre de lignes, définissez ce paramètre. Sinon, le nombre de lignes peut dépasser le nombre de lignes par défaut dans une page.

nullable

(Facultatif) Définissez-le sur false pour retourner une valeur NULL SQL sous la forme de chaîne "null", plutôt que sous la forme de valeur null.

Par défaut, les valeurs SQL NULL sont retournées comme la valeur null :

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

En donnant la valeur false à ce paramètre de requête (par exemple, /api/statements?nullable=false renvoie une valeur SQL NULL sous la forme de chaîne "null" :

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

En-têtes de requête

La requête doit inclure les en-têtes énumérés dans En-têtes de requête pour toutes les opérations.

Corps de la requête

(Obligatoire) Le corps de la requête doit contenir l’objet spécifié dans Corps de la requête POST dans /api/statements/.

Réponse

Cette opération peut renvoyer les codes de réponse énumérés ci-dessous.

Code

Description

200

L’instruction a été exécutée avec succès.

Pour ce code de réponse, la réponse peut avoir les en-têtes suivants :

Si une seule instruction SQL a été soumise dans la requête, le corps de la réponse contient un objet ResultSet contenant les données demandées.

Note

Si le champ code de la réponse est défini sur 391908, le jeu de résultats est trop grand, . et la réponse ne comprend pas le jeu de résultats.

Voir Vérification de la taille de la page du jeu de résultats par rapport à la limite autorisée pour plus de détails.

Voici un exemple de réponse pour une seule instruction SQL dont les résultats tiennent sur une seule page, où {handle} est le handle de l’instruction et {id1}, {id2} et {id3} sont des IDs de requêtes générés de manière unique :

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:06:24 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "pageSize" : 10,
    "numPages" : 1,
    "numRows" : 4,
    "format" : "json",
    "rowType" : [ {
      "name" : "COLUMN1",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 4,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16,
      "collation" : null
    }, {
      "name" : "COLUMN2",
      "database" : "",
      "schema" : "",
      "table" : "\"VALUES\"",
      "scale" : 0,
      "precision" : 1,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    } ]
  },
  "data" : [ [ "0", "test", "2" ], [ "1", "test", "3" ], [ "2", "test", "4" ], [ "3", "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}&pageSize=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151584132
}

Voici un exemple de réponse pour une seule instruction SQL dont les résultats doivent être renvoyés dans plusieurs pages, où {handle} est le handle de l’instruction et {id1}, {id2}, {id3} et {id4} sont des IDs de requêtes générés de manière unique :

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:08:15 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=1&pageSize=-1>; rel="next",
  </api/statements/{handle}?requestId={id3}&page=7&pageSize=-1>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "numPages" : 8,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "0", "0", "QqKow2xzdJ....." ],.... [ "98", "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id4}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

Si plusieurs instructions SQL ont été soumises dans la requête, le corps de la réponse contient un objet ResultSet avec des détails sur le statut d’exécution des multiples instructions.

Dans ce cas, la réponse ne contient pas les données demandées. Au lieu de cela, le champ data contient simplement le message « Multiple statements executed successfully » (Les instructions multiples ont été exécutées avec succès).

La réponse contient le champ statementHandles, qui est un tableau de handles d’instructions que vous pouvez utiliser pour récupérer les résultats des instructions individuelles.

Voici un exemple de réponse pour une requête qui spécifie plusieurs instructions SQL, où :

  • {handle} est le handle de l’instruction de l’ensemble des instructions.

  • {handle1}, {handle2} et {handle3 sont les handles des différentes instructions SQL de la requête.

  • {id1}, {id2}, et {id3} sont des IDs de requêtes générés de manière unique :

HTTP/1.1 200 OK
Date: Mon, 31 May 2021 22:50:31 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=-1>; rel="last"

{
  "resultSetMetaData" : {
  "page" : 0,
  "numPages" : 1,
  "numRows" : 1,
  "format" : "json",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ]
  },
  "data" : [ [ "0", "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1622501430333
}

202

L’exécution de l’instruction est toujours en cours. Utilisez GET /api/statements/statementHandle} pour vérifier le statut d’exécution de l’instruction.

Le corps de la réponse contient un objet QueryStatus avec des détails sur le statut de l’exécution de l’instruction.

Voici un exemple de réponse :

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 18:12:37 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c06a4-0000-df4f-0000-00100006589e",
  "statementStatusUrl" : "/api/statements/019c06a4-0000-df4f-0000-00100006589e"
}

408

L’exécution de l’instruction a dépassé le délai d’attente. L’exécution de l’instruction a été annulée.

Le corps de la réponse contient un objet QueryStatus avec des détails sur l’annulation de l’exécution de l’instruction.

422

Une erreur s’est produite lors de l’exécution de l’instruction. Vérifiez le code d’erreur et le message d’erreur pour plus de détails.

Le corps de la réponse contient un objet QueryFailureStatus avec des détails sur l’erreur.

Voici un exemple de réponse :

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 20:24:11 GMT
Content-Type: application/json
{
  "code" : "000904",
  "message" : "SQL compilation error: error line 1 at position 7\ninvalid identifier 'AFAF'",
  "sqlState" : "42000",
  "statementHandle" : "019c0728-0000-df4f-0000-00100006606e"
}

Pour les autres codes de réponse renvoyés par cette opération, voir Codes de réponse pour toutes les opérations.

Vérifier le statut d’exécution d’une instruction et obtenir les résultats

Pour vérifier le statut d’exécution d’une instruction, envoyez une requête GET à /api/statements/{statementHandle}. Si l’instruction a été exécutée avec succès, le corps de la réponse comprend un objet ResultSet contenant les données demandées.

Syntaxe de la requête

GET /api/statements/{statementHandle}

Paramètres de chemin

Paramètre

Description

statementHandle

(Obligatoire) Le handle de l’instruction que vous voulez vérifier. Vous pouvez obtenir cet handle à partir de l’objet QueryStatus renvoyé dans la réponse à la requête d’exécution de l’instruction.

Paramètres de requête

requestId

(Facultatif) ID unique (un UUID) de la requête API. Voir Attribution d’un ID de requête unique pour la resoumission des requêtes.

page

(Facultatif) Numéro qui identifie la page de résultats à retourner. Ce nombre peut aller de 0 au nombre total de pages moins 1.

pageSize

(Facultatif) Nombre de lignes à renvoyer par page. La taille de la page peut varier entre le nombre minimum (10) et le nombre maximum (10 000) de lignes par page. Par défaut, le nombre de lignes retournées varie en fonction de l’exécution de l’instruction.

En-têtes de requête

La requête doit inclure les en-têtes énumérés dans En-têtes de requête pour toutes les opérations.

Réponse

Cette opération peut renvoyer les codes de réponse énumérés ci-dessous.

Code

Description

200

L’instruction a été exécutée avec succès.

Pour ce code de réponse, la réponse peut avoir les en-têtes suivants :

Le corps de la réponse contient un objet ResultSet contenant les données demandées.

Voici un exemple de réponse, où {handle} est le handle de l’instruction et {id1}, {id2}, {id3}, {id4} et {id5} sont des IDs de requêtes générés de manière unique :

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 20:25:46 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="prev",
  </api/statements/{handle}?requestId={id3}&page=2&pageSize=10>; rel="next",
  </api/statements/{handle}?requestId={id4}&page=999&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 1,
    "pageSize" : 10,
    "numPages" : 1000,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "10", "10", "lJPPMTSwps......" ], ... [ "19", "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id5}&pageSize=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

202

L’exécution de l’instruction est toujours en cours. Répétez la requête pour vérifier le statut de l’exécution de l’instruction.

Le corps de la réponse contient un objet QueryStatus avec des détails sur le statut de l’exécution de l’instruction.

Voici un exemple de réponse :

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 22:31:33 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c07a7-0000-df4f-0000-001000067872",
  "statementStatusUrl" : "/api/statements/019c07a7-0000-df4f-0000-001000067872"
}

422

Une erreur s’est produite lors de l’exécution de l’instruction. Vérifiez le code d’erreur et le message d’erreur pour plus de détails.

Le corps de la réponse contient un objet QueryFailureStatus avec des détails sur l’erreur.

Pour les autres codes de réponse renvoyés par cette opération, voir Codes de réponse pour toutes les opérations.

Annuler l’exécution d’une instruction

Pour annuler l’exécution d’une instruction, envoyez une requête POST à /api/statements/{statementHandle}/cancel.

Syntaxe de la requête

POST /api/statements/{statementHandle}/cancel

Paramètres de chemin

Paramètre

Description

statementHandle

(Obligatoire) Le handle de l’instruction que vous voulez vérifier. Vous pouvez obtenir cet handle à partir de l’objet QueryStatus renvoyé dans la réponse à la requête d’exécution de l’instruction.

Paramètres de requête

Paramètre

Description

requestId

(Facultatif) ID unique (un UUID) de la requête API. Voir Attribution d’un ID de requête unique pour la resoumission des requêtes.

En-têtes de requête

La requête doit inclure les en-têtes énumérés dans En-têtes de requête pour toutes les opérations.

Réponse

Cette opération peut renvoyer les codes de réponse énumérés ci-dessous.

Code

Description

200

L’exécution de l’instruction a été annulée avec succès.

Le corps de la réponse contient un objet CancelStatus qui contient des informations sur l’annulation de l’instruction.

Voici un exemple de réponse :

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 22:52:15 GMT
Content-Type: application/json
Content-Length: 230
{
  "code" : "000604",
  "sqlState" : "57014",
  "message" : "SQL execution canceled",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e",
  "statementStatusUrl" : "/api/statements/019c07bc-0000-df4f-0000-001000067c3e"
}

422

Une erreur s’est produite lors de l’exécution de l’instruction. Vérifiez le code d’erreur et le message d’erreur pour plus de détails.

Le corps de la réponse contient un objet QueryFailureStatus avec des détails sur l’erreur.

Voici un exemple de réponse :

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 22:52:49 GMT
Content-Type: application/json
Content-Length: 183
{
  "code" : "000709",
  "message" : "Statement 019c07bc-0000-df4f-0000-001000067c3e not found",
  "sqlState" : "02000",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e"
}

Pour les autres codes de réponse renvoyés par cette opération, voir Codes de réponse pour toutes les opérations.

En-têtes de requête pour toutes les opérations

Les en-têtes de requête suivants s’appliquent à toutes les opérations :

En-tête

Obligatoire ou facultatif ?

Description

Authorization

Obligatoire

Donnez-lui la valeur Bearer, suivie du jeton utilisé pour s’authentifier auprès de Snowflake.

Par exemple :

Authorization: Bearer jeton

Voir Authentification auprès du serveur.

Accept

Obligatoire

Définissez la liste des types de médias (types MIME) qui sont acceptables dans le corps de la réponse. Incluez le type application/json (ou, si tous les types sont acceptables, donnez-lui la valeur */*).

Content-Type

Obligatoire

Définissez ce paramètre sur le type de média (type MIME) du corps de la requête. Définissez ceci sur application/json.

User-Agent

Obligatoire

Indiquez le nom et la version de votre application (par exemple, applicationName/applicationVersion). Vous devez utiliser une valeur conforme à la norme RFC 7231.

X-Snowflake-Authorization-Token-Type

Obligatoire pour l’authentification par paire de clés

Facultatif pour OAuth

Si vous utilisez l’authentification par paire de clés, cet en-tête est obligatoire. Vous devez donner à cet en-tête la valeur KEYPAIR_JWT.

Si vous utilisez OAuth pour l’authentification, cet en-tête est facultatif. (Si vous choisissez de définir cet en-tête, définissez-le sur OAUTH).

Types d’objets dans le corps de la requête

Corps de la requête POST dans /api/statements/

Le corps d’une requête POST vers le point de terminaison /api/statements/ est un objet JSON que vous utilisez pour spécifier l’instruction SQL à exécuter, le contexte de l’instruction et le format des données dans le jeu de résultats. Vous utilisez cet objet dans le corps d’une requête pour exécuter une instruction.

Champs

Champ

Description

statement

(Facultatif) Instruction SQL à exécuter. Voir Introduction pour connaître les listes d’instructions prises en charge et non prises en charge.

Type : chaîne

timeout

(Facultatif) Délai en secondes pour l’exécution de l’instruction. Si l’exécution d’une instruction prend plus de temps que le délai spécifié, l’exécution est automatiquement annulée. Pour définir le délai d’attente à la valeur maximale (604800 secondes), définissez le délai d’attente sur 0. Si ce champ n’est pas défini, le délai d’attente spécifié par le paramètre STATEMENT_TIMEOUT_IN_SECONDS est utilisé.

Type : nombre entier signé de 64 bits

Exemple : 10

resultSetMetaData

(Facultatif) Métadonnées sur le jeu de résultats à renvoyer.

Type : objet (instructions_resultSetMetaData)

database

(Facultatif) Base de données dans laquelle l’instruction doit être exécutée. La valeur de ce champ est sensible à la casse.

Type : chaîne

Exemple : TESTDB

schema

(Facultatif) Schéma dans lequel l’instruction doit être exécutée. La valeur de ce champ est sensible à la casse.

Type : chaîne

Exemple : TESTSCHEMA

warehouse

(Facultatif) Entrepôt à utiliser lors de l’exécution de l’instruction. La valeur de ce champ est sensible à la casse.

Type : chaîne

Exemple : TESTWH

role

(Facultatif) Rôle à utiliser lors de l’exécution de l’instruction. La valeur de ce champ est sensible à la casse.

Type : chaîne

Exemple : TESTROLE

bindings

(Facultatif) Valeurs des variables bind dans l’instruction SQL. Lors de l’exécution de l’instruction, Snowflake remplace les caractères de remplacement (? et :name) dans l’instruction par ces valeurs spécifiées.

Notez que le format de ce champ peut changer pour la version GA de l’API SQL.

Type : objet

Exemple :

{"1":{"type":"FIXED","value":"123"},"2":{"type":"TEXT","value":"teststring"}}

parameters

(Facultatif) Paramètres de session que vous souhaitez définir pour cette requête.

Type : objet (statements_parameters)

Exemple

Voici un exemple de l’objet du corps :

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

statements_parameters

statements_parameters est un objet JSON que vous utilisez pour spécifier les paramètres de session que vous souhaitez définir pour cette requête. Cet objet doit se trouver dans le champ parameters du corps de la requête POST adressée au point de terminaison /api/statements.

Champs

Champ

Description

timezone

(Facultatif) Fuseau horaire à utiliser lors de l’exécution de l’instruction. Pour plus de détails, voir la documentation sur le paramètre TIMEZONE.

Type : chaîne

Exemple : america/los_angeles

query_tag

(Facultatif) Balise de requête que vous voulez associer à l’instruction SQL. Pour plus de détails, voir la documentation sur le paramètre QUERY_TAG.

Type : chaîne

Exemple : tag-1234

instructions_resultSetMetaData

statements_resultSetMetaData est un objet JSON que vous utilisez pour spécifier des métadonnées sur le jeu de résultats à renvoyer. Cet objet doit se trouver dans le champ resultSetMetaData du corps de la requête POST adressée au point de terminaison /api/statements.

Champs

Champ

Description

format

(Facultatif) Format des données dans le jeu de résultats. La seule valeur prise en charge est json.

Type : chaîne

Codes de réponse pour toutes les opérations

Cette section énumère les codes de réponse qui s’appliquent à toutes les opérations.

Code

Description

400

Mauvaise requête.

La charge utile de la requête n’est pas valide ou est mal formatée. Cela se produit si l’application n’a pas envoyé la bonne charge utile de la requête. Le corps de la réponse peut inclure le code d’erreur et le message indiquant la cause réelle. L’application doit reconstruire le corps de la requête pour une nouvelle tentative.

Voici un exemple de réponse :

HTTP/1.1 400 Bad Request
Date: Tue, 04 May 2021 22:54:21 GMT
Content-Type: application/json
{
  "code" : "390142",
  "message" : "Incoming request does not contain a valid payload."
}

401

Non autorisé.

La requête n’est pas autorisée. Cela se produit si le jeton d’accès joint n’est pas valide ou manquant. Le corps de la réponse peut inclure le code d’erreur et le message indiquant la cause réelle, par exemple, un jeton expiré ou non valide. L’application doit obtenir un nouveau jeton d’accès pour une nouvelle tentative.

Voir Authentification auprès du serveur.

Voici un exemple de réponse :

HTTP/1.1 401 Unauthorized
Date: Tue, 04 May 2021 20:17:57 GMT
Content-Type: application/json
{
  "code" : "390303",
  "message" : "Invalid OAuth access token. ...TTTTTTTT"
}

403

Interdit.

La requête est interdite. Cela se produit si la requête est faite même si l’API n’est pas activée.

404

Introuvable.

Le point de terminaison de la requête n’est pas valide. Cela se produit si le point de terminaison de l’API est incorrect. Par exemple, si l’application demande /api/hello, ce qui n’existe pas, le serveur renvoie ce code.

405

Méthode non autorisée.

La méthode de la requête ne correspond pas à l’API prise en charge. Cela se produit, par exemple, si l’application appelle l’API avec la méthode GET mais que le point de terminaison n’accepte que le POST. L’application doit utiliser une méthode prise en charge lors de l’envoi de la requête.

Voici un exemple de réponse :

HTTP/1.1 405 Method Not Allowed
Date: Tue, 04 May 2021 22:55:38 GMT
Content-Length: 0

415

L’en-tête de la requête Content-Type comprend un type de média non pris en charge.

L’API ne prend en charge que application/json. Si aucun Content-Type n’est spécifié, la charge utile de la requête sont interprétées comme du JSON, mais si un autre type de média est spécifié, cette erreur est renvoyée.

429

Limite dépassée.

Le nombre de requêtes a atteint la limite de débit. L’application doit réduire la fréquence des requêtes envoyées aux points de terminaison de l’API.

Voici un exemple de réponse :

HTTP/1.1 429 Too many requests
Content-Type: application/json
Content-Length: 69
{
  "code" : "390505",
  "message" : "Too many concurrent requests"
}

500

Erreur de serveur interne.

Le serveur a rencontré une erreur système irrécupérable. Le corps de la réponse peut inclure le code d’erreur et un message pour plus d’informations.

503

Service indisponible.

La requête n’a pas été traitée en raison d’un délai d’attente sur le serveur. L’application peut réessayer avec une interruption. Une interruption à gigue exponentielle est recommandée.

504

Délai d’expiration de la passerelle.

La requête n’a pas été traitée en raison d’un délai d’attente sur le serveur. L’application peut réessayer avec une interruption. Une interruption à gigue exponentielle est recommandée.

En-têtes de réponse pour toutes les opérations

Les réponses peuvent contenir les en-têtes suivants :

En-tête

Description

Link

Cet en-tête se trouve dans la réponse 200 pour une requête d’exécution de l’instruction et une requête de vérification de statut d’exécution d’une instruction.

Cet en-tête fournit des liens vers d’autres pages de résultats (par exemple, la première page, la dernière page, etc.). L’en-tête peut inclure plusieurs entrées URL avec différentes valeurs d’attribut rel qui spécifient la page à renvoyer (first, next, prev et last).

Par exemple :

Link: </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="last">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="next">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=0; rel="first">

Types d’objets dans le corps de la réponse

CancelStatus

CancelStatus est un objet JSON qui contient des informations sur l’annulation de l’exécution d’une instruction. Cet objet est renvoyé dans le corps de la réponse pour une requête d’annulation.

Champs

Champ

Description

code

Type : chaîne

sqlState

Type : chaîne

message

Exemple : successfully cancelled

Type : chaîne

statementHandle

Identificateur unique pour l’instruction en cours d’exécution.

Type : chaîne (un UUID)

Exemple : 536fad38-b564-4dc5-9892-a4543504df6c

statementStatusUrl

URL pour obtenir le statut de l’instruction et le jeu de résultats.

Type : chaîne (une URL)

Exemple : /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully canceled",
  "statementHandle" : "536fad38-b564-4dc5-9892-a4543504df6c",
  "statementStatusUrl" : "/api/statements/536fad38-b564-4dc5-9892-a4543504df6c"
}

QueryFailureStatus

QueryFailureStatus est un objet JSON qui contient des informations sur l’échec de l’exécution d’une instruction. Cet objet est renvoyé dans le corps de la réponse 422 pour une demande d’exécution de l’instruction.

Champs

Champ

Description

code

Type : chaîne

Exemple : 0

sqlState

Type : chaîne

message

Type : chaîne

Exemple : successfully executed

statementHandle

Identificateur unique pour l’instruction en cours d’exécution.

Type : chaîne (un UUID)

Exemple : 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

Horodatage qui précise le moment où l’exécution de l’instruction a commencé. L’horodatage est exprimé en millisecondes depuis l’epoch.

Type : nombre entier signé de 64 bits

Exemple : 1597090533987

statementStatusUrl

URL pour obtenir le statut de l’instruction et le jeu de résultats.

Type : chaîne (une URL)

Exemple : /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "002140",
  "sqlState" : "42601",
  "message" : "SQL compilation error",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}

QueryStatus

QueryStatus est un objet JSON qui contient des informations sur le statut de l’exécution d’une instruction. Cet objet est renvoyé dans ce qui suit :

Champs

Champ

Description

code

Type : chaîne

Exemple : 0

sqlState

Type : chaîne

message

Type : chaîne

Exemple : successfully executed

statementHandle

Identificateur unique pour l’instruction en cours d’exécution.

Type : chaîne (un UUID)

Exemple : 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

Horodatage qui précise le moment où l’exécution de l’instruction a commencé. L’horodatage est exprimé en millisecondes depuis l’epoch.

Type : nombre entier signé de 64 bits

Exemple : 1597090533987

statementStatusUrl

URL pour obtenir le statut de l’instruction et le jeu de résultats.

Type : chaîne (une URL)

Exemple : /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully executed",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}

ResultSet

ResultSet est un objet JSON qui contient les résultats de l’exécution d’une instruction. Cet objet est renvoyé dans le corps de la réponse 200 pour une requête d’exécution de l’instruction et une requête de vérification du statut d’exécution d’une instruction.

Champs

Champ

Description

code

Type : chaîne

Exemple : 0

sqlState

Type : chaîne

message

Type : chaîne

Exemple : successfully executed

statementHandle

Identificateur unique pour l’instruction en cours d’exécution.

Si plusieurs instructions ont été spécifiées dans la requête, cet handle correspond à l’ensemble de ces instructions. Pour les handles des différentes instructions de la requête, voir le champ statementHandles.

Type : chaîne (un UUID)

Exemple : 536fad38-b564-4dc5-9892-a4543504df6c

statementHandles

Tableau d’identificateurs uniques pour les instructions exécutées pour cette requête.

Type : tableau de chaînes (UUID)

Exemple : [ "019c9f9a-0502-f25e-0000-438300e0d046", "019c9f9a-0502-f25e-0000-438300e0d04a", "019c9f9a-0502-f25e-0000-438300e0d04e" ]

createdOn

Horodatage qui précise le moment où l’exécution de l’instruction a commencé. L’horodatage est exprimé en millisecondes depuis l’epoch.

Exemple : 1597090533987

statementStatusUrl

URL pour obtenir le statut de l’instruction et le jeu de résultats.

Type : chaîne (une URL)

Exemple : /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

resultSetMetaData

Métadonnées sur le jeu de résultats retourné.

Type : objet (ResultSet_resultSetMetaData)

data

Si la requête contient une seule instruction SQL, ce champ contient les données du jeu de résultats.

Un format de jeu de résultats est un tableau de tableaux dans JSON :

  • Chaque tableau correspond à une seule ligne.

  • Le premier élément d’une ligne est une chaîne JSON contenant un ID de séquence qui commence à partir de 0.

  • Le reste des éléments d’une ligne sont les données réelles.

  • Les données sont codées sous forme de chaînes JSON, quel que soit le type de données Snowflake.

Type : tableau de tableaux

Exemple :

[
  ["0","customer1","1234 A Avenue","98765","1565481394123000000"],
  ["1","customer2","987 B Street","98765","1565516712912012345"],
  ["2","customer3","8777 C Blvd","98765","1565605431999999999"],
  ["3","customer4","64646 D Circle","98765","1565661272000000000"]
]

Si la requête contient plusieurs instructions SQL, ce champ contient simplement le message « Multiple statements executed successfully » (Les instructions multiples ont été exécutées avec succès). Pour récupérer les résultats de chaque instruction dans la requête, récupérez les handles de ces instructions dans le champ statementHandles, et envoyez des requêtes pour obtenir les résultats de chaque instruction.

stats

Pour les instructions DML, ce champ contient des statistiques sur le nombre de lignes affectées par l’opération.

Type : objet (ResultSet_stats)

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData est un objet JSON qui contient des métadonnées sur les résultats de l’exécution d’une instruction. Cet objet se trouve dans le champ resultSetMetaData de l’objet ResultSet.

Champs

Champ

Description

page

Le numéro qui identifie la page actuelle des résultats.

Type : nombre entier signé de 64 bits

Exemple : 12

pageSize

Le nombre de lignes par page. Ce champ est défini uniquement si vous avez spécifié le paramètre pageSize dans la requête.

Type : nombre entier signé de 64 bits

Exemple : 10

numPages

Le nombre de pages de résultats.

Type : nombre entier signé de 64 bits

Exemple : 10

numRows

Le nombre total de lignes de résultats.

Type : nombre entier signé de 64 bits

Exemple : 100

format

Format des données dans le jeu de résultats. La seule valeur prise en charge est json.

Type : chaîne

rowType

Tableau d’objets ResultSet_resultSetMetaData_rowType qui décrivent les colonnes du jeu de résultats.

Type : tableau de ResultSet_resultSetMetaData_rowType.

Exemple :

[
 {"name":"ROWNUM","type":"FIXED","length":0,"precision":38,"scale":0,"nullable":false},
 {"name":"ACCOUNT_ID","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}
]

ResultSet_resultSetMetaData_rowType

ResultSet_resultSetMetaData_rowType est un objet JSON qui décrit une colonne dans un jeu de résultats. Un tableau de ces objets se trouve dans le champ rowType de l’objet ResultSet_resultSetMetaData.

Champs

Champ

Description

name

Nom de la colonne.

Type : chaîne

type

Type de données Snowflake de la colonne.

Type : chaîne

length

Longueur de la colonne.

Type : nombre entier signé de 64 bits

precision

Précision de la colonne.

Type : nombre entier signé de 64 bits

scale

Échelle de la colonne.

Type : nombre entier signé de 64 bits

nullable

Spécifie si la colonne peut avoir le critère Null ou non.

Type : booléen

Exemple

{
 "name":"ACCOUNT_NAME",
 "type":"TEXT",
 "length":1024,
 "precision":0,
 "scale":0,
 "nullable":false
}

ResultSet_stats

ResultSet_stats est un objet JSON qui contient des statistiques sur l’exécution d’une instruction DML. Cet objet se trouve dans le champ stats de l’objet ResultSet_resultSetMetaData.

Champs

Champ

Description

numRowsInserted

Nombre de lignes qui ont été insérées.

Type : nombre entier signé de 64 bits

Exemple : 12

numRowsUpdated

Nombre de lignes qui ont été mises à jour.

Type : nombre entier signé de 64 bits

Exemple : 9

numRowsDeleted

Nombre de lignes qui ont été supprimées.

Type : nombre entier signé de 64 bits

Exemple : 8

numDuplicateRowsUpdated

Nombre de lignes dupliquées qui ont été mises à jour.

Type : nombre entier signé de 64 bits

Exemple : 20