Temporal functions ​

Temporal functionsは、日付、時刻、時点、期間を読み取り、計算し、相互に移動します。これは標準ライブラリで最大のカテゴリです。また、1日ずれるレポート、年に2回1時間遅れて発火するSLA、システム境界を越えると変わる日付など、統合バグが最も発生しやすい場所でもあります。

最初に適切な型を選択する ​

ほとんどの時間関連バグは、関数の選択ではなく型の選択によるものです。 WELは時点とウォールクロックの表示を分離し、この分離によって典型的なエラーを防ぎます。

コンポーネントを読み取る ​

これらはPlainDate、DateTime、またはPlainDateTimeを受け取り、その一部を返します。

year ​

年を返します。

year(value)

year(PlainDate('2026-03-15'))

2026

month ​

月を1から12の数値として返します。

month(value)

month(PlainDate('2026-03-15'))

3

day ​

月の日を1から31で返します。

day(value)

day(PlainDate('2026-03-15'))

15

quarter ​

カレンダー四半期を1から4で返します。

quarter(value)

quarter(PlainDate('2026-03-15'))

1

day_of_year ​

年の日を1から366で返します。

day_of_year(value)

day_of_year(PlainDate('2026-03-15'))

74

day_of_week ​

曜日を1から7で返します。1はロケールの週の最初の日です。

そのため、この数値はロケールに依存します。同じ日付でも、週が日曜日に始まる場所では1、月曜日に始まる場所では7になります。数値が宛先システムに入る場合は、day_of_week_nameとの明示的な比較を優先するか、レシピのロケールを確認してください。

day_of_week(value)

day_of_week(PlainDate('2026-03-15'))

1

day_of_week_name ​

曜日のローカライズされた名前を返します。

day_of_week_name(value)

day_of_week_name(PlainDate('2026-03-15'))

日曜日

month_name ​

月のローカライズされた名前を返します。

month_name(value)

month_name(PlainDate('2026-03-15'))

March

hour ​

時を0から23で返します。

hour(value)

hour(DateTime('2026-03-15T09:30:45Z'))

9

minute ​

分を0から59で返します。

minute(value)

minute(DateTime('2026-03-15T09:30:45Z'))

30

second ​

秒をDecimalとして返すため、小数精度が保持されます。

second(value)

second(DateTime('2026-03-15T09:30:45Z'))

45

time ​

ウォールクロック時刻をPlainTimeとして返します。タイムゾーン引数を指定すると、代わりにそのゾーンのローカル時刻を返します。

time(datetime, timezone)

time(DateTime('2026-03-15T09:30:45Z'))

09:30:45

time(DateTime('2026-03-15T09:30:45Z'), 'Asia/Tokyo')

18:30:45

to_map ​

Durationを含む任意の時間値を、そのコンポーネントのマップに分解します。

to_map(value)

to_map(PlainDate('2026-03-15'))

{year: 2026, month: 3, day: 15}

to_map(Duration('PT2H30M'))

{hours: 2, minutes: 30, seconds: 0}

カレンダー演算 ​

カレンダー上の1か月と30日は同じ増分ではありません。その違いは月末に現れます。これら2つの関数は、そのケースを異なる方法で処理します。

add_months ​

指定した月数を追加し、対象月の日数が少ない場合は月末にクランプします。 ExcelのEDATE関数と同等です。

1月31日に1か月を足すと、2月28日、うるう年では2月29日になります。ビジネスルールが「翌月の同じ日付、存在しない場合は最終日」を意味する場合に使用します。これはほとんどの請求およびサブスクリプションルールを表します。

add_months(date, months)

add_months(PlainDate('2026-01-31'), 1)

2026-02-28

add_months(PlainDate('2026-03-15'), -2)

2026-01-15

advance_date ​

PlainDateを年、月、日の任意の組み合わせで進めます。

advance_dateは、add_monthsとは異なり、結果が実在する日付にならない場合にクランプせずエラーを発生させます。不可能な日付が入力の誤りを意味し、日を黙って移動するよりもジョブを失敗させたい場合に使用します。

advance_date(date, delta)

advance_date(PlainDate('2026-03-15'), {days: 10})

2026-03-25

advance_date(PlainDate('2026-03-15'), {years: 1, months: 2})

2027-05-15

date_diff ​

2つの日付間の差を年、月、日に分解します。

date_diffは最初の日付から2番目の日付までを測定するため、2番目の日付が早い場合は負のコンポーネントになります。

date_diff(from, to)

date_diff(PlainDate('2025-01-10'), PlainDate('2026-03-15'))

{years: 1, months: 2, days: 5}

date_diff(PlainDate('2026-03-15'), PlainDate('2025-01-10'))

{years: -1, months: -2, days: -5}

advance_datetime ​

指定されたタイムゾーンで、DateTimeを年、月、日、時、分、秒で進めます。

advance_datetime(datetime, delta, timezone, on_gap, on_fold)

advance_datetime(DateTime('2026-03-15T09:30:00Z'), {hours: 5})

2026-03-15T14:30:00Z

