> ## Documentation Index
> Fetch the complete documentation index at: https://axiom-mano-sample-app.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Datetime functions

> Learn how to use and combine different timespan functions in APL

## DateTime/ Timespan functions

| **Function Name**                  | **Description**                                                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [ago()](#ago)                      | Subtracts the given timespan from the current UTC clock time.                                                        |
| [datetime\_add()](#datetime-add)   | Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. |
| [datetime\_part()](#datetime-part) | Extracts the requested date part as an integer value.                                                                |
| [datetime\_diff()](#datetime-diff) | Calculates calendarian difference between two datetime values.                                                       |
| [dayofmonth()](#dayofmonth)        | Returns the integer number representing the day number of the given month                                            |
| [dayofweek()](#dayofweek)          | Returns the integer number of days since the preceding Sunday, as a timespan.                                        |
| [dayofyear()](#dayofyear)          | Returns the integer number represents the day number of the given year.                                              |
| [endofyear()](#endofyear)          | Returns the end of the year containing the date                                                                      |
| [getmonth()](#getmonth)            | Get the month number (1-12) from a datetime.                                                                         |
| [getyear()](#getyear)              | Returns the year part of the `datetime` argument.                                                                    |
| [hourofday()](#hourofday)          | Returns the integer number representing the hour number of the given date                                            |
| [endofday()](#endofday)            | Returns the end of the day containing the date                                                                       |
| [now()](#now)                      | Returns the current UTC clock time, optionally offset by a given timespan.                                           |
| [endofmonth()](#endofmonth)        | Returns the end of the month containing the date                                                                     |
| [endofweek()](#endofweek)          | Returns the end of the week containing the date.                                                                     |
| [monthofyear()](#monthofyear)      | Returns the integer number represents the month number of the given year.                                            |
| [startofday()](#startofday)        | Returns the start of the day containing the date                                                                     |
| [startofmonth()](#startofmonth)    | Returns the start of the month containing the date                                                                   |
| [startofweek()](#startofweek)      | Returns the start of the week containing the date                                                                    |
| [startofyear()](#startofyear)      | Returns the start of the year containing the date                                                                    |

* We support the ISO 8601 format, which is the standard format for representing dates and times in the Gregorian calendar. [Check them out here](/apl/data-types/scalar-data-types#supported-formats)

## ago()

Subtracts the given timespan from the current UTC clock time.

### Arguments

* Interval to subtract from the current UTC clock time

### Returns

now() - a\_timespan

### Example

```kusto
ago(6h)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%286h%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "date_time_functions": "2023-09-11T20:12:39Z"
}
```

```kusto
ago(3d)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20date_time_functions%20%3D%20ago%283d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "date_time_functions": "2023-09-09T02:13:29Z"
}
```

## datetime\_add()

Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime.

### Arguments

* period: string.
* amount: integer.
* datetime: datetime value.

### Returns

A date after a certain time/date interval has been added.

### Example

```kusto
datetime_add(period,amount,datetime)
```

```kusto
['sample-http-logs']
| project new_datetime = datetime_add( "month", 1, datetime(2016-10-06))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_add%28%20%5C%22month%5C%22%2C%201%2C%20datetime%282016-10-06%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "new_datetime": "2016-11-06T00:00:00Z"
}
```

## datetime\_part()

Extracts the requested date part as an integer value.

### Arguments

* date: datetime
* part: string

### Returns

An integer representing the extracted part.

### Examples

```kusto
datetime_part(part,datetime)
```

```kusto
['sample-http-logs']
| project new_datetime = datetime_part("Day", datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_part%28%5C%22Day%5C%22%2C%20datetime%282016-06-26T08%3A20%3A03.123456Z%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "new_datetime": 26
}
```

## datetime\_diff()

Calculates calendarian difference between two datetime values.

### Arguments

* period: string.
* datetime\_1: datetime value.
* datetime\_2: datetime value.

### Returns

An integer, which represents amount of periods in the result of subtraction (datetime\_1 - datetime\_2).

### Example

```kusto
datetime_diff(period,datetime_1,datetime_2)
```

```kusto
['sample-http-logs']
| project new_datetime = datetime_diff("week", datetime(2019-06-26T08:20:03.123456Z), datetime(2014-06-26T08:19:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222019-06-26T08%3A20%3A03.123456Z%5C%22%29%2C%20datetime%28%5C%222014-06-26T08%3A19%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "new_datetime": 260
}
```

```kusto
['sample-http-logs']
| project new_datetime = datetime_diff("week", datetime(2015-11-08), datetime(2014-11-08))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20new_datetime%20%3D%20datetime_diff%28%5C%22week%5C%22%2C%20datetime%28%5C%222014-11-08%5C%22%29%2C%20datetime%28%5C%222014-11-08%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "new_datetime": 52
}
```

## dayofmonth()

Returns the integer number representing the day number of the given month

### Arguments

* `a_date`: A `datetime`

### Returns

day number of the given month.

### Example

```kusto
dayofmonth(a_date)
```

```kusto
['sample-http-logs']
| project day_of_the_month = dayofmonth(datetime(2017-11-30))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_month%20%3D%20dayofmonth%28datetime%28%5C%222017-11-30%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "day_of_the_month": 30
}
```

## dayofweek()

Returns the integer number of days since the preceding Sunday, as a timespan.

### Arguments

* a\_date: A datetime.

### Returns

The `timespan` since midnight at the beginning of the preceding Sunday, rounded down to an integer number of days.

### Example

```kusto
dayofweek(a_date)
```

```kusto
['sample-http-logs']
| project day_of_the_week = dayofweek(datetime(2019-05-18))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_week%20%3D%20dayofweek%28datetime%28%5C%222019-05-18%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "day_of_the_week": 6
}
```

## dayofyear()

Returns the integer number represents the day number of the given year.

### Arguments

* `a_date`: A `datetime.`

### Returns

`day number` of the given year.

### Example

```kusto
dayofyear(a_date)
```

```kusto
['sample-http-logs']
| project day_of_the_year = dayofyear(datetime(2020-07-20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20day_of_the_year%20%3D%20dayofyear%28datetime%28%5C%222020-07-20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "day_of_the_year": 202
}
```

## endofyear()

Returns the end of the year containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the year for the given date value

### Example

```kusto
endofyear(date)
```

```kusto
['sample-http-logs']
| extend end_of_the_year = endofyear(datetime(2016-06-26T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20%20end_of_the_year%20%3D%20endofyear%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "end_of_the_year": "2016-12-31T23:59:59.999999999Z"
}
```

## getmonth()

Get the month number (1-12) from a datetime.

```kusto
['sample-http-logs']
| extend get_specific_month = getmonth(datetime(2020-07-26T08:20))
```

## getyear()

Returns the year part of the `datetime` argument.

### Example

```kusto
getyear(datetime())
```

```kusto
['sample-http-logs']
| project get_specific_year = getyear(datetime(2020-07-26))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_year%20%3D%20getyear%28datetime%28%5C%222020-07-26%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "get_specific_year": 2020
}
```

## hourofday()

Returns the integer number representing the hour number of the given date

### Arguments

* a\_date: A datetime.

### Returns

hour number of the day (0-23).

### Example

```kusto
hourofday(a_date)
```

```kusto
['sample-http-logs']
| project get_specific_hour = hourofday(datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20get_specific_hour%20%3D%20hourofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "get_specific_hour": 8
}
```

## endofday()

Returns the end of the day containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the day for the given date value.

### Example

```kusto
endofday(date)
```

```kusto
['sample-http-logs']
| project end_of_day_series = endofday(datetime(2016-06-26T08:20:03.123456Z))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_day_series%20%3D%20endofday%28datetime%28%5C%222016-06-26T08%3A20%3A03.123456Z%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "end_of_day_series": "2016-06-26T23:59:59.999999999Z"
}
```

## now()

Returns the current UTC clock time, optionally offset by a given timespan. This function can be used multiple times in a statement and the clock time being referenced will be the same for all instances.

### Arguments

* offset: A timespan, added to the current UTC clock time. Default: 0.

### Returns

The current UTC clock time as a datetime.

### Example

```kusto
now([offset])
```

```kusto
['sample-http-logs']
| project returns_clock_time = now(-5d)
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20returns_clock_time%20%3D%20now%28-5d%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "returns_clock_time": "2023-09-07T02:54:50Z"
}
```

## endofmonth()

Returns the end of the month containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the month for the given date value.

### Example

```kusto
endofmonth(date)
```

```kusto
['sample-http-logs']
| project end_of_the_month = endofmonth(datetime(2016-06-26T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_month%20%3D%20endofmonth%28datetime%28%5C%222016-06-26T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "end_of_the_month": "2016-06-30T23:59:59.999999999Z"
}
```

## endofweek()

Returns the end of the week containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the end of the week for the given date value

### Example

```kusto
endofweek(date)
```

```kusto
['sample-http-logs']
| project end_of_the_week = endofweek(datetime(2019-04-18T08:20))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20end_of_the_week%20%3D%20endofweek%28datetime%28%5C%222019-04-18T08%3A20%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "end_of_the_week": "2019-04-20T23:59:59.999999999Z"
}
```

## monthofyear()

Returns the integer number represents the month number of the given year.

### Arguments

* `date`: A datetime.

### Returns

month number of the given year.

### Example

```kusto
monthofyear(datetime("2018-11-21"))
```

```kusto
['sample-http-logs']
| project month_of_the_year = monthofyear(datetime(2018-11-11))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20month_of_the_year%20%3D%20monthofyear%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "month_of_the_year": 11
}
```

## startofday()

Returns the start of the day containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the day for the given date value

### Examples

```kusto
startofday(datetime(2020-08-31))
```

```kusto
['sample-http-logs']
| project start_of_the_day = startofday(datetime(2018-11-11))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20start_of_the_day%20%3D%20startofday%28datetime%28%5C%222018-11-11%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "start_of_the_day": "2018-11-11T00:00:00Z"
}
```

## startofmonth()

Returns the start of the month containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the month for the given date value

### Example

```kusto
['github-issues-event']
| project start_of_the_month =  startofmonth(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "start_of_the_month": "2020-08-01T00:00:00Z"
}
```

```kusto
['hackernews']
| extend start_of_the_month = startofmonth(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_month%20%3D%20startofmonth%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "start_of_the_month": "2020-08-01T00:00:00Z"
}
```

## startofweek()

Returns the start of the week containing the date

Start of the week is considered to be a Sunday.

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the week for the given date value

### Examples

```kusto
['github-issues-event']
| extend start_of_the_week =  startofweek(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27github-issues-event%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "start_of_the_week": "2020-07-26T00:00:00Z"
}
```

```kusto
['hackernews']
| extend start_of_the_week = startofweek(datetime(2020-08-01))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27hn%27%5D%5Cn%7C%20project%20start_of_the_week%20%3D%20startofweek%28datetime%28%5C%222020-08-01%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "start_of_the_week": "2020-07-26T00:00:00Z"
}
```

```kusto
['sample-http-logs']
| extend start_of_the_week = startofweek(datetime(2018-06-11T00:00:00Z))
```

## startofyear()

Returns the start of the year containing the date

### Arguments

* date: The input date.

### Returns

A datetime representing the start of the year for the given date value

### Examples

```kusto
['sample-http-logs']
| project yearStart = startofyear(datetime(2019-04-03))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-04-03%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "yearStart": "2019-01-01T00:00:00Z"
}
```

```kusto
['sample-http-logs']
| project yearStart = startofyear(datetime(2019-10-09 01:00:00.0000000))
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%5Cn%7C%20project%20yearStart%20%3D%20startofyear%28datetime%28%5C%222019-10-09%2001%3A00%3A00.0000000%5C%22%29%29%22%2C%22queryOptions%22%3A%7B%22quickRange%22%3A%2230d%22%7D%7D)

* Result:

```json
{
  "yearStart": "2019-01-01T00:00:00Z"
}
```