Verarbeiten von Antworten¶

Erläuterungen zum Ablauf der Ausführung¶

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

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.

• 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/v2/statements/statementHandle/cancel senden, wobei Sie das Anweisungshandle aus dem Feld statementHandle des QueryStatus-Objekts verwenden. Siehe Abbrechen der Ausführung einer 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 Endpunkt /api/v2/statements/ und hängen das Anweisungshandle als Pfadparameter an das Ende des URL-Pfads an: Weitere Informationen dazu finden Sie unter GET /api/v2/statements/{statementHandle}.

GET /api/v2/statements/{statementHandle}

Dabei ist {statementHandle} das Handle der Anweisung, 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/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
  }
  

  Copy

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

  Copy

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/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"

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.

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

Wie im obigen Flussdiagramm dargestellt:

• Wenn die Anweisung erfolgreich ausgeführt wurde, gibt Snowflake den HTTP-Antwortcode 200 und die Ergebniszeilen in einem ResultSet-Objekt zurück.

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

• Wenn die Ausführung der Anweisung noch nicht abgeschlossen ist, gibt Snowflake den HTTP-Antwortcode 202 mit einem QueryStatus-Objekt zurück.

  Verwenden Sie dieses Objekt, um den Ausführungsstatus der Anweisung zu überprüfen.

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

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.

Die Snowflake-API gibt Daten in Partitionen zurück. Snowflake bestimmt die Anzahl der Partitionen und die Größe der einzelnen Partitionen, die zurückgegeben werden. Die Größe einer Partition ist variabel und richtet sich nach der von Snowflake für eine bestimmte SQL-Abfrage zurückgegebenen Datenmenge.

Wenn Sie eine Anforderung übermitteln, enthält der Textkörper dieser Antwort ein partitionInfo-Feld. Dieses Feld enthält ein Array von Objekten, von denen jedes eine Datenpartition beschreibt. Dieses erste Objekt beschreibt die in dieser Antwort zurückgegebene Datenpartition. Die übrigen Objekte beschreiben die weiteren verfügbaren Partitionen, die Sie durch Übermitteln weiterer Anforderungen mit partition=partition_number abrufen können.

Jedes Objekt im Array gibt die Zeilenanzahl und die Größe einer Partition an. Ihre Anwendung kann diese Partitions-Metadaten verwenden, um zu bestimmen, wie die Partitionen zu behandeln sind, die bei nachfolgenden Anforderungen zurückgegeben werden.

Im Folgenden ist ein Beispiel für einen Teil der Antwort dargestellt:

{
  "code": "090001",
  "statementHandle": "536fad38-b564-4dc5-9892-a4543504df6c",
  "sqlState": "00000",
  "message": "successfully executed",
  "createdOn": 1597090533987,
  "statementStatusUrl": "/api/v2/statements/536fad38-b564-4dc5-9892-a4543504df6c",
  "resultSetMetaData" : {
    "numRows" : 50000,
    "format" : "jsonv2",
    "partitionInfo" : [ {
      "rowCount" : 12288,
      "uncompressedSize" : 124067,
      "compressedSize" : 29591
    }, {
      "rowCount" : 37712,
      "uncompressedSize" : 414841,
      "compressedSize" : 84469
    }],
  },
  "data": [
    ["customer1", "1234 A Avenue", "98765", "2021-01-20
    12:34:56.03459878"],
    ["customer2", "987 B Street", "98765", "2020-05-31
    01:15:43.765432134"],
    ["customer3", "8777 C Blvd", "98765", "2019-07-01
    23:12:55.123467865"],
    ["customer4", "64646 D Circle", "98765", "2021-08-03
    13:43:23.0"]
  ]
}

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 zum Resultset (z. B. das Format der Ergebnisse, die Anzahl der zurückgegebenen Partitionen usw.).

{
 "resultSetMetaData": {
  "numRows": 1300,
  "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
   }],
  "partitionInfo": [{
    ... // Partition metadata
  }]
 }
}

  {
    "resultSetMetaData": {
    "numRows: 103477,
    "format": "jsonv2"
    "rowType": {
      ... // Column metadata.
    },
    "partitionInfo": [{
        "rowCount": 12344,
        "uncompressedSize": 14384873,
      },{
        "rowCount": 47387,
        "uncompressedSize": 76483423,
        "compressedSize": 4342748
      },{
        "rowCount": 43746,
        "uncompressedSize": 43748274,
        "compressedSize": 746323
    }]
  },
  ...
}

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 aus einem Array von Zeichenfolgen in JSON. Beispiel:

{
  ...
  "data": [
    ["customer1", "1234 A Avenue", "98765", "2021-01-20 12:34:56.03459878"],
    ["customer2", "987 B Street", "98765", "2020-05-31 01:15:43.765432134"],
    ["customer3", "8777 C Blvd", "98765", "2019-07-01 23:12:55.123467865"],
    ["customer4", "64646 D Circle", "98765", "2021-08-03 13:43:23.0"]
  ],
  ...
}

Jedes Array innerhalb des Arrays enthält die Daten für eine Zeile. Die Elemente in jedem Array repräsentieren die Daten in einer Zeile.

Die Daten im Resultset sind in JSON kodiert, was bedeutet, dass alle Daten unabhängig vom Snowflake-Datentyp der Spalte als Zeichenfolge dargestellt 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 Zeichenfolge in den folgenden Formaten zurück (wenn in der POST-Übermittlungsanweisung kein Ausgabeformat-Parameter angegeben ist) abhängig vom Snowflake-Datentyp:

INT / NUMBER

Dezimalzahl in einer Zeichenfolge

FLOAT

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

VARCHAR

Zeichenfolge

BINARY

Hexadezimalzahl in einer Zeichenfolge

BOOLEAN

„false“ oder „true“ 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 Partitionen¶

Die Snowflake-SQL-API gibt Daten in Partitionen zurück. Die erste Partition wird im JSON-Format zurückgegeben und enthält Metadaten zu allen Partitionen, die für eine bestimmte Abfrage zurückgegeben werden. Ihre Anwendung kann diese Partitions-Metadaten verwenden, um zu bestimmen, wie die Partitionen zu behandeln sind, die bei nachfolgenden Anforderungen zurückgegeben werden.

Nachdem Sie die Antwort mit der ersten Datenpartition erhalten haben, können Sie die restlichen Partitionen abrufen, indem Sie Anforderungen mit partition=partition_number stellen, wobei partition_number die zurückzugebende Datenpartition angibt. Die Partitionsnummer 0 kennzeichnet die erste Datenpartition, die mit der ersten Anforderung zurückgegeben wird.

Nachdem Sie beispielsweise die erste Datenpartition erhalten haben, können Sie die zweite Datenpartition abrufen, indem Sie eine Anforderung mit dem Partitionsparameter 1 übermitteln:

GET /api/v2/statements/<handle>?partition=1

In der Antwort auf eine GET /api/v2/statements/<handle>?partition=partition_number-Anforderung enthält der Antworttext JSON-Daten in komprimierter Form (mit gzip).

Die Antwort enthält den HTTP-Header Content-Encoding: gzip, der anzeigt, dass der Antworttext komprimiert ist.

Diese Antworten enthalten keine Metadaten. Die Metadaten für alle Partitionen werden in der ersten Partition bereitgestellt.

Rückgabe von SQL NULL-Werten als Zeichenfolgen¶

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

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

Wenn diese Werte stattdessen als Zeichenfolge "null" zurückgegeben werden sollen, setzen Sie den Abfrageparameter nullable in der POST-Anforderung auf false, um die SQL-Anweisung zur Ausführung zu übermitteln. Beispiel:

POST /api/v2/statements?nullable=false

So werden SQL NULL-Werte als "null" zurückgegeben:

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

Formatieren der Ausgabe von Abfrageergebnissen¶

Die Snowflake-SQL-API unterstützt Parameter zur Formatierung der Ausgabe (z. B. Sitzungsparameter für Datum, Uhrzeit und Zeitstempel).

Beispielsweise wird ein DATE-Wert wie 2019-03-27 standardmäßig als „17982“ zurückgegeben (2019-03-27 ist 17.982 Tage nach der Epoche). Wenn Sie in der Anforderung angeben, dass DATE_OUTPUT_FORMAT „DD/MM/YY“ sein soll:

{
  "statement": "select date_column from mytable",
  "resultSetMetaData": {
    "format": "jsonv2",
  },
  "parameters": {
    "DATE_OUTPUT_FORMAT": "MM/DD/YYYY"
  }
  ...
}

Als DATE-Wert wird „27/03/2019“ zurückgegeben.

Im Anforderungstext können Sie im Feld parameters die folgenden Parameter einstellen, um das Ausgabeformat der Daten festzulegen:

• BINARY_OUTPUT_FORMAT

• DATE_OUTPUT_FORMAT

• TIME_OUTPUT_FORMAT

• TIMESTAMP_LTZ_OUTPUT_FORMAT

• TIMESTAMP_NTZ_OUTPUT_FORMAT

• TIMESTAMP_TZ_OUTPUT_FORMAT

• TIMESTAMP_OUTPUT_FORMAT

• TIMEZONE

Aufnehmen von Zeilennummern in das resultSet-Objekt¶

Zeilennummern werden im Resultset nicht zurückgegeben. Um Zeilennummern in die Antwort aufzunehmen, rufen Sie in Ihrer Abfrage die Fensterfunktion SEQUENCE oder ROW_NUMBER auf, mit denen die entsprechenden Zeilennummern generiert werden.