Pega プロパティ型選択の落とし穴|金額は Decimal・日時は DateTime で丸め誤差とタイムゾーン事故を防ぐ

「とりあえず数値だから Double」「日付だから DateTime」——この安易な型選択が、請求額の1円ずれや締め日の1日ずれとして本番で顕在化する。Pega のプロパティ型は一度データが入ると変更コストが高く、設計初期の判断がそのまま数年残る。本記事は金額・数量・日時という壊れやすい値に絞り、正しい型と落とし穴を整理する。

結論から:型は値の「正体」で選ぶ

Pega でデータモデルを設計するとき、プロパティにどの型を割り当てるかは一見些細な選択に見えます。しかし、この一手が本番稼働後に請求額の1円ずれや締め日の1日ずれとして表面化することがあります。しかもプロパティ型は、一度インスタンスが作られると変更コストが跳ね上がります。設計初期の判断が、そのまま数年間そのアプリケーションに残るのです。

結論を先に述べます。

金額・数量・レートなど正確性が要る値は必ず Decimal を使う。Double は誤差を許容できる科学技術計算に限定する。日時は「瞬間」だけを DateTime(内部 UTC 保持)にし、時刻を持たない日付は Date、時刻だけは TimeOfDay を使う。数値や日付を Text に入れてはいけない。

「数値だから Double」「日付だから DateTime」という反射的な選択が事故の温床です。本記事では、特に壊れやすい 金額・数量・日時 に絞って、正しい型と落とし穴を整理します。

プロパティ型の選び分け 単一値プロパティは「何を表す値か」で型を選ぶ。数値は Decimal / Double / Integer、日付・時刻は DateTime / Date / TimeOfDay を使い分ける比較図。 単一値プロパティ|何を表す値か? 数値 Decimal 金額・数量・レート ― 任意精度で丸め誤差なし Double 科学技術計算・誤差を許容できる場面に限定 Integer 小数を持たない個数・件数・連番 日付・時刻 DateTime 日付+時刻の瞬間 ― 内部は UTC で保持 Date 時刻を持たない日付 ― 誕生日・締め日 TimeOfDay 時刻だけ ― 営業開始時刻など Text に数値・日付を入れない ― 比較・集計・ソートが壊れる
図:単一値プロパティは「何を表す値か」で型を決める。数値は正確性が要るなら Decimal、誤差許容なら Double、小数なしは Integer。日時は瞬間なら DateTime(内部 UTC)、日付だけは Date、時刻だけは TimeOfDay。

なぜ型選択がそれほど重要なのか

型を後から変えればいい、と考えるのは危険です。プロパティ型は、そのプロパティを含むインスタンスがまだ存在しない設計初期であれば低コストで変えられますが、すでに本番データが入っていると変更コストが跳ね上がります。公開列(Exposed Column)にマッピングされているプロパティの型を変えれば列定義の再マッピングが必要になり、格納済みの値をどう移送・変換するかというデータ移行の問題が発生します。型が変わると比較・集計の挙動も変わるため、その値を参照しているルール・レポート・連携すべてに影響が及びます。

だからこそ、型は設計の初期に確定させるのが鉄則です。「あとで直せる」前提で雑に決めると、直せない状態になってから問題が顕在化します。

数値:Decimal か Double か、それとも Integer か

数値型の選択が、金額を扱うシステムでは最も事故が多い領域です。

Decimal ― 正確性が要る値はすべてこれ

Decimal は任意精度で値を保持します(Pega は内部的に Java の BigDecimal として表現します)。十進の小数を桁落ちなく正確に表現でき、加算や乗算を繰り返しても丸め誤差が発生しません。金額、数量、税率、為替レート、単価×数量の計算結果——「1円たりともずれてはいけない値」はすべて Decimal を使うのが原則です。

請求・会計・在庫といった、数字の正しさそのものが業務価値になる領域では、迷う余地はありません。Decimal 一択です。

Double ― 誤差を許容できる場面に限定

**Double は倍精度浮動小数点で、0.1 のような値を内部で正確に表現できません。**二進の浮動小数点方式である以上、0.1 + 0.2 が 0.3 にならないといった誤差が構造的に生じ、加算を繰り返すほど誤差が蓄積していきます。

たとえば単価 0.1 の項目を 1,000 回足し合わせると、Decimal なら正確に 100 になりますが、Double では末尾にわずかな誤差が乗ります。1件では見えなくても、大量の明細を集計した合計額で数円のずれとなって現れ、「帳簿と1円合わない」という調査に何時間も溶かすことになります。

Double を使ってよいのは、そもそも誤差が許容される科学技術計算——物理シミュレーション、統計的な近似値、センサーの測定値のように「有効数字が合っていれば十分」な場面に限られます。業務の金額計算で Double を選ぶ理由は、基本的にありません。

Integer ― 小数を持たない値

個数、件数、連番、回数のように小数点以下が存在しない整数値は Integer を使います。ここでよくあるのが Integer と Decimal の混同です。「数量」と一括りにして Decimal にしてしまうと、本来整数であるべき「注文個数」に 2.5 のような不正な値が入り込む余地を残します。逆に、小数を持ちうる「重量(kg)」や「面積(m²)」を Integer にすると小数部が切り捨てられます。その値が小数を取りうるかで Integer と Decimal を明確に分けてください。

Decimal と Double の使い分け早見表

観点DecimalDouble
内部表現任意精度(Java の BigDecimal)倍精度浮動小数点
丸め誤差発生しない発生・蓄積する
0.1 の表現正確不正確
向いている値金額・数量・レート・税額物理計算・統計・測定値
業務の金額計算必ずこちら使ってはいけない

日時:DateTime か Date/TimeOfDay か

日時系の事故は「タイムゾーン」で起きます。

DateTime は内部 UTC、表示時にタイムゾーン変換される

**DateTime は内部的に UTC 基準で保持され、表示するときにオペレーターやブラウザのタイムゾーンへ変換されます。**Pega の公式概念ドキュメント(Understanding the Date, TimeofDay, and DateTime property types)でも、DateTime は「既知のタイムゾーンで、可能な場合はミリ秒単位まで内部保持される日付+時刻」と定義され、内部形式は yyyyMMdd'T'HHmmss.SSS 'GMT' です(Pega では GMT と UTC を同一に扱います)。この仕組みは「世界中どこで操作しても同一の瞬間を指す」ためのもので、システム連携の発生時刻・ログ・イベントのタイムスタンプのように 「時間軸上の1点(瞬間)」を表す値には正しい選択です。日本のオペレーターが操作した時刻も、GMT/UTC で保存され、閲覧者の環境に合わせて変換表示されます。

時刻を持たない値に DateTime を使わない

問題は、時刻の概念がない値まで DateTime にしてしまうケースです。誕生日、締め日、契約日、請求日——これらは「その日」を表すだけで、何時何分という情報を持ちません。

こうした値を DateTime で持つと、内部で UTC に変換される過程で「その日の 0 時」といった時刻が暗黙に付与されます。すると、閲覧者のタイムゾーンによって同じ値が前日や翌日に表示され、締め日や誕生日が1日ずれるという事故が起きます。たとえば「3月31日締め」のつもりで入れた値が、タイムゾーン変換の結果 3月30日として集計されれば、月次のカットオフを丸ごと誤ります。

これを避けるための型が用意されています。公式ドキュメントでも、Date は「タイムゾーンやロケールを持たない、グレゴリオ暦上の1日」、TimeOfDay は「タイムゾーンやロケールを持たない時刻」と定義されており、DateTime(瞬間=instant in time)とは明確に区別されています。

  • 時刻を持たない日付(誕生日・締め日・契約日)→ Date
  • 日付を持たない時刻(営業開始時刻・受付終了時刻)→ TimeOfDay
  • 日付+時刻の瞬間(イベント発生時刻・タイムスタンプ)→ DateTime

「その値はタイムゾーンで動いてよいのか?」と自問してください。動いてはいけない(=絶対的な日付・時刻)なら Date か TimeOfDay、動くべき瞬間なら DateTime です。

公式ドキュメントの補足(版に依存する運用上の注意):Pega の公式概念ドキュメントは、work item や assignment のような永続オブジェクトで Date / TimeOfDay を使う場合、単一のタイムゾーンでしか使わないアプリでも、値の解釈にタイムゾーンが必要なら別プロパティにタイムゾーン値も併せて保持するよう注意喚起しています。Date / TimeOfDay 自体がタイムゾーンを持たないため、値の意味がタイムゾーンに依存すると保持オブジェクト単体では曖昧になり得るからです。裏を返せば、Date が正解なのは誕生日や締め日のようにそもそもタイムゾーンで意味が動かない日付のとき。もし日付の意味がタイムゾーンで変わるなら、それは実は「瞬間」(DateTime)かもしれない、というサインです(Infinity ‘25 時点の公式ドキュメントに基づく。運用上の注意点はバージョンにより差異があり得ます)。

型の選び分け早見表

こういう値推奨型主な理由・落とし穴
金額・請求額・単価DecimalDouble だと丸め誤差で合計がずれる
数量(小数あり)・レート・税率Decimal正確性が業務価値。Double 不可
個数・件数・連番Integer小数を許すと不正値が混入
物理計算・統計・測定値Double誤差許容が前提の場面のみ
イベント発生時刻・タイムスタンプDateTime内部 UTC。瞬間を表す値に最適
誕生日・締め日・契約日DateDateTime だとタイムゾーンで日付がずれる
営業開始・受付終了などの時刻TimeOfDay日付を持たせない
上記いずれの数値・日付もText は不可比較・集計・ソートが壊れる

Text に数値・日付を入れてはいけない

もう一つの典型的な失敗が、数値や日付を Text(文字列) として格納することです。「フォーマットを自由に扱えて楽だから」と Text にすると、後で必ず痛い目を見ます。

  • 比較・集計ができない — 文字列としての大小比較になり、数値の合計や範囲検索が正しく機能しません。
  • ソートが壊れる — 文字列ソートでは "100" が "20" より小さいと判定されます(先頭文字 1 < 2 のため)。公開列でソートする一覧画面やレポートで、直感に反する並び順になります。
  • 日付も同様 — ISO 8601(2026-03-31)のような桁揃えの形式でない限り、文字列ソートは時系列と一致しません。

数値は数値型、日付は日付型で持つ。当たり前のようでいて、外部データ取り込みや暫定対応の名残で Text のまま残ってしまうことが実務では珍しくありません。公開列とインデックスの設計を含めた詳細は 公開列とインデックス設計の記事 も参照してください。

よくある失敗

これまで見てきた事故を、失敗パターンとして整理します。

  1. 金額を Double で持つ — 最頻出かつ最も痛い失敗。単体テストでは気づかず、大量明細の合計で1円ずれが顕在化します。金額は無条件で Decimal です。
  2. 誕生日・締め日を DateTime にする — タイムゾーン変換で日付が前後し、締め処理や年齢計算がずれます。時刻を持たない値は Date にします。
  3. Integer と Decimal の混同 — 整数であるべき個数に小数が入る、小数を取る重量が切り捨てられる。小数を取りうるかで分けます。
  4. 数値・日付を Text に格納する — 比較・集計・ソートが破綻します。型で持てば起きない問題です。
  5. 「あとで直せる」前提で型を決める — 本番データが入った後の型変更は、公開列の再マッピングとデータ移送を伴う高コスト作業です。型は設計初期に確定させます。

なお、型ごとの内部保持形式・UI 挙動・関数の振る舞いは Pega のバージョンによって差異があります。実装時は必ず対象バージョンの公式仕様で確認してください。本記事は版に依存しない判断の型を示すものです。

まとめ

  • 金額・数量・レートは Decimal。 任意精度(内部は BigDecimal)で丸め誤差が出ない。業務の金額計算で Double は使わない。
  • Double は誤差許容の科学技術計算に限定。 0.1 を正確に表現できず、加算で誤差が蓄積する。
  • 時刻を持つ瞬間だけ DateTime(内部 UTC)。 誕生日・締め日など時刻のない日付は Date、時刻だけは TimeOfDay。タイムゾーンで日付がずれる事故を防ぐ。
  • 数値・日付を Text に入れない。 比較・集計・ソートが壊れる。
  • 型は設計初期に確定させる。 本番データが入ると変更コストが跳ね上がる。

プロパティ型の選択は、Pega アプリケーションのデータ整合性の土台です。「数値だから」「日付だから」で反射的に決めず、その値が本当は何を表しているのかを一度言語化してから型を割り当てる——この一手間が、本番での1円ずれ・1日ずれを未然に防ぎます。データモデルの設計判断でお困りの際は、Pega Platform 開発支援 までお気軽にご相談ください。


Pega の設計・実装でお困りの際は、Pega Platform 開発支援 や 無料相談 をご利用ください。Pega 認定資格の最高位 LSA(Lead System Architect)を保有するコンサルタントが、データモデル設計からご支援します。

関連リンク

このテーマの記事をまとめて読む: Pega のデータモデルとルール設計 用語は Pega 用語集 で引けます

関連記事

Pega 日時・タイムゾーン設計|DateTime と Date の使い分けと UTC 保存の落とし穴

「登録日が1日ずれる」「バッチの集計時刻が合わない」——多言語・多地域展開の Pega アプリで LSA が必ず直面するのが日時とタイムゾーンの設計だ。DateTime を UTC で保存し表示で現地時刻へ変換するモデルを理解せず、暦上の日付まで DateTime にしてしまうと、タイムゾーン変換で日付が前後する。プロパティ型の選択基準から整理する。

記事を読む

Pega 埋め込みリストのレポート設計|Declare Index と明細クラス化の判断

「ケースの明細行を横断で集計したい」— これは Report Definition だけでは解けない典型です。埋め込みページリストは DB の列ではないため、Declare Index で行として外出しするか、初めから別クラスとして持つかを設計段階で決める必要があります。後から報告要件で無理に index 化して破綻する前に、判断基準を整理します。

記事を読む

Pega Savable Data Page 設計|外部システムへの書き戻しとコネクタ直呼びの使い分け

「データページは読み取り専用」という前提は、Savable Data Page を使うと変わる。読み書きを同じデータ仮想化レイヤに集約できる一方、保存は自動では走らず、コミット境界やエラー処理を誤ると『保存したつもり』の未反映や部分保存を招く。どこまでを Savable Data Page に任せ、どこからをフロー内のコネクタ直呼びにするかを整理する。

記事を読む

設計標準と設計レビューのご相談

判断の理由と適用範囲まで書いた設計標準をもとに、設計レビューと内製化を支援しています。