infrahub-importing-data

CSV/TSV から Infrahub オブジェクトへのインポート

概要

ユーザーが提供する CSV または TSV 入力 — 単一ファイル、ファイルのフォルダー、またはその任意の組み合わせ — を、infrahubctl object load が受け入れる Infrahub オブジェクト YAML に変換するための専門的なガイダンスです。このスキルは「スプレッドシートがある」と「レビュー可能なブランチ上にオブジェクトが存在する」の間の橋渡しを行います。

このスキルは厳密にライブスキーマのコンシューマーです。CSV の列に対応するスキーマの受け皿がない場合、処理を停止し、問題のある列を一覧表示し、スキーマの判断を別途行うためにユーザーを infrahub-managing-schemas へ誘導します。属性の追加、ドロップダウンの選択肢、その他のスキーマ編集を提案することは決してなく、デフォルトブランチへ直接書き込むことも決してありません。

プロジェクトコンテキスト

既存のスキーマファイル: !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

既存のオブジェクトファイル: !find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -10

.infrahub.yml が存在する場合: !find . -maxdepth 2 -name ".infrahub.yml" 2>/dev/null | head -1

作業ツリー内の候補となる CSV/TSV 入力: !find . -maxdepth 3 \( -name "*.csv" -o -name "*.tsv" \) 2>/dev/null | head -10

引数を付けて呼び出された場合（例: /infrahub:importing-data inventory.csv）、最初の引数を入力ファイルまたはフォルダーとして扱い、残りの引数を含める追加のパスとして扱います。

使用する場合

• ユーザーが 1 つ以上の CSV または TSV ファイルを渡し、そのデータを Infrahub に取り込みたい場合。
• 入力が非正規化されている — 1 つのシートに複数の種類が混在している — ため、正しいロード順で適切なスキーマノードに分割する必要がある場合。
• CSV にドロップダウンラベルのように見える列（例: Status: Active）があり、選択肢の name（例: active）を出力する必要がある場合。
• 親の種類の行が CSV 内で子ごとに繰り返されており、子が親のコンポーネント子としてインラインで属する場合。
• インターフェース形状の名前（eth0..eth47）が連続して現れ、範囲を圧縮して出力したい場合。
• ユーザーがインポートされたすべての値にリネージタグを付与したい場合。

使用しない場合

• 入力が infrahubctl dump からの LDJSON ダンプである場合。infrahubctl load を使用してください。これは別の形式を読み取るものであり、CSV には不適切なツールです。どちらもトップレベルのコマンドであり、import や export というコマンドグループはありません。スキルはこれらを混同しないように区別します。
• ユーザーがスキーマの変更を必要としている場合。このスキルはスキーマに対して読み取り専用です。infrahub-managing-schemas に引き継いでください。
• ユーザーが Infrahub から CSV へデータをエクスポートする必要がある場合。単一種類のエクスポートは infrahubctl object get -o csv ですでに機能します。複数種類のエクスポートは将来のコンパニオンスキルで対応します。
• 入力が JSON、XLSX、Parquet、その他の非 CSV 形式である場合。v1 は CSV + TSV のみを対象とします。

ルールカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	ワークフロー	workflow-	スキーマイントロスペクション、プロファイルサンプル、フェイルクローズドゲート、事前インタビュー、セルフチェック、プリフライトクロージャー、ブランチファースト、検証エラーマッピング
HIGH	入力	inputs-	ファイル / フォルダー / リストの正規化、CSV 方言の検出、同一種類のマージ
CRITICAL	マッピング	mapping-	列 → 属性、値の型変換、空/null の処理、ドロップダウンラベル → name、参照 HFID の検出
HIGH	分解	decomposition-	非正規化された CSV を種類ごとに分割
MEDIUM	範囲	range-	インターフェース形状の検出と圧縮
LOW	リネージ	lineage-	インポート時のオプションのソース/オーナーの付与
LOW	出力	outputs-	ファイルレベルの形状に関する懸念（来歴コメント）

このスキルが依存するスキーマ機能

このスキルは、対象スキーマの実際の形状に準拠したオブジェクト YAML を出力します。CSV が必要とする機能がスキーマに欠けている場合、ロードは失敗します。だからこそ、このスキルはこうした点を事前にチェックし、黙って回避するのではなくエスカレーションします。

CSV にこれがある場合...	スキーマはこれをする必要があります...	参照
別の kind を指す参照列	対象ノードに human_friendly_id を定義する。HFID の長さがスカラー参照かリスト参照かの形状を決定します	../infrahub-managing-schemas/rules/display-human-friendly-id.md
Dropdown 列に対するラベル形式の値（active ではなく Active）	ドロップダウンの choices を name と label の両方を持つオブジェクトとして宣言する。エミッターは name を書き込み、スキーマから label を読み取ります	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
子ごとの列を持つ繰り返し親行	Component（親）と Parent（子）のリレーションシップを同じ識別子でペアにし、子側で optional: false を設定する	../infrahub-managing-schemas/rules/relationship-component-parent.md
明らかなスキーマ上の置き場所がない列	infrahub-managing-schemas を介して拡張する。このスキルはフェイルクローズし、引き継ぎます	../infrahub-managing-schemas/SKILL.md

ユーザーがロードしたいデータに対してこれらのいずれかが欠けている場合、それはインポートの修正ではなくスキーマの移行です。スキルは停止し、その旨を伝えます。

ワークフロー

以下の 14 ステップを順番に実行してください。番号付けは重要です。前のステップが後のステップを制約します。

1. 入力をフラットなファイルリストに正規化します。 単一のパス、ディレクトリ（*.csv / *.tsv を再帰的にスキャン）、またはリストを受け入れ、プロファイリングの前にフラットなリストに解決します。各ファイルについて、行を読み取る前に CSV の方言（区切り文字、エンコーディング、BOM、改行コード）を検出します。rules/inputs-file-folder-list.md と rules/inputs-csv-dialect.md をお読みください。

2. スキーマを検出します — 読み取り専用。 優先順位に従ってソースを試し、CSV が必要とする kind を返した最初のもので停止します。

   1. MCP サーバー — infrahub-analyzing-data が使用するのと同じサーフェス。ブランチ固有のドロップダウン選択肢や HFID を含むデプロイ済みの状態を参照します。
   2. infrahubctl schema export --branch <name> — MCP が接続されていない場合に、設定済みサーバーに対する CLI エクスポート。
   3. /api/schema?branch=<name> REST エンドポイント — infrahubctl が利用できない、または別のサーバーを指している場合の直接 HTTP フェッチ。
   4. リポジトリ内のローカル schemas/*.yml — 最後の手段。デプロイ済みの状態より遅れている可能性があるため、ステップ 11 のサーバー検証が差異を検出するために必要です。

   どのソースを使用したかを記録し、ユーザーがマッピングの信頼性を把握できるようにします。スキーマの編集を提案しないでください。 rules/workflow-introspect-first.md をお読みください。

3. 各ファイルをプロファイリングします。 ヘッダーとサンプル行を読み取ります（デフォルト 20。ドロップダウン、範囲、非正規化の検出に必要ならそれ以上）。列のデータ形状、列ごとの異なる値の数、サンプル値、シーケンスパターンを記録します。rules/workflow-profile-sample.md をお読みください。

4. ファイルごとにマッピングのドラフトを作成する reference.md のヒューリスティクスを使用します：

   • カラム → 属性: 完全一致、 次に snake_case のラウンドトリップ、次に表示ラベルの あいまい一致、次に単位の除去（(GB)、(MHz)） — それ以降はすべてインタビューに委ねます。 rules/mapping-column-to-attribute.md を参照してください。
   • 値の型変換: Boolean / Number / DateTime / JSON 属性の種類では、出力前に 明示的な型変換が必要です。 rules/mapping-value-coercion.md を参照してください。
   • 空セル: スキーマの optional および default_value 宣言に基づいて、省略するか失敗させるかを判断します。 rules/mapping-empty-and-null.md を参照してください。
   • ドロップダウンカラム: スキーマからラベル→名前の ルックアップを構築して変換します。 rules/mapping-dropdown-label-to-name.md を参照してください。
   • 参照カラム: リレーションシップに対する名前の一致と、 対象の種類の HFID に対する値の形状によって検出します。 rules/mapping-reference-and-hfid.md を参照してください。
   • 範囲カラム: 連続するインターフェイス形式のシーケンスを まとめます。 rules/range-detection.md を参照してください。
   • 非正規化カラム: 繰り返される親グループを検出し、 入力を種類ごとに分割します。 rules/decomposition-denormalized-csv.md を参照してください。
   • 複数の入力に同じ種類が存在する場合: 1 つの番号付き出力ファイルに マージし、HFID で重複を排除し、 競合はインタビューで明らかにします。 rules/inputs-merge-same-kind.md を参照してください。

5. フェイルクローズドゲート。 どのカラムにも スキーマ上の居場所がない場合は、停止します。 マッピングされていない カラムと確認した種類を列挙した構造化レポートを出力し、 ユーザーに infrahub-managing-schemas を案内して、 終了します。部分的な書き込みは行いません。 rules/workflow-fail-closed-on-unmapped-columns.md を参照してください。

6. 事前インタビュー。 ファイルが書き込まれる前に、 残っているすべてのあいまいさを 1 回の多肢選択式の 質問にまとめます。 rules/workflow-up-front-interview.md を参照してください。

7. マッピングを確認してロックします。 最初のファイルが 書き込まれる前に、完全な計画（対象ファイル、種類、カラムの バインディング、ブランチ名、リネージのオプトイン）を そのまま返します。

8. オブジェクト YAML を出力する ローカルの作業 ディレクトリ（デフォルト ./output_dir/）へ出力します。各ファイルは managing-objects エンベロープに準拠します： apiVersion: infrahub.app/v1、kind: Object、 spec.kind、spec.data。ファイルはロード順に 番号が付けられます（NN_<kind-plural>.yml）。各ファイルには、 ソース CSV + sha256 + 出力タイムスタンプを示す 先頭の来歴コメントが付きます。 ../infrahub-managing-objects/rules/format-structure.md のフォーマット規則、 ../infrahub-managing-objects/rules/organization-load-order.md のファイル命名規則、 rules/outputs-provenance-comment.md のコメントの形式を相互参照してください。

9. managing-objects に対するセルフチェック。 列挙された managing-objects のルールを再度読み、出力を 各ルールに照らして確認します。ローカルのみ — CLI なし、 サーバーなし、ブランチなし。先に進む前に その場で修正します。 rules/workflow-self-check-against-managing-objects.md を参照してください。

10. プリフライト参照クロージャ。 出力内のすべての リレーションシップ参照をたどり、 ターゲットが上流ファイルの行、または イントロスペクションが取得したライブオブジェクトの いずれかに解決できることを検証します。孤立した参照は、 ブランチに触れる前にフェイルクローズします。詳しくは rules/workflow-pre-flight-closure.md をお読みください。

11. ブランチを作成します。 セルフチェックと プリフライトクロージャが通過した後にのみ、 infrahubctl branch create <name> を実行します（デフォルトは csv-import-YYYYMMDD-HHMM、インタビューでユーザーが 上書き可能）。これを最後に行うことで、使い捨ての ブランチがブランチ一覧に残りません。詳しくは rules/workflow-branch-before-load.md をお読みください。

12. サーバー検証 をブランチ上で実行します: infrahubctl object validate ./output_dir/ --branch <name>。ローカルのチェックでは検出できない スキーマ解決エラー（スキーマに存在しない kind、 属性名の誤り、参照ターゲットの欠落）を検出します。 エラーが発生した場合は、診断結果を元の CSV セルに 対応付けて戻し、入力を修正するようユーザーに依頼します — 出力された YAML を手で編集しないでください。詳しくは rules/workflow-validate-error-mapping.md をお読みください。

13. ロード をブランチ上で実行します: infrahubctl object load ./output_dir/ --branch <name>。オブジェクト ロードはファイルをまたいでトランザクションではありません — 20 ファイル中 17 番目が失敗した場合、ファイル 1〜16 は すでにブランチ上にあります。ブランチファーストの設計では、 ブランチを破棄して新しいブランチ名で再実行します — 部分的な状態を手作業でクリーンアップすることはありません。

14. 引き継ぎ。 ブランチがレビュー可能であること、 実行された validate/load コマンド、UI で 提案された変更を開く方法をユーザーに伝えます。 自動マージは行わないでください。

関連リファレンス

• examples.md — 8 つの実践的な CSV パターン: フラットリスト、非正規化分割、 親と子、ドロップダウンラベルの正規化、 範囲の圧縮、リネージのスタンプ、フェイルクローズ レポート、マージ + 重複排除
• reference.md — ヒューリスティックな 順序、ファイルエンベロープのリマインダー、HFID の判断 マトリクス、ファイル命名規則
• rules/ — カテゴリプレフィックスごとの 個別ルール。rules/_sections.md から始めてください
• ../infrahub-managing-objects/SKILL.md — 出力されるすべてのファイルが準拠すべきコンシューマー側の ルール（エンベロープ、値のマッピング、コンポーネント、 範囲、ロード順、ブランチファースト）
• ../infrahub-analyzing-data/SKILL.md — ライブスキーマ検出のための MCP イントロスペクション パターン
• ../infrahub-managing-schemas/SKILL.md — カラムにスキーマ上の居場所がない場合の エスケープハッチ
• ../infrahub-common/metadata-lineage.md — 値メタデータのセマンティクス（source はリネージ 専用。ロックには owner + is_protected が必要）
• ../infrahub-common/rules/workflow-branch-for-crud.md — スキーマ書き込みとオブジェクト書き込みの両方が継承する 共有のブランチファーストルール
• ../infrahub-common/rules/connectivity-server-check.md — ワークフロー内のサーバー依存コマンドの前に、infrahubctl info でサーバーに到達可能か確認する
• ../infrahub-common/rules/connectivity-python-environment.md — すべての infrahubctl 呼び出しのために、プロジェクトの Python 環境プレフィックス（uv run / poetry run）を検出する
• ../infrahub-common/rules/workflow-information-priority.md -- スキルコンテンツを最優先。真に不足がある場合（例: ノードの削除）に docs.infrahub.app を参照する方法