Snowflake-SQL-API-Referenz

Unter diesem Thema sind die Operationen, Anforderungen und Antworten der SQL-API dokumentiert.

Unter diesem Thema:

Operationen

POST /api/v2/statements

Um eine oder mehrere SQL-Anweisungen zur Ausführung zu übermitteln, senden Sie eine POST-Anforderung an /api/v2/statements. Sie können angeben, dass die Anweisung asynchron ausgeführt werden soll.

Syntax von Anforderungen

POST /api/v2/statements
(request body)
Copy

Abfrageparameter

Parameter

Beschreibung

requestId

(Optional) Eindeutige ID (eine UUID) der API-Anforderung. Siehe Erneutes Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen.

async

(Optional) Wird auf true gesetzt, um die Anweisung asynchron auszuführen und das Anweisungshandle zurückzugeben.

Wenn der Parameter nicht angegeben oder auf „false“ gesetzt ist, wird eine Anweisung ausgeführt, und die Ergebnisse werden zurückgegeben, wenn die Ausführung innerhalb von 45 Sekunden abgeschlossen ist. Wenn die Ausführung der Anweisung länger dauert, wird das Anweisungshandle zurückgegeben.

nullable

(Optional) Auf false setzen, um einen SQL NULL-Wert als Zeichenfolge "null" und nicht als Wert null zurückzugeben.

Bemerkung

Sie können diesen Parameter nicht in einer GET-Anforderung angeben.

Standardmäßig werden SQL NULL-Werte als der Wert null zurückgegeben:

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

Das Festlegen dieses Abfrageparameters auf „false“ (z. B. /api/v2/statements?nullable=false gibt einen SQL NULL-Wert als Zeichenfolge "null" zurück:

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

Header der Anforderung

Die Anforderung muss die unter Anforderungsheader für alle Operationen aufgeführten Header enthalten.

Anforderungstext

(Erforderlich) Der Anforderungstext muss das unter Text der POST-Anforderung an /api/v2/statements/ angegebene Objekt enthalten.

Antwort

Diese Operation kann die unten aufgeführten Antwortcodes zurückgeben.

Code

Beschreibung

200

Die Anweisung wurde erfolgreich ausgeführt.

Für diesen Antwortcode kann die Antwort den folgenden Header haben:

Wenn in der Anforderung eine einzelne SQL-Anweisung übermittelt wurde, enthält der Antworttext ein ResultSet-Objekt, das die angeforderten Daten enthält.

Bemerkung

Wenn das Feld code in der Antwort auf 391908 gesetzt ist, ist das Resultset zu groß, . und die Antwort enthält nicht das gesamte Resultset.

Das folgende Beispiel zeigt eine Antwort für eine einzelne SQL-Anweisung, bei der die Ergebnisse in einer einzigen Partition zurückgegeben werden. Dabei ist {handle} das Anweisungshandle, und {id1}, {id2} und {id3} sind eindeutig generierte Anforderungs-IDs:

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

Das folgende Beispiel zeigt eine Antwort für eine einzelne SQL-Anweisung, bei der die Ergebnisse in mehreren Partitionen zurückgegeben werden müssen, wobei {handle} das Anweisungshandle ist und {id1}, {id2}, {id3} und {id4} eindeutig generierte Anforderungs-IDs sind:

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

Wenn in der Anforderung mehrere SQL-Anweisungen übermittelt wurden, enthält der Antworttext ein ResultSet-Objekt mit Details zum Ausführungsstatus der einzelnen Anweisungen.

In diesem Fall enthält die Antwort nicht die angeforderten Daten. Stattdessen enthält das Feld data nur die Meldung „Multiple statements executed successfully“ (Mehrere Anweisungen erfolgreich ausgeführt).

Die Antwort enthält das Feld statementHandles, das ein Array von Anweisungshandles ist, mit denen Sie die Ergebnisse der einzelnen Anweisungen abrufen können.

Das folgende Beispiel zeigt eine Antwort auf eine Anforderung, die mehrere SQL-Anweisungen angibt, wobei:

  • {handle} ist das Anweisungshandle für die Menge der Anweisungen.

  • {handle1}, {handle2} und {handle3} sind die Handles für die einzelnen SQL-Anweisungen in der Anforderung.

  • {id1}, {id2}, und {id3} sind eindeutig generierte Anforderungs-IDs.

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

202

Die Ausführung der Anweisung ist noch nicht abgeschlossen. Verwenden Sie GET /api/v2/statements/{statementHandle}, um den Status der Anweisungsausführung zu prüfen. Weitere Informationen dazu finden Sie unter GET /api/v2/statements/{statementHandle}.

Der Antworttext enthält ein QueryStatus-Objekt mit Angaben zum Status der Anweisungsausführung.

Das folgende Beispiel zeigt eine Antwort:

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

408

Die Dauer der Anweisungsausführung hat das Timeout-Limit überschritten. Die Ausführung der Anweisung wurde abgebrochen.

Der Antworttext enthält ein QueryStatus-Objekt mit Details zum Abbruch der Anweisungsausführung.

422

Beim Ausführen der Anweisung ist ein Fehler aufgetreten. Überprüfen Sie den Fehlercode und die Fehlermeldung für Details.

Der Antworttext enthält ein QueryFailureStatus-Objekt mit Details zum Fehler.

Das folgende Beispiel zeigt eine Antwort:

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

Informationen zu den anderen Antwortcodes, die von dieser Operation zurückgegeben werden können, finden Sie unter Antwortcodes für alle Operationen.

GET /api/v2/statements/{statementHandle}

Um den Status der Anweisungsausführung zu prüfen, senden Sie eine GET-Anforderung an /api/v2/statements/{statementHandle}. Wenn die Anweisung erfolgreich ausgeführt wurde, enthält der Antworttext ein ResultSet-Objekt, das die angeforderten Daten enthält.

Syntax von Anforderungen

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

Pfadparameter

Parameter

Beschreibung

statementHandle

(Erforderlich) Das Handle der Anweisung, die Sie prüfen möchten. Sie können dieses Handle über das QueryStatus-Objekt erhalten, das in der Antwort auf die Anforderung zur Anweisungsausführung zurückgegeben wird.

Abfrageparameter

requestId

(Optional) Eindeutige ID (eine UUID) der API-Anforderung. Siehe Erneutes Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen.

partition

(Optional) Die Partitionsnummer, die zurückgegeben werden soll. Die Größe der einzelnen Partitionen wird von Snowflake festgelegt.

Weitere Informationen dazu finden Sie unter Abrufen der Ergebnisse aus der Antwort.

Header der Anforderung

Die Anforderung muss die unter Anforderungsheader für alle Operationen aufgeführten Header enthalten.

Antwort

Diese Operation kann die unten aufgeführten Antwortcodes zurückgeben.

Code

Beschreibung

200

Die Anweisung wurde erfolgreich ausgeführt.

Für diesen Antwortcode kann die Antwort den folgenden Header haben:

Der Antworttext enthält ein ResultSet-Objekt, das die angeforderten Daten enthält.

Das folgende Beispiel zeigt eine Antwort, wobei {handle} das Anweisungshandle ist und {id1}, {id2}, {id3}, {id4} und {id5}} eindeutig generierte Anforderungs-IDs sind:

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

202

Die Ausführung der Anweisung ist noch nicht abgeschlossen. Wiederholen Sie die Anforderung, um den Status der Anweisungsausführung zu überprüfen.

Der Antworttext enthält ein QueryStatus-Objekt mit Angaben zum Status der Anweisungsausführung.

Das folgende Beispiel zeigt eine Antwort:

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

422

Beim Ausführen der Anweisung ist ein Fehler aufgetreten. Überprüfen Sie den Fehlercode und die Fehlermeldung für Details.

Der Antworttext enthält ein QueryFailureStatus-Objekt mit Details zum Fehler.

Informationen zu den anderen Antwortcodes, die von dieser Operation zurückgegeben werden können, finden Sie unter Antwortcodes für alle Operationen.

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

