Prepare the docs for the DocumentDB 1.0 release

api-reference/commands/aggregation/aggregate.md

@@ -18,6 +18,8 @@ db.collection.aggregate(pipeline, options)
 - **pipeline**: An array of aggregation stages that process and transform the data.
 - **options**: Optional. Specifies more options for the aggregation, such as `explain`, `allowDiskUse`, and `cursor`.
 
+Collation is off by default: an `aggregate` that sets `collation` fails with `collation is not supported in the aggregate command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Examples
 
 ### Example 1: Calculate total sales by category

api-reference/commands/aggregation/count.md

@@ -20,6 +20,8 @@ db.collection.count(query, options)
 - `query`: A document specifying the selection criteria using query operators.
 - `options`: Optional. A document specifying options, such as `limit` and `skip`.
 
+Collation is off by default: a `count` that sets `collation` fails with `collation is not supported in the count command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Examples
 
 Here are some examples to demonstrate the usage of the `count` command:

api-reference/commands/aggregation/distinct.md

@@ -19,7 +19,7 @@ db.collection.distinct(field, query, options)
 
 - `field`: The field that receives the returned distinct values.
 - `query`: Optional. A query that specifies the documents from which to retrieve the distinct values.
-- `options`: Optional. Other options for the command.
+- `options`: Optional. Other options for the command. `collation` isn't supported and fails with `collation is not supported in the distinct command yet.`
 
 ## Examples
 

api-reference/commands/diagnostic/hello.md

@@ -9,7 +9,7 @@ category: diagnostic
 
 The `hello` command returns a document describing the role of the DocumentDB server, along with connection limits, supported authentication mechanisms, and the version of the DocumentDB engine you are connected to. It's the recommended way to discover the DocumentDB version from a MongoDB client, since the `internal.documentdb_versions` field reports the underlying engine version rather than only the emulated MongoDB wire-protocol version.
 
-The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, in `major-minor` form such as `0.113-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `0.113.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, when the shared library has been updated but `ALTER EXTENSION documentdb UPDATE` hasn't yet been run. A mismatch such as `["0.112-0", "0.113.0"]` indicates the SQL schema is behind the loaded binary.
+The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, such as `1.0-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `1.0.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, after the 1.0 packages are installed over 0.117 but before `ALTER EXTENSION documentdb UPDATE` has been run. A mismatch such as `["0.117-0", "1.0.0"]` indicates the SQL schema is behind the loaded binary.
 
 ## Syntax
 
@@ -42,7 +42,7 @@ The response includes the following fields. Fields marked as DocumentDB-specific
 | **`readOnly`** | `true` when the connection is read-only. |
 | **`connectionId`** | Identifier of the current connection. |
 | **`saslSupportedMechs`** | Authentication mechanisms the server supports, for example `SCRAM-SHA-256`. |
-| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (`major-minor`, for example `0.113-0`) — followed by the loaded binary version (dotted, for example `0.113.0`). These normally match and diverge only during an upgrade. |
+| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (for example `1.0-0`) — followed by the loaded binary version (dotted, for example `1.0.0`). These normally match and diverge only during an upgrade. |
 | **`ok`** | `1` when the command succeeds. |
 
 ## Examples
@@ -75,8 +75,8 @@ The server returns a document similar to the following:
   ],
   "internal": {
     "documentdb_versions": [
-      "0.113-0",
-      "0.113.0"
+      "1.0-0",
+      "1.0.0"
     ],
     "kind": ""
   },
@@ -95,7 +95,7 @@ db.runCommand({ hello: 1 }).internal.documentdb_versions
 The command returns an array with the installed SQL extension version followed by the loaded binary version:
 
 ```json
-[ "0.113-0", "0.113.0" ]
+[ "1.0-0", "1.0.0" ]
 ```
 
 The first value is the installed SQL extension version — the schema version, from the `pg_extension` catalog — and the second is the compiled binary version. They normally describe the same release and differ only in formatting.

api-reference/commands/query-and-write/delete.md

