use-semantius

use-semantius Skill

Semantiusは、セマンティックデータモデル、エンティティ、フィールド、リレーションシップ、アクセスルールを定義すると、REST API、自動生成 UI、分析レイヤーを備えた、完全に管理された PostgreSQL データベースをすぐに利用できるローコードプラットフォームです。データがどのようなものか（レイヤー 1）を定義すれば、Semantius がストレージとクエリ（レイヤー 2）、テーブルをまたいだ分析（レイヤー 3）を処理します。

semantiusは、3 つのサーバー、すなわちcrud（スキーマ管理とレコード操作）、cube（CubeJS 互換の分析）、組み込みのutils（CSV の構造解析、ホスト間でのエンティティとモジュールの移動）に、シェルとエージェントからアクセスできる公式 CLI です。

---

アーキテクチャ：3 つの独立したレイヤー

どのレイヤーで作業するかを把握すると、使用するツールが決まります。

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: Semantic Data Model                               │
│  Defines entities, fields, modules, relationships, RBAC     │
│  Tables: entities, fields, modules, permissions, roles...   │
│  Tools: create_entity, create_field, create_permission...   │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Business Data (PostgreSQL via PostgREST)          │
│  Actual records in your entity tables: /products, /orders   │
│  Tools: postgrestRequest (GET/POST/PATCH/DELETE)            │
│         sqlToRest for SQL→PostgREST conversion              │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Analytics (CubeJS-compatible API)                 │
│  Multi-table queries, aggregations, metrics, time-series    │
│  Tools: cube discover → validate → load / chart             │
└─────────────────────────────────────────────────────────────┘

目安：

• 何が存在するか（スキーマ、権限、ロール）を定義する → レイヤー 1 の型付きツール
• 単一のテーブル内の実際のレコードを扱う → レイヤー 2 の postgrestRequest
• テーブルをまたいでクエリする、または集計／メトリクスが必要 → レイヤー 3 の cube

---

リファレンスファイル

ファイル	読むタイミング
references/cli-usage.md	CLI コマンドとその階層、認証情報とホスト、オプション、シェルのパターン、コマンドの連結、インストール。「Moving Entities and Modules Between Hosts」セクション
references/data-modeling.md	レイヤー 1、エンティティ、フィールド、モジュール、リレーションシップ、安全な進化。「Enum values and labels」セクション
references/entity-families.md	レイヤー 1、サブタイプと拡張（id_type: is_a / has_a、id_refentity）：使用するタイミング、作成順序、レベル間の読み取りと書き込み、制限、削除、エラーコード。このようなエンティティで最初のcreate_entityを実行する前に読んでください
references/jsonlogic.md	レイヤー 1、JsonLogic ルール：computed_fields、validation_rules、拡張演算子、エンティティ間の検索、動的なinput_type_rule（条件付きの読み取り専用／非表示／必須）
references/select-rule.md	レイヤー 1、行レベルのセキュリティ：select_rule、各行を閲覧できるユーザー、REPLACE と AND のセマンティクス、管理者が締め出されるリスク
references/rbac.md	レイヤー 1、権限、ロール、ユーザーの割り当て、階層
references/crud-tools.md	レイヤー 1 の型付きツールと、レイヤー 2 の postgrestRequest／sqlToRest のリファレンス。「Bulk operations」セクション（配列data／id、レコードの各セットにつき 1 回の呼び出し）
references/cube-queries.md	レイヤー 3、CubeJS クエリ DSL、日付フィルタリング、分析モード
references/cube-tools.md	レイヤー 3、検出／検証／読み込み／チャートのツールシグネチャ
references/webhooks.md	署名付き Webhook レシーバーを通じて外部システムからレコードを受信する方法：設定、署名、ログ
references/lucide-icon-finder.ts	読まずにbunで実行してください：<query…>（それぞれ 1 語以上。具体性の高いものから順に指定）を指定すると、各クエリに対応する Lucide アイコン名が指定順に一覧表示されます。data-modeling.md →「Icons are Lucide icons」を参照
references/lucide-icon-checker.ts	読まずにbunで実行してください：アイコン名を記述する前に<name…>を指定すると、Lucide アイコン名を確認できます。終了コード 1 の場合、不明な名前が表示されます。data-modeling.md →「Icons are Lucide icons」を参照
references/vendor-names.ts	読まずにbunで実行してください：entity:<Name>…とfield:<Name>…を指定すると、対象製品のレコード名とフィールド名（単数形で、製品独自の表記）をtable_nameとラベル、またはfield_nameとラベルに変換します。手作業で変換しないでください。semantius-architect（stage-2-naming.md）とsemantius-analyst（stage-4-fields.md）が使用します

