Datetime¶

Source: src/memframe/wrappers/analytix/datetime.py

DateTimeWrapper is the public datetime interface exposed through ContextManager.dt. It provides pandas-like methods for extracting date parts, day/month names, rounding to calendar units, timezone localization and conversion, boolean calendar checks, timestamp conversion, string formatting and parsing, timedelta arithmetic, durations, date filtering, resampling, frequency conversion, calendar-aware offsets, replacement, and normalization.

resample lives here (moved from inspection): time-bucketed aggregation belongs to the datetime domain. Use dataset.dt.resample(...) — the old flat dataset.resample(...) no longer exists (see Inspect for the migration note).

Users normally call datetime methods via the dt accessor on a dataset context returned by an upload operation:

dataset = mf.upload_df(frame)
result = dataset.dt.year("event_time")

dataset = await mf.aupload_df(frame)
result = await dataset.dt.ayear("event_time")

datetime is dt-only (dataset.dt.*) — not dataset.year — to avoid collision with ArithmeticWrapper (floor/ceil/round/add/sub). Non-datetime operations remain at the top level.

The lower-level files are implementation details:

src/memframe/core/analytix/datetime/ builds and executes backend-specific SQL (base.py holds the DuckDB-flavoured shared engine plus dialect hooks, postgres.py/clickhouse.py override per backend, factory.py dispatches).
src/memframe/core/orchestrator/analytix/datetime.py resolves the active dataset context and passes persistence metadata.
src/memframe/wrappers/analytix/datetime.py exposes synchronous and asynchronous public methods.

Public API¶

Every datetime operation has synchronous and asynchronous forms:

Synchronous	Asynchronous	Purpose
`extract(column, field)`	`await aextract(...)`	Extract a datetime field
`year(column)`	`await ayear(...)`	Extract year
`month(column)`	`await amonth(...)`	Extract month
`day(column)`	`await aday(...)`	Extract day-of-month
`hour(column)`	`await ahour(...)`	Extract hour
`minute(column)`	`await aminute(...)`	Extract minute
`second(column)`	`await asecond(...)`	Extract second
`dayofweek(column)`	`await adayofweek(...)`	Extract day-of-week
`dayofyear(column)`	`await adayofyear(...)`	Extract day-of-year
`week(column)`	`await aweek(...)`	Extract week-of-year
`quarter(column)`	`await aquarter(...)`	Extract quarter
`floor(column, unit)`	`await afloor(...)`	Floor to calendar unit
`ceil(column, unit)`	`await aceil(...)`	Ceil to calendar unit
`round(column, unit)`	`await around(...)`	Round to calendar unit
`tz_localize(column, tz, ambiguous="raise", nonexistent="raise")`	`await atz_localize(...)`	Localize naive datetimes
`tz_convert(column, tz)`	`await atz_convert(...)`	Convert timezone
`is_month_start(column)`	`await ais_month_start(...)`	Flag month start
`is_month_end(column)`	`await ais_month_end(...)`	Flag month end
`is_year_start(column)`	`await ais_year_start(...)`	Flag year start
`is_year_end(column)`	`await ais_year_end(...)`	Flag year end
`is_quarter_start(column)`	`await ais_quarter_start(...)`	Flag quarter start
`is_quarter_end(column)`	`await ais_quarter_end(...)`	Flag quarter end
`days_in_month(column)`	`await adays_in_month(...)`	Days in month
`is_weekend(column)`	`await ais_weekend(...)`	Flag weekend
`is_weekday(column)`	`await ais_weekday(...)`	Flag weekday
`is_business_day(column)`	`await ais_business_day(...)`	Flag business day
`week_of_month(column)`	`await aweek_of_month(...)`	Week-of-month
`timestamp(column)`	`await atimestamp(...)`	Convert to Unix timestamp
`from_timestamp(column=None, value=None, tz=None)`	`await afrom_timestamp(...)`	Convert Unix timestamp to datetime
`strftime(column, fmt)`	`await astrftime(...)`	Format datetime to string
`strptime(column, fmt)`	`await astrptime(...)`	Parse string to datetime
`add(column, interval)`	`await aadd(...)`	Add interval
`sub(column, interval)`	`await asub(...)`	Subtract interval
`replace(column, **kwargs)`	`await areplace(...)`	Replace datetime components
`normalize(column)`	`await anormalize(...)`	Normalize to midnight
`day_name(column)`	`await aday_name(...)`	Weekday name (`Monday`…)
`month_name(column)`	`await amonth_name(...)`	Month name (`January`…)
`diff(col1, col2, unit="day", target_col=None)`	`await adiff(...)`	`col2 - col1` in a unit
`to_datetime(column, format=None, errors="raise", unit=None, tz=None)`	`await ato_datetime(...)`	Convert column to datetime
`between(column, start, end)`	`await abetween(...)`	Keep rows in range (inclusive)
`before(column, value)`	`await abefore(...)`	Keep rows strictly before value
`after(column, value)`	`await aafter(...)`	Keep rows strictly after value
`select_year(column, values)`	`await aselect_year(...)`	Keep rows whose year is in values
`select_month(column, values)`	`await aselect_month(...)`	Keep rows whose month is in values
`resample(column, freq, agg="count", value_columns=None, group_by=None, label="left", closed="left")`	`await aresample(...)`	Bucket datetimes and aggregate
`asfreq(column, freq, method=None)`	`await aasfreq(...)`	Reindex to a regular frequency
`add_offset(column, years=0, quarters=0, months=0, weeks=0, days=0, business_day=False, target_col=None)`	`await aadd_offset(...)`	Calendar-aware offset

