Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen

Unter diesem Thema wird erklärt, wie Sie eine Anforderung an die SQL-API übermitteln.

Unter diesem Thema:

Um SQL-Anweisungen zur Ausführung zu übermitteln, senden Sie eine POST-Anforderung an den Endpunkt /api/v2/statements/: Weitere Informationen dazu finden Sie unter POST /api/v2/statements.

POST /api/v2/statements HTTP/1.1
(request body)

Einrichten der Anforderung

In der Anforderungs-URL können Sie Abfrageparameter festlegen:

Legen Sie im Anforderungstext die folgenden Felder fest:

  • Legen Sie im Feld statement die SQL-Anweisung fest, die Sie ausführen möchten. Beispiel:

    {
      "statement": "select * from my_table",
      ...
    }
    

    Wenn Sie in einer Anweisung mehrere Anforderungen übermitteln möchten, verwenden Sie ein Semikolon (;) zwischen den Anweisungen. Weitere Informationen dazu finden Sie unter Übermitteln mehrerer SQL-Anweisungen in einer einzigen Anforderung.

  • Wenn Sie Bindungsvariablen (?-Platzhalter) in die Anweisung aufnehmen, legen Sie im Feld bindings ein Objekt fest, das die entsprechenden Snowflake-Datentypen und -Werte für jede Variable angibt.

    Weitere Details dazu finden Sie unter Verwenden von Bindungsvariablen in einer Anweisung.

  • Geben Sie in den Feldern warehouse, database, schema und role Werte für das zu verwendende Warehouse, die Datenbank, das Schema und die Rolle an.

    Bei den Werten in diesen Feldern wird zwischen Groß- und Kleinschreibung unterschieden.

    Wenn Sie diese Felder auslassen, verwendet die SQL-API die Werte der entsprechenden Eigenschaften des Benutzers (d. h. die Benutzereigenschaften des Benutzers DEFAULT_WAREHOUSE, DEFAULT_NAMESPACE und DEFAULT_ROLE).

  • Um ein Timeout für die Ausführung der Anweisung festzulegen, setzen Sie das Feld timeout auf die maximale Anzahl der zu wartenden Sekunden. Wenn das Feld timeout nicht gesetzt ist, wird das durch den Parameter STATEMENT_TIMEOUT_IN_SECONDS festgelegte Timeout verwendet.

Beispiel für eine Anforderung

Beispielsweise sendet der folgende curl-Befehl eine SQL-Anweisung zur Ausführung. Im Beispiel wird die Datei request-body.json verwendet, um den Anforderungstext anzugeben.

curl -i -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt>" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    -d "@request-body.json" \
    "https://<account_identifier>.snowflakecomputing.com/api/v2/statements"

Wobei:

In diesem Beispiel enthält request-body.json den Anforderungstext:

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

Im Anforderungstext des obigen Beispiels:

  • Das Feld statement gibt die auszuführende SQL-Anweisung an.

    Die Anweisung enthält eine Bindungsvariable (das Fragezeichen in "cl=?"), die auf die erste Bindung ("1") ausgewertet wird, die im Feld bindings angegeben ist.

  • Das Feld timeout gibt an, dass der Server 60 Sekunden für die Ausführung der Anweisung zulässt.

  • Die Felder database, schema, warehouse und role geben an, dass die Datenbank TESTDB, das Schema TESTSCHEMA, das Warehouse TESTWH und die Rolle TESTROLE bei der Ausführung der Anweisung verwendet werden sollen.

Übermitteln von Abfragen an URLs mit einem Kontonamen einer Organisation (nur OAuth)

Wenn Sie eine URL verwenden, die den Kontonamen einer Organisation angibt (z. B. myorganization-myaccount.snowflakecomputing.com), und Sie sich mit OAuth am Server authentifizieren, müssen Sie den Kontonamen in Ihrer POST-Anforderung über den Snowflake-Account-Header explizit angeben.

Bemerkung

Wenn Ihr Kontobezeichner eine Region enthält (z. B. xy12345.us-east-2.aws.snowflakecomputing.com), oder Sie sich nicht mit OAuth beim Server authentifizieren, müssen Sie den Snowflake-Account-Header nicht angeben.