---

クイック判断ガイド

スキーマの管理、エンティティ、フィールド、モジュールの作成・変更ですか？ → レイヤー 1。references/data-modeling.md を読み、必須の作成順序に従ってください。

1 つのものに複数の種類がある（「メールと通話はどちらもアクティビティ」）、またはレコードが兼ねることもできるもの（「ビジネスパートナーは顧客にもなれる」）ですか？ → レイヤー 1。作成前に references/entity-families.md を読んでください。is_a、has_a、列挙型フィールド、個別のエンティティのどれを選ぶかが決まり、作成順序も変わります（レベルごとに create_entity を 1 回呼び出し、基底エンティティから作成します）。選択は作成時に確定するため、ユーザーに確認してください。

計算フィールド、検証ルール、または条件付きフィールドの動作（レコードに応じて読み取り専用／非表示／必須になるなど）ですか？ → レイヤー 1。references/jsonlogic.md を読み、エンティティレベルおよびフィールドレベルの JsonLogic、演算子、エンティティをまたぐ参照を確認してください。

一部のユーザーに対してのみ、レコードへの特定の操作（削除、クローズ、承認、特定フィールドの変更など）を許可しますか？ → レイヤー 1。references/jsonlogic.md § 操作の判定 を読んでください。エンティティの edit_permission は挿入、更新、削除をまとめて制御します。そのため、1 つの操作または状態遷移に対する制限は、$mode（または変更されたフィールド）を判定する検証ルールにし、その後、呼び出し元を確認します。$old.owner_user_id == $user_id のように所有者が一致するかを確認する場合、権限は不要ですが、has_permission を使う場合は権限が必要です。権限は references/rbac.md に従って作成してください。

権限、ロール、ユーザーの設定ですか？ → レイヤー 1。references/rbac.md を読んでください。

ユーザーが参照できる行を制限しますか（select_rule による行レベルセキュリティ）？ → レイヤー 1。references/select-rule.md を読んでください。注意：空でないルールを設定すると、読み取り時には view_permission が置き換えられます。has_permission の選択肢を含まないルールを設定すると、管理者も締め出されます。

単一のテーブルでレコードの挿入、読み取り、更新、削除を行いますか？ → レイヤー 2。postgrestRequest を使ってください。詳細は references/crud-tools.md を参照してください。

同じ種類のレコードを複数（多数のフィールド、権限、行）作成、更新、削除しますか？ → ループではなく、1 回の呼び出しで行ってください。create_* では data に配列を、update_*／delete_* では id／table_name に配列を指定します。postgrestRequest の POST では、配列 body（キーはすべて同一）を使ってください。ゴールデンルール 7 と references/crud-tools.md § 「一括操作」を参照してください。

複数のテーブルにまたがるクエリ、集計、時系列の推移、トップ N、指標ですか？ → レイヤー 3。cube を使い、references/cube-queries.md と references/cube-tools.md を読んでください。

シェルスクリプトの作成、または CLI コマンドの連結ですか？ → references/cli-usage.md を読んでください。

CSV ファイルのインポートですか？ → まず semantius-importer スキルを使います。ファイルを解析し（utils/get_csvschema）、エンティティを作成または再利用して、バッチで一括読み込みします。

