Pega 埋め込みリストのレポート設計|Declare Index と明細クラス化の判断
「ケースの明細行を横断で集計したい」— これは Report Definition だけでは解けない典型です。埋め込みページリストは DB の列ではないため、Declare Index で行として外出しするか、初めから別クラスとして持つかを設計段階で決める必要があります。後から報告要件で無理に index 化して破綻する前に、判断基準を整理します。
結論から:報告が主目的の明細は「初めから別クラス/子ケース」、既存の埋め込みには Declare Index
Pega で「ケースが持つ明細行(発注の品目、点検の各項目、月次の内訳など)を横断で集計・一覧したい」という要件は、設計の途中で必ずと言っていいほど現れます。ところが、これを Report Definition にそのまま持ち込もうとすると壁にぶつかります。Report Definition は原則、対象クラスに公開されたトップレベルのスカラープロパティ(=物理的な DB 列)に対して動くため、ケースの中に埋め込みページリストとして抱えた明細は、そのままではレポート・集計の対象にできないのです。
結論を先に言います。
報告・集計がその明細の主目的なら、初めから別データクラスや子ケースとして「1行1明細」で持つ。既に正当な理由で埋め込みリストを持っていて、そこに後から集計要件が乗った場合に限り、Declare Index で明細を専用のインデックスクラスへ外出しする。既存の埋め込み構造を、後付けの報告要件のためだけに無理やり index 化しない。
「便利そうだから全部 Declare Index」でも「埋め込みのまま SQL で無理やり集計しようとする」でもなく、明細の性質と要件から持ち方そのものを決める——これが実務での型です。本記事ではこの判断を、仕組みの理由から具体的な分岐まで落とし込みます。
なぜ埋め込みページリストは直接集計できないのか
前提として、Pega がケースデータをどう格納しているかを押さえておく必要があります。Pega はケースのクリップボードデータを圧縮してストレージ列(BLOB)に格納し、明示的に公開(最適化)したトップレベルのスカラープロパティだけが物理的な DB 列として姿を現します。Report Definition はこの物理列に対して SQL を組み立てるため、公開列になっていない埋め込みの値は、そのままではフィルタ・ソート・集計の対象にできません。
ここで重要なのが「トップレベルのスカラー」という条件です。埋め込みページ(単一ページ)や埋め込みページリスト(.Items(1).Amount のような構造)の中にある値は、公開(列化)の対象にできず、1つのケース行の中に複数の明細が畳み込まれているため、そのまま列にはできません。1件のケースに明細が 20 行あっても、DB 上のケース行は 1 行です。「明細行ごとに 1 行、金額を合計したい」という報告要件は、この構造とそもそも噛み合わないのです。
公開列(Exposed Column)と BLOB の切り分けそのものについては、Pega 公開列とインデックス設計|BLOB格納とレポート性能の最適化 で詳しく扱っています。本記事はその先の「では埋め込みリストの明細をどう集計するか」に絞ります。
Declare Index とは — 明細を「1行1明細」に外出しする仕組み
Declare Index は、この噛み合わなさを解消するためのルールです。埋め込みページリスト内のプロパティを、Index- ベースクラスから派生した専用のインデックスクラスのインスタンスとして外部のテーブルに書き出し、1明細を1行として持たせます。こうすると、Report Definition はそのインデックスクラスを対象クラスにして、通常のスカラー列と同じようにフィルタ・ソート・GROUP BY 集計ができるようになります。
イメージとしては、「1件のケースに畳み込まれていた明細リストを、報告のために平らに展開した明細テーブルを別に持つ」というものです。親ケースは従来どおり埋め込みリストで明細を保持し、その写像としてインデックス行が並行して維持されます。
一意化はエンジンが行う — 設計の勘どころはページコンテキストと Purpose
Declare Index のインデックスクラスは Index- ベースクラスから派生し、各行のキーは 「元インスタンスのハンドル(pxInsIndexedKey)+システムが採番する連番(pxIndexCount)+ルールの Purpose(pxIndexPurpose)」 で自動的に構成されます。つまり「どの親の、リストの何番目の明細か」という一意化は、開発者が手でキーを組まなくてもエンジンが行い、古くなった明細のインデックス削除もコミット時に自動処理されます。
そのため設計で本当に効くのは、キーの組み方ではなく次の3点です。どの埋め込みページリストをインデックス対象にするか(ソースページコンテキスト。リスト全体を対象にするには添字を付けずに指定する)/ Purpose 名(同じクラスに複数の Declare Index を張るなら明確に分ける)/ 元プロパティとインデックスプロパティのマッピング。ここを誤ると、意図しないページを拾ったり、集計対象が噛み合わなくなります。
書き込みは「コミット契機」— 維持コストと鮮度のトレードオフ
Declare Index の行は、親インスタンスがコミットされるタイミングで処理されます。インデックス処理はコミットのたびに評価され、対象プロパティに変更があればインデックス側の書き込み(追加・更新・不要行の削除)が走るため、以下のトレードオフが生じます。
- 維持コスト(書き込み負荷) — 明細が多い・更新が頻繁なケースほど、コミット時のインデックス更新負荷が積み上がる
- 鮮度 — インデックスはコミット契機で更新されるため、「今まさに編集中でまだ保存していない明細」はレポートには現れない
読み取り(レポート)を速くする代わりに、書き込みとデータの二重管理のコストを払っている、という構図です。
判断の分岐:Declare Index か、初めから別クラス/子ケースか
ここが本題です。「明細を集計したい」となったとき、選択肢は Declare Index だけではありません。むしろ、報告が主目的なら、明細を初めから別データクラスや子ケースとして持つほうがシンプルなことが多いのです。両者を軸で並べます。
| 判断軸 | 明細を別クラス/子ケース化 | 既存の埋め込み+Declare Index |
|---|---|---|
| 明細の集計・レポート | 明細クラスをそのまま対象にできる | インデックスクラスを対象にできる |
| データの持ち方 | 最初から1行1明細(正規化) | 埋め込みリスト+写像の二重持ち |
| ロック・排他 | 明細単位で制御可(子ケースの場合) | 親ケース単位のまま |
| ライフサイクル | 明細に独自の進行を持たせられる | 親ケースに従属 |
| 書き込みコスト | 明細を直接更新するだけ | 親コミット時にインデックス更新(変更検知時) |
| 鮮度 | 常に実体そのもの | コミット契機で追従 |
| 向いている場面 | 報告・検索・明細操作が主目的 | 既存の埋め込み構造に後から集計要件 |
| 新規設計での既定 | まずこちらを検討 | 安易な既定にしない |
新規設計で「この明細は集計・検索・単独操作されるものだ」と分かっているなら、初めから別クラス/子ケースにするのが素直です。 レポートはその明細クラスを対象クラスに指定すれば済み、Declare Index の二重管理も、コミット契機の維持コストも発生しません。ロックやライフサイクルの観点でも、明細を独立して扱いたいなら子ケース化のほうが筋が通ります(ケースと明細のどちらで持つべきかの一般論は Pega設計の分岐点:ケースにすべきか、データインスタンスか を参照)。
一方 Declare Index が正当化されるのは、「埋め込みリストで持つ確かな理由がすでにある」場合です。たとえば、明細が親ケースと不可分の「その時点の記録」で、親のライフサイクルの中で一括編集され、単独では意味を持たない——そういう明細をあえて別クラスに割るのは過剰です。そこに後から「四半期で品目別に集計したい」という報告要件が乗ったとき、既存の埋め込み構造を壊さずに集計を可能にする手段として Declare Index が効いてきます。
具体例で見る使い分け
- 発注ケースの品目明細 — 品目ごとに検収・入荷の進行を追い、単独で検索・集計する → 明細を子ケース or 別データクラスに。初めから1行1明細で持つ。
- 保険金請求の請求内訳 — 請求ケースと不可分で、請求のライフサイクル内で一括入力・確定される。単独では動かない → 埋め込みリストで保持。後から内訳の科目別集計が必要になったら Declare Index。
- 点検ケースのチェック項目 — 点検票と一体で、その回の記録。項目単独の進行はない → 埋め込み。項目別の不適合率をダッシュボードで見たくなったら Declare Index を検討。
- 月次レポートの内訳行を横断集計 — そもそも報告が主目的で、明細が検索・集計の対象そのもの → 初めから明細クラス化。埋め込みにして後で index 化する遠回りをしない。
判断の入口は毎回同じです。「その明細は、報告・検索・単独操作の対象か、それとも親と不可分の記録か」。前者なら別クラス、後者なら埋め込み(+必要になったら Declare Index)です。
よくある失敗
失敗1:既存インスタンスが自動で再インデックスされると思い込む。 最も多い落とし穴です。Declare Index を新規に追加しても、すでに存在しているケースのインデックスは自動では作られません。ルールを入れた時点以降にコミットされたものだけが対象になり、過去分は空のままです。既存データを集計対象に含めるには、対象インスタンスの再保存や一括再インデックス処理が必要になります。「レポートに古いケースが出てこない」の大半はこれが原因です。なお、具体的な再生成手順やトリガの挙動は Pega のバージョン・構成によって異なるため、利用中の版の公式ドキュメントで必ず確認してください。
失敗2:報告要件のために埋め込み構造を無理やり index 化する。 本来は明細クラスや子ケースにすべきものを、既存の埋め込みリストのまま放置し、後付けの Declare Index で凌ごうとするパターン。二重持ちの維持コストと設定・運用の複雑さを恒久的に抱え込むことになります。報告が主目的だと分かっているなら、設計をさかのぼって明細クラス化するほうが、長期的には安く済みます。
失敗3:ソースページコンテキストや Purpose の指定を誤る。 インデックス行の一意化(親ハンドル+システム採番の連番+Purpose)や、古くなった明細インデックスの削除はエンジンがコミット時に自動で行うため、キーを手作業で組む必要はありません。実務でつまずくのはむしろ、どの埋め込みページリストをインデックス対象にするか(ソースページコンテキスト。リスト全体を対象にするには添字を付けずに指定する) と Purpose 名の付け方です。対象の指定を誤ると別のページを拾い、同じクラスに複数の Declare Index を張るのに Purpose を分けないと集計が噛み合いません。対象ページ・Purpose・プロパティのマッピングが意図どおりかを、保存前に確認します。
失敗4:鮮度と維持コストを見積もらない。 インデックスはコミット契機で更新されるため、リアルタイム性が要る集計には向きません。また明細数・更新頻度が大きいと、コミット時のインデックス書き込みが性能に効いてきます。実際、1回のコミットで大量のインデックス(目安として100件超)が生成されると、Pega は PEGA0034 アラートを上げて設計の見直しを促します。レポートの鮮度要件と書き込み負荷を、導入前に必ず見積もってください(レポート側の性能設計は Pega Report Definition のパフォーマンス設計 も参照)。
まとめ
- Report Definition は公開されたトップレベルのスカラー列に対して動く。埋め込みページリスト内の明細は、そのままでは集計できない。
- 報告・集計・単独操作が主目的の明細は、初めから別データクラスや子ケースとして「1行1明細」で持つ——これが第一選択。レポート・ロック・ライフサイクルのすべてでシンプルになる。
- Declare Index は、埋め込みで持つ正当な理由がすでにあり、そこに後から集計要件が乗ったときの手段。 既存構造を壊さずに明細を行として外出しできるが、データの二重持ち・コミット契機の維持コスト・鮮度のトレードオフを負う。
- 既存の埋め込み構造を、後付けの報告要件のためだけに無理やり index 化しない。 それは多くの場合、設計をさかのぼって明細クラス化すべきサインである。
- 導入時は既存インスタンスが自動で再インデックスされないことに注意。再保存や一括再インデックスが要る。具体的な手順・トリガ挙動は版・構成で異なるため要確認。
明細をどう持つかは、レポートの実現性だけでなく、ロック・ライフサイクル・性能の土台になります。「報告が主目的か、親と不可分の記録か」を設計の初期に言語化しておくことが、後工程での大きな手戻りを防ぎます。
関連リンク
このテーマの記事をまとめて読む: Pega の性能とレポート設計 用語は Pega 用語集 で引けます
関連記事
Pega 日時・タイムゾーン設計|DateTime と Date の使い分けと UTC 保存の落とし穴
「登録日が1日ずれる」「バッチの集計時刻が合わない」——多言語・多地域展開の Pega アプリで LSA が必ず直面するのが日時とタイムゾーンの設計だ。DateTime を UTC で保存し表示で現地時刻へ変換するモデルを理解せず、暦上の日付まで DateTime にしてしまうと、タイムゾーン変換で日付が前後する。プロパティ型の選択基準から整理する。
記事を読むPega Savable Data Page 設計|外部システムへの書き戻しとコネクタ直呼びの使い分け
「データページは読み取り専用」という前提は、Savable Data Page を使うと変わる。読み書きを同じデータ仮想化レイヤに集約できる一方、保存は自動では走らず、コミット境界やエラー処理を誤ると『保存したつもり』の未反映や部分保存を招く。どこまでを Savable Data Page に任せ、どこからをフロー内のコネクタ直呼びにするかを整理する。
記事を読むPega プロパティ型選択の落とし穴|金額は Decimal・日時は DateTime で丸め誤差とタイムゾーン事故を防ぐ
「とりあえず数値だから Double」「日付だから DateTime」——この安易な型選択が、請求額の1円ずれや締め日の1日ずれとして本番で顕在化する。Pega のプロパティ型は一度データが入ると変更コストが高く、設計初期の判断がそのまま数年残る。本記事は金額・数量・日時という壊れやすい値に絞り、正しい型と落とし穴を整理する。
記事を読む