Snowflake-SQL-API-Entwicklerhandbuch

In dieser Anleitung wird die Verwendung der Snowflake-SQL-API erläutert.

Unter diesem Thema:

Einführung

Die Snowflake-SQL-API ist eine REST-API, mit der Sie auf Daten in einer Snowflake-Datenbank zugreifen und diese aktualisieren können. Sie können diese API verwenden, um eigene Anwendungen und Integrationen für folgende Aufgaben zu entwickeln:

  • Ausführen von einfachen Abfragen

  • Verwalten Ihrer Implementierung (z. B. Bereitstellen von Benutzern und Rollen, Erstellen von Tabellen usw.)

Fähigkeiten und Möglichkeiten der SQL-API

Die Snowflake-SQL-API bietet Operationen, die Sie für Folgendes verwenden können:

  • Übermitteln von SQL-Anweisungen zur Ausführung

  • Überprüfen des Ausführungsstatus von Anweisungen

  • Abbrechen der Ausführung von Anweisungen

Sie können diese API verwenden, um Standardabfragen und die meisten DDL- und DML-Anweisungen auszuführen. Weitere Informationen zu Typen von Anweisungen, die nicht unterstützt werden, finden Sie unter Einschränkungen der SQL-API.

Die Ergebnisse von Abfragen können paginiert werden (z. B. Abrufen der Ergebnisse auf Seiten mit 10 Ergebnissen).

Der Endpunkt der SQL-API (/api/statements) ist durch die Netzwerkrichtlinien geschützt, die Sie zur Einschränkung des Zugriffs auf Ihr Konto eingerichtet haben.

Einschränkungen der SQL-API

Die SQL-API weist folgende Einschränkungen auf:

  • Die maximale Größe einer Ergebnisseite beträgt etwa 10 MB.

  • Die maximale Anzahl von Zeilen, die auf einer Ergebnisseite zurückgegeben werden, ist 10.000.

  • Der Dienst unterstützt derzeit nicht das gleichzeitige Abrufen von Ergebnissen (d. h. parallel mit mehreren Threads). Anforderungen werden nur von einem einzelnen Thread unterstützt.

  • Die folgenden Anweisungen werden nicht unterstützt:

    • PUT

    • GET

Verwenden der API

Die SQL-API ist unter https://Kontobezeichner.snowflakecomputing.com/api verfügbar, wobei Kontobezeichner Ihre Kontobezeichner ist.

Die API besteht aus der /api/statements/-Ressource und stellt die folgenden Endpunkte zur Verfügung:

Endpunkt

Beschreibung

/api/statements/

Verwenden Sie diesen Endpunkt für das Übermitteln von SQL-Anweisungen zur Ausführung.

/api/statements/statementHandle

Verwenden Sie diesen Endpunkt zum Prüfen des Ausführungsstatus einer Anweisung (statementHandle ist ein eindeutiger Bezeichner der zur Ausführung übergebenen Anweisung).

/api/statements/statementHandle/cancel

Verwenden Sie diesen Endpunkt zum Abbrechen der Ausführung einer Anweisung.

Sie können Entwicklungstools und Bibliotheken von REST-APIs (z. B. Postman) verwenden, um Anforderungen zu senden und Antworten zu verarbeiten.

Authentifizierung am Server

Wenn Sie eine Anforderung senden, muss diese Authentifizierungsinformationen enthalten. In den nächsten Abschnitten wird erläutert, wie Sie diese Informationen zur Anforderung hinzufügen:

Verwenden von OAuth

Um OAuth zu verwenden, führen Sie die folgenden Schritte aus:

  1. Richten Sie OAuth für die Authentifizierung ein.

    Weitere Informationen zum Einrichten von OAuth und Abrufen eines OAuth-Tokens finden Sie unter OAuth.

  2. Verwenden Sie SnowSQL, um zu überprüfen, ob Sie ein generiertes OAuth-Token für die Verbindung mit Snowflake verwenden können:

    $ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token=<oauth_token>
    
  3. Legen Sie in Ihrem Anwendungscode in jeder API-Anforderung, die Sie senden, die folgenden Header fest:

    • Authorization: Bearer Oauth-Token

      wobei Oauth-Token das generierte OAuth-Token ist.

    • X-Snowflake-Authorization-Token-Type: OAUTH

      Beachten Sie, dass Sie den Header X-Snowflake-Authorization-Token-Type auch weglassen können. Wenn dieser Header nicht vorhanden ist, nimmt Snowflake an, dass das Token im Authorization-Header ein OAuth-Token ist.

Verwenden der Schlüsselpaar-Authentifizierung

