Référence de l’API SQL Snowflake¶

requestId

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

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

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 :

• Lien

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.

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
}

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.

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.

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.

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 :

• Lien

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
}

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.

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.

requestId

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

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

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

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

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

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

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

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, voir 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_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_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

use_cached_result

(Facultatif) Si les résultats de la requête peuvent être réutilisés entre des appels successifs de la même requête tant que le résultat original n’a pas expiré. Pour plus de détails, voir Paramètre USE_CACHED_RESULT.

Type : chaîne

Exemple : true

code

Type : chaîne

message

Exemple : successfully cancelled

Type : chaîne

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

code

Type : chaîne

Exemple : 0

message

Type : chaîne

Exemple : successfully executed

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

code

Type : chaîne

Exemple : 0

message

Type : chaîne

Exemple : successfully executed

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

code

Type : chaîne

Exemple : 0

message

Type : chaîne

Exemple : successfully executed

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

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

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.

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.

format

Format des données dans le jeu de résultats.

Type : chaîne

name

Nom de la colonne.

Type : chaîne

length

Longueur de la colonne.

Type : nombre entier signé de 64 bits

scale

Échelle de la colonne.

Type : nombre entier signé de 64 bits

numRowsInserted

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

Type : nombre entier signé de 64 bits

Exemple : 12

numRowsDeleted

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

Type : nombre entier signé de 64 bits

Exemple : 8