omnigraph

Omnigraph をローカルで運用する

このスキルには、ローカルまたはリモートにデプロイされた Omnigraph を使用するための運用ルールがまとめられています。スキーマの作成、クエリの記述、データの読み込み、スキーマの変更、グラフ操作の自動化を行う際は、このルールに従ってください。

この手順を使用する前に、omnigraph version とコマンドの --help を確認してください。このスキルは、Omnigraph-Http-Api: 0.13 を含む、現在の CLI／サーバー間の仕様に対応しています。リリース済みの 0.12 仕様には対応していません。エンジンは internal-schema 16 (serves v14 to v16) と報告します。これは、書き込むストレージ形式と、提供する形式の範囲を示しています。新しいグラフでは、システム列に __id／__src／__dst が使用されます。すでに id／src／dst という名前になっているグラフでは、物理列がそのまま維持されます。スタンドアロンの v8 または v9 グラフ（0.11.x で書き込まれたもの）、あるいは v13 グラフは、オフラインの omnigraph upgrade によりインプレースで変換されます。v0.10 のグラフは v6 を使用しているため、0.11 バイナリでまず v9 に移行するか、再構築してください。v0.11 より後へのアップグレードを参照してください。デプロイ済みのバイナリを置き換える前に、移行ガイダンスをお読みください。

skill コマンドを備えた omnigraph バイナリには、そのバイナリ用に作成されたこのスキルのコピーが含まれています。omnigraph skill export <dir> --force は、エージェントがスキルを読み込む場所にコピーを書き出し、omnigraph skill show [<path>] は単一のファイルを出力します。インストール済みの CLI がこのコピーの作成時に使用されたものと異なる場合は、そのコピーを優先してください（バージョンに対応したスキルを参照）。

GQ 2.1 のトラバーサルサポート

0.12.0 では GQ 2.1 がコンパイルされ、トラバーサルに型付きエッジ選択が追加されます。v0.11 バイナリはこの構文を解析できないため、0.12 へのアップグレードが済んでいないデプロイ先には送信しないでください。$a (knows | likes) $b は名前付きのエッジ型を選択します。$a * $b は、取得したスキーマから互換性のある型を選択し、宣言済みの端点ノード型を必要とします。境界を省略した場合は常に {1,1} になります。再帰トラバーサルには、{1,3} のような有限の境界が必要です。$a $e:(knows | likes) $b は、1 ホップの具体的なエッジをバインドし、$e.@type と $e.@id を参照できるようにします。共通プロパティは、すべてのメンバーに互換性のある基本型で存在する必要があります。NULL 許容性と列挙型の値域は拡張されます。

set traversal_work_limit = 1000000; は、選択を使用するステートメントで共有されるトラバーサル行の処理量を制御します。選択性の高い近傍であっても、スキャン前に選択対象のテーブル全体のサイズがカウントされます。この上限を結果の上限で代用することはできません。上限に達するとクエリはエラーで終了し、受信済みの行が部分的な成功として扱われることはありません。過去のワイルドカード対象は拒否されます。スキーマの追加によってワイルドカードの共通プロパティ参照が無効になる場合、保存済みクエリの検証でその追加が拒否されることがあります。トラバーサルとセッション設定を参照してください。

7 つのルール

1. コミット前に lint を実行する — omnigraph lint --schema schema.pg --query queries/foo.gq は、スキーマとクエリの両方を相互に検証します。リポジトリを実行する必要はありません。
2. apply の前に plan を実行する — 成功した schema plan を実行せずに schema apply を実行してはいけません。apply は破壊的ですが、plan は無料です。（クラスター モードにも同じルールがあり、動詞が異なります。cluster apply の前に cluster plan を実行します。plan にはエンジンの実際のマイグレーション手順が含まれます。）
3. ブランチはデータ用、apply はスキーマ用 — 一括データ読み込みはフィーチャーブランチでレビューしてからマージします。スキーマ変更は main に直接適用します。クラスター モードでは、.pg を編集して cluster apply を実行します（--server <name|url> を指定すると、再起動せずに稼働中のサーバーへデプロイします。指定しない場合は、先にサービスを停止する必要があります。クラスター管理のグラフに対して直接 schema apply を実行すると、拒否されます）。マネージドサービスでは、コミットしてから cluster push --managed、cluster plan --managed --rev <rev>、続いて cluster apply --managed --plan <run> を実行します。schema plan／apply はクラスター管理ではないストア用です。
4. 適切な書き込みコマンドを選ぶ — 編集には mutate（型チェック済み、パラメーター化済み）を使用します。一括 JSONL には、ローカルでもリモートでも load を使用し、必須の --mode を指定します（merge は upsert、append は厳密な挿入、overwrite はバッチに含まれるノード／エッジ型のみを置き換えます）。load --from <base> はレビュー用ブランチを一度の操作で作成します。引数なしの load には、既存のターゲットブランチが必要です。
5. すべてをパラメーター化する — .gq の本文や --params に値を文字列補間してはいけません。$var: Type を宣言し、--params で渡します。
6. エージェントの読み取り操作はエイリアスとして公開する — エイリアスにより、読み取り操作名を保存済みクエリの実装から切り離せます。エイリアスは読み取り専用です。提供中の保存済みミューテーションは omnigraph mutate <name> --server ... で実行します。
7. リモートの応答が失われた場合は、結果不明として扱う — データを変更するミューテーションまたは load は、正確なコミットを返しますが、プロキシは公開後に 504 を返すことがあります。ブランチ文には、それぞれ異なる結果／レシートのセマンティクスがあります。タイムアウト時は、再実行する前に、意図した効果と関連する履歴を照合してください。references/remote-ops.md を参照してください。

