This is an automated email from the ASF dual-hosted git repository.
pgj pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
The following commit(s) were added to refs/heads/main by this push:
new aaf900531 Amend description of `use_index` on `/{db}/_find`
aaf900531 is described below
commit aaf900531177d807ff3b328bab97a5e1a0fac3e8
Author: Gabor Pali <[email protected]>
AuthorDate: Sun Sep 24 22:05:07 2023 +0200
Amend description of `use_index` on `/{db}/_find`
The semantics of Mango's `use_index` query parameter has changed
over time but this has not been reflected in the documentation,
which causes a lot of confusion.
The `use_index` parameter was introduced in 1b0426aa to force the
index selection to a specific index. Unfortunately, this did not
work out well in practice, so 743bd882 added a fallback mechanism
to make it less brittle. With that, `use_index` became only a
"hint" not an "instruction".
---
src/docs/src/api/database/find.rst | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/src/docs/src/api/database/find.rst
b/src/docs/src/api/database/find.rst
index 62dfb4f80..c707a1c1e 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -42,9 +42,14 @@
should be returned. If it is omitted, the entire object is returned.
More information provided in the section on :ref:`filtering fields
<find/filter>`. *Optional*
- :<json string|array use_index: Instruct a query to use a specific index.
- Specified either as ``"<design_document>"`` or
- ``["<design_document>", "<index_name>"]``. *Optional*
+ :<json string|array use_index: Request a query to use a specific
+ index. Specified either as ``"<design_document>"`` or
+ ``["<design_document>", "<index_name>"]``. It is not
+ guaranteed that the index will be actually used because if the
+ index is not valid for the selector, fallback to a valid index
+ is attempted. Therefore that is more like a hint. When
+ fallback occurs, the details are given in the ``warning``
+ field of the response. *Optional*
:<json boolean conflicts: Include conflicted documents if ``true``.
Intended use is to easily find conflicted documents, without an
index or view. Default is ``false``. *Optional*
