pipefy-database-tables

データベーステーブル

MCP クライアント：［references/mcp.md］(references/mcp.md)をお読みください。CLI ユーザー：［references/cli.md］(references/cli.md)をお読みください。以下の例では、共通の操作引数について説明します。

Pipefy Database Tables のテーブル、レコード（行）、スキーマ列（テーブルフィールド）、添付ファイルを扱います。

---

共通パターン

• CreateTableFieldInput／UpdateTableFieldInput などの入力には、introspect_type を使用します。
• ページネーション： get_table_records と find_records は first／after に対応しています。デフォルトのページサイズは 50 です。
• フィールド値がわかっている場合は、ページネーションを使った get_table_records よりも find_records を使用します。field_id と field_value を指定した 1 回の呼び出しのほうが、get_table_records を N ページ取得するより効率的です。

---

テーブル操作

操作	読み取り専用	目的
get_tables	はい	ID を指定してデータベーステーブルを読み込みます。
search_tables	はい	名前でテーブルを検索します。
get_table	はい	テーブルのメタデータとフィールドスキーマを取得します。
create_table	いいえ	新しいデータベーステーブルを作成します。
update_table	いいえ	名前または設定を変更します。
delete_table	いいえ	破壊的な操作です。事前に確認し、承認を得てください。

---

テーブルフィールド（スキーマ列）の操作

操作	目的
create_table_field	テーブルスキーマに列を追加します。
update_table_field	列名、説明、必須設定、またはオプションを変更します。
delete_table_field	破壊的な操作です。事前に確認し、承認を得てください。 table_id が必要です。

---

レコード操作

操作	読み取り専用	目的
get_table_records	はい	テーブル内のすべてのレコードをページネーションで取得します。
find_records	はい	field_id と field_value でレコードを絞り込みます。get_table_records のページネーションよりもこちらを推奨します。
get_table_record	はい	入力済みのすべてのフィールド値を含む単一のレコードを取得します。
create_table_record	いいえ	テーブルに行を追加します。
update_table_record	いいえ	行の title、due_date、または status_id を更新します。それ以外のキーはエラーにならずに破棄されます。
set_table_record_field_value	いいえ	行のフィールド値を 1 つ設定します。すべてのテーブルフィールドに使用してください。
delete_table_record	いいえ	破壊的な操作です。事前に確認し、承認を得てください。

---

手順 — レコードの検索と更新

1. テーブル ID を取得する（不明な場合）：

   操作：search_tables(table_name="Customers") を実行し、結果からテーブル ID を選択します。

2. レコードを検索する（ページネーションではなく find_records を使用）：

   操作：find_records(table_id=456, field_id="email", field_value="[email protected]")

3. フィールドを 1 つ更新する（対象を指定）：

   操作：set_table_record_field_value(record_id=789, field_id="status", value="Active")

   レコードのメタデータを更新する（タイトル、期限、ステータスなど）：

   操作：update_table_record(record_id=789, fields={"title":"Updated title"})

---

破壊的な変更を確認する

削除する前に、影響を受けるデータを表示し、明示的な承認を得てください。操作ごとに、次の内容をプレビューします。

• delete_table — テーブルの名前とフィールド数を表示します。get_table はレコード数を返しません。スキーマを確認したうえで GraphQL を使うか、実行可能であればすべてのレコードをページごとに取得して、レコード数を確認してください。件数が不明な場合は、その旨を明確に伝えてください。テーブルを削除すると、すべての行とスキーマが失われます。
• delete_table_record — ユーザーが削除される行を特定できるよう、レコードのタイトルと主なフィールド値を表示します。
• delete_table_field — フィールドの名前と型を表示し、列のデータがすべて完全に失われることを明示して警告します。

影響を受けるデータを事前に確認せずに削除してはいけません。

---

成功条件

• get_table_records が、作成または更新されたレコードを正しいフィールド値とともに返します。
• スキーマの変更が get_table に直ちに反映されます。

障害モード

• get_table_record／get_table_records は空のフィールドを省略します。 レコードには値が設定されたフィールドのみが返されるため、完全なスキーマを取得するために get_table を呼び出さない限り、「フィールドが未設定」なのか「フィールドが存在しない」のかを判別できません。
• create_table_record のタイトルは通知なく上書きされます。 テーブルの最初のフィールドが開始フォーム形式のラベル列である場合、Pipefy はそのフィールドの値をレコードの title として使用し、title パラメーターを無視します。最初のフィールドがラベル形式の列に値を自動入力する場合は、title に依存しないでください。
• create_table_field が型を拒否します： 有効なフィールド型を確認するには、introspect_type(type_name="CreateTableFieldInput") を呼び出してください。
• update_table_record はカスタムフィールドをエラーなしで無視します： title、due_date、status_id のみを送信し、それ以外のすべてのキーを破棄します。この3つのいずれも含まれていない場合にのみ失敗します。各カスタムフィールドは set_table_record_field_value で設定し、その後 get_table_record でレコードを再取得してください。
• find_records が空の結果を返します： field_id が、get_table で確認できるフィールドの ID（ラベルではありません）と一致していることを確認してください。
• ページネーションカーソルの有効期限が切れました： 最初から再取得してください。カーソルの有効期間は短いです。

関連項目

• pipefy-relations — テーブルをパイプに接続します（テーブル関係 ID の名前空間に関する注意点も記載しています）。
• pipefy-introspection — フィールド入力スキーマを確認します。