基本：クエリ、ミューテーション、ロード

以下のパターンは日常的な作業の 80% をカバーしており、このファイルから離れずに正しい .gq と JSONL を作成できます。その他の詳細（複数ホップ、否定、集計、ハイブリッド検索、各種デコレーター）は references/queries.md と references/schema.md に記載されています。

.pg と .gq のコメントには # ではなく、// を使用します（最も多いパースエラーの原因です）。

読み取りクエリ（.gq）

query get_signal($slug: String) {
    match {
        $s: Signal { slug: $slug }   // inline property filter goes in the match block
        $s formsPattern $p           // edge FormsPattern declared PascalCase, traversed lowerCamelCase
    }
    return { $s.slug, $s.name, $p.slug }
}

• 文字列補間はせず、必ずパラメーター化します。 シグネチャで $var: Type を宣言し、--params '{"slug":"sig-foo"}' で渡します。シグネチャが空でも、かっこが必要です：query foo() { ... }。
• エッジの走査には lowerCamelCase を使用します。 スキーマではエッジを PascalCase で宣言します（FormsPattern → formsPattern）。
• システムの識別子には @ を使用します。 $s.@id と $e.@src／$e.@dst を読み取ります。id、src、dst を単独で使うと、宣言済みのユーザープロパティを指します。return { $s } は、@id と Blob／Vector 以外のプロパティを含むオブジェクトを返します。schema show --json は、グラフの物理 system_columns を報告します。GQ では物理名の __id に置き換えないでください。
• リスト／ソート — return の後に order { $s.stagingTimestamp desc } limit 50 を追加します。order がない場合、limit n は有効な行のうち任意の n 件を返すことがあります（対象のサブセットはリリース間で変わる場合があります）。ページを安定させるには、順序を指定してください。
• nearest と rrf には末尾の limit N が必要です — 省略するとコンパイルエラーになります。bm25 に limit は必須ではありませんが、ランキング結果の件数を制限するために指定してください。ランキング演算子は order { } の先頭に置き、対象行も絞り込みます（bm25 はテキストに一致するもののみを保持し、nearest は null のベクトルをスキップします）。まず match／フィルターで対象範囲を指定してからランキングします（order { nearest($d.embedding, $q) } limit 10）。先頭のキーを繰り返してスコアを投影します：return { $d.slug, nearest($d.embedding, $q) as distance }。

ミューテーション（.gq）

トップレベルに mutation { } はありません。各ブロックは名前付きの query で、動詞（insert／update／delete）によって書き込みになります。omnigraph query ではなく、omnigraph mutate で実行してください。（ソースにブランチ文がちょうど1つだけ含まれる場合もあります。branch create|delete|merge|list を参照してください。詳細は references/queries.md をご覧ください。）

query add_signal($slug: String, $name: String, $brief: String, $createdAt: DateTime) {
    insert Signal { slug: $slug, name: $name, brief: $brief,
                    stagingTimestamp: $createdAt, createdAt: $createdAt, updatedAt: $createdAt }
}
query link($from: String, $to: String) { insert FormsPattern { from: $from, to: $to } }
query retitle($slug: String, $t: String) { update Signal set { name: $t } where slug = $slug }
query remove($slug: String)              { delete Signal where slug = $slug }

• NULL 不許可のプロパティはすべて指定する必要があります。 通常、欠けている場合は lint で T12 が報告されます。@embed を持つ NULL 不許可の Vector ターゲットは既知の例外です。ソースのみの insert は lint に通っても、実行時にはベクトルが必要です。明示的に指定してください。書き込みで自動的に埋め込みが行われることはありません。
• 1つのミューテーションは insert／update のみ、または delete のみです。両方を含めることはできません（D₂ ルール。実行時に、効果が生じる前に拒否されます。lint では検出されません）。分割してください。
• エッジの insert では、論理的な from／to エンドポイント ID を指定します。プロパティのないエッジで必要なのはこれらだけで、GQ にネストされた data ブロックはありません。キーのないエッジの insert は厳密な動作で、2回挿入するとエッジが2つ作成されます。作成時にエッジ型の本体で @key(@src, @dst[, prop…]) を宣言できます。この場合、insert は派生 ID に基づいて upsert され、同一の insert は2つのブランチ上でマージ時に収束します。エッジは update できません（T16）。

一括読み込み（JSONL）

{"type":"Signal","data":{"slug":"sig-foo","name":"Foo","brief":"…","stagingTimestamp":"2026-04-14T00:00:00Z","createdAt":"2026-04-14T00:00:00Z","updatedAt":"2026-04-14T00:00:00Z"}}
{"edge":"FormsPattern","from":"sig-foo","to":"pat-bar","data":{}}

omnigraph load --data seed.jsonl --mode merge $GRAPH                                  # --mode is REQUIRED (no default)
omnigraph load --data delta.jsonl --from main --branch review --mode merge $GRAPH     # fork a review branch in one shot

• --mode：merge（論理エンティティ ID に基づいて upsert します。キー付きノードとキー付きエッジの ID は @key のタプルから派生します。merge ファイルを再実行すると、キーのないエッジは重複します）・append（ID が衝突すると失敗します）・overwrite（破壊的で、ステージングされます）。--from <base> は、存在しない --branch をフォークします。load のみを指定する場合は、既存のブランチが必要です。ローカルとリモートの両方で動作します。
• 日付値：Date には暦日文字列（YYYY-MM-DD）、DateTime にはミリ秒までの ISO タイムスタンプ（.123 または .123000。.123456 は拒否されます）を使用します。mutate --params と JSONL の両方で同様です。load では Date に整数のエポック日も使用できます。

