> For the complete documentation index, see [llms.txt](https://docs.ninox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ninox.com/ninox-scripting/automate-your-workflows/work-with-functions/dates-and-time.md). # Dates and time Dates and time values drive schedules, deadlines, logs, and reports in Ninox. This chapter shows you how to create date values, measure spans, extract date parts, and build reporting keys for dashboards and automation. In this chapter, you will learn how to: * Create current and fixed date or time values. * Format date and time output. * Measure elapsed time and add time offsets. * Extract parts like year, month, weekday, or quarter. * Build reporting keys and business calculations from dates.
Function (A-Z)Task
age()Return the age in years from a date
date()Create a specific date
datetime()Create a specific date and time
day()Return the day of the month
days()Return the number of days between two dates
duration()Return the span between two date or time values
endof()Return the end of a period such as a month
format()Display a date or time value as text
month()Return the month number
now()Return the current date and time
quarter()Return the quarter number
time()Create a specific time value
timeinterval()Create a duration offset such as 2 hours
timestamp()Convert a value to a UTC-based timestamp
today()Return the current date
week()Return the week number
weekday()Return the weekday number
workdays()Return business days between two dates
year()Return the year number
yearmonth()Build a year-month reporting key
yearquarter()Build a year-quarter reporting key
yearweek()Build a year-week reporting key
## Create date and time values Use these functions when you need a real date or time value. They are useful for stamps, due dates, schedules, and logs. ### Get today’s date with `today()` Use `today()` when only the date matters. Use it when you want to: * Compare against a deadline. * Use the date of today directly or as a basis for further calculations. `today()` returns the current date without a time part. #### Let’s take a look at some examples: ```ninox if today() > due_date then "Overdue" else "On time" end ``` Checks whether a record is past its due date. ```ninox today() + 7 ``` Builds the date seven days from today. ```ninox year(today()) ``` Returns the current year from today’s date. ### Get the current date and time with `now()` Use `now()` when the exact moment matters. Use it when you want to: * Stamp record creation. * Measure elapsed hours or minutes. * Build date calculations from the current timestamp. `now()` returns the exact current timestamp at the moment the function runs. #### Let’s take a look at some examples: ```ninox created_at := now() ``` Stores the current timestamp in a field. ```ninox date(now()) + 7 ``` Builds a date value for seven days from today. ### Create fixed values with `date()`, `time()`, and `datetime()` Use `date()` to create a date or convert a time-based value to a date. Use `time()` to create a fixed time value. Use `datetime()` to create a local timestamp from numeric values, a date and time, or Unix time in milliseconds. Use them when you want to: * Build a due date from year, month, and day. * Convert a time-related value to a time. * Set a meeting time. `date(any)`\ `date(year, month, day)`\ `time()`\ `time(any)`\ `time(hour, minute)`\ `time(hour, minute, second)`\ `time(hour, minute, second, millisecond)`\ `datetime(milliseconds)`\ `datetime(year, month, day)`\ `datetime(year, month, day, hour)`\ `datetime(year, month, day, hour, minute)`\ `datetime(year, month, day, hour, minute, second)`\ `datetime(year, month, day, hour, minute, second, millisecond)`\ `datetime(date, time)` * `any` (for `date(any)`): a date, datetime, or numeric timestamp in milliseconds * `year`: the year value * `month`: the month number * `day`: the day of the month * `hour`: the hour value in 24-hour format * `minute`: the minute value * `second`: the second value * `millisecond`: the millisecond value * `any` (for `time(any)`): a date, datetime, appointment boundary, time, or numeric timestamp in milliseconds * `date`: the date part * `time`: the time part If you pass a number to `date(any)`, Ninox treats it as Unix time in milliseconds. If you omit the time part in `datetime()`, Ninox uses `00:00`. If you pass a number to `time(any)`, Ninox treats it as Unix time in milliseconds. #### Let’s take a look at some examples: ```ninox date(2026, 12, 31) ``` Creates the date 31 December 2026. ```ninox date(appointment) ``` Returns the date part from the `appointment` date/time field. ```ninox date(2026, 8, 0) ``` Returns 31 July 2026. Use `0` as the day to get the last day of the previous month. ```ninox date(1617873118285) ``` Converts the Unix timestamp in milliseconds into a date value. ```ninox time() ``` Returns the current local time. ```ninox time(endof(appointment)) ``` Returns the time part from the end of the `appointment` field. ```ninox time(14, 30) ``` Creates the time value 14:30. ```ninox time(14, 30, 45) ``` Creates a time value with seconds. ```ninox time(14, 30, 45, 125) ``` Creates a time value with milliseconds. ```ninox datetime(2026, 4, 22) ``` Creates a local timestamp for 22 April 2026 at 00:00. ```ninox datetime(2026, 4, 22, 9) ``` Creates a local timestamp for 22 April 2026 at 9:00. ```ninox datetime(2026, 4, 22, 9, 30) ``` Creates a local timestamp for 22 April 2026 at 9:30. ```ninox datetime(2026, 4, 22, 9, 30, 45) ``` Creates the same timestamp like above with 45 seconds. ```ninox datetime(date, time) ``` Combines the date from the field `Date` and the time from the field `Time` into one timestamp. ```ninox datetime(1617873118285) ``` Converts a Unix timestamp in milliseconds into a local timestamp. Tips: * Use `date(year, month, 0)` to get the last day of the previous month. * Use `datetime(date, time)` when date and time are stored in separate fields. ### Convert values to UTC-based timestamps with `timestamp()` Use `timestamp(any)` to convert a time-related value to a UTC-based timestamp. Use it when you want to: * Convert a date or datetime to a UTC-based timestamp. `timestamp(any)` * `any`: a time-related value, or a number that represents Unix time in milliseconds If the input has no time part, Ninox uses `00:00` related to your local time zone. #### Let’s take a look at some examples: ```ninox timestamp(1640991540010) ``` Converts Unix milliseconds into a UTC-based timestamp. ```ninox number(timestamp('Date + Time')) ``` Returns the numeric Unix time in milliseconds for the `'Date + Time'` value. ```ninox timestamp(format(now(), "x")) ``` Converts a millisecond value into a timestamp. Tips: * Use `number(timestamp(...))` when you need the Unix value in milliseconds. * Use `now()` when you need the current local timestamp. ## Format date and time output Use `format()` when you want to display a date, time, timestamp, or appointment as readable text. This is useful for: * print layouts * exported values `format(value, string)` * `value`: the value you want to format * `string`: the pattern of the format as text Examples: ```ninox format(today(), "YYYY-MM-DD") ``` Returns a value such as `2026-04-22`. ```ninox format(now(), "dddd, DD MMMM YYYY") ``` Returns a value such as `Wednesday, 23 April 2026`. ```ninox format(now(), "HH:mm") ``` Returns a value such as `14:30`. ```ninox format(now(), "hh:mm a") ``` Returns a value such as `02:30 pm`. You can also pass a language code as the third argument: ```ninox format(today(), "DD MMMM YYYY", "fr") ``` This returns the formatted date in French. ### Common format codes Use these format codes inside the format pattern:
Format codeDescriptionExample
YYYear with 2 digits21
YYYYYear with 4 digits2021
MMonth with 1 or 2 digits1 ... 12
MoMonth as an ordinal number1st ... 12th
MMMonth with 2 digits01 ... 12
MMMMonth name with 3 lettersFeb
MMMMFull month nameFebruary
DDay of month with 1 or 2 digits1 ... 31
DoDay of month as an ordinal number1st ... 31st
DDDay of month with 2 digits01 ... 31
dWeekday number0 ... 6
doWeekday number as an ordinal0th ... 6th
ddWeekday name with 2 lettersMo ... Su
dddWeekday name with 3 lettersMon ... Sun
ddddFull weekday nameFriday
w or WCalendar week1 ... 53
QQuarter1 ... 4
lShort numeric date6/15/2021
LNumeric date with leading zeros06/15/2021
hHour in 12-hour format with 1 or 2 digits1 ... 12
hhHour in 12-hour format with 2 digits01 ... 12
HHour in 24-hour format with 1 or 2 digits0 ... 23
HHHour in 24-hour format with 2 digits00 ... 23
aam or pm11:30 pm
mMinute with 1 or 2 digits0 ... 59
mmMinute with 2 digits00 ... 59
sSecond with 1 or 2 digits0 ... 59
ssSecond with 2 digits00 ... 59
xUnix time in milliseconds1617873118285
XUnix time in seconds1617873118
ZTime zone offset from UTC-04:00:00
Tips: * Combine format codes to build your own output pattern. * Use `HH:mm` for 24-hour time. * Use `hh:mm a` for 12-hour time. * Use `YYYY-MM-DD` when you need a stable, sortable date format. * Test formatted output with real values before you use it in exports or integrations. ## Measure time spans and offsets Use `duration()` to measure time spans. Use `timeinterval()` to create an offset you can add to a date or time. ### Measure elapsed time with `duration()` Use `duration()` to calculate a time span from an appointment or between two date and time values. Use it when you want to: * Track task runtime. * Get the length of an appointment from its start and end. `duration(appointment)`\ `duration(end, start)` * `appointment`: the appointment for which Ninox returns the duration * `end`: the later value * `start`: the earlier value If the result is longer than 24 hours, Ninox also shows days. #### Let’s take a look at some examples: ```ninox duration(end, start) ``` Returns the time span between two `datetime` fields "End" and "Start". ```ninox duration(holiday) ``` Returns the duration of the `appointment` field "Holiday". ```ninox duration(now(), created_at) ``` Returns the elapsed time since the record was created. ```ninox duration(appointment(date(2026, 3, 27), date(2026, 3, 29))) ``` Returns a duration of two days. ### Count days between two dates with `days()` Use `days()` to return the number of calendar days between two date values. Use it when you want to: * Check how many days remain until a deadline. * Measure a date range in full calendar days. `days(date, date)` * first `date`: the start date * second `date`: the end date You can use all value types that contain a date. #### Let’s take a look at some examples: ```ninox days(start, end) ``` Returns the number of days between the two given dates. ```ninox days(date1, date2) ``` If `date1` is `07/02/2026` and `date2` is `12/31/2026`, the result is `183`. Tips: * Use `days()` when you need plain calendar days. * Use `workdays()` when weekends should not count. * Use `duration()` when you need a time span, not only a day count. ### Count business days with `workdays()` Use `workdays()` to count working days between two dates. Use it when you want to: * Plan schedules. * Track delivery windows. `workdays(date, date)` * first `date`: the start date * second `date`: the end date `workdays()` counts Monday to Friday as working days. Public holidays are not considered. If you start from an appointment, pass `start(appointment)` and `endof(appointment)`. #### Let’s take a look at some examples: ```ninox workdays(today() - 13, today() + 6) ``` Returns `14`. ```ninox workdays(start(appointment), endof(appointment)) ``` Counts business days across the appointment range. ### Create time intervals with `timeinterval()` Use `timeinterval()` to build a reusable duration or convert a time-related value to a duration. Use it when you want to: * Convert milliseconds to a duration. * Turn a time value into a duration. \ `timeinterval(number)` * `number`: a time value or a number If the input is a number, Ninox treats it as a duration in milliseconds. Unlike `duration()`, `timeinterval()` describes a duration by itself. It does not measure the span between two date values. #### Let’s take a look at some examples: ```ninox timeinterval(60000) ``` Converts 60000 milliseconds to a duration of one minute. ```ninox timeinterval(time(1, 30)) ``` Converts the time value `01:30` into a duration of 1 hour and 30 minutes. ```ninox now() + timeinterval(7200000) ``` Builds a datetime two hours from now. Tips: * Use `duration()` for measured spans. * Use `timeinterval()` for planned durations. ## Extract date parts Use these functions to break a date into smaller parts. They are useful for grouping, filtering, and reporting. ### Get year, month, and day with `year()`, `month()`, and `day()` Use these functions when you need one part of a date or timestamp. `year(date)`\ `year(appointment)`\ `year(timestamp)`\ `month(date)`\ `month(appointment)`\ `month(timestamp)`\ `day(appointment)`\ `day(date)`\ `day(timestamp)` * `date`: the date from which Ninox returns the requested part * `appointment`: an appointment value from which Ninox returns the year, month, or day from the start date * `timestamp`: a timestamp from which Ninox returns the requested date part #### Let’s take a look at some examples: ```ninox year(today()) ``` Returns the current year. ```ninox year(endof(appointment)) ``` Returns the year from the end of the `appointment` field. ```ninox month(today()) ``` Returns the current month number. ```ninox month(today()) + 3 ``` Adds three to the current month number. ```ninox month(appointment) ``` Returns the month number from the start date of the `appointment` field. ```ninox month(now()) ``` Returns the month number from the current timestamp. ```ninox day(date) ``` Returns the day of the month from the field "Date". ```ninox day(1624226400000) ``` Returns the day from a Unix timestamp. Tip: * If you use an appointment and need the end date, wrap it with `endof()`. ### Get weekday, week, and quarter with `weekday()`, `week()`, and `quarter()` Use these functions when calendar periods matter. `weekday(date)`\ `weekday(timestamp)`\ `weekday(appointment)`\ `week(date)`\ `week(timestamp)`\ `week(appointment)`\ `quarter(date)` * `date`: the date from which Ninox returns the requested calendar value * `timestamp`: a timestamp from which Ninox returns the weekday or calendar week * `appointment`: an appointment from which Ninox returns the weekday or calendar week of the start date `weekday()` returns a number from `0` to `6`, where Monday = `0` and Sunday = `6`. `weekday()` does not consider public holidays. `quarter()` returns a number from `1` to `4`. If you use an appointment, first choose whether you need the start or end date. #### Let’s take a look at some examples: ```ninox weekday(today()) ``` Returns the weekday number for today. ```ninox weekday(date(2026, 4, 22)) ``` Returns `2` because 22 April 2026 is a Wednesday. ```ninox if weekday(date) > 4 then "Weekend" else "Business day" end ``` Checks whether a date falls on a weekend or a workday. ```ninox week(today()) ``` Returns the current week number. ```ninox week(now()) ``` Returns the calendar week from the current timestamp. ```ninox week(appointment) ``` Returns the calendar week from the start date of the `appointment` field. ```ninox quarter(today()) ``` Returns the current quarter number. ```ninox quarter(date) ``` Returns the quarter number from the `date` field. ```ninox quarter(start(appointment)) ``` Returns the quarter number from the start of the `appointment` field. ```ninox quarter(endof(appointment)) ``` Returns the quarter number from the end of the `appointment` field. ### Jump to a period end with `endof()` Use `endof()` to return the end of an appointment or the end of a calendar period. Use it when you want to: * Get the end timestamp of an appointment. * Trigger reminders near a deadline. `endof(appointment)` * `appointment`: the appointment field or result from which Ninox returns the end timestamp #### Let’s take a look at some examples: ```ninox endof(appointment) ``` Returns the end timestamp of the `appointment` field. ```ninox format(endof(holiday), "dddd, HH:mm") ``` Formats the end of the "Holiday" appointment field as readable text. ## Build reporting keys and business calculations Use these functions when you want compact grouping keys or business-friendly date calculations. ### Build reporting keys with `yearmonth()`, `yearweek()`, and `yearquarter()` Use these functions to group records by a period in one value. Use them when you want to: * Group invoices by month. * Build weekly charts. * Summarize results by quarter. `yearmonth(appointment)`\ `yearmonth(date)`\ `yearmonth(timestamp)`\ `yearweek(appointment)`\ `yearweek(date)`\ `yearweek(timestamp)`\ `yearquarter(appointment)`\ `yearquarter(date)`\ `yearquarter(datetime)`\ `yearquarter(timestamp)` * `appointment`: an appointment from which Ninox builds the reporting key from the start date * `date`: the date from which Ninox builds the reporting key * `timestamp`: a timestamp from which Ninox builds the reporting key `yearmonth()` returns a string in the format `YYYY/MM`. `yearweek()` returns a string in the format `YYYY WW`. `yearquarter()` returns a string in the format `YYYY Qn`. If you use an appointment and need the end date, wrap it with `endof()`. #### Let’s take a look at some examples: ```ninox yearmonth(today()) ``` Returns a combined year-month key for the current date. ```ninox yearmonth(appointment) ``` Returns a value such as `2021/06` from the start date of the "Appointment" field. ```ninox yearmonth(endof(appointment)) ``` Returns the year and month from the end of the "Appointment" field. ```ninox yearweek(today()) ``` Returns a combined year-week key for the current date. ```ninox yearweek(appointment) ``` Returns a value such as `2021 23` from the start date of the `appointment` field. ```ninox yearweek(endof(appointment)) ``` Returns the year and week from the end of the `appointment` field. ```ninox yearquarter(today()) ``` Returns a combined year-quarter key for the current date. ```ninox yearquarter(appointment) ``` Returns a value such as `2021 Q2` from the start date of the `appointment` field. ```ninox yearquarter(endof(appointment)) ``` Returns the year and quarter from the end of the `appointment` field. ### Calculate age with `age()` Use `age(date)` to return the number of full years between a date and the current date. Use it when you want to: * Show a person’s age. The current date is always used for this calculation. `age(date)` * `date`: the reference date from which Ninox calculates the number of full years #### Let’s take a look at some examples: ```ninox age(date_of_birth) ``` Returns the age in full years from the date in `date_of_birth`. ```ninox age(date(1976, 4, 12)) ``` Returns the number of full years since 12 April 1976, based on today’s date. ## Common date recipes These short patterns cover common date and time tasks in Ninox. ### Flag overdue records ```ninox if today() > due_date then "Overdue" else "On time" end ``` Compares the current date with a due date. ### Measure SLA time since creation ```ninox duration(now(), created_at) ``` Measures the elapsed time since the record was created. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ninox.com/ninox-scripting/automate-your-workflows/work-with-functions/dates-and-time.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.