データバインディング

データバインディングは、プロジェクトデータベースと IoT ボード上のウィジェットを繋ぐ橋渡しです。ウィジェットの構成可能なプロパティのほぼすべて（タイトル、値、色、チャートシリーズ、ゲージ範囲など）を、プロジェクトの TimescaleDB から来るライブデータで動的に駆動できます。このページでは、テーブルのカラムをウィジェットプロパティに接続する方法と、フィルターでデータを精密にする方法を説明します。

データがどのようにプロジェクトデータベースに届くかの全体像については、データ処理の概要をご覧ください。

データをバインドする 2 つの方法

IronFlock Board Studio には、基本となる 2 つのバインディングモードがあります：

値参照 — 単一のスカラー値（あるカラムの最新レコード）をウィジェットプロパティにバインドします。
テーブル参照 — 配列を期待するウィジェットプロパティに、結果セット全体（複数行）をバインドします。

どちらのモードもフィルタリングをサポートし、リアルタイム更新を提供します。新しい行がプロジェクトデータベースに到着すると、バインド済みのウィジェットプロパティはポーリングなしで自動的に更新されます。

値参照

ほとんどのウィジェット設定フィールドは単一の値を期待します — タイトル、数値の表示、色、ステータスラベルなど。ウィジェットエディタではこれらのフィールドの下に小さなデータバインディングスイッチがあります。

スイッチを有効にしてフィールドをクリックすると、プロジェクトデータベースで利用可能なすべてのデータをリストするドロップダウンが開きます。次のことができます：

プロジェクトデータベースからテーブルを選ぶ。
そのテーブル内のカラムをプロパティにバインドするために選ぶ。

例：ゲージウィジェットのタイトルフィールドを machine テーブルの name カラムにバインドしたり、数値ウィジェットの値フィールドを sensor_data テーブルの最新の temperature 値にバインドできます。

フィルターアイコン

カラムをウィジェットプロパティにバインドすると、フィールド下のデータスイッチの隣に小さなフィルターアイコンが表示されます。クリックするとダイアログが開き、値抽出時に考慮する行を絞り込むフィルターを構成できます。下のフィルター構成をご覧ください。

テーブル参照

一部のウィジェットは、スカラーではなく値の配列を期待します。たとえばチャートウィジェットは線を描くために多数の (x, y) ポイントを必要とし、テーブルウィジェットは多数の行を必要とします。

こうした箇所では、ウィジェットエディタはフィールドラベル横に追加ボタン（配列要素を手動で追加するため）とデータバインディングスイッチを表示します。

手動モード： 追加をクリックして、静的な値を持つ要素を一つずつ追加します。
データバインディングモード： スイッチを切り替えて配列をテーブルにバインドします。テーブルを選択すると、条件に一致する各行が配列の 1 要素になります。

データスイッチの隣のフィルターアイコンで、返される行を必要な条件に合わせて絞り込めます — フィルター構成をご覧ください。

配列要素フィールドへのカラムマッピング

テーブル参照のデータバインディングが有効になると、接続されたテーブルの値を使って単一の配列要素テンプレートを構成します。折れ線チャートの場合、要素には x と y の値が必要です — バインドされたテーブルからそれぞれの軸に供給するカラムを選ぶことで、両方をデータ駆動にできます。フィルター後の結果セットの各行は、そのマッピングを使ってチャートにレンダリングされます。

同じパターンは、配列を受け取るすべてのウィジェット（棒グラフ、テーブル、リスト、ヒートマップなど）に適用されます。

フィルター構成

フィルターは、値参照またはテーブル参照で使用される行を絞り込みます。ダイアログの各セクションは表示されている順に適用され、それはプロジェクトデータベースが適用する順序でもあります：

1. ローリング時間ウィンドウ

レコードが時間でどのようにフィルターされるかを構成します：

ローリングウィンドウ — 現在時刻に対して、直近 N 分、時間、日などの行のみを表示します。
カスタム時間ウィンドウ — 開始パラメータと終了パラメータの名前を指定します。これらのパラメータ名は実行時にカレンダーウィジェットによって供給され、エンドユーザーがボード上で期間を選べます。

2. 任意のカラムフィルター

次のいずれかの値ソースを使用して、任意の数のカラムレベルフィルターを追加します：

定数値 — ハードコードされた値（例：status = 'active'）。
フィルターパラメータ — フィルターウィジェットから URL 経由で供給される値。
ルーティングパスセグメント — ナビゲーションウィジェットを介して現在のページ URL から抽出される値。

3. 集計

既定では、バインディングは生データ行を返します。時間で集計に切り替えると、プロジェクトデータベースは選択されたレコードを時間バケット（またはカテゴリ）にグループ化し、グループごとに計算された値を 1 つ返します — 1 時間ごとの平均、機械ごとのレコード件数、今日の合計などです。

フィルターはこのステップの前に実行されるため、どのレコードが各バケットに入るかを決めます。集計については専用のページで詳しく説明しています。集計とダウンサンプリングをご覧ください。

4. 行数制限

ウィジェットに対して返される行数の上限を設定します。制限は 3000 を超えることはできません — この上限はブラウザもプロジェクトデータベースも過大な結果セットから保護します。

集計されたバインディングの場合、返されるバケット数は代わりに（ウィジェットの幅または選択した間隔から）導出され、行数制限はフォールバック時の安全装置としてのみ機能します。

すべてのセクションは合成されます：時間ウィンドウが時間範囲を絞り、カラムフィルターがさらに行を精緻化し、集計がそれらをバケットごとに 1 つの値へまとめ、行数制限が最終出力を上限します。

JSON カラムからのフィールド選択

プロジェクトデータベースは、非構造化または半構造化データ（デバイステレメトリのペイロード、設定 Blob、ネストしたレコード）向けに JSON カラムをサポートします。

JSON カラムをウィジェットプロパティにバインドすると、JSON 構造内のリーフフィールドへのパスを指定するための追加入力が表示されます。パスは標準の JavaScript オブジェクト記法を使用します：


sensor.temperature
payload.items.0.value
metadata.location.city

ウィジェットは各レコードからそのパスの値を抽出します。これは値参照（最新の JSON レコードから抽出されたリーフ）とテーブル参照（各行から抽出されたリーフ）の両方で機能します。

まとめ

スカラープロパティ（タイトル、値、色）には値参照を使用します — tsp による最新値を得られます。
配列プロパティ（チャートシリーズ、テーブル、リスト）にはテーブル参照を使用します — カラムを配列要素フィールドにマッピングします。
時間ウィンドウ、カラムフィルター、行数制限（最大 3000）で行を絞り込むにはフィルターダイアログを使用します。
レコードそのものではなく計算された値が必要な場合は、バインディングを集計に切り替えます — 集計とダウンサンプリングをご覧ください。
非構造化 JSON カラムを掘り下げるには JSON パス記法を使用します。