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ê ativouQueryInsights, isso API também retornará informações e métricas relacionadas à consulta que você executou. QueryInsightsajuda no ajuste do desempenho de sua consulta. Para obter mais informações sobreQueryInsights, consulte Uso de insights de consulta para otimizar consultas no Amazon Timestream.

nota

O número máximo de Query API solicitações que você pode fazer com QueryInsights ativado é de 1 consulta por segundo (QPS). Se você exceder essa taxa de consulta, isso poderá resultar em limitação.

Queryexpirará após 60 segundos. Você deve atualizar o tempo limite padrão no SDK para suportar um tempo limite de 60 segundos. Consulte o exemplo 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 o IAM principal 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 comuns a todas as ações, consulte Parâmetros Comuns.

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

ClientToken

Cadeia de caracteres exclusiva, com distinção entre maiúsculas e minúsculas, de até 64 ASCII caracteres, especificada quando uma Query solicitação é feita. Fornecer um ClientToken faz com que a chamada seja Query idempotente. Isso significa que executar a mesma consulta repetidamente produzirá o mesmo resultado. Em outras palavras, fazer várias Query solicitações idênticas tem o mesmo efeito que fazer uma única solicitação. Ao usar ClientToken em uma consulta, observe o seguinte:

Se a consulta API for instanciada sem umClientToken, a consulta SDK 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 contiverNextToken, essa invocação específica será considerada uma invocação subsequente de uma chamada anterior para a Consulta e um conjunto de resultados será API retornado.
Depois de 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 tamanho máximo é 128.

Obrigatório: Não

MaxRows

O número total de linhas a serem retornadas na Query saída. 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 que1MB.
O número de linhas no conjunto de resultados é menor que o valor demaxRows.

Caso contrário, a invocação inicial de retorna Query apenas aNextToken, que pode ser usada em chamadas subsequentes para buscar o conjunto de resultados. Para retomar a paginação, forneça o NextToken valor no 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: número 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 o Query API é invocado usandoNextToken, essa invocação específica é considerada uma invocação subsequente de uma chamada anterior paraQuery, e um conjunto de resultados é retornado. No entanto, se a Query invocação contiver apenas oClientToken, 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, e. TokenA 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 consulta. API
O último NextToken deve ser usado para paginar até null ser retornado, momento em que um novo NextToken deve ser usado.
Se o IAM principal 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.

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