期間演算 ​

次の関数は、ISO 8601期間をDateTimeに加算または減算します。

datetime_add_duration ​

ISO 8601文字列として記述された期間をDateTimeに追加します。

PT2Hなどのクロックのみの期間はオフセットを保持します。 P1Dなどのカレンダー期間は、指定されたタイムゾーン、またはロケールのタイムゾーンで適用されるため、「1日後」は夏時間の変更をまたいでも同じウォールクロック時刻のままです。

datetime_add_duration(datetime, duration, timezone, on_gap, on_fold)

datetime_add_duration(DateTime('2026-03-15T09:30:00Z'), 'PT2H')

2026-03-15T11:30:00Z

datetime_sub_duration ​

DateTimeから期間を減算します。 datetime_add_durationと同じ引数を取ります。

datetime_sub_duration(datetime, duration, timezone, on_gap, on_fold)

datetime_sub_duration(DateTime('2026-03-15T09:30:00Z'), 'P1D')

2026-03-14T09:30:00Z

間隔を測定する ​

次の関数は、2つの時点間の間隔をDurationとして測定します。

until ​

最初の時点から2番目の時点までの符号付き期間を返します。

until(from, to)

until(DateTime('2026-03-15T09:00:00Z'), DateTime('2026-03-15T11:30:00Z'))

PT2H30M

since ​

2つの時点間の符号付き期間を返し、最初から2番目を引きます。これはuntilとは逆の引数順です。

since(now(), created_at)は、通常の質問の言い方である「作成されてからどれくらい経ったか」に一致します。

since(later, earlier)

since(DateTime('2026-03-15T11:30:00Z'), DateTime('2026-03-15T09:00:00Z'))

PT2H30M

in_hours、in_minutes、in_seconds、in_days ​

Durationを、指定された単位の整数に変換します。丸めではなく切り捨てます。 PT150Mは3時間ではなく2時間です。

in_days(duration)
in_hours(duration)
in_minutes(duration)
in_seconds(duration)

in_hours(Duration('PT150M'))

2

in_minutes(Duration('PT2H30M'))

150

in_seconds(Duration('PT1M30S'))

90

in_days(Duration('PT72H'))

3

ユースケース: SLAを過ぎたチケットにフラグを付ける ​

サポートキューでは、チケットが長時間開いたままになったらフラグを付ける必要があります。各チケットの経過時間をnow()と比較して測定し、48時間を超えるものにマークを付けます。

入力

{
  "tickets": [
    {"id": "T-1", "created_at": "2026-07-09T08:00:00Z"},
    {"id": "T-2", "created_at": "2026-07-12T06:00:00Z"}
  ]
}

Formula

_.tickets >> map_by(t ~> {
  id: t.id,
  age_hours: in_hours(since(now(), DateTime(t.created_at))),
  breached: in_hours(since(now(), DateTime(t.created_at))) > 48
})

出力

[
  {"id": "T-1", "age_hours": 76, "breached": true},
  {"id": "T-2", "age_hours": 6, "breached": false}
]

この例では、2026-07-12T12:34:56.789Z時点のnow()を使用しています。このFormulaは常に同じ時点からage_hoursとbreachedを計算するため、両者が食い違うことはありません。これは、now()がステップ全体で固定されているためです。

期間境界 ​

これらは値を期間の開始または終了にスナップします。これは、レポートウィンドウの作成やレコードを月ごとにバケット化する通常の方法です。

それぞれ、引数なしではUTCの現在時点、1つの引数では指定された値、2つの引数ではDateTimeとタイムゾーンを受け付けます。

start_of_dayとend_of_day ​

カレンダー日の最初と最後の時点を返します。

start_of_day(datetime)
end_of_day(datetime, timezone)

