PHPLIB-1596 Fully describe $search, $searchMeta and $vectorSearch stages

mongodb · Dec 3, 2024 · 588fe7d · 588fe7d
1 parent 373bbc4
commit 588fe7d
Show file tree

Hide file tree

Showing 56 changed files with 4,793 additions and 23 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -22,5 +22,6 @@ rector.php export-ignore
 /src/Builder/Accumulator/*.php linguist-generated=true
 /src/Builder/Expression/*.php linguist-generated=true
 /src/Builder/Query/*.php linguist-generated=true
+/src/Builder/Search/*.php linguist-generated=true
 /src/Builder/Stage/*.php linguist-generated=true
 /tests/Builder/*/Pipelines.php linguist-generated=true
diff --git a/generator/README.md b/generator/README.md
@@ -42,6 +42,8 @@ Each operator can contain a `tests` section with a list if pipelines. To represe
 | Int64       | `!bson_int64 '123456789'`                              |
 | Decimal128  | `!bson_decimal128 '0.9'`                               |
 | UTCDateTime | `!bson_utcdatetime 0`                                  |
+| ObjectId    | `!bson_ObjectId '5a9427648b0beebeb69589a1`             |
 | Binary      | `!bson_binary 'IA=='`                                  |
+| Binary UUID | `!bson_uuid 'fac32260-b511-4c69-8485-a2be5b7dda9e'`    |
 
 To add new test cases to operators, you can get inspiration from the official MongoDB documentation and use the `generator/js2yaml.html` web page to manually convert a pipeline array from JS to Yaml.
diff --git a/generator/composer.json b/generator/composer.json
@@ -4,7 +4,7 @@
     "repositories": [
         {
             "type": "path",
-            "url": "../",
+            "url": "..",
             "symlink": true
         }
     ],

diff --git a/generator/config/definitions.php b/generator/config/definitions.php
@@ -58,4 +58,16 @@
             OperatorTestGenerator::class,
         ],
     ],
+
+    // Search Operators
+    [
+        'configFiles' => __DIR__ . '/search',
+        'namespace' => 'MongoDB\\Builder\\Search',
+        'classNameSuffix' => 'Operator',
+        'generators' => [
+            OperatorClassGenerator::class,
+            OperatorFactoryGenerator::class,
+            OperatorTestGenerator::class,
+        ],
+    ],
 ];
diff --git a/generator/config/expressions.php b/generator/config/expressions.php
@@ -109,6 +109,10 @@
         'implements' => [ResolvesToAny::class],
         'acceptedTypes' => ['string'],
     ],
+    'searchOperator' => [
+        'returnType' => Type\SearchOperatorInterface::class,
+        'acceptedTypes' => [Type\SearchOperatorInterface::class, ...$bsonTypes['object']],
+    ],
     'geometry' => [
         'returnType' => Type\GeometryInterface::class,
         'acceptedTypes' => [Type\GeometryInterface::class, ...$bsonTypes['object']],
@@ -168,4 +172,12 @@
     'GeoPoint' => [
         'acceptedTypes' => [...$bsonTypes['object']],
     ],
+
+    // Search
+    'searchPath' => [
+        'acceptedTypes' => ['string', 'array'],
+    ],
+    'searchScore' => [
+        'acceptedTypes' => [...$bsonTypes['object']],
+    ],
 ];
diff --git a/generator/config/schema.json b/generator/config/schema.json
@@ -46,7 +46,8 @@
                             "resolvesToInt",
                             "resolvesToTimestamp",
                             "resolvesToLong",
-                            "resolvesToDecimal"
+                            "resolvesToDecimal",
+                            "searchOperator"
                         ]
                     }
                 },
@@ -60,7 +61,8 @@
                     "enum": [
                         "array",
                         "object",
-                        "single"
+                        "single",
+                        "search"
                     ]
                 },
                 "description": {
@@ -135,7 +137,8 @@
                             "resolvesToInt", "intFieldPath", "int",
                             "resolvesToTimestamp", "timestampFieldPath", "timestamp",
                             "resolvesToLong", "longFieldPath", "long",
-                            "resolvesToDecimal", "decimalFieldPath", "decimal"
+                            "resolvesToDecimal", "decimalFieldPath", "decimal",
+                            "searchPath", "searchScore", "searchOperator"
                         ]
                     }
                 },

diff --git a/generator/config/search/autocomplete.yaml b/generator/config/search/autocomplete.yaml
@@ -0,0 +1,152 @@
+# $schema: ../schema.json
+name: autocomplete
+link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/'
+type:
+    - searchOperator
+encode: object
+description: |
+    The autocomplete operator performs a search for a word or phrase that
+    contains a sequence of characters from an incomplete input string. The
+    fields that you intend to query with the autocomplete operator must be
+    indexed with the autocomplete data type in the collection's index definition.
+arguments:
+    -
+        name: path
+        type:
+            - searchPath
+    -
+        name: query
+        type:
+            - string
+    -
+        name: tokenOrder
+        optional: true
+        type:
+            - string # any|sequential
+    -
+        name: fuzzy
+        optional: true
+        type:
+            - object
+    -
+        name: score
+        optional: true
+        type:
+            - searchScore
+tests:
+    -
+        name: 'Basic'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#basic-example'
+        pipeline:
+            -
+                $search:
+                    autocomplete:
+                        query: 'off'
+                        path: 'title'
+            -
+                $limit: 10
+            -
+                $project:
+                    _id: 0
+                    title: 1
+
+    -
+        name: 'Fuzzy'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#fuzzy-example'
+        pipeline:
+            -
+                $search:
+                    autocomplete:
+                        query: 'pre'
+                        path: 'title'
+                        fuzzy:
+                            maxEdits: 1
+                            prefixLength: 1
+                            maxExpansions: 256
+            -
+                $limit: 10
+            -
+                $project:
+                    _id: 0
+                    title: 1
+
+    -
+        name: 'Token Order any'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#simple-any-example'
+        pipeline:
+            -
+                $search:
+                    autocomplete:
+                        query: 'men with'
+                        path: 'title'
+                        tokenOrder: 'any'
+            -
+                $limit: 4
+            -
+                $project:
+                    _id: 0
+                    title: 1
+
+    -
+        name: 'Token Order sequential'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#simple-sequential-example'
+        pipeline:
+            -
+                $search:
+                    autocomplete:
+                        query: 'men with'
+                        path: 'title'
+                        tokenOrder: 'sequential'
+            -
+                $limit: 4
+            -
+                $project:
+                    _id: 0
+                    title: 1
+
+    -
+        name: 'Highlighting'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#highlighting-example'
+        pipeline:
+            -
+                $search:
+                    autocomplete:
+                        query: 'ger'
+                        path: 'title'
+                    highlight:
+                        path: 'title'
+            -
+                $limit: 5
+            -
+                $project:
+                    score:
+                        $meta: 'searchScore'
+                    _id: 0
+                    title: 1
+                    highlights:
+                        $meta: 'searchHighlights'
+
+    -
+        name: 'Across Multiple Fields'
+        link: 'https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/#search-across-multiple-fields'
+        pipeline:
+            -
+                $search:
+                    compound:
+                        should:
+                            -
+                                autocomplete:
+                                    query: 'inter'
+                                    path: 'title'
+                            -
+                                autocomplete:
+                                    query: 'inter'
+                                    path: 'plot'
+                        minimumShouldMatch: 1
+            -
+                $limit: 10
+            -
+                $project:
+                    _id: 0
+                    title: 1
+                    plot: 1