Query - Amazon Timestream
AnforderungssyntaxAnforderungsparameterAntwortsyntaxAntwortelementeFehlerWeitere Informationen finden Sie unter:

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Query

Queryist ein synchroner Vorgang, mit dem Sie eine Abfrage für Ihre Amazon Timestream Timestream-Daten ausführen können.

Wenn Sie diese Option aktiviert habenQueryInsights, werden API auch Erkenntnisse und Metriken zurückgegeben, die sich auf die von Ihnen ausgeführte Abfrage beziehen. QueryInsightshilft bei der Leistungsoptimierung Ihrer Abfrage. Weitere Informationen QueryInsights dazu finden Sie unter Verwenden von Abfrageerkenntnissen zur Optimierung von Abfragen in Amazon Timestream.

Anmerkung

Die maximale Anzahl von Query API Anfragen, die Sie bei QueryInsights aktivierter Option stellen dürfen, beträgt 1 Abfrage pro Sekunde (QPS). Wenn Sie diese Abfragerate überschreiten, kann dies zu einer Drosselung führen.

Querywird nach 60 Sekunden ein Timeout ausgelöst. Sie müssen das Standard-Timeout in der aktualisierenSDK, um ein Timeout von 60 Sekunden zu unterstützen. Einzelheiten finden Sie im Codebeispiel.

Ihre Abfrageanfrage schlägt in den folgenden Fällen fehl:

  • Wenn Sie eine Query Anfrage mit demselben Client-Token außerhalb des 5-minütigen Idempotenzfensters einreichen.

  • Wenn Sie innerhalb des 5-minütigen Idempotenzfensters eine Query Anfrage mit demselben Client-Token einreichen, aber andere Parameter ändern.

  • Wenn die Größe der Zeile (einschließlich der Abfrage-Metadaten) 1 MB überschreitet, schlägt die Abfrage fehl und die folgende Fehlermeldung wird angezeigt:

    Query aborted as max page response size has been exceeded by the output result row

  • Wenn der IAM Prinzipal des Abfrageinitiators und des Ergebnislesers nicht identisch sind und/oder der Abfrageinitiator und der Ergebnisleser nicht dieselbe Abfragezeichenfolge in den Abfrageanforderungen haben, schlägt die Abfrage mit einem Invalid pagination token Fehler fehl.

Anforderungssyntax

{
   "ClientToken": "string",
   "MaxRows": number,
   "NextToken": "string",
   "QueryInsights": { 
      "Mode": "string"
   },
   "QueryString": "string"
}

Anforderungsparameter

Informationen zu den Parametern, die alle Aktionen gemeinsam haben, finden Sie unter Allgemeine Parameter.

Die Anfrage akzeptiert die folgenden Daten im JSON Format.

ClientToken

Eindeutige, bei der Groß- und Kleinschreibung berücksichtigende Zeichenfolge mit bis zu 64 ASCII Zeichen, die bei der Query Anfrage angegeben wird. Die Angabe von a ClientToken macht den Aufruf Query idempotent. Das bedeutet, dass das wiederholte Ausführen derselben Abfrage zum gleichen Ergebnis führt. Mit anderen Worten, das Stellen mehrerer identischer Query Anfragen hat den gleichen Effekt wie das Stellen einer einzelnen Anfrage. Beachten Sie ClientToken bei der Verwendung in einer Abfrage Folgendes:

  • Wenn die Abfrage ohne a instanziiert API wirdClientToken, SDK generiert die Abfrage in ClientToken Ihrem Namen eine.

  • Wenn der Query Aufruf nur das, ClientToken aber kein A enthält, wird davon ausgegangenNextToken, dass es sich bei diesem Aufruf von um einen neuen Abfragelauf Query handelt.

  • Wenn der Aufruf enthältNextToken, wird davon ausgegangen, dass es sich bei diesem speziellen Aufruf um einen nachfolgenden Aufruf eines vorherigen Abfrageaufrufs handeltAPI, und es wird eine Ergebnismenge zurückgegeben.

  • Nach 4 Stunden ClientToken wird jede Anfrage mit demselben Inhalt wie eine neue Anfrage behandelt.

Typ: Zeichenfolge

