コレクションとデータ
問い合わせ、注文、授業の予約を GetMyBot 内に保存します。表を作り、データを追加してリアクションで使う方法を説明します。
このページの内容
コレクションは表のようなものです。1 行に問い合わせ 1 件、注文 1 件、授業の予約 1 件などを保存します。ボットはユーザーの回答から行を追加でき、あなたはデータ → コレクションで確認・編集できます。
たとえば相談予約用に、name、phone、topic というフィールドを持つ leads コレクションを作ります。ボットが質問した後、名前、電話番号、相談内容を 1 行に保存します。その記録は後で検索してリアクションに使えます。
コレクションとは
フィールドは「電話番号」「相談内容」などの列です。レコードには 1 行分の値が入ります。フィールドと型の一覧をスキーマと呼びます。技術的にはレコードは JSON 文書で、新しいフィールドを加えても既存の行を作り直す必要はありません。
コレクション名は 1 つのボット内で一意で、リアクションのアクションから参照する識別子です。例:leads、orders、scores。
フィールドの型
作成時に各フィールドの型を指定します。
| 型 | 保存するもの | 用途の例 |
|---|---|---|
text | 文字列 | 名前、メール、コメント |
number | 数値 | 金額、個数、点数 |
bool | はい/いいえ:true / false | 注文の支払い済みか |
datetime | 日付と時刻 | 授業の予約日時 |
json | 入れ子のオブジェクトやリスト | 商品の属性を含む注文内容 |
型によって画面での入力方法と保存時の変換方法が変わります。ただしスキーマは厳格ではありません。スキーマ外のフィールドがレコードにあっても保存され、別の列として表示されます。
コレクションを作成する
- データ → コレクションを開き、追加を押します。
- 名前を付けます。リアクションで参照しやすいよう、英数字でスペースを入れない名前がおすすめです。
- フィールドから必要な列を追加し、各列の型を選びます。
- 必要に応じて下記の保存ルールを決め、保存します。
レコードの確認と編集
コレクションカードの表アイコンから、そのコレクションのデータ画面を開けます。
- 表示: 新しい行から順に、各フィールドの値を一覧表示します。
- レコードを追加: スキーマに沿ったフォームを開きます。
boolは切り替え、jsonは JSON 入力欄など、型に合った方法で編集できます。 - 編集(鉛筆):既存の行を変更します。
- 削除(ごみ箱):行を削除します。
リアクションのアクションからも同じコレクションへ自動で記録できます。手動編集と自動記録は、同じデータを扱います。
保存期間(retention)
コレクションが無制限に増えないよう、自動削除のルールを設定できます。
- 最大レコード数: 上限を超えると古い行から削除します。
- 最大保存日数: 指定日数より古い行を削除します。
たとえば一時的なログなら 30 日に設定できます。削除は期限ちょうどではなく、定期処理で行われます。両方の上限を同時に使えます。まだ必要な注文には保存期限を付けないでください。
リアクションからデータを使う
コレクションはリアクションエディターと連携しています。次のアクションが使えます。
- レコードを作成:
{{user_id}}や{{text}}などの置換を使って行を追加します。重複防止キーがあれば、同じキーで再実行したときは新しい行を作らず既存の行を更新します。ユーザー ID をキーにすると、1 人 1 件の最新の問い合わせを保てます。 - レコードを更新: 条件に合う行を変更します。
- レコードを照会: 行を配列として実行コンテキストに読み込み、後続で処理します。
- コレクションのページを読む(
record_page):たとえばカード 2 件ずつ、次ページボタン付きで段階的に読み込みます。 - コレクション全体の集計(
record_aggregate):保存ルールの範囲にある条件一致レコードすべての件数と合計を計算します。最初のページしか読み込まなくても、この計算は限定されません。 - コレクションのアトミックなトランザクション(
collection_transaction):条件を確認し、席の確保と申請作成など複数の変更をまとめて保存します。競合時は途中までの変更も取り消されます。 - レコードを削除: 条件に合う行を消します。
- リストのループ(for-each): コンテキスト内の配列をたどり、行の更新、合計計算、外部サービスへの送信などを各要素に行います。
これにより、外部データベースなしで CRM、問い合わせの管理、ポイント、レポートを作れます。
実践レッスンでは、カタログの続きの表示、条件に合う注文全体の合計、最後の空き枠の予約を扱います。読み込んだリストのページ、コレクションのページ、コレクション全体の集計は別の用途です。次のステップに渡るデータの違いも説明します。
ループは一斉配信の手段ではありません。 1 回のループで扱えるのは最大 500 要素ですが、イベント全体から送信できるのは最大 50 メッセージです。各要素から送ると最初の 50 件は送れても、その後は拒否されます。コレクション内の人へ送るにはセグメントを作って一斉配信を使ってください。速度、停止、配信記録を管理できます。詳しくはアクション → 1 イベントの予算をご覧ください。
カタログ:検索、選択、詳細表示
最初は授業を検索するレッスンを試してください。用意するコレクション、アクションの順序、検索結果が空・複数・古いボタンの場合の確認方法を説明します。
カタログのデータはリアクションと分けて保存します。たとえば products に name と aliases、variants に product_id、name、card を置きます。variants.product_id の編集画面で別のコレクションとの関連付けをオンにし、products、キー _record_id、表示用フィールド name を選びます。関連付けはフィールドの用途を表すだけで、レコードの変更や削除を自動で連鎖させません。
- 受信テキストのリアクションにコレクションを検索(
record_search)を追加します。products、検索語{{text}}、検索フィールドname、別名のフィールドaliases、結果名searchを選びます。別名は文字列または文字列の JSON 配列にできます。検索は大文字小文字とロシア語の е/ё を区別せず、句読点は空白に置き換えます。 searchを元データにして次のステップを選択(branch_result)を追加します。最初に合う分岐だけが実行されます。まず結果が不完全なら検索語を詳しくするよう求め、次に見つからない、あいまいな一致、1 件、複数件を設定します。あいまいな一致では確認を求めます。0 件または 1 件と判断するには結果が完全である必要があります。- 複数の結果にはメッセージの見つかったレコードからボタンを作成を使います。元データ
search、表示用フィールドname、次のリアクションを選ぶと、補助機能がbuttons_from.over = search.rows、文字のテンプレート、carry.selected_id = {{item._record_id}}を設定します。表示フィールドが結果に含まれているか確認してください。詳細なボタン設定も引き続き使えます。 - 次のリアクションに関連レコードを検索(
record_related)を追加します。コレクションvariants、キーproduct_id、値{{ctx.selected_id}}、結果名variantsを指定します。選ばれた商品そのものを読むなら、productsとキー_record_idを使います。関連付けを別の業務キーで保存しているなら、ボタンの補助機能と読み取りアクションで同じキーを選んでください。 - 再び結果によって分岐します。1 件なら
{{ctx.variants.first.card}}で詳細を表示し、複数ならボタンにします。ボタンには ID を渡し、クリック後に最新データを読みます。carryにカードやほかの変更されうる値を保存しないでください。
読み取り結果
search.rows はレコードの一覧、search.count は読み込んだ件数、search.first は最初のレコード、search.first.name はそのフィールドです。各行には _record_id、_score、_match_type が加わります。これら 3 つの名前は予約済みです。結果がなければ、以前の先頭レコードとそのフィールドは消去されます。
search.total は調べた候補の中での一致件数です。total_exact = false はコレクション全体を調べていないこと、truncated = true は件数が制限されたことを示します。その結果を完全と考えたり、コレクション全体で最良の一致が見つかったと保証したりしないでください。1 回のリクエストで調べる上限は 10,000 件、16 MiB です。応答には実際の制限が示されます。返す行数は初期値で最大 100 件、上限 10,000 件です。
検索を試して結果を確認する
検索の編集画面で検索をテストを開き、具体的な文字列や ID を入力します。これは読み取り専用です。次のリアクション、メッセージ、ほかのアクションは実行されません。追加フィルターに置換を使っている場合は、先に具体的な値に変えてください。テストでは行、一致の種類、確認した件数、制限を表示します。プロジェクト、コレクション、設定、アクセス権が変わると古い結果は隠されます。
実行ログには検索フィールド、一致の種類、調べた行数と返した行数、制限、選択した分岐が表示されます。リアクション図では、同じリアクションに向かうすべての条件が示されます。過去の実行を見直す際は、内容への閲覧権があれば、対応するイベントを開いて検索の説明を確認できます。
ボタン作成の補助機能は初期設定で最大 20 個作ります。ボタンの最大数は 1~100 に変更できますが、これは制限でありページ送りではありません。空の一覧からはボタンを作りません。結果が多い場合は、検索語を絞り込む分岐を作ってください。
計算アクションの読み込んだリストの操作補助機能は、件数、最初のレコード、フィールドの合計、表示名の一覧を計算する数式を作ります。計算対象は読み込んだ行だけです。結果が不完全なら、コレクション全体の合計にはなりません。
API と MCP
同じ操作は POST /api/bots/{botID}/collections/{name}/search と /related、および collections:read 権限を使う MCP ツール search_records、related_records でもできます。呼び出しは現在のプロジェクトとリージョンに限定されます。REST のテストには具体的な値を渡し、テンプレートの置換はリアクションのアクション内で実行されます。
結果の処理と条件付きの変更
コレクションの結果を list_transform に渡すと、行の絞り込み、並べ替え、重複削除、ページの取り出しができます。list_aggregate は読み込んだ行から名前付きの集計を計算し、必要ならグループ分けします。どちらもコレクションに限らず、HTTP 応答などのリストで使えます。
同時に走る 2 つの処理が同じ状態変更を繰り返さないようにするには record_update_if を使います。ID、期待するフィールド、新しい値を指定すると、1 レコードについて確認と変更が一体で実行されます。保存した updated、conflict、not_found の状態を branch_value で分岐できます。これはフィルターに合う全行を無条件で更新する方法とは異なります。
設定、制限、例もご覧ください。
申請を一度だけ承認するレッスンでは、状態と所有者の確認、updated、conflict、not_found ごとの返答を扱います。
Mini App からのアクセス
ボットの Telegram Mini App からコレクションを読み取れます。画面側がコレクション名、フィルター、件数上限を指定して取得し、注文履歴やランキングなどを Telegram 内で表示できます。
ヒント
- フィールド名は
email、total、paidのように短くすると、リアクションのテンプレートで使いやすくなります。 - 同じアクションの繰り返しで新しい行を作りたくない場合は、重複防止キーを使います。これを冪等性といいます。
- 一時的なログや不要になるデータには保存期限(
retention)を指定してください。 - 値の構造が決まっていない場合は
json型が便利です。