実行

omnigraph alias  signal sig-foo                  # operator alias → its bound stored read query
omnigraph query  get_signal --params '{"slug":"sig-foo"}'   # served stored query by name (verb asserts read vs write)
omnigraph query  -e 'query q() { match { $s: Signal } return { $s.slug } limit 5 }'   # ad-hoc/inline (or: --query f.gq <name>)
omnigraph mutate add_signal --query mutations.gq --params '{"slug":"sig-foo","name":"Foo","brief":"Example","createdAt":"2026-04-14T00:00:00Z"}'   # name positional; ad-hoc file source
omnigraph lint   --schema schema.pg --query queries/foo.gq    # after EVERY .gq/.pg edit (no server needed)

.gq 文法

注意が必要なポイントを先に説明し、その後に文法全体を示します。

• スカラー型のパラメーター：String Bool I32 I64 U32 U64 F32 F64 DateTime Date Blob。修飾子：T?（省略可能）、[T]（リスト）、Vector(N)。Intはありません。I64を使用してください。
• 読み取りクエリにはmatchとreturnの両方が必要です（order／limitは省略可能）。変更クエリにはどちらもなく、insert／update／deleteのみを使用します。
• limitにはパラメーターではなく整数リテラルを指定します。limit 50のように指定し、limit $nは使用できません。
• 可変ホップのトラバーサル：$p knows{1,3} $f。上限は有限である必要があります（{1,}は「無制限のトラバーサルは無効です」として拒否されます）。ホップ数は最短経路の距離です。各$_は個別の匿名ノードです。__で始まる変数は予約されています。
• 無向トラバーサル：$p <knows> $fは、どちらの方向のエッジにも一致し、重複は除外されます（両方向に接続するペアも1回だけ現れます）。両端の型が同じエッジのみ使用できます（例：Related: Issue -> Issue）。非対称エッジは拒否されます（T22）。上限（$p <knows>{1,3} $f）や相関ブロック（not { }、exists { }、count { } > 2）と組み合わせられます。
• エッジのバインド：エッジ名の前に$var:を付けると任意でバインドできます。例：$src $w:knows $dst、無向の場合は$a $w:<related> $b。一致したエッジ行をバインドするため、エッジのプロパティをフィルター（$w.confidence = "asserted"）、射影（return { $w.role }）、集計、並べ替えで使用できます。バインドしたトラバーサルはエッジごとに1行を返します（並行するエッジは別々に扱われます）。{min,max}の複数ホップをバインドすること、使用済みの名前を再バインドすること、$w単体を射影することは拒否されます（T23）。
• リテラルと関数呼び出し：now()、date("2026-04-29")、datetime("…T00:00:00Z")、リスト[…]。 starts_with、contains、in、>=、<=、!=、>、<、=、is null、is not null

これらがフィルター演算子のすべてです（$m.number in $numbersは、リスト型のパラメーターまたはリテラルに含まれるかどうかを判定します）。条件はand、or、not、括弧、is null／is not nullで組み合わせられます。フィルターは式がtrueの行のみを残します（オペランドにnullを含む比較の結果はnullです）。文字列の述語は完全一致で、大文字と小文字を区別します。集計関数はcount/sum/avg/min/maxです（count($f) as n）。min／maxはString、Bool、Date、DateTimeも受け付けます。集計関数にはエイリアスを付け、エイリアスで並べ替えます。

• 結果列名は重複できません（T25）：エイリアスを付けた射影の列名が重複する場合は拒否されます。
• 保存済みクエリのメタデータ：パラメーターリストの後に@description("…")／@instruction("…")を指定できます。
• 大文字・小文字の規則：型名は先頭を大文字にします（Signal）。識別子／エッジ名は先頭を小文字にします（formsPattern）。変数には$を付けます。コメントには//と/* */のみを使用できます。

コンパイラーの文法crates/omnigraph-compiler/src/query/query.pestが唯一の正となる情報源です。

CLI リファレンス（簡略版）

表記：<x>は必須、[x]は省略可能、<a|b>は選択肢、…は繰り返し可能です。

グローバルなアドレス指定フラグ：--as <actor>（直接エンジンへの書き込み、rebuild-full-text-indexes、cluster apply／upgrade-ledgerで使用します。提供中のサーバーへの書き込みでは、サーバーがBearerトークンからアクターを解決するため、--asを指定すると拒否されます。また、読み取り動詞では使用できません）、--server <name|url>、--cluster <dir|uri>（クラスター管理ストレージ。主にメンテナンス用）、--graph <id>（--serverまたは--clusterのスコープ内で選択します。管理対象のクエリ、変更、読み込み、コミットの読み取りでは必須）、--profile <name>（$OMNIGRAPH_PROFILE）、--store <uri>、--direct（データコマンドで管理コンテキストを無視します）。位置引数に空きがあるコマンドでは、file://、s3://、またはプレビュー版のaz://も直接指定できます。--config <dir>は、cluster、organization、useのソース／コンテキストフォルダーを選択します。出力：--json。読み取りクエリでは--format <json|jsonl|csv|kv|table>も指定できます（arrowも一覧にありますが、0.12.0では常に失敗します）。書き込みガード：--yesは、破壊的な書き込みでローカル以外の確認を省略します。--quietは、解決されたターゲットの表示を抑制します。 データプレーン — any（--server／--profile 経由でサーブ、または --store／URI 経由で直接実行）：

