Query - Amazon Timestream
Sintassi della richiestaParametri della richiestaSintassi della rispostaElementi di rispostaErroriVedi anche

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Query

Queryè un'operazione sincrona che consente di eseguire una query sui dati di Amazon Timestream.

Se abilitataQueryInsights, restituisce API anche informazioni e metriche relative alla query che hai eseguito. QueryInsightsaiuta a ottimizzare le prestazioni della query. Per ulteriori informazioni suQueryInsights, consulta Usare le informazioni sulle query per ottimizzare le query in Amazon Timestream.

Nota

Il numero massimo di Query API richieste che puoi effettuare con QueryInsights enabled è 1 query al secondo (). QPS Se superi questa frequenza di query, potrebbe verificarsi una limitazione.

Queryscadrà dopo 60 secondi. È necessario aggiornare il timeout predefinito in SDK per supportare un timeout di 60 secondi. Per i dettagli, consulta l'esempio di codice.

La richiesta di interrogazione avrà esito negativo nei seguenti casi:

  • Se invii una Query richiesta con lo stesso token client al di fuori della finestra di idempotenza di 5 minuti.

  • Se invii una Query richiesta con lo stesso token client, ma modifichi altri parametri, entro la finestra di idempotenza di 5 minuti.

  • Se la dimensione della riga (inclusi i metadati della query) supera 1 MB, la query avrà esito negativo e verrà visualizzato il seguente messaggio di errore:

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

  • Se il IAM principale dell'iniziatore della query e del lettore dei risultati non coincidono e/o l'iniziatore della query e il lettore dei risultati non hanno la stessa stringa di query nelle richieste di query, la query avrà esito negativo e restituirà un errore. Invalid pagination token

Sintassi della richiesta

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

Parametri della richiesta

Per informazioni sui parametri comuni per tutte le azioni, consulta Parametri comuni.

La richiesta accetta i seguenti dati nel JSON formato.

ClientToken

Stringa univoca con distinzione tra maiuscole e minuscole, composta da un massimo di 64 ASCII caratteri, specificata quando viene effettuata una Query richiesta. L'immissione di un ClientToken rende la chiamata idempotente. Query Ciò significa che l'esecuzione ripetuta della stessa query produrrà lo stesso risultato. In altre parole, fare più Query richieste identiche ha lo stesso effetto di fare una singola richiesta. Quando si utilizza ClientToken in una query, tenete presente quanto segue:

  • Se la Query API viene istanziata senza aClientToken, la Query SDK genera un'istanza per ClientToken conto dell'utente.

  • Se la Query chiamata contiene solo ClientToken ma non include aNextToken, si presume che tale invocazione di Query sia l'esecuzione di una nuova query.

  • Se la chiamata contieneNextToken, si presume che quella particolare invocazione sia una chiamata successiva di una precedente chiamata alla Query e viene restituito un set di risultati. API

  • Dopo 4 ore, qualsiasi richiesta con lo stesso valore ClientToken viene trattata come una nuova richiesta.

Tipo: stringa

Vincoli di lunghezza: lunghezza minima di 32. La lunghezza massima è 128 caratteri.

Campo obbligatorio: no

MaxRows

Il numero totale di righe da restituire nell'Queryoutput. L'esecuzione iniziale di Query con un MaxRows valore specificato restituirà il set di risultati della query in due casi:

  • La dimensione del risultato è inferiore a1MB.

  • Il numero di righe nel set di risultati è inferiore al valore dimaxRows.

In caso contrario, l'invocazione iniziale di restituisce Query solo aNextToken, che può quindi essere utilizzato nelle chiamate successive per recuperare il set di risultati. Per riprendere l'impaginazione, fornite il NextToken valore nel comando successivo.

Se la dimensione della riga è grande (ad esempio una riga ha molte colonne), Timestream può restituire un numero inferiore di righe per evitare che la dimensione della risposta superi il limite di 1 MB. Se non MaxRows viene fornito, Timestream invierà il numero di righe necessario per soddisfare il limite di 1 MB.

Tipo: integer

Intervallo valido: valore minimo di 1. Valore massimo pari a 1000.

Campo obbligatorio: no

NextToken

