Skip to content

Commit 06a1ae3

Browse files
author
Jill Grant
authored
Merge pull request #245450 from seesharprun/cosmos-populate-nosql
Cosmos DB | Add NoSQL query functions #3
2 parents 632d9a4 + d043a78 commit 06a1ae3

File tree

10 files changed

+350
-627
lines changed

10 files changed

+350
-627
lines changed

‎articles/cosmos-db/nosql/query/cot.md‎

Lines changed: 7 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ ms.reviewer: sidandrews
88
ms.service: cosmos-db
99
ms.subservice: nosql
1010
ms.topic: reference
11-
ms.date: 07/01/2023
11+
ms.date: 07/19/2023
1212
ms.custom: query-reference
1313
---
1414

@@ -35,26 +35,16 @@ COT(<numeric_expr>)
3535
Returns a numeric expression.
3636

3737
## Examples
38-
38+
3939
The following example calculates the cotangent of the specified angle using the function.
40-
41-
```sql
42-
SELECT VALUE {
43-
cotangent: COT(124.1332)
44-
}
45-
```
46-
47-
```json
48-
[
49-
{
50-
"cotangent": -0.040311998371148884
51-
}
52-
]
53-
```
40+
41+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/cot/query.sql" highlight="2":::
42+
43+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/cot/result.json":::
5444

5545
## Remarks
5646

57-
- This system function doesn't utilize the index.
47+
- This function doesn't use the index.
5848

5949
## Next steps
6050

‎articles/cosmos-db/nosql/query/datetimeadd.md‎

Lines changed: 44 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,72 @@
11
---
2-
title: DateTimeAdd in Azure Cosmos DB query language
3-
description: Learn about SQL system function DateTimeAdd in Azure Cosmos DB.
4-
author: seesharprun
2+
title: DateTimeAdd
3+
titleSuffix: Azure Cosmos DB for NoSQL
4+
description: An Azure Cosmos DB for NoSQL system function that returns a datetime that's the resulting of adding a number to a part of the specified datetime.
5+
author: jcodella
6+
ms.author: jacodel
7+
ms.reviewer: sidandrews
58
ms.service: cosmos-db
69
ms.subservice: nosql
7-
ms.topic: conceptual
8-
ms.date: 07/09/2020
9-
ms.author: sidandrews
10-
ms.reviewer: jucocchi
11-
ms.custom: query-reference, ignite-2022
10+
ms.topic: reference
11+
ms.date: 07/19/2023
12+
ms.custom: query-reference
1213
---
13-
# DateTimeAdd (Azure Cosmos DB)
14+
15+
# DateTimeAdd (NoSQL query)
16+
1417
[!INCLUDE[NoSQL](../../includes/appliesto-nosql.md)]
1518

16-
Returns DateTime string value resulting from adding a specified number value (as a signed integer) to a specified DateTime string
19+
Returns a date and time string value that is the result of adding a specified number value to the provided date and time string.
1720

1821
## Syntax
1922

2023
```sql
21-
DateTimeAdd (<DateTimePart> , <numeric_expr> ,<DateTime>)
24+
DateTimeAdd(<date_time_part>, <numeric_expr> ,<date_time>)
2225
```
2326

2427
## Arguments
25-
26-
*DateTimePart*
27-
The part of date to which DateTimeAdd adds an integer number. This table lists all valid DateTimePart arguments:
28-
29-
| DateTimePart | abbreviations |
30-
| ------------ | -------------------- |
31-
| Year | "year", "yyyy", "yy" |
32-
| Month | "month", "mm", "m" |
33-
| Day | "day", "dd", "d" |
34-
| Hour | "hour", "hh" |
35-
| Minute | "minute", "mi", "n" |
36-
| Second | "second", "ss", "s" |
37-
| Millisecond | "millisecond", "ms" |
38-
| Microsecond | "microsecond", "mcs" |
39-
| Nanosecond | "nanosecond", "ns" |
40-
41-
*numeric_expr*
42-
Is a signed integer value that will be added to the DateTimePart of the specified DateTime
43-
44-
*DateTime*
45-
UTC date and time ISO 8601 string value in the format `YYYY-MM-DDThh:mm:ss.fffffffZ` where:
46-
47-
|Format|Description|
48-
|-|-|
49-
|YYYY|four-digit year|
50-
|MM|two-digit month (01 = January, etc.)|
51-
|DD|two-digit day of month (01 through 31)|
52-
|T|signifier for beginning of time elements|
53-
|hh|two-digit hour (00 through 23)|
54-
|mm|two-digit minutes (00 through 59)|
55-
|ss|two-digit seconds (00 through 59)|
56-
|.fffffff|seven-digit fractional seconds|
57-
|Z|UTC (Coordinated Universal Time) designator|
58-
59-
For more information on the ISO 8601 format, see [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)
60-
61-
## Return types
6228