Public methods return the resulting DataFrame directly. Invalid operations raise OperationError.

Usage Overview¶

dataset = mf.upload_df(frame)

sample = dataset.dt.year("event_time")
sample = dataset.dt.floor("event_time", "day")
sample = dataset.dt.is_weekend("event_time")
sample = dataset.dt.day_name("event_time")
sample = dataset.dt.resample("event_time", "ME", agg={"sales": "sum"})
sample = dataset.dt.between("event_time", "2026-01-01", "2026-01-31")

dataset = await mf.aupload_df(frame)

sample = await dataset.dt.ayear("event_time")
sample = await dataset.dt.afloor("event_time", "month")
sample = await dataset.dt.ais_weekend("event_time")
sample = await dataset.dt.aday_name("event_time")
sample = await dataset.dt.aresample("event_time", "ME", agg={"sales": "sum"})
sample = await dataset.dt.abetween("event_time", "2026-01-01", "2026-01-31")

Extract¶

`extract`¶

Generic extractor. field must be one of the supported keys:

Field	Aliases	Description
`year`	—	Year
`month`	—	Month `1..12`
`day`	—	Day-of-month
`hour`	—	Hour `0..23`
`minute`	—	Minute
`second`	—	Second
`dayofweek`	`dow`	Day-of-week
`dayofyear`	`doy`	Day-of-year
`week`	`weekofyear`	Week-of-year
`quarter`	—	Quarter `1..4`

result = dataset.dt.extract("event_time", "year")
result = dataset.dt.extract("event_time", "dow")

result = await dataset.dt.aextract("event_time", "quarter")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`field`	`str`	Field to extract (see table).

Unsupported fields return is_error True ("Unsupported datetime field").

`year`, `month`, `day`, `hour`, `minute`, `second`, `dayofweek`, `dayofyear`, `week`, `quarter`¶

Shortcuts for extract:

result = dataset.dt.year("event_time")
result = dataset.dt.month("signup_date")
result = dataset.dt.dayofweek("created_at")
result = dataset.dt.quarter("closed_at")

result = await dataset.dt.ayear("event_time")
result = await dataset.dt.amonth("signup_date")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.

Generated columns are named dt_<column>_<field> (e.g. dt_event_time_year).

Rounding¶

`floor`, `ceil`, `round`¶

Round datetimes to a calendar unit. Supported unit values are year, quarter, month, week, day, hour, minute, second.

result = dataset.dt.floor("event_time", "day")
result = dataset.dt.ceil("event_time", "month")
result = dataset.dt.round("event_time", "hour")

result = await dataset.dt.afloor("event_time", "week")
result = await dataset.dt.aceil("event_time", "year")
result = await dataset.dt.around("event_time", "day")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`unit`	`str`	Calendar unit to round to.

Unsupported units return is_error True. DuckDB and PostgreSQL use DATE_TRUNC/INTERVAL; ClickHouse uses toStartOfDay/toStartOfMonth etc.

Timezone¶

`tz_localize`¶

Localize naive datetimes to a timezone. tz=None removes timezone (casts to timestamp).

result = dataset.dt.tz_localize("event_time", "UTC")
result = dataset.dt.tz_localize("event_time", None)

result = await dataset.dt.atz_localize("event_time", "America/New_York")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`tz`	`str` or `None`	Target timezone or `None` to strip.
`ambiguous`	`str`	`"raise"` (default); other values warn but are not fully supported in SQL engines.
`nonexistent`	`str`	`"raise"` (default); other values warn similarly.

ambiguous/nonexistent other than "raise" produce a warnings list.

`tz_convert`¶

Convert timezone-aware datetimes. tz=None converts to UTC and strips.

result = dataset.dt.tz_convert("event_time", "UTC")
result = dataset.dt.tz_convert("event_time", "Asia/Kolkata")

result = await dataset.dt.atz_convert("event_time", "UTC")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`tz`	`str` or `None`	Target timezone.

Boolean Checks¶

All boolean checks create a BOOLEAN column dt_<column>_<suffix> and return a sample DataFrame.

`is_month_start`, `is_month_end`, `is_year_start`, `is_year_end`¶

result = dataset.dt.is_month_start("event_time")
result = dataset.dt.is_month_end("event_time")
result = dataset.dt.is_year_start("event_time")
result = dataset.dt.is_year_end("event_time")

`is_quarter_start`, `is_quarter_end`¶

