Skip to content

Commit 958a50e

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #199721 from jcocchi/add-query-datetimebin
add doc for datetimebin query system function
2 parents a12e433 + fd7138b commit 958a50e

File tree

3 files changed

+125
-0
lines changed

3 files changed

+125
-0
lines changed

‎articles/cosmos-db/TOC.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,9 @@
390390
- name: DateTimeAdd
391391
displayName: DateTimeAdd, date time add, timestamp, date and time functions, datetime
392392
href: sql/sql-query-datetimeadd.md
393+
- name: DateTimeBin
394+
displayName: DateTimeBin, date time bin, date and time functions, datetime
395+
href: sql/sql-query-datetimebin.md
393396
- name: DateTimeDiff
394397
displayName: DateTimeDiff, date time diff, date and time functions, datetime
395398
href: sql/sql-query-datetimediff.md

‎articles/cosmos-db/sql/sql-query-date-time-functions.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ or numeric ticks whose value is the number of 100 nanosecond ticks which have el
2929
The following functions allow you to easily manipulate DateTime, timestamp, and tick values:
3030

3131
* [DateTimeAdd](sql-query-datetimeadd.md)
32+
* [DateTimeBin](sql-query-datetimebin.md)
3233
* [DateTimeDiff](sql-query-datetimediff.md)
3334
* [DateTimeFromParts](sql-query-datetimefromparts.md)
3435
* [DateTimePart](sql-query-datetimepart.md)

‎articles/cosmos-db/sql/sql-query-datetimebin.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: DateTimeBin in Azure Cosmos DB query language
3+
description: Learn about SQL system function DateTimeBin in Azure Cosmos DB.
4+
author: jcocchi
5+
ms.service: cosmos-db
6+
ms.subservice: cosmosdb-sql
7+
ms.topic: conceptual
8+
ms.date: 05/27/2022
9+
ms.author: jucocchi
10+
ms.custom: query-reference
11+
---
12+
13+
# DateTimeBin (Azure Cosmos DB)
14+
[!INCLUDE[appliesto-sql-api](../includes/appliesto-sql-api.md)]
15+
16+
Returns the nearest multiple of *BinSize* below the specified DateTime given the unit of measurement *DateTimePart* and start value of *BinAtDateTime*.
17+
18+
19+
## Syntax
20+
21+
```sql
22+
DateTimeBin (<DateTime> , <DateTimePart> [,BinSize] [,BinAtDateTime])
23+
```
24+
25+
26+
## Arguments
27+
28+
*DateTime*
29+
The string value date and time to be binned. A UTC date and time ISO 8601 string value in the format `YYYY-MM-DDThh:mm:ss.fffffffZ` where:
30+
31+
|Format|Description|
32+
|-|-|
33+
|YYYY|four-digit year|
34+
|MM|two-digit month (01 = January, etc.)|
35+
|DD|two-digit day of month (01 through 31)|
36+
|T|signifier for beginning of time elements|
37+
|hh|two-digit hour (00 through 23)|
38+
|mm|two-digit minutes (00 through 59)|
39+
|ss|two-digit seconds (00 through 59)|
40+
|.fffffff|seven-digit fractional seconds|
41+
|Z|UTC (Coordinated Universal Time) designator|
42+
43+
For more information on the ISO 8601 format, see [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)
44+
45+
*DateTimePart*
46+
The date time part specifies the units for BinSize. DateTimeBin is Undefined for DayOfWeek, Year, and Month. The finest granularity for binning by Nanosecond is 100 nanosecond ticks; if Nanosecond is specified with a BinSize less than 100, the result is Undefined. This table lists all valid DateTimePart arguments for DateTimeBin:
47+
48+
| DateTimePart | abbreviations |
49+
| ------------ | -------------------- |
50+
| Day | "day", "dd", "d" |
51+
| Hour | "hour", "hh" |
52+
| Minute | "minute", "mi", "n" |
53+
| Second | "second", "ss", "s" |
54+
| Millisecond | "millisecond", "ms" |
55+
| Microsecond | "microsecond", "mcs" |
56+
| Nanosecond | "nanosecond", "ns" |
57+
58+
*BinSize* (optional)
59+
Numeric value that specifies the size of bins. If not specified, the default value is one.
60+
61+
62+
*BinAtDateTime* (optional)
63+
A UTC date and time ISO 8601 string value in the format `YYYY-MM-DDThh:mm:ss.fffffffZ` that specifies the start date to bin from. Default value is the Unix epoch, ‘1970-01-01T00:00:00.000000Z’.
64+
65+
66+
## Return types
67+
68+
Returns the result of binning the *DateTime* value.
69+
70+
71+
## Remarks
72+
73+
DateTimeBin will return `Undefined` for the following reasons:
74+
- The DateTimePart value specified is invalid
75+
- The BinSize value is zero or negative
76+
- The DateTime or BinAtDateTime isn't a valid ISO 8601 DateTime or precedes the year 1601 (the Windows epoch)
77+
78+
79+
## Examples
80+
81+
The following example bins ‘2021-06-28T17:24:29.2991234Z’ by one hour:
82+
83+
```sql
84+
SELECT DateTimeBin('2021-06-28T17:24:29.2991234Z', 'hh') AS BinByHour
85+
```
86+
87+
```json
88+
[
89+
    {
90+
        "BinByHour": "2021-06-28T17:00:00.0000000Z"
91+
    }
92+
]
93+
```
94+
95+
The following example bins ‘2021-06-28T17:24:29.2991234Z’ given different *BinAtDateTime* values:
96+
97+
```sql
98+
SELECT 
99+
DateTimeBin('2021-06-28T17:24:29.2991234Z', 'day', 5) AS One_BinByFiveDaysUnixEpochImplicit,
100+
DateTimeBin('2021-06-28T17:24:29.2991234Z', 'day', 5, '1970-01-01T00:00:00.0000000Z') AS Two_BinByFiveDaysUnixEpochExplicit,
101+
DateTimeBin('2021-06-28T17:24:29.2991234Z', 'day', 5, '1601-01-01T00:00:00.0000000Z') AS Three_BinByFiveDaysFromWindowsEpoch,
102+
DateTimeBin('2021-06-28T17:24:29.2991234Z', 'day', 5, '2021-01-01T00:00:00.0000000Z') AS Four_BinByFiveDaysFromYearStart,
103+
DateTimeBin('2021-06-28T17:24:29.2991234Z', 'day', 5, '0001-01-01T00:00:00.0000000Z') AS Five_BinByFiveDaysFromUndefinedYear
104+
```
105+
106+
```json
107+
[
108+
    {
109+
        "One_BinByFiveDaysUnixEpochImplicit": "2021-06-27T00:00:00.0000000Z",
110+
        "Two_BinByFiveDaysUnixEpochExplicit": "2021-06-27T00:00:00.0000000Z",
111+
        "Three_BinByFiveDaysFromWindowsEpoch": "2021-06-28T00:00:00.0000000Z",
112+
        "Four_BinByFiveDaysFromYearStart": "2021-06-25T00:00:00.0000000Z"
113+
    }
114+
]
115+
```
116+
117+
## Next steps
118+
119+
- [Date and time functions Azure Cosmos DB](sql-query-date-time-functions.md)
120+
- [System functions Azure Cosmos DB](sql-query-system-functions.md)
121+
- [Introduction to Azure Cosmos DB](../introduction.md)

0 commit comments

Comments
 (0)