• query <name> — 名前で指定するサーブされた保存済みクエリ（--server／--profile 経由）、またはアドホックな [<name>] (--query <f.gq> | -e '<GQ>')。<name> でソース内のクエリを選択します。[--params <json> | --params-file <p>] [--branch <b> | --snapshot <id>] [--format <fmt> | --json]。位置引数の URI はありません。--server／--store／--profile で指定します。
• mutate — 同じ形式です（<name> で指定するサーブされた保存済みミューテーション、またはアドホックな --query／-e）。[--params …] [--branch <b>] [--if-commit <graph_commit_id>] [--json]。動詞で種類を指定します。前提条件を満たさない場合、効果はありません。サーブされた mutate は終了コード 4、直接実行（--store）は終了コード 1 で終了します。
• load --data <f.jsonl> --mode <overwrite|append|merge> [--branch <b>] [--from <base>] [--json] — --mode は必須です。--from は存在しない --branch をフォークします。overwrite は表現されている型のみを置き換えます
• blob <get|stat> <node|edge> <TYPE> <ID> <PROPERTY> — Blob セル専用の読み取りです。get は範囲指定／--out に対応し、stat はメタデータを返します
• snapshot [--branch <b>] [--json]
• export [--branch <b>] [--type <T>…]（JSONL をストリーム出力します）
• branch <create <name> [--from <base>] | list | delete <name> | merge <source> [--into <target>] [--delete-branch]> [--json]（--from／--into のデフォルトは main です。mutate -e／query -e 経由の GQ ステートメントとしても利用できます）
• commit <list [--branch <b>] | show <commit_id> | changes <commit_id> [filters…]> [--json]
• diff --from <branch|commit_id> --to <branch|commit_id> [filters…] [--json] — 2 つの読み取り対象間のエンティティ変更をまとめて表示します。branch diff <source> [--into <target>] はブランチをマージベースと照合し、branch merge-base <source> [--into <target>] はそのベースを表示します
• changes <poll [--start now|beginning|after:<id> | --cursor <c>] | baseline --out <snapshot.jsonl>> [filters…] [--json]
• schema show（別名 get）

すべての読み取りクエリはエンジン v2 で実行されます。これは予定されている実行経路であり、唯一の engine 値です。query -e 'explain query q() { … }' はクエリを実行せずに、v2 の論理プラン、物理プラン、および利用可能な DataFusion ツリーを返します。通常のクエリ対象とパラメータ指定フラグを使用します。

サーブされた場合のみ（--server／--profile が必要）：graphs list [--json]

直接実行／ストレージ — --server は受け付けません。init には位置引数の URI が必要です。 schema plan／apply は位置引数の URI または --store を使用します。lint とメンテナンスでは --cluster <dir|file://|s3://|az://> --graph <id> も使用できます：

• init --schema <f.pg> <uri> [--force]
• schema <plan|apply> --schema <f.pg> [--json] — apply はクラスター管理対象のグラフを拒否します。それらは cluster apply で進化させてください
• upgrade <uri> [--check] [--to-format <N>] [--json] — オフラインでスタンドアロンの変換を行います。v8、v9、または v13 のグラフを、omnigraph version が報告する形式に変換します。使用できる --to-format の対象はこれのみです。より古い形式でサーブされているグラフは、その形式にスタンプされるだけです。 schema upgrade-system-columns <uri> [--check] [--json] は、形式を変更せずに、サーブされたグラフの従来の id／src／dst 列の表記を変更します。 先に移行の前提条件を確認してください。 クラスター管理対象のルートでは拒否されます。0.11 バイナリの upgrade は --to-format <7|8|9> を受け取り、デフォルトは v9 でした。
• lint --query <f.gq> [--schema <f.pg>] [<uri>] [--json] — --schema を指定するとオフラインで実行し、URI を指定するとグラフを使用します
• optimize [--json] · repair [--json] · cleanup [--keep <N>] [--older-than <7d>] --confirm [--json]（保持オプションを 1 つ以上指定してください。両方を組み合わせることもできます）
• rebuild-full-text-indexes [--branch <b>] [--json] — 1 つのブランチの全文検索インデックスをデフォルトの英語解析で置き換えます。カスタムトークナイザー設定は置き換えられます。重複する書き込みを停止し、アップグレードに備えてストア全体のバックアップを保持してください。--as は帰属情報を記録します。直接アクセスではサーバーポリシーを読み込みません。メンテナンスコマンドを参照してください。 コントロールプレーン：
• organization --managed <members | invitations> <command>（エイリアス org）— 選択した組織のメンバーを管理します。--api <origin> と --organization <id> を指定するか、フォルダーをバインドして使用します。組織の members_manage 権限が必要です。書き込みには --idempotency-key が必要です。メンバー登録と招待によってグラフの権限が付与されることはありません。オフボーディングの前に Cedar による取り消しをデプロイし、既存のグラフ認証情報を使って拒否されることを確認してください。すべてのコマンドと部分的な結果の処理については、組織の管理を参照してください。
• cluster <validate | plan | apply | status | observe> [--config <dir>] [--json] — --managed を明示しない限り、セルフホスト環境が対象です。フォルダーのコンテキストによってモードが選択されることはありません。plan と observe は読み取り専用です。plan、apply、status では --server <name|url> を指定できます。サーバー上で実行する apply はアクティベーションを待ちます。--no-wait を指定すると、永続的な受け付け後に戻ります。--timeout <1..3600> で呼び出し側の待機時間を制限できます。status --deployment-id <id> --wait [--timeout <seconds>] で監視を再開できます。タイムアウトしても実行はキャンセルされません。直接復旧する場合は、元の --deployment-id と --writers-stopped を指定します。
• cluster force-unlock <lock_id> [--config <dir>] [--json] · --cluster <root> cluster upgrade-ledger --writers-stopped [--json]（サービングと書き込みを停止した状態で、サポート対象のレガシー台帳を明示的に変換します）
• マネージドサービス：use <CLUSTER_ID> --api <origin> · cluster <command> --managed で、create <name> --api <origin>、push --expected-revision <rev> --message <m>、plan [--rev <rev>]、apply --plan <run>、status [RUN_ID]、operation <id> [--wait]、history、cancel <run>、token ([--ttl 1h] | --clear)、delete --incarnation <id>、または undo-delete --incarnation <id> --deletion-id <id> を実行します。このモードでは通常のターゲット／アクターのフラグと --direct は使用できません。マネージドクラスターを参照してください。
• policy <validate | test --tests <f> | explain --actor <a> --action <act> [--branch <b> | --target-branch <b>]> --cluster <dir|uri> [--graph <id>]
• queries <validate | list> --cluster <dir|uri> [--graph <id>] [--json]

