User Guide

Timestamps overview

Montycat handles timestamp indexes natively.
It dynamically parses timestamps supplied by clients and supports a variety of time formats.
Montycat's “preferred” default is ISO 8601.

Date Only Formats

• YYYY-MM-DD → 2021-07-15
• DD-MM-YYYY → 15-07-2021
• DD.MM.YYYY → 15.07.2021
• YYYY/MM/DD → 2021/07/15
• DD Mon YYYY → 15 Jul 2021
• DD Month YYYY → 15 July 2021
• Mon DD, YYYY → Jul 15, 2021
• DD/MM/YYYY → 15/07/2021

Time Only Formats

• HH:MM → 14:30
• HH:MM:SS → 14:30:45
• HH:MM AM/PM → 02:30 PM (12-hour clock)
• HH:MM (24-hour strict) → 23:59
• HH:MM:SS.sss… → 14:30:45.123456 (with subseconds, 3–6 digits)

Date + Time Formats

• YYYY-MM-DD HH:MM:SS → 2021-07-15 14:30:45
• YYYY-MM-DDTHH:MM:SS → 2021-07-15T14:30:45 (ISO 8601 with T)

Week-based Formats

• YYYY-Www → 2021-W29 (ISO week date)
• YYYY-Www-D → 2021-W29-3 (ISO week + weekday, here 3 = Wednesday)

RFC 3339 and ISO Extended

• YYYY-MM-DDTHH:MM:SS.sssZ → 2021-07-15T14:30:45.123Z (Zulu/UTC time; fractional seconds are optional)
• YYYY-MM-DDTHH:MM:SS±HH:MM → 2021-07-15T09:30:45-05:00 (UTC offsets are normalized to the same instant)

Using timestamps

To work with timestamps, use the Timestamp class.

from montycat import Schema, Timestamp
from keyspaces import Employees
import datetime

class EmployeesSchema(Schema):
    username: string
    location: string
    age: number
    dateHired: Timestamp

datetime_str = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')

record = EmployeesSchema(
    username="Name",
    location="Location",
    age=21,
    dateHired=Timestamp(datetime_str)
).serialize()

res2 = await Employees.insert_value(record)

# {"status": True, "payload": "128222336824100726154851618391811195396", "error": None}

Lookups using timestamps

Once records with timestamps are stored, Montycat enables timestamp-based lookups on both keys and values.
Malformed bounds, invalid ranges, and timestamps outside the index's representable range return an error instead of an empty result.
The Timestamp class supports range queries:

• before → all records before a given timestamp
• after → all records after a given timestamp
• range → records between a start and stop

from keyspaces import Employees
from montycat import Timestamp

res1 = await Employees.lookup_values_where(
    dateHired: Timestamp(after="2025-06-10 12:00:00"),
)

# {
#  "status": True,
#  "payload": [{username: 'Name', location: 'Location', age: 21, dateHired: '2025-08-10 12:00:00'}],
#  "error": None
# }

res2 = await Employees.lookup_values_where(
    dateHired: Timestamp(before="2025-08-24 12:00:00"),
)

res3 = await Employees.lookup_values_where(
    dateHired: Timestamp(start="2025-06-10 12:00:00", stop="2025-08-24 12:00:00"),
)

res4 = await Employees.lookup_keys_where(
    dateHired: Timestamp(after="2025-06-10 12:00:00"),
)

# {"status": True, "payload": ["128222336824100726154851618391811195396"], "error": None}