Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Timestream for InfluxDB 3 からのデータのクエリ
Amazon Timestream for InfluxDB 3 には、時系列データを取得するための複数のクエリ API とプロトコルが用意されています。このプラットフォームは、HTTP プロトコルと Flight (gRPC) プロトコルを通じて SQL クエリ言語と InfluxQL クエリ言語の両方をサポートし、さまざまなユースケースやクライアント設定に柔軟に対応します。
## クエリメソッドの概要
InfluxDB 3 では、次のクエリメソッドをサポートしています。
+ ネイティブ v3 HTTP API – REST エンドポイントを介した SQL および InfluxQL クエリ。
+ influxdb3 CLI – インタラクティブクエリ用のコマンドラインインターフェイス。
+ Flight\+gRPC プロトコル – クライアントライブラリ用の高性能バイナリプロトコル。
+ v1 Compatibility API – 下位互換性のためのレガシー InfluxQL クエリ。
### v3 HTTP Query API の使用
v3 API では、GET メソッドと POST メソッドの両方をサポートする SQL クエリと InfluxQL クエリ専用のエンドポイントが提供されます。
#### SQL クエリ (`/api/v3/query_sql`)
GET リクエストの例:
```
curl --get "https://your-cluster-endpoint:8086/api/v3/query_sql" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home WHERE time >= now() - INTERVAL '1 day'"
```
POST リクエストの例 (複雑なクエリの場合):
```
curl "https://your-cluster-endpoint:8086/api/v3/query_sql" \
--header "Authorization: Bearer YOUR_TOKEN" \
--json '{
"db": "DATABASE_NAME",
"q": "SELECT * FROM home WHERE room = '\''Kitchen'\'' AND temp > 20",
"format": "jsonl"
}'
```
#### InfluxQL クエリ (`/api/v3/query_influxql`)
InfluxQL クエリの場合は、次を行います。
```
curl --get "https://your-cluster-endpoint:8086/api/v3/query_influxql" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT mean(temp) FROM home WHERE time >= now() - 1d GROUP BY room"
```
#### クエリパラメータ
次のパラメータを使用することができます。
| **パラメータ** | **説明** | **必須** |
| --- | --- | --- |
| db | [Database name] (データベース名) | はい |
| q | クエリ文字列 (SQL または InfluxQL) | はい |
| format | レスポンス形式 (json、jsonl、csv、pretty、parquet) | いいえ (デフォルト: json) |
| params | パラメータ化されたクエリのパラメータ | いいえ |
#### Influxdb3 CLI の使用
InfluxDB 3 コマンドラインインターフェイス (CLI) は `influxdb3` コマンドで呼び出されます。複数の出力形式をサポートしてデータをクエリするインタラクティブな方法を提供します。
基本的なクエリを以下に示します。
```
influxdb3 query \
--host "your-cluster-endpoint:8086" \
--token "YOUR_TOKEN" \
--database "DATABASE_NAME" \
"SELECT * FROM home WHERE time >= now() - INTERVAL '1 day'"
```
以下は、さまざまな出力形式のクエリを示しています。
```
# JSON output
influxdb3 query \
--database "DATABASE_NAME" \
--format json \
"SELECT * FROM home LIMIT 10"
# CSV output
influxdb3 query \
--database "DATABASE_NAME" \
--format csv \
"SELECT * FROM home LIMIT 10"
# Parquet file output
influxdb3 query \
--database "DATABASE_NAME" \
--format parquet \
--output results.parquet \
"SELECT * FROM home"
```
以下の出力形式がサポートされています。
+ pretty (デフォルト) – 人間が読める表形式。
+ json – 標準 JSON 配列。
+ jsonl – JSON Lines (ストリーミングフレンドリ)。
+ CSV – カンマで区切られた値。
+ parquet – バイナリ列形式 (ファイル出力が必要)。
### v1 Compatibility API の使用
レガシー InfluxQL クエリの場合は、`/query` エンドポイントを使用します。
```
curl --get "https://your-cluster-endpoint:8086/query" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home" \
--data-urlencode "epoch=ms"
```
## v3 HTTP Query API の認証オプション
+ ベアラートークン: `Authorization: Bearer TOKEN`
+ 基本的な認証: `--user "any:TOKEN"`
+ クエリパラメータ: `?p=TOKEN`
## v3 HTTP Query API のレスポンス形式
+ JSON (デフォルト)
+ CSV (`Accept: application/csv` ヘッダー付き)
## SQL クエリの例
基本的なクエリを以下に示します。
```
-- Select specific fields with time filter
SELECT temp, humidity, room
FROM home
WHERE time >= now() - INTERVAL '7 days'
AND room = 'Kitchen'
ORDER BY time DESC
-- Show all tables in database
SHOW TABLES
-- Show columns in a table
SHOW COLUMNS FROM home
```
集計クエリを次に示します。
```
-- Aggregate by tags
SELECT
room,
AVG(temp) as avg_temp,
MAX(humidity) as max_humidity
FROM home
WHERE time >= now() - INTERVAL '24 hours'
GROUP BY room
-- Time-based aggregation using DATE_BIN
SELECT
DATE_BIN(INTERVAL '1 hour', time) as time,
AVG(temp) as avg_temp,
COUNT(*) as reading_count
FROM home
GROUP BY 1
ORDER BY time DESC
```
以下に、SQL の高度な機能を示します。
```
-- Parameterized queries (via API)
SELECT * FROM home
WHERE room = $room
AND temp > $min_temp
AND time >= $start_time
-- Gap filling with interpolation
SELECT
date_bin_gapfill(INTERVAL '5 minutes', time) as time,
room,
interpolate(avg(temp)) as temp
FROM home
WHERE time >= '2025-01-01T00:00:00Z'
AND time <= '2025-01-01T12:00:00Z'
GROUP BY 1, room
-- Type casting
SELECT
temp::INTEGER as temp_int,
CAST(humidity AS VARCHAR) as humidity_str
FROM home
```
以下に、InfluxQL クエリの例を示します。
```
-- Basic query with time filter
SELECT * FROM home WHERE time >= now() - 1d
-- Aggregation with GROUP BY time
SELECT MEAN(temp), MAX(humidity)
FROM home
WHERE time >= now() - 7d
GROUP BY time(1h), room
-- Using selector functions
SELECT FIRST(temp), LAST(temp)
FROM home
WHERE time >= now() - 1h
GROUP BY room
```
以下は、システムテーブルをクエリしてデータベース構造を理解し、パフォーマンスをモニタリングする方法を示しています。
```
-- View all tables with schema information
SELECT * FROM information_schema.tables
-- View column details for a specific table
SELECT * FROM information_schema.columns
WHERE table_name = 'home'
-- Monitor recent queries
SELECT * FROM system.queries
ORDER BY issue_time DESC
LIMIT 10
-- Check cache configurations
SELECT * FROM system.last_caches
SELECT * FROM system.distinct_caches
```
## クエリパフォーマンスに関するベストプラクティス
+ **時間フィルターを使用する**: スキャンされるデータを制限するため、常に時間範囲フィルターを含めます。
+ **インデックスを活用する**: タグフィルターを効果的に使用するようにクエリを設計します。
+ **適切な出力形式を選択する**:
+ 大きな結果をストリーミングするには jsonl を使用します。
+ データのエクスポートと分析には parquet を使用します。
+ スプレッドシートの互換性を確保するには csv を使用します。
+ **集計を最適化する**: 時間ベースのグループ化に DATE\_BIN を使用します。
+ **パラメータ化されたクエリを使用する**: インジェクション攻撃を防ぎ、再利用性を向上させます。
+ **クエリパフォーマンスをモニタリングする**: system.queries テーブルでスロークエリを確認します。
## クライアントライブラリクエリのサポート
InfluxDB 3 クライアントライブラリは、Flight\+gRPC プロトコルを使用して最適なパフォーマンスを実現します。以下の Python コードは、これを実行する方法を示しています。
```
from influxdb3 import InfluxDBClient3
client = InfluxDBClient3(
host="your-cluster-endpoint:8086",
token="YOUR_TOKEN",
database="DATABASE_NAME"
)
# SQL query
sql_result = client.query("SELECT * FROM home WHERE room = 'Kitchen'")
# InfluxQL query
influxql_result = client.query(
"SELECT MEAN(temp) FROM home WHERE time >= now() - 1h GROUP BY room",
language="influxql"
)
```
## SQL クエリ機能と InfluxQL クエリ機能の比較
次の表は、SQL と InfluxQL のクエリ機能を比較したものです。
| **機能** | **SQL** | **InfluxQL** |
| --- | --- | --- |
| 結合 | サポート | サポートされていません |
| ウィンドウ関数 | フルサポート | 制限あり |
| サブクエリ | サポート | サポートされていません |
| Time 関数 | DATE\_BIN, INTERVAL | time() のグループ分け |
| パラメータ化されたクエリ | ネイティブサポート | サポートされていません |
| ギャップ埋め | date\_bin\_gapfill() | fill() 関数 |
これらのクエリの機能を理解し、ユースケースに適した方法を選択することで、Timestream for InfluxDB 3 から時系列データを効率的に取得して分析できます。
SQL の利点:
+ 複雑なクエリをサポートするフル機能の SQL 実装。
+ 結合、ユニオン、ウィンドウ関数のサポート。
+ SQL 使用経験を持つユーザーに使い慣れた構文。
+ より広範な分析機能。
InfluxQL の利点:
+ 時系列データ専用に設計。
+ 一般的な時系列オペレーションの構文を簡素化。
+ InfluxDB v1 から移行するユーザーの下位互換性。
+ 特殊な時系列関数。
## クエリ最適化機能
InfluxDB 3 には、特定のユースケースのクエリパフォーマンスを向上させる最適化機能がいくつか用意されています。これらの機能は、インメモリキャッシュとカスタムインデックス作成戦略によって、頻繁にアクセスされるデータパターンに対してミリ秒未満の応答時間を提供します。
### 最終値キャッシュ (LVC)
最終値キャッシュ (LVC) は、指定されたフィールドの最新の N 値をメモリに保存するため、最新のデータポイントを必要とするクエリの応答時間が 10 ミリ秒未満になります。この機能は Core エディションと Enterprise エディションの両方で使用できます。
#### LVC の仕組み
LVC は、キー列 (通常はタグ) の一意の組み合わせごとに最新の値のインメモリテーブルを維持します。例えば、センサーデータでは以下のとおりです。
```
Table: home
├── Tags: room, wall
└── Fields: temp, humidity, co
LVC Configuration:
- Key columns: room, wall
- Value columns: temp, humidity, co
- Count: 4 (last 4 values)
```
キャッシュには以下が保存されます。
| **ルーム** | **wall (壁)** | **一時** | **湿度** | **c**o | **time** |
| --- | --- | --- | --- | --- | --- |
| キッチン | east (東) | 22.7 | 36.5 | 26 | 2025-01-26T20:00:00Z |
| キッチン | east (東) | 22.7 | 36.0 | 9 | 2025-01-26T17:00:00Z |
| キッチン | east (東) | 22.7 | 36.2 | 3 | 2025-01-26T15:00:00Z |
| キッチン | east (東) | 22.7 | 36.1 | 0 | 2025-01-26T10:00:00Z |
| Living Room (リビングルーム) | north (北) | 22.2 | 36.4 | 17 | 2025-01-26T20:00:00Z |
| ... | ... | ... | ... | ... | ... |
#### LVC を作成する
LVC を作成するには以下のコマンドを使用します。
```
influxdb3 create last_cache \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table home \
--key-columns room,wall \
--value-columns temp,hum,co \
--count 5 \
--ttl 30mins \
homeLastCache
```
#### LVC をクエリする
LVC をクエリするには、次のコマンドを使用します。
```
-- Query the last cached values
SELECT * FROM last_cache('home', 'homeLastCache')
-- Filter specific series
SELECT * FROM last_cache('home', 'homeLastCache')
WHERE room = 'Kitchen'
```
#### LVC のベストプラクティス
+ カーディナリティの管理: メモリ使用量を最小限に抑えるために、必須タグをキー列としてのみ含めます。
+ 値カウントの最適化: クエリのニーズとメモリ消費量のバランスを取ります。
+ TTL の検討: キャッシュエントリの適切な有効期限を設定します。
+ メモリ監視: キャッシュサイズ = (key\_column\_cardinality × count × value\_columns)。
### 一意値キャッシュ (DVC)
一意値キャッシュ (DVC) は、メモリ内の指定された列に存在する一意の値を維持し、メタデータクエリを 30 ミリ秒未満の応答時間に高速化します。Core エディションと Enterprise エディションの両方で使用できます。
#### DVC の仕組み
DVC は、指定された列における値の一意の組み合わせをすべて保存し、使用可能なタグ値またはメタデータを一覧表示する必要があるクエリに最適です。
位置データのキャッシュの例:
| **国** | **county (郡)** | **都市** |
| --- | --- | --- |
| オーストリア | Salzburg (ザルツブルク) | Salzburg (ザルツブルク) |
| オーストリア | Vienna (ウィーン) | Vienna (ウィーン) |
| ベルギー | Antwerp (アントワープ) | Antwerp (アントワープ) |
| ベルギー | West Flanders (ウェスト＝フランデレン) | Bruges (ブルージュ) |
| チェコ共和国 | Prague (プラハ) | Prague (プラハ) |
#### DVC を作成する
DVC を作成するには以下のコマンドを使用します。
```
influxdb3 create distinct_cache \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data \
--columns country,county,city \
--max-cardinality 10000 \
--max-age 24h \
windDistinctCache
```
#### DVC をクエリする
次のコマンドを使用して DVC をクエリします。
```
-- Get all distinct values
SELECT * FROM distinct_cache('wind_data', 'windDistinctCache')
-- Get distinct countries
SELECT DISTINCT country
FROM distinct_cache('wind_data', 'windDistinctCache')
```
#### DVC に関するベストプラクティス
+ カーディナリティ制限の設定: メモリを制御するために最大の一意値の組み合わせを定義します。
+ 最大経過時間の設定: 古い値を自動的に削除します。
+ キャッシュ戦略列: メタデータクエリで頻繁に使用される列にフォーカスします。
+ キャッシュサイズのモニタリング: カーディナリティが高いほど、より多くのメモリが必要になります。
### Enterprise でのみ利用可能なファイルインデックス
**Enterprise エディションでのみ使用できます。**ファイルインデックスを使用すると、ストレージ内のデータのインデックス作成方法をカスタマイズできるので、単一系列のクエリパフォーマンスが大幅に向上します。
#### デフォルトインデックス作成とカスタムインデックス作成
デフォルトインデックス作成: InfluxDB は、すべてのタグに時間を加えたインデックスを作成します。
カスタムインデックス作成: クエリに関連する列のインデックスのみ作成します。
最適化の例:
```
Schema columns: country, state_province, county, city, postal_code
Query patterns: Always filter by country, state_province, city
Custom index: time, country, state_province, city (skip county, postal_code)
```
以下は、カスタムファイルインデックスを作成する方法を示しています。
```
influxdb3 create file_index \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data \
country,state_province,city
```
次は、ファイルインデックスを削除する方法を示しています。
```
influxdb3 delete file_index \
--database DATABASE_NAME \
--token YOUR_TOKEN \
--table wind_data
```
#### ファイルインデックスに関する考慮事項
+ 圧縮が必要: インデックスはデータ圧縮 (第 2 世代以降) 中に構築されます。
+ 文字列の列のみ: タグと文字列フィールドの両方にインデックスを作成できます。
+ クエリパターン分析: カスタムインデックスを作成する前にワークロードを分析します。
+ 単一系列の最適化: 特定の系列をターゲットとするクエリに最も役立ちます。
### キャッシュ情報の管理
システムテーブルを使用してキャッシュ設定と統計を表示します。
```
-- View Last Value Caches
SELECT * FROM system.last_caches
-- View Distinct Value Caches
SELECT * FROM system.distinct_caches
-- Check cache memory usage
SELECT
cache_name,
table_name,
key_columns,
value_count,
memory_size_bytes
FROM system.last_caches
```
### パフォーマンス最適化戦略
クエリパターンに基づいて適切な最適化機能を選択します。
| **クエリパターン** | **推奨機能** | **期待されるパフォーマンス** |
| --- | --- | --- |
| 系列ごとの最新の値 | 最終値キャッシュ | <10 ミリ秒 |
| 指定できるタグ値 | 一意値キャッシュ | <30 ミリ秒 |
| 単一系列のクエリ | ファイルインデックス (Enterprise) | 大幅な改善 |
| 時間範囲の集計 | 標準インデックス | ベースラインパフォーマンス |
### メモリとリソースに関する考慮事項
**キャッシュメモリ式:**
+ LVC: メモリ = key\_cardinality × value\_count × value\_columns × data\_size
+ DVC: メモリ = distinct\_combinations × column\_count × data\_size
**ベストプラクティス:**
+ 小さなキャッシュから始めてメモリ使用量をモニタリングする
+ TTL 設定を使用してキャッシュの増加を制限する
+ 頻繁にクエリされるデータのみをキャッシュする
+ システムテーブルを通じてキャッシュヒットレートをモニタリングする
+ Enterprise の場合: キャッシュとカスタムファイルインデックスを組み合わせて最適なパフォーマンスを実現する
これらの最適化機能を適切に活用することで、リソースの消費を効果的に管理しながら、特定のクエリパターンのパフォーマンスを大幅に改善させることができます。