@terascope/data-mate / teal-frame/date-value

teal-frame/date-value

Variables

DATE_MS

const DATE_MS: "ms" = 'ms'

Defined in: data-mate/src/teal-frame/date-value.ts:27

How TealFrame stores a Date field, matching what DataFrame holds.

DataFrame stores epoch milliseconds, or a DateTuple ([epochMillis, offsetMinutes]) once setTimezone, toTimeZone or toTimeZoneUsingLocation has attached a display offset. The choice is made per value. Here every Date column has one type:

STRUCT(ms BIGINT, tz_offset SMALLINT) tz_offset is NULL unless an offset was set

With one shape for every date, readers never need to know whether an earlier step attached an offset. A date without an offset renders with a Z suffix.

Compared with a TIMESTAMP column, the file is about a third smaller (milliseconds compress better than microseconds) and range filters and writes are faster. Date functions pay a small cost for the per-row offset check.

DuckDB does not treat a number as a date (hour(BIGINT) does not bind and there is no BIGINT to TIMESTAMP cast), so every date expression wraps the member in epoch_ms(...).

---

DATE_OFFSET

const DATE_OFFSET: "tz_offset" = 'tz_offset'

Defined in: data-mate/src/teal-frame/date-value.ts:28

---

DATE_TYPE

const DATE_TYPE: DuckDBStructType

Defined in: data-mate/src/teal-frame/date-value.ts:33

Functions

dateJson()

dateJson(accessor): string

Defined in: data-mate/src/teal-frame/date-value.ts:104

SQL that renders the date as JSON text, byte-for-byte equal to toISO8601. A missing or zero offset renders as UTC with a Z; any other offset renders the local wall time followed by +HH:MM or -HH:MM.

Parameters

Parameter	Type
accessor	string

Returns

string

---

fromDateValue()

fromDateValue(value): unknown

Defined in: data-mate/src/teal-frame/date-value.ts:51

Converts the struct back to DataFrame's form: a DateTuple, or plain epoch millis.

Parameters

Parameter	Type
value	unknown

Returns

unknown

---

fromTimestampSQL()

fromTimestampSQL(expression): string

Defined in: data-mate/src/teal-frame/date-value.ts:94

SQL that turns a TIMESTAMP back into a date value with no offset. In DataFrame, a date function that returns a date also returns plain epoch millis, even for tuple input.

Parameters

Parameter	Type
expression	string

Returns

string

---

instantSQL()

instantSQL(accessor): string

Defined in: data-mate/src/teal-frame/date-value.ts:77

SQL for the instant as a TIMESTAMP, for date functions that ignore the offset.

Parameters

Parameter	Type
accessor	string

Returns

string

---

localSQL()

localSQL(accessor): string

Defined in: data-mate/src/teal-frame/date-value.ts:86

SQL for the local wall time as a TIMESTAMP: the instant shifted by the offset, or the instant itself when there is none. This matches getValidDateWithTimezone, which DataFrame's date functions use on a DateTuple. The per-row offset check is a single coalesce.

Parameters

Parameter	Type
accessor	string

Returns

string

---

renderPlainDate()

renderPlainDate(value): unknown

Defined in: data-mate/src/teal-frame/date-value.ts:65

Renders a plain { ms, tz_offset } object (the struct after toPlainValue) the way DataFrame's toISO8601 renders the same value. Other values are returned unchanged.

Parameters

Parameter	Type
value	unknown

Returns

unknown

---

toDateValue()

toDateValue(value): DuckDBStructValue | null

Defined in: data-mate/src/teal-frame/date-value.ts:39

Converts a JS date value to the struct. Accepts epoch millis (what coerceToType produces for a plain date) or a DateTuple, whose offset is kept.

Parameters

Parameter	Type
value	unknown

Returns

DuckDBStructValue | null