Device Query
Device Query は、SQL ライクなクエリ言語を使ってデバイス全体のフリートを横断検索できる機能です。デバイスのメタデータ、接続状態、最新のシャドウ状態を一つのクエリ可能なサーフェスに統合しているため、複数のデータソースを自分で結合する必要がありません。
Device Query を開く
Fleets のデプロイメントで、左メニューの Device Query をクリックします。
クエリの記述
テキストエディターにクエリを入力し、Run Query をクリックします。結果は下の Query Results テーブルに表示されます。
クエリ結果には、該当する各 Thing の名前、MQTT クライアント ID、ステータスが含まれます。
例による説明
この例では、オフラインのスマートロックをすべて検索します。
クエリエディターに以下を入力します。
thingTypeName:com.demo.fleets.smart-lock AND status:offlineRun Query をクリックします。
Query Results テーブルに、該当するすべての Thing の名前、MQTT クライアント ID、ステータスが一覧表示されます。
Thing 名をクリックすると詳細ページが開き、最終オフライン時間やシャドウ状態を確認できます。
クエリ構文
クエリは field:value 形式で記述し、比較、否定、論理演算子、グルーピングをサポートします。
| パターン | 説明 | 例 |
|---|---|---|
field:value | 完全一致 | status:online |
field:a,b | 指定した値のいずれかに一致（IN） | operationMode:cool,heat |
field:* | レポートされた状態にフィールドが存在する | temperature:* |
field:>value | より大きい（数値フィールド） | temperature:>25 |
field:>=value | 以上 | battery:>=20 |
field:<value | より小さい | humidity:<60 |
field:<=value | 以下 | voltage:<=3.3 |
NOT field:value | 条件の否定 | NOT status:offline |
a AND b | 両方の条件を満たす | status:online AND temperature:>30 |
a OR b | いずれかの条件を満たす | status:online OR temperature:>40 |
(a OR b) AND c | 優先順位を制御するグルーピング | (mode:cool OR mode:heat) AND connected:true |
AND と OR は明示的に記述する必要があります。演算子なしの a:1 b:2 は無効です。
クエリ可能なフィールド
| フィールド | 説明 |
|---|---|
thingName | Thing 名 |
thingTypeName | Thing タイプ名 |
status | 接続状態：online または offline |
connected | status のブール相当：true はオンライン、false はオフライン |
hasDelta / shadow.hasDelta | 希望状態と報告状態が異なる場合は true |
shadow.version / shadowVersion | 現在のシャドウバージョン番号 |
lastConnectedAt | 最終接続時刻（等価比較推奨） |
shadow.reported.<key> | 最新の報告状態の任意のキー |
shadow.desired.<key> | 最新の希望状態の任意のキー |
報告状態のフィールドでは、shadow.reported. プレフィックスを省略してプロパティ名だけでも使用可能です。reported.<key> も同様です。例えば、temperature:>25、reported.temperature:>25、shadow.reported.temperature:>25 はすべて同じ意味です。
上記管理リストにないフィールド名はすべてシャドウの報告キーとして扱われます。
クエリ例
オンラインのデバイスをすべて検索：
status:online切断されたデバイスを検索：
connected:false希望状態の差分があるデバイスを検索：
hasDelta:true温度が30℃を超えるサーモスタットを検索：
thingTypeName:Thermostat AND temperature:>30バッテリー残量が少なく、なおかつオンラインのデバイスを検索：
status:online AND battery:<20複数のモードのいずれかにあるデバイスを検索：
operationMode:cool,heat少なくとも一度はフィールドが報告されたデバイスを検索：
temperature:*フィルターの追加
+ Add filter をクリックして、クエリ文字列に加えて構造化フィルターを適用できます。利用可能なフィルターは以下の通りです。
- Things：特定の Thing 名に結果を制限
- Group：特定の Thing グループのメンバーに結果を制限
- Thing Type：特定タイプの Thing に結果を制限
- Status：
onlineまたはofflineでフィルター - Reported Time Window：指定した時間範囲内に状態を報告した Thing に結果を制限
すべての有効なフィルターは AND で結合されます。
クエリ履歴
Query History をクリックすると、現在のセッションで実行した過去のクエリを表示・再実行できます。
時系列フィルター
Reported Time Window フィルターは、指定した時間範囲内にシャドウ状態を報告した Thing に結果を制限します。これは最新のスナップショットだけでなく、GreptimeDB の履歴時系列データを参照します。
コンソールでは、+ Add filter から Reported Time Window フィルターを追加し、開始時刻と終了時刻を設定します。
REST API 利用時は、リクエストボディに以下のパラメーターを渡します。
| パラメーター | 説明 |
|---|---|
tsFrom | 時間範囲の開始（RFC3339 UTC）。tsTo とセットで必須。 |
tsTo | 時間範囲の終了（RFC3339 UTC）。tsFrom とセットで必須。 |
tsFieldName | 任意。時間範囲内に報告された特定のトップレベルキーに限定。省略すると範囲内の任意の報告行にマッチ。 |
tsLimit | 時系列の事前フィルターで対象となる最大 Thing 数。デフォルトは 1000、最大は 10000。ページネーションの limit とは異なります。 |
例：1時間のウィンドウ内で温度を報告したオンラインデバイスを検索する例：
{
"query": "status:online",
"tsFrom": "2026-05-27T00:00:00Z",
"tsTo": "2026-05-27T01:00:00Z",
"tsFieldName": "temperature",
"page": 1,
"limit": 20
}重要なお知らせ
時系列フィルターは GreptimeDB を参照します。GreptimeDB が利用できない場合、tsFrom / tsTo を使ったクエリは 503 Service Unavailable を返します。
REST API
Device Query は REST API でも利用可能です：
POST /api/v1/device-query/searchデプロイメントの API エンドポイントをベース URL とし、デプロイメント API キーを使った Basic 認証でアクセスします。エンドポイントの取得方法やキーの作成方法は Deployment API Keys を参照してください。