Um die Schlüsselpaar-Authentifizierung zu verwenden, führen Sie die folgenden Schritte aus:

  1. Richten Sie die Schlüsselpaar-Authentifizierung ein.

    Als Teil dieses Prozesses müssen Sie Folgendes tun:

    1. Generieren Sie ein öffentlich-privates Schlüsselpaar. Der generierte private Schlüssel muss sich in einer Datei befinden (z. B. mit dem Namen rsa_key.p8).

    2. Weisen Sie den öffentlichen Schlüssel Ihrem Snowflake-Benutzer zu. Nachdem Sie dem Benutzer den Schlüssel zugewiesen haben, führen Sie den Befehl DESCRIBE USER aus. In der Ausgabe muss die Eigenschaft RSA_PUBLIC_KEY_FP auf den Fingerabdruck des dem Benutzer zugewiesenen öffentlichen Schlüssels gesetzt sein.

    Eine Anleitung zum Generieren des Schlüsselpaars und zum Zuweisen eines Schlüssels an einen Benutzer finden Sie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

  2. Verwenden Sie SnowSQL, um zu überprüfen, ob Sie den generierten privaten Schlüssel verwenden können, um eine Verbindung zu Snowflake herzustellen:

    $ snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8
    

    Wenn Sie einen verschlüsselten privaten Schlüssel generiert haben, fordert SnowSQL Sie zur Eingabe der Passphrase auf, die Sie beim Generieren des Schlüssels erstellt haben.

  3. In Ihrem Anwendungscode:

    1. Generieren Sie den Fingerabdruck (einen SHA-256-Hash) des öffentlichen Schlüssels für den Benutzer. Stellen Sie dem Fingerabdruck das Präfix SHA256: voran. Beispiel:

      SHA256:Hash

      Ein Beispiel für das Generieren des Fingerabdrucks aus einer privaten Schlüsseldatei in Python finden Sie unter jwt-generator.

      Die folgenden Codeauszüge zeigen, wie der Fingerabdruck generiert wird.

      from cryptography.hazmat.primitives.serialization import load_pem_private_key
      from cryptography.hazmat.primitives.serialization import Encoding
      from cryptography.hazmat.primitives.serialization import PublicFormat
      from cryptography.hazmat.backends import default_backend
      ..
      import base64
      from getpass import getpass
      import hashlib
      ..
      # If you generated an encrypted private key, implement this method to return
      # the passphrase for decrypting your private key. As an example, this function
      # prompts the user for the passphrase.
      def get_private_key_passphrase():
          return getpass('Passphrase for private key: ')
      
      # Private key that you will load from the private key file.
      private_key = None
      
      # Open the private key file.
      # Replace <private_key_file_path> with the path to your private key file (e.g. /x/y/z/rsa_key.p8).
      with open('<private_key_file_path>', 'rb') as pem_in:
          pemlines = pem_in.read()
          try:
              # Try to access the private key without a passphrase.
              self.private_key = load_pem_private_key(pemlines, None, default_backend())
          except TypeError:
              # If that fails, provide the passphrase returned from get_private_key_passphrase().
              self.private_key = load_pem_private_key(pemlines, get_private_key_passphrase().encode(), default_backend())
      
      # Get the raw bytes of the public key.
      public_key_raw = private_key.public_key().public_bytes(Encoding.DER, PublicFormat.SubjectPublicKeyInfo)
      
      # Get the sha256 hash of the raw bytes.
      sha256hash = hashlib.sha256()
      sha256hash.update(public_key_raw)
      
      # Base64-encode the value and prepend the prefix 'SHA256:'.
      public_key_fp = 'SHA256:' + base64.b64encode(sha256hash.digest()).decode('utf-8')
      
    2. Generieren Sie ein JSON Web Token (JWT) mit den folgenden Feldern in der Nutzlast (Payload):

      Feld

      Beschreibung

      Beispiel

      iss

      Dies ist das Feld für den Aussteller des JWT. Setzen Sie dies auf den folgenden Wert:

      Kontobezeichner.Benutzer.Fingerabdruck_aus_öffentlichem_Schlüssel

      Wobei:

      • Kontobezeichner ist Ihr Snowflake-Kontobezeichner.

        Wenn Sie den Konto-Locator verwenden, schließen Sie alle Regionsinformationen aus dem Konto-Locator aus.

      • Benutzer ist Ihr Snowflake-Benutzername.

      • Fingerabdruck_aus_öffentlichem_Schlüssel ist der Fingerabdruck, den Sie im vorherigen Schritt generiert haben.

      MYACCOUNT.MYUSER.SHA256:Fingerabdruck_aus_öffentlichem_Schlüssel

      sub

      Dies ist das Feld für das Subjekt des JWT. Setzen Sie dies auf den folgenden Wert:

      Kontobezeichner.Benutzer

      MYORGANIZATION-MYACCOUNT.MYUSER

      iat

      Dies ist das Feld für den Zeitpunkt, zu dem das JWT ausgestellt wurde. Setzen Sie diesen auf die aktuelle Zeit (die Anzahl der Sekunden seit dem Beginn der Epoche in UTC).

      Hinweis: Verwenden Sie bei Auswahl der Ausführungszeit die Zeitzone Ihrer Snowflake-Bereitstellung.

      1615370644

      exp

      Dies ist das Feld für den Zeitpunkt, an dem das JWT abläuft. Setzen Sie dies auf die Ablaufzeit (die Anzahl der Sekunden seit dem Beginn der Epoche in UTC).

      Hinweis: Das JWT ist maximal eine Stunde nach Ausgabe des Tokens gültig, auch wenn Sie eine längere Ablaufzeit angeben.

      1615374184

      Ein Beispiel für die Generierung eines JWT in Python finden Sie unter jwt-generator.

      Die folgenden Codeauszüge zeigen, wie ein JWT generiert wird. Im Beispiel wird das PyJWT-Modul verwendet, das Sie installieren können, indem Sie Folgendes ausführen:

      pip install pyjwt
      
      from datetime import timedelta, timezone, datetime
      
      # This example relies on the PyJWT module (https://pypi.org/project/PyJWT/).
      import jwt
      
      # Construct the fully qualified name of the user in uppercase.
      # - Replace <account_identifier> with your account identifier.
      #   (See https://docs.snowflake.com/en/user-guide/admin-account-identifier.html .)
      # - Replace <user_name> with your Snowflake user name.
      account = "<account_identifier>"
      # Get the account identifier without the region, cloud provider, or subdomain.
      if not '.global' in account:
          idx = account.find('.')
          if idx > 0:
              account = account[0:idx]
          else:
              # Handle the replication case.
              idx = account.find('-')
              if idx > 0:
                  account = account[0:idx]
      # Use uppercase for the account identifier and user name.
      account = account.upper()
      user = "<user_name>".upper()
      qualified_username = account + "." + user
      
      # Get the current time in order to specify the time when the JWT was issued and the expiration time of the JWT.
      now = datetime.now(timezone.utc)
      # Specify the length of time during which the JWT will be valid. You can specify at most 1 hour.
      lifetime = timedelta(minutes=59)
      
      # Create the payload for the token.
      payload = {
          # Set the issuer to the fully qualified username concatenated with the public key fingerprint (calculated in the
          # previous step).
          "iss": qualified_username + '.' + public_key_fp,
      
          # Set the subject to the fully qualified username.
          "sub": qualified_username,
      
          # Set the issue time to now.
          "iat": now,
      
          # Set the expiration time, based on the lifetime specified for this object.
          "exp": now + lifetime
      }
      
      # Generate the JWT. private_key is the private key that you read from the private key file in the previous step when you
      # generated the public key fingerprint.
      encoding_algorithm="RS256"
      token = jwt.encode(payload, key=private_key, algorithm=encoding_algorithm)
      # If you are using a version of PyJWT prior to 2.0, jwt.encode returns a byte string, rather than a string.
      # If the token is a byte string, convert it to a string.
      if isinstance(token, bytes):
        token = token.decode('utf-8')
      decoded_token = jwt.decode(token, key=private_key.public_key(), algorithm=[encoding_algorithm])
      print("Generated a JWT with the following payload:\n{}".format(decoded_token))
      
    3. Legen Sie in jeder API-Anforderung, die Sie senden, die folgenden Header fest:

      • Authorization: Bearer JWT

        wobei JWT das Token ist, das Sie generiert haben.

      • X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

Zuweisen einer eindeutigen Anforderungs-ID für die erneute Übermittlung von Anforderungen

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 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 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 Anforderungs-ID zu spezifizieren, generieren Sie einen universell eindeutigen Bezeichner (UUID) und schließen diesen Bezeichner in den requestId-Abfrageparameter ein. Beispiel:

POST /api/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83 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.

Senden einer Anforderung zum Ausführen von SQL-Anweisungen

Um SQL-Anweisungen zur Ausführung zu übermitteln, senden Sie eine POST-Anforderung an den Endpunkt „/statements/“:

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

    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.

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

  • Wenn die Abfrage eine große Anzahl von Zeilen zurückgibt, legen Sie den Parameter pageSize fest. Andernfalls kann die Anzahl der Zeilen die Standardanzahl der Zeilen auf einer Seite überschreiten.

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 "Authorization: Bearer <jwt>" \
    -H "Content-Type: application/json" \
    -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/statements

Wobei:

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

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

Im obigen Beispiel:

  • In der Anforderungs-URL gibt der Anfrageparameter pageSize (&pageSize=10) an, dass das Resultset in jeder Antwort maximal 10 Zeilen enthalten soll.

  • Im Anforderungstext:

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

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

Verarbeitung der Antwort

Standardmäßig führt Snowflake die Anweisung synchron aus und gibt einen der im folgenden Flussdiagramm gezeigten Antwortcodes zurück:

