コレクションとデータ

コレクションはボット独自のデータテーブルです。申し込み、注文、ダイアログからの回答、ゲームのスコア、レッスン予約など、ボットがユーザーから収集したり連携から受け取ったりするデータを格納するのに便利です。セクションは左側メニューのデータ → コレクションにあります。

コレクションとは

コレクションはフィールド（列を定義するスキーマ）とレコード（データの行）で構成されます。各レコードはコレクションのフィールドに対応する値のセットであり、内部では柔軟な JSON ドキュメントとして保存されるため、新しいフィールドを追加してもコレクションは問題なく機能し続けます。

コレクション名は1つのボット内でユニークであり、リアクションのアクションでの識別子として使用されます（例: leads、orders、scores）。

コレクション作成時に、フィールドの一覧と各フィールドの型を定義します:

型はインターフェースでのフィールド編集方法と、保存時の値の変換に影響します。スキーマは厳格ではありません: スキーマ外のフィールドがレコードに含まれている場合、それも保存されて別の列として表示されます。

コレクションカードにはテーブルアイコンのボタンがあり、そのコレクションのレコードが表示されるデータウィンドウが開きます:

表示 — すべての行がフィールドごとにセル形式でリスト表示されます（最新のものから順に）。
レコードを追加 — コレクションのスキーマに基づくフォームが開きます。各フィールドはその型に応じて編集できます（bool はトグル、json は JSON 入力フィールドなど）。
編集（鉛筆アイコン）— 既存の行を編集します。
削除（ゴミ箱アイコン）— 行を削除します。

レコードはボットのリアクションアクションによって自動的に追加されることもあります（下記参照）。手動編集と自動書き込みは同じコレクションに対して機能します。

コレクションが無限に増大しないよう、自動クリーンアップルールを設定できます:

クリーンアップはバックグラウンドプロセスによって定期的に実行されます。ルールは組み合わせることができます。

コレクションはリアクションコンストラクターと直接連携しています。リアクションのアクションで利用できる操作:

レコードを作成 — 行を追加します。値はテンプレートから取得されます（例: {{user.id}}、{{message.text}}）。重複排除キーを設定することで、同じ呼び出しを繰り返した際に重複を作らず同じ行を更新できます。
レコードを更新 — 条件に一致する行を変更します。
レコードを照会 — 実行コンテキストに行を配列として読み込み、後で反復処理できます。
レコードを削除 — 条件に一致する行を削除します。
ループ（for-each） — コンテキストの配列を反復処理し、各要素に対してネストされたアクションを実行します（例: コレクションのリストに対してメッセージを一斉送信）。

これにより、ボットは外部データベースを使わずに CRM を運用し、申し込みを蓄積し、ポイントを付与し、レポートを生成できます。

コレクションのレコードはボットの Telegram Mini App から読み取ることができます: フロントエンドがフィルターと制限を指定してコレクションデータを名前で要求します。これにより、ユーザーの注文履歴やリーダーボードを Telegram 内で直接表示できます。

フィールドには短いマシンフレンドリーな名前（email、total、paid）を付けてください — リアクションテンプレートでの使用が便利になります。
べき等な書き込み（例:「ユーザーごとに1件の申し込み」）には重複排除キーを使用してください。
ログや一時データにはリテンションを有効にして、コレクションが肥大化しないようにしてください。
値の構造が事前に決まっていない場合は json 型が適しています。