User Guide

Everything you need to install, configure, and build with Montycat — from getting started to governance, advanced operations, and security.

Timestamps overview

Montycat handles timestamps related indexes natively.
It supports dinamic parsing of timestamps from clinet sides and provide support to 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)

ISO Extended with Zulu

  • YYYY-MM-DDTHH:MM:SS.sssZ → 2021-07-15T14:30:45.123Z (Zulu/UTC time, subseconds optional up to 3 digits)

Using timestamps

To work with timestamps, use the Timestamp class.

Timestamps must always be provided as stringified values.

Performance note: Montycat timestamps parsing is highly CPU-bound.
Avoid massive bulk inserts with timestamp-heavy records, as dynamic parsing may slow down ingestion.

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.
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}