ローカル（グラフなし）：

• alias <name> [args…] — オペレーターのエイリアスにバインドされた保存済み読み取りクエリを実行します。[--params … | --params-file <p>] [--format <fmt> | --json]（サーバー／グラフ／クエリはバインディングから取得します）
• embed (--seed <embed.yaml> | --input <raw.jsonl> --output <out.jsonl> --spec <spec.json>) [--reembed-all | --clean] [--type <T>…] [--select "<Type>:<field>=<value>"]
• login <server> [--token <t>]（トークンは標準入力からパイプする方法を推奨します） · logout <server> · login --api <origin> / logout --api <origin>（マネージドセッション） · profile <list | show [<name>]> · skill <export <dir> [--force] [--json] | show [<path>]> · version [--json]

マネージドフォルダーでは、login --api と use を使って Intent API を選択できます。暗黙的に実行される query、mutate、load、commit list／show、graphs list は、それぞれ別の ID 認証情報を取得して キャッシュします（cluster token --managed は引き続き認証情報の管理に使用します）。グローバルな --direct を指定すると、通常のアドレス指定が選択されます。環境に応じたターゲットや認証情報を使用する前に、マネージドルーティングを参照してください。

0.7.0 より前の表記（read／change／ingest、--target、位置引数の http://）→ references/migrations.md。

スキーマ設計

Omnigraph のスキーマはオントロジーです。多くのエージェントが 1 つのグラフを共有する場合、スキーマはその座標系となり、事実をどこに格納するか、保存された値が何を意味するか、エージェントがどの経路に沿って推論するかを決めます。収束を目指して設計してください。同じ入力を与えられた 2 つのエージェントが、同じグラフを書き込み、同じ意味を読み取れるようにします。何をモデル化するかは慎重に決めてください。モデル化した後は、正確に制約します。後から制約を厳しくする変更（@key／@unique／@range／@check の追加、カーディナリティの変更、T? → T）は拒否されます。インプレースで適用できるのは、@index の追加、NULL 許容の追加、列挙型の拡張、名前の変更、削除のみです。

要約すると、Gruber の 5 つの基準（明確さ・一貫性・拡張性・エンコードの偏りを最小限にすること・コミットメントを最小限にすること）に従います。緩すぎず（1 つの意味に対して多数のエンコードがある状態）、厳しすぎず（エンコードできない意味がある状態）、エージェントが収束すべき箇所は厳密にし、宣言した拡張ポイントは開いておきます · まず質問を .gq として記述します · アイデンティティを最初に設計します（@key、キー付きエッジ、作成前に検索） · 種類は型、役割はエッジです · 事実を決定するものに、その事実を配置します · 帰属、根拠、確信度、時間はそれぞれ別の軸として保持します · プロビナンスは構造として表現します（Claim → 事実、Actor、Source）。自由記述の source フィールドは使いません · 抽出・統合した知識は、生のスパンにさかのぼれる系譜を持たせたうえで、その上に配置し、事実ごとにキーを設定します（スパン + 抽出器 + ステートメントのダイジェスト） · 決定事項を保存し、派生事実は計算します · 型を絞り、語彙を閉じます · スキーマで表現できないルールは GraphPolicy ノードとして定義し、エージェントがそれに照らしてグラフを検査します。必須リンクごとに孤立チェックを含めてください（@card は、エッジを持たないノードが書き込まれたことを検出しません） · 共有アイデンティティを中心に構成します（モジュールはコアを変更せず、ファセットを追加します）。組み合わせ可能な一般的プリミティブを使います · 検索を最適化します。再現率にはリンクを、適合率には具体的なエッジ、フィルター、回答サイズの単位を使います · コンテキストのない読み手にも伝わるよう、名前、@description、@instruction を記述します · フィールドの用途を転用しません · 独立した 2 つのエンコーダーを使って収束を測定します。Omnigraph のマッピングを含む全文は、references/schema-design.md を参照してください。

ストレージと認証情報

グラフのバイトデータは、次の 3 種類のサポート対象 URI ファミリーのいずれかに格納されます。