Flow chart for submitting a statement for execution

Wie im obigen Flussdiagramm dargestellt:

  • Wenn Sie eine einzelne Anweisung übermittelt haben, die erfolgreich ausgeführt wurde, gibt Snowflake den HTTP-Antwortcode 200 und die Zeilen aus den Ergebnissen in einem ResultSet-Objekt zurück.

    Verwenden Sie das ResultSet-Objekt, um die Ergebnisse abzurufen.

    Beachten Sie, dass das Objekt höchstens die durch den Parameter pageSize angegebene Anzahl von Zeilen enthält. Wenn das Feld numRows in ResultSet_resultSetMetaData anzeigt, dass es zusätzliche Ergebniszeilen gibt, finden Sie unter Abrufen zusätzlicher Ergebnisseiten weitere Informationen.

  • Wenn Sie in einer Anforderung mehrere Anweisungen übermittelt haben, die erfolgreich ausgeführt wurden, gibt Snowflake den HTTP-Antwortcode 200 und ein ResultSet-Objekt zurück.

    Das ResultSet-Objekt enthält keine Zeilen aus den Ergebnissen. Stattdessen enthält das Feld data nur die Meldung „Multiple statements executed successfully“ (Mehrere Anweisungen erfolgreich ausgeführt).

    Zum Abrufen der Daten müssen Sie die Handles der einzelnen Anweisungen der Anforderung aus dem Feld statementHandles abrufen. Senden Sie für jedes Anweisungshandle eine Anforderung zum Prüfen des Ausführungsstatus der Anweisung. Siehe Prüfen des Ausführungsstatus der Anweisung und Abrufen der Daten.

    Weitere Informationen zur Verarbeitung der Antwort einer Anfrage, die mehrere SQL-Anweisungen angibt, finden Sie unter Abrufen der Ergebnisse jeder SQL-Anweisung in der Anforderung.

  • Wenn die Ausführung der Anweisung länger als 45 Sekunden dauert, oder wenn Sie angegeben haben, dass die Anweisung asynchron ausgeführt werden soll, gibt Snowflake den HTTP-Antwortcode 202 mit einem QueryStatus-Objekt zurück.

    Sie können eine Anforderung an den im Feld statementStatusUrl des QueryStatus-Objekts angegebenen Endpunkt senden, um den Status der Ausführung der Anweisung zu prüfen. Siehe Prüfen des Ausführungsstatus der Anweisung und Abrufen der Daten.

    Wenn Sie die Ausführung der Anweisung abbrechen möchten, können Sie eine Anfrage an das /api/statements/statementHandle/cancel senden, wobei Sie das Anweisungshandle aus dem Feld statementHandle des QueryStatus-Objekts verwenden. Siehe Abbrechen der Ausführung von SQL-Anweisungen.

Prüfen des Ausführungsstatus der Anweisung und Abrufen der Daten

In einigen Fällen müssen Sie eine Anforderung senden, um Ausführungsstatus einer Anweisung prüfen zu können:

  • Wenn Sie eine SQL-Anweisung zur Ausführung übermitteln und die Ausführung der Anweisung noch nicht abgeschlossen ist bzw. eine asynchrone Abfrage übermittelt wurde, gibt Snowflake einen 202-Antwortcode zurück.

    Um zu überprüfen, ob die Ausführung der Anweisung beendet ist, müssen Sie eine Anforderung zur Überprüfung des Status der Anweisung senden.

  • Wenn Sie in einer Anforderung mehrere SQL-Anweisungen übermitteln, erhalten Sie die Ergebnisse jeder einzelnen Anweisung, indem Sie eine Anforderung zur Überprüfung des Status der Anweisung senden.

In beiden Fällen senden Sie eine GET-Anforderung an den „/api/statements/“-Endpunkt und hängen das Anweisungshandle als Pfadparameter an das Ende des URL-Pfads an:

GET /api/statements/{statementHandle}