エンティティまたはモジュールを別のホストに移動する、バックアップする、エクスポートを復元する作業ですか？ → semantius-transfer スキルでワークフローを実行してください。手順については references/cli-usage.md § 「ホスト間でのエンティティとモジュールの移動」を参照してください。

トランザクションメールの送信ですか？ → レイヤー 2 のユーティリティを使います。crud sendEmail を使い、references/crud-tools.md § 「sendEmail」を参照してください。

（semantius-skill-maker が生成したスキルなどの）作成済みレシピで予期しない 409／422 が発生し、スキーマの不整合が疑われますか？ → read_entity／read_field で実行時にスキーマを調査してください。references/data-modeling.md § 「実行時のスキーマ調査（ライブ FK／形状の参照）」を参照してください。レシピを黙って適応させないでください。処理を中止して不整合を明示し、ドメインスキルの再生成を推奨してください。

環境のセットアップ

1. semantius はインストールされていますか？ semantius --version を実行します。シェルで見つからない場合（POSIX では command not found／終了コード 127、PowerShell では CommandNotFoundException）、インストール済みでも、このセッションの PATH にまだ追加されていない可能性があります。%LOCALAPPDATA%\Programs\Semantius\semantius.exe（Windows）、または /usr/local/bin/semantius と ~/.local/bin/semantius（Linux／macOS）を確認します。見つかった場合は、これらのスキルで semantius と記載されている箇所で、フルパスを指定して実行してください（references/cli-usage.md §「エージェントからのインストール」）。どこにも見つからない場合は、停止してください。semantius コマンドは実行せず、references/cli-usage.md §「インストール」に記載されている、使用シェル向けのインストールコマンドと、ガイド https://www.semantius.com/docs/cli/use-semantius/ をユーザーに伝えてください。

2. 接続されていますか？ references/cli-usage.md §「接続の確認」の手順に従います。要点は次のとおりです。

• 確認（semantius whoami、または必要な getCurrentUser 呼び出し）。終了コード 0 の場合は接続済みです。使用中の認証情報を確認する必要がある場合は、ホスト、その host_source、および auth_method を示してください。終了コードが 0 でも、§「認証情報：最初に一致したものを使用」には 2 つの注意点があります。
• 終了コード 3： 1 回だけ再試行し、その後エラーを表示して停止します。
• MISSING_ENV_VAR または終了コード 5： whoami で current と表示されている場合を除き、ホストをユーザーに確認してから semantius use <host> でサインインします。まだインスタンスを持っていないユーザーは https://app.semantius.com で登録してください。登録すると、ホスト（<org>.semantius.app）と接続手順が案内されます。例外：意図的なキーまたはトークンの設定で、エラーに SEMANTIUS_API_KEY または SEMANTIUS_JWT の名前が含まれている場合は、エラーを表示して停止します。
• その他の場合： エラーを表示して停止します。

ユーザーのサインイン（§「ユーザーのサインイン」）：semantius use <host> は以降のすべてのディレクトリで、後続のすべてのコマンドに使うホストを切り替えるため、ユーザーが作業対象として指定したホストに対してのみ実行してください。semantius login --host <host> は、ホストを切り替えずにサインインします。logout は決して実行しないでください。サインインはバックグラウンドで実行し、その URL をユーザーに伝えてください。ユーザーがこのマシンの画面を見ていない場合は、必ず --login-flow device を追加します。

whoami、ping、hosts は安全な読み取り専用の診断コマンドです。コマンド、ティア、ホストと認証情報の優先順位については、references/cli-usage.md を参照してください。

---

CLI の基本コマンド

semantius                              # List all servers and tools
semantius -d                           # List with descriptions
semantius info <server>               # Show tools for a server
semantius info <server> <tool>        # Get tool JSON schema
semantius grep "<pattern>"            # Search tools by glob
semantius call <server> <tool> '{}'   # Call tool with inline JSON
semantius call <server> <tool>        # Call tool — reads JSON from stdin

