Sintaksis Permintaan Parameter Permintaan Sintaksis Respons Elemen Respons Kesalahan Lihat Juga

Query

Queryadalah operasi sinkron yang memungkinkan Anda menjalankan kueri terhadap data Amazon Timestream Anda.

Jika Anda mengaktifkanQueryInsights, ini API juga menampilkan wawasan dan metrik yang terkait dengan kueri yang Anda jalankan. QueryInsightsmembantu penyetelan kinerja kueri Anda. Untuk informasi selengkapnyaQueryInsights, lihat Menggunakan wawasan kueri untuk mengoptimalkan kueri di Amazon Timestream.

catatan

Jumlah maksimum Query API permintaan yang diizinkan untuk Anda buat dengan QueryInsights diaktifkan adalah 1 kueri per detik (QPS). Jika Anda melebihi tingkat kueri ini, itu mungkin mengakibatkan pelambatan.

Queryakan habis setelah 60 detik. Anda harus memperbarui batas waktu default SDK untuk mendukung batas waktu 60 detik. Lihat contoh kode untuk detailnya.

Permintaan kueri Anda akan gagal dalam kasus berikut:

Jika Anda mengirimkan Query permintaan dengan token klien yang sama di luar jendela idempotensi 5 menit.
Jika Anda mengirimkan Query permintaan dengan token klien yang sama, tetapi mengubah parameter lain, dalam jendela idempotensi 5 menit.
Jika ukuran baris (termasuk metadata kueri) melebihi 1 MB, maka kueri akan gagal dengan pesan kesalahan berikut:

Query aborted as max page response size has been exceeded by the output result row
Jika IAM prinsipal inisiator kueri dan pembaca hasil tidak sama dan/atau inisiator kueri dan pembaca hasil tidak memiliki string kueri yang sama dalam permintaan kueri, kueri akan gagal dengan kesalahanInvalid pagination token.

Sintaksis Permintaan


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

Parameter Permintaan

Untuk informasi tentang parameter yang umum untuk semua tindakan, lihat Parameter Umum.

Permintaan menerima data berikut dalam JSON format.

ClientToken

String unik dan peka huruf besar/kecil hingga 64 ASCII karakter yang ditentukan saat Query permintaan dibuat. ClientTokenMemberikan panggilan untuk Query idempoten. Ini berarti bahwa menjalankan kueri yang sama berulang kali akan menghasilkan hasil yang sama. Dengan kata lain, membuat beberapa Query permintaan identik memiliki efek yang sama seperti membuat permintaan tunggal. Saat menggunakan ClientToken dalam kueri, perhatikan hal berikut:

Jika Query API dipakai tanpa aClientToken, Query akan SDK menghasilkan a ClientToken atas nama Anda.
Jika Query pemanggilan hanya berisi ClientToken tetapi tidak menyertakan aNextToken, pemanggilan tersebut diasumsikan sebagai Query kueri baru yang dijalankan.
Jika pemanggilan berisiNextToken, pemanggilan tertentu diasumsikan sebagai pemanggilan berikutnya dari panggilan sebelumnya ke KueriAPI, dan kumpulan hasil dikembalikan.
Setelah 4 jam, permintaan apa pun dengan hal ClientToken yang sama diperlakukan sebagai permintaan baru.

Tipe: String

Kendala Panjang: Panjang minimum 32. Panjang maksimum 128.

Wajib: Tidak

MaxRows

Jumlah total baris yang akan dikembalikan dalam Query output. Jalankan awal Query dengan MaxRows nilai yang ditentukan akan mengembalikan kumpulan hasil kueri dalam dua kasus:

Ukuran hasilnya kurang dari1MB.
Jumlah baris dalam set hasil kurang dari nilaimaxRows.

Jika tidak, pemanggilan awal Query hanya mengembalikan aNextToken, yang kemudian dapat digunakan dalam panggilan berikutnya untuk mengambil set hasil. Untuk melanjutkan pagination, berikan NextToken nilai dalam perintah berikutnya.

Jika ukuran baris besar (misalnya baris memiliki banyak kolom), Timestream dapat mengembalikan lebih sedikit baris agar ukuran respons tidak melebihi batas 1 MB. Jika tidak MaxRows disediakan, Timestream akan mengirimkan jumlah baris yang diperlukan untuk memenuhi batas 1 MB.

Jenis: Integer

Rentang yang Valid: Nilai minimum 1. Nilai maksimum 1000.

Wajib: Tidak

NextToken

Token pagination digunakan untuk mengembalikan serangkaian hasil. Ketika Query API dipanggil menggunakanNextToken, pemanggilan tertentu diasumsikan sebagai pemanggilan berikutnya dari panggilan sebelumnya keQuery, dan kumpulan hasil dikembalikan. Namun, jika Query pemanggilan hanya berisiClientToken, pemanggilan tersebut Query diasumsikan sebagai kueri baru yang dijalankan.

Perhatikan hal berikut saat menggunakan NextToken dalam kueri:

Token pagination dapat digunakan hingga lima Query pemanggilan, ATAU untuk durasi hingga 1 jam — mana yang lebih dulu.
Menggunakan yang sama NextToken akan mengembalikan set catatan yang sama. Untuk terus melakukan paginasi melalui set hasil, Anda harus menggunakan yang terbaru. nextToken
Misalkan Query pemanggilan mengembalikan dua NextToken nilai, TokenA dan. TokenB Jika TokenB digunakan dalam Query pemanggilan berikutnya, maka tidak valid dan TokenA tidak dapat digunakan kembali.
Untuk meminta set hasil sebelumnya dari kueri setelah pagination dimulai, Anda harus memanggil ulang Query. API
Yang terbaru NextToken harus digunakan untuk paginasi sampai null dikembalikan, pada titik mana yang baru NextToken harus digunakan.
Jika IAM prinsipal inisiator kueri dan pembaca hasil tidak sama dan/atau inisiator kueri dan pembaca hasil tidak memiliki string kueri yang sama dalam permintaan kueri, kueri akan gagal dengan kesalahanInvalid pagination token.

Tipe: String

Batasan Panjang: Panjang minimum 1. Panjang maksimum 2048.

Wajib: Tidak

QueryInsights

Merangkum pengaturan untuk mengaktifkan. QueryInsights

Mengaktifkan QueryInsights mengembalikan wawasan dan metrik selain hasil kueri untuk kueri yang Anda jalankan. Anda dapat menggunakan QueryInsights untuk menyetel kinerja kueri Anda.

Tipe: Objek QueryInsights

Wajib: Tidak

QueryString

Query yang akan dijalankan oleh Timestream.

Tipe: String

Panjang Batasan: Panjang minimum 1. Panjang maksimum 262144.

Wajib: Ya

Sintaksis Respons


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