Snowflake-SQL-API-Referenz

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

Unter diesem Thema:

Operationen

Übermitteln einer SQL-Anweisung zur Ausführung

Um eine oder mehrere SQL-Anweisungen zur Ausführung zu übermitteln, senden Sie eine POST-Anforderung an /api/statements. Sie können angeben, dass die Anweisung asynchron ausgeführt werden soll, und Sie können die Anzahl der Zeilen angeben, die pro Seite zurückgegeben werden sollen.

Syntax von Anforderungen

POST /api/statements
(request body)

Abfrageparameter

Parameter

Beschreibung

requestId

(Optional) Eindeutige ID (eine UUID) der API-Anforderung. Siehe Zuweisen einer eindeutigen Anforderungs-ID für die erneute Übermittlung von Anforderungen.

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.

Beachten Sie, dass die Ergebnisse nach Abschluss der Anweisungsausführung höchstens die durch den Parameter pageSize angegebene Anzahl von Zeilen enthalten. Wenn das Feld numRows in ResultSet_resultSetMetaData anzeigt, dass es zusätzliche Ergebniszeilen gibt, finden Sie unter Abrufen zusätzlicher Ergebnisseiten weitere Informationen.

pageSize

(Optional) Anzahl der Zeilen, die pro Seite zurückgegeben werden sollen. Die Seitengröße kann zwischen der minimalen unterstützten Anzahl (10) und der maximalen unterstützten Anzahl (10000) von Zeilen pro Seite liegen. Standardmäßig variiert die Anzahl der zurückgegebenen Zeilen in Abhängigkeit von der Ausführung der Anweisung.

Hinweis: Verwenden Sie diesen Parameter, wenn die Abfrage eine große Anzahl von Zeilen zurückgibt. Andernfalls kann die Anzahl der Zeilen die Standardanzahl der Zeilen auf einer Seite überschreiten.

nullable

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

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

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

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

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

Header der Anforderung

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

Text der Anforderung

(Erforderlich) Der Anforderungstext muss das unter Text der POST-Anforderung an „/api/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.

Weitere Informationen dazu finden Sie unter Feststellen, ob die Seitengröße des Resultsets den Grenzwert überschreitet.

Das folgende Beispiel zeigt eine Antwort für eine einzelne SQL-Anweisung, bei der die Ergebnisse auf eine einzige Seite passen, wobei {handle} das Anweisungshandle ist und {id1}, {id2} und {id3} eindeutig generierte Anforderungs-IDs sind:

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

Das folgende Beispiel zeigt eine Antwort für eine einzelne SQL-Anweisung, bei der die Ergebnisse auf mehreren Seiten 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/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=1&pageSize=-1>; rel="next",
  </api/statements/{handle}?requestId={id3}&page=7&pageSize=-1>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "numPages" : 8,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "0", "0", "QqKow2xzdJ....." ],.... [ "98", "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id4}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

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/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=-1>; rel="last"

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

202

Die Ausführung der Anweisung ist noch nicht abgeschlossen. Verwenden Sie GET /api/statements/{statementHandle}, um den Status der Anweisungsausführung zu prü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 18:12:37 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c06a4-0000-df4f-0000-00100006589e",
  "statementStatusUrl" : "/api/statements/019c06a4-0000-df4f-0000-00100006589e"
}

408

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

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

Status der Anweisungsausführung prüfen und Ergebnisse abrufen

Um den Status der Anweisungsausführung zu prüfen, senden Sie eine GET-Anforderung an /api/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/statements/{statementHandle}

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 Zuweisen einer eindeutigen Anforderungs-ID für die erneute Übermittlung von Anforderungen.

page

(Optional) Nummer, die angibt, welche Seite der Ergebnisse zurückgegeben werden soll. Die Anzahl kann zwischen 0 und der Gesamtzahl der Seiten minus 1 liegen.

pageSize

(Optional) Anzahl der Zeilen, die pro Seite zurückgegeben werden sollen. Die Seitengröße kann zwischen der minimalen unterstützten Anzahl (10) und der maximalen unterstützten Anzahl (10000) von Zeilen pro Seite liegen. Standardmäßig variiert die Anzahl der zurückgegebenen Zeilen in Abhängigkeit von der Ausführung der Anweisung.

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/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="prev",
  </api/statements/{handle}?requestId={id3}&page=2&pageSize=10>; rel="next",
  </api/statements/{handle}?requestId={id4}&page=999&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 1,
    "pageSize" : 10,
    "numPages" : 1000,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "10", "10", "lJPPMTSwps......" ], ... [ "19", "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id5}&pageSize=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

202

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/statements/019c07a7-0000-df4f-0000-001000067872"
}

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.

Abbrechen der Ausführung von Anweisungen

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

Syntax von Anforderungen

POST /api/statements/{statementHandle}/cancel

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 Zuweisen einer eindeutigen Anforderungs-ID für die erneute Übermittlung von Anforderungen.

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/statements/019c07bc-0000-df4f-0000-001000067c3e"
}

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

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

Der Text einer POST Anforderung an den „/api/statements/“-Endpunkt 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 Einführung.

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

resultSetMetaData

(Optional) Metadaten über das Resultset, das zurückgegeben werden soll.

Typ: Objekt (statements_resultSetMetaData)

database

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

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.

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.

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.

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

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,
  "resultSetMetaData" : {
    "format" : "json"
  },
  "database" : "TESTDB",
  "schema" : "TESTSCHEMA",
  "warehouse" : "TESTWH",
  "role" : "TESTROLE",
  "bindings" : {
    "1" : {
      "type" : "FIXED",
      "value" : "123"
    }
  }
}

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 sollte im Feld parameters des POST-Anforderungstextes an den „/api/statements“-Endpunkt enthalten sein.

Felder

Feld

Beschreibung

timezone

(Optional) Zeitzone, die beim Ausführen der Anweisung verwendet werden soll. Weitere Informationen dazu finden Sie in der Dokumentation zum TIMEZONE-Parameter.

Typ: Zeichenfolge

Beispiel: america/los_angeles

query_tag

(Optional) Abfrage-Tag, das Sie der SQL-Anweisung zuordnen möchten. Weitere Informationen dazu finden Sie in der Dokumentation zum QUERY_TAG-Parameter.

Typ: Zeichenfolge

Beispiel: tag-1234

statements_resultSetMetaData

statements_resultSetMetaData ist ein JSON-Objekt, das Sie verwenden, um Metadaten über das Resultset anzugeben, das zurückgegeben werden soll. Dieses Objekt sollte im Feld resultSetMetaData des POST-Anforderungstextes an den „/api/statements“-Endpunkt enthalten sein.

Felder

Feld

Beschreibung

format

(Optional) Format der Daten im Resultset. Derzeit wird nur der Wert json unterstützt.

Typ: Zeichenfolge

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

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

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/hello anfordert, das nicht existiert, gibt der Server diesen 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

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

Limit Exceeded (Grenzwert überschritten).

Die Anzahl der Anforderungen hat das Ratenlimit erreicht. Die Anwendung muss die Häufigkeit der an die API-Endpunkte gesendeten Anforderungen reduzieren.

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

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 Ergebnisseiten (z. B. zur ersten Seite, zur letzten Seite). Der Header kann mehrere URL-Einträge mit unterschiedlichen rel-Attributwerten enthalten, die die zurückzugebende Seite angeben (first, next, prev und last).

Beispiel:

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

Objekttypen im Anforderungstext

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/statements/536fad38-b564-4dc5-9892-a4543504df6c

Beispiel

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

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/statements/536fad38-b564-4dc5-9892-a4543504df6c

Beispiel

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

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/statements/536fad38-b564-4dc5-9892-a4543504df6c

Beispiel

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

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

Bemerkung

Wenn code auf 391908 gesetzt ist, siehe Feststellen, ob die Seitengröße des Resultsets den Grenzwert überschreitet.

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

  • Das erste Element in einer Zeile ist eine JSON-Zeichenfolge mit einer Sequenz-ID, die mit 0 beginnt.

  • Die restlichen Elemente in einer Zeile sind die eigentlichen Daten.

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

Typ: Array von Arrays

Beispiel:

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

**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

page

Die Nummer, die die aktuelle Ergebnisseite kennzeichnet.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 12

pageSize

Die Anzahl der Zeilen pro Seite. Dieses Feld ist nur gesetzt, wenn Sie den Parameter pageSize in der Anforderung angegeben haben.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 10

numPages

Die Anzahl der Ergebnisseiten.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 10

numRows

Die Gesamtzahl der Ergebniszeilen.

Typ: vorzeichenbehaftete 64-Bit-Ganzzahl

Beispiel: 100

format

Format der Daten im Resultset. Derzeit wird nur der Wert json unterstützt.

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

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
}

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