Windows（PowerShell）：インライン JSON を必ず渡すか、引数を取らないツールの場合は空の入力をパイプしてください。 JSON 引数を省略すると、CLI は EOF まで標準入力を読み取ろうとして停止します。一部のエージェントハーネスのように、状態が保持される PowerShell セッションでは、標準入力のパイプが閉じられないため、エラーもタイムアウトも発生せず、呼び出しが永久にハングします。これはネットワークや認証の問題ではなく、再試行しても解決しません。空の場合でも、必ず JSON を明示的に指定してください。

semantius call crud getCurrentUser '{}'     # inline JSON, never blocks
"" | semantius call crud getCurrentUser     # or explicitly pipe stdin closed

Windows／PowerShell では、上記のいずれかの形式を使わずに、引数なしの semantius call ... をそのまま実行しないでください。

info <server> <tool> と info <server>/<tool> は、どちらも同じように使用できます。

---

2 つのサーバー

crud：スキーマ管理＋レコード操作（レイヤー 1、2）

レイヤー 1 の型付きツールは、セマンティックデータモデルを管理します。create_entity、create_field、create_module、create_permission、create_role などが該当します。これらは Semantius 独自のスキーマテーブルを操作します。すべての create_* では、data に単一のオブジェクト、またはオブジェクトの配列（1 回の呼び出しで複数のフィールド、権限、ロールを指定）を渡せます。また、すべての update_*／delete_* では、id（エンティティの場合は table_name、権限の場合は permission_name）に単一の値、または配列を渡せます。

**レイヤー 2 の postgrestRequest**は、実際のビジネスデータを操作します。定義したエンティティはすべて、PostgREST 経由でアクセスできる PostgreSQL テーブルになります。

# Read records from your 'products' entity
semantius call crud postgrestRequest '{"method":"GET","path":"/products?status=eq.active&order=name.asc"}'

# Insert a new order record
semantius call crud postgrestRequest '{"method":"POST","path":"/orders","body":{"customer_id":"123","total":99.99}}'

# Insert several records in ONE call — array body; every row carries the same keys (raw PostgREST rule)
semantius call crud postgrestRequest '{"method":"POST","path":"/orders","body":[{"customer_id":"123","total":99.99},{"customer_id":"124","total":15.00}]}'

# Update matching records
semantius call crud postgrestRequest '{"method":"PATCH","path":"/products?category=eq.electronics","body":{"on_sale":true}}'

詳細は references/crud-tools.md を参照してください。

cube：CubeJS 互換の分析（レイヤー 3）

cube サーバーは CubeJS 互換の API を実装しています。CubeJS をご存じであれば、クエリ DSL は同じです。結合、集計、または PostgREST だけでは効率的に表現できないメトリクスが必要な場合に使用します。

必ず最初に discover を呼び出してください。スキーマ、クエリ言語の完全なリファレンス、日付フィルタリングのガイドが返されます。

完全なリファレンス：references/cube-queries.md、references/cube-tools.md

---

Web UI へのリンク

Semantius の Web アプリでレコードや一覧をユーザーに示す場合はいつでも、作成後、検索後、クエリ結果の報告時など、クリック可能なリンクが生の JSON より適している場面では、getCurrentUser の ui_baseurl からリンクを作成してください。これはスキーマの作業とは無関係です。レイヤー 1 のスキーマ変更だけでなく、レイヤー 2 のレコード操作にも適用されます。

• エンティティのレコード一覧：{ui_baseurl}/{module_slug}/{table_name}
• 特定のレコード：{ui_baseurl}/{module_slug}/{table_name}/{id}

例：https://mytest.semantius.app/it-ops-starter/service_requests/5

• getCurrentUser から ui_baseurl を取得してください（semantius call crud getCurrentUser '{}'）。組織のホストをハードコードしないでください。
• パスには、表示名の module_name ではなく、小文字の module_slug を使用してください。

詳細：references/crud-tools.md § getCurrentUser。

---

厳守事項

