DRIVERS-3540 add "substring"

source/client-side-encryption/client-side-encryption.md

@@ -1367,7 +1367,7 @@ One of the strings:
     - Used for the `$encStrStartsWith` operator.
 - "suffix" / "suffixPreview"
     - Used for the `$encStrEndsWith` operator.
-- "substringPreview"
+- "substring" / "substringPreview"
     - Used for the `$encStrContains` operator.
 
 queryType only applies when algorithm is "Indexed", "Range", or "String". libmongocrypt returns an error if queryType is
@@ -2523,6 +2523,8 @@ explicit session parameter as described in the [Drivers Sessions Specification](
 
 ## Changelog
 
+- 2026-06-22: Add stable support for substring queries
+
 - 2026-06-17: Restore `prefixPreview` and `suffixPreview` as experimental.
 
 - 2026-06-16: Update tests in response to server-side validation of payloads

source/client-side-encryption/etc/data/encryptedFields-substring-ci-di.json

@@ -11,15 +11,15 @@
       "bsonType": "string",
       "queries": [
         {
-          "queryType": "substringPreview",
+          "queryType": "substring",
           "strMaxLength": {
             "$numberInt": "10"
           },
           "strMinQueryLength": {
             "$numberInt": "2"
           },
           "strMaxQueryLength": {
-            "$numberInt": "10"
+            "$numberInt": "6"
           },
           "contention": 0,
           "caseSensitive": false,
@@ -28,4 +28,4 @@
       ]
     }
   ]
-}
+}

source/client-side-encryption/etc/data/encryptedFields-substring-preview.json

@@ -0,0 +1,33 @@
+{
+  "fields": [
+    {
+            "keyId": {
+                "$binary": {
+                    "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+                    "subType": "04"
+                }
+            },
+            "path": "encryptedText",
+            "bsonType": "string",
+            "queries": [
+                {
+                    "queryType": "substringPreview",
+                    "strMaxLength": {
+                        "$numberInt": "10"
+                    },
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "6"
+                    },
+                    "contention": {
+                        "$numberLong": "0"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                }
+            ]
+        }
+  ]
+}

source/client-side-encryption/etc/data/encryptedFields-substring.json

@@ -1,6 +1,6 @@
 {
-  "fields": [
-    {
+    "fields": [
+        {
             "keyId": {
                 "$binary": {
                     "base64": "EjRWeBI0mHYSNBI0VniQEg==",
@@ -11,15 +11,15 @@
             "bsonType": "string",
             "queries": [
                 {
-                    "queryType": "substringPreview",
+                    "queryType": "substring",
                     "strMaxLength": {
                         "$numberInt": "10"
                     },
                     "strMinQueryLength": {
                         "$numberInt": "2"
                     },
                     "strMaxQueryLength": {
-                        "$numberInt": "10"
+                        "$numberInt": "6"
                     },
                     "contention": {
                         "$numberLong": "0"
@@ -29,5 +29,5 @@
                 }
             ]
         }
-  ]
+    ]
 }

source/client-side-encryption/tests/README.md

@@ -3883,9 +3883,12 @@ create the following collections with majority write concern:
     This step requires server pre-9.0.0.
 - `db.substring` using the `encryptedFields` option set to the contents of
     [encryptedFields-substring.json](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/etc/data/encryptedFields-substring.json)
-    This step requires server pre-9.0.0.
+    This step requires server 9.0.0+.
 - `db.substring-ci-di` using the `encryptedFields` option set to the contents of
     [encryptedFields-substring-ci-di.json](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/etc/data/encryptedFields-substring-ci-di.json)
+    This step requires server 9.0.0+.
+- `db.substring-preview` using the `encryptedFields` option set to the contents of
+    [encryptedFields-substring-preview.json](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/etc/data/encryptedFields-substring-preview.json)
     This step requires server pre-9.0.0.
 
 Load the file
@@ -3971,15 +3974,15 @@ class EncryptOpts {
       diacriticSensitive: true,
       substring: SubstringOpts {
        strMaxLength: 10,
-       strMaxQueryLength: 10,
+       strMaxQueryLength: 6,
        strMinQueryLength: 2,
       }
    },
 }
 ```
 
-Use `explicitEncryptedClient` to insert the following document into `db.substring` (if created) with majority write
-concern:
+Use `explicitEncryptedClient` to insert the following document into `db.substring` (if created) and
+`db.substring-preview` (if created) with majority write concern:
 
 ```javascript
 { "_id": 0, "encryptedText": <encrypted 'foobarbaz'> }
@@ -4139,29 +4142,34 @@ Assert that no documents are returned.
 
 #### Case 5: can find a document by substring
 
-Skip this test on server 9.0.0+.
+Run this case multiple times with the following sets of parameters:
+
+- `queryType=substring` and `collection=substring`
+    - Require server 9.0.0+ and libmongocrypt 1.20.0+.
+- `queryType=substringPreview` and `collection=substring-preview`
+    - Require server pre-9.0.0 and libmongocrypt 1.18.1+.
 
 Use `clientEncryption.encrypt()` to encrypt the string `"bar"` with the following `EncryptOpts`:
 
 ```typescript
 class EncryptOpts {
    keyId : <key1ID>,
    algorithm: "String",
-   queryType: "substringPreview",
+   queryType: "<queryType>",
    contentionFactor: 0,
    stringOpts: StringOpts {
       caseSensitive: true,
       diacriticSensitive: true,
       substring: SubstringOpts {
        strMaxLength: 10,
-       strMaxQueryLength: 10,
+       strMaxQueryLength: 6,
        strMinQueryLength: 2,
       }
    },
 }
 ```
 
-Use `explicitEncryptedClient` to run a "find" operation on the `db.substring` collection with the following filter:
+Use `explicitEncryptedClient` to run a "find" operation on the `db.<collection>` collection with the following filter:
 
 ```javascript
 { $expr: { $encStrContains: {input: '$encryptedText', substring: <encrypted 'bar'>} } }
@@ -4175,29 +4183,34 @@ Assert the following document is returned:
 
 #### Case 6: assert no document found by substring
 
-Skip this test on server 9.0.0+.
+Run this case multiple times with the following sets of parameters:
+
+- `queryType=substring` and `collection=substring`
+    - Require server 9.0.0+ and libmongocrypt 1.20.0+.
+- `queryType=substringPreview` and `collection=substring-preview`
+    - Require server pre-9.0.0 and libmongocrypt 1.18.1+.
 
 Use `clientEncryption.encrypt()` to encrypt the string `"qux"` with the following `EncryptOpts`:
 
 ```typescript
 class EncryptOpts {
    keyId : <key1ID>,
    algorithm: "String",
-   queryType: "substringPreview",
+   queryType: "<queryType>",
    contentionFactor: 0,
    stringOpts: StringOpts {
       caseSensitive: true,
       diacriticSensitive: true,
       substring: SubstringOpts {
        strMaxLength: 10,
-       strMaxQueryLength: 10,
+       strMaxQueryLength: 6,
        strMinQueryLength: 2,
       }
    },
 }
 ```
 
-Use `explicitEncryptedClient` to run a "find" operation on the `db.substring` collection with the following filter:
+Use `explicitEncryptedClient` to run a "find" operation on the `db.<collection>` collection with the following filter:
 
 ```javascript
 { $expr: { $encStrContains: {input: '$encryptedText', substring: <encrypted 'qux'>} } }
@@ -4399,14 +4412,14 @@ Use `clientEncryption.encrypt()` to encrypt the string `"bar"` with the followin
 class EncryptOpts {
    keyId : <key1ID>,
    algorithm: "String",
-   queryType: "substringPreview",
+   queryType: "substring",
    contentionFactor: 0,
    stringOpts: StringOpts {
       caseSensitive: false,
       diacriticSensitive: false,
       substring: SubstringOpts {
         strMaxLength: 10,
-        strMaxQueryLength: 10,
+        strMaxQueryLength: 6,
         strMinQueryLength: 2,
       }
    },
@@ -4445,14 +4458,14 @@ Use `clientEncryption.encrypt()` to encrypt the string `"cafe"` with the followi
 class EncryptOpts {
    keyId : <key1ID>,
    algorithm: "String",
-   queryType: "substringPreview",
+   queryType: "substring",
    contentionFactor: 0,
    stringOpts: StringOpts {
       caseSensitive: false,
       diacriticSensitive: false,
       substring: SubstringOpts {
         strMaxLength: 10,
-        strMaxQueryLength: 10,
+        strMaxQueryLength: 6,
         strMinQueryLength: 2,
       }
    },