Skip to content

Commit c443be5

Browse files
committed
Polish doc wording to match existing user-doc house style
Replace non-idiomatic phrasing (rejected, descriptive error, fail fast) with the standard 'is not supported' / 'returns an error' / 'fails with an error' forms used across docs/user/. No behavioral claims changed. Signed-off-by: Eric Wei <mengwei.eric@gmail.com>
1 parent db26cb0 commit c443be5

1 file changed

Lines changed: 27 additions & 27 deletions

File tree

docs/user/dql/vector-search.rst

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -31,42 +31,42 @@ Description
3131
``vectorSearch(table='<index>', field='<vector-field>', vector='<array>', option='<key=value[,key=value]*>')``
3232

3333
All four arguments are required and must be passed by name as string
34-
literals. Positional or mixed-positional calls are rejected, for example::
34+
literals. Positional arguments, or a mix of positional and named
35+
arguments, are not supported. For example, the following is invalid::
3536

36-
-- invalid: positional argument
3737
FROM vectorSearch('my_vectors', field='embedding',
3838
vector='[0.1,0.2]', option='k=5') AS v
3939

40-
A table alias is required. Reference projected fields through the alias
41-
(``v._id``, ``v._score``, ``v.category``).
40+
A table alias is required. Projected fields are referenced through the
41+
alias (``v._id``, ``v._score``, ``v.category``).
4242

4343
If the ``opensearch-knn`` plugin is not installed on the target cluster,
4444
query execution fails with a ``vectorSearch() requires the k-NN plugin``
45-
error. ``_explain`` still works without the plugin.
45+
error. ``_explain`` continues to work without the plugin.
4646

4747
Arguments
4848
---------
4949

5050
- ``table`` — single concrete index or alias to search. Wildcards
5151
(``*``), comma-separated multi-index targets, ``_all``, ``.``, and
52-
``..`` are rejected. The target index must have ``index.knn: true`` and
53-
map the target field as ``knn_vector``.
52+
``..`` are not supported. The target index must have
53+
``index.knn: true`` and map the target field as ``knn_vector``.
5454
- ``field`` — name of the ``knn_vector`` field.
5555
- ``vector`` — query vector as a JSON-style array of numbers, passed as a
5656
string (for example, ``'[0.1, 0.2, 0.3]'``). Components must be
57-
comma-separated finite numbers; semicolon, colon, or pipe separators
58-
and empty components (for example, ``'[1.0,,2.0]'`` or ``'[1.0,]'``)
59-
are rejected. The vector dimension must match the ``knn_vector``
60-
mapping on the target index.
57+
comma-separated finite numbers. Semicolon, colon, and pipe separators
58+
are not supported, and empty components (for example, ``'[1.0,,2.0]'``
59+
or ``'[1.0,]'``) return an error. The vector dimension must match the
60+
``knn_vector`` mapping on the target index.
6161
- ``option`` — comma-separated ``key=value`` pairs. Exactly one of ``k``,
6262
``max_distance``, or ``min_score`` is required. ``filter_type`` is
6363
optional.
6464

6565
Supported option keys
6666
---------------------
6767

68-
Option keys are lower-case and case-sensitive. ``K=5`` or ``Filter_Type=post``
69-
will be rejected with an "Unknown option key" error.
68+
Option keys are lower-case and case-sensitive. ``K=5`` or
69+
``Filter_Type=post`` returns an "Unknown option key" error.
7070

7171
- ``k`` — top-k mode. Integer between 1 and 10000. The query returns up to
7272
``k`` nearest neighbors.
@@ -83,8 +83,8 @@ exactly one.
8383

8484
Native k-NN tuning options (for example, ``method_parameters.ef_search``,
8585
``method_parameters.nprobes``, ``rescore.oversample_factor``) are not
86-
exposed through ``vectorSearch()`` and are rejected as unknown option
87-
keys.
86+
supported through ``vectorSearch()`` and return an "Unknown option
87+
key" error.
8888

8989
Syntax
9090
------
@@ -190,19 +190,19 @@ Behavior depends on whether ``filter_type`` is specified:
190190
results are returned. A query with no ``WHERE`` clause is valid.
191191
- **Explicit ``post``** — a ``WHERE`` clause is required and must be
192192
translatable to an OpenSearch filter query. If the ``WHERE`` clause is
193-
missing or cannot be translated, the query fails with a descriptive
194-
error. Specifying ``filter_type=post`` explicitly is useful when you
195-
want the query to fail fast rather than silently fall back to in-memory
196-
filtering.
193+
missing or cannot be translated, the query fails with an error.
194+
Specifying ``filter_type=post`` explicitly is useful when the query
195+
should fail with an error instead of silently falling back to
196+
in-memory filtering.
197197
- **Explicit ``efficient``** — a ``WHERE`` clause is required and must
198198
compile to a filter shape that can be embedded under ``knn.filter``.
199199
``efficient`` supports simple native filters: ``term``, ``range``,
200200
``wildcard``, ``exists``, full-text family (``match``, ``match_phrase``,
201201
``match_phrase_prefix``, ``match_bool_prefix``, ``multi_match``,
202202
``query_string``, ``simple_query_string``), and boolean combinations of
203203
those filters. Predicates that compile to script queries (arithmetic,
204-
function calls, ``CASE``, date math), nested predicates, and unknown
205-
query shapes are rejected.
204+
function calls, ``CASE``, date math), nested predicates, and other
205+
query shapes are not supported in this mode and return an error.
206206

207207
Example 4: Implicit pushdown (no ``filter_type``)
208208
-------------------------------------------------
@@ -263,13 +263,13 @@ Limitations
263263
The following are not supported on ``vectorSearch()``:
264264

265265
- ``GROUP BY`` and aggregations over a ``vectorSearch()`` relation are
266-
rejected with an error.
266+
not supported and return an error.
267267
- An outer ``WHERE`` clause applied to a ``vectorSearch()`` subquery is
268-
rejected with an error, because the predicate would be evaluated only
269-
after the top-k rows have been selected by vector distance and can
270-
silently yield zero rows. Place the predicate inside the subquery,
271-
directly on the ``vectorSearch()`` alias, so it can participate in
272-
``WHERE`` pushdown.
268+
not supported and returns an error, because the predicate would be
269+
evaluated only after the top-k rows have been selected by vector
270+
distance and can silently yield zero rows. Place the predicate inside
271+
the subquery, directly on the ``vectorSearch()`` alias, so that it
272+
participates in ``WHERE`` pushdown.
273273
- ``JOIN`` between a ``vectorSearch()`` relation and another relation is
274274
not supported.
275275
- ``UNION`` / ``INTERSECT`` / ``EXCEPT`` combining a ``vectorSearch()``

0 commit comments

Comments
 (0)