Para recursos semelhantes aos do Amazon Timestream para, considere o Amazon Timestream LiveAnalytics para InfluxDB. Ele oferece ingestão de dados simplificada e tempos de resposta de consulta de um dígito em milissegundos para análises em tempo real. Saiba mais [aqui](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html). As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Query `Query` é uma operação síncrona que permite que você execute uma consulta em seus dados do Amazon Timestream. Se você ativou `QueryInsights`, essa API também retornará informações e métricas relacionadas à consulta que você executou. `QueryInsights` ajuda no ajuste do desempenho de sua consulta. Para mais informações sobre `QueryInsights`, consulte [Uso de insights de consulta para otimizar consultas no Amazon Timestream](https://docs.aws.amazon.com/timestream/latest/developerguide/using-query-insights.html). **nota** O número máximo de solicitações de API `Query` que você pode fazer com o `QueryInsights` ativado é de 1 consulta por segundo (QPS). Se você exceder essa taxa de consulta, isso poderá resultar em um controle de utilização. `Query` atingirá o tempo limite após 60 segundos. Você deve atualizar o tempo limite padrão no SDK para suportar um tempo limite de 60 segundos. Consulte a [amostra de código](https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html) para obter detalhes. Sua solicitação de consulta falhará nos seguintes casos: + Se você enviar uma `Query` solicitação com o mesmo token de cliente fora da janela de idempotência de 5 minutos. + Se você enviar uma `Query` solicitação com o mesmo token de cliente, mas alterar outros parâmetros, dentro da janela de idempotência de 5 minutos. + Se o tamanho da linha (incluindo os metadados da consulta) exceder 1 MB, a consulta falhará com a seguinte mensagem de erro: `Query aborted as max page response size has been exceeded by the output result row` + Se o principal do IAM do iniciador da consulta e do leitor de resultados não forem os mesmos, and/or o iniciador da consulta e o leitor de resultados não tiverem a mesma string de consulta nas solicitações de consulta, a consulta falhará com um `Invalid pagination token` erro. ## Sintaxe da solicitação ``` { "ClientToken": "string", "MaxRows": number, "NextToken": "string", "QueryInsights": { "Mode": "string" }, "QueryString": "string" } ``` ## Parâmetros da solicitação Para obter informações sobre os parâmetros que são comuns em todas as ações, consulte [Parâmetros comuns](CommonParameters.md). A solicitação aceita os dados a seguir no formato JSON. ** [ClientToken](#API_query_Query_RequestSyntax) ** Sequência exclusiva, com distinção entre maiúsculas e minúsculas, de até 64 caracteres ASCII, especificada quando uma `Query` solicitação é feita. Fornecer um `ClientToken` torna a chamada `Query` *idempotente*. Isso significa que executar a mesma consulta repetidamente produzirá o mesmo resultado. Em outras palavras, fazer várias solicitações `Query` idênticas tem o mesmo efeito de se fazer uma única solicitação. Após o uso `ClientToken` em uma consulta, observe o seguinte: + Se a API de consulta for instanciada sem um `ClientToken`, o SDK de consulta gerará um `ClientToken` em seu nome. + Se a `Query` invocação contiver apenas o, `ClientToken` mas não incluir um`NextToken`, essa invocação de será `Query` considerada uma nova execução de consulta. + Se a invocação contiver `NextToken`, essa invocação específica será considerada uma invocação subsequente de uma chamada anterior para a API de consulta e um conjunto de resultados será retornado. + Após 4 horas, qualquer solicitação com a mesma `ClientToken` é tratada como uma nova solicitação. Tipo: string Restrições de comprimento: comprimento mínimo de 32. O comprimento máximo é 128. Obrigatório: não ** [MaxRows](#API_query_Query_RequestSyntax) ** O número total de itens para retornar na saída `Query`. A execução inicial de `Query` com um `MaxRows` valor especificado retornará o conjunto de resultados da consulta em dois casos: + O tamanho do resultado é menor que `1MB`. + O número de linhas no conjunto de resultados é menor que o valor de `maxRows`. Caso contrário, a invocação inicial de retorna `Query` apenas a `NextToken`, que pode ser usada em chamadas subsequentes para buscar o conjunto de resultados. Para retomar a paginação, forneça o valor `NextToken` no argumento de um comando subsequente. Se o tamanho da linha for grande (por exemplo, uma linha tem muitas colunas), o Timestream pode retornar menos linhas para evitar que o tamanho da resposta exceda o limite de 1 MB. Se não `MaxRows` for fornecido, o Timestream enviará o número necessário de linhas para atingir o limite de 1 MB. Tipo: inteiro Intervalo válido: valor mínimo de 1. Valor máximo de 1.000. Obrigatório: não ** [NextToken](#API_query_Query_RequestSyntax) ** Um token de paginação usado para retornar um conjunto de resultados. Quando a API `Query` é invocada usando `NextToken`, essa invocação específica é considerada uma invocação subsequente de uma chamada anterior para `Query`, e um conjunto de resultados é retornado. No entanto, se a `Query` invocação contiver apenas o `ClientToken`, essa invocação de será `Query` considerada uma nova consulta executada. Observe o seguinte ao usar NextToken em uma consulta: + Um token de paginação pode ser usado para até cinco `Query` invocações OU por uma duração de até 1 hora, o que ocorrer primeiro. + Usar o mesmo `NextToken` retornará o mesmo conjunto de registros. Para continuar paginando o conjunto de resultados, você deve usar o mais recente `nextToken`. + Suponha que uma `Query` invocação retorne dois `NextToken` valores, `TokenA` e `TokenB`. Se `TokenB` for usado em uma `Query` invocação subsequente, será invalidado e `TokenA` não poderá ser reutilizado. + Para solicitar um conjunto de resultados anterior de uma consulta após o início da paginação, você deve invocar novamente a API de consulta. + O último `NextToken` deve ser usado para paginar até `null` ser retornado, momento em que um novo `NextToken` deve ser usado. + Se o principal do IAM do iniciador da consulta e do leitor de resultados não forem os mesmos, and/or o iniciador da consulta e o leitor de resultados não tiverem a mesma string de consulta nas solicitações de consulta, a consulta falhará com um `Invalid pagination token` erro. Tipo: string Restrições de tamanho: tamanho mínimo 1. O comprimento máximo é 2.048. Obrigatório: não ** [QueryInsights](#API_query_Query_RequestSyntax) ** Encapsula as configurações para ativar o `QueryInsights`. A ativação `QueryInsights` retorna insights e métricas, além dos resultados da consulta que você executou. Você pode usar `QueryInsights` para ajustar o desempenho da consulta. Tipo: objeto [QueryInsights](API_query_QueryInsights.md) Obrigatório: não ** [QueryString](#API_query_Query_RequestSyntax) ** A consulta a ser executada pelo Timestream. Tipo: string Restrições de comprimento: tamanho mínimo de 1. O comprimento máximo é 262144. Obrigatório: sim ## Sintaxe da resposta ``` { "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" } ] } ] } ] } ``` ## Elementos de resposta Se a ação for bem-sucedida, o serviço retornará uma resposta HTTP 200. Os dados a seguir são retornados no formato JSON pelo serviço. ** [ColumnInfo](#API_query_Query_ResponseSyntax) ** Os tipos de dados da coluna do conjunto de resultados retornado. Tipo: matriz de objetos [ColumnInfo](API_query_ColumnInfo.md) ** [NextToken](#API_query_Query_ResponseSyntax) ** Um token de paginação que pode ser usado novamente em uma `Query` chamada para obter o próximo conjunto de resultados. Tipo: string Restrições de tamanho: tamanho mínimo 1. O comprimento máximo é 2.048. ** [QueryId](#API_query_Query_ResponseSyntax) ** Um ID exclusivo para a consulta em questão. Tipo: string Restrições de tamanho: tamanho mínimo 1. O comprimento máximo é 64. Padrão: `[a-zA-Z0-9]+` ** [QueryInsightsResponse](#API_query_Query_ResponseSyntax) ** Encapsulamentos `QueryInsights` contendo insights e métricas relacionadas à consulta que você executou. Tipo: objeto [QueryInsightsResponse](API_query_QueryInsightsResponse.md) ** [QueryStatus](#API_query_Query_ResponseSyntax) ** Informações sobre o status da consulta, incluindo progresso e bytes examinados. Tipo: objeto [QueryStatus](API_query_QueryStatus.md) ** [Rows](#API_query_Query_ResponseSyntax) ** As linhas do conjunto de resultados retornado pela consulta. Tipo: matriz de objetos [Row](API_query_Row.md) ## Erros Para informações sobre os erros comuns retornados pelas ações, consulte [Erros comuns](CommonErrors.md). ** AccessDeniedException ** Você não tem as permissões necessárias para acessar as configurações da conta. Código de status HTTP: 400 ** ConflictException ** Não é possível obter resultados de uma consulta cancelada. Código de status HTTP: 400 ** InternalServerException ** Ocorreu um erro interno ao processar a solicitação. Código de status HTTP: 400 ** InvalidEndpointException ** O endpoint solicitado é inválido. Código de status HTTP: 400 ** QueryExecutionException ** O Timestream não conseguiu executar a consulta com êxito. Código de status HTTP: 400 ** ThrottlingException ** A solicitação foi restringida devido ao excesso de solicitações. Código de status HTTP: 400 ** ValidationException ** Solicitação inválida ou malformada. Código de status HTTP: 400 ## Consulte também Para obter mais informações sobre como usar essa API em uma das linguagens específicas AWS SDKs, consulte o seguinte: + [AWS Interface de linha de comando V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS SDK para .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/timestream-query-2018-11-01/Query) + [AWS SDK para C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/timestream-query-2018-11-01/Query) + [AWS SDK para Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS SDK para Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/timestream-query-2018-11-01/Query) + [AWS SDK para JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/timestream-query-2018-11-01/Query) + [AWS SDK para Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/timestream-query-2018-11-01/Query) + [AWS SDK para PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS SDK para Python](https://docs.aws.amazon.com/goto/boto3/timestream-query-2018-11-01/Query) + [AWS SDK para Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/timestream-query-2018-11-01/Query)