schema-explorer

スキーマエクスプローラー

dxs schema コマンドを使った OData スキーマの検出。

参考資料

• references/batch-syntax.md — バッチコマンドの構文、引数の形式、エンティティの説明に使うフラグ、アンチパターン
• references/subagent-template.md — サブエージェントへの委任プロンプト

Footprint の接続 — まず entity-expert スキルを確認する

接続が FootPrintApi 接続（Footprint WMS データ — Tasks、Shipments、ArchivedShippingLicensePlateContents、LicensePlate、Lot、Material など）の場合は、スキーマを調べる前に footprint-entity-expert スキルを確認してください。このスキルには、OData メタデータからは分からないナビゲーションチェーン、ビジネスルールのフィルター、重量計算が記載されています。また、あるビジネス概念を実際に裏付けているエンティティも示しています（例：「出荷済み在庫」→ Shipments ではなく ASLPC）。Footprint 以外の接続では、この手順を省略してください。

接続の解決

スキーマコマンドには接続 ID（-c <id>）が必要です。ユーザーが明示的に指定する場合と、指定しない場合があります。

ユーザーが接続 ID または名前を指定した場合 — そのまま使用します。例：「接続 9 を使って」「Prod 接続を使って」。

ユーザーが「Prod で」や「Demo 環境で」のように指定した場合 — 該当する FootprintApi 接続を探します。

1. dxs auth status — 認証済みの組織 ID を取得します
2. dxs organization connection list --org <org_id> — すべての接続を一覧表示します
3. apiConnectionTypeName: FootPrintApi で絞り込み、名前を照合します

ユーザーが接続をまったく指定しない場合 — 利用可能な FootprintApi 接続を一覧表示し、どれを使うか尋ねます。

1. dxs auth status — 組織 ID を取得します
2. dxs organization connection list --org <org_id> — 接続を一覧表示します
3. FootprintApi 接続のみをユーザーに提示します（MongoDB、AMQP、SFTP などは除外）。使用する接続を選んでもらいます

入出力の仕様

入力： 接続 ID ＋検索キーワード

出力： 次の構成の field-mapping.md ファイル：

# Schema: <EntityName>

## Connection
- Connection ID: <id>
- Namespace: <namespace>

## Primary Entity
- Entity Set: <name>
- Entity Type: <namespace.type>
- Keys: <key fields and types>

## Fields

### Root Fields
| Field | Type | Notes |
|-------|------|-------|

### Navigation Properties
| Nav Property | Target Type | Cardinality | Key Fields |
|-------------|-------------|-------------|------------|

### Expanded Fields (via $expand)
| Path | Type | Source Entity | Binding |
|------|------|---------------|---------|

Mark the **Binding** column:
- `flat` — field is reachable through single navigation properties; safe for flat DataSet fields
- `⚠ collection` — path crosses a collection navigation property (1:N cardinality); requires flow datasource flattening or child dataset with `CommandText` deep path. Will silently render blank if added as a flat DataSet field.

## Composite Keys / Special Notes

コマンド選択ルール

リクエストが 1 件の場合 → 直接コマンドを使います。独立したリクエストが複数ある場合 → 1 つのバッチにまとめます。

• 必要な操作が 1 つだけの場合（例：検索 1 件、説明 1 件）は、直接コマンドを使います。--request を 1 つだけ指定して dxs schema batch に入れないでください。
• 独立した操作が 2 件以上必要な場合は、すべてを 1 回の dxs schema batch 呼び出しにまとめます。独立したリクエストを複数のバッチ呼び出しに分割しないでください。呼び出しごとに別の HTTP 往復が発生します。
• 1 回目の結果によって次に照会する内容が決まる場合に限り、2 回目の呼び出しに分けてください。
• すべての一覧コマンドで対象を絞り込んでください。 entities、actions、properties、indexes はフィルターを指定しないとモデル全体を返します。実際の接続では、1 回の呼び出しで数十〜数百 KB になり、なかでも indexes が最大です。それぞれに絞り込み用のフラグがあります。properties／navigation-properties では --entity-type、indexes では --entity-set と --covering、すべてのコマンドでは --search と --filter が使えます。-n と --skip でページ分割してください。必要なのが件数だけの場合は --count を使います。

ワークフロー

1. エンティティを検索する — すべてのキーワード検索を 1 つのバッチにまとめます。

   dxs schema batch -c <id> \
     --request 'search shipment' \
     --request 'search order' \
     --request 'search warehouse' \
     --request 'search carrier'
   

   エンティティセット名を推測できる場合は、検索と describes を同じバッチにまとめます。検索結果には完全修飾された entity_type（例：Datex.FootPrint.Api.Warehouse）が含まれます。後続の手順で --entity-type フラグに使用するため、これらを保存してください。

   キーワードが 1 つだけの場合は、直接コマンドを使用します：dxs schema search "keyword" -c <id>。

2. エンティティとリレーションシップを記述する — すべてのエンティティの記述とリレーションシップの調査を 1 つのバッチにまとめます。describe-entity では --compact --no-udf を、リレーションシップでは --depth 2 を使用します。

   dxs schema batch -c <id> \
     --request 'describe-entity Shipments --compact --no-udf' \
     --request 'describe-relationships Shipments --depth 2' \
     --request 'describe-entity Orders --compact --no-udf' \
     --request 'describe-relationships Orders --depth 2' \
     --request 'describe-entity ShipmentLines --compact --no-udf' \
     --request 'describe-relationships ShipmentLines --depth 2'
   

   初期調査には --compact を使用します。特定のフィールドの詳細が後で必要になった場合は、--select Field1,Field2 を使用して、対象のプロパティだけを記述します。

3. 関連エンティティのフィールドを調べる — 関連エンティティのスキャンをすべて 1 つのバッチにまとめます。$expand する予定の各ナビゲーションプロパティの対象について、describe-entity --compact --no-udf を使用します。

   dxs schema batch -c <id> \
     --request 'describe-entity Materials --compact --no-udf' \
     --request 'describe-entity Lots --compact --no-udf' \
     --request 'describe-entity Addresses --compact --no-udf' \
     --request 'describe-entity Contacts --compact --no-udf' \
     --request 'describe-entity Warehouses --compact --no-udf' \
     --request 'describe-relationships Warehouses --depth 2'
   

   手順 2 の describe-relationships --depth 2 ですでに確認したエンティティはスキップします。depth-2 の出力には、ネストされたナビゲーションプロパティ名と対象型が含まれます。$select 句に必要なスカラー型フィールドの一覧を確認するエンティティだけをスキャンします。

   型 ID しかない場合（例：リレーションシップの出力にある Datex.FootPrint.Api.Warehouse）で、エンティティセット名がわからないときは、代わりに properties --entity-type Namespace.Type を使用します。完全修飾型を直接指定できます。$expand パスも必要な場合は、navigation-properties --entity-type も併せて使用します。

   注： 関連エンティティの $expand パス（そのエンティティから展開できるもの）が必要な場合は、navigation_properties の出力を確認してください。describe-entity --compact には、スカラー型プロパティとナビゲーションプロパティの両方が含まれます。

4. 列挙型の値を解決する — プロパティの型が Edm. で始まらない場合、その型は列挙型または複合型です。すべての列挙型の検索を 1 つのバッチにまとめます（1 つだけの場合は直接コマンドを使用します）。

   dxs schema batch -c <id> \
     --request 'describe-enum Datex.FootPrint.Api.Statuses' \
     --request 'describe-enum Datex.FootPrint.Api.OrderTypes'
   

   これにより、フィルター値の意味がわかります（例：StatusId eq 1 →「有効」）。

5. 展開パスを検証する — odata-execution スキルを実行し、ナビゲーションプロパティがデータを返すことを確認します（$top=1 と $expand を使用）。外部キーが NULL のため、展開結果が空になるナビゲーションプロパティを持つエンティティもあります。

   検証する項目：

   • 深いパス（深さ >= 2、例：OrderLine.Material.Description）— 失敗するリスクが高くなります
   • NULL 許容の外部キーを経由するパス（例：ShipToContactId が NULL 許容の場合の ShipToContact）
   • コレクションを経由するコレクションの展開（例：ShipmentLines($expand=OrderLine(...))）
   • 確信が持てないパス

   省略しても安全な項目： 外部キーが NULL 許容でない場合の、参照エンティティへの単一レベルの展開（Status、Type、Category のパターン）。これらはスキーマによって構造的に保証されています。

   欠けている項目を記録し、代替のクエリパスを提案します（例：関連エンティティにフィルターを適用して直接クエリする）。展開したコレクション内のフィルターが必要な場合は、ラムダ演算子（any()／all()）もテストします。

6. フィールドマッピングテーブルを作成する — 見つかったすべてのフィールドをフィールドマッピングテンプレートにまとめ、ルートフィールド、ナビゲーションプロパティ、展開フィールドに分けます。

   欠けている項目も明示してください。 ユーザーが「成功／失敗」「納期遅れの注文」「優先度」などの概念について尋ねていても、スキーマに対応するフィールドがない場合は、フィールドマッピングにその旨を記載します。存在するフィールドだけでなく、存在しないフィールドを説明することにも同じ価値があります。存在しない情報を探す手間を省き、回避策（計算による導出、外部照合など）を判断できるようになります。

インデックスの認識

dxs 0.5.5 より新しいバージョンが必要です — これらのコマンドは 0.5.5 タグ以降に統合されました。古いビルドでは dxs schema indexes は存在せず、describe-entity は indexes キーを返しません。このキーがないのは CLI 側の事情であり、メタデータ側の問題ではありません。また、ストレージについて何かを示すものでもありません。 メタデータには、各エンティティセットの背後にある物理データベースインデックスが報告されます。大規模なエンティティセットに対してフィルターや並べ替えを行うスキーマをマッピングする場合は、必ず確認してください。インデックスのない述語は、本番環境ではタイムアウトするのに、小規模な開発用データセットでは問題なく見えるデータソースの、よくある原因です。

describe-entity は追加の HTTP 呼び出しなしでエンティティセットのインデックスを返すので、ステップ 2 を実行済みなら、すでに確認できます。--compact、--no-udf、--properties-only のいずれを指定してもインデックスは保持されます。indexes コマンドを使うのは、エンティティを横断する質問の場合だけです。

dxs schema batch -c <id> \
  --request 'indexes --entity-set Shipments' \
  --request 'indexes --covering ModifiedSysDateTime'

--covering COLUMN は Columns/any(c: c/Name eq 'COLUMN') の省略形で、「この列はどこかでインデックス化されているか？」をラムダ式を手書きせずに確認できます。

すべての Footprint サーバーがインデックスを報告するわけではありません。 スキーマサービスが Indexes エンティティセットを公開している必要があり、古いバージョンでは公開されていません。CLI は接続ごとに一度だけ確認し（キャッシュ期間は 24 時間）、リクエストを失敗させるのではなく、その状況に対応します。indexes と describe-index は DXS-SCHEMA-015 を返して拒否し、describe-entity はオプションの展開を省略して、indexes キーを返しません。直接実行した describe-entity では警告として理由が示されますが、バッチ内では何も示されません。キーが単に存在しないため、バッチ経由では、indexes キーがない場合に「結論を出す前に、この接続に直接問い合わせる」と判断してください。バッチでは、インデックスのみを対象とするリクエストはローカルでエラーとして処理され、送信されません。そのため、サポートされていないリクエストが原因でバッチ全体が失敗することはありません。機能の非対応はサーバーバージョンに関する事実であり、インデックスの調査結果を示す 4 つ目の種類ではありません。ストレージについては何も示しません。「このサーバーはインデックスメタデータを報告しない」と説明し、「インデックスがない」とは説明しないでください。

出力の読み方 — 注意すべき 3 点：

• その列だけでフィルターしてインデックスシークを行うには、key_ordinal が 1 である必要があります。(StatusId, AccountId) に対するインデックスは、AccountId だけでフィルターする場合には役立ちません。
• is_included: true の列はフィルターに使えません。 その列はルックアップなしで $select を満たすために含まれているだけなので、その列だけでフィルターすると、依然としてテーブル全体がスキャンされます。
• インデックスが報告されない場合は、「なし」ではなく「不明」です。 空の結果、つまり describe-entity の indexes: [] や空の indexes リストは、そのエンティティセットについてメタデータに情報がないことを意味し、ストレージにインデックスがないことを意味するわけではありません。この状態のエンティティセットは API では常に読み取り専用ですが、通常のキー付きテーブルのように見えるものもいくつかあるため、おそらくインデックスは存在するものの、報告されていません。そこでのフィルターがスキャンするとも、インデックスシークするとも結論づけないでください。マッピングでは「インデックス情報なし」と記述してください。

空の --covering 結果には 3 通りの解釈があり、スコープ指定で除外できるのはそのうち 1 つだけです。 --entity-set を指定すると、列名の誤記 は除外できます。そのエンティティ型に存在しない列は空の結果になるのではなく、DXS-SCHEMA-014 で失敗するためです。ただし、情報がない 場合は除外できません。エンティティセットがインデックスをまったく報告しない場合、スコープを指定して見つからなくても、3 つ目の注意点と同じく「不明」です。決定的な解釈、つまり「この列はインデックス化されていないため、この列でフィルターするとスキャンする」と判断するには、スコープを指定し、かつそのエンティティセットが少なくとも 1 つのインデックスを報告している必要があります。スコープを指定しないと、名前を照合するエンティティ型がないため、「どこにもインデックスがない」と「列名の誤記」を区別できません。モデル全体を対象にした --covering は「この列はどこでインデックス化されているか？」を確認する用途なら問題ありませんが、結果が $filter の判断に関わる場合は、必ずスコープを指定して再実行してください。

dxs schema indexes -c <id> --entity-set Shipments --covering ModifiedSysDateTime

3 通りのうちどれに当たるのかを推測するのではなく、CLI に示させてください。ただし、パスによって答えが表示される場所が異なるので、どこに表示されるかを把握しておきましょう。

パス	文言が表示される場所
dxs schema indexes。--entity-set／--covering で絞り込まず、空の結果の場合	metadata.index_hint
同じケースの dxs schema batch 内の indexes	そのリクエストの warnings[]
直接実行した場合の describe-entity と indexes: []	metadata.index_hint
バッチ内の describe-entity と indexes: []	そのリクエストの warnings[]
スコープを指定していない indexes リストが空で返された場合	何もありません。結果を読み取る前にスコープを指定してください
indexes キー自体がない場合	直接実行した describe-entity では、サーバー名を示す警告が表示されます。バッチ内、またはこの機能より古い CLI では何も表示されません。どちらの場合も、エンティティセットについて何らかの判断ができるわけではありません

実際に判断できる空の結果には、すべて説明文が付いています。説明文がないのはスコープ未指定の結果であり、これが最も証拠になりません。

意図するフィルター列に先頭列インデックスがない場合は、その旨をルートフィールドの表の該当フィールド横にある Notes 列に記載してください。これはデータソース設計における実際の制約であり、脚注ではありません。

ガード付きフィルターは、インデックスとともに消えることがあります。 dxs datasource generate でフィルターをパラメーター化する方法はすべて、述語を $utils.isDefined() ガードで囲みます。そのため、実行時にパラメーターが未指定だと述語が除去され、インデックスを確認したばかりのクエリがテーブル全体をスキャンします。--detect-params は名前に反して、必須のガードなしフィルターを出力するフラグではありません。

したがって、パラメーター化されたフィルターのインデックス確認は、その背後にあるバインディングの品質に左右されます。スコープ指定パラメーターをインデックスの確認結果とあわせて報告し、datasource-creator に引き継いでください。その references/odata-datasources.md → 「The index check is undone by a guarded scoping filter」には、その仕組みと、この問題を解消する2つの方法が記載されています。

サブエージェントの使用

スキーマの調査では、大量の出力が生成されることがあります。メインコンテキストを整理しておくため、サブエージェントに委任してください。プロンプトのテンプレートについては、references/subagent-template.md を参照してください。

アーティファクトディレクトリに出力を書き込みます。

• 01-schema-exploration.md — スキーマの生の調査結果
• 02-field-mapping.md — 完成したフィールドマッピング表

describe-entity のフラグ

describe-entity は --concise をサポートしていません。表示フラグの一覧（--compact、--no-udf、-P、-N、--prop-top、--select）については、references/batch-syntax.md を参照してください。すべてのフラグはバッチで使用できます。例：--request 'describe-entity Orders --compact --no-udf'

その他のルール

上記のワークフローステップにすでに含まれているルールは、ここでは繰り返しません。アンチパターンの一覧については、references/batch-syntax.md を参照してください。

• 必ず keys: セクションを確認してください。一部のエンティティには複合キーがあり、Id フィールドがありません
• describe-properties で指定できるプロパティ名は一度に1つだけです。カンマ区切りにはできません。まとめて調べる場合は、describe-entity --compact --no-udf を使用するか、複数の呼び出しをバッチにまとめてください
• schema コマンドで DXS-API-CONN／DXS-API-TLS／DXS-API-TIMEOUT／DXS-API-NET エラーが発生した場合は、エンティティ名の誤りではなくネットワーク障害です。ペイロードの suggestions[] に従ってください。configuration-roundtrip.md → Exit 141 and transport errors を参照してください
• バッチを使えば「順次実行」の制約を解消できます。失敗時に兄弟の呼び出しを中断する並列ツール呼び出しとは異なり、バッチは個々のリクエストの失敗を適切に処理します