• ローカルファイルシステム — パスまたは file:// URI です。クラスター モードでは storage: の既定値が設定ディレクトリのため、ローカル開発にオブジェクトストアは不要です。
• S3 互換オブジェクトストレージ — AWS、Railway、Tigris などです（s3://bucket/prefix）。標準の AWS_* 環境変数契約を使って認証します。
• Azure Blob ストレージのプレビュー — az://container/prefix です。読み取りと Azurite による適格性確認は利用できますが、Azure は本番環境ではサポートされません。すべての書き込みまたはメンテナンス処理は、ルートスコープの omnigraph-azure-admission ラッパーを通じて起動する必要があります。

開発用の認証情報は Git の追跡対象外である .env.omni に保存し、CLI 呼び出しの前に読み込んでください。

set -a && source .env.omni && set +a

直接実行する init／load と cluster apply は、HTTP サーバーを介さずにストレージへ書き込みます。サーバー経由の load は異なり、CLI が omnigraph-server に処理を送り、サーバーがグラフを書き込みます。直接実行する cluster apply は、クラスターの台帳とグラフのデータセットに直接アクセスするため、実行ホストにはストレージ認証情報が必要です（cluster apply --managed --plan は Intent API が実行します）。サーバープロセスにも、サーバー経由のデータプレーン書き込みを行うための読み書きアクセスが必要です。curl http://127.0.0.1:8080/readyz で検証してください（HTTP 200、ready: true。/healthz で確認できるのはプロセスの稼働のみです）。続いて omnigraph snapshot --server <name> --graph <id> --json を実行します。

プロジェクト構成

デプロイとアクセス

• クラスターへのデプロイ — サービスを提供する唯一の方法です。 cluster.yaml でデプロイ全体（グラフ、スキーマ、保存済みクエリ、ポリシー、任意の S3/Azure storage: ルート）を宣言し、omnigraph cluster apply でその状態に収束させます。omnigraph-server --cluster .（または --cluster s3://bucket/prefix。設定ファイルは不要）でサービスを提供します。直接 apply した場合はアドミッションロックが保持されます。書き込みが完了したら、サーバーを起動する前に cluster force-unlock <LOCK_ID> でそのロックを解除し、以降の変更は cluster apply --server <name|url> で送信してください。 references/cluster.md を参照してください。
• 直接／埋め込みアクセス — サーバーは不要です。 グラフのストレージに --store <file://|s3://|az:// uri> または位置引数の URI で直接アクセスし、単発の CLI 操作を行います。単一グラフのサーバーモードはありません — サーバーはクラスター専用です。

2 つの設定領域

設定には単一の管理主体が所有する領域が 2 つ（RFC-007/008）あり、それに加えて、すべてを明示するフラグ／環境変数の階層があります。

領域	管理主体	場所	宣言する内容
クラスター設定	リポジトリ内のチーム	cluster.yaml + そこで参照される .pg／.gq／ポリシーファイル	システムの構成：グラフ、スキーマ、クエリ、ポリシー、ストレージ
オペレーター設定	個人	~/.omnigraph/config.yaml（$OMNIGRAPH_HOME で場所を変更できます）	自分の情報：ID、名前付きサーバー、出力の既定値、個人用エイリアス
フラグ／環境変数	呼び出しごと	—	すべてを明示的に指定

# ~/.omnigraph/config.yaml — per operator, never committed
operator:
  actor: act-andrew          # default --as identity
servers:
  intel-dev:
    url: https://graph.example.com    # no tokens here, ever
defaults:
  output: table              # read-format default
  server: intel-dev          # default served scope (or `store: file://…/g.omni` for a local default — mutually exclusive)
  default_graph: spike       # graph within a server/cluster scope
profiles:                    # optional named scope bundles — pick with --profile <name>
  staging: { server: intel-staging, default_graph: spike }
aliases:                     # personal bindings to TEAM stored queries (see references/aliases.md)
  triage: { server: intel-dev, graph: spike, query: weekly_triage, args: [since] }

オペレーター設定と認証情報は自動検出され、参照先を指定するフラグはありません。CLI は $OMNIGRAPH_HOME/config.yaml（既定値は ~/.omnigraph/config.yaml）を読み込み、ファイルが存在しない場合は空のレイヤーとして扱います（ゼロ設定）。$OMNIGRAPH_HOME で移動できるのはディレクトリのみで、特定のファイルは指定できません。--config は cluster、organization、use のソース／コンテキストフォルダーを選択します。

認証情報は設定ファイルの外に保存されます。echo $TOKEN | omnigraph login intel-dev を実行すると、~/.omnigraph/credentials（0600）に書き込まれます。対応するトークンは OMNIGRAPH_TOKEN_INTEL_DEV またはそのファイルから解決されます。トークンが送信されるのは、そのサーバーの url 配下の URL に限られます。servers: エントリーに一致しないリテラルの --server <url> には認証情報が使われず、OMNIGRAPH_BEARER_TOKEN も読み込まれません。

グラフの指定方法：ストレージに直接アクセスする場合は --store <file://|s3://|az:// uri> または位置引数の URI、サービス提供されているリモートにアクセスする場合は --server <name|url>（+ --graph <id>）、名前付きバンドルを使う場合は --profile <name>、それ以外はオペレーターの defaults を使用します。リモートの指定には --server を使います（http(s):// の URL だけではグラフアドレスになりません）。相対パスの queries/、schema.pg、.env.omni を解決できるよう、グラフのプロジェクトフォルダーからデータプレーンコマンドを実行してください。

コミットするもの

