Date / time functions

# ======================================================================
# Date handling over one book's `published` timestamp. `Extract*` pulls a
# component (year, month, day, weekday, quarter); `Trunc*` rounds a timestamp
# down to a unit (`date_trunc`); `Now()` is the statement timestamp.
# ======================================================================

# ----------------------------------------------------------------------
# date parts & truncation over the 2026 book
# ----------------------------------------------------------------------

# Django:
Book.objects.filter(title="Postgres for Authors").annotate(
    year=ExtractYear("published"), month=ExtractMonth("published"),
    day=ExtractDay("published"), weekday=ExtractWeekDay("published"),
    quarter=ExtractQuarter("published"), week=ExtractWeek("published"),
    isoyear=ExtractIsoYear("published"), isodow=ExtractIsoWeekDay("published"),
    hour=ExtractHour("published"), minute=ExtractMinute("published"),
    second=ExtractSecond("published"),
    tmonth=TruncMonth("published"), tyear=TruncYear("published"),
    tday=TruncDay("published"), tweek=TruncWeek("published"),
    tquarter=TruncQuarter("published"), thour=TruncHour("published"),
    tminute=TruncMinute("published"), tsecond=TruncSecond("published"),
    ttime=TruncTime("published"), now=Now(),
)

# SQL:
#   SELECT EXTRACT(YEAR
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "year", EXTRACT(MONTH
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "month", EXTRACT(DAY
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "day", EXTRACT(DOW
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') + 1 AS "weekday", EXTRACT(QUARTER
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "quarter", EXTRACT(WEEK
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "week", EXTRACT(ISOYEAR
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "isoyear", EXTRACT(ISODOW
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "isodow", EXTRACT(HOUR
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "hour", EXTRACT(MINUTE
#   FROM "examples_book"."published" AT TIME ZONE 'UTC') AS "minute", EXTRACT(SECOND
#   FROM DATE_TRUNC('second', "examples_book"."published" AT TIME ZONE 'UTC')) AS "second", DATE_TRUNC('month', "examples_book"."published" AT TIME ZONE 'UTC') AS "tmonth", DATE_TRUNC('year', "examples_book"."published" AT TIME ZONE 'UTC') AS "tyear", DATE_TRUNC('day', "examples_book"."published" AT TIME ZONE 'UTC') AS "tday", DATE_TRUNC('week', "examples_book"."published" AT TIME ZONE 'UTC') AS "tweek", DATE_TRUNC('quarter', "examples_book"."published" AT TIME ZONE 'UTC') AS "tquarter", DATE_TRUNC('hour', "examples_book"."published" AT TIME ZONE 'UTC') AS "thour", DATE_TRUNC('minute', "examples_book"."published" AT TIME ZONE 'UTC') AS "tminute", DATE_TRUNC('second', "examples_book"."published" AT TIME ZONE 'UTC') AS "tsecond", ("examples_book"."published" AT TIME ZONE 'UTC')::time AS "ttime", STATEMENT_TIMESTAMP() AS "now"
#   FROM "examples_book"
#   WHERE "examples_book"."title" = 'Postgres for Authors'
#   ORDER BY "examples_book"."id" ASC
#   LIMIT 1

# Result:
#   ExtractYear      -> 2026
#   ExtractMonth     -> 1
#   ExtractDay       -> 15
#   ExtractWeekDay   -> 5  (1=Sun .. 7=Sat)
#   ExtractISOWeekDay-> 4  (1=Mon .. 7=Sun)
#   ExtractQuarter   -> 1
#   ExtractWeek      -> 3
#   ExtractISOYear   -> 2026
#   ExtractHour      -> 0
#   ExtractMinute    -> 0
#   ExtractSecond    -> 0
#   TruncMonth       -> 2026-01-01
#   TruncYear        -> 2026-01-01
#   TruncDay         -> 2026-01-15
#   TruncWeek        -> 2026-01-12
#   TruncQuarter     -> 2026-01-01
#   TruncHour        -> 2026-01-15 00:00
#   TruncMinute      -> 2026-01-15 00:00
#   TruncSecond      -> 2026-01-15 00:00:00
#   TruncTime        -> 00:00:00
#   Now()            -> 2026-05-22 19:01 UTC