This is an automated email from the ASF dual-hosted git repository. vatamane pushed a commit to branch merge-3.4.3 in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit eaa93dd5ffffd8541344cd4c9ae03cfa76fa1ca4 Author: Jamie Bliss <[email protected]> AuthorDate: Mon Feb 17 16:52:51 2025 -0500 Rework the index documentation, bring more of it into the prose I think this makes it more clear what exactly index definitions are and how different kinds of indexes are similar/different --- src/docs/src/api/database/find.rst | 28 +++-------------- src/docs/src/ddocs/mango.rst | 64 +++++++++++++++++++++++++++++++++----- 2 files changed, 60 insertions(+), 32 deletions(-) diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst index b6837df6a..011edf800 100644 --- a/src/docs/src/api/database/find.rst +++ b/src/docs/src/api/database/find.rst @@ -337,7 +337,8 @@ built using MapReduce Views. :<header Content-Type: - :mimetype:`application/json` - :query object index: JSON object describing the index to create. + :query object index: JSON object describing the index to create. (Depends + on the type of index, see :ref:`ddoc/mango/indexes`) :query string ddoc: Name of the design document in which the index will be created. By default, each index will be created in its own design document. @@ -372,14 +373,6 @@ built using MapReduce Views. :code 404: Database not found :code 500: Execution error - The `index` parameter is a JSON object with the following fields: - - - **fields** (`array`): Array of field names following the :ref:`sort - syntax <find/sort>`. Nested fields are also allowed, e.g. `"person.name"`. - - **partial_filter_selector** (`object`): A :ref:`selector <find/selectors>` - to apply to documents at indexing time, creating a - :ref:`partial index <find/partial_indexes>`. *Optional* - Example of creating a new index for a field called ``foo``: **Request**: @@ -472,27 +465,14 @@ present, including those which have ``null`` values. :>header Transfer-Encoding: ``chunked`` :>json number total_rows: Number of indexes. - :>json array indexes: Array of index definitions (see below). + :>json array indexes: Array of index definitions (see + :ref:`ddoc/mango/indexes/definitions`). :code 200: Success :code 400: Invalid request :code 401: Read permission required :code 500: Execution error - Index definitions are JSON objects with the following fields: - - - **ddoc** (`string`): ID of the design document the index belongs to. This ID - can be used to retrieve the design document containing the index, - by making a ``GET`` request to ``/{db}/ddoc``, where ``ddoc`` is the - value of this field. - - **name** (`string`): Name of the index. - - **partitioned** (`boolean`): Partitioned (``true``) or global - (``false``) index. - - **type** (`string`): Type of the index. Currently ``"json"`` is the only - supported type. - - **def** (`object`): Definition of the index, containing the indexed fields - and the sort order: ascending or descending. - **Request**: .. code-block:: http diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst index 93560ab55..522454c4b 100644 --- a/src/docs/src/ddocs/mango.rst +++ b/src/docs/src/ddocs/mango.rst @@ -727,6 +727,8 @@ operator. But it is not always the case: for example, comparison of strings is done with ICU and can can give surprising results if you were expecting ASCII ordering. See :ref:`views/collation` for more details. +.. _ddoc/mango/indexes + Indexes ======= @@ -747,6 +749,50 @@ They primarily consist of a list of fields to index, but can also contain a This represents synthetic indexes produced by CouchDB itself and refers exclusively to ``_all_docs``. +.. _ddoc/mango/indexes/definitions: + +Index Definitions +----------------- + +Index definitions are JSON objects with the following fields: + +- **ddoc** (`string`): ID of the design document the index belongs to. This ID + can be used to retrieve the design document containing the index, + by making a ``GET`` request to ``/{db}/ddoc``, where ``ddoc`` is the + value of this field. +- **name** (`string`): Name of the index. +- **partitioned** (`boolean`): Partitioned (``true``) or global + (``false``) index. +- **type** (`string`): Type of the index. Can be ``"json"``, ``"text"``, + ``"nouveau"``, or sometimes ``"special"``. +- **def**/**index** (`object`): Definition of the index, depending on the type + (see below). Which name is used depends on the context. + +JSON Indexes +------------ + +JSON Indexes are you standard structural indexes, used by the majority of +:ref:`selector operators<find/selectors>`. + +Their definition consists of: + +- **fields** (`array`): Array of field names following the :ref:`sort + syntax <find/sort>`. Nested fields are also allowed, e.g. `"person.name"`. +- **partial_filter_selector** (`object`): A :ref:`selector <find/selectors>` + to apply to documents at indexing time, creating a + :ref:`partial index <find/partial_indexes>`. *Optional* + +Example: + +.. code-block:: javascript + + { + "type" : "json", + "index": { + "fields": ["foo"] + } + } + .. _find/partial_indexes: Partial Indexes @@ -839,7 +885,7 @@ can be queried using either ``$text`` or Example index: -.. code-block:: json +.. code-block:: javascript { "type": "nouveau", @@ -853,14 +899,16 @@ Example index: } } -* ``fields``: ``"all_fields"`` or list of objects: - * ``name``: not blank - * ``type``: one of ``"text"``, ``"string"``, ``"number"``, ``"boolean"`` -* ``default_analyzer``: Nouveau analyzer to use, defaults to ``"keyword"`` -* ``default_field``: boolean or object of ``enabled`` and ``analyzer`` -* ``partial_filter_selector``: A :ref:`selector<find/selectors>`, causing this +A Nouveau index definition consists of: + +* **fields**: ``"all_fields"`` or list of objects: + * **name** (`string`): not blank + * **type** (`string`): one of ``"text"``, ``"string"``, ``"number"``, ``"boolean"`` +* **default_analyzer** (`string`): Nouveau analyzer to use, defaults to ``"keyword"`` +* **default_field**: boolean or object of ``enabled`` and ``analyzer`` +* **partial_filter_selector** (`object`): A :ref:`selector<find/selectors>`, causing this to be a :ref:`partial index<find/partial_indexes>` -* ``selector``: A :ref:`selector<find/selectors>` +* **selector** (`object`): A :ref:`selector<find/selectors>` Indexes and Design Documents ----------------------------