コミット対象： schema.pg、queries/*.gq、cluster.yaml、seed.md、seed.jsonl、プロジェクトの README.md と CLAUDE.md。

無視対象： .env.omni（認証情報）、.claude/（ローカルのエージェント状態）、*.omni/（ローカルのグラフ生成物）、__cluster/ と graphs/（クラスター状態と派生グラフのルート）。

エージェント用に CLAUDE.md を用意する

プロジェクトごとの CLAUDE.md には、ファイルの場所や重要な規約をコーディングエージェントに伝えます。これがないと、エージェントはセッションのたびに同じことを再発見することになります。

よくある落とし穴

問題になりやすい落とし穴をまとめました。解析エラーや実行時エラーのデバッグを始める前に、この表に目を通してください。

罠	症状	対処法
.pg 内の # コメント	parse error: expected schema_file	// を使います
単独の enum Foo { ... } ブロック	parse error: expected EOI or schema_decl	kind: enum(a, b) のようにインラインで記述します
[Category]（enum のリスト）	コンパイルエラー	[String] を使います。リストにはスカラー値を含める必要があります
@embed のソースは引用符で囲む必要があると思い込む	不要なスキーマ変更	@embed(text) と @embed("text") はどちらも有効です。引用符付きの形式が標準です
新しいグラフのエッジ制約で src／dst をそのまま使う	オフラインの lint は通るが、init／schema plan で unknown property reference 'Knows.src'; the system field is '@src' が発生	エッジ本体内に @unique(@src) を記述します。src は宣言済みのユーザープロパティを意味します
新しいグラフで _ から始まるプロパティを使う	property name '_x' is reserved for system columns (names starting with '_')	名前を変更します。エッジでは from／to も予約されています（is reserved on edge types）
@embed がロード時にベクトルを生成すると想定する	ベクトルがない、または古い	@embed はメタデータです。オフラインの omnigraph embed ... --reembed-all ファイルパイプラインを実行してから、その出力をロードします
フィーチャーブランチを開いたまま schema apply を実行する	schema apply requires a graph with only main	ブランチを削除します（merge --delete-branch または branch delete）。マージしただけではブランチは残ります
limit なしで nearest(...)／rrf(...) を使う	コンパイルエラー	limit N を追加します。BM25 のみのクエリでは省略できますが、出力を制限することを推奨します
バックフィルなしで非 NULL プロパティを追加する	サポートされていないマイグレーション	まず省略可能にしてからバックフィルします。そのまま省略可能にしておきます（T? → T の制約強化は拒否されます。OG-MF-106）
omnigraph init --json	unexpected argument '--json' found	init は --json をサポートしていません。フラグを削除します
初期化済みの URI に対して omnigraph init を実行する	graph already initialized or initialization metadata exists at '<uri>'	上書きしないでください。--force は、グラフマニフェストがないことを確認した後に、孤立したスキーマ成果物を置き換える場合にのみ使います
プロパティ／型を削除する schema apply	apply 時には何も回収されず、古いコミットは削除されたデータを読み取る	ストレージを回収するには、削除前のコミットを保持対象から除外する保持期間で cleanup を実行します。データは復元できなくなります
.env.omni をコミットする	認証情報の漏えい	.env* を .gitignore に追加します
パラメーター化されていないクエリ値	型チェックの予期しない結果、インジェクションのリスク	$param: Type を宣言し、--params を使って渡します
insert で必須フィールドが欠落している	T12: insert for `X` must provide non-nullable property `Y`	ミューテーションのシグネチャでパラメーターを受け取ります
1 つのクエリで delete と insert／update を混在させる	lint は通るが、mutate で "mixes inserts/updates and deletes" が発生	2 つのミューテーションに分割します（D₂ ルール）
v0.10 のクエリで $p.id、{ id: $v }、where id = を使う	T6／T2／T11：type `Person` has no property `id`; the system identity is `$p.@id` （失敗した保存済みクエリレジストリーによって、そのグラフは隔離されます）	$p.@id、$e.@src／@dst、where @id = を使います。v0.11 以降で再起動する前に、すべての .gq を lint します
フィーチャーブランチを長期間維持する	マージの競合、schema apply がブロックされる	速やかにマージし、完了したら削除します
.gq で mutation { ... } ラッパーを使う	1 行目で parse error: expected query_file	query <name>(...) { insert T { ... } } を使います。トップレベルの mutation キーワードはありません
データ／スキーマのコマンドで --config を使う	unexpected argument '--config' found	cluster、organization、use で使います。それ以外では --server／--graph、--store、または --profile を使います
サービス経由の書き込みで --as を使う	`--as` is not allowed on a served write	削除します。ベアラートークンによってアクターが選択されます
標準出力の上限があるツールで大きなスキーマを読み取る	出力が切り詰められる、文字化けする、または重複する	omnigraph schema show --server <name> --graph <id> > /tmp/schema.pg を実行してから、ファイルを分割して読み取ります
--mode なしで omnigraph load を実行する	the following required arguments were not provided: --mode <MODE>	--mode merge|append|overwrite を渡します。デフォルトはありません（overwrite は破壊的なため、暗黙に選択されることはありません）。直接ストレージまたはサービス経由のグラフを指定します
504 の後に確認せず再試行する	キーのないノード／エッジが重複する、または処理が繰り返される	まず対象のブランチ／エンティティの状態を比較します。試行が反映されていないと確認できた場合にのみ再試行します
タイムアウトした load --from の後にレビュー用ブランチが残っている	ロード結果が不明	内容と履歴を確認します。main のヘッドと一致するだけでは、放棄されたことや削除が許可されていることの証明にはなりません
クラスター管理対象のグラフで omnigraph schema apply／init を実行する	拒否される — クラスターの台帳を迂回するため	クラスターのグラフは omnigraph cluster apply --config . で変更します。schema apply／init はクラスター管理対象ではないストア用です
Blob を含むデータはコンパクションできないと思い込む	不要なメンテナンスの見送り	Lance 11 では Blob のコンパクションがサポートされています。optimize は NULL／空／非空の値を保持します
Blob 列に @unique／@index を指定する	スキーマの解析／検証で拒否される	Blob プロパティはキー、unique、またはインデックスにできません
Lance 11 より前（v0.9 の時期）に構築したインデックスで全文検索する。omnigraph upgrade の実行後も同様	FullTextIndexRebuildRequired	バージョンが混在したアクセスを停止し、テキスト検索が必要なすべての稼働中ブランチで rebuild-full-text-indexes --branch <b> を実行します。upgrade はインデックスを再構築しません
v0.10／v6 のグラフを v0.12 で再度開く	__manifest is stamped at internal schema v6, but this omnigraph reads only v14 to v14	古いフリートを停止します。スタンドアロンのグラフは 0.11 の upgrade で v9 にしてから、0.12 の upgrade で v14 にするか、エクスポート、init、load --mode overwrite で再構築します
ブランチがあるグラフ、または _ プロパティがあるグラフで、0.11 バイナリのデフォルトの omnigraph upgrade を実行する	the route ends at v9, which requires a graph with only main（または reserves property names starting with '_'）	ブランチを削除するか、先に @rename_from を指定します。または、チェックと実行の両方に --to-format 8 を渡します。0.12 の upgrade は v8 と v9 の両方を変換します
v8 または v9 のグラフを 0.12 で開く	拒否される：0.12 は形式 14 のみを読み取り、omnigraph upgrade を案内する	グラフを使用しているすべてのプロセスを停止し、ルート全体をバックアップしてから、スタンドアロンのグラフで 0.12 の upgrade --check と upgrade を実行します。クラスター管理対象のグラフは 0.11.x でエクスポートして再構築します。v0.11 以降へのアップグレードを参照してください
新しいグラフで識別子に data.id を使う	unknown input field 'id': move data.id to the top-level 'id' field	JSONL のトップレベルの id に識別子を指定します。data にはユーザープロパティを含めます
キーのないエッジを含む --mode merge のロードを再実行する	エッジが重複する	安定したトップレベルのエッジ id を指定するか、エッジ型の作成時に @key(@src, @dst) を宣言します
すべての JSON 結果セルにはキーがあると思い込む	NULL 値のキーがない	クエリ／エクスポートの JSON では NULL のセルが省略されます。変更イメージでは明示的な NULL が保持されます
--format arrow または defaults.output: arrow	クエリの実行後に has no text rendering が発生	0.12.0 には Arrow 出力がありません。json または jsonl を使います
cluster.yaml の相対パスに .. またはシンボリックリンクを使う	config_path_escape／config_path_symlink	参照するファイルは設定ディレクトリ内に置き、通常の相対パスを使います
管理対象フォルダーに OMNIGRAPH_PROFILE またはオペレーターのデフォルトサーバー／ストアを組み合わせる	managed_target_ambiguous	明示的に --server／--store／--profile、または --direct を指定します
グラフと cluster バンドルの両方を適用してポリシーコマンドを実行する	matches 2 policy bundles	policy validate/test/explain --graph における既知の 0.12.0 の制限です。各バンドルファイルを直接確認します

詳細解説

基本を超える内容については、該当するリファレンスファイルを読み込んでください。それぞれ単独で完結しているため、必要なものだけを読み込んでください。

リファレンス	読み込むタイミング
references/schema.md	.pg ファイルの編集、schema plan／apply の実行、型の名前変更、必須フィールドのバックフィル
references/schema-design.md	スキーマの設計またはレビュー：Gruber の基準、設計フロー、アイデンティティ、来歴、GraphPolicy のルール、構成、エージェント間の収束度の測定
references/queries.md	.gq ファイルの作成またはリント、検索関数、集計、複数ホップのパターン
references/data.md	mutate と load の使い分け（必須の --mode、レビュー用ブランチをフォークする --from）；ブランチレビューのワークフロー；上書き範囲の厳密な指定
references/blobs.md	管理対象／外部 Blob 値の書き込みと読み取り、セレクター／範囲、セキュリティとライフサイクルの境界
references/changes.md	厳密な読み取り／書き込み位置、条件付き変更、コミット差分、フィードカーソル、ベースライン、保持期間のギャップ
references/remote-ops.md	--server 経由での操作：厳密なレシート、不明な 504 の結果、競合処理、安全な再試行の判断
references/cluster.md	クラスターの構成、plan／apply、ドリフト、サービス提供
references/search.md	埋め込み、@embed、ベクトル／テキストのランキング、スコープ指定後にランキングするパターン
references/aliases.md	エージェント向けのエイリアスの定義、構造化出力、JSON 引数
references/stored-queries.md	クラスターの保存済みクエリレジストリ：宣言、queries validate/list --cluster、サービス経由の呼び出し、invoke_query の Cedar によるゲーティング
references/server-policy.md	HTTP サーバーの起動、ルート、ベアラー認証、Cedar ポリシーによるゲーティング、複数グラフモード
references/commands.md	現在のコマンド形式、アドレス指定、出力、メンテナンス
references/migrations.md	v0.11 グラフをストレージ形式 14 にアップグレード；v0.11 のストレージ／システム列のアップグレードとワイヤー形式の変更；旧バージョンの v0.9→v0.10 および pre-0.7 の境界