Um die Ausführung einer Anweisung abzubrechen, senden Sie eine POST-Anforderung an /api/v2/statements/{statementHandle}/cancel.

Syntax von Anforderungen

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

Pfadparameter

Parameter

Beschreibung

statementHandle

(Erforderlich) Das Handle der Anweisung, die Sie prüfen möchten. Sie können dieses Handle über das QueryStatus-Objekt erhalten, das in der Antwort auf die Anforderung zur Anweisungsausführung zurückgegeben wird.

Abfrageparameter

Parameter

Beschreibung

requestId

(Optional) Eindeutige ID (eine UUID) der API-Anforderung. Siehe Erneutes Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen.

Header der Anforderung

Die Anforderung muss die unter Anforderungsheader für alle Operationen aufgeführten Header enthalten.

Antwort

Diese Operation kann die unten aufgeführten Antwortcodes zurückgeben.

Code

Beschreibung

200

Die Ausführung der Anweisung wurde erfolgreich abgebrochen.

Der Antworttext enthält ein CancelStatus-Objekt mit Informationen zum Abbruch der Anweisungsausführung.

Das folgende Beispiel zeigt eine Antwort:

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

422

Beim Ausführen der Anweisung ist ein Fehler aufgetreten. Überprüfen Sie den Fehlercode und die Fehlermeldung für Details.

Der Antworttext enthält ein QueryFailureStatus-Objekt mit Details zum Fehler.

Das folgende Beispiel zeigt eine Antwort:

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

Informationen zu den anderen Antwortcodes, die von dieser Operation zurückgegeben werden können, finden Sie unter Antwortcodes für alle Operationen.

Anforderungsheader für alle Operationen

Die folgenden Anforderungsheader gelten für alle Operationen:

Header

Erforderlich oder optional?

Beschreibung

Authorization

Erforderlich

Geben Sie hier Bearer, gefolgt von dem Token an, das zur Authentifizierung bei Snowflake verwendet wird.

Beispiel:

Authorization: Bearer token

Siehe Authentifizierung am Server.

Accept

Erforderlich