result = dataset.dt.is_quarter_start("event_time")
result = dataset.dt.is_quarter_end("event_time")

`is_weekend`, `is_weekday`, `is_business_day`¶

is_business_day is currently is_weekday (DOW 1..5).

result = dataset.dt.is_weekend("event_time")
result = dataset.dt.is_weekday("event_time")
result = dataset.dt.is_business_day("event_time")

`days_in_month`, `week_of_month`¶

result = dataset.dt.days_in_month("event_time")
result = dataset.dt.week_of_month("event_time")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.

Timestamp Conversion¶

`timestamp`¶

Convert datetime to Unix timestamp (DOUBLE PRECISION).

result = dataset.dt.timestamp("event_time")

result = await dataset.dt.atimestamp("event_time")

Uses EXTRACT(EPOCH ...) on PostgreSQL, epoch() on DuckDB, toUnixTimestamp() on ClickHouse.

`from_timestamp`¶

Convert Unix timestamp (column or scalar) to datetime.

result = dataset.dt.from_timestamp(column="epoch_col", tz="UTC")
result = dataset.dt.from_timestamp(value=1704067200, tz="UTC")

result = await dataset.dt.afrom_timestamp(column="epoch_col")

Parameters:

Parameter	Type	Description
`column`	`str` or `None`	Column holding Unix timestamps.
`value`	`float` or `None`	Scalar Unix timestamp if `column` is omitted.
`tz`	`str` or `None`	Target timezone.

One of column or value is required. Uses TO_TIMESTAMP / toDateTime plus toTimezone on ClickHouse.

Formatting¶

`strftime`¶

Format datetime to string (TEXT).

result = dataset.dt.strftime("event_time", "%Y-%m-%d")

result = await dataset.dt.astrftime("event_time", "%Y-%m-%d")

PostgreSQL converts via _convert_strftime_format (%Y→YYYY), DuckDB uses strftime(), ClickHouse formatDateTime(). Non-timestamp columns are cast to TIMESTAMP/DateTime first.

`strptime`¶

Parse string column to datetime (TIMESTAMP) using a format.

result = dataset.dt.strptime("date_str", "%Y-%m-%d")

result = await dataset.dt.astrptime("date_str", "%Y-%m-%d")

PostgreSQL TO_TIMESTAMP(col, sql_fmt), DuckDB strptime(), ClickHouse parseDateTimeBestEffort().

Parameters:

Parameter	Type	Description
`column`	`str`	Column to format/parse.
`fmt`	`str`	Python `strftime` pattern.

Timedelta¶

`add`, `sub`¶

Add or subtract an interval string.

result = dataset.dt.add("event_time", "1 day")
result = dataset.dt.sub("event_time", "1 hour")

result = await dataset.dt.aadd("event_time", "7 day")
result = await dataset.dt.asub("event_time", "30 minute")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`interval`	`str`	Interval literal (e.g. `"1 day"`, `"3 month"`).

Uses INTERVAL '...' on DuckDB/PostgreSQL and INTERVAL ... with toTimezone handling on ClickHouse.

Replacement and Normalization¶

`replace`¶

Replace one or more datetime components in place (year, month, day, hour, minute, second).

result = dataset.dt.replace("event_time", year=2000, month=1)

result = await dataset.dt.areplace("event_time", hour=0, minute=0)

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`**kwargs`	`int`	Components to replace: `year`, `month`, `day`, `hour`, `minute`, `second`.

Unsupported keys return is_error True. Uses MAKE_TIMESTAMP / makeDateTime with EXTRACT / toYear fallbacks.

`normalize`¶

Normalize to midnight (00:00:00) of the same day.

result = dataset.dt.normalize("event_time")

result = await dataset.dt.anormalize("event_time")

DATE_TRUNC('day') on DuckDB/Postgres, toStartOfDay() on ClickHouse.

Names¶

`day_name`, `month_name`¶

Weekday and month names as text (dt_<column>_day_name, dt_<column>_month_name):

result = dataset.dt.day_name("event_time")    # Monday, Tuesday, ...
result = dataset.dt.month_name("event_time")  # January, February, ...

result = await dataset.dt.aday_name("event_time")
result = await dataset.dt.amonth_name("event_time")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column (text columns are cast).

DAYNAME/MONTHNAME on DuckDB, TO_CHAR(..., 'FMDay'/'FMMonth') on PostgreSQL (the FM prefix strips padding), formatDateTime(..., '%A'/'%B') on ClickHouse. Ideal for group-by analytics (day_name → weekday volumes).

Durations¶

`diff`¶

Two-column duration: col2 - col1 expressed in unit, as a DOUBLE PRECISION column (dt_<col1>_<col2>_diff_<unit>, or target_col):

result = dataset.dt.diff("start_date", "end_date")                    # days
result = dataset.dt.diff("start_date", "end_date", unit="hour")
result = dataset.dt.diff("start_date", "end_date", unit="month", target_col="months")

result = await dataset.dt.adiff("start_date", "end_date", unit="minute")

Parameters:

Parameter	Type	Description
`col1`	`str`	Start datetime column.
`col2`	`str`	End datetime column.
`unit`	`str`	`millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`. Defaults to `"day"`.
`target_col`	`str` or `None`	Name for the result column.

DuckDB/PostgreSQL divide EXTRACT(EPOCH ...) by a per-unit divisor; ClickHouse uses native dateDiff. Calendar months/quarters/years use 30/91.25/365-day conventions (documented approximation, not calendar-exact).

This is the two-column counterpart to stats.datetime_diff, which measures consecutive-row deltas within one column.

Parsing¶

`to_datetime`¶

Canonical column-to-datetime conversion (dt_<column>_todatetime):

result = dataset.dt.to_datetime("date_str")                              # ISO strings
result = dataset.dt.to_datetime("date_str", format="%Y-%m-%d")           # explicit format
result = dataset.dt.to_datetime("date_str", errors="coerce")             # bad values → NULL
result = dataset.dt.to_datetime("epoch", unit="s")                       # Unix timestamps
result = dataset.dt.to_datetime("event_time", tz="UTC")                  # attach timezone

result = await dataset.dt.ato_datetime("date_str", errors="coerce")

Parameters:

Parameter	Type	Description
`column`	`str`	Column to convert (text, date, or numeric epoch).
`format`	`str` or `None`	Explicit `strftime` pattern; delegates to `strptime`.
`errors`	`str`	`"raise"` (default) or `"coerce"` (unparseable → `NULL`).
`unit`	`str` or `None`	Epoch unit: `"s"`, `"ms"`, or `"us"`.
`tz`	`str` or `None`	Timezone to attach after conversion.

coerce uses TRY_CAST (DuckDB), toDateTimeOrNull/parseDateTimeBestEffortOrNull (ClickHouse), and an ISO-pattern guard on PostgreSQL (which has no TRY_CAST; non-ISO strings are out of scope there). Prefer format= when the layout is known.

Filtering¶

Row filters materialize a clone table with matching rows (no new column). between is inclusive; before/after are exclusive:

january = dataset.dt.between("event_time", "2026-01-01", "2026-01-31")
early = dataset.dt.before("event_time", "2026-01-01")
late = dataset.dt.after("event_time", "2026-06-01")
y2026 = dataset.dt.select_year("event_time", 2026)
q1 = dataset.dt.select_month("event_time", [1, 2, 3])

january = await dataset.dt.abetween("event_time", "2026-01-01", "2026-01-31")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column (text columns are cast).
`start` / `end` / `value`	`str`	Datetime bounds; validated with pandas before SQL is built.
`values`	`int` or `list[int]`	Years, or months (`1..12`, validated).

Bounds are parsed by pandas first, so "2026-01-01", "2026-01-01 10:30", and datetime objects all work; unparseable bounds raise OperationError without touching the database. For arbitrary predicates, use Selection (iloc with a raw WHERE string).

Resampling¶

resample buckets a datetime column and aggregates — the time-based group-by at the heart of time-series analytics. Moved here from inspection; the old flat dataset.resample(time_column=..., rule=...) is now dataset.dt.resample(column=..., freq=...).

daily = dataset.dt.resample("event_time", "D")
monthly_sales = dataset.dt.resample("event_time", "ME", agg="sum", value_columns="sales")
multi = dataset.dt.resample("event_time", "ME", agg=["sum", "mean"], value_columns="sales")
by_region = dataset.dt.resample("event_time", "ME", agg={"sales": "sum"}, group_by=["region"])

daily = await dataset.dt.aresample("event_time", "W", agg="mean", value_columns="temp")

Frequency aliases (single-bucket units only; "2h"/"15min" fail loudly):

Alias	Unit
`s`	second
`T`, `min`	minute
`h`	hour
`D`	day
`W`	week (ISO)
`M`, `ME`, `MS`	month
`Q`, `QE`	quarter
`A`, `Y`, `YE`	year

Plus the full unit words (day, month, …).

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column to bucket.
`freq`	`str`	Bucket frequency (see aliases).
`agg`	`str`, `list[str]`, or `dict`	`"count"` (default, no value column), one function, a list over `value_columns`, or `{column: func}` / `{column: [funcs]}`. Functions: `count`, `sum`, `mean`/`avg`, `min`, `max`, `median`, `std`.
`value_columns`	`str`, `list[str]`, or `None`	Columns to aggregate (required unless `agg="count"`).
`group_by`	`str`, `list[str]`, or `None`	Extra grouping keys carried into the output.
`label`	`str`	`"left"` (default) or `"right"` (bucket stamped at interval end).
`closed`	`str`	`"left"` (default) or `"right"` (validated; bins are left-closed).

Output columns are <time_column> (bucket) plus value (single agg) or value_<column>_<agg> per aggregation, plus any group_by keys. Result tables are persisted (deep_cache).

Bucketing is DATE_TRUNC on all backends (ClickHouse toISOWeek for weeks so all backends agree with pandas isocalendar).

`asfreq`¶

Reindex to a regular frequency, materializing gap rows with NULL (or filled) values — the companion that makes irregular series plottable/joinable:

regular = dataset.dt.asfreq("event_time", "D")
filled = dataset.dt.asfreq("event_time", "D", method="ffill")

regular = await dataset.dt.aasfreq("event_time", "h", method="bfill")

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column to reindex.
`freq`	`str`	Target frequency (same aliases as `resample`).
`method`	`str` or `None`	`None` (gaps stay `NULL`), `"ffill"`, or `"bfill"`.

The grid is generated in-engine (generate_series on DuckDB/PostgreSQL, numbers + dateAdd on ClickHouse, capped at 100,000 buckets) and LEFT JOINed; fills use portable correlated subqueries. Like pandas, duplicate timestamps per bucket are refused — resample first. Result tables are persisted (deep_cache).

Calendar Arithmetic¶

`add_offset`¶

Calendar-aware addition — months stay months (unlike add("30 day")):

next_month = dataset.dt.add_offset("event_time", months=1)
combo = dataset.dt.add_offset("event_time", years=1, quarters=1, weeks=1, days=2)
biz = dataset.dt.add_offset("event_time", days=5, business_day=True)

next_month = await dataset.dt.aadd_offset("event_time", months=1)

Parameters:

Parameter	Type	Description
`column`	`str`	Datetime column.
`years` / `quarters` / `months` / `weeks` / `days`	`int`	Calendar units to add (negative allowed). Quarters expand to months.
`business_day`	`bool`	Count `days` as Mon–Fri business days (pandas `BDay` semantics). Combines only with `days`.
`target_col`	`str` or `None`	Name for the result column (`dt_<column>_offset` default).

INTERVAL chains on DuckDB/PostgreSQL, addYears/addQuarters/addMonths/addWeeks/addDays nesting on ClickHouse. business_day uses closed-form weekday arithmetic matching pandas (weekend starts roll forward/backward and consume one offset); holidays are out of scope — see is_business_day.

Return Values and Errors¶

Public datetime methods return the resulting DataFrame directly. Generated table names and result_metadata remain internal to cache and AI layers. Invalid operations raise OperationError:

Unsupported field for extract → "Unsupported datetime field: ..."
Unsupported unit for floor/ceil/round → "Unsupported ceil/round/floor unit: ..."
Unsupported replace keys → "Unsupported field: ..."
from_timestamp without column or value → "Provide either column or value"
Unsupported freq for resample/asfreq → "Unsupported freq: ..."
Unsupported agg/method for resample/asfreq → "Unsupported agg/method: ..."
asfreq on duplicate timestamps per bucket → "... has multiple rows per ... bucket; resample first"
asfreq grids over 100,000 buckets are refused
Unparseable between/before/after bounds, non-int select_year/select_month values, months outside 1..12, non-bool business_day, or business_day combined with calendar units → OperationError before SQL runs
add_offset with all units zero → "at least one offset unit must be non-zero"
Unsupported backend → NotImplementedError wrapped as is_error True

Generated Tables¶

Every datetime operation is non-destructive to the source upload table. Each operation:

Clones the source table into a new transient table (<table>__op_<n>).
Adds a result column (e.g. dt_event_time_year, dt_ts_floor_day).
Populates it with backend-specific SQL (EXTRACT/DATE_TRUNC/ClickHouse to*).
Returns the sample DataFrame directly; table metadata remains internal.

Backend Behavior¶

Datetime supports DuckDB, PostgreSQL, and ClickHouse adapters:

Identifiers are sanitized via SQLIdentifierSanitizer and quoted (" vs `).
EXTRACT(YEAR/MONTH/...) on DuckDB/Postgres vs toYear/toMonth/toDayOfMonth/toHour/... on ClickHouse (with CAST(col AS DateTime) for text columns).
floor/ceil/round use DATE_TRUNC + INTERVAL vs toStartOf* + IF on ClickHouse.
Timezone uses AT TIME ZONE vs toTimezone.
String formatting uses TO_CHAR/strftime vs formatDateTime.
ClickHouse uses ALTER TABLE ... UPDATE ... WHERE 1 instead of UPDATE.
ClickHouse mutations carry SETTINGS mutations_sync = 1 so a subsequent read never observes the pre-update default (async mutations otherwise lag).
Weeks use ISO numbering everywhere (toISOWeek on ClickHouse) and day-of-week follows EXTRACT(DOW) (0=Sunday..6=Saturday; ClickHouse wraps toDayOfWeek % 7) so all backends agree with pandas.
resample buckets with DATE_TRUNC on all backends; asfreq grids come from generate_series (UNNESTed for DuckDB) vs numbers + dateAdd.
diff divides EXTRACT(EPOCH ...) on DuckDB/PostgreSQL vs native dateDiff on ClickHouse; month/quarter/year use 30/91.25/365-day conventions.
Datetime targets on ClickHouse materialize wall time (toTimezone results are instants that would re-render in the server timezone).

Errors¶

Datetime methods raise OperationError for validation or backend failures. Invalid inputs produce is_error True with involved_cols/generated_cols populated where applicable.

API Reference¶

`memframe.wrappers.analytix.datetime.DateTimeWrapper` ¶

Bases: DateTimeOrchestrator

Wrapper around DateTimeOrchestrator with async/sync methods.

`aextract(column, field)` `async` ¶

Asynchronously extract a datetime field from a column.

`extract(column, field)` `async` ¶

Synchronously extract a datetime field from a column.

`ayear(column)` `async` ¶

Asynchronously extract year values from a datetime column.

`year(column)` `async` ¶

Synchronously extract year values from a datetime column.

`amonth(column)` `async` ¶

Asynchronously extract month values from a datetime column.

`month(column)` `async` ¶

Synchronously extract month values from a datetime column.

`aday(column)` `async` ¶

Asynchronously extract day-of-month values.

`day(column)` `async` ¶

Synchronously extract day-of-month values.

`ahour(column)` `async` ¶

Asynchronously extract hour values from datetime entries.

`hour(column)` `async` ¶

Synchronously extract hour values from datetime entries.

`aminute(column)` `async` ¶

Asynchronously extract minute values from datetime entries.

`minute(column)` `async` ¶

Synchronously extract minute values from datetime entries.

`asecond(column)` `async` ¶

Asynchronously extract second values from datetime entries.

`second(column)` `async` ¶

Synchronously extract second values from datetime entries.

`adayofweek(column)` `async` ¶

Asynchronously extract day-of-week values.

`dayofweek(column)` `async` ¶

Synchronously extract day-of-week values.

`adayofyear(column)` `async` ¶

Asynchronously extract day-of-year values.

`dayofyear(column)` `async` ¶

Synchronously extract day-of-year values.

`aweek(column)` `async` ¶

Asynchronously extract week values from a datetime column.

`week(column)` `async` ¶

Synchronously extract week values from a datetime column.

`aquarter(column)` `async` ¶

Asynchronously extract quarter values from a datetime column.

`quarter(column)` `async` ¶

Synchronously extract quarter values from a datetime column.

`afloor(column, unit)` `async` ¶

Asynchronously floor datetime values to a given unit.

`floor(column, unit)` `async` ¶

Synchronously floor datetime values to a given unit.

`aceil(column, unit)` `async` ¶

Asynchronously ceil datetime values to a given unit.

`ceil(column, unit)` `async` ¶

Synchronously ceil datetime values to a given unit.

`around(column, unit)` `async` ¶

Asynchronously round datetime values to a given unit.

`round(column, unit)` `async` ¶

Synchronously round datetime values to a given unit.

`atz_localize(column, tz, ambiguous='raise', nonexistent='raise')` `async` ¶

Asynchronously localize naive datetimes to a timezone.

`tz_localize(column, tz, ambiguous='raise', nonexistent='raise')` `async` ¶

Synchronously localize naive datetimes to a timezone.

`atz_convert(column, tz)` `async` ¶

Asynchronously convert timezone-aware datetimes to another zone.

`tz_convert(column, tz)` `async` ¶

Synchronously convert timezone-aware datetimes to another zone.

`ais_month_start(column)` `async` ¶

Asynchronously flag whether each date is month start.

`is_month_start(column)` `async` ¶

Synchronously flag whether each date is month start.

`ais_month_end(column)` `async` ¶

Asynchronously flag whether each date is month end.

`is_month_end(column)` `async` ¶

Synchronously flag whether each date is month end.

`ais_year_start(column)` `async` ¶

Asynchronously flag whether each date is year start.

`is_year_start(column)` `async` ¶

Synchronously flag whether each date is year start.

`ais_year_end(column)` `async` ¶

Asynchronously flag whether each date is year end.

`is_year_end(column)` `async` ¶

Synchronously flag whether each date is year end.

`ais_quarter_start(column)` `async` ¶

Asynchronously flag whether each date is quarter start.

`is_quarter_start(column)` `async` ¶

Synchronously flag whether each date is quarter start.

`ais_quarter_end(column)` `async` ¶

Asynchronously flag whether each date is quarter end.

`is_quarter_end(column)` `async` ¶

Synchronously flag whether each date is quarter end.

`adays_in_month(column)` `async` ¶

Asynchronously compute number of days in each month.

`days_in_month(column)` `async` ¶

Synchronously compute number of days in each month.

`ais_weekend(column)` `async` ¶

Asynchronously flag whether each date is a weekend.

`is_weekend(column)` `async` ¶

Synchronously flag whether each date is a weekend.

`ais_weekday(column)` `async` ¶

Asynchronously flag whether each date is a weekday.

`is_weekday(column)` `async` ¶

Synchronously flag whether each date is a weekday.

`ais_business_day(column)` `async` ¶

Asynchronously flag whether each date is a business day.

`is_business_day(column)` `async` ¶

Synchronously flag whether each date is a business day.

`aweek_of_month(column)` `async` ¶

Asynchronously compute week-of-month values.

`week_of_month(column)` `async` ¶

Synchronously compute week-of-month values.

`atimestamp(column)` `async` ¶

Asynchronously convert datetime values to Unix timestamps.

`timestamp(column)` `async` ¶

Synchronously convert datetime values to Unix timestamps.

`afrom_timestamp(column=None, value=None, tz=None)` `async` ¶

Asynchronously convert Unix timestamps to datetime values.

`from_timestamp(column=None, value=None, tz=None)` `async` ¶

Synchronously convert Unix timestamps to datetime values.

`astrftime(column, fmt)` `async` ¶

Asynchronously format datetime values to strings.

`strftime(column, fmt)` `async` ¶

Synchronously format datetime values to strings.

`astrptime(column, fmt)` `async` ¶

Asynchronously parse datetime strings using a format.

`strptime(column, fmt)` `async` ¶

Synchronously parse datetime strings using a format.

`aadd(column, interval)` `async` ¶

Asynchronously add a time interval to datetime values.

`add(column, interval)` `async` ¶

Synchronously add a time interval to datetime values.

`asub(column, interval)` `async` ¶

Asynchronously subtract a time interval from datetime values.

`sub(column, interval)` `async` ¶

Synchronously subtract a time interval from datetime values.

`areplace(column, **kwargs)` `async` ¶

Asynchronously replace components of datetime values.

`replace(column, **kwargs)` `async` ¶

Synchronously replace components of datetime values.

`anormalize(column)` `async` ¶

Asynchronously normalize datetimes to midnight.

`normalize(column)` `async` ¶

Synchronously normalize datetimes to midnight.

`aday_name(column)` `async` ¶

Asynchronously extract weekday names from a datetime column.

`day_name(column)` `async` ¶

Synchronously extract weekday names from a datetime column.

`amonth_name(column)` `async` ¶

Asynchronously extract month names from a datetime column.

`month_name(column)` `async` ¶

Synchronously extract month names from a datetime column.

`adiff(col1, col2, unit='day', target_col=None)` `async` ¶

Asynchronously compute col2 - col1 in the given unit.

`diff(col1, col2, unit='day', target_col=None)` `async` ¶

Synchronously compute col2 - col1 in the given unit.

`ato_datetime(column, format=None, errors='raise', unit=None, tz=None)` `async` ¶

Asynchronously convert a column to datetime.

`to_datetime(column, format=None, errors='raise', unit=None, tz=None)` `async` ¶

Synchronously convert a column to datetime.

`abetween(column, start, end)` `async` ¶

Asynchronously filter rows to a datetime range (inclusive).

`between(column, start, end)` `async` ¶

Synchronously filter rows to a datetime range (inclusive).

`abefore(column, value)` `async` ¶

Asynchronously keep rows with datetime strictly before value.

`before(column, value)` `async` ¶

Synchronously keep rows with datetime strictly before value.

`aafter(column, value)` `async` ¶

Asynchronously keep rows with datetime strictly after value.

`after(column, value)` `async` ¶

Synchronously keep rows with datetime strictly after value.

`aselect_year(column, values)` `async` ¶

Asynchronously keep rows whose year is in values.

`select_year(column, values)` `async` ¶

Synchronously keep rows whose year is in values.

`aselect_month(column, values)` `async` ¶

Asynchronously keep rows whose month is in values.

`select_month(column, values)` `async` ¶

Synchronously keep rows whose month is in values.

`aresample(column, freq, agg='count', value_columns=None, group_by=None, label='left', closed='left')` `async` ¶

Asynchronously bucket a datetime column and aggregate.

`resample(column, freq, agg='count', value_columns=None, group_by=None, label='left', closed='left')` `async` ¶

Synchronously bucket a datetime column and aggregate.

`aasfreq(column, freq, method=None)` `async` ¶

Asynchronously reindex a datetime column to a regular frequency.

`asfreq(column, freq, method=None)` `async` ¶

Synchronously reindex a datetime column to a regular frequency.

`aadd_offset(column, years=0, quarters=0, months=0, weeks=0, days=0, business_day=False, target_col=None)` `async` ¶

Asynchronously add a calendar-aware offset to datetimes.

`add_offset(column, years=0, quarters=0, months=0, weeks=0, days=0, business_day=False, target_col=None)` `async` ¶

Synchronously add a calendar-aware offset to datetimes.

Datetime¶

Public API¶

Usage Overview¶

Extract¶

extract¶

year, month, day, hour, minute, second, dayofweek, dayofyear, week, quarter¶

Rounding¶

floor, ceil, round¶

Timezone¶

tz_localize¶

tz_convert¶

Boolean Checks¶

is_month_start, is_month_end, is_year_start, is_year_end¶

is_quarter_start, is_quarter_end¶

is_weekend, is_weekday, is_business_day¶

days_in_month, week_of_month¶

Timestamp Conversion¶

timestamp¶

from_timestamp¶

Formatting¶

strftime¶

strptime¶

Timedelta¶

add, sub¶

Replacement and Normalization¶

replace¶

normalize¶

Names¶

day_name, month_name¶

Durations¶

diff¶

Parsing¶

to_datetime¶

Filtering¶

Resampling¶

asfreq¶

Calendar Arithmetic¶

add_offset¶

Return Values and Errors¶

Generated Tables¶

Backend Behavior¶

Errors¶

API Reference¶

memframe.wrappers.analytix.datetime.DateTimeWrapper ¶

aextract(column, field) async ¶

extract(column, field) async ¶

ayear(column) async ¶

year(column) async ¶

amonth(column) async ¶

month(column) async ¶

aday(column) async ¶

day(column) async ¶

ahour(column) async ¶

hour(column) async ¶

aminute(column) async ¶

minute(column) async ¶

asecond(column) async ¶

second(column) async ¶

adayofweek(column) async ¶

dayofweek(column) async ¶

adayofyear(column) async ¶

dayofyear(column) async ¶

aweek(column) async ¶

week(column) async ¶

aquarter(column) async ¶

quarter(column) async ¶

afloor(column, unit) async ¶

floor(column, unit) async ¶

aceil(column, unit) async ¶

ceil(column, unit) async ¶

around(column, unit) async ¶

round(column, unit) async ¶

atz_localize(column, tz, ambiguous='raise', nonexistent='raise') async ¶

tz_localize(column, tz, ambiguous='raise', nonexistent='raise') async ¶

atz_convert(column, tz) async ¶

tz_convert(column, tz) async ¶

ais_month_start(column) async ¶

is_month_start(column) async ¶

ais_month_end(column) async ¶

is_month_end(column) async ¶

`extract`¶

`year`, `month`, `day`, `hour`, `minute`, `second`, `dayofweek`, `dayofyear`, `week`, `quarter`¶

`floor`, `ceil`, `round`¶

`tz_localize`¶

`tz_convert`¶

`is_month_start`, `is_month_end`, `is_year_start`, `is_year_end`¶

`is_quarter_start`, `is_quarter_end`¶

`is_weekend`, `is_weekday`, `is_business_day`¶

`days_in_month`, `week_of_month`¶

`timestamp`¶

`from_timestamp`¶

`strftime`¶

`strptime`¶

`add`, `sub`¶

`replace`¶

`normalize`¶

`day_name`, `month_name`¶

`diff`¶

`to_datetime`¶

`asfreq`¶

`add_offset`¶

`memframe.wrappers.analytix.datetime.DateTimeWrapper` ¶

`aextract(column, field)` `async` ¶

`extract(column, field)` `async` ¶

`ayear(column)` `async` ¶

`year(column)` `async` ¶

`amonth(column)` `async` ¶

`month(column)` `async` ¶

`aday(column)` `async` ¶

`day(column)` `async` ¶

`ahour(column)` `async` ¶

`hour(column)` `async` ¶

`aminute(column)` `async` ¶

`minute(column)` `async` ¶

`asecond(column)` `async` ¶

`second(column)` `async` ¶

`adayofweek(column)` `async` ¶

`dayofweek(column)` `async` ¶

`adayofyear(column)` `async` ¶

`dayofyear(column)` `async` ¶

`aweek(column)` `async` ¶

`week(column)` `async` ¶

`aquarter(column)` `async` ¶

`quarter(column)` `async` ¶

`afloor(column, unit)` `async` ¶

`floor(column, unit)` `async` ¶

`aceil(column, unit)` `async` ¶

`ceil(column, unit)` `async` ¶

`around(column, unit)` `async` ¶

`round(column, unit)` `async` ¶

`atz_localize(column, tz, ambiguous='raise', nonexistent='raise')` `async` ¶

`tz_localize(column, tz, ambiguous='raise', nonexistent='raise')` `async` ¶

`atz_convert(column, tz)` `async` ¶

`tz_convert(column, tz)` `async` ¶

`ais_month_start(column)` `async` ¶

`is_month_start(column)` `async` ¶

`ais_month_end(column)` `async` ¶

`is_month_end(column)` `async` ¶

`ais_year_start(column)` `async` ¶

`is_year_start(column)` `async` ¶

`ais_year_end(column)` `async` ¶

`is_year_end(column)` `async` ¶

`ais_quarter_start(column)` `async` ¶

`is_quarter_start(column)` `async` ¶

`ais_quarter_end(column)` `async` ¶

`is_quarter_end(column)` `async` ¶

`adays_in_month(column)` `async` ¶

`days_in_month(column)` `async` ¶

`ais_weekend(column)` `async` ¶

`is_weekend(column)` `async` ¶

`ais_weekday(column)` `async` ¶

`is_weekday(column)` `async` ¶

`ais_business_day(column)` `async` ¶

`is_business_day(column)` `async` ¶

`aweek_of_month(column)` `async` ¶

`week_of_month(column)` `async` ¶

`atimestamp(column)` `async` ¶

`timestamp(column)` `async` ¶

`afrom_timestamp(column=None, value=None, tz=None)` `async` ¶

`from_timestamp(column=None, value=None, tz=None)` `async` ¶