Verarbeiten von Antworten

Unter diesem Thema wird erklärt, wie eine Antwort der SQL-API zu behandeln ist.

Unter diesem Thema:

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:

Ablaufplan für das Übermitteln einer Anweisung zur Ausführung

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

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

Wobei:

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

Ablaufplan für das Überprüfen des Status einer zur Ausführung übermittelten Anweisung

Wie im obigen Flussdiagramm dargestellt:

Abrufen der Ergebnisse aus der Antwort

Bemerkung

Snowflake, Version 5.40 führt unter anderem Änderungen in der Art und Weise ein, wie die von der Snowflake-SQL-API zurückgegebenen Daten behandelt werden.

In diesem Abschnitt wird beschrieben, wie die Ergebnisse in einer Antwort unter Verwendung neuerer Funktionen der Snowflake-SQL-API abgerufen werden können. Weitere Informationen zur Verwendung der älteren und nunmehr veralteten Funktionen finden Sie unter Veraltete Funktionalität.

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

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

Abrufen von Metadaten zu den im ResultSet-Objekt zurückgegebenen Spalten

Das Feld resultSetMetaData enthält Informationen zu den im ResultSet-Objekt zurückgegebenen Spalten.

Im Beispiel unten 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": {
  "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
  }]
 }
}
Copy

Abrufen von Metadaten zu den vom ResultSet-Objekt zurückgegebenen Partitionen

Wenn Sie eine Anforderung zur Ausführung einer Abfrage übermitteln, enthält die Antwort Metadaten, die beschreiben, wie die Daten auf die Antworten partitioniert sind, sowie die erste Datenpartition.

Das Feld resultSetMetaData enthält ein Feld partitionInfo. 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.

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

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

In diesem Beispiel beschreibt das erste Objekt im Feld partitionInfo die Datenpartition im Datenfeld dieser Antwort.

Das zweite Objekt beschreibt die zweite Datenpartition, die 47387 Zeilen enthält und die Sie durch Senden der Anforderung

GET /api/v2/statements/handle?partition=1.

Das dritte Objekt beschreibt die dritte Datenpartition, die 43.746 Zeilen enthält und die Sie durch Senden der Anforderung

GET /api/v2/statements/handle?partition=2.

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

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
Copy

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 ], ... ]
Copy

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
Copy

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

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

Bemerkung

Sie können den Parameter nullable nicht in GET-Anforderungen angeben, um den Anweisungsstatus zu prüfen.

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

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

Bemerkung

Snowflake ignoriert die Einstellungen auf Konto- und Benutzerebene für diese Parameter. Um das Format der Werte in den SQL-API-Ergebnissen zu ändern, müssen Sie diese Ausgabeparameter im Anforderungstext festlegen.

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.