Query - Amazon Timestream
Syntaxe de la requêteParamètres de demandeSyntaxe de la réponseEléments de réponseErreursconsultez aussi

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Query

Queryest une opération synchrone qui vous permet d'exécuter une requête sur vos données Amazon Timestream.

Si vous l'avez activéQueryInsights, cela renvoie API également des informations et des mesures relatives à la requête que vous avez exécutée. QueryInsightsaide à optimiser les performances de votre requête. Pour en savoir plusQueryInsights, consultez la section Utilisation des informations relatives aux requêtes pour optimiser les requêtes dans Amazon Timestream.

Note

Le nombre maximum de Query API demandes que vous êtes autorisé à effectuer lorsque QueryInsights cette option est activée est d'une requête par seconde (QPS). Si vous dépassez ce taux de requêtes, cela peut entraîner un ralentissement.

Queryexpirera au bout de 60 secondes. Vous devez mettre à jour le délai d'expiration par défaut dans le SDK pour prendre en charge un délai d'attente de 60 secondes. Consultez l'exemple de code pour plus de détails.

Votre demande de requête échouera dans les cas suivants :

  • Si vous soumettez une Query demande avec le même jeton client en dehors de la fenêtre d'idempuissance de 5 minutes.

  • Si vous soumettez une Query demande avec le même jeton client, mais que vous modifiez d'autres paramètres, dans le délai d'idempotentie de 5 minutes.

  • Si la taille de la ligne (y compris les métadonnées de la requête) dépasse 1 Mo, la requête échouera avec le message d'erreur suivant :

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

  • Si le IAM principal de l'initiateur de requête et le lecteur de résultats ne sont pas identiques et/ou si l'initiateur de requête et le lecteur de résultats n'ont pas la même chaîne de requête dans les demandes de requête, la requête échouera avec une Invalid pagination token erreur.

Syntaxe de la requête

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

Paramètres de demande

Pour plus d'informations sur les paramètres courants pour toutes les actions, consultez Paramètres courants.

La demande accepte le JSON format des données suivantes.

ClientToken

Chaîne unique distinguant majuscules et minuscules de 64 ASCII caractères maximum spécifiée lorsqu'une Query demande est faite. Fournir un ClientToken fait passer l'appel à Query idempotent. Cela signifie que l'exécution répétée de la même requête produira le même résultat. En d'autres termes, le fait de faire plusieurs Query demandes identiques a le même effet qu'une seule demande. Lorsque vous l'utilisez ClientToken dans une requête, notez les points suivants :

  • Si la requête API est instanciée sans aClientToken, elle en SDK génère un en votre ClientToken nom.

  • Si l'Queryinvocation ne contient que le ClientToken mais n'inclut pas unNextToken, cet appel de Query est supposé être une nouvelle requête exécutée.

  • Si l'invocation contientNextToken, cette invocation particulière est supposée être une invocation ultérieure d'un appel antérieur à la requêteAPI, et un ensemble de résultats est renvoyé.

  • Après 4 heures, toute demande contenant la même chose ClientToken est traitée comme une nouvelle demande.

Type : String

Contraintes de longueur : longueur minimale de 32. Longueur maximale de 128.

Obligatoire : non

MaxRows

Le nombre total de lignes à renvoyer dans la Query sortie. L'exécution initiale de Query avec une MaxRows valeur spécifiée renverra le jeu de résultats de la requête dans deux cas :

  • La taille du résultat est inférieure à1MB.

  • Le nombre de lignes du jeu de résultats est inférieur à la valeur demaxRows.

Sinon, l'appel initial de renvoie Query uniquement aNextToken, qui peut ensuite être utilisé lors des appels suivants pour récupérer le jeu de résultats. Pour reprendre la pagination, entrez la NextToken valeur dans la commande suivante.

Si la taille de la ligne est grande (par exemple, une ligne comporte de nombreuses colonnes), Timestream peut renvoyer moins de lignes afin d'empêcher la taille de réponse de dépasser la limite de 1 Mo. Si MaxRows ce n'est pas le cas, Timestream enverra le nombre de lignes nécessaire pour respecter la limite de 1 Mo.

Type : entier

Plage valide : valeur minimum de 1. La valeur maximale est 1 000.

Obligatoire : non

NextToken

