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

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

結論から:値の「本質」で型を選ぶ — 一意な瞬間は DateTime、暦日は Date、時刻は TimeOfDay

多言語・多地域に展開する Pega アプリケーションで、設計者がほぼ確実につまずくのが日時とタイムゾーンです。「登録日が地域によって1日ずれる」「日次バッチの集計が現地の締め時刻と合わない」——こうした不具合の大半は、コードのバグではなく、プロパティ型の選択ミスに根があります。

結論を先に言います。

その値が表すものの本質で型を選ぶ。一意な瞬間(取引時刻・締切)は DateTime、暦上の日付(生年月日・記念日)は Date、時刻そのもの(営業開始時刻)は TimeOfDay。

なぜこれが効くのかは、Pega の DateTime が 内部的に UTC(GMT)で保存され、表示時にオペレータのタイムゾーン設定で現地時刻へ変換されるという仕組みを理解すると腑に落ちます。この変換は「一意な瞬間」を正しく世界中で共有するための機能ですが、変換されては困る値(暦上の日付)に適用すると、日付が前後してしまうのです。

DateTime・Date・TimeOfDay の使い分け 値が一意な瞬間なら DateTime、暦上の日付なら Date、時刻のみなら TimeOfDay を選ぶ判断図。DateTime だけがタイムゾーン変換を伴う。 この値の本質は何か? 一意な瞬間 / 暦上の日付 / 時刻のみ 一意な瞬間 暦上の日付 時刻のみ DateTime 一意な瞬間を表す ・UTC で保存 ・表示で現地時刻へ変換 ・取引時刻・締切・ログ 例:注文確定日時 Date 暦上の日付を表す ・日付のみ保持 ・TZ 変換を伴わない ・暦日として不変 例:生年月日・記念日 TimeOfDay 時刻のみを表す ・時刻のみ保持 ・TZ 変換を伴わない ・日付に依存しない 例:店舗の営業開始時刻 暦上の日付や時刻のみを DateTime にすると、UTC 変換で日付・時刻がズレる
図:値が一意な瞬間なら DateTime、暦上の日付なら Date、時刻のみなら TimeOfDay。タイムゾーン変換を伴うのは DateTime だけ。

Pega の DateTime は UTC で保存され、表示で変換される

まず、すべての判断の土台になる仕組みを押さえます。

Pega の DateTime プロパティは、データベースには UTC(GMT)で保存されます。オペレータ(リクエスタ)が画面でその値を見るときには、そのオペレータに設定されたタイムゾーンに従って現地時刻へ変換して表示されます。逆に、画面から入力された現地時刻は、保存時に UTC へ変換されて格納されます。

このモデルの利点は明快です。「2026-11-14 に東京で確定した注文」と「同じ瞬間をロンドンで見た値」を、同一の UTC 値として矛盾なく保持できます。世界のどこから見ても指し示す瞬間は1つで、表示だけがローカライズされる——これは多地域システムにとって理想的な設計です。

一方で、Date と TimeOfDay はタイムゾーン変換を伴いません。Date は「暦上の日付」だけを、TimeOfDay は「時刻」だけを保持します。オペレータのタイムゾーンが東京だろうがロンドンだろうが、2000-01-01 は 2000-01-01 のままです。この「変換されない」という性質こそが、暦日や時刻を扱ううえで決定的に重要になります。

型の選択:一意な瞬間・暦日・時刻のみ

型選択は、値の性質を次の3つのどれに当てはめるかで決まります。

DateTime — 一意な瞬間を表す

タイムライン上の特定の1点を指す値は DateTime です。

  • 注文が確定した瞬間、契約の締切、システムログのタイムスタンプ、SLA の期限
  • これらは「世界のどこで見ても同じ瞬間」であるべきで、UTC 保存+現地表示のモデルがそのまま正解になります

「その値を、別のタイムゾーンにいる人が見たときにローカル時刻で表示されてほしいか?」を自問し、Yes なら DateTime です。

Date — 暦上の日付を表す

暦の上の日付であって、特定の瞬間ではない値は Date です。

  • 生年月日、記念日、契約上の「◯月◯日」、請求の計上日
  • これらは「地球上のどこでも同じ日付」であるべきで、タイムゾーンで前後に動いてはいけません

生年月日を DateTime にすると、内部的に「その日の午前0時 UTC」のような瞬間として保存され、UTC より西のタイムゾーンで表示したときに前日にずれます。これは後述する最も典型的な失敗です。

TimeOfDay — 時刻のみを表す

日付から独立した時刻を表す値は TimeOfDay です。

  • 店舗の営業開始・終了時刻、リマインダーを鳴らす時刻、定例の開始時刻
  • 「9:00 に開店」は特定の日付に紐づかない繰り返しの時刻なので、日付ごと持つ DateTime は不適切です

型選択の早見表

観点DateTimeDateTimeOfDay
表すもの一意な瞬間暦上の日付時刻のみ
タイムゾーン変換あり(UTC⇔現地)なしなし
保存の考え方UTC で保存日付そのまま時刻そのまま
典型例取引時刻・締切・ログ生年月日・記念日営業開始時刻
誤用したときの症状(適切)日付が1日ずれる日付に引きずられる
判断の問い別TZで現地表示したい?暦日として不変であるべき?日付と無関係な時刻?

「別のタイムゾーンで見たときに現地時刻へ変換されてほしいか」——この1問が DateTime とそれ以外を分ける最短の判定基準です。 変換されては困る値(暦日・時刻)に DateTime を使わない、これだけで日付ズレの大半は消えます。

バッチ・エージェント・ジョブスケジューラの時刻設計

対話ユーザーの画面表示だけでなく、バックグラウンド処理の時刻も設計対象です。ここは見落とされがちで、かつ地域展開時に問題が表面化しやすいポイントです。

キューによる非同期処理やジョブスケジューラ、エージェントといったバックグラウンドの実行主体は、画面を操作する対話ユーザーとは異なるコンテキストで動きます。対話ユーザーには本人のタイムゾーン設定がありますが、バックグラウンド処理は「誰の現地時刻で動いているのか」の前提が変わり得ます。具体的な挙動(どのタイムゾーンを基準に起動時刻を解釈するか等)はサーバ設定や Pega のバージョンによって異なるため、ここで断定はしません。設計上の指針だけを述べます。

  • 「毎日 9:00 に実行」が、どこの 9:00 なのかを設計時に言語化する。 サーバのタイムゾーン基準なのか、特定地域の現地時刻基準なのかを曖昧にしない
  • バックグラウンド処理が生成・比較する DateTime は UTC 基準で考える。 ログや処理時刻を現地時刻前提で解釈すると、対話画面とバッチで食い違う
  • 起動時刻のタイムゾーン前提は、利用する版の公式ドキュメントで必ず確認する。 「たぶんサーバ時刻だろう」で進めない

バックグラウンド処理の時刻前提は、開発環境(単一地域)では露見せず、本番の多地域運用で初めて牙をむきます。設計文書に「基準タイムゾーン」を明記しておくことが唯一の予防策です。

レポートと集計境界:UTC を意識した日次締め

比較演算やレポートは UTC 基準で行われるという点も、集計設計に直結します。

DateTime は内部的に UTC で保持されているため、レポートで「日付」による絞り込みや >= < の比較を素朴に書くと、UTC の日付境界で切られます。ところが業務が求める締めは、多くの場合「現地時刻の 0:00〜23:59」です。この2つは一致しません。

たとえば東京(UTC+9)で「11月14日の売上」を集計したいとき、それは UTC では「11月13日 15:00 〜 11月14日 15:00」に相当します。UTC の暦日で TransactionDateTime を単純に日付グルーピングすると、現地の深夜帯の取引が前後の日に振り分けられ、現地の締めと1件単位でずれます。

  • 現地時刻での日次締めが要件なら、集計の境界を明示的に変換して設計する。 UTC のまま暦日で切らない
  • どのタイムゾーンで締めるのかを、レポート設計の前提として文書化する。 多地域なら「地域ごとに締めが違う」ケースもある
  • 表示は現地・集計境界も現地、内部保持は UTC という三者を混同しない

集計要件を詰めるときは「その”1日”は誰のタイムゾーンの1日か」を必ず確認してください。これを曖昧にしたまま実装すると、数字が「なんとなく合わない」という最も厄介な形で顕在化します。

よくある失敗

日時設計の失敗は、経験上いくつかの定番に集約されます。

失敗1:暦上の日付を DateTime にして1日ずれる

最頻出の失敗です。生年月日・記念日・契約日といった暦日を DateTime プロパティで持ってしまうパターン。UTC 保存+現地変換のモデルに乗ってしまい、UTC より西のタイムゾーンで表示すると前日にずれます。生年月日が地域によって1日変わるのは業務的に致命的です。暦上の日付は必ず Date にしてください。

失敗2:時刻のみの値を DateTime にする

「営業開始 9:00」のような日付から独立した時刻を DateTime で持つと、意味のない日付部分がくっつき、タイムゾーン変換の対象にもなって挙動が読みにくくなります。時刻そのものは TimeOfDay が正解です。

失敗3:バッチの実行時刻を「サーバ=現地」と思い込む

バックグラウンド処理の起動時刻や生成タイムスタンプを、開発時の単一地域の感覚で「サーバ時刻=現地時刻」と暗黙に前提してしまうパターン。多地域本番で対話画面とバッチの時刻がずれて発覚します。基準タイムゾーンを設計時に確定し、版の仕様で裏を取ることが必要です。

失敗4:レポートの日付境界を UTC のまま切る

現地時刻での日次締めが要件なのに、UTC の暦日でそのままグルーピングしてしまうパターン。深夜帯の取引が隣の日に混ざり、現地の締め数字と合いません。集計境界は明示的に現地時刻へ変換して設計します。

まとめ

  • Pega の DateTime は UTC で保存され、表示時にオペレータのタイムゾーンで現地時刻へ変換される。この変換が正しく効くのは「一意な瞬間」に対してだけ
  • 型は値の本質で選ぶ——一意な瞬間は DateTime、暦上の日付は Date、時刻のみは TimeOfDay。Date と TimeOfDay はタイムゾーン変換を伴わない
  • 最頻出の失敗は暦日を DateTime にして1日ずれること。生年月日・記念日は必ず Date
  • バッチ・エージェント・ジョブスケジューラは対話ユーザーと別コンテキストで動く。基準タイムゾーンを設計時に明記し、版の仕様で確認する
  • 比較・レポートは UTC 基準。現地時刻での日次締めは、集計境界を明示的に変換して設計する

日時とタイムゾーンは、単一地域で開発しているうちは問題が見えず、多地域展開の本番で一気に噴き出します。プロパティ型を1つ選ぶ設計の初期判断が、後工程のデータ整合性・レポート・運用の安定性を大きく左右します。「この値は現地時刻に変換されるべきか」を最初に言語化しておくことが、最も費用対効果の高い予防策です。


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

関連リンク

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

関連記事

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

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

記事を読む

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

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

記事を読む

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

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

記事を読む

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

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