63-
Returns a UTC date and time ISO 8601 string value in the format `YYYY-MM-DDThh:mm:ss.fffffffZ` where:
64-
65-
|Format|Description|
66-
|-|-|
67-
|YYYY|four-digit year|
68-
|MM|two-digit month (01 = January, etc.)|
69-
|DD|two-digit day of month (01 through 31)|
70-
|T|signifier for beginning of time elements|
71-
|hh|two-digit hour (00 through 23)|
72-
|mm|two-digit minutes (00 through 59)|
73-
|ss|two-digit seconds (00 through 59)|
74-
|.fffffff|seven-digit fractional seconds|
75-
|Z|UTC (Coordinated Universal Time) designator|
29+
| | Description |
30+
| --- | --- |
31+
| **`date_time_part`** | A string representing a part of an ISO 8601 date format specification. This part is used to indicate which aspect of the date to modify by the related numeric expression. |
32+
| **`numeric_expr`** | A numeric expression resulting in a signed integer. |
33+
| **`date_time`** | A Coordinated Universal Time (UTC) date and time string in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.fffffffZ`. |
7634

77-
## Remarks
35+
> [!NOTE]
36+
> For more information on the ISO 8601 format, see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
7837
79-
DateTimeAdd will return `undefined` for the following reasons:
38+
## Return types
8039

81-
- The DateTimePart value specified is invalid
82-
- The numeric_expr specified is not a valid integer
83-
- The DateTime in the argument or result is not a valid ISO 8601 DateTime.
40+
Returns a UTC date and time string in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.fffffffZ`.
8441

8542
## Examples
86-
87-
The following example adds 1 month to the DateTime: `2020-07-09T23:20:13.4575530Z`
8843

89-
```sql
90-
SELECT DateTimeAdd("mm", 1, "2020-07-09T23:20:13.4575530Z") AS OneMonthLater
91-
```
44+
The following example adds various values (one year, one month, one day, one hour) to the date **July 3, 2020** at **midnight (00:00 UTC)**. The example also subtracts various values (two years, two months, two days, two hours) from the same date. Finally, this example uses an expression to modify the seconds of the same date.
9245

93-
```json
94-
[
95-
{
96-
"OneMonthLater": "2020-08-09T23:20:13.4575530Z"
97-
}
98-
]
99-
```
46+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/datetimeadd/query.sql" highlight="2-10":::
10047

101-
The following example subtracts 2 hours from the DateTime: `2020-07-09T23:20:13.4575530Z`
48+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/datetimeadd/result.json":::
10249

103-
```sql
104-
SELECT DateTimeAdd("hh", -2, "2020-07-09T23:20:13.4575530Z") AS TwoHoursEarlier
105-
```
50+
## Remarks
10651

107-
```json
108-
[
109-
{
110-
"TwoHoursEarlier": "2020-07-09T21:20:13.4575530Z"
111-
}
112-
]
113-
```
52+
- This function returns `undefined` for these reasons:
53+
- The specified date and time part is invalid.
54+
- The numeric expression isn't a valid integer.
55+
- The date and time in the argument isn't a valid ISO 8601 date and time string.
56+
- The ISO 8601 date format specifies valid date and time parts to use with this function:
57+
| | Format |
58+
| --- | --- |
59+
| **Year** | `year`, `yyyy`, `yy` |
60+
| **Month** | `month`, `mm`, `m` |
61+
| **Day** | `day`, `dd`, `d` |
62+
| **Hour** | `hour`, `hh` |
63+
| **Minute** | `minute`, `mi`, `n` |
64+
| **Second** | `second`, `ss`, `s` |
65+
| **Millisecond** | `millisecond`, `ms` |
66+
| **Microsecond** | `microsecond`, `mcs` |
67+
| **Nanosecond** | `nanosecond`, `ns` |
11468

11569
## Next steps
11670

11771
- [System functions Azure Cosmos DB](system-functions.yml)
118-
- [Introduction to Azure Cosmos DB](../../introduction.md)
72+
- [`DateTimeBin`](datetimebin.md)

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