1. 書き込む前に読み取ること。create_* を実行する前に、必ず read_* を呼び出して重複がないか確認してください。必ず最初に行います。
   • create_module の前に → まず read_module を実行
   • create_entity の前に → まず read_entity を実行
   • create_permission の前に → まず read_permission を実行
   • create_role の前に → まず read_role を実行
   • 読み取り結果がある場合は、重複を作成せず、その ID を使用してください。結果が空の場合にのみ作成します。
   • 一括作成の場合は、in.(...) フィルターを使った read_* を1 回実行すれば、すべての項目を確認できます（"filters": "field_name=in.(description,cost)&table_name=eq.services"）。レコードごとに --single の読み取りを実行してはいけません。
2. スキーマを最初に作成します。モジュール → 権限 → すべてのエンティティ → フィールドの順です。手順を飛ばさず、フィールドを作成する前に、モデルのすべてのエンティティを作成してください。これにより、各フィールドの reference_table（自己参照を含む）がすでに存在する状態になります。例外： is_a / has_a エンティティの場合は、基底エンティティを先に作成し、それを基にするエンティティをレベルごとに create_entity 呼び出し 1 回で作成します。フィールドはすべてのレベルの作成後に作成してください（references/entity-families.md）。
3. 自動生成フィールドは作成しないでください。 id、label、created_at、updated_at、および label_column フィールドは、create_entity によって自動的に作成されます。is_a / has_a エンティティでは、基底エンティティのフィールドも作成しないでください。そのエンティティ独自のフィールドのみを作成します。また、create_field では field_order も指定しないでください。プラットフォームは新しいフィールドを配列順に追加しますが、手動で指定した値が自動作成フィールドと意図せず同じになることがあります（ラベルフィールドの値は 20 です）。特定の位置をユーザーが希望する場合に限り、エンティティの最新の field_order 値を読み取ってから設定してください。
4. reference_table を指定する場合は、リレーショナル形式が必須です。 reference_table を持つフィールドには、必ず format: "reference" または format: "parent" を指定してください。例外はありません。
5. リスクのある変更の前に警告すること。table_name / field_name の変更、およびエンティティやフィールドの削除には、ユーザーの明示的な確認が必要です。
6. 役立つ場合は、必ず UI リンクをユーザーに提示すること。スキーマの変更後、およびレコード操作（作成／検索／更新）の後に提示します。形式：{ui_baseurl}/{module_slug}/{table_name}。単一レコードの場合は /{id} を追加します。ルールについては、上記の「Web UI へのリンク」を参照してください（getCurrentUser から ui_baseurl を取得し、小文字の module_slug を使用します）。
7. 常に一括処理を行うこと。同じ種類のレコードは 1 回で処理し、個別の呼び出しを繰り返してはいけません。 同じ種類のレコードが複数ある場合（エンティティの複数のフィールド、モジュールの複数の権限、複数の role_permission 行、更新または削除する複数の ID、テーブルの複数の行など）は、1 回の呼び出しで送信してください。create_* には data 配列を渡し（'{"data": [{...}, {...}]}'）、update_* / delete_* には id 配列を渡します（エンティティでは table_name、権限では permission_name を指定。例：'{"id": [4, 5, 6]}'。同じ data がすべての ID に適用されます）。配列の各項目で、同じキーを指定する必要はありません。ある項目でキーが省略されている場合は、その列のデフォルト値が使われます。1 回の呼び出しが 1 リクエストであり、1 トランザクションです（すべて成功するか、すべて失敗します）。レスポンスは常に、影響を受けたレコードの配列です。1 回の呼び出しは、およそ 100 行／ID までにしてください。配列で 1 回の呼び出しが可能なのに、レコードごとに N 回呼び出すのは誤りです。順序に関する唯一の例外は、ファミリーのエンティティです。基底エンティティを先にして、レベルごとに create_entity を 1 回呼び出してください。postgrestRequest も配列の body を受け取りますが、PostgREST の生のルールに従います（項目ごとに同一のキーを指定するか、パスに ?columns= を指定します。省略されたキーは NULL になります）。詳しくは references/crud-tools.md の「Bulk operations」を参照してください。

レスポンスの処理：終了コードだけでは不十分です

