Polish Atlas search docs

Author: timgraham

docs/source/ref/models/search.rst

@@ -77,7 +77,7 @@ in a MongoDB Atlas Search index.
 
 - ``path``: The document path to the field.
 - ``query``: The value to match.
-- ``fuzzy``: Fuzzy matching options, e.g., ``{"maxEdits": 1}``.
+- ``fuzzy``: A dictionary of fuzzy matching options, e.g., ``{"maxEdits": 1}``.
 - ``token_order``: Controls token sequence behavior. Accepts values like
   ``"sequential"`` or ``"any"``.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
@@ -226,7 +226,7 @@ date, or other comparable fields based on upper and/or lower bounds.
 
 Matches string fields using a regular expression.
 
-Uses the :doc:`regex operator <atlas:atlas-search/regex>` to apply a regular
+Uses the :doc:`regex operator <atlas:atlas-search/regex>` to match a regular
 expression pattern to the contents of a specified field.
 
 .. code-block:: pycon
@@ -241,10 +241,9 @@ expression pattern to the contents of a specified field.
 **Arguments:**
 
 - ``path``: The document path to the field.
-- ``query``: Regular expression string that will be applied to the field
-  contents.
-- ``allow_analyzed_field``: Boolean indicating whether to allow matching
-  against analyzed fields.
+- ``query``: The regular expression to match.
+- ``allow_analyzed_field``: Boolean indicating whether to match against an
+  analyzed field. ``False`` if not specified.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
 ``SearchText``
@@ -255,8 +254,8 @@ expression pattern to the contents of a specified field.
 Performs full-text search using the :doc:`text operator
 <atlas:atlas-search/text>`.
 
-Matches terms in the specified field and supports fuzzy matching, match
-criteria, and synonym mappings.
+Matches terms in the specified field. Supports fuzzy matching, match criteria,
+and synonym mappings.
 
 .. code-block:: pycon
 
@@ -274,9 +273,8 @@ criteria, and synonym mappings.
 **Arguments:**
 
 - ``path``: The document path to the field.
-- ``query``: The argument is the search term or phrase.
-- ``fuzzy``: A dictionary of fuzzy matching options, such as
-  ``{"maxEdits": 1}``.
+- ``query``: The search term or phrase.
+- ``fuzzy``: A dictionary of fuzzy matching options, e.g., ``{"maxEdits": 1}``.
 - ``match_criteria``: Whether to match ``"all"`` or ``"any"`` terms (defaults
   to Atlas Search behavior).
 - ``synonyms``: The name of a synonym mapping defined in your Atlas index.
@@ -308,8 +306,8 @@ single character) wildcards.
 
 - ``path``: The document path to the field.
 - ``query``: A wildcard string that may include ``*`` and ``?``.
-- ``allow_analyzed_field``: Boolean indicating whether to allow matching
-  against analyzed fields.
+- ``allow_analyzed_field``: Boolean indicating whether to match against an
+  analyzed field. ``False`` if not specified.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
 ``SearchGeoShape``
@@ -320,8 +318,8 @@ single character) wildcards.
 Filters documents based on spatial relationships with a geometry.
 
 Uses the :doc:`geoShape operator <atlas:atlas-search/geoShape>` to match
-documents where a geo field has a specified spatial relation to a given
-GeoJSON geometry.
+documents where a geo field has a specified spatial relation to a given GeoJSON
+geometry.
 
 .. code-block:: pycon
 
@@ -338,8 +336,8 @@ GeoJSON geometry.
 **Arguments:**
 
 - ``path``: The document path to the field.
-- ``relation``: The spatial relation to test. Valid values include
-  ``"within"``, ``"intersects"``, and ``"disjoint"``.
+- ``relation``: The spatial relation to test. Valid values are ``"contains"``,
+  ``"disjoint"``, ``"intersects"``, and ``"within"``.
 - ``geometry``: A GeoJSON geometry object to compare against.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
@@ -359,7 +357,7 @@ geometry.
     >>> from django_mongodb_backend.expressions import SearchGeoWithin
     >>> polygon = {"type": "Polygon", "coordinates": [[[0, 0], [3, 6], [6, 1], [0, 0]]]}
     >>> Article.objects.annotate(
-    ...     score=SearchGeoWithin(path="location", kind="Polygon", geo_object=polygon)
+    ...     score=SearchGeoWithin(path="location", kind="geometry", geo_object=polygon)
     ... )
     <QuerySet [
         <Article: title: Local Environmental Impacts Study (location: [2, 3])>,
@@ -369,7 +367,8 @@ geometry.
 **Arguments:**
 
 - ``path``: The document path to the field.
-- ``kind``: The GeoJSON geometry type ``circle``, ``box``, or ``geometry``.
+- ``kind``: The GeoJSON geometry type: ``"circle"``, ``"box"``, or
+  ``"geometry"``.
 - ``geo_object``: The GeoJSON geometry defining the spatial boundary.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
@@ -399,11 +398,10 @@ retrieve documents that resemble one or more example documents.
 
 **Arguments:**
 
-- ``documents``: List of example documents or expressions
-  that serve as references for similarity.
+- ``documents``: List of example documents or expressions that serve as
+  references for similarity.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
-
 ``CompoundExpression``
 ======================
 
@@ -442,9 +440,8 @@ contribute to document matching and scoring.
   match.
 - ``score``: A :class:`SearchScoreOption` to tune the relevance score.
 
-
-``Combinable expressions``
---------------------------
+Combinable expressions
+----------------------
 
 All Atlas Search expressions subclassed from ``SearchExpression``
 can be combined using Python's bitwise operators:
@@ -472,8 +469,8 @@ This allows for more expressive and readable search logic:
 Performs vector similarity search using the :doc:`$vectorSearch stage
 <atlas:atlas-vector-search/vector-search-stage>`.
 
-Retrieves documents whose vector field is most similar to a given query
-vector, using either approximate or exact nearest-neighbor search.
+Retrieves documents whose vector field is most similar to a given query vector,
+using either approximate or exact nearest-neighbor search.
 
 .. code-block:: pycon
 
@@ -495,9 +492,10 @@ vector, using either approximate or exact nearest-neighbor search.
 - ``path``: The document path to the field.
 - ``query_vector``: The input vector used for similarity comparison.
 - ``limit``: The maximum number of matching documents to return.
-- ``num_candidates``: The number of candidate documents considered during
-  search.
+- ``num_candidates``: The number of nearest neighbors to use during the search.
+  Required if ``exact`` is ``False`` or omitted.
 - ``exact``:  A boolean whether to enforce exact search instead of approximate.
+  Required if ``num_candidates`` is omitted. If omitted, defaults to ``False``.
 - ``filter``: A MQL filter expression to restrict the candidate documents.
 
 .. warning::