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

POST /api/v2/statements

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

Syntaxe de la requête

POST /api/v2/statements
(request body)

Paramètres de requête

Paramètre

Description

requestId

(Facultatif) ID unique (un UUID) de la requête API. Voir Nouvelle soumission d’une requête d’exécution d’instructions SQL.

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

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.

Note

Vous ne pouvez pas spécifier ce paramètre dans une requête GET.

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

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

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

"data" : [ [ "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/v2/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.

Voici un exemple de réponse pour une seule instruction SQL dont les résultats sont renvoyés dans une seule partition. {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/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 4,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 4,
      "uncompressedSize": 1438,
    }]
  },
  "data" : [ [ "test", "2" ], [ "test", "3" ], [ "test", "4" ], [ "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id3}&partition=0",
  "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 partitions, 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/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 56090,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "0", "QqKow2xzdJ....." ],.... [ "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/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/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=1>; rel="last"

{
  "resultSetMetaData" : {
  "numRows" : 56090,
  "format" : "jsonv2",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
     "rowCount": 43746,
     "uncompressedSize": 43748274,
     "compressedSize": 746323
    }]
  },
  "data" : [ [ "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/v2/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/v2/statements/{statementHandle} pour vérifier le statut d’exécution de l’instruction. Voir GET /api/v2/statements/{statementHandle} pour plus de détails.

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/v2/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.

GET /api/v2/statements/{statementHandle}

Pour vérifier le statut d’exécution d’une instruction, envoyez une requête GET à /api/v2/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/v2/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 Nouvelle soumission d’une requête d’exécution d’instructions SQL.

partition

(Facultatif) Le numéro de la partition à retourner. La taille de chaque partition est déterminée par Snowflake.

Voir Obtention des résultats à partir de la réponse pour plus d’informations.

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/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="prev",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id4}&partition=10>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 10000,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "10", "lJPPMTSwps......" ], ... [ "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id5}&partition=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/v2/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.

POST /api/v2/statements/{statementHandle}/cancel

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

Syntaxe de la requête

POST /api/v2/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 Nouvelle soumission d’une requête d’exécution d’instructions SQL.

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/v2/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/v2/statements/

Le corps d’une requête POST vers le point de terminaison /api/v2/statements/ (voir POST /api/v2/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 Limitations de l’API SQL 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

database

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

Si vous omettez ce champ, l’API SQL utilise la base de données à partir de la valeur de la DEFAULT_NAMESPACE propriété de l’utilisateur.

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.

Si vous omettez ce champ, l’API SQL utilise le schéma de la valeur de la DEFAULT_NAMESPACE propriété de l’utilisateur.

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.

Si vous omettez ce champ, l’API SQL utilise la valeur de la DEFAULT_WAREHOUSE propriété de l’utilisateur.

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.

Si vous omettez ce champ, l’API SQL utilise la valeur de la DEFAULT_ROLE propriété de l’utilisateur.

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" : "jsonv2"
  },
  "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/v2/statements (voir Corps de la requête POST dans /api/v2/statements/).

Note

L’API SQL ne prend en charge que les paramètres de session énumérés dans le tableau suivant.

Champs

Champ

Description

binary_output_format

(Facultatif) Le format des valeurs VARCHAR renvoyées en sortie par les fonctions de conversion BINARY vers VARCHAR. Pour plus de détails, voir BINARY_OUTPUT_FORMAT.

Type : chaîne

Exemple : HEX

date_output_format

(Facultatif) Spécifie le format d’affichage pour le type de données DATE. Pour plus de détails, voir DATE_OUTPUT_FORMAT. Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : YYYY-MM-DD

multi_statement_count

(Obligatoire lors de la spécification de plusieurs instructions SQL dans une requête) Spécifie le nombre d’instructions SQL à soumettre dans une requête lors de l’utilisation de la fonctionnalité multi-instructions. Les valeurs valides sont :

  • 0 : indique qu’un nombre variable d’instructions peut être inclus dans la requête.

  • 1 : indique qu’une seule instruction SQL peut être incluse dans la requête. Il s’agit de la valeur par défaut utilisée si vous ne spécifiez pas le champ MULTI_STATEMENT_COUNT.

  • > 1 : indique le nombre d’instructions SQL soumises dans la requête. Ce nombre doit correspondre au nombre d’instructions spécifié dans le champ statement.

Type : chaîne

Exemple : 2

query_tag

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

Type : chaîne

Exemple : tag-1234

time_output_format

(Facultatif) Spécifie le format d’affichage pour le type de données TIME. Pour plus de détails, TIME_OUTPUT_FORMAT Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : HH24:MI:SS

timestamp_ltz_output_format

(Facultatif) Spécifie le format d’affichage pour le type de données TIMESTAMP_LTZ. Pour plus de détails, voir TIMESTAMP_LTZ_OUTPUT_FORMAT. Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : YYYY-MM-DD HH24:MI:SS.FF3

timestamp_ntz_output_format

(Facultatif) Spécifie le format d’affichage pour le type de données TIMESTAMP_NTZ. Pour plus de détails, voir TIMESTAMP_NTZ_OUTPUT_FORMAT. Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : YYYY-MM-DD HH24:MI:SS.FF3

timestamp_output_format

(Facultatif) Spécifie le format d’affichage de l’alias de type de données TIMESTAMP. Pour plus de détails, voir TIMESTAMP_OUTPUT_FORMAT. Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : YYYY-MM-DD HH24:MI:SS.FF3 TZHTZM

timestamp_tz_output_format

(Facultatif) Spécifie le format d’affichage pour le type de données TIMESTAMP_TZ. Pour plus de détails, voir TIMESTAMP_TZ_OUTPUT_FORMAT. Voir Formatage de la sortie des résultats de la requête pour plus de détails sur l’utilisation des paramètres pour déterminer le format de sortie des résultats de la requête.

Type : chaîne

Exemple : YYYY-MM-DD HH24:MI:SS.FF3

timezone

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

Type : chaîne

Exemple : america/los_angeles

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/v2/hello, ce qui n’existe pas, le serveur renvoie ce code.

405

Méthode non autorisée.

La méthode de demande ne correspond pas aux API prises 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

Trop de requêtes.

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. L’application peut réessayer avec une interruption. Une interruption à gigue exponentielle est recommandée.

Cette réponse peut également se produire lorsque le serveur reçoit trop de requêtes simultanées. Les limites d’accès concurrentiel sur l’API sont déterminées par les limites d’accès concurrentiel appliquées par Snowflake.

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 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 partitions de résultats (par exemple, la première partition, la dernière, etc.). L’en-tête peut inclure plusieurs entrées d’URL avec différentes valeurs d’attribut rel qui spécifient la partition à renvoyer (first, next, prev, et last).

Par exemple :

Link: </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=1; rel="last">,
      </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=1; rel="next">,
      </api/v2/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?partition=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/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully canceled",
  "statementHandle" : "536fad38-b564-4dc5-9892-a4543504df6c",
  "statementStatusUrl" : "/api/v2/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/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "002140",
  "sqlState" : "42601",
  "message" : "SQL compilation error",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/v2/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/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c

Exemple

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully executed",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/v2/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/v2/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.

  • Les éléments d’une ligne correspondent aux valeurs des colonnes de cette ligne.

  • 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 :

[
  ["customer1","1234 A Avenue","98765","1565481394123000000"],
  ["customer2","987 B Street","98765","1565516712912012345"],
  ["customer3","8777 C Blvd","98765","1565605431999999999"],
  ["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

partition

Le numéro d’index de la partition que vous voulez retourner (où 0 spécifie la première partition de données). Snowflake retourne les données en partitions. Snowflake détermine le nombre de partitions et la taille de chaque partition au moment de l’exécution. Vous pouvez obtenir la liste des partitions à partir de l’objet resultSetMetaData dans la réponse à la requête POST.

Voir Obtention des résultats à partir de la réponse pour plus d’informations.

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. Donnez-lui la valeur jsonv2 pour utiliser le nouveau modèle de retour des résultats dans les partitions.

Si vous omettez ce champ ou lui attribuez la valeur json, l’API SQL utilise le modèle existant pour renvoyer les résultats.

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

Revenir au début