crud サーバーは、1 行だけに一致するクエリでも、デフォルトでは JSON 配列を返します。0 行に一致する GET は、本文が [] のまま終了コード 0 を返します。これはプロトコル層では成功ですが、ドメイン層では「見つかりません」です。終了コードだけを成功の判定基準にすると、空の結果が気づかれずに後続処理へ渡され、依存する書き込みがすべて破損します。

これは postgrestRequest だけでなく、すべての crud ツールに当てはまります。 型付き Layer-1 ツールも配列を返します。read_entity、read_module、および create_*／update_*／delete_* ツールはすべて、単独のオブジェクトではなく [{...}] を出力します。また、一括呼び出し（配列の data、配列の id）では、影響を受けたすべてのレコードがその配列に出力されます。そのため、create_role のレスポンスに対する jq -r '.id' は Cannot index array with string で失敗します。配列をインデックス指定して jq -r '.[0].id' を使うか、--single を渡して単独のオブジェクトを取得してください（単一レコードの呼び出しのみ。data／body／id／table_name が配列の場合、--single は拒否されます）。さらに望ましいのは、新しい行の id を作成レスポンス自体から読み取らないことです。エコーバックされた表現は、id／自然キーを確実に保持する手段ではありません。作成後に自然キーで再読み込みしてください（モデラーの ensure／ensureMany ヘルパーがまさにこれを行います。一括処理全体に対して 1 回の in.(...) 読み込みを行います）。こうすれば、配列とオブジェクトの違いが jq に渡ることはありません。

crud に対して読み取る方法は2 つあります。呼び出しの意図に合った方法を選んでください。

パターン A：1 行だけを想定する場合の --single

必ず 1 行に解決される必要がある読み込み（id、一意な列、またはレシピですでに一意性が確認されている複合キーによる検索）では、postgrestRequest に --single を渡してください。CLI は内部で PostgREST の Accept: application/vnd.pgrst.object+json ヘッダーを設定し、レスポンスをエージェントのシェル契約に合わせて変換します。

結果	終了コード	stdout
ちょうど 1 行	0	{"id":"...", ...}（単独のオブジェクト、配列ではありません）
0 行	1	stderr にエラー
2 行以上	2	stderr にエラー
引数／設定／JSON の不備	1	stderr にエラーメッセージ
ネットワーク／トランスポート（一時的、再試行可能）	3	stderr にエラーメッセージ
ツールの実行失敗（RLS、重複キー、スキーマ）	4	stderr にエラーメッセージ
認証失敗（API キーの欠落／無効、401、403）	5	stderr にエラーメッセージ

終了コード 1 は、「0 行」と「引数の不備」という 2 つの異なるケースを表すことに注意してください。適切に記述されたスクリプトの通常稼働時には、「0 行」の意味だけが実行時に発生するため、標準的なガード（「見つからない、または曖昧」）は明確です。引数の不備を示す 1 はレシピのバグであり、エンドユーザーに届くことはありません。

終了コード 3 と 5 は意図的に分けられています。3 は一時的なエラー（1〜2 回再試行）、5 は永続的なエラー（ユーザーが認証情報を修正できるよう、ただちに通知）です。これらを条件分岐に使うレシピでは、stderr を解析せずに case $? in 3) retry ;; 5) abort ;; esac を実行できます。

終了コードが「見つからない」ケースを直接示すようになりました。標準的なスクリプトパターンは、1 つのガードにまとめられます。

row=$(semantius call crud postgrestRequest --single "{\"method\":\"GET\",\"path\":\"/<table>?<unique-filter>\"}") \
  || { echo "step N: <entity> '<value>' not found or ambiguous" >&2; exit 1; }
# $row is the bare object: {"id":"...", ...}
# Parse with jq '.id' or grep -oE '"id":"[^"]+"' (no head -n1, no [0] index).

ドメインスキルでの読み込みの大半には、--single が適切なパターンです。「id による検索」、すべての eq.<unique-column> による解決、ジャンクションのレシピにおける親行の読み込みで使ってください。0 行または複数行の結果が通常の分岐ではなくドメインエラーとなる場合は、必ず使用してください。

