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

Einrichten der Anforderung¶

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

• Geben Sie eine Anforderungs-ID an, die diese Anforderung von anderen Anforderungen unterscheidet.

• Führen Sie die Anweisung asynchron aus.

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

  Copy

  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:

• jwt ist das für die Authentifizierung generierte JWT.

• myApplicationName ist ein Beispiel für einen Bezeichner für Ihre Anwendung.

• account_identifier ist Ihr Kontobezeichner.

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.

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.

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.