@@ -30,7 +30,7 @@ db.collection.deleteMany(
 | Parameter | Description |
 | --- | --- |
 | **<`filter`>** | A document that specifies the criteria for deletion. Only the documents that match the filter are deleted|
-| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation|
+| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation. Collation is off by default: a delete that sets it fails with `BSON field 'delete.deletes.collation' is not yet supported` unless the server enables `documentdb_core.enableCollation`.|
 
 ## Example(s)
 

api-reference/commands/query-and-write/find.md

@@ -25,6 +25,8 @@ db.collection.find(query, projection, options)
 | **`projection`** | (Optional) A document that specifies the fields in the matching documents to be returned in the result set|
 | **`options`** | (Optional) A document that specifies options for query behavior and results|
 
+Collation is off by default: a `find` that sets `collation` fails with `collation is not supported in the find command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Example(s)
 
 Consider this sample document from the stores collection in the StoreData database.

api-reference/commands/query-and-write/findandmodify.md

@@ -35,6 +35,8 @@ db.collection.findAndModify({
 - **fields**: Limits the fields to return for the matching document.
 - **upsert**: If `true`, creates a new document if no document matches the query.
 
+`collation` isn't supported and fails with `findAndModify.collation is not implemented yet`.
+
 ## Examples
 
 ### Example 1: Update total sales
@@ -135,6 +137,19 @@ db.stores.findAndModify({
     ]
   },
   "promotionEvents": [
+    {
+      "eventName": "Incredible Discount Days",
+      "promotionalDates": {
+        "startDate": { "Year": 2024, "Month": 2, "Day": 11 },
+        "endDate": { "Year": 2024, "Month": 2, "Day": 18 }
+      },
+      "discounts": [
+        { "categoryName": "Square Sunglasses", "discountPercentage": 16 },
+        { "categoryName": "Safety Glasses", "discountPercentage": 17 },
+        { "categoryName": "Wayfarers", "discountPercentage": 7 },
+        { "categoryName": "Eyewear Accessories", "discountPercentage": 12 }
+      ]
+    },
     {
       "eventName": "Electronics Super Saver",
       "promotionalDates": { "startDate": "2025-09-31", "endDate": "2025-09-31" },
@@ -156,7 +171,7 @@ db.stores.findAndModify({
 
 ### Example 3: Remove a promotional event
 
-Suppose we want to remove the "Electronics Super Saver" promotional event from the store with `_id` "e5767a9f-cd95-439c-9ec4-7ddc13d22926" and return the original document.
+Suppose we want to remove the "Electronics Super Saver" promotional event from the store with `_id` "e5767a9f-cd95-439c-9ec4-7ddc13d22926" and return the updated document.
 
 ```javascript
 db.stores.findAndModify({

api-reference/commands/query-and-write/update.md

@@ -9,6 +9,8 @@ category: query-and-write
 
 The `update` command is used to modify existing documents within a collection. The `update` command can be used to update one or multiple documents based on filtering criteria. Values of fields can be changed, new fields and values can be added and existing fields can be removed.
 
+The `collation` option isn't supported and fails with `BSON field 'update.updates.collation' is not yet supported`.
+
 ## Example(s)
 
 Consider this sample document from the stores collection in the StoreData database.

api-reference/operators/aggregation/$changestream.md

@@ -1,13 +1,16 @@
 ---
 title: $changeStream
-description: The $changeStream stage opens a change stream cursor to track data changes in real-time.
+description: The $changeStream stage opens a change stream cursor in MongoDB. DocumentDB does not support it.
 type: operators
 category: aggregation
 ---
 
 # $changeStream
 
-The `$changeStream` aggregation stage opens a change stream cursor that tracks data changes in real-time. This stage enables applications to react to insert, update, delete, and other operations as they occur in the collection.
+> [!IMPORTANT]
+> DocumentDB does not support `$changeStream`. Any pipeline that uses it, including `db.collection.watch()`, fails with `Stage $changeStream is not supported yet in native pipeline` (`CommandNotSupported`, code 115).
+
+In MongoDB, the `$changeStream` aggregation stage opens a cursor that reports inserts, updates, deletes, and other changes as they happen. The syntax below is listed for reference only.
 
 ## Syntax
 
@@ -37,123 +40,9 @@ The `$changeStream` aggregation stage opens a change stream cursor that tracks d
 | **`startAtOperationTime`** | Optional. timestamp for starting change stream from a specific time. |
 | **`showExpandedEvents`** | Optional. Boolean. Include another change stream events. Default is false. |
 
-## Examples
-
-Consider this sample document from the stores collection.
-
-```json
-{
-    "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
-    "name": "First Up Consultants | Beverage Shop - Satterfieldmouth",
-    "location": {
-        "lat": -89.2384,
-        "lon": -46.4012
-    },
-    "staff": {
-        "totalStaff": {
-            "fullTime": 8,
-            "partTime": 20
-        }
-    },
-    "sales": {
-        "totalSales": 75670,
-        "salesByCategory": [
-            {
-                "categoryName": "Wine Accessories",
-                "totalSales": 34440
-            },
-            {
-                "categoryName": "Bitters",
-                "totalSales": 39496
-            },
-            {
-                "categoryName": "Rum",
-                "totalSales": 1734
-            }
-        ]
-    },
-    "promotionEvents": [
-        {
-            "eventName": "Unbeatable Bargain Bash",
-            "promotionalDates": {
-                "startDate": {
-                    "Year": 2024,
-                    "Month": 6,
-                    "Day": 23
-                },
-                "endDate": {
-                    "Year": 2024,
-                    "Month": 7,
-                    "Day": 2
-                }
-            },
-            "discounts": [
-                {
-                    "categoryName": "Whiskey",
-                    "discountPercentage": 7
-                },
-                {
-                    "categoryName": "Bitters",
-                    "discountPercentage": 15
-                },
-                {
-                    "categoryName": "Brandy",
-                    "discountPercentage": 8
-                },
-                {
-                    "categoryName": "Sports Drinks",
-                    "discountPercentage": 22
-                },
-                {
-                    "categoryName": "Vodka",
-                    "discountPercentage": 19
-                }
-            ]
-        },
-        {
-            "eventName": "Steal of a Deal Days",
-            "promotionalDates": {
-                "startDate": {
-                    "Year": 2024,
-                    "Month": 9,
-                    "Day": 21
-                },
-                "endDate": {
-                    "Year": 2024,
-                    "Month": 9,
-                    "Day": 29
-                }
-            },
-            "discounts": [
-                {
-                    "categoryName": "Organic Wine",
-                    "discountPercentage": 19
-                },
-                {
-                    "categoryName": "White Wine",
-                    "discountPercentage": 20
-                },
-                {
-                    "categoryName": "Sparkling Wine",
-                    "discountPercentage": 19
-                },
-                {
-                    "categoryName": "Whiskey",
-                    "discountPercentage": 17
-                },
-                {
-                    "categoryName": "Vodka",
-                    "discountPercentage": 23
-                }
-            ]
-        }
-    ]
-}
-```
-
-### Example 1: Monitor all changes in stores collection
+## Example
 
-This operation sets up a change stream to monitor all changes in the stores collection.
+This pipeline is rejected:
 
 ```javascript
 db.stores.aggregate([
@@ -165,27 +54,6 @@ db.stores.aggregate([
 ])
 ```
 
-When a store document is updated, the change stream returns the change event with the full document.
-
-```json
-{
-  "_id": { "_data": "AeARBpQ/AAAA" },
-  "operationType": "update",
-  "fullDocument": {
-    "_id": "905d1939-e03a-413e-a9c4-221f74055aac",
-    "name": "Trey Research | Home Office Depot - Lake Freeda",
-    "sales": {
-      "revenue": 42500
-    },
-    "company": "Trey Research",
-    "lastUpdated": "ISODate('2024-06-16T10:30:00.000Z')"
-  },
-  "ns": {
-    "db": "StoreData",
-    "coll": "stores"
-  },
-  "documentKey": {
-    "_id": "905d1939-e03a-413e-a9c4-221f74055aac"
-  }
-}
+```
+Stage $changeStream is not supported yet in native pipeline
 ```

api-reference/operators/aggregation/$collstats.md

@@ -14,7 +14,6 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab
 ```javascript
 {
   $collStats: {
-    latencyStats: { histograms: <boolean> },
     storageStats: { scale: <number> },
     count: {}
   }
@@ -25,10 +24,11 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab
 
 | Parameter | Description |
 | --- | --- |
-| **`latencyStats`** | Optional. Specifies whether to include latency statistics. The `histograms` field is a boolean that indicates whether to include histograms of latency data. |
 | **`storageStats`** | Optional. Specifies whether to include storage statistics. The `scale` field is a number that indicates the scale factor for the storage statistics. |
 | **`count`** | Optional. Includes the count of documents in the collection. |
 
+`latencyStats` and `queryExecStats` aren't supported; either one fails with `collStats with <option> not supported yet` (`CommandNotSupported`).
+
 ## Examples
 
 Consider this sample document from the stores collection.

api-reference/operators/array-update/$positional-all.md

@@ -1,13 +1,13 @@
 ---
 title: $[]
-description: The $[] operator is used to update all elements in an array that match the query condition.
+description: The $[] all positional operator applies an update to every element of an array.
 type: operators
 category: array-update
 ---
 
 # $[]
 
-The $[] operator in DocumentDB is used to update all elements in an array that match a specified condition. This operator allows you to perform updates on multiple elements in an array without specifying their positions. It is particularly useful when you need to apply the same update to all items in an array.
+The `$[]` all positional operator applies an update to every element of an array in each matched document. Unlike `$`, it doesn't depend on which element the query matched, and unlike `$[<identifier>]`, it takes no `arrayFilters`. If the path holds a value that isn't an array, the update fails.
 
 ## Syntax
 
@@ -28,7 +28,7 @@ db.collection.update(
 | --- | --- |
 | **`<query>`** | The selection criteria for the documents to update. |
 | **`<arrayField>`** | The field containing the array to update. |
-| **`<value>`** | The value to set for each matching element in the array. |
+| **`<value>`** | The value to set for each element in the array. |
 
 ## Examples
 
@@ -150,7 +150,7 @@ This query updates all elements in the discounts array inside each promotion eve
 
 ```javascript
 db.stores.updateOne(
-  { _id: "905d1939-e03a-413e-a9c4-221f74055aac" },
+  { _id: "0fcc0bf0-ed18-4ab8-b558-9848e18058f4" },
   {
     $inc: {
       "promotionEvents.$[].discounts.$[].discountPercentage": 5
@@ -165,7 +165,7 @@ This query increase the total sales for all categories by 10% by using the $[] o
 
 ```javascript
 db.stores.update(
-  { _id: "905d1939-e03a-413e-a9c4-221f74055aac" },
+  { _id: "0fcc0bf0-ed18-4ab8-b558-9848e18058f4" },
   {
     $mul: {
       "sales.salesByCategory.$[].totalSales": 1.10