Snowflake SQL-API: Änderungen am Prozess der Übermittlung von SQL-Anweisungen

Mit diesem Release werden Änderungen an der Snowflake-SQL-API eingeführt, die der Verbesserung der Verarbeitungseffizienz der SQL-API dienen.

Im Rahmen dieser Änderungen sind nun einige Funktionen veraltet, wie in folgenden Artikeln beschrieben:

Aktivieren der neuen SQL-API-Funktionalität

Um die neue SQL-API-Funktionalität für eine bestimmte Anforderung zu aktivieren, setzen Sie das Formatfeld für resultSetMetaData auf „jsonv2“, wie im folgenden Beispiel gezeigt:

{
  "statement": "select * from mytable",
  "resultSetMetaData": {
     "format": "jsonv2"
    },
  ...
 }
Copy

Wenn Sie die veraltete Funktionalität für die Verarbeitung von Ergebnissen verwenden möchten, lassen Sie das Feld resultSetMetaData weg, oder setzen Sie das Feld auf „json“.

  • Hinweis: In Zukunft verwendet die SQL-API diese neue Funktionalität standardmäßig. Sobald die SQL-API zur allgemeinen Verfügbarkeit freigegeben wird, wird die veraltete Funktionalität nicht mehr unterstützt.

Geänderte und veraltete Funktionalität

Die Snowflake-SQL-API gibt die Daten nicht mehr in Seiten gleicher Größe zurück. Stattdessen gibt die SQL-API Partitionen zurück, bei denen es sich um einzelne physische Blöcke von Daten handelt. Die Größe der einzelnen Partitionen ist variabel und wird von Snowflake zur Laufzeit automatisch bestimmt.

Folgende Änderungen wurden vorgenommen:

  • Sie können den nullwertfähigen Parameter nicht mehr in einer GET-Anforderung angeben. Der Parameter kann in einer POST-Anforderung nur angegeben werden, um eine SQL-Anweisung zur Ausführung zu übermitteln.

    Beispiel:

    POST /api/statements?nullable=false

  • Der Parameter pageSize ist veraltet. Snowflake gibt in jeder Antwort eine Datenpartition zurück, und Snowflake bestimmt die Größe der zurückgegebenen Partition. Die Größe einer Partition ist variabel und richtet sich nach der von Snowflake für eine bestimmte SQL-Abfrage zurückgegebenen Datenmenge.

  • Der Parameter „page“ wird durch den Parameter „partition“ ersetzt. Anstatt den Parameter „page“ zu verwenden, um die nächste Seite der zurückzugebenden Daten anzugeben, verwenden Sie den Parameter „partition“, um die nächste zurückzugebende Datenpartition anzugeben.

    Nachdem Sie die Antwort mit der ersten Datenpartition erhalten haben, können Sie die restlichen Partitionen abrufen, indem Sie Anforderungen mit „partion=<Partitionsnummer>“ stellen, wobei <Partitionsnummer> 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 auf 1 gesetzten Partitionsparameter übermitteln:

    GET /api/statements/<Handle>?partition=1

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

    Der Text dieser Antwort 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=<Partitionsnummer> 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:

     {
     "resultSetMetaData": {
      "numRows: 1300,
      "format": "jsonv2"
      "rowType": {
        ... // column metadata. No change
      },
      "partitionInfo": [{
          "rowCount": 12344,
          "uncompressedSize": 14384873,
        },{
          "rowCount": 47387,
          "uncompressedSize": 76483423,
          "compressedSize": 4342748
        },{
          "rowCount": 43746,
          "uncompressedSize": 43748274,
          "compressedSize": 746323
      }]
    },
    "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
  • In diesem Beispiel:

    • Das erste Objekt im Feld partitionInfo beschreibt die Datenpartition im Feld „data“ dieser Antwort.

    • Das zweite Objekt beschreibt die zweite Datenpartition, die 47.387 Zeilen enthält und die Sie durch Senden der Anforderung GET /api/statements/<Handle>?partition=1 abrufen können.

    • Das dritte Objekt beschreibt die dritte Datenpartition, die 47.386 Zeilen enthält und die Sie durch Senden der Anforderung GET /api/statements/<Handle>?partition=2 abrufen können.

  • Zusätzliche Partitionen werden im komprimierten Format zurückgegeben. In der Antwort auf eine GET /api/statements/<Handler>?partition=<Partitionsnummer>-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, nicht komprimierten Partition bereitgestellt.

  • Die veralteten Felder page, pageSize und numPages sind nicht mehr im resultSetMetaData-Objekt des Antworttextes enthalten.

    Mit der neuen Funktionalität gibt die SQL-API keine Daten mehr in Seitenform zurück. Stattdessen gibt die SQL-API Daten in Partitionen zurück, und Sie verwenden das Feld partitionInfo im Objekt resultSetMetaData, um die Anzahl der Partitionen und die Anzahl der Zeilen in jeder Partition zu ermitteln.

  • Im Resultset sind keine Zeilennummern mehr enthalten.

    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.

  • Boolesche Werte werden jetzt als „true“ oder „false“ zurückgegeben, anstatt als 1 oder 0.