wobei {statementHandle} das Handle der Anweisung ist, die Sie prüfen möchten. So erhalten Sie das Anweisungshandle zu erhalten:

  • Wenn Sie eine Antwort mit Antwortcode 202 erhalten haben, enthält der Text der Antwort ein QueryStatus-Objekt. Sie können das Anweisungshandle aus dem Feld statementHandle dieses Objekts abrufen.

    Beachten Sie, dass Sie die vollständige URL der Anforderung auch dem Feld statementStatusUrl dieses Objekts entnehmen können.

    {
      "code": "090001",
      "sqlState": "00000",
      "message": "successfully executed",
      "statementHandle": "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
      "statementStatusUrl": "/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
    }
    
  • Wenn Sie eine Anforderung mit mehreren SQL-Anweisungen gesendet haben, enthält der Text der Antwort ein ResultSet-Objekt mit einem statementHandles-Feld. Aus diesem Feld können Sie die Handles für die einzelnen Anweisungen entnehmen.

    {
      ...
      "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
      ...
    

Mit dem folgenden curl-Befehl wird z. B. der Status der Anweisung mit dem Handle e4ce975e-f7ff-4b5e-b15e-bf25f59371ae geprüft:

curl -i -X GET \
    -H "Authorization: Bearer <jwt>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "User-Agent: myApplicationName/1.0" \
    -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
    https://<account_identifier>.snowflakecomputing.com/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae

Wobei:

Wenn Sie eine Anforderung zur Überprüfung des Status senden, gibt Snowflake eine der im folgenden Flussdiagramm gezeigten Antworten zurück:

Flow chart for checking the status of a statement submitted for execution

Wie im obigen Flussdiagramm dargestellt:

Abrufen der Ergebnisse aus der Antwort

Wenn Sie eine SQL-Anweisung zur Ausführung übermitteln oder den Ausführungsstatus der Anweisung überprüfen, gibt Snowflake bei erfolgreicher Ausführung der Anweisung ein ResultSet-Objekt im Antworttext zurück.

Es folgt ein Beispiel für ein ResultSet-Objekt, das für eine Abfrage zurückgegeben wird. Die Abfrage gibt an, dass die Ergebnisse mit 10 Zeilen pro Seite paginiert werden sollen. Das Feld numPages im resultSetMetaData-Objekt zeigt an, dass es 10 Seiten mit Ergebnissen gibt, und das Feld numRows zeigt an, dass die Abfrage insgesamt 100 Zeilen findet.

{
 "code": "090001",
 "statementHandle": "536fad38-b564-4dc5-9892-a4543504df6c",
 "sqlState": "00000",
 "message": "successfully executed",
 "createdOn": 1597090533987,
 "statementStatusUrl": "/api/statements/536fad38-b564-4dc5-9892-a4543504df6c",
 "resultSetMetaData": {
  "page": 1,
  "pageSize": 10,
  "numPages": 10,
  "numRows": 100,
  "format": "json",
  "rowType": [
   {
    "name":"ROWNUM",
    "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
   }
  ]
 },
 "data": [
  ["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"]
  ...
 ]
}

Feststellen, ob die Seitengröße des Resultsets den Grenzwert überschreitet

Die SQL-API kann eine Resultset-Seite zurückgeben, die eine maximale Größe von etwa 10 MB hat. Wenn die Resultset-Seite diese Größe überschreitet, gibt der Endpunkt eine HTTP-Antwort mit einer abgeschnittenen Ergebnismenge im Textkörper zurück, und das Feld code wird auf 391908 gesetzt:

HTTP/1.1 200 OK
...
{
  "code": "391908",
  ...

Wenn dies auftritt, senden Sie die Anforderung erneut, wobei der Parameter pageSize nun aber auf einen kleineren Wert eingestellt ist, der in die maximale Größe einer Seite passt.

Bemerkung

Derzeit gibt Snowflake in einem solchen Fall den HTTP-Antwortcode 200 zurück, aber dies kann sich künftig ändern.

Abrufen von Metadaten zu den Ergebnissen

Im ResultSet-Objekt, das in der Antwort zurückgegeben wird, enthält das Feld resultSetMetaData ein ResultSet_resultSetMetaData-Objekt mit Informationen über das Resultset (z. B. das Format der Ergebnisse, die Anzahl der Ergebnisseiten usw.).

Im folgenden Objekt enthält das rowType-Feld ein Array von ResultSet_resultSetMetaData_rowType-Objekten. Jedes Objekt beschreibt eine Spalte in den Ergebnissen. Das type-Feld gibt den Snowflake-Datentyp der Spalte an.

{
 "resultSetMetaData": {
  "rowType": [
   {
    "name":"ROWNUM",
    "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
   }
  ]
 },
}

Abrufen der Daten aus den Ergebnissen

Die Ergebnisse befinden sich im ResultSet-Objekt der Antwort im Feld data. Das data-Feld enthält ein Array von Arrays in JSON. Beispiel:

{
 "data": [
  ["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"]
 ],
}

Jedes Array innerhalb des Arrays enthält die Daten für eine Zeile:

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

  • Die restlichen Elemente in jedem Array stellen die Daten in einer Zeile dar.

Die Daten im Resultset sind in JSON v1.0 kodiert, was bedeutet, dass alle Daten unabhängig vom Snowflake-Datentyp der Spalte als Zeichenfolge ausgedrückt werden.

So wird zum Beispiel der Wert 1.0 in einer NUMBER-Spalte als Zeichenfolge "1.0" zurückgegeben. Als weiteres Beispiel werden Zeitstempel als die Anzahl der Nanosekunden seit der Epoche zurückgegeben. So wird zum Beispiel der Zeitstempel für Donnerstag, den 28. Januar 2021 10:09:37,123456789 PM als "1611871777123456789" zurückgegeben.

Die Konvertierung der Zeichenfolgen in die entsprechenden Datentypen liegt in Ihrer Verantwortung.

Snowflake gibt die Werte als Zeichenfolgen je nach Snowflake-Datentyp in den folgenden Formaten zurück:

INT / NUMBER

Dezimalzahl in einer Zeichenfolge

FLOAT

Ganzzahl (Integer) oder Gleitkommazahl (Float) in einer Zeichenfolge

VARCHAR

Zeichenfolge

BINARY

Hexadezimalzahl in einer Zeichenfolge

BOOLEAN

0 (falsch) oder 1 (wahr) in einer Zeichenfolge

DATE

Ganzzahliger Wert (in einer Zeichenfolge) der Anzahl der Tage seit der Epoche (z. B. 18262).

TIME, TIMESTAMP_LTZ, TIMESTAMP_NTZ

Gleitkommawert (mit 9 Dezimalstellen) der Anzahl der Sekunden seit der Epoche (z. B. 82919.000000000).

TIMESTAMP_TZ

Gleitkommawert (mit 9 Dezimalstellen) der Anzahl der Sekunden seit der Epoche, gefolgt von einem Leerzeichen und dem Zeitzonenoffset in Minuten (z. B. 1616173619000000000 960)

Abrufen zusätzlicher Ergebnisseiten

Wenn Sie den Anforderungsparameter pageSize zum Paginieren der Ergebnisse festlegen, gibt Snowflake die erste Seite der Ergebnisse aus der Antwort zurück. Sie können das Feld numPages des Objekts ResultSet_resultSetMetaData im Objekt ResultSet verwenden, um die Gesamtzahl der Ergebnisseiten zu ermitteln.

Um die nächste Ergebnisseite oder andere Ergebnisseiten zu erhalten, verwenden Sie die URLs, die im Link-Header der HTTP-Antwort angegeben sind. Der Link-Header gibt die URLs zum Abrufen der ersten, nächsten, vorherigen und letzten Seite der Ergebnisse an:

HTTP/1.1 200 OK
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-3b4d4f969840512c?page=0>;rel="first"
...

Jede URL im Header hat ein rel-Attribut mit einem der folgenden Werte:

  • first: Die erste Seite der Ergebnisse.

  • next: Die nächste Seite der Ergebnisse.

  • prev: Die vorherige Seite der Ergebnisse.

  • last: Die letzte Seite der Ergebnisse.

Übermitteln mehrerer SQL-Anweisungen in einer einzigen Anforderung

In einigen Fällen müssen Sie möglicherweise mehrere SQL-Anweisungen in einer Anforderung angeben. Das wäre in folgenden Beispielen der Fall:

  • Definieren einer explizite Transaktion

  • Erstellen einer gespeicherten Prozedur

  • Festlegen und Verwenden von Sitzungsvariablen in Anweisungen einer Anforderung

  • Erstellen und Verwenden von temporären Tabellen in Anweisungen einer Anforderung

  • Ändern der Datenbank, des Schemas, des Warehouses oder der Rolle für Anweisungen einer Anforderung

In den folgenden Abschnitten wird erläutert, wie Sie eine Anforderung übermitteln, die mehrere SQL-Anweisungen enthält.

Angeben mehrerer SQL-Anweisungen in der Anforderung

Wenn Sie in einer Anweisung mehrere SQL-Anforderungen übermitteln möchten, verwenden Sie ein Semikolon (;) zwischen jeder Anweisung. Beispiel:

POST /api/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "alter session set QUERY_TAG='mytesttag'; select count(*) from mytable",
  ...

Abrufen der Ergebnisse jeder SQL-Anweisung in der Anforderung

Wenn eine Anforderung, die mehrere SQL-Anweisungen enthält, erfolgreich ausgeführt wurde, dann enthält die Antwort nicht die Daten, die bei der Ausführung der einzelnen Anweisungen zurückgegeben werden. Die Antwort enthält stattdessen ein statementHandles-Feld, das wiederum ein Array mit den Handles für jede einzelne Anweisung enthält.

Bemerkung

Das Feld statementHandles unterscheidet sich vom Feld statementHandle:

  • Das Feld statementHandle gibt das Handle für den Satz von SQL-Anweisungen in der Anforderung an.

  • Das Feld statementHandles ist ein Array, das die Handles jeder einzelnen SQL-Anweisungen in der Anforderung enthält.

Beispiel: Angenommen, Sie senden eine Anforderung, die zwei SQL-Anweisungen zur Ausführung angibt:

POST /api/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

{
  "statement": "select * from A; select * from B",
  ...

Die Antwort enthält ein statementHandles-Feld, das wiederum ein Array mit den Handles für jede einzelne Anweisung enthält.

HTTP/1.1 200 OK
...
{
  ...
  "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
  ...

Um den Status zu prüfen und die Daten für die einzelnen Anweisungen abzurufen, senden Sie eine GET-Anforderung an den /statements/-Endpunkt und hängen das Handle der jeweiligen Anweisung an den URL-Pfad an:

GET /api/statements/019c9fce-0502-f1fc-0000-438300e02412
...
GET /api/statements/019c9fce-0502-f1fc-0000-438300e02416
...

Behandeln von Fehlern bei der Angabe mehrerer Anweisungen in einer Anforderung

Wenn Sie mehrere SQL-Anweisungen in der Anforderung angegeben haben und bei Ausführung einer der Anweisungen ein Fehler aufgetreten ist, gibt Snowflake den HTTP-Antwortcode 422 mit einem QueryFailureStatus-Objekt zurück.

Sie können Details zum aufgetretenen Fehler aus diesem Objekt abrufen.

Angenommen, Ihre Anforderungen enthält die folgenden Anweisungen, bei denen die zweite INSERT-Anweisung einen Fehler enthält:

{
  "statement": "create or replace table table1 (i int); insert into table1 (i) values (1); insert into table1 (i) values ('This is not a valid integer.'); insert into table1 (i) values (2); select i from table1 order by i",
  ...

Snowflake gibt eine Antwort mit HTTP-Antwortcode 422 und mit einem QueryFailureStatus-Objekt zurück, das die Details zum Fehler enthält:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...
{
  "code" : "100132",
  "message" : "JavaScript execution error: Uncaught Execution of multiple statements failed on statement \"insert into table1 (i) values ...\" (at line 1, position 75).\nNumeric value 'This is not a valid integer.' is not recognized in SYSTEM$MULTISTMT at '    throw `Execution of multiple statements failed on statement {0} (at line {1}, position {2}).`.replace('{1}', LINES[i])' position 4\nstackstrace: \nSYSTEM$MULTISTMT line: 10",
  "sqlState" : "P0000",
  "statementHandle" : "019d6e97-0502-317e-0000-096d0041f036"
}

Im obigen Beispiel beginnt die INSERT-Anweisung mit dem Fehler an der Zeichenposition 75 im Wert des Feldes statement.

Die Anweisungen vor der fehlerhaften Anweisung werden erfolgreich ausgeführt (die CREATE TABLE- und die erste INSERT-Anweisung in diesem Beispiel). Die Anweisungen nach der fehlerhaften Anweisung werden nicht ausgeführt.

Erstellen und Aufrufen von gespeicherten Prozeduren

Sie können die SQL-API verwenden, um gespeicherte Prozeduren zu erstellen und aufzurufen. Das folgende Beispiel zeigt den Text einer POST-Anforderung, der eine neue gespeicherte Prozedur erstellt, die den Namen einer Tabelle übergibt und die Anzahl der Zeilen in dieser Tabelle zurückgibt:

{
  "statement": "create or replace procedure sql_api_stored_proc(table_name varchar) returns varchar language javascript as $$var sql_command = \"select count(*) from \" + TABLE_NAME; var rs = snowflake.execute({sqlText: sql_command}); rs.next(); var rowCount = rs.getColumnValue(1); return rowCount; $$;",
  "resultSetMetaData": {
    "format": "json"
  },
  "role": "MY_ROLE",
  "warehouse": "MY_WAREHOUSE",
  "database": "MY_DB",
  "schema": "MY_SCHEMA"
}

Das folgende Beispiel zeigt den Text zur Antwort dieser Anforderung:

{
  "resultSetMetaData": {
    "page": 0,
    "numPages": 1,
    "numRows": 1,
    "format": "json",
    "rowType": [ {
      "name": "status",
      "database": "",
      "schema": "",
      "table": "",
      "type": "text",
      "byteLength": 16777216,
      "scale": null,
      "precision": null,
      "nullable": true,
      "collation": null,
      "length": 16777216
    } ]
  },
  "data": [ [ "0", "Function SQL_API_STORED_PROC successfully created." ] ],
  "code": "090001",
  "statementStatusUrl": "/api/statements/019c9f28-0502-f257-0000-438300e0a02a?requestId=...",
  "sqlState": "00000",
  "statementHandle": "019c9f28-0502-f257-0000-438300e0a02a",
  "message": "Statement executed successfully.",
  "createdOn": 1622494569592
}

Es folgt ein Beispiel für den Text einer POST-Anforderung, der die gespeicherte Prozedur aufruft und den Tabellennamen „prices“ übergibt:

{
  "statement": "call sql_api_stored_proc('prices');",
  "resultSetMetaData": {
    "format": "json"
  },
  "role": "MY_ROLE",
  "warehouse": "MY_WAREHOUSE",
  "database": "MY_DB",
  "schema": "MY_SCHEMA"
}

Das folgende Beispiel zeigt den Text zur Antwort dieser Anforderung:

{
  "resultSetMetaData": {
    "page": 0,
    "numPages": 1,
    "numRows": 1,
    "format": "json",
    "rowType": [ {
      "name": "SQL_API_STORED_PROC",
      "database": "",
      "schema": "",
      "table": "",
      "type": "text",
      "byteLength": 16777216,
      "length": 16777216,
      "scale": null,
      "precision": null,
      "nullable": true,
      "collation": null
    } ]
  },
  "data": [ [ "0", "4" ] ],
  "code": "090001",
  "statementStatusUrl": "/api/statements/019c9f2a-0502-f244-0000-438300e04496?requestId=...",
  "sqlState": "00000",
  "statementHandle": "019c9f2a-0502-f244-0000-438300e04496",
  "message": "Statement executed successfully.",
  "createdOn": 1622494718694
}

Verwenden expliziter Transaktionen

Zur Ausführung von SQL-Anweisungen in einer expliziten Transaktion müssen Sie eine einzelne HTTP-Anforderung verwenden, um den Start, das Ende und die Anweisungen der Transaktion anzugeben. Beispiel:

{
  "statement": "begin transaction; insert into table2 (i) values (1); commit; select i from table1 order by i",
  ...

Wie bei der Angabe von mehreren Anweisungen in einer Anforderung gibt Snowflake bei erfolgreicher Verarbeitung der Anforderung eine Antwort zurück, die das Feld statementHandles enthält, das auf ein Array von Handles für die Anweisungen in der Anforderung (einschließlich der Anweisungen BEGIN TRANSACTION und COMMIT) gesetzt ist.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resultSetMetaData" : {
    "page" : 0,
    "numPages" : 1,
    "numRows" : 1,
    "format" : "json",
    "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "byteLength" : 16777216,
      "scale" : null,
      "precision" : null,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ]
  },
  "data" : [ [ "0", "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "019d6ed0-0502-3101-0000-096d00421082", "019d6ed0-0502-3101-0000-096d00421086", "019d6ed0-0502-3101-0000-096d0042108a", "019d6ed0-0502-3101-0000-096d0042108e" ],
  "statementStatusUrl" : "/api/statements/019d6ed0-0502-3101-0000-096d0042107e?requestId=066920fa-e589-43c6-8cca-9dcb2d4be978",
  "sqlState" : "00000",
  "statementHandle" : "019d6ed0-0502-3101-0000-096d0042107e",
  "message" : "Statement executed successfully.",
  "createdOn" : 1625684162876
}

Die Handles im Feld statementHandles entsprechen den Anweisungen in der Anforderung. In diesem Beispiel sind die Anweisungen mit den entsprechenden Handles wie folgt:

  • BEGIN TRANSACTION (019d6ed0-0502-3101-0000-096d00421082)

  • INSERT (019d6ed0-0502-3101-0000-096d00421086)

  • COMMIT (019d6ed0-0502-3101-0000-096d0042108a)

  • SELECT (019d6ed0-0502-3101-0000-096d0042108e)

Sie können diese Handles verwenden, um den Status jeder Anweisung zu überprüfen.

Abrufen von Details zu einem Fehler

Wenn die Anweisung nicht erfolgreich ausgeführt wird, gibt Snowflake einen der folgenden Antwortcodes zurück, wie im folgenden Flussdiagramm dargestellt:

Flow chart for handling errors during statement execution

Wie im folgenden Flussdiagramm dargestellt:

  • Wenn die Ausführung der Anweisung länger dauert als die durch das Feld timeout in der Anforderung angegebene Timeout-Zeit (oder die durch den Parameter STATEMENT_TIMEOUT_IN_SECONDS angegebene Timeout-Zeit, wenn im Feld timeout kein Wert angegeben ist), gibt Snowflake den HTTP-Antwortcode 408 mit einem QueryStatus-Objekt zurück.

    Verwenden Sie dieses Objekt, um Details zum Abbruch der Anweisungsausführung zu erhalten.

  • Wenn bei der Ausführung der Anweisung ein Fehler aufgetreten ist, gibt Snowflake den HTTP-Antwortcode 422 mit einem QueryFailureStatus-Objekt zurück.

    Sie können Details zum aufgetretenen Fehler aus diesem Objekt abrufen.

Abbrechen der Ausführung von SQL-Anweisungen

Um die Ausführung einer Anweisung abzubrechen, senden Sie eine POST-Anforderung an den „cancel“-Endpunkt.

POST /api/statements/{statementHandle}/cancel

Das folgende Flussdiagramm veranschaulicht die Schritte, die Sie zum Abbrechen einer Anforderung ausführen müssen.

Flow chart for cancelling the execution of a statement