Lines changed: 53 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,72 @@
11
---
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: nosql
7-
ms.topic: conceptual
8-
ms.date: 05/27/2022
9-
ms.author: jucocchi
10-
ms.custom: query-reference, ignite-2022
11-
---
12-
13-
# DateTimeBin (Azure Cosmos DB)
14-
[!INCLUDE[NoSQL](../../includes/appliesto-nosql.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.
2+
title: DateTimeBin
3+
titleSuffix: Azure Cosmos DB for NoSQL
4+
description: An Azure Cosmos DB for NoSQL system function that returns a date and time that's the resulting of binning (rounding) a part of the specified datetime.
5+
author: jcodella
6+
ms.author: jacodel
7+
ms.reviewer: sidandrews
8+
ms.service: cosmos-db
9+
ms.subservice: nosql
10+
ms.topic: reference
11+
ms.date: 07/19/2023
12+
ms.custom: query-reference
13+
---
6014

15+
# DateTimeBin (NoSQL query)
6116

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’.
17+
[!INCLUDE[NoSQL](../../includes/appliesto-nosql.md)]
6418

19+
Returns a date and time string value that is the result of binning (or rounding) a part of the provided date and time string.
6520

66-
## Return types
21+
## Syntax
6722

68-
Returns the result of binning the *DateTime* value.
23+
```sql
24+
DateTimeBin(<date_time> , <date_time_part> [, <bin_size>] [, <bin_start_date_time>])
25+
```
6926

27+
## Arguments
7028

71-
## Remarks
29+
| | Description |
30+
| --- | --- |
31+
| **`date_time`** | A Coordinated Universal Time (UTC) date and time string in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.fffffffZ`. |
32+
| **`date_time_part`** | A string representing a part of an ISO 8601 date format specification. This part is used to indicate which aspect of the date to bin. Specifically, this part argument represents the level of granularity for binning (or rounding). The minimum granularity for the part is **days** and the maximum granularity is **nanoseconds**. |
33+
| **`bin_size` *(Optional)*** | An optional numeric value specifying the size of the bin. If not specified, the default value is `1`. |
34+
| **`bin_start_date_time` *(Optional)*** | An optional Coordinated Universal Time (UTC) date and time string in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.fffffffZ`. This date and time argument specifies the start date to bin from. If not specified, the default value is the Unix epoch `1970-01-01T00:00:00.000000Z`. |
7235

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)
36+
> [!NOTE]
37+
> For more information on the ISO 8601 format, see [ISO 8601](https://wikipedia.org/wiki/ISO_8601). For more information on the Unix epoch, see [Unix time](https://wikipedia.org/wiki/unix_time).
7738
39+
## Return types
7840

79-
## Examples
41+
Returns a UTC date and time string in the ISO 8601 format `YYYY-MM-DDThh:mm:ss.fffffffZ`.
8042

81-
The following example bins ‘2021-06-28T17:24:29.2991234Z’ by one hour:
43+
## Examples
8244

83-
```sql
84-
SELECT DateTimeBin('2021-06-28T17:24:29.2991234Z', 'hh') AS BinByHour
85-
```
45+
The following example bins the date **January 8, 2021** at **18:35 UTC** by various values. The example also changes the bin size, and the bin start date and time.
8646

87-
```json
88-
[
89-
    {
90-
        "BinByHour": "2021-06-28T17:00:00.0000000Z"
91-
    }
92-
]
93-
```
47+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/datetimebin/query.sql" highlight="2-7":::
9448

95-
The following example bins ‘2021-06-28T17:24:29.2991234Z’ given different *BinAtDateTime* values:
49+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/datetimebin/result.json":::
9650

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-
```
51+
## Remarks
10552

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-
```
53+
- This function returns `undefined` for these reasons:
54+
- The specified date and time part is invalid.
55+
- The bin size value isn't a valid integer, is zero, or is negative.
56+
- The date and time in either argument isn't a valid ISO 8601 date and time string.
57+
- The date and time for the bin start precedes the year `1601`, the Windows epoch.
58+
- The ISO 8601 date format specifies valid date and time parts to use with this function:
59+
| | Format |
60+
| --- | --- |
61+
| **Day** | `day`, `dd`, `d` |
62+
| **Hour** | `hour`, `hh` |
63+
| **Minute** | `minute`, `mi`, `n` |
64+
| **Second** | `second`, `ss`, `s` |
65+
| **Millisecond** | `millisecond`, `ms` |
66+
| **Microsecond** | `microsecond`, `mcs` |
67+
| **Nanosecond** | `nanosecond`, `ns` |
11668

117-
## Next steps
69+
## Next steps
11870

119-
- [System functions Azure Cosmos DB](system-functions.yml)
120-
- [Introduction to Azure Cosmos DB](../../introduction.md)
71+
- [System functions Azure Cosmos DB](system-functions.yml)
72+
- [`DateTimeAdd`](datetimeadd.md)

0 commit comments

Comments
 (0)