Geben Sie hier die Liste der Medientypen (MIME-Typen) an, die im Antworttext zulässig sind. Fügen Sie den Typ application/json hinzu (oder, wenn alle Typen zulässig sind, verwenden Sie */*).

Content-Type

Erforderlich

Geben Sie hier den Medientyp (MIME-Typ) des Anforderungstextes an. Geben Sie application/json an.

User-Agent

Erforderlich

Geben Sie hier den Namen und die Version Ihrer Anwendung an (z. B. applicationName/applicationVersion). Sie müssen einen Wert verwenden, der dem RFC 7231-Standard entspricht.

X-Snowflake-Authorization-Token-Type

Erforderlich für Schlüsselpaar-Authentifizierung

Optional für OAuth

Wenn Sie die Schlüsselpaar-Authentifizierung verwenden, ist dieser Header erforderlich. Sie müssen diesen Header auf KEYPAIR_JWT setzen.

Wenn Sie OAuth zur Authentifizierung verwenden, ist dieser Header optional. (Wenn Sie den Header einstellen möchten, setzen Sie ihn auf OAUTH.)

Objekttypen im Anforderungstext

Text der POST-Anforderung an /api/v2/statements/

Der Text einer POST-Anforderung an den Endpunkt /api/v2/statements/ (siehe POST /api/v2/statements) ist ein JSON-Objekt, mit dem Sie die auszuführende SQL-Anweisung, den Anweisungskontext und das Datenformat des Resultsets angeben. Sie verwenden dieses Objekt im Anforderungstext, um eine Anweisung auszuführen.

Felder

Feld

Beschreibung

statement

(Optional) SQL-Anweisung, die ausgeführt werden soll. Eine Liste der unterstützten und nicht unterstützten Anweisungen finden Sie unter Einschränkungen der SQL-API.

Typ: Zeichenfolge

timeout

(Optional) Timeout in Sekunden für die Anweisungsausführung. Wenn die Ausführung einer Anweisung länger dauert als das angegebene Timeout, wird die Ausführung automatisch abgebrochen. Um für das Timeout den maximalen Wert (604.800 Sekunden) festzulegen, setzen Sie „timeout“ auf 0. Wenn kein Wert angegeben wird, wird das im Parameter STATEMENT_TIMEOUT_IN_SECONDS festgelegte Timeout verwendet.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 10

database

(Optional) Datenbank, in der die Anweisung ausgeführt werden soll. Beim Wert in diesem Feld wird zwischen Groß- und Kleinschreibung unterschieden.

Wenn Sie dieses Feld auslassen, verwendet die SQL-API die Datenbank aus dem Wert der Benutzereigenschaft DEFAULT_NAMESPACE.

Typ: Zeichenfolge

Beispiel: TESTDB

schema

(Optional) Schema, in dem die Anweisung ausgeführt werden soll. Beim Wert in diesem Feld wird zwischen Groß- und Kleinschreibung unterschieden.

Wenn Sie dieses Feld auslassen, verwendet die SQL-API das Schema aus dem Wert der Benutzereigenschaft DEFAULT_NAMESPACE.

Typ: Zeichenfolge

Beispiel: TESTSCHEMA

warehouse

(Optional) Warehouse, das beim Ausführen der Anweisung verwendet werden soll. Beim Wert in diesem Feld wird zwischen Groß- und Kleinschreibung unterschieden.

Wenn Sie dieses Feld auslassen, verwendet die SQL-API den Wert der Benutzereigenschaft DEFAULT_WAREHOUSE.

Typ: Zeichenfolge

Beispiel: TESTWH

role

(Optional) Rolle, die beim Ausführen der Anweisung verwendet werden soll. Beim Wert in diesem Feld wird zwischen Groß- und Kleinschreibung unterschieden.

Wenn Sie dieses Feld auslassen, verwendet die SQL-API den Wert der Benutzereigenschaft DEFAULT_ROLE.

Typ: Zeichenfolge

Beispiel: TESTROLE

bindings

(Optional) Werte der bindenden Variablen in der SQL-Anweisung. Beim Ausführen der Anweisung ersetzt Snowflake die Platzhalter (? und :name) in der Anweisung durch diese angegebenen Werte.

Beachten Sie, dass sich das Format dieses Feldes in der Version für die allgemeine Verfügbarkeit der SQL-API möglicherweise ändern kann.

Typ: Objekt

Beispiel:

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

parameters

(Optional) Sitzungsparameter, die Sie für diese Anforderung einstellen möchten.

Typ: Objekt (statements_parameters)

Beispiel

Das folgende Beispiel zeigt ein Textobjekt:

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

statements_parameters

statements_parameters ist ein JSON-Objekt, mit dem Sie die Sitzungsparameter angeben, die Sie für diese Anforderung festlegen möchten. Dieses Objekt muss im Feld parameters des POST-Anforderungstextes an den Endpunkt /api/v2/statements (siehe Text der POST-Anforderung an /api/v2/statements/) enthalten sein.

Bemerkung

Die SQL-API unterstützt nur die in der folgenden Tabelle aufgeführten Sitzungsparameter.

Felder

Feld

Beschreibung

binary_output_format

(Optional) Gibt das Format für VARCHAR-Werte an, die von BINARY-VARCHAR-Konvertierungsfunktionen zurückgegeben werden. Weitere Details dazu finden Sie unter BINARY_OUTPUT_FORMAT.

Typ: Zeichenfolge

Beispiel: HEX

client_result_chunk_size

(Optional) Gibt die maximale Größe (in MB) jedes Sets (oder Blocks) der herunterzuladenden Abfrageergebnisse an. Weitere Details dazu finden Sie unter CLIENT_RESULT_CHUNK_SIZE.

Typ: Ganzzahl (Integer)

Beispiel: 100

date_output_format

(Optional) Gibt das Anzeigeformat für den Datentyp DATE an. Weitere Details dazu finden Sie unter DATE_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

Beispiel: YYYY-MM-DD

multi_statement_count

(Erforderlich, wenn in einer Anforderung mehrere SQL-Anweisungen angegeben werden) Gibt die Anzahl der SQL-Anweisungen in einer Anforderung an, die übermittelt werden, wenn die Funktion für mehrere Anweisungen verwendet wird. Gültige Werte:

  • 0: Gibt an, dass eine variable Anzahl von Anweisungen in die Anforderung aufgenommen werden kann.

  • 1: Zeigt an, dass nur eine SQL-Anweisung in der Anforderung enthalten sein kann. Dies ist der Standardwert, der verwendet wird, wenn Sie im Feld MULTI_STATEMENT_COUNT keinen Wert angeben.

  • > 1: Gibt die Anzahl der in der Anforderung übermittelten SQL-Anweisungen an. Diese Anzahl muss mit der im statement-Feld angegebenen Anzahl von Anweisungen übereinstimmen.

Typ: Zeichenfolge

Beispiel: 2

query_tag

(Optional) Abfrage-Tag, das Sie der SQL-Anweisung zuordnen möchten. Weitere Details dazu finden Sie unter Parameter QUERY_TAG.

Typ: Zeichenfolge

Beispiel: tag-1234

rows_per_resultset

(Optional) Gibt die maximale Anzahl von Zeilen an, die in einem Resultset zurückgegeben werden, wobei 0 (Standard) für kein Maximum steht. Weitere Details dazu finden Sie unter Parameter ROWS_PER_RESULTSET.

Typ: Ganzzahl (Integer)

Beispiel: 200

time_output_format

(Optional) Gibt das Anzeigeformat für den Datentyp TIME an. Weitere Details dazu finden Sie unter TIME_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

Beispiel: HH24:MI:SS

timestamp_ltz_output_format

(Optional) Gibt das Anzeigeformat für den Datentyp TIMESTAMP_LTZ an. Weitere Details dazu finden Sie unter TIMESTAMP_LTZ_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

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

timestamp_ntz_output_format

(Optional) Gibt das Anzeigeformat für den Datentyp TIMESTAMP_NTZ an. Weitere Details dazu finden Sie unter TIMESTAMP_NTZ_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

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

timestamp_output_format

(Optional) Gibt das Anzeigeformat für den Datentypalias TIMESTAMP an. Weitere Details dazu finden Sie unter TIMESTAMP_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

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

timestamp_tz_output_format

(Optional) Gibt das Anzeigeformat für den Datentyp TIMESTAMP_TZ an. Weitere Details dazu finden Sie unter TIMESTAMP_TZ_OUTPUT_FORMAT. Weitere Details zur Verwendung von Parametern zur Bestimmung des Ausgabeformats von Abfrageergebnissen finden Sie unter Formatieren der Ausgabe von Abfrageergebnissen.

Typ: Zeichenfolge

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

timezone

(Optional) Zeitzone, die beim Ausführen der Anweisung verwendet werden soll. Weitere Details dazu finden Sie unter Parameter TIMEZONE.

Typ: Zeichenfolge

Beispiel: america/los_angeles

use_cached_result

(Optional) Gibt an, ob Abfrageergebnisse zwischen aufeinanderfolgenden Aufrufen derselben Abfrage wiederverwendet werden können, solange das ursprüngliche Ergebnis nicht abgelaufen ist. Weitere Informationen dazu finden Sie unter Parameter USE_CACHED_RESULT.

Typ: Zeichenfolge

Beispiel: true

Antwortcodes für alle Operationen

In diesem Abschnitt sind die Antwortcodes aufgeführt, die für alle Operationen gelten.

Code

Beschreibung

400

„Bad Request“.

Nutzlast (Payload) der Anforderung ist ungültig oder falsch formatiert. Dies geschieht, wenn die Anwendung nicht die korrekte Anforderungsnutzlast gesendet hat. Der Antworttext kann den Fehlercode und eine Meldung mit Angaben zur tatsächlichen Ursache enthalten. Die Anwendung muss den Anforderungstext für einen erneuten Versuch rekonstruieren.

Das folgende Beispiel zeigt eine Antwort:

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

401

Unauthorized (Nicht autorisiert).

Die Anforderung ist nicht autorisiert. Dies geschieht, wenn das angehängte Zugriffstoken ungültig ist oder fehlt. Der Antworttext kann den Fehlercode und eine Meldung mit Angaben zur tatsächlichen Ursache, wie abgelaufenes oder ungültiges Token, enthalten. Die Anwendung muss ein neues Zugriffstoken für einen erneuten Versuch erhalten.

Siehe Authentifizierung am Server.

Das folgende Beispiel zeigt eine Antwort:

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

403

Forbidden (Unzulässig).

Die Anforderung ist unzulässig. Dies geschieht, wenn die Anforderung auch dann erfolgt, wenn die API nicht aktiviert ist.

404

Not found (Nicht gefunden).

Der Endpunkt der Anforderung ist ungültig. Dies geschieht, wenn der API-Endpunkt falsch ist. Wenn die Anwendung z. B. /api/v2/hello anfordert, das nicht vorhanden ist, gibt der Server folgenden Code zurück.

405

Method Not Allowed (Methode nicht zugelassen).

Die Anforderungsmethode stimmt nicht mit der unterstützten API überein. Dies geschieht beispielsweise, wenn die Anwendung die API mit der GET-Methode aufruft, der Endpunkt aber nur POST akzeptiert. Die Anwendung muss beim Senden der Anforderung eine unterstützte Methode verwenden.

Das folgende Beispiel zeigt eine Antwort:

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

415

Der Anforderungsheader Content-Type enthält einen nicht unterstützten Medientyp.

Die API unterstützt nur application/json. Wenn kein Wert für Content-Type angegeben ist, wird die Nutzlast (Payload) der Anforderung als JSON interpretiert, aber wenn ein anderer Medientyp angegeben ist, wird dieser Fehler zurückgegeben.

429

Too many requests (Zu viele Anforderungen).

Die Anzahl der Anforderungen hat das Ratenlimit erreicht. Die Anwendung muss die Häufigkeit der an die API-Endpunkte gesendeten Anforderungen reduzieren. Die Anwendung kann es mit Backoff erneut versuchen. Es wird ein exponentiell gejittertes Backoff empfohlen.

Diese Antwort kann auch auftreten, wenn der Server zu viele gleichzeitige Anforderungen erhält. Die Parallelitätseinschränkungen für die API werden durch die von Snowflake erzwungenen Parallelitätseinschränkungen bestimmt.

Das folgende Beispiel zeigt eine Antwort:

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

500

Internal Server Error (Interner Serverfehler).

Der Server ist auf einen nicht behebbaren Systemfehler gestoßen. Der Antworttext kann den Fehlercode und die Fehlermeldung zur weiteren Bearbeitung enthalten.

503

Service Unavailable (Dienst ist nicht verfügbar).

Die Anforderung wurde aufgrund eines Timeout auf dem Server nicht bearbeitet. Die Anwendung kann es mit Backoff erneut versuchen. Es wird ein exponentiell gejittertes Backoff empfohlen.

504

Gateway Timeout.

Die Anforderung wurde aufgrund eines Timeout auf dem Server nicht bearbeitet. Die Anwendung kann es mit Backoff erneut versuchen. Es wird ein exponentiell gejittertes Backoff empfohlen.

Antwortheader für alle Operationen

Antworten können die folgenden Header enthalten:

Header

Beschreibung

Link

Dieser Header ist in der 200-Antwort für eine Anforderung zur Anweisungsausführung und einer Anforderung zur Überprüfung des Status der Anweisungsausführung enthalten.

Dieser Header enthält Links zu anderen Partitionen von Ergebnissen (z. B. zur ersten Partition, zur letzten Partition usw.). Der Header kann mehrere URL-Einträge mit unterschiedlichen rel-Attributwerten enthalten, die die zurückzugebende Partition angeben (first, next, prev und last).

Beispiel:

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

Objekttypen im Antworttext

CancelStatus

CancelStatus ist ein JSON-Objekt, das Informationen zum Abbruch der Anweisungsausführung enthält. Dieses Objekt wird im Antworttext einer Abbruchanforderung zurückgegeben.

Felder

Feld

Beschreibung

code

Typ: Zeichenfolge

sqlState

Typ: Zeichenfolge

message

Beispiel: successfully cancelled

Typ: Zeichenfolge

statementHandle

Eindeutiger Bezeichner für die auszuführende Anweisung.

Typ: Zeichenfolge (eine UUID)

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

statementStatusUrl

URL zum Abrufen von Anweisungsstatus und Resultset.

Typ: Zeichenfolge (eine URL)

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

Beispiel

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

QueryFailureStatus

QueryFailureStatus ist ein JSON-Objekt, das Informationen zur fehlgeschlagenen Ausführung einer Anweisung enthält. Dieses Objekt wird im Antworttext der 422-Antwort einer Anforderung zur Ausführung der Anweisung zurückgegeben.

Felder

Feld

Beschreibung

code

Typ: Zeichenfolge

Beispiel: 0

sqlState

Typ: Zeichenfolge

message

Typ: Zeichenfolge

Beispiel: successfully executed

statementHandle

Eindeutiger Bezeichner für die auszuführende Anweisung.

Typ: Zeichenfolge (eine UUID)

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

createdOn

Zeitstempel, der angibt, wann die Ausführung der Anweisung begonnen hat. Der Zeitstempel wird in Millisekunden seit der Epoche angegeben.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 1597090533987

statementStatusUrl

URL zum Abrufen von Anweisungsstatus und Resultset.

Typ: Zeichenfolge (eine URL)

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

Beispiel

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

QueryStatus

QueryStatus ist ein JSON-Objekt, das Informationen zum Status der Anweisungsausführung enthält. Dieses Objekt wird auf folgende Weise zurückgegeben:

Felder

Feld

Beschreibung

code

Typ: Zeichenfolge

Beispiel: 0

sqlState

Typ: Zeichenfolge

message

Typ: Zeichenfolge

Beispiel: successfully executed

statementHandle

Eindeutiger Bezeichner für die auszuführende Anweisung.

Typ: Zeichenfolge (eine UUID)

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

createdOn

Zeitstempel, der angibt, wann die Ausführung der Anweisung begonnen hat. Der Zeitstempel wird in Millisekunden seit der Epoche angegeben.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 1597090533987

statementStatusUrl

URL zum Abrufen von Anweisungsstatus und Resultset.

Typ: Zeichenfolge (eine URL)

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

Beispiel

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

ResultSet

ResultSet ist ein JSON-Objekt, das die Ergebnisse der Anweisungsausführung enthält. Dieses Objekt wird im Antworttext der 200-Antwort einer Anforderung zur Anweisungsausführung und einer Anforderung zur Überprüfung des Status der Anwendungsausführung zurückgegeben.

Felder

Feld

Beschreibung

code

Typ: Zeichenfolge

Beispiel: 0

sqlState

Typ: Zeichenfolge

message

Typ: Zeichenfolge

Beispiel: successfully executed

statementHandle

Eindeutiger Bezeichner für die auszuführende Anweisung.

Wenn in der Anforderung mehrere Anweisungen angegeben wurden, entspricht dieses Handle der Menge dieser Anweisungen. Die Handles der einzelnen Anweisungen in der Anforderung finden Sie im Feld statementHandles.

Typ: Zeichenfolge (eine UUID)

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

statementHandles

Array mit eindeutigen Bezeichnern für die Anweisungen, die für diese Anforderung ausgeführt werden.

Typ: Array von Zeichenfolgen (UUID)

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

createdOn

Zeitstempel, der angibt, wann die Ausführung der Anweisung begonnen hat. Der Zeitstempel wird in Millisekunden seit der Epoche angegeben.

Beispiel: 1597090533987

statementStatusUrl

URL zum Abrufen von Anweisungsstatus und Resultset.

Typ: Zeichenfolge (eine URL)

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

resultSetMetaData

Metadaten über das zurückgegebene Resultset.

Typ: Objekt (ResultSet_resultSetMetaData)

data

Wenn die Anforderung eine einzelne SQL-Anweisung enthält, enthält dieses Feld die Daten des Resultset.

Ein Resultset-Format ist ein Array von Arrays in JSON:

  • Jedes Array entspricht einer einzelnen Zeile.

  • Die Elemente in einer Zeile entsprechen den Werten in den Spalten der jeweiligen Zeile.

  • Die Daten werden unabhängig vom Snowflake-Datentyp als JSON-Zeichenfolgen kodiert.

Typ: Array von Arrays

Beispiel:

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

Wenn die Anforderung mehrere SQL-Anweisungen enthält, enthält das Feld nur die Meldung „Multiple statements executed successfully“ (Mehrere Anweisungen erfolgreich ausgeführt). Um die Ergebnisse für jede Anweisung in der Anforderung abzurufen, rufen Sie die Handles für diese Anweisungen aus dem Feld statementHandles ab und senden Anforderungen, um die Ergebnisse jeder Anweisung zu erhalten.

stats

Bei DML-Anweisungen enthält dieses Feld eine Statistik über die Anzahl der von der Operation betroffenen Zeilen.

Typ: Objekt (ResultSet_stats)

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData ist ein JSON-Objekt, das Metadaten über die Ergebnisse der Anweisungsausführung enthält. Dieses Objekt befindet sich im Feld resultSetMetaData des Objekts ResultSet.

Felder

Feld

Beschreibung

partition

Die Indexnummer der Partition, die Sie zurückgeben möchten (wobei 0 die erste Datenpartition angibt). Snowflake liefert Daten in Partitionen. Snowflake bestimmt die Anzahl der Partitionen und die Größe der einzelnen Partitionen zur Laufzeit. Sie können die Liste der Partitionen aus dem resultSetMetaData-Objekt in der Antwort auf die POST-Anforderung erhalten.

Weitere Informationen dazu finden Sie unter Abrufen der Ergebnisse aus der Antwort.

numRows

Die Gesamtzahl der Ergebniszeilen.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 100

format

Format der Daten im Resultset.

Typ: Zeichenfolge

rowType

Array von ResultSet_resultSetMetaData_rowType-Objekten, die die Spalten im Resultset beschreiben.

Typ: Array von ResultSet_resultSetMetaData_rowType.

Beispiel:

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

ResultSet_resultSetMetaData_rowType

ResultSet_resultSetMetaData_rowType ist ein JSON-Objekt, das eine Spalte in einem Resultset beschreibt. Ein Array dieser Objekte befindet sich im Feld rowType des Objekts ResultSet_resultSetMetaData.

Felder

Feld

Beschreibung

name

Name der Spalte.

Typ: Zeichenfolge

type

Snowflake-Datentypen der Spalte.

Typ: Zeichenfolge

length

Länge der Spalte.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

precision

Genauigkeit der Spalte.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

scale

Skalierung der Spalte.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

nullable

Gibt an, ob die Spalte nullwertfähig ist oder nicht.

Typ: Boolean

Beispiel

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

ResultSet_stats

ResultSet_stats ist ein JSON-Objekt, das Statistiken über die Ausführung einer DML-Anweisung enthält. Dieses Objekt befindet sich im Feld stats des Objekts ResultSet_resultSetMetaData.

Felder

Feld

Beschreibung

numRowsInserted

Anzahl der eingefügten Zeilen.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 12

numRowsUpdated

Anzahl der aktualisierten Zeilen.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 9

numRowsDeleted

Anzahl der gelöschten Zeilen.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 8

numDuplicateRowsUpdated

Anzahl der doppelten Zeilen, die aktualisiert wurden.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 20
Sprache: Deutsch