Längenbeschränkungen: Mindestlänge von 32. Maximale Länge beträgt 128 Zeichen.

Erforderlich: Nein

MaxRows

Die Gesamtzahl der Zeilen, die in der Query Ausgabe zurückgegeben werden sollen. Bei der ersten Ausführung von Query mit einem angegebenen MaxRows Wert wird in zwei Fällen die Ergebnismenge der Abfrage zurückgegeben:

  • Die Größe des Ergebnisses ist kleiner als1MB.

  • Die Anzahl der Zeilen in der Ergebnismenge ist geringer als der Wert vonmaxRows.

Andernfalls gibt der erste Aufruf von Query only a zurückNextToken, das dann in nachfolgenden Aufrufen zum Abrufen der Ergebnismenge verwendet werden kann. Um die Paginierung fortzusetzen, geben Sie den NextToken Wert im nachfolgenden Befehl ein.

Wenn die Zeilengröße groß ist (z. B. eine Zeile hat viele Spalten), gibt Timestream möglicherweise weniger Zeilen zurück, um zu verhindern, dass die Antwortgröße die Grenze von 1 MB überschreitet. Wenn nicht MaxRows angegeben, sendet Timestream die erforderliche Anzahl von Zeilen, um das Limit von 1 MB einzuhalten.

Typ: Ganzzahl

Gültiger Bereich: Mindestwert 1. Maximaler Wert von 1 000.

Erforderlich: Nein

NextToken

Ein Paginierungstoken, das verwendet wird, um eine Reihe von Ergebnissen zurückzugeben. Wenn das mit aufgerufen Query API wird, wird davon ausgegangenNextToken, dass es sich bei diesem bestimmten Aufruf um einen nachfolgenden Aufruf eines vorherigen Aufrufs von handeltQuery, und es wird eine Ergebnismenge zurückgegeben. Wenn der Query Aufruf jedoch nur den enthält, Query wird davon ausgegangenClientToken, dass es sich bei diesem Aufruf von um einen neuen Abfragelauf handelt.

Beachten Sie bei der Verwendung NextToken in einer Abfrage Folgendes:

  • Ein Paginierungstoken kann für bis zu fünf Query Aufrufe ODER für eine Dauer von bis zu 1 Stunde verwendet werden — je nachdem, was zuerst eintritt.

  • Wenn Sie dasselbe verwenden, NextToken wird derselbe Satz von Datensätzen zurückgegeben. Um die Ergebnismenge weiterhin paginieren zu können, müssen Sie die neueste Version verwenden. nextToken

  • Angenommen, ein Query Aufruf gibt zwei NextToken Werte zurück, und. TokenA TokenB Wenn in einem nachfolgenden Query Aufruf verwendet TokenB wird, TokenA ist es ungültig und kann nicht wiederverwendet werden.

  • Um nach Beginn der Paginierung eine vorherige Ergebnismenge aus einer Abfrage anzufordern, müssen Sie die Abfrage erneut aufrufen. API

  • Die neueste Version NextToken sollte verwendet werden, um zu paginieren, bis sie zurückgegeben null wird. Ab diesem Zeitpunkt sollte eine neue NextToken Version verwendet werden.

  • Wenn der IAM Prinzipal des Abfrageinitiators und des Ergebnislesers nicht identisch sind und/oder der Abfrageinitiator und der Ergebnisleser nicht dieselbe Abfragezeichenfolge in den Abfrageanforderungen haben, schlägt die Abfrage mit einem Fehler fehl. Invalid pagination token

Typ: Zeichenfolge

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge beträgt 2048 Zeichen.

Erforderlich: Nein

QueryInsights

Kapselt Einstellungen für die Aktivierung. QueryInsights

Durch die Aktivierung werden zusätzlich zu den Abfrageergebnissen für die von Ihnen ausgeführte Abfrage auch Erkenntnisse und Metriken QueryInsights zurückgegeben. Sie können es verwendenQueryInsights, um Ihre Abfrageleistung zu optimieren.

Typ: QueryInsights Objekt

Erforderlich: Nein

QueryString

Die Abfrage, die von Timestream ausgeführt werden soll.

Typ: Zeichenfolge

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge von 262144.

Erforderlich: Ja

Antwortsyntax

{
   "ColumnInfo": [ 
      { 
         "Name": "string",
         "Type": { 
            "ArrayColumnInfo": "ColumnInfo",
            "RowColumnInfo": [ 
               "ColumnInfo"
            ],
            "ScalarType": "string",
            "TimeSeriesMeasureValueColumnInfo": "ColumnInfo"
         }
      }
   ],
   "NextToken": "string",
   "QueryId": "string",
   "QueryInsightsResponse": { 
      "OutputBytes": number,
      "OutputRows": number,
      "QuerySpatialCoverage": { 
         "Max": { 
            "PartitionKey": [ "string" ],
            "TableArn": "string",
            "Value": number
         }
      },
      "QueryTableCount": number,
      "QueryTemporalRange": { 
         "Max": { 
            "TableArn": "string",
            "Value": number
         }
      },
      "UnloadPartitionCount": number,
      "UnloadWrittenBytes": number,
      "UnloadWrittenRows": number
   },
   "QueryStatus": { 
      "CumulativeBytesMetered": number,
      "CumulativeBytesScanned": number,
      "ProgressPercentage": number
   },
   "Rows": [ 
      { 
         "Data": [ 
            { 
               "ArrayValue": [ 
                  "Datum"
               ],
               "NullValue": boolean,
               "RowValue": "Row",
               "ScalarValue": "string",
               "TimeSeriesValue": [ 
                  { 
                     "Time": "string",
                     "Value": "Datum"
                  }
               ]
            }
         ]
      }
   ]
}

Antwortelemente

Wenn die Aktion erfolgreich ist, sendet der Dienst eine HTTP 200-Antwort zurück.

Die folgenden Daten werden vom Dienst im JSON Format zurückgegeben.

ColumnInfo

Die Spaltendatentypen der zurückgegebenen Ergebnismenge.

Typ: Array von ColumnInfo-Objekten

NextToken

Ein Paginierungstoken, das bei einem Query Aufruf erneut verwendet werden kann, um die nächsten Ergebnisse abzurufen.

Typ: Zeichenfolge

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge beträgt 2048 Zeichen.

QueryId

Eine eindeutige ID für die angegebene Abfrage.

Typ: Zeichenfolge

Längenbeschränkungen: Minimale Länge beträgt 1 Zeichen. Maximale Länge beträgt 64 Zeichen.

Pattern: [a-zA-Z0-9]+

QueryInsightsResponse

QueryInsightsEnthält Erkenntnisse und Metriken zu der von Ihnen ausgeführten Abfrage.

Typ: QueryInsightsResponse Objekt

QueryStatus

Informationen zum Status der Abfrage, einschließlich des Fortschritts und der gescannten Byte.

Typ: QueryStatus Objekt

Rows

Die von der Abfrage zurückgegebenen Ergebnismengenzeilen.

Typ: Array von Row-Objekten

Fehler

Weitere Informationen zu den allgemeinen Fehlern, die bei allen Aktionen zurückgegeben werden, finden Sie unter Häufige Fehler.

AccessDeniedException

Sie sind nicht berechtigt, diese Aktion auszuführen.

HTTPStatuscode: 400

ConflictException

Die Ergebnisse für eine stornierte Abfrage konnten nicht abgefragt werden.

HTTPStatuscode: 400

InternalServerException

Der Dienst konnte diese Anfrage aufgrund eines internen Serverfehlers nicht vollständig verarbeiten.

HTTPStatuscode: 400

InvalidEndpointException

Der angeforderte Endpunkt war nicht gültig.

HTTPStatuscode: 400

QueryExecutionException

Timestream konnte die Abfrage nicht erfolgreich ausführen.

HTTPStatuscode: 400

ThrottlingException

Die Anforderung wurde aufgrund der Drosselung von Anforderungen abgelehnt.

HTTPStatuscode: 400

ValidationException

Ungültige oder falsch formatierte Anfrage.

HTTPStatuscode: 400

Weitere Informationen finden Sie unter:

Weitere Informationen zur Verwendung API in einer der sprachspezifischen Sprachen AWS SDKs finden Sie im Folgenden: