Skip to content

Commit e593e0f

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #2983 from abinav2307/literal-expression-third-pass-validation
Update $literal documentation with new examples and date
2 parents d30d329 + f6466a3 commit e593e0f

File tree

1 file changed

+149
-86
lines changed
  • articles/cosmos-db/mongodb/vcore/operators/literal-expression

1 file changed

+149
-86
lines changed

‎articles/cosmos-db/mongodb/vcore/operators/literal-expression/$literal.md‎

Lines changed: 149 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
ms.service: azure-cosmos-db
88
ms.subservice: mongodb-vcore
99
ms.topic: language-reference
10-
ms.date: 08/03/2025
10+
ms.date: 09/04/2025
1111
---
1212

1313
# $literal
@@ -28,66 +28,123 @@ The `$literal` operator returns the specified value without parsing it as an exp
2828
| --- | --- |
2929
| **`<value>`** | Any value that should be returned as-is without interpretation. This can be a string, number, boolean, array, object, or null. |
3030

31-
## Example
31+
## Examples
3232

33-
Let's understand the usage with sample json from `stores` dataset.
33+
Consider this sample document from the stores collection.
3434

3535
```json
3636
{
37-
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
38-
"name": "First Up Consultants | Bed and Bath Center - South Amir",
39-
"location": {
40-
"lat": 60.7954,
41-
"lon": -142.0012
42-
},
43-
"staff": {
44-
"totalStaff": {
45-
"fullTime": 18,
46-
"partTime": 17
47-
}
48-
},
49-
"sales": {
50-
"totalSales": 37701,
51-
"salesByCategory": [
52-
{
53-
"categoryName": "Mattress Toppers",
54-
"totalSales": 37701
55-
}
56-
]
57-
},
58-
"promotionEvents": [
59-
{
60-
"eventName": "Price Drop Palooza",
61-
"promotionalDates": {
62-
"startDate": {
63-
"Year": 2024,
64-
"Month": 9,
65-
"Day": 21
66-
},
67-
"endDate": {
68-
"Year": 2024,
69-
"Month": 9,
70-
"Day": 30
37+
"_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
38+
"name": "First Up Consultants | Beverage Shop - Satterfieldmouth",
39+
"location": {
40+
"lat": -89.2384,
41+
"lon": -46.4012
42+
},
43+
"staff": {
44+
"totalStaff": {
45+
"fullTime": 8,
46+
"partTime": 20
7147
}
72-
},
73-
"discounts": [
48+
},
49+
"sales": {
50+
"totalSales": 75670,
51+
"salesByCategory": [
52+
{
53+
"categoryName": "Wine Accessories",
54+
"totalSales": 34440
55+
},
56+
{
57+
"categoryName": "Bitters",
58+
"totalSales": 39496
59+
},
60+
{
61+
"categoryName": "Rum",
62+
"totalSales": 1734
63+
}
64+
]
65+
},
66+
"promotionEvents": [
7467
{
75-
"categoryName": "Bath Accessories",
76-
"discountPercentage": 18
68+
"eventName": "Unbeatable Bargain Bash",
69+
"promotionalDates": {
70+
"startDate": {
71+
"Year": 2024,
72+
"Month": 6,
73+
"Day": 23
74+
},
75+
"endDate": {
76+
"Year": 2024,
77+
"Month": 7,
78+
"Day": 2
79+
}
80+
},
81+
"discounts": [
82+
{
83+
"categoryName": "Whiskey",
84+
"discountPercentage": 7
85+
},
86+
{
87+
"categoryName": "Bitters",
88+
"discountPercentage": 15
89+
},
90+
{
91+
"categoryName": "Brandy",
92+
"discountPercentage": 8
93+
},
94+
{
95+
"categoryName": "Sports Drinks",
96+
"discountPercentage": 22
97+
},
98+
{
99+
"categoryName": "Vodka",
100+
"discountPercentage": 19
101+
}
102+
]
77103
},
78104
{
79-
"categoryName": "Pillow Top Mattresses",
80-
"discountPercentage": 17
105+
"eventName": "Steal of a Deal Days",
106+
"promotionalDates": {
107+
"startDate": {
108+
"Year": 2024,
109+
"Month": 9,
110+
"Day": 21
111+
},
112+
"endDate": {
113+
"Year": 2024,
114+
"Month": 9,
115+
"Day": 29
116+
}
117+
},
118+
"discounts": [
119+
{
120+
"categoryName": "Organic Wine",
121+
"discountPercentage": 19
122+
},
123+
{
124+
"categoryName": "White Wine",
125+
"discountPercentage": 20
126+
},
127+
{
128+
"categoryName": "Sparkling Wine",
129+
"discountPercentage": 19
130+
},
131+
{
132+
"categoryName": "Whiskey",
133+
"discountPercentage": 17
134+
},
135+
{
136+
"categoryName": "Vodka",
137+
"discountPercentage": 23
138+
}
139+
]
81140
}
82-
]
83-
}
84-
]
141+
]
85142
}
86143
```
87144

88145
### Example 1: Adding literal status fields
89146

90-
The example demonstrates adding literal status information to store documents, including literal strings that might otherwise be interpreted as field names or operators.
147+
This query demonstrates adding literal status information to store documents, including literal strings that might otherwise be interpreted as field names or operators.
91148

92149
```javascript
93150
db.stores.aggregate([
@@ -110,26 +167,28 @@ db.stores.aggregate([
110167
])
111168
```
112169

113-
The query adds literal values to each store document. Note how `$pending` is treated as a literal string rather than a field reference.
170+
This query returns the following result.
114171

115172
```json
116-
{
117-
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
118-
"name": "First Up Consultants | Bed and Bath Center - South Amir",
119-
"totalSales": 37701,
120-
"status": "Active",
121-
"reviewStatus": "$pending",
122-
"priority": 1,
123-
"metadata": {
124-
"lastUpdated": "2024-06-13",
125-
"source": "automated-system"
173+
[
174+
{
175+
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
176+
"name": "First Up Consultants | Bed and Bath Center - South Amir",
177+
"totalSales": 37701,
178+
"status": "Active",
179+
"reviewStatus": "$pending",
180+
"priority": 1,
181+
"metadata": {
182+
"lastUpdated": "2024-06-13",
183+
"source": "automated-system"
184+
}
126185
}
127-
}
186+
]
128187
```
129188

130189
### Example 2: Creating literal arrays and conditional values
131190

132-
This example shows how to use `$literal` with arrays and in conditional expressions to ensure values are not interpreted as operators.
191+
This query shows how to use `$literal` with arrays and in conditional expressions to ensure values are not interpreted as operators.
133192

134193
```javascript
135194
db.stores.aggregate([
@@ -157,25 +216,27 @@ db.stores.aggregate([
157216
])
158217
```
159218

160-
The query creates literal arrays and objects that contain strings starting with `$`, which would normally be interpreted as operators or field references.
219+
This query returns the following result.
161220

162221
```json
163-
{
164-
"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
165-
"name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury",
166-
"totalSales": 160000,
167-
"performanceCategory": "High Performer",
168-
"tags": ["$featured", "$promoted", "$new"],
169-
"searchKeywords": {
170-
"$or": ["electronics", "entertainment"],
171-
"$and": ["home", "theater"]
222+
[
223+
{
224+
"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
225+
"name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury",
226+
"totalSales": 160000,
227+
"performanceCategory": "High Performer",
228+
"tags": ["$featured", "$promoted", "$new"],
229+
"searchKeywords": {
230+
"$or": ["electronics", "entertainment"],
231+
"$and": ["home", "theater"]
232+
}
172233
}
173-
}
234+
]
174235
```
175236

176237
### Example 3: Literal null and boolean values
177238

178-
This example demonstrates using `$literal` with null values and booleans, especially useful when these values need to be explicitly set rather than computed.
239+
This query demonstrates using `$literal` with null values and booleans, especially useful when these values need to be explicitly set rather than computed.
179240

180241
```javascript
181242
db.stores.aggregate([
@@ -200,23 +261,25 @@ db.stores.aggregate([
200261
])
201262
```
202263

203-
The query adds explicit literal values including null, booleans, and strings that look like MongoDB expressions.
264+
This query returns the following result.
204265

205266
```json
206-
{
207-
"_id": "e6895a31-a5cd-4103-8889-3b95a864e5a6",
208-
"name": "VanArsdel, Ltd. | Picture Frame Store - Port Clevelandton",
209-
"totalSales": 17676,
210-
"specialOffer": null,
211-
"isOnline": false,
212-
"hasInventory": true,
213-
"calculationFormula": "$multiply: [price, quantity]",
214-
"ratingSystem": {
215-
"min": 0,
216-
"max": 5,
217-
"default": null
267+
[
268+
{
269+
"_id": "e6895a31-a5cd-4103-8889-3b95a864e5a6",
270+
"name": "VanArsdel, Ltd. | Picture Frame Store - Port Clevelandton",
271+
"totalSales": 17676,
272+
"specialOffer": null,
273+
"isOnline": false,
274+
"hasInventory": true,
275+
"calculationFormula": "$multiply: [price, quantity]",
276+
"ratingSystem": {
277+
"min": 0,
278+
"max": 5,
279+
"default": null
280+
}
218281
}
219-
}
282+
]
220283
```
221284

222285
## Related content

0 commit comments

Comments
 (0)