Un token di impaginazione utilizzato per restituire una serie di risultati. Quando Query API viene richiamato utilizzandoNextToken, si presume che quella particolare invocazione sia una chiamata successiva di una chiamata precedente a e viene restituito un set di Query risultati. Tuttavia, se la Query chiamata contiene solo il, si presume che tale invocazione sia una nuova esecuzione di Query una query. ClientToken

Quando si utilizza NextToken in una query, tenete presente quanto segue:

  • Un token di impaginazione può essere utilizzato per un massimo di cinque Query invocazioni, OPPURE per una durata massima di 1 ora, a seconda dell'evento che si verifica per primo.

  • L'utilizzo dello stesso NextToken restituirà lo stesso set di record. Per continuare a sfogliare il set di risultati, è necessario utilizzare i più recenti. nextToken

  • Supponiamo che una Query chiamata restituisca due valori e. NextToken TokenA TokenB Se TokenB viene utilizzato in una Query chiamata successiva, viene invalidato e non può essere TokenA riutilizzato.

  • Per richiedere un set di risultati precedente da una query dopo l'inizio dell'impaginazione, è necessario richiamare nuovamente la Query. API

  • L'ultimo NextToken dovrebbe essere usato per impaginare fino a quando non null viene restituito, a quel punto dovrebbe essere usato un nuovoNextToken.

  • Se il IAM principale dell'iniziatore della query e del lettore dei risultati non sono gli stessi e/o l'iniziatore della query e il lettore dei risultati non hanno la stessa stringa di query nelle richieste di query, la query avrà esito negativo e verrà generato un errore. Invalid pagination token

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima di 1. La lunghezza massima è 2048 caratteri.

Campo obbligatorio: no

QueryInsights

Incapsula le impostazioni per l'attivazione. QueryInsights

L'attivazione QueryInsights restituisce approfondimenti e metriche oltre ai risultati delle query per la query che hai eseguito. È possibile utilizzarlo QueryInsights per ottimizzare le prestazioni delle query.

Tipo: oggetto QueryInsights

Campo obbligatorio: no

QueryString

La query che deve essere eseguita da Timestream.

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima pari a 1. Lunghezza massima di 262144.

Campo obbligatorio: sì

Sintassi della risposta

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

Elementi di risposta

Se l'azione ha esito positivo, il servizio restituisce una risposta di HTTP 200.

I seguenti dati vengono restituiti in JSON formato dal servizio.

ColumnInfo

I tipi di dati delle colonne del set di risultati restituito.

Tipo: matrice di oggetti ColumnInfo

NextToken

Un token di impaginazione che può essere riutilizzato durante una Query chiamata per ottenere il successivo set di risultati.

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima di 1. La lunghezza massima è 2048 caratteri.

QueryId

Un ID univoco per la query specificata.

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 64 caratteri.

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

QueryInsightsResponse

Incapsula QueryInsights contenente informazioni e metriche relative alla query che hai eseguito.

Tipo: oggetto QueryInsightsResponse

QueryStatus

Informazioni sullo stato della query, inclusi lo stato di avanzamento e i byte scansionati.

Tipo: oggetto QueryStatus

Rows

Le righe del set di risultati restituite dalla query.

Tipo: matrice di oggetti Row

Errori

Per informazioni sugli errori comuni a tutte le operazioni, consultare Errori comuni.

AccessDeniedException

Non sei autorizzato a eseguire questa azione.

HTTPCodice di stato: 400

ConflictException

Impossibile visualizzare i risultati del sondaggio per una query annullata.

HTTPCodice di stato: 400

InternalServerException

Il servizio non è stato in grado di elaborare completamente questa richiesta a causa di un errore interno del server.

HTTPCodice di stato: 400

InvalidEndpointException

L'endpoint richiesto non era valido.

HTTPCodice di stato: 400

QueryExecutionException

Timestream non è riuscito a eseguire la query con successo.

HTTPCodice di stato: 400

ThrottlingException

La richiesta è stata negata a causa del throttling della richiesta.

HTTPCodice di stato: 400

ValidationException

Richiesta non valida o non valida.

HTTPCodice di stato: 400

Vedi anche

Per ulteriori informazioni sull'utilizzo API in una delle lingue specifiche AWS SDKs, consulta quanto segue: