データバックエンド
IronFlockは各プロジェクトにTimescaleDB搭載のプライベートデータベースをプロビジョニングします。アプリがデータスキーマを定義すると、デバイスがアプリに追加された瞬間にIronFlockがテーブルを作成してデータ収集を開始します。
仕組み
.ironflock/data-template.ymlでデータスキーマを定義します。- IronFlock SDKを使用してエッジコードからデータを送信します。
- IronFlockはアプリがインストールされた各プロジェクトにデータベーステーブルを自動的にセットアップします。
- データはデバイスからメッセージングシステムを経由してプロジェクトデータベースに流れ込みます。
各プロジェクトは独自の物理データベースを持ちます — プロジェクト間でのデータ共有はありません。
ユーザーは、そのプロジェクト内でアプリが収集するデータを完全に管理できます。開発者としてこのデータにアクセスすることはできません。
データスキーマの定義
.ironflock/ディレクトリにdata-template.ymlファイルを作成します:
data:
tables:
- tablename: sensordata
columns:
- id: tsp
name: Timestamp
description: Timestamp of measurement
path: args[0].timestamp
dataType: timestamp
- id: temperature
name: Temperature
description: Temperature reading in Celsius
path: args[0].temperature
dataType: numeric
- id: humidity
name: Humidity
description: Relative humidity percentage
path: args[0].humidity
dataType: numeric
- id: device_id
name: Device ID
description: Source device identifier
path: args[0].device_id
dataType: stringカラムオプション
| フィールド | 説明 |
|---|---|
id | 内部カラム識別子(タイムスタンプカラムにはtspを使用) |
name | ボードで表示される人間が読みやすいカラム名 |
description | オプションの説明 |
path | 送信されたデータオブジェクト内の値へのパス(例:args[0].temperature) |
dataType | timestamp、numeric、string、booleanのいずれか |
secret | このカラムを保存時に暗号化し、通常の読み取りでは決して平文で返しません — 後述のシークレットカラムを参照 |
シークレットカラム
保存はしなければならないものの、決して表示してはならない値があります。APIトークン、デバイスのパスワード、ライセンスキーなどです。カラムにsecret: trueを指定すると、データバックエンドが挿入時にそれを暗号化します:
- tablename: credentials
columns:
- id: tsp
dataType: timestamp
- id: device_id
dataType: string
- id: api_token
dataType: string
secret: trueそれ以降、通常の読み取りが平文を返すことは一切ありません — そのデータを書き込んだアプリ自身に対してもです:
| 読み取り経路 | 返ってくるもの |
|---|---|
| 履歴の読み取りとリアルタイムの行:ボード、ウィジェット、SDK、そのテーブルを読み取る他のアプリが受け取るもの | プレースホルダ__secret__ |
| SQL(SQLクエリコンソール、データエクスポート、FleetDB AccessのPostgresログイン)とデータベースのバックアップ | 保存された暗号文ifsec:1:… |
| SDKのreveal関数 | 復号された値 |
NULLはどこでもNULLのままなので、「設定済みだが非表示」と「一度も書き込まれていない」は引き続き区別できます。
シークレットを平文で読み戻せるのは、アプリ自身のコンテナからSDK経由で行う場合だけです — SDKリファレンスのシークレットカラムを参照してください。ボードや他のアプリがそれを取得する手段はまったくありません。だからこそ「平文で決して表示されない」が、見せかけではなく事実になります。
シークレットを失わずに行を更新する。エンティティテーブルでは、行を編集するクライアントが本物のシークレットを送り返すことは決してできません — 読み取りで得られたのは常にプレースホルダだけだからです。そのためデータバックエンドは、書き込み時のプレースホルダ__secret__(およびボードが表示するマスク••••••••)を直前の値を維持するという意味に解釈し、シークレットカラムが省略された場合も同様に維持します。明示的にnullを送信するとシークレットはクリアされます。したがって、ボードのフォームで機械の説明を編集しても、そのアクセスコードが消えることはありません。
ここから2つの帰結が導かれます。リテラル文字列__secret__および••••••••自体をシークレット値として保存することはできず(生のifsec:…暗号文も入力として拒否されます)、エンティティキーのないテーブルではプレースホルダの書き込みは拒否されます — 維持すべき直前の行が存在しないためです。
次の点は指針ではなくハードな制約なので、あらかじめ設計に織り込んでおいてください。
- シークレットカラムは文字列のみです。暗号化はテキストを生成するため、
numeric、boolean、timestampのカラムをシークレットにすることはできません。必須のtspカラムもシークレットにはできません。 - シークレットカラムでフィルタ、グループ化、ソートを行うことはできません。各行はそれぞれ独自のランダムな値で暗号化されるため、同じシークレットを保持する2つの行は異なる暗号文を保存します。シークレットカラムに対する等価フィルタ、
GROUP BY、ORDER BY、DISTINCTは、原理的に機能しません。「この値は一致するか?」に答えるには、何も返さずにデータバックエンド内部で比較を行うSDKのverify関数を使用してください。 - シークレットカラムをエンティティキーにすることはできません。行ごとに暗号文が異なるため、エンティティごとの最新の行を読み取ると、各行がそれぞれ別のエンティティとして扱われてしまいます。そのため、
maintainLatestFlagForでシークレットカラムを指定することは明確に拒否されます。
最後の2つの制約はデータテンプレートの検証時にチェックされます。そのため、これらに違反するテーブルは、後から不正に動作するのではなくリリース時に失敗します。
テーブルオプション
columnsのほかに、テーブルの説明方法とデータの経年管理を制御するオプションキーがいくつかあります。
data:
tables:
- tablename: sensordata
description: 製造現場の環境測定値
chunkTimeInterval: 1 hour
dropAfter: 30 days
columns:
# ...| フィールド | 説明 |
|---|---|
tablename | テーブル名 |
description | オプションの説明。UIに表示され、AIエージェントがテーブルを理解するために使用します |
chunkTimeInterval | テーブルを分割する時間パーティションのサイズ。デフォルトは7 days |
dropAfter | 保持期間 — これより古いパーティションは自動的に削除されます |
downsample | 長期ウィンドウのチャートを高速化するための事前集計済みコピーを維持します — 後述の継続的ダウンサンプリングを参照 |
maintainLatestFlagFor | 一意のエンティティを識別するカラム — 後述のエンティティの最新状態の追跡を参照 |
private | このテーブルを他のアプリから隠します — 後述の他のアプリとのデータ共有を参照 |
chunkTimeInterval は、時系列データをディスク上でどう分割するかを決めます。1つのパーティションが一度に問い合わせるデータ量とおおよそ一致するように選んでください。毎秒収集されるような高頻度データは小さなチャンク(分〜時間)が、変化の遅いデータは大きなチャンク(週)が適しています。これはアプリのデフォルト値にすぎず、プロジェクトの所有者は後から自身のデータバックエンドで調整できます。
dropAfter は、テーブルをローリングウィンドウに変えます。指定した期間より古いパーティションはまるごと削除されるため、行を1件ずつ削除するよりはるかに低コストです。クリーンアップジョブはdropAfter / 4の間隔で実行されるため、レコードはパーティションが削除されるまで、最大で期間の4分の1だけ有効期限を超えて残ることがあります。データを無期限に保持するにはdropAfterを省略してください。
いずれもPostgreSQLの間隔文字列を取ります — 30 minutes、1 hour、7 days、6 months。
継続的ダウンサンプリング
ダッシュボードはデータベースにデータの集計を依頼できます — 1時間ごとの平均、1日ごとの合計、機械ごとの件数など。これを生レコードから計算するのは、1日分であれば問題ありませんが、1年分となると高コストです。テーブルにdownsampleを追加すると、プラットフォームは継続的に更新される事前集計済みのコピーを維持し、長期ウィンドウのクエリにはそのコピーから応答するようになります:
data:
tables:
- tablename: sensordata
dropAfter: 30 days
downsample:
bucket: 1 minute
keepFor: 2 years
paths:
- payload.temperature
columns:
# ...| フィールド | 説明 |
|---|---|
bucket | 事前集計済みコピーの粒度。デフォルトは1 minute |
keepFor | ダウンサンプリング済み履歴を保持する期間。省略すると無期限に保持されます |
paths | 対象に含めるJSONフィールドのパス。ダッシュボードと同じ記法を使用します |
bucket は、チャートに提供できる最も細かい解像度です。これよりはるかに細かいバケットを要求するチャートは、代わりに生テーブルを読み取ります。1日を均等に分割する1 secondから1 dayまでの固定幅の間隔(1 minute、5 minutes、1 hourなど)を指定できます。デフォルトの1 minuteは実質的にあらゆるダッシュボードに適しています。バケットを粗くすると、ストレージと書き込みスループットのコストが下がります。
keepFor は、そもそも長期履歴を可能にするための設定です。生レコードはdropAfterによって消えていきますが、ダウンサンプリング済みのコピーは独自の保持期間を持ちます。生データを30日、ダウンサンプリング済みデータを2年間保持すれば、ボードはごく一部のストレージで2年分の1時間平均をチャート表示できます。dropAfterより長く設定してください — 逆の設定は誤設定としてプラットフォームが拒否します。
paths は、ダウンサンプリングをJSONカラム内の値にも広げます。数値カラムは自動的に含まれますが、JSONカラムには固定のキー集合がないため、JSONフィールドは明示的に指定する必要があります。宣言されていないフィールドもダッシュボードでは問題なく動作します — 単に生テーブルから計算されるだけです。
これ以外はすべて自動です。すべての数値カラムについて統計(平均、合計、最小値、最大値、最初の値、最後の値、レコード件数)が維持され、テーブルのエンティティキー(maintainLatestFlagFor、またはデータを送信したデバイス)でグループ化されます。ダッシュボード側に設定は不要で、その存在を意識する必要もありません。ウィジェットは通常どおりクエリを実行し、プラットフォームがクエリごとに事前集計済みコピーで応答できるかを判断します — 応答できない場合、例えばコピーがグループ化していないカラムをフィルターが参照している場合などは、透過的に生テーブルへフォールバックします。
スキーマ変更はコピーを再構築します。ダウンサンプリング対象テーブルのカラムを追加・削除・型変更した場合、あるいは
downsampleブロック自体を編集した場合、事前集計済みコピーは生テーブルから再構築されます。dropAfterより古いものは復元できず、失われます。可能な限りテーブルと同時にこのブロックを設定し、長期運用しているテーブルへの後からのスキーマ変更は意識的な判断として扱ってください。
エッジコードからのデータ送信
IronFlock SDKを使用してアプリからデータを送信します:
Python
from ironflock import IronFlock
flock = IronFlock()
await flock.start()
await flock.publish_to_table("sensordata", {
"timestamp": "2025-01-15T10:30:00Z",
"temperature": 23.5,
"humidity": 62.1,
"device_id": "sensor-001"
})すべての行には、必須のtspカラムの値が必要です。tspのない行は、データバックエンドが拒否します。SDKのテーブル書き込みはエラーで失敗し、ボードが公開した行は破棄されて、アプリのerror-logsテーブルにエントリが1件残るだけです。上のsensordataの定義ではpath: args[0].timestampでこのカラムをマッピングしているため、tspは行のtimestampフィールドから取得されます。pathのないカラムは、行内の同名のフィールド(args[0].<id>)を読み取ります。このマッピングがなければ、各行に独自のtspフィールドが必要です。
高頻度データの場合は、1 行ごとにラウンドトリップを行う代わりに、publish_rows_to_table / publishRowsToTable / PublishRowsToTable または append_rows_to_table / appendRowsToTable / AppendRowsToTable を使用して、複数の行を 1 つのメッセージで送信できます — この 2 つは同じもので、どちらも挿入結果を報告します。各バッチはアトミックに挿入されます — オール・オア・ナッシングです。詳細についてはSDK リファレンスを参照してください。
変換テーブル
生データを自動的に集計・処理するSQL変換を定義できます:
data:
tables:
- tablename: sensordata
columns:
# ... 生データカラム ...
transforms:
- tablename: hourly_averages
materialize: true
schedule: "0 * * * *"
sql: >
SELECT
time_bucket('1 hour', tsp) AS hour,
avg(temperature) AS avg_temp,
avg(humidity) AS avg_humidity
FROM sensordata
GROUP BY hour
columns:
- id: hour
name: Hour
dataType: timestamp
- id: avg_temp
name: Average Temperature
dataType: numeric
- id: avg_humidity
name: Average Humidity
dataType: numeric| フィールド | 説明 |
|---|---|
tablename | 派生テーブルの名前 |
materialize | trueの場合、結果は保存され、スケジュールに従って更新される。falseの場合、変換はビューとなり、読み取りのたびに計算される |
schedule | 変換を実行するタイミングのcron式。5 項目(分、時、日、月、曜日)、または先頭に秒の項目を加えた 6 項目で指定する。*/5 * * * * は 5 分ごと、*/10 * * * * * は 10 秒ごとに実行される。実行のたびにマテリアライズされた結果が更新され、変換にバインドされたボードに現在の結果が送信される。アプリのコードからも、このような実行をオンデマンドで行える。オンデマンドでの更新を参照 |
sql | 変換を計算するSQLクエリ |
columns | 出力のカラム定義 |
変換テーブルは、通常のテーブルと同様にボードやSDK経由でアクセスできます。
変換は、自身の SQL が返すとおりに読み取られます。ウィジェットの時間ウィンドウ、カレンダーフィルター、latest モードはテーブルに適用されるものであり、変換に対しては無視されます。ここから 3 つのルールが導かれます。時間範囲はクエリの中で区切ること(WHERE tsp > now() - interval '7 days')、時系列は新しい順に並べて(ORDER BY <time column> DESC)行数制限がかかっても新しい行が残るようにすること、そしてボードでプロットまたはフィルターに使うカラムをすべて選択すること — 変換に暗黙のタイムスタンプカラムやデバイスカラムはありません。1 回の読み取りで返るのは最大 3000 行なので、クエリの中で集計してください。
変換は、テーブルの読み取りでは表現できないもののためにあります:結合、比率、複数のテーブルの現在の行にわたる集計などです。エンティティの現在の状態を表示したり、削除済みレコードを非表示にしたりするための手段ではありません。それらはテーブル自身の読み取りモード、すなわち latest トグルと deleted カラムに対するフィルター(後述)であり、ライブで動作します:テーブルにバインドされたウィジェットは、新しい行をすべて 1 秒以内に追従します。変換がボードに届くのはそのスケジュールのタイミングだけ(あるいは、アプリのコードが自身の書き込みの後に変換を更新したとき。ボードでの保存がこれを引き起こすことはありません)なので、エンティティごとの最新の行を選び出したり削除済みの行を除外したりするビューは、同じ結果を遅れて表示することになります。変換がエンティティテーブルの現在の状態を本当に必要とする場合(たとえば別のテーブルと結合するとき)は、その SQL の中で DISTINCT ON を使って選択し、deleted のチェックもそこで行ってください。順序はレコードの論理削除に示すとおりです。
変換を手に入れる方法は、アプリに同梱することだけではありません。データアクセス権限を持つプロジェクトメンバーは、アプリをまったく使わずに、プロジェクトのデータビューから同じ種類の変換を保存できます。AI アシスタントも同様です。カスタム変換を参照してください。
マテリアライズド変換が更新されるタイミング
スケジュールされた実行がマテリアライズド変換を更新するのは、変換が読み取るテーブルに前回の更新以降の書き込みがあった場合だけです。ただし、それとは関係なく少なくとも10分ごとに更新されます。新たに読み取るものがない実行では、保存済みの結果はそのまま残ります。たとえば、1時間に1行しか届かないテーブルを読み取る、毎分実行のスケジュールの変換は、その行が届いた後に更新され、それ以外のときは10分ごとに更新されます。
書き込みがなくても結果が変わりうる場合、マテリアライズド変換は実行のたびに更新されます:
- SQLが現在時刻や乱数を使用している場合(
now()、CURRENT_DATE、random()など) - 同じ入力に対して異なる結果を返しうる関数を呼び出している場合:揮発性(volatile)関数、またはPostgreSQLに組み込まれていない安定(stable)関数
- アプリのテーブルとマテリアライズド変換以外のもの(たとえば、マテリアライズドでない変換、ダウンサンプリング済みコピー、プラットフォーム自身のテーブル)を読み取っている場合
多数の変換が同時に実行時刻を迎えると、プラットフォームは一度に少数ずつ更新し、残りは順番を待ちます。そのため、更新の完了がスケジュール上の時刻より遅れることがあります。同じ変換の前回の更新がまだ実行中または待機中のときに実行時刻を迎えた実行はスキップされます。
オンデマンドでの更新
アプリ自身のコードは、スケジュールを待たずに変換の実行を起動できます:SDKのrefresh_transform / refreshTransform / RefreshTransformは、マテリアライズされた結果を更新し(通常のビューは読み取られるだけです)、変換にバインドされたボードに現在の結果を送信します。そのため、アプリが書き込んだばかりのバッチがボードにすぐに表示されます。スケジュールされた実行と同じルールが適用されます:変換が読み取るテーブルに前回の更新以降の書き込みがなければ更新はスキップされ(スキップされたことが報告されます)、同じ変換の更新が実行中のときに届いた呼び出しはその後ろで待機する1回の更新を待ち、変換ごとに開始される更新は1秒あたり最大1回です。SDKのテーブル書き込みは返る前にコミットされているため、書き込みに続けて更新を行っても、その書き込みが取りこぼされることはありません。アプリの変換を更新できるのは、そのアプリ自身のコンテナだけです。ボードは行を受け取り、別のアプリのデータを消費するアプリはその変換を読み取れますが、更新はできません。プロジェクトのデータビューから保存された変換はどのアプリにも属さず、スケジュールでのみ実行されます。refreshTransform / refresh_transform / RefreshTransformを参照してください。
エンティティの最新状態の追跡
機械、資産、生産オーダーなど、現実世界のエンティティの現在の状態を表すテーブルに対して、IronFlockは最新状態追跡と呼ばれるパターンをサポートしています。
変更があったときに行を上書きする代わりに、常に新しい行を追加します。ユニークなエンティティを識別するカラムを宣言しておくと、IronFlockはテーブルが読み取られるたびにエンティティごとの最新の行を導出します。これにより、すべての変更の完全な履歴を保持しながら、現在の状態のみを簡単にクエリできます。
maintainLatestFlagForでテーブルに有効化します:
- tablename: machineform
maintainLatestFlagFor: ['machinename']
columns:
- id: tsp
dataType: timestamp
- id: machinename
dataType: string
- id: machinetype
dataType: string
- id: active
dataType: boolean
- id: description
dataType: stringmaintainLatestFlagForには、ユニークなエンティティを識別するカラムのリストを指定します。行そのものには何も書き込まれません。IronFlockはそのエンティティキーとタイムスタンプでテーブルにインデックスを作成し、クエリ時にエンティティごとの最新の行を選び出します。そのため、遅れて到着した行や順序が前後した行が古いマークを残してしまうことはありません。
エンティティテーブルは、エンティティとタイムスタンプの組み合わせごとに1行を保持します。保存済みの行とエンティティキーおよびtspの両方が一致する行は拒否されます。エンティティキーとtspの両方が互いに一致する2行を含むバッチも拒否されます。SDKの書き込みはURI_ENTITY_KEY_CONFLICTで失敗し、アプリのerror-logsテーブルにその拒否が記録されます。エンティティの各バージョンには、それぞれ固有のtspを付けてください。エンティティキーのカラムが空(NULL)の行は、どのエンティティにも属しません。重複として拒否されることはなく、最新状態の読み取りからは除外されます。
部分的な行によるエンティティの更新
エンティティテーブルに追加される行は、そのエンティティの新しいバージョンです — そして、行は完全である必要はありません。行に含まれていないカラムは、そのエンティティの直前の最新の行から引き継がれます。そのため、1つのフィールドだけを更新するには、エンティティキー、タイムスタンプ、そのフィールドだけを送信すれば済みます:
| 新しい行のカラムの状態 | 保存されるバージョンが保持する値 |
|---|---|
提供されている(0、false、""も提供済みとみなされます) | 提供された値 |
明示的にnull | NULL — カラムはクリアされます |
| 存在しない | 直前の最新の行の値 |
カラムを空にするには、null(PythonではNone、Goではnil、C#ではnull)として送信します。省略すると直前の値が保持されます。意図せずフィールドを省略してしまうコードに注意してください。たとえば、値がundefinedのJavaScriptプロパティはペイロードから除外されます。言語ごとのケースはSDKリファレンスにまとめています。
押さえておきたい詳細が2つあります:
- すべてのカラムを提供する行は、直前の行の参照を完全にスキップします。そのため、完全な行はこれまでどおり低コストのままです — 高頻度の経路では引き続き完全な行を送信してください。
- 引き継ぎは時間を尊重します。古いタイムスタンプで到着した行(バックフィル)は、自身の
tsp以前の行からのみ引き継ぎ、それより新しい行から引き継ぐことは決してありません。
maintainLatestFlagForのないテーブルは、単純な追記のセマンティクスを維持します。行に含まれていないカラムはNULLとして保存されます。
現在の機械状態のみをクエリするには:
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC特定の機械の全履歴を表示するには:
SELECT * FROM machineform WHERE machinename = 'Assembly-Line-01' ORDER BY tspこのクエリを手書きすることはほとんどありませんし、変換として保存すべきでもありません。このテーブルに接続するボード上のウィジェットには、フィルタ設定にlatestトグルが用意されており、ユーザーは追加作業なしで常に現在の値を確認できます。このトグルはライブで動作します。ウィジェットはテーブルの新しい行を届いた時点で受け取り、そのエンティティの以前の行をそれで置き換えるため、変更は書き込みから1秒以内に表示され、テーブルにはすべてのバージョンが残ります。スケジュールによる再計算は一切なく、変換が付け加えるのはまさにその再計算だけです。SDKからは、filterAndに{"latest": true}を追加することで同じモードをリクエストできます — getHistoryを参照してください。
latest_flagからの移行:以前のバージョンのIronFlockは、latest_flagという物理的なブーリアンカラムを保存していました。このカラムはもう存在せず、現在の状態は代わりにSQLで導出されます。これにより、行が順不同で到着した場合でも正しい結果が保たれます。latest_flag = trueでフィルタする既存のボードやSDK呼び出しはそのまま動作します。IronFlockがそれらを認識し、最新状態モードを適用するためです。新しいコードでは、latestトグルまたは{"latest": true}フィルタエントリを使用してください。
エンティティキーの変更
アプリのバージョンがリリースされると、そのアプリの各テーブルのエンティティキーは固定されます。クラウドIDEのサイドパネルにあるデータ構造を更新と新しいリリースのビルドは、アプリの最新リリースに含まれるテーブルのエンティティキーを変更するdata-template.ymlを拒否します:
maintainLatestFlagForへのカラムの追加、削除、置き換え、または順序の変更maintainLatestFlagForがなかったテーブルへのmaintainLatestFlagForの追加、またはその削除
このような変更は、アプリをインストールしたすべてのプロジェクトで、テーブルが返す内容を黙って変えてしまいます。キーに新たに加わったカラムは既存のすべての行で空であり、最新状態の読み取りではキーカラムが空の行が除外されるため、既存のエンティティがすべて消えてしまいます。キーから削除されたカラムは、行のタイムスタンプが同じエンティティ同士を1つに統合してしまう可能性がありますが、テーブルはエンティティとタイムスタンプの組み合わせごとに1行しか保持できません。
別のエンティティキーを使用するには、新しいキーで新しいテーブルを作成し、たとえばアプリのコードからデータをそのテーブルに移してください。データの移行はアプリに任されています。まだどのリリースにも含まれていないテーブルは、開発中であればエンティティキーを変更できます。このルールが導入される前にリリースされたアプリバージョンでは、引き続きエンティティキーを変更できます。ただし、そのバージョンに更新するプロジェクトはデータ構造の更新を拒否し、以前のデータ構造を維持します。
エンティティとタイムスタンプが重複する行
IronFlockがエンティティとタイムスタンプごとに1行を強制するようになる前に書き込まれたテーブルには、重複が残っている場合があります。エンティティキーを変更した開発用テーブルも同様です。データサービスがそのようなテーブルをセットアップするとき(起動時、またはデータ構造の更新後)、重複している各グループのすべての行を同じデータバックエンド内の<table>__entitykey_dupesという名前のテーブルに移動し、各グループから1行を元のテーブルに戻します。以降、そのテーブルは重複を拒否します。アプリのerror-logsテーブルのエントリに、移動された行数が示されます。
新しいテーブルは、移動された各行をそのまま保持し、2つのカラムを追加します。移動した時刻を示すquarantined_atと、元に戻された行を示すrestoredです。どの行が戻されるかは任意で、これは最新状態の読み取りでも以前から同じでした。プロジェクトのデータビューのクエリコンソールで、databackend_<key>.<table>__entitykey_dupesとしてクエリしてください。元のテーブルがプライベートの場合、新しいテーブルもプライベートになります。行を移動できなかった場合は、error-logsのエントリにその理由が示され、データサービスは次回の起動時に再試行します。
レコードの論理削除
IronFlockの追記専用モデルでは、レコードは物理的に削除されません。代わりに、deletedブーリアンカラムを使用してレコードを削除済みとしてマークします。これにより、ダッシュボードから削除されたレコードを非表示にしつつ、完全な監査証跡を保持します。
任意のエンティティテーブルにdeletedカラムを追加します:
- id: deleted
name: Deleted
dataType: booleanユーザーがレコードを削除すると(例えばボード上のフォーム経由で)、アプリはそのエンティティに対してdeleted: trueの新しい行を送信します。maintainLatestFlagForと組み合わせることで、この新しい行が最新の状態になります。その後の部分的な行は、他のカラムと同様にdeletedマーカーを引き継ぎます。そのため、deletedに言及しない更新がエンティティを復活させることも、非表示にすることもありません。
アクティブ(未削除)の現在のレコードのみをクエリするには:
SELECT * FROM (
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC
) latest
WHERE deleted IS NULL OR deleted = falsedeletedのチェックは、機械ごとの最新の行が選び出された後に実行されます。この順序が重要です。先に削除済みの行を除外してしまうと、その前の未削除の行が現在の状態として再び現れてしまいます。
ボードウィジェットとSDKは、同じ順序を自動的に適用します。latestトグル(または{"latest": true})とdeletedフィルタを組み合わせれば、まさにこの動作が得られます。削除されたレコードはフォーム送信直後にダッシュボードから消えますが、データベースには履歴および監査目的で残ります。
ボード上では削除フォームがレコードを削除します。削除フォームとは、送信ボタンに削除と表示され、非表示のチェックボックスフィールドがレコードのキーと一緒にdeletedカラムへtrueを書き込むフォームです(データの削除を参照)。レコードを一覧表示するウィジェットは、テーブルそのものをフィルタします。一覧を整理するためのビューや変換は必要なく、仮に作ったとしても、削除が反映されるのは次のスケジュール実行のときになります。
他のアプリとのデータ共有
データバックエンドはアプリ専用です。プロジェクトにインストールされた他のアプリからテーブルは見えません。data-template.ymlの2つのオプションキーがこれを変えます。
他のアプリのデータを読み取るには、読み取り元のアプリをトップレベルのconsumes:セクションに列挙します。data:の中ではなく、その隣に置きます。
consumes:
- app: machine-monitor
reason: "モニターの機械状態およびカウンターストリームからOEEを算出します"
data:
tables:
- tablename: oee_results
columns:
# ... 通常どおり、自アプリのテーブルappは提供側アプリの技術名、またはプロジェクト内のすべてのアプリを表す"*"(引用符が必須)です。reasonは同意ダイアログでユーザーに表示されます。宣言しただけでは何も許可されず、ユーザーの承認が必要です。
個別のテーブルを非公開にするには、private: trueを指定します。定義したものはデフォルトで共有可能ですが、プライベートなテーブルやトランスフォームは他のアプリが見るカタログに一切現れません。
data:
tables:
- tablename: measurements # 共有(デフォルト)
columns: [ ... ]
- tablename: calibration_state # 内部用 — 他のアプリからは決して見えない
private: true
columns: [ ... ]アクセスは読み取り専用で、プロジェクトごとにユーザーが許可し、いつでも取り消せます。モデル全体と、提供側アプリの履歴・ライブストリームを読み取るSDK呼び出しについては他のアプリのデータの利用を参照してください。
特権アクセス
アプリのコンテナはデバイスから隔離され、Dockerのデフォルトの権限で実行されます。シリアルポートやUSBアダプター、GPIO、CANやBluetoothのインターフェース、ホストネットワークなど、それ以上を必要とするアプリもあります。これが特権アクセスです。特権アクセスを持つアプリは、他のアプリとそのデータを含め、デバイス全体を制御できます。そのため、アプリは特権アクセスをリクエストする必要があり、付与するかどうかはユーザーが決めます。
リクエストするには、reasonを含むprivileged:セクションをトップレベルに追加します。data:の中ではなく、その隣に置きます。
privileged:
reason: "シリアルポート/dev/ttyUSB0経由でPLCを読み取ります"
data:
tables:
# ... 通常どおり、自アプリのテーブルreasonは必須です。同意ダイアログでユーザーに表示されるため、アプリを信頼するかどうかを判断する人に向けて書いてください。
テーブルのないアプリは、privilegedの隣にdata: {}と書きます。data:キーのないdata-template.ymlは公開できません。
ユーザーが許可する内容は、アプリの構成によって異なります。
- 単一イメージのアプリ(
Dockerfileのみ)は、ユーザーが許可すると特権モードで実行され、すべてのLinuxケーパビリティ、デバイスの/dev、ホストのD-Busを利用できます。宣言がない場合は、ホストのデバイス、追加のケーパビリティ、ホストのD-Busなしで実行されます。リリースはそれでも公開され、そのビルドログに警告が表示されます。 - Docker Composeのアプリは、
docker-compose.ymlが要求する設定だけを受け取り、同意ダイアログにはその一覧が表示されます。composeファイルが以下の設定のいずれかを使う場合、アプリはprivilegedを宣言する必要があります。宣言がないとリリースの公開は失敗し、エラーにはサービスと設定が示されます。composeファイルがどれも使わないのにprivilegedを宣言した場合も失敗します。
次のcompose設定が特権とみなされます。
| 設定 | 特権とみなされる条件 |
|---|---|
privileged | false以外のすべての値 |
cap_add、devices、device_cgroup_rules | エントリがある |
security_opt | no-new-privileges以外のエントリがある |
network_mode、pid、ipc、uts、userns_mode、cgroup | hostまたはcontainer:…に設定されている |
cgroup_parent | 値が設定されている |
サービスのvolumes | ホストのパス(/…、~/…、C:\…)、アプリのフォルダー外のパス(../…)、または名前付きパイプをマウントする。読み取り専用の/etc/localtimeと/etc/timezoneは問題ありません。 |
volumes_from | container:…を指定する |
トップレベルのvolumes | ボリュームにdriver_opts、external、または固定のnameがある |
トップレベルのnetworks | ネットワークがbridge以外のdriver(macvlan、ipvlan、hostなど)またはdriver_optsを設定している、externalである、または固定のnameがある |
トップレベルのsecrets、configs | エントリがアプリのフォルダー外のfileを読み込む |
名前付きボリューム、デフォルトのbridgeドライバーを使うネットワーク、アプリのフォルダー内のバインドマウント(./config:/config)、公開ポート、GPUの予約(gpus、deploy.resources.reservations.devices)は特権ではありません。
これらの設定で${VAR}プレースホルダーを使うことはできますが、特権とみなされるため、やはり宣言が必要です。これにより、アプリパラメータでユーザーがシリアルポートを選べるようになります。
services:
plc:
build: .
devices:
- "${SERIAL_PORT}:/dev/ttyS0"include、またはfileを指定したextendsを使うcomposeファイルは、宣言の有無にかかわらず公開できません。リリースにはdocker-compose.ymlしか含まれないためです。ほかのファイルはそこに統合してください。
アプリに必要な分だけをリクエストしてください。シリアルポートが1つだけ必要なら、単一イメージやprivileged: trueではなく、サービス1つとdevices: [/dev/ttyUSB0]だけのcomposeファイルを書きます。ユーザーはアプリが得るものを正確に確認でき、アプリはそれ以上のことができません。
同意と取り消し
- インストール時には、
reasonと、composeアプリの場合は設定の一覧がユーザーに表示され、ユーザーが特権アクセスのオン/オフを切り替えます。拒否してもインストールが妨げられることはありません。 - アップデート時には、新しいバージョンが特権アクセスをリクエストしていて、プロジェクトがまだ許可していない場合、アップデートダイアログで確認されます。拒否してもアプリはアップデートされ、新しいバージョンは特権アクセスなしで実行されます。
- その後、特権アクセスはプロジェクトのアプリ設定のスイッチになり、ユーザーはいつでも取り消したり許可したりできます。実行中のデバイスは新しい設定でアプリを再起動します。
クラウドIDEからの開発モードでの実行は宣言に従い、スイッチはありません。.ironflock/data-template.ymlがprivilegedを宣言していれば開発ビルドは特権モードで実行され、宣言していなければ特権アクセスなしで実行されます。composeファイルが宣言なしで特権設定を使う場合、開発ビルドは公開時と同じエラーで失敗します。
許可がない場合
アプリはそれでも起動します。単一イメージのアプリはDockerのデフォルトで実行され、/devも追加のケーパビリティもホストのD-Busもありません。composeアプリの場合、デバイスエージェントはアプリを起動する前にcomposeファイルから特権設定を削除し、どのサービスからどの設定を削除したかをアプリのログに書き込みます。開けないシリアルポートなど、到達できないものがある場合は、クラッシュせずにそれを報告するようにコードを書いてください。
以前のリリース
アプリが特権アクセスを宣言する必要が生じる前に公開されたリリースは、特権アクセスをリクエストしているものとみなされます。既存のインストールもそれを保持するため、これらのアプリは従来どおり動作します。ユーザーは他のアプリと同様に、プロジェクトのアプリ設定で取り消せます。次のリリースからは、アプリに必要であればprivilegedを宣言してください。