Sintaxe da solicitação Parâmetros da solicitação Sintaxe da resposta Elementos de resposta Erros Consulte também

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.

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 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 a entidade principal do IAM do iniciador da consulta e do leitor de resultados não forem os mesmos e/ou 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.

A solicitação aceita os dados a seguir no formato JSON.

ClientToken

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 umNextToken, 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 o mesmo ClientToken será tratada como uma nova solicitação.

Tipo: string

Restrições de tamanho: tamanho mínimo de 32. O tamanho máximo é 128.

Obrigatório: não

MaxRows

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

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 a entidade principal do IAM do iniciador da consulta e do leitor de resultados não forem os mesmos e/ou 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 erro Invalid pagination token.

Tipo: string

Restrições de tamanho: tamanho mínimo 1. Tamanho máximo de 2.048.

Obrigatório: não

QueryInsights

Encapsula as configurações para ativaçã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

Obrigatório: não

QueryString

A consulta a ser executada pelo Timestream.

Tipo: string

Restrições de comprimento: tamanho mínimo de 1. Tamanho máximo de 262144.

Exigido: 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"
                  }
               ]
            }
         ]
      }
   ]
}