AWS documentdb documentation change

Service: documentdb · 2026-03-31 · Documentation low

File: documentdb/latest/developerguide/substrBytes.md

Summary

Added new documentation page for the $substrBytes operator in Amazon DocumentDB, including description, parameters, MongoDB shell example, and code examples in Node.js and Python.

Security assessment

This change introduces documentation for a database operator ($substrBytes) that extracts substrings based on byte positions. There is no evidence of addressing a security vulnerability, weakness, or incident. The content is purely functional documentation explaining operator usage, parameters, and providing code examples. The code examples include standard connection strings with TLS parameters, but these are routine security best practices for database connections, not new security documentation.

Diff

diff --git a/documentdb/latest/developerguide/substrBytes.md b/documentdb/latest/developerguide/substrBytes.md
index 8b1378917..fd6452fcc 100644
--- a//documentdb/latest/developerguide/substrBytes.md
+++ b//documentdb/latest/developerguide/substrBytes.md
@@ -0,0 +1 @@
+[](/pdfs/documentdb/latest/developerguide/developerguide.pdf#substrBytes "Open PDF")
@@ -1,0 +3,132 @@
+[Documentation](/index.html)[Amazon DocumentDB](/documentdb/index.html)[Developer Guide](what-is.html)
+
+Example (MongoDB Shell)Code examples
+
+# $substrBytes
+
+The `$substrBytes` operator in Amazon DocumentDB is used to extract a substring from a string based on a specified byte range. This operator is useful when you need to extract a substring from a string and the number of bytes required to represent each character in the string is important.
+
+Unlike `$substrCP`, which operates on the number of Unicode code points, `$substrBytes` operates on the number of bytes required to represent the characters in the string. This can be particularly useful when working with strings that contain non-ASCII characters, as these characters may require more than one byte to represent.
+
+*Note:* `$substr` has been deprecated since version 3.4. `$substr` is now an alias for `$substrBytes`.
+
+**Parameters**
+
+  * `string`: The input string from which the substring will be extracted.
+
+  * `startByte`: The zero-based starting byte position of the substring to be extracted. A negative value can be used to specify a position from the end of the string.
+
+  * `length`: The number of bytes in the substring to be extracted.
+
+
+
+
+## Example (MongoDB Shell)
+
+In this example, we'll use `$substrBytes` to extract a substring from a string that contains non-ASCII characters.
+
+**Create sample documents**
+    
+    
+    db.people.insertMany([
+      { "_id": 1, "Desk": "Düsseldorf-NRW-021" },
+      { "_id": 2, "Desk": "Bremerhaven-HBB-32a" },
+      { "_id": 3, "Desk": "Norderstedt-SHH-892.50" },
+      { "_id": 4, "Desk": "Brandenburg-BBB-78" }
+    ]);
+
+**Query example**
+    
+    
+    db.people.aggregate([
+      {
+        $project: {
+          "state": { $substrBytes: [ "$Desk", 12, 3] }
+        }
+      }
+    ])
+
+**Output**
+    
+    
+    { "_id": 1, "state": "NRW" },
+    { "_id": 2, "state": "HBB" },
+    { "_id": 3, "state": "SHH" },
+    { "_id": 4, "state": "BBB" }
+
+In this example, we use `$substrBytes` to extract a 3-byte substring starting from the 12th byte of the `Desk` field. This allows us to extract the 2-character state abbreviation, even though the string may contain non-ASCII characters.
+
+## Code examples
+
+To view a code example for using the `$substrBytes` command, choose the tab for the language that you want to use:
+
+Node.js
+    
+    
+    
+    const { MongoClient } = require('mongodb');
+    
+    async function example() {
+      const client = await MongoClient.connect('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
+      const db = client.db('test');
+      const people = db.collection('people');
+    
+      const result = await people.aggregate([
+        {
+          $project: {
+            "state": { $substrBytes: ["$Desk", 12, 3] }
+          }
+        }
+      ]).toArray();
+    
+      console.log(result);
+      client.close();
+    }
+    
+    example();
+
+Python
+    
+    
+    
+    from pymongo import MongoClient
+    
+    def example():
+        client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
+        db = client.test
+        people = db.people
+    
+        result = list(people.aggregate([
+            {
+                '$project': {
+                    "state": { '$substrBytes': ["$Desk", 12, 3] }
+                }
+            }
+        ]))
+    
+        print(result)
+        client.close()
+    
+    example()
+
+![Warning](https://d1ge0kk1l5kms0.cloudfront.net/images/G/01/webservices/console/warning.png) **Javascript is disabled or is unavailable in your browser.**
+
+To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.
+
+[Document Conventions](/general/latest/gr/docconventions.html)
+
+$substr
+
+$substrCP
+
+Did this page help you? - Yes
+
+Thanks for letting us know we're doing a good job!
+
+If you've got a moment, please tell us what we did right so we can do more of it.
+
+Did this page help you? - No
+
+Thanks for letting us know this page needs work. We're sorry we let you down.
+
+If you've got a moment, please tell us how we can make the documentation better.