パターン B：配列（デフォルト）。0 行または複数行が想定される場合

件数自体が答えとなる読み取りでは、--single を省略します。 重複チェック（「この中間テーブルの行はすでに存在するか？」）や、一覧取得、 バッチ読み取りが該当します。この場合、レスポンスは配列となり、 エージェントは返された内容を知るために本文を確認する必要があります。

結果	終了コード	stdout	対応
行が見つかった	0	[{...}, ...]	その行を使用します
行が見つからなかった	0	[]	重複チェック／一覧取得の答えは「なし」です。それに応じて処理します
引数／設定／JSON が不正	1	stderr にエラーメッセージ	引数を修正します。再試行しないでください
ネットワーク／トランスポートの一時的なエラー	3	stderr にエラーメッセージ	1、2 回再試行してから、ユーザーに伝えます
ツールの実行に失敗（RLS、重複キー、スキーマ）	4	stderr にエラーメッセージ	ユーザーに伝えます。通常、実際のバグまたは書き込みの競合です
認証の失敗（API キーの欠落／無効、401、403）	5	stderr にエラーメッセージ	中止してユーザーに伝えます。再試行しないでください

空かどうかによって業務上の解釈が決まる、配列を返す読み取りの標準的なパターン：

rows=$(semantius call crud postgrestRequest "{\"method\":\"GET\",\"path\":\"/<table>?<filter>&select=id\"}") \
  || { echo "step N (<what>) failed" >&2; exit 2; }
if ! printf '%s' "$rows" | grep -q '"id"'; then
  # zero rows, the recipe's "go ahead and create / no duplicate" branch
  ...
else
  # one or more rows, the recipe's "already exists / use existing" branch
  ...
fi

どちらを選ぶか

読み取りの目的	パターン
<title> を feature の行に解決する	--single（タイトルが存在しないと、レシピを続行できません）
id で親の行を読み取る	--single
(feature_id, user_id) の中間テーブルの行が存在するか確認する	配列（0 行は通常の「作成」分岐です）
ステータスごとにすべての feature を一覧表示する	配列
書き込みが反映されたことを確認する	--single（その行が存在する必要があります。たった今書き込んだためです）
一括処理が完了したことを確認する（残存する行が 0 件）	配列（1 行であることを確認するのではなく、行数を数えます）

書き込み（POST / PATCH / DELETE）

成功した POST または PATCH は、挿入／更新された行を返します （Prefer: return=minimal が設定されている場合は [] を返しますが、 プラットフォームではデフォルトで設定されません）。DELETE は削除された行を返します。したがって、 0 行に一致した書き込みにも、「終了コード 0 ＋ [] は何もしていない」という同じルールが適用されます。 行に一致しないフィルターを使った PATCH は、何も報告せずに成功します。--single は単一レコードの書き込み （ちょうど 1 行に影響する必要がある POST/PATCH）でも使用でき、 変更が反映されたことを確認する最も簡潔な方法です。状態を変更する操作では、必ず読み取り直して確認してください。

一括書き込みの結果は常に配列で返されます。--single は使用しません。 配列の data を指定する create_*、配列の id（または table_name）を指定する update_*／delete_*、 あるいは配列の body を指定する postgrestRequest は、常に影響を受けたレコードの配列を返します。 反映された行ごとに 1 要素が含まれます。CLI はそのような呼び出しで --single を渡すと、 送信前に拒否します（終了コード 1、SINGLE_ARRAY_INPUT）。配列を指定する場合は、 明示的に "accept": "application/vnd.pgrst.object+json" を渡すことも絶対に避けてください。 一括書き込みは件数（jq 'length' が送信した行数と一致すること）か、 in.(...) フィルターを指定した後続の read_* で確認します。一括呼び出しは 1 つのトランザクションです。 失敗した場合、その呼び出しで反映された内容はありません。原因を修正して同じ呼び出しを再実行してください。 単一レコードの呼び出しをループする方法に切り替えないでください。