Un jeton de pagination utilisé pour renvoyer un ensemble de résultats. Lorsque le Query API est invoqué en utilisantNextToken, cet appel particulier est supposé être une invocation ultérieure d'un appel précédent àQuery, et un ensemble de résultats est renvoyé. Toutefois, si l'Queryinvocation ne contient que leClientToken, cette invocation de Query est supposée être une nouvelle requête exécutée.

Notez les points suivants lors de l'utilisation NextToken dans une requête :

  • Un jeton de pagination peut être utilisé pour un maximum de cinq Query invocations, OU pour une durée maximale d'une heure, selon la première éventualité.

  • L'utilisation de la même option NextToken renverra le même ensemble d'enregistrements. Pour continuer à paginer dans le jeu de résultats, vous devez utiliser le plus récent. nextToken

  • Supposons qu'Queryun appel renvoie deux NextToken valeurs, TokenA etTokenB. S'il TokenB est utilisé lors d'un appel ultérieur, Query il TokenA est alors invalidé et ne peut pas être réutilisé.

  • Pour demander un ensemble de résultats antérieur à partir d'une requête après le début de la pagination, vous devez réinvoquer la requête. API

  • La dernière NextToken doit être utilisée pour paginer jusqu'à ce qu'elle null soit renvoyée, après quoi une nouvelle NextToken doit être utilisée.

  • Si le IAM principal de l'initiateur de requête et le lecteur de résultats ne sont pas identiques et/ou si l'initiateur de requête et le lecteur de résultats n'ont pas la même chaîne de requête dans les demandes de requête, la requête échouera avec une Invalid pagination token erreur.

Type : String

Contraintes de longueur : longueur minimum de 1. Longueur maximale de 2048.

Obligatoire : non

QueryInsights

Encapsule les paramètres à activerQueryInsights.

L'activation QueryInsights renvoie des informations et des métriques en plus des résultats de requête pour la requête que vous avez exécutée. Vous pouvez l'utiliser QueryInsights pour optimiser les performances de vos requêtes.

Type : objet QueryInsights

Obligatoire : non

QueryString

Requête à exécuter par Timestream.

Type : String

Contraintes de longueur : longueur minimum de 1. Longueur maximum de 262 144.

Obligatoire : oui

Syntaxe de la réponse

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

Eléments de réponse

Si l'action aboutit, le service renvoie une réponse HTTP 200.

Les données suivantes sont renvoyées sous JSON forme formatée par le service.

ColumnInfo

Les types de données de colonne du jeu de résultats renvoyé.

Type : tableau d’objets ColumnInfo

NextToken

Un jeton de pagination qui peut être réutilisé lors d'un Query appel pour obtenir la prochaine série de résultats.

Type : String

Contraintes de longueur : longueur minimum de 1. Longueur maximale de 2048.

QueryId

Un identifiant unique pour la requête donnée.

Type : String

Contraintes de longueur : longueur minimum de 1. Longueur maximale de 64.

Modèle : [a-zA-Z0-9]+

QueryInsightsResponse

Encapsule QueryInsights contenant des informations et des mesures relatives à la requête que vous avez exécutée.

Type : objet QueryInsightsResponse

QueryStatus

Informations sur l'état de la requête, y compris la progression et les octets analysés.

Type : objet QueryStatus

Rows

Les lignes du jeu de résultats renvoyées par la requête.

Type : tableau d’objets Row

Erreurs

Pour plus d'informations sur les erreurs courantes pour toutes les actions, consultez Erreurs courantes.

AccessDeniedException

Vous n'êtes pas autorisé à effectuer cette action.

HTTPCode de statut : 400

ConflictException

Impossible d'interroger les résultats d'une requête annulée.

HTTPCode de statut : 400

InternalServerException

Le service n'a pas pu traiter complètement cette demande en raison d'une erreur interne du serveur.

HTTPCode de statut : 400

InvalidEndpointException

Le point de terminaison demandé n'était pas valide.

HTTPCode de statut : 400

QueryExecutionException

Timestream n'a pas pu exécuter correctement la requête.

HTTPCode de statut : 400

ThrottlingException

La demande a été refusée suite à une limitation des demandes.

HTTPCode de statut : 400

ValidationException

Demande non valide ou mal formée.

HTTPCode de statut : 400

consultez aussi

Pour plus d'informations sur son utilisation API dans l'une des langues spécifiques AWS SDKs, consultez ce qui suit :