Der folgende curl-Befehl zeigt, wie der Snowflake-Account-Header in einer POST-Anforderung angegeben wird:

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Agent: myApplicationName/1.0" \
  -H "X-Snowflake-Authorization-Token-Type: OAUTH" \
  -H "Snowflake-Account: xy12345" \
  --data '{"statement":"select 1", "timeout": 1000, "warehouse": "TESTWH", \
  "database": "TESTDB", "schema": "TESTSCHEMA", "role": "SYSADMIN"}' \
  "https://myorg-myaccount.snowflakecomputing.com:443/api/statements"

Im Snowflake-Account-Header kann kein Kontoalias angegeben werden.

Wenn Sie diesen Header in einer URL mit Kontonamen einer Organisation weglassen, oder wenn Sie den Kontoalias im Header angeben, gibt der Server den folgenden Fehler zurück:

HTTP/1.1 401 Unauthorized
{
  "code" : "390100",
  "message" : "Incorrect username or password was specified."
}

Verwenden von Bindungsvariablen in einer Anweisung

Wenn Sie Bindungsvariablen (? Platzhalter) in der Anweisung verwenden möchten, verwenden Sie das Feld bindings, um die Werte anzugeben, die eingefügt werden sollen.

Setzen Sie dieses Feld auf ein JSON-Objekt, das den Snowflake-Datentyp und den Wert für jede Bindungsvariable angibt.

...
"statement": "select * from T where c1=?",
...
"bindings": {
  "1": {
    "type": "FIXED",
    "value": "123"
  }
},
...

Wählen Sie den Datenbanktyp aus, der dem Typ des Wertes entspricht, den Sie binden möchten. Wenn der Wert beispielsweise eine Zeichenfolge ist, diese ein Datum darstellt (z. B. 2021-04-15), und Sie den Wert in eine DATE-Spalte einfügen möchten, verwenden Sie den Bindungstyp TEXT.

Die folgende Tabelle gibt die Werte des Feldes type an, die Sie zum Binden an verschiedene Snowflake-Datentypen für diese Vorschauversion verwenden können.

  • Die erste Spalte auf der linken Seite gibt die Bindungstypen an, die Sie verwenden können.

  • In den restlichen Spalten geben den Snowflake-Datentyp der Spalte an, in die Sie die Daten einfügen möchten.

  • Jede Zelle gibt den Typ des Wertes an, den Sie mit einem Bindungstyp verwenden können, um Daten in eine Spalte eines bestimmten Snowflake-Datentyps einzufügen.

    Wenn die Zelle für Bindungstyp und Snowflake-Datentyp leer ist, können Sie den angegebenen Bindungstyp nicht verwenden, um Daten in eine Spalte dieses Snowflake-Datentyps einzufügen.

Unterstützte Bindungstypen für verschiedene Snowflake-Datentypen

Snowflake-Datentypen

INT / NUMBER

FLOAT

VARCHAR

BINARY

BOOLEAN

DATE

TIME

TIMESTAMP_TZ

TIMESTAMP_LTZ

TIMESTAMP_NTZ

Bindungs- . typen

FIXED

Ganzzahl

Ganzzahl

Ganzzahl

0 (falsch) / ungleich Null (wahr)

REAL

Ganzzahl

Ganzzahl oder Gleitkomma

Ganzzahl oder Gleitkomma

0 / Nicht-0

TEXT

Ganzzahl

Ganzzahl oder Gleitkomma

beliebiger Text

Hexadezimal

"true"/ "false"

siehe Hinweise unten

siehe Hinweise unten

siehe Hinweise unten

siehe Hinweise unten

siehe Hinweise unten

BINARY

Hexadezimal

BOOLEAN

wahr/falsch, 0/1

wahr/falsch

DATE

Epoche (ms)

Epoche (ms)

Epoche (ms)

Epoche (ms)

Epoche (ms)

TIME

Epoche (nano)

Epoche (nano)

TIMESTAMP_TZ

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

TIMESTAMP_LTZ

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

TIMESTAMP_NTZ

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

Epoche (nano)

Beachten Sie Folgendes:

  • Die Werte der Bindungsvariablen müssen Zeichenfolgen sein (z. B. "1.0" für den Wert 1.0).

  • Wenn Sie den Bindungstyp DATE verwenden, geben Sie die Anzahl der Millisekunden seit der Epoche an.

  • Wenn Sie den Bindungstyp TIME oder TIMESTAMP* verwenden, geben Sie die Anzahl der Nanosekunden seit der Epoche an.

  • Wenn Sie den Bindungstyp TIMESTAMP_TZ verwenden, geben Sie die Anzahl der Nanosekunden seit der Epoche an, gefolgt von einem Leerzeichen und dem Zeitzonen-Offset in Minuten (z. B. 1616173619000000000 960).

  • Bei Verwendung des Bindungstyps TEXT:

    • Um Daten in eine DATE-Spalte einzufügen, können Sie jedes Datumsformat verwenden, das von der AUTO-Erkennung unterstützt wird.

    • Um Daten in eine TIME-Spalte einzufügen, können Sie jedes Zeitformat verwenden, das von der AUTO-Erkennung unterstützt wird.

    • Um Daten in eine TIMEZONE*-Spalte einzufügen, können Sie jedes Datum-Uhrzeit-Format verwenden, das von der AUTO-Erkennung unterstützt wird.

Wenn der Wert in einem Format vorliegt, das von Snowflake nicht unterstützt wird, gibt die API einen Fehler zurück:

{
  code: "100037",
  message: "<bind type> value '<value>' is not recognized",
  sqlState: "22018",
  statementHandle: "<ID>"
}

Übermitteln von gleichzeitigen Anforderungen

Die Snowflake-SQL-API unterstützt das Senden gleichzeitiger Anforderungen an den Server. Die Parallelitätseinschränkungen für die API werden durch die von Snowflake erzwungenen Parallelitätseinschränkungen bestimmt.

Je nach aktueller Serverauslastung können Sie eine HTTP 429-Fehlermeldung erhalten, die anzeigt, dass der Server derzeit zu viele Anforderungen erhält.

Um sicherzustellen, dass Ihre Anwendung die 429-Fehler korrekt verarbeitet, verwenden Sie bei gleichzeitigen Anforderungen eine Wiederholungslogik.

Erneutes Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen

In einigen Fällen ist es möglicherweise nicht klar, ob Snowflake die SQL-Anweisung in einer API-Anforderung ausgeführt hat (z. B. aufgrund eines Netzwerkfehlers oder eines Timeouts). Sie können die gleiche Anforderung erneut an Snowflake senden, falls Snowflake die Anweisung nicht ausgeführt hat.

Wenn Snowflake jedoch die Anweisung bereits in der ursprünglichen Anforderung ausgeführt hat und Sie die Anforderung erneut übermitteln, wird die Anweisung zweimal ausgeführt. Bei einigen Typen von Anforderungen kann das wiederholte Ausführen derselben Anweisung unbeabsichtigte Folgen haben (z. B. das Einfügen doppelter Daten in eine Tabelle).

Um zu verhindern, dass Snowflake bei einer erneuten Übermittlung dieselbe Anweisung zweimal ausführt, können Sie eine Anforderungs-ID verwenden, um Ihre Anforderung von anderen Anforderungen zu unterscheiden. Wenn Sie dieselbe Anforderungs-ID aus der ursprünglichen Anforderung zusammen mit dem Parameter retry=true auch in der erneut eingereichten Anforderung angeben, führt Snowflake die Anweisung nur dann erneut aus, wenn die Anweisung noch nicht erfolgreich ausgeführt wurde.

Um eine Anforderung-ID zu spezifizieren, generieren Sie einen universell eindeutigen Bezeichner (UUID). Sie können diesen Bezeichner dann in den Abfrageparameter requestId aufnehmen. Sie müssen auch den Parameter retry=true als Teil der Anforderung angeben, wie im folgenden Beispiel gezeigt.

POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1

Wenn Snowflake eine Anforderung nicht verarbeiten kann, können Sie dieselbe Anforderung erneut mit der gleichen Anforderungs-ID übermitteln. Die Verwendung der gleichen Anforderungs-ID zeigt dem Server an, dass Sie die gleiche Anforderung erneut übermitteln.

Bemerkung

Der Parameter retry=true erhöht den Aufwand für die Verarbeitung der SQL-Anweisung, da Snowflake eine Anweisung in der Anweisungshistorie suchen und abgleichen muss. Verwenden Sie diesen Parameter nur, wenn ein erneuter Versuch der Anweisung erforderlich ist.

Zurück zum Anfang