rnewson commented on code in PR #4662:
URL: https://github.com/apache/couchdb/pull/4662#discussion_r1262607142
##########
src/docs/src/api/database/find.rst:
##########
@@ -1508,22 +1514,151 @@ it easier to take advantage of future improvements to
query planning
"title"
],
"partitioned": false
+ "index_candidates": [
+ {
+ "index": {
+ "ddoc": null,
+ "name": "_all_docs",
+ "type": "special",
+ "def": {
+ "fields": [
+ {
+ "_id": "asc"
+ }
+ ]
+ }
+ },
+ "usable": true,
+ "reason": "unfavored_type",
+ "ranking": 1
+ }
+ ],
+ "selector_hints": {
+ "indexable_fields": {
+ "json": [
+ "year"
+ ]
+ },
+ "unindexable_fields": {
+ "json": []
+ }
+ }
}
+.. _find/index_selection:
+
Index selection
===============
:ref:`_find <api/db/_find>` chooses which index to use for responding
-to a query, unless you specify an index at query time.
+to a query, unless you specify an index at query time. In this
+section, a brief overview of the index selection process is presented.
-The query planner looks at the selector section and finds the index with the
-closest match to operators and fields used in the query. If there are two
-or more json type indexes that match, the index with the smallest
-number of fields in the index is preferred.
-If there are still two or more candidate indexes,
-the index with the first alphabetical name is chosen.
+.. note::
+
+ It is good practice to specify indexes explicitly in your
+ queries. This prevents existing queries being affected by new
+ indexes that might get added in a production environment.
.. note::
- It is good practice to specify indexes explicitly in your queries. This
- prevents existing queries being affected by new indexes that might get
added
- in a production environment.
+
+ Both the :ref:`_explain <api/db/find/explain>` and :ref:`_find
+ <api/db/_find>` endpoints rely on the same index selection logic.
+ But :ref:`_explain <api/db/find/explain>` is a bit more elaborate,
+ therefore it could be used for simulation and exploration. In the
+ output, reasons for discarding indexes are placed in the ``reason``
+ field of the JSON objects under ``index_candidates``. Each reason
+ has a specific code, which will be mentioned at the relevant
+ subsections below.
+
+The index selection happens in multiple rounds.
+
+First, all the indexes for the database are collected. Whenever
+possible, the result includes the special index called `all docs`
+which is a trivial index on the ``_id`` field. This is reserved as a
+catch-all answer when no other suitable indexes could be found, but
+its use of discouraged for performance reasons.
Review Comment:
please don't refer to the primary index as 'trivial'. :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
