Date and time types

The Data API supports various time-related types.

Date

Use the date type for dates with no time or timezone component.

The date must be represented in RFC 3339 full-date format (YYYY-MM-DD) where the year is at least 4 digits. If the year is positive and greater than 4 digits, it must be prefixed by +, such as +YYYYYY-MM-DD.

Client behavior:

Python: Provides custom date and time classes to augment or replace the standard library classes.
TypeScript: Accepts properly formatted strings or DataAPIDate instances. Returns DataAPIDate.
Java: Accepts and returns java.util.Date

Time

Use the time type for time of day without an associated date or timezone.

The time must be represented in RFC 3339 partial-time format including HH:MM:SS and optional nanoseconds (.nnnnnnnnn).

In responses, sub-seconds are expanded in groups of three digits as needed. For example, a time written as "12:34:56.7887" is subsequently returned as "12:34:56.788700".

Client behavior:

Python: Provides custom date and time classes to augment or replace the standard library classes.
TypeScript: Accepts properly formatted strings or DataAPITime instances. Returns DataAPITime.
Java: Accepts and returns java.time.LocalTime

Timestamp

Use the timestamp type for a date and time with millisecond precision.

The timestamp must be represented as a string in complete RFC 3339 date-time format.

RFC 3339 date-time format rules

Include the following components in order given: Year, month, day, T, hour, minute, second, sub-seconds, offset. For example, 1984-01-10T12:55:01Z.

Only the sub-seconds are optional. All other components are required. If a required component has no value, use zero-padding to achieve the required format.
The year must be at least 4 digits, optionally prefixed by -. If the year is positive and more than 4 digits, it must be prefixed by +.
Month, day, hour, and minute must be 2 digits. For values 0-9, you must include a leading 0, such as 01 for January.
T must separate the date from the time, as in 1984-01-10T12:01Z
The offset can be Z (shorthand for +00:00) or an ISO-formatted offset consisting of + or - followed by HH:MM, such as +05:00 or -08:00. The offset hour and minute must be 2 digits.
Sub-seconds are optional and can include up to 3 digits (millisecond precision), defined as .nnn, such as 1984-01-10T12:01:23.456Z or 1984-01-10T12:01:23.4Z. Sub-seconds are always returned as 3 digits. For example, 1984-01-10T12:01:23.4Z is returned as 1984-01-10T12:01:23.400Z.

timestamp format examples

# Minimum expression
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS+HH:MM
YYYY-MM-DDTHH:MM:SS-HH:MM

# Optional sub-seconds
YYYY-MM-DDTHH:MM:SS.nnnZ
YYYY-MM-DDTHH:MM:SS.nnn+HH:MM
YYYY-MM-DDTHH:MM:SS.nnn-HH:MM

# Optional negative sign before the year
-YYYY-MM-DDTHH:MM:SS.nnnZ
-YYYY-MM-DDTHH:MM:SS.nnn+HH:MM
-YYYY-MM-DDTHH:MM:SS.nnn-HH:MM

# Positive sign before the year if the year is positive and greater than 4 digits
+YYYYYY-MM-DDTHH:MM:SS.nnnZ
+YYYYYY-MM-DDTHH:MM:SS.nnn+HH:MM
+YYYYYY-MM-DDTHH:MM:SS.nnn-HH:MM

Client behavior:

Python: Provides custom date and time classes to augment or replace the standard library classes.
TypeScript: Accepts properly formatted strings or Date instances. Returns Date.
Java: Accepts and returns java.time.Instant.

Duration

Use the duration type for time intervals.

The preferred format is ISO-8601 interval format, such as P3Y6M4DT12H30M5S.

ISO-8601 duration format rules

Prefixed by P (positive duration) or -P (negative duration).
Contains a non-empty sequence of one or more sets of quantities and units in strict decreasing order.
Quantities must be non-negative integers.
Units must use the following values in the order given: Y, M, D, H, M, S. Note that the first M is months and the second M is minutes.
If the duration includes sub-day units (hours, minutes, seconds), you must include T before the first sub-day quantity, such as P10DT2H30M or PT2H30M.
Can skip units, but the units must still follow the given order, such as P1Y22DT45M30S.
Cannot repeat units.
Cannot be empty. For zero duration, you must specify at least one unit with a 0 quantity, such as P0Y.

For lossless inserts down to nanosecond precision, use the Apache Cassandra® notation for durations, such as 12y3mo1d or 12y3mo1d12h30m5s.

Cassandra duration notation rules

A non-empty sequence of one or more sets of quantities and units in strict decreasing order.
Optionally prefixed by - (negative duration).
Quantities are non-negative integers of at least one digit.
Units must use the following case-insensitive values in the order given: y, mo, w, d, h, m, s, ms, us (or µs), ns.
Can skip units, but the units must still follow the given order, such as 1y22d45m30s.
Cannot repeat units.
Cannot be empty. For zero duration, you must specify at least one unit with a 0 quantity, such as 0s.

Client behavior:

Python: Provides custom date and time classes to augment or replace the standard library classes.
TypeScript: Accepts properly formatted strings or DataAPIDuration instances. Returns DataAPIDuration.
Java: Accepts java.time.Period and/or java.time.Duration. Returns com.datastax.astra.client.tables.definition.TableDuration.

Column timestamps (unsupported)

The Data API supports the timestamp data type, but it doesn’t expose CQL write timestamps. Additionally, the Data API doesn’t set timestamps for any mutation. To read or write CQL write timestamps, use CQL directly instead of the Data API.

Date and time types

Date

Time

Timestamp

Duration

Column timestamps (unsupported)

Was this helpful?

Give Feedback