start_of_day(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T00:00:00Z

end_of_day(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T23:59:59.999999999Z

end_of_dayは、その日の最後に表現可能な時点であり、翌日の午前0時ではありません。そのため、これに対する<=比較は、翌日を含めずにその日全体を含めます。

start_of_hour ​

その時間の最初の時点を返します。

start_of_hour(datetime, timezone)

start_of_hour(DateTime('2026-03-15T09:30:45Z'))

2026-03-15T09:00:00Z

start_of_weekとend_of_week ​

これらの関数はロケール対応です。週がどの日に始まるかは、レシピのロケールによって異なります。

start_of_week(value)
end_of_week(value, timezone)

start_of_week(PlainDate('2026-03-15'))

2026-03-15

end_of_week(PlainDate('2026-03-15'))

2026-03-21

start_of_monthとend_of_month ​

カレンダー月の最初の日と最後の日を返します。

start_of_month(value)
end_of_month(value, timezone)

start_of_month(PlainDate('2026-03-15'))

2026-03-01

end_of_month(PlainDate('2026-03-15'))

2026-03-31

start_of_quarterとend_of_quarter ​

カレンダー四半期の最初の日と最後の日を返します。

start_of_quarter(value)
end_of_quarter(value, timezone)

start_of_quarter(PlainDate('2026-03-15'))

2026-01-01

end_of_quarter(PlainDate('2026-03-15'))

2026-03-31

start_of_yearとend_of_year ​

カレンダー年の最初の日と最後の日を返します。

start_of_year(value)
end_of_year(value, timezone)

start_of_year(PlainDate('2026-03-15'))

2026-01-01

end_of_year(PlainDate('2026-03-15'))

2026-12-31

ユースケース: 今月のレポートウィンドウを作成する ​

レポートには、現在のカレンダー月の最初の日と最後の日が必要です。 start_of_monthとend_of_monthを使用して、両方をnow()から作成します。

入力

{}

Formula

{
  from: start_of_month(PlainDate(now())),
  to: end_of_month(PlainDate(now()))
}

出力

{"from": "2026-07-01", "to": "2026-07-31"}

この例では、2026-07-12T12:34:56.789Z時点のnow()を使用しています。最初にPlainDateに変換します。レポートAPIはカレンダー日付を想定しており、時点の日付は読み取り側のゾーンによって異なります。

タイムゾーン ​

次の関数は、DateTimeをタイムゾーン間で変換し、そのオフセットを調べます。

in_tz ​

同じ時点を別のタイムゾーンで再レンダリングします。時点は変わらず、読み取り方だけが変わります。

in_tz(datetime, timezone)

in_tz(DateTime('2026-03-15T09:30:00Z'), 'Asia/Tokyo')

2026-03-15T18:30:00+09:00

assume_tz ​

PlainDateTimeのウォールクロックの表示を、指定されたタイムゾーンで発生したものとして解釈し、DateTimeを生成します。

assume_tzはin_tzとは逆方向です。 in_tzは時点を保持し、表示を変更します。 assume_tzは表示を保持し、時点を決定します。ソースシステムがローカル時刻を送信し、ゾーンを別途通知する場合に使用します。

assume_tz(plain_datetime, timezone, on_gap, on_fold)

assume_tz(PlainDateTime('2026-03-15T09:30:00'), 'Europe/London')

2026-03-15T09:30:00Z

utc_offset ​

UTCからのオフセットを正規文字列として返します: Z、または+02:00などの符号付きオフセット。

utc_offset(datetime)

utc_offset(DateTime('2026-03-15T09:30:00Z'))

Z

utc_offset(in_tz(DateTime('2026-07-15T09:30:00Z'), 'Asia/Tokyo'))

+09:00

is_dst? ​

そのゾーンのその時点で夏時間が有効な場合はtrueを返します。

is_dst?(datetime, timezone)

is_dst?(DateTime('2026-07-15T09:30:00Z'), 'Europe/London')

true

is_dst?(DateTime('2026-01-15T09:30:00Z'), 'Europe/London')

false

observes_dst? ​

指定された年に、そのタイムゾーンが夏時間を採用している場合はtrueを返します。

observes_dst?(timezone)
observes_dst?(timezone, year)

observes_dst?('Europe/London')

true

observes_dst?('Asia/Tokyo')

false

ユースケース: ローカル営業日でイベントをレポートする ​

同じUTC日の2つのイベントが、東京では異なるカレンダー日付になります。日付を取得する前にローカルゾーンに変換してください。そうしないと、15:00 UTC以降のすべてについて日次レポートが誤ります。

入力

{
  "events": [
    {"id": "E-1", "at": "2026-03-15T16:30:00Z"},
    {"id": "E-2", "at": "2026-03-15T09:30:00Z"}
  ]
}

Formula

_.events >> map_by(e ~> {
  id: e.id,
  tokyo_date: PlainDate(in_tz(DateTime(e.at), 'Asia/Tokyo'))
})

出力

[
  {"id": "E-1", "tokyo_date": "2026-03-16"},
  {"id": "E-2", "tokyo_date": "2026-03-15"}
]

E-1は、16:30 UTCが東京では翌朝01:30であるため、16日に移動します。元のUTC値のPlainDateでは、代わりに両方とも15日としてレポートされます。

現在時点とエポック時刻 ​

次の関数は、現在時点を読み取るか、Unixエポック秒との間で変換します。

now ​

ステップ全体で固定されるUTCオフセット付きの現在時点を返します。引数は不要です。

now()

epoch ​

Unixエポック秒からDateTimeを作成します。

epoch(seconds)

epoch(1773567000)

2026-03-15T09:30:00Z

to_epoch ​

DateTimeをUnixエポック秒に変換します。ナノ秒精度が保持されるようにDecimalとして返します。

to_epoch(datetime)

to_epoch(DateTime('2026-03-15T09:30:00Z'))

1773567000

to_iso8601 ​

DateTimeをオフセット付きのISO 8601としてフォーマットします。

to_iso8601(datetime)

to_iso8601(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T09:30:00Z

関連情報 ​

• 変換関数: DateTime、PlainDate、Durationなど、各データ型の構築方法。
• フォーマット関数: format_date、parse_datetime、to_rfc3339。
• データ型: 時間型に関する詳細情報。
• エラーコード: E020やE222などのジョブ失敗をトラブルシューティングします。