You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2025/03/12 12:06:38 UTC
(couchdb) branch main updated (100ca2ab3 -> 5fd85e9ff)
This is an automated email from the ASF dual-hosted git repository.
jan pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
from 100ca2ab3 dev(CI): Temporary exclude Nouveau tests on Windows (#5472)
new dc75ae7a8 Basic rework
new d0aedc0b0 Update index type to include nouveau
new f6889ae11 Make linter happy
new 92622557c Document mango+nouveau
new 0c574afe9 Fix up typos and linting
new f090064dc Don't call the syntax mango
new 6c0b0d2a9 An editing passing, and making use of h3
new 637d7efb4 Rework the index documentation, bring more of it into the prose
new 8e6268d8d Fix syntax
new 9bf304bbd Do an editing pass
new d96e1098c Fix lint
new 42618dfe2 Update src/docs/src/ddocs/mango.rst
new f26e5f7b3 Update src/docs/src/ddocs/mango.rst
new 23b37f601 Remove the mention of _foo fields.
new ce216a2c1 Some edits from @janl
new 0fc466bdb Fix docs warnings
new 5fd85e9ff Actually fix warnings
The 17 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/docs/src/api/database/find.rst | 766 +------------------------------
src/docs/src/ddocs/index.rst | 3 +-
src/docs/src/ddocs/mango.rst | 894 +++++++++++++++++++++++++++++++++++++
src/docs/src/ddocs/nouveau.rst | 2 +
src/docs/src/ddocs/search.rst | 2 +
5 files changed, 908 insertions(+), 759 deletions(-)
create mode 100644 src/docs/src/ddocs/mango.rst
(couchdb) 03/17: Make linter happy
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit f6889ae11f7f0d27ab57a5ccda7f0126e95cc45b
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Feb 15 12:08:56 2025 -0500
Make linter happy
---
src/docs/src/api/database/find.rst | 1 -
src/docs/src/ddocs/mango.rst | 10 +++++-----
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index 7e5773622..0564df2f6 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -166,7 +166,6 @@ Example response when finding documents using an index:
}
}
-
.. _find/sort:
Sort Syntax
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index eb894aaaa..b80b3d46a 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -50,7 +50,6 @@ of function or result.
* Field names starting with ``$`` cannot be queried ("Invalid operator: $")
* Fields at the root of the document starting with ``_`` cannot be queried ("Bad special document member: _")
-
.. _find/selectorbasics:
Selector Basics
@@ -690,14 +689,15 @@ 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.
-
Indexes
=======
-Indexes are like indexes in most other database systems: they spend a little extra space to improve the performance of queries.
-
-They primarily consist of a list of fields to index, but can also contain a :ref:`selector <find/selector>` to create a :ref:`partial index <find/partial_index>`.
+Indexes are like indexes in most other database systems: they spend a little
+extra space to improve the performance of queries.
+They primarily consist of a list of fields to index, but can also contain a
+:ref:`selector <find/selector>` to create a
+:ref:`partial index <find/partial_index>`.
.. note::
Mango indexes have a type, currently ``json``, ``text``, ``nouveau``. This
(couchdb) 01/17: Basic rework
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit dc75ae7a846c727849f7079bd988c168631584ef
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Feb 15 11:53:09 2025 -0500
Basic rework
---
src/docs/src/api/database/find.rst | 731 ----------------------------------
src/docs/src/ddocs/index.rst | 1 +
src/docs/src/ddocs/mango.rst | 793 +++++++++++++++++++++++++++++++++++++
3 files changed, 794 insertions(+), 731 deletions(-)
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index a4f54e2e7..9d39f50fe 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -166,657 +166,6 @@ Example response when finding documents using an index:
}
}
-.. _find/selectors:
-
-Selector Syntax
-===============
-
-Selectors are expressed as a JSON object describing documents of interest.
-Within this structure, you can apply conditional logic using specially named
-fields.
-
-Whilst selectors have some similarities with MongoDB query documents, these
-arise from a similarity of purpose and do not necessarily extend to commonality
-of function or result.
-
-.. _find/selectorbasics:
-
-Selector Basics
----------------
-
-Elementary selector syntax requires you to specify one or more fields, and the
-corresponding values required for those fields. This selector matches all
-documents whose ``"director"`` field has the value ``"Lars von Trier"``.
-
-.. code-block:: javascript
-
- {
- "director": "Lars von Trier"
- }
-
-A simple selector, inspecting specific fields:
-
-.. code-block:: javascript
-
- "selector": {
- "title": "Live And Let Die"
- },
- "fields": [
- "title",
- "cast"
- ]
-
-You can create more complex selector expressions by combining operators.
-For best performance, it is best to combine 'combination' or
-'array logical' operators, such as ``$regex``, with an operator
-that defines a contiguous range of keys such as ``$eq``,
-``$gt``, ``$gte``, ``$lt``, ``$lte``, and ``$beginsWith``
-(but not ``$ne``). For more information about creating complex
-selector expressions, see :ref:`creating selector expressions
-<find/expressions>`.
-
-.. _find/twofields:
-
-Selector with 2 fields
-----------------------
-
-This selector matches any document with a name field containing ``"Paul"``,
-and that also has a location field with the value ``"Boston"``.
-
-.. code-block:: javascript
-
- {
- "name": "Paul",
- "location": "Boston"
- }
-
-.. _find/subfields:
-
-Subfields
----------
-
-A more complex selector enables you to specify the values for field of nested
-objects, or subfields. For example, you might use a standard JSON structure for
-specifying a field and subfield.
-
-Example of a field and subfield selector, using a standard JSON structure:
-
-.. code-block:: javascript
-
- {
- "imdb": {
- "rating": 8
- }
- }
-
-An abbreviated equivalent uses a dot notation to combine the field and subfield
-names into a single name.
-
-.. code-block:: javascript
-
- {
- "imdb.rating": 8
- }
-
-.. _find/operators:
-
-Operators
----------
-
-Operators are identified by the use of a dollar sign (``$``) prefix in the name
-field.
-
-There are two core types of operators in the selector syntax:
-
-- Combination operators
-- Condition operators
-
-In general, combination operators are applied at the topmost level of selection.
-They are used to combine conditions, or to create combinations of conditions,
-into one selector.
-
-Every explicit operator has the form:
-
-.. code-block:: javascript
-
- {
- "$operator": argument
- }
-
-A selector without an explicit operator is considered to have an implicit
-operator. The exact implicit operator is determined by the structure of the
-selector expression.
-
-.. _find/implicit_operators:
-
-Implicit Operators
-------------------
-
-There are two implicit operators:
-
-- Equality
-- And
-
-In a selector, any field containing a JSON value, but that has no operators in
-it, is considered to be an equality condition. The implicit equality test
-applies also for fields and subfields.
-
-Any JSON object that is not the argument to a condition operator is an implicit
-``$and`` operator on each field.
-
-In the below example, we use an operator to match any document, where the
-``"year"`` field has a value greater than ``2010``:
-
-.. code-block:: javascript
-
- {
- "year": {
- "$gt": 2010
- }
- }
-
-In this next example, there must be a field ``"director"`` in a matching
-document, and the field must have a value exactly equal to ``"Lars von Trier"``.
-
-.. code-block:: javascript
-
- {
- "director": "Lars von Trier"
- }
-
-You can also make the equality operator explicit.
-
-.. code-block:: javascript
-
- {
- "director": {
- "$eq": "Lars von Trier"
- }
- }
-
-In the next example using subfields, the required field ``"imdb"`` in a matching
-document must also have a subfield ``"rating"`` and the subfield must have a
-value equal to ``8``.
-
-Example of implicit operator applied to a subfield test:
-
-.. code-block:: javascript
-
- {
- "imdb": {
- "rating": 8
- }
- }
-
-Again, you can make the equality operator explicit.
-
-.. code-block:: javascript
-
- {
- "imdb": {
- "rating": { "$eq": 8 }
- }
- }
-
-An example of the ``$eq`` operator used with full text indexing:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "year": {
- "$eq": 2001
- }
- },
- "sort": [
- "title:string"
- ],
- "fields": [
- "title"
- ]
- }
-
-An example of the ``$eq`` operator used with database indexed on the field ``"year"``:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "year": {
- "$eq": 2001
- }
- },
- "sort": [
- "year"
- ],
- "fields": [
- "year"
- ]
- }
-
-In this example, the field ``"director"`` must be present and contain the value
-``"Lars von Trier"`` and the field ``"year"`` must exist and have the value
-``2003``.
-
-.. code-block:: javascript
-
- {
- "director": "Lars von Trier",
- "year": 2003
- }
-
-You can make both the ``$and`` operator and the equality operator explicit.
-
-Example of using explicit ``$and`` and ``$eq`` operators:
-
-.. code-block:: javascript
-
- {
- "$and": [
- {
- "director": {
- "$eq": "Lars von Trier"
- }
- },
- {
- "year": {
- "$eq": 2003
- }
- }
- ]
- }
-
-.. _find/explicit_operators:
-
-Explicit Operators
-------------------
-
-All operators, apart from 'Equality' and 'And', must be stated explicitly.
-
-.. _find/combination_operators:
-
-Combination Operators
----------------------
-
-Combination operators are used to combine selectors. In addition to the common
-boolean operators found in most programming languages, there are three
-combination operators (``$all``, ``$elemMatch``, and ``$allMatch``) that help
-you work with JSON arrays and one that works with JSON maps (``$keyMapMatch``).
-
-A combination operator takes a single argument. The argument is either another
-selector, or an array of selectors.
-
-The list of combination operators:
-
-+------------------+----------+--------------------------------------------------+
-| Operator | Argument | Purpose |
-+==================+==========+==================================================+
-| ``$and`` | Array | Matches if all the selectors in the array match. |
-+------------------+----------+--------------------------------------------------+
-| ``$or`` | Array | Matches if any of the selectors in the array |
-| | | match. All selectors must use the same index. |
-+------------------+----------+--------------------------------------------------+
-| ``$not`` | Selector | Matches if the given selector does not match. |
-+------------------+----------+--------------------------------------------------+
-| ``$nor`` | Array | Matches if none of the selectors in the array |
-| | | match. |
-+------------------+----------+--------------------------------------------------+
-| ``$all`` | Array | Matches an array value if it contains all the |
-| | | elements of the argument array. |
-+------------------+----------+--------------------------------------------------+
-| ``$elemMatch`` | Selector | Matches and returns all documents that contain an|
-| | | array field with at least one element that |
-| | | matches all the specified query criteria. |
-+------------------+----------+--------------------------------------------------+
-| ``$allMatch`` | Selector | Matches and returns all documents that contain an|
-| | | array field with all its elements matching all |
-| | | the specified query criteria. |
-+------------------+----------+--------------------------------------------------+
-| ``$keyMapMatch`` | Selector | Matches and returns all documents that contain a |
-| | | map that contains at least one key that matches |
-| | | all the specified query criteria. |
-+------------------+----------+--------------------------------------------------+
-
-.. _find/and:
-
-**The** ``$and`` **operator**
-
-``$and`` operator used with two fields:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "$and": [
- {
- "title": "Total Recall"
- },
- {
- "year": {
- "$in": [1984, 1991]
- }
- }
- ]
- },
- "fields": [
- "year",
- "title",
- "cast"
- ]
- }
-
-The ``$and`` operator matches if all the selectors in the array match. Below is
-an example using the primary index (``_all_docs``):
-
-.. code-block:: javascript
-
- {
- "$and": [
- {
- "_id": { "$gt": null }
- },
- {
- "year": {
- "$in": [2014, 2015]
- }
- }
- ]
- }
-
-.. _find/or:
-
-**The** ``$or`` **operator**
-
-The ``$or`` operator matches if any of the selectors in the array match. Below
-is an example used with an index on the field ``"year"``:
-
-.. code-block:: javascript
-
- {
- "year": 1977,
- "$or": [
- { "director": "George Lucas" },
- { "director": "Steven Spielberg" }
- ]
- }
-
-.. _find/not:
-
-**The** ``$not`` **operator**
-
-The ``$not`` operator matches if the given selector does not match. Below is an
-example used with an index on the field ``"year"``:
-
-.. code-block:: javascript
-
- {
- "year": {
- "$gte": 1900,
- "$lte": 1903
- },
- "$not": {
- "year": 1901
- }
- }
-
-.. _find/nor:
-
-**The** ``$nor`` **operator**
-
-The ``$nor`` operator matches if the given selector does not match. Below is an
-example used with an index on the field ``"year"``:
-
-.. code-block:: javascript
-
- {
- "year": {
- "$gte": 1900.
- "$lte": 1910
- },
- "$nor": [
- { "year": 1901 },
- { "year": 1905 },
- { "year": 1907 }
- ]
- }
-
-.. _find/all:
-
-**The** ``$all`` **operator**
-
-The ``$all`` operator matches an array value if it contains all the elements of
-the argument array. Below is an example used with the primary index
-(``_all_docs``):
-
-.. code-block:: javascript
-
- {
- "_id": {
- "$gt": null
- },
- "genre": {
- "$all": ["Comedy","Short"]
- }
- }
-
-.. _find/elemmatch:
-
-**The** ``$elemMatch`` **operator**
-
-The ``$elemMatch`` operator matches and returns all documents that contain an
-array field with at least one element matching the supplied query criteria.
-Below is an example used with the primary index (``_all_docs``):
-
-.. code-block:: javascript
-
- {
- "_id": { "$gt": null },
- "genre": {
- "$elemMatch": {
- "$eq": "Horror"
- }
- }
- }
-
-.. _find/allmatch:
-
-**The** ``$allMatch`` **operator**
-
-The ``$allMatch`` operator matches and returns all documents that contain an
-array field with all its elements matching the supplied query criteria. Below
-is an example used with the primary index (``_all_docs``):
-
-.. code-block:: javascript
-
- {
- "_id": { "$gt": null },
- "genre": {
- "$allMatch": {
- "$eq": "Horror"
- }
- }
- }
-
-.. _find/keymapmatch:
-
-**The** ``$keyMapMatch`` **operator**
-
-The ``$keyMapMatch`` operator matches and returns all documents that contain a
-map that contains at least one key that matches all the specified query criteria.
-Below is an example used with the primary index (``_all_docs``):
-
-.. code-block:: javascript
-
- {
- "_id": { "$gt": null },
- "cameras": {
- "$keyMapMatch": {
- "$eq": "secondary"
- }
- }
- }
-
-.. _find/condition-operators:
-
-Condition Operators
--------------------
-
-Condition operators are specific to a field, and are used to evaluate the value
-stored in that field. For instance, the basic ``$eq`` operator matches when the
-specified field contains a value that is equal to the supplied argument.
-
-.. note::
- For a condition operator to function correctly, the field **must exist**
- in the document for the selector to match. As an example, ``$ne`` means
- the specified field must exist, and is not equal to the value of the
- argument.
-
-The basic equality and inequality operators common to most programming
-languages are supported. Strict type matching is used.
-
-In addition, some 'meta' condition operators are available. Some condition
-operators accept any valid JSON content as the argument. Other condition
-operators require the argument to be in a specific JSON format.
-
-+---------------+-----------------+-------------+------------------------------------+
-| Operator type | Operator | Argument | Purpose |
-+===============+=================+=============+====================================+
-| (In)equality | ``$lt`` | Any JSON | The field is less than the |
-| | | | argument. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$lte`` | Any JSON | The field is less than or equal to |
-| | | | the argument. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$eq`` | Any JSON | The field is equal to the argument.|
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$ne`` | Any JSON | The field is not equal to the |
-| | | | argument. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$gte`` | Any JSON | The field is greater than or equal |
-| | | | to the argument. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$gt`` | Any JSON | The field is greater than the |
-| | | | argument. |
-+---------------+-----------------+-------------+------------------------------------+
-| Object | ``$exists`` | Boolean | Check whether the field exists or |
-| | | | not, regardless of its value. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$type`` | String | Check the document field's type. |
-| | | | Valid values are ``"null"``, |
-| | | | ``"boolean"``, ``"number"``, |
-| | | | ``"string"``, ``"array"``, and |
-| | | | ``"object"``. |
-+---------------+-----------------+-------------+------------------------------------+
-| Array | ``$in`` | Array of | The document field must exist in |
-| | | JSON values | the list provided. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$nin`` | Array of | The document field not must exist |
-| | | JSON values | in the list provided. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$size`` | Integer | Special condition to match the |
-| | | | length of an array field in a |
-| | | | document. Non-array fields cannot |
-| | | | match this condition. |
-+---------------+-----------------+-------------+------------------------------------+
-| Miscellaneous | ``$mod`` | [Divisor, | Divisor is a non-zero integer, |
-| | | Remainder] | Remainder is any integer. |
-| | | | Non-integer values result in a |
-| | | | 404. Matches documents where |
-| | | | ``field % Divisor == Remainder`` |
-| | | | is true, and only when the |
-| | | | document field is an integer. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$regex`` | String | A regular expression pattern to |
-| | | | match against the document field. |
-| | | | Only matches when the field is a |
-| | | | string value and matches the |
-| | | | supplied regular expression. The |
-| | | | matching algorithms are based on |
-| | | | the Perl Compatible Regular |
-| | | | Expression (PCRE) library. For |
-| | | | more information about what is |
-| | | | implemented, see the |
-| | | | `Erlang Regular Expression |
-| | | | <http://erlang.org/doc |
-| | | | /man/re.html>`_. |
-+---------------+-----------------+-------------+------------------------------------+
-| | ``$beginsWith`` | String | Matches where the document field |
-| | | | begins with the specified prefix |
-| | | | (case-sensitive). If the document |
-| | | | field contains a non-string value, |
-| | | | the document is not matched. |
-+---------------+-----------------+-------------+------------------------------------+
-
-.. warning::
- Regular expressions do not work with indexes, so they should not be used to
- filter large data sets. They can, however, be used to restrict a
- :ref:`partial index <find/partial_indexes>`.
-
-.. _find/expressions:
-
-Creating Selector Expressions
------------------------------
-
-We have seen examples of combining selector expressions, such as :ref:`using
-explicit $and and $eq operators <find/combination_operators>`.
-
-In general, whenever you have an operator that takes an argument, that argument
-can itself be another operator with arguments of its own. This enables us to
-build up more complex selector expressions.
-
-However, only operators that define a contiguous range of values
-such as ``$eq``, ``$gt``, ``$gte``, ``$lt``, ``$lte``,
-and ``$beginsWith`` (but not ``$ne``) can be used as the basis
-of a query that can make efficient use of a ``json`` index. You should
-include at least one of these in a selector, or consider using
-a ``text`` index if greater flexibility is required.
-
-For example, if you try to perform a query that attempts to match all documents
-that have a field called `afieldname` containing a value that begins with the
-letter `A`, this will trigger a warning because no index could be used and
-the database performs a full scan of the primary index:
-
- **Request**
-
- .. code-block:: http
-
- POST /movies/_find HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 112
- Host: localhost:5984
-
- {
- "selector": {
- "afieldname": {"$regex": "^A"}
- }
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Thu, 01 Sep 2016 17:25:51 GMT
- Server: CouchDB (Erlang OTP)
- Transfer-Encoding: chunked
-
- {
- "warning":"no matching index found, create an index to optimize query time",
- "docs":[
- ]
- }
-
-.. warning::
- It is always recommended that you create an appropriate index when deploying
- in production.
-
-Most selector expressions work exactly as you would expect for the given
-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.
.. _find/sort:
@@ -1104,86 +453,6 @@ Example index creation using all available query parameters:
By default, a JSON index will include all documents that have the indexed fields
present, including those which have ``null`` values.
-.. _find/partial_indexes:
-
-Partial Indexes
-===============
-
-Partial indexes allow documents to be filtered at indexing time, potentially
-offering significant performance improvements for query selectors that do not
-map cleanly to a range query on an index.
-
-Let's look at an example query:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "status": {
- "$ne": "archived"
- },
- "type": "user"
- }
- }
-
-Without a partial index, this requires a full index scan to find all the
-documents of ``"type":"user"`` that do not have a status of ``"archived"``.
-This is because a normal index can only be used to match contiguous rows,
-and the ``"$ne"`` operator cannot guarantee that.
-
-To improve response times, we can create an index which excludes documents
-where ``"status": { "$ne": "archived" }`` at index time using the
-``"partial_filter_selector"`` field:
-
-.. code-block:: http
-
- POST /db/_index HTTP/1.1
- Content-Type: application/json
- Content-Length: 144
- Host: localhost:5984
-
- {
- "index": {
- "partial_filter_selector": {
- "status": {
- "$ne": "archived"
- }
- },
- "fields": ["type"]
- },
- "ddoc" : "type-not-archived",
- "type" : "json"
- }
-
-Partial indexes are not currently used by the query planner unless specified
-by a ``"use_index"`` field, so we need to modify the original query:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "status": {
- "$ne": "archived"
- },
- "type": "user"
- },
- "use_index": "type-not-archived"
- }
-
-Technically, we do not need to include the filter on the ``"status"`` field
-in the query selector - the partial index ensures this is always true -
-but including it makes the intent of the selector clearer and will make
-it easier to take advantage of future improvements to query planning
-(e.g. automatic selection of partial indexes).
-
-.. note::
- An index with fields is only used, when the selector includes
- all of the fields indexed. For instance, if an index contains ``["a". "b"]``
- but the selector only requires field ``["a"]`` to exist in the matching
- documents, the index would not be valid for the query. All indexes,
- however, can be treated as if they include the special fields ``_id`` and
- ``_rev``. They **never** need to be specified in the query selector.
-
.. _api/db/find/index-get:
.. http:get:: /{db}/_index
diff --git a/src/docs/src/ddocs/index.rst b/src/docs/src/ddocs/index.rst
index 8c8a5449b..975284860 100644
--- a/src/docs/src/ddocs/index.rst
+++ b/src/docs/src/ddocs/index.rst
@@ -26,6 +26,7 @@ replications.
ddocs
views/index
+ mango
search
nouveau
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
new file mode 100644
index 000000000..7c54ff94b
--- /dev/null
+++ b/src/docs/src/ddocs/mango.rst
@@ -0,0 +1,793 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+=============
+Mango Queries
+=============
+
+In addition to :ref:`map/reduce views <viewfun>`, CouchDB supports a expressive
+query syntax called Mango.
+
+The mango system consists of two major concepts:
+
+* Selectors, which are the queries, and are passed to the mango endpoints
+* Indexes, which are a specialization of design docs used in mango queries
+
+There are a few important endpoints for interacting with these concepts:
+
+* :http:post:`/{db}/_find`, which executes a query
+* :http:post:`/{db}/_explain`, which describes the execution of a query
+* :http:get:`/{db}/_index` and :http:post:`/{db}/_index`, which manage indexes
+
+.. _find/selectors:
+
+Selectors
+=========
+
+Selectors are expressed as a JSON object describing documents of interest.
+Within this structure, you can apply conditional logic using specially named
+fields.
+
+Whilst selectors have some similarities with MongoDB query documents, these
+arise from a similarity of purpose and do not necessarily extend to commonality
+of function or result.
+
+.. warning::
+
+ While CouchDB will happily store just about anything JSON, the mango system
+ has limitations about what it can work with:
+
+ * Empty field names (``""``) cannot be queried ("One or more conditions is missing a field name.")
+ * Field names starting with ``$`` cannot be queried ("Invalid operator: $")
+ * Fields at the root of the document starting with ``_`` cannot be queried ("Bad special document member: _")
+
+
+.. _find/selectorbasics:
+
+Selector Basics
+---------------
+
+Elementary selector syntax requires you to specify one or more fields, and the
+corresponding values required for those fields. This selector matches all
+documents whose ``"director"`` field has the value ``"Lars von Trier"``.
+
+.. code-block:: javascript
+
+ {
+ "director": "Lars von Trier"
+ }
+
+A simple selector, inspecting specific fields:
+
+.. code-block:: javascript
+
+ "selector": {
+ "title": "Live And Let Die"
+ },
+ "fields": [
+ "title",
+ "cast"
+ ]
+
+You can create more complex selector expressions by combining operators.
+For best performance, it is best to combine 'combination' or
+'array logical' operators, such as ``$regex``, with an operator
+that defines a contiguous range of keys such as ``$eq``,
+``$gt``, ``$gte``, ``$lt``, ``$lte``, and ``$beginsWith``
+(but not ``$ne``). For more information about creating complex
+selector expressions, see :ref:`creating selector expressions
+<find/expressions>`.
+
+.. _find/twofields:
+
+Selector with 2 fields
+----------------------
+
+This selector matches any document with a name field containing ``"Paul"``,
+and that also has a location field with the value ``"Boston"``.
+
+.. code-block:: javascript
+
+ {
+ "name": "Paul",
+ "location": "Boston"
+ }
+
+.. _find/subfields:
+
+Subfields
+---------
+
+A more complex selector enables you to specify the values for field of nested
+objects, or subfields. For example, you might use a standard JSON structure for
+specifying a field and subfield.
+
+Example of a field and subfield selector, using a standard JSON structure:
+
+.. code-block:: javascript
+
+ {
+ "imdb": {
+ "rating": 8
+ }
+ }
+
+An abbreviated equivalent uses a dot notation to combine the field and subfield
+names into a single name.
+
+.. code-block:: javascript
+
+ {
+ "imdb.rating": 8
+ }
+
+.. _find/operators:
+
+Operators
+---------
+
+Operators are identified by the use of a dollar sign (``$``) prefix in the name
+field.
+
+There are two core types of operators in the selector syntax:
+
+- Combination operators
+- Condition operators
+
+In general, combination operators are applied at the topmost level of selection.
+They are used to combine conditions, or to create combinations of conditions,
+into one selector.
+
+Every explicit operator has the form:
+
+.. code-block:: javascript
+
+ {
+ "$operator": argument
+ }
+
+A selector without an explicit operator is considered to have an implicit
+operator. The exact implicit operator is determined by the structure of the
+selector expression.
+
+.. _find/implicit_operators:
+
+Implicit Operators
+------------------
+
+There are two implicit operators:
+
+- Equality
+- And
+
+In a selector, any field containing a JSON value, but that has no operators in
+it, is considered to be an equality condition. The implicit equality test
+applies also for fields and subfields.
+
+Any JSON object that is not the argument to a condition operator is an implicit
+``$and`` operator on each field.
+
+In the below example, we use an operator to match any document, where the
+``"year"`` field has a value greater than ``2010``:
+
+.. code-block:: javascript
+
+ {
+ "year": {
+ "$gt": 2010
+ }
+ }
+
+In this next example, there must be a field ``"director"`` in a matching
+document, and the field must have a value exactly equal to ``"Lars von Trier"``.
+
+.. code-block:: javascript
+
+ {
+ "director": "Lars von Trier"
+ }
+
+You can also make the equality operator explicit.
+
+.. code-block:: javascript
+
+ {
+ "director": {
+ "$eq": "Lars von Trier"
+ }
+ }
+
+In the next example using subfields, the required field ``"imdb"`` in a matching
+document must also have a subfield ``"rating"`` and the subfield must have a
+value equal to ``8``.
+
+Example of implicit operator applied to a subfield test:
+
+.. code-block:: javascript
+
+ {
+ "imdb": {
+ "rating": 8
+ }
+ }
+
+Again, you can make the equality operator explicit.
+
+.. code-block:: javascript
+
+ {
+ "imdb": {
+ "rating": { "$eq": 8 }
+ }
+ }
+
+An example of the ``$eq`` operator used with full text indexing:
+
+.. code-block:: javascript
+
+ {
+ "selector": {
+ "year": {
+ "$eq": 2001
+ }
+ },
+ "sort": [
+ "title:string"
+ ],
+ "fields": [
+ "title"
+ ]
+ }
+
+An example of the ``$eq`` operator used with database indexed on the field ``"year"``:
+
+.. code-block:: javascript
+
+ {
+ "selector": {
+ "year": {
+ "$eq": 2001
+ }
+ },
+ "sort": [
+ "year"
+ ],
+ "fields": [
+ "year"
+ ]
+ }
+
+In this example, the field ``"director"`` must be present and contain the value
+``"Lars von Trier"`` and the field ``"year"`` must exist and have the value
+``2003``.
+
+.. code-block:: javascript
+
+ {
+ "director": "Lars von Trier",
+ "year": 2003
+ }
+
+You can make both the ``$and`` operator and the equality operator explicit.
+
+Example of using explicit ``$and`` and ``$eq`` operators:
+
+.. code-block:: javascript
+
+ {
+ "$and": [
+ {
+ "director": {
+ "$eq": "Lars von Trier"
+ }
+ },
+ {
+ "year": {
+ "$eq": 2003
+ }
+ }
+ ]
+ }
+
+.. _find/explicit_operators:
+
+Explicit Operators
+------------------
+
+All operators, apart from 'Equality' and 'And', must be stated explicitly.
+
+.. _find/combination_operators:
+
+Combination Operators
+---------------------
+
+Combination operators are used to combine selectors. In addition to the common
+boolean operators found in most programming languages, there are three
+combination operators (``$all``, ``$elemMatch``, and ``$allMatch``) that help
+you work with JSON arrays and one that works with JSON maps (``$keyMapMatch``).
+
+A combination operator takes a single argument. The argument is either another
+selector, or an array of selectors.
+
+The list of combination operators:
+
++------------------+----------+--------------------------------------------------+
+| Operator | Argument | Purpose |
++==================+==========+==================================================+
+| ``$and`` | Array | Matches if all the selectors in the array match. |
++------------------+----------+--------------------------------------------------+
+| ``$or`` | Array | Matches if any of the selectors in the array |
+| | | match. All selectors must use the same index. |
++------------------+----------+--------------------------------------------------+
+| ``$not`` | Selector | Matches if the given selector does not match. |
++------------------+----------+--------------------------------------------------+
+| ``$nor`` | Array | Matches if none of the selectors in the array |
+| | | match. |
++------------------+----------+--------------------------------------------------+
+| ``$all`` | Array | Matches an array value if it contains all the |
+| | | elements of the argument array. |
++------------------+----------+--------------------------------------------------+
+| ``$elemMatch`` | Selector | Matches and returns all documents that contain an|
+| | | array field with at least one element that |
+| | | matches all the specified query criteria. |
++------------------+----------+--------------------------------------------------+
+| ``$allMatch`` | Selector | Matches and returns all documents that contain an|
+| | | array field with all its elements matching all |
+| | | the specified query criteria. |
++------------------+----------+--------------------------------------------------+
+| ``$keyMapMatch`` | Selector | Matches and returns all documents that contain a |
+| | | map that contains at least one key that matches |
+| | | all the specified query criteria. |
++------------------+----------+--------------------------------------------------+
+
+.. _find/and:
+
+**The** ``$and`` **operator**
+
+``$and`` operator used with two fields:
+
+.. code-block:: javascript
+
+ {
+ "selector": {
+ "$and": [
+ {
+ "title": "Total Recall"
+ },
+ {
+ "year": {
+ "$in": [1984, 1991]
+ }
+ }
+ ]
+ },
+ "fields": [
+ "year",
+ "title",
+ "cast"
+ ]
+ }
+
+The ``$and`` operator matches if all the selectors in the array match. Below is
+an example using the primary index (``_all_docs``):
+
+.. code-block:: javascript
+
+ {
+ "$and": [
+ {
+ "_id": { "$gt": null }
+ },
+ {
+ "year": {
+ "$in": [2014, 2015]
+ }
+ }
+ ]
+ }
+
+.. _find/or:
+
+**The** ``$or`` **operator**
+
+The ``$or`` operator matches if any of the selectors in the array match. Below
+is an example used with an index on the field ``"year"``:
+
+.. code-block:: javascript
+
+ {
+ "year": 1977,
+ "$or": [
+ { "director": "George Lucas" },
+ { "director": "Steven Spielberg" }
+ ]
+ }
+
+.. _find/not:
+
+**The** ``$not`` **operator**
+
+The ``$not`` operator matches if the given selector does not match. Below is an
+example used with an index on the field ``"year"``:
+
+.. code-block:: javascript
+
+ {
+ "year": {
+ "$gte": 1900,
+ "$lte": 1903
+ },
+ "$not": {
+ "year": 1901
+ }
+ }
+
+.. _find/nor:
+
+**The** ``$nor`` **operator**
+
+The ``$nor`` operator matches if the given selector does not match. Below is an
+example used with an index on the field ``"year"``:
+
+.. code-block:: javascript
+
+ {
+ "year": {
+ "$gte": 1900.
+ "$lte": 1910
+ },
+ "$nor": [
+ { "year": 1901 },
+ { "year": 1905 },
+ { "year": 1907 }
+ ]
+ }
+
+.. _find/all:
+
+**The** ``$all`` **operator**
+
+The ``$all`` operator matches an array value if it contains all the elements of
+the argument array. Below is an example used with the primary index
+(``_all_docs``):
+
+.. code-block:: javascript
+
+ {
+ "_id": {
+ "$gt": null
+ },
+ "genre": {
+ "$all": ["Comedy","Short"]
+ }
+ }
+
+.. _find/elemmatch:
+
+**The** ``$elemMatch`` **operator**
+
+The ``$elemMatch`` operator matches and returns all documents that contain an
+array field with at least one element matching the supplied query criteria.
+Below is an example used with the primary index (``_all_docs``):
+
+.. code-block:: javascript
+
+ {
+ "_id": { "$gt": null },
+ "genre": {
+ "$elemMatch": {
+ "$eq": "Horror"
+ }
+ }
+ }
+
+.. _find/allmatch:
+
+**The** ``$allMatch`` **operator**
+
+The ``$allMatch`` operator matches and returns all documents that contain an
+array field with all its elements matching the supplied query criteria. Below
+is an example used with the primary index (``_all_docs``):
+
+.. code-block:: javascript
+
+ {
+ "_id": { "$gt": null },
+ "genre": {
+ "$allMatch": {
+ "$eq": "Horror"
+ }
+ }
+ }
+
+.. _find/keymapmatch:
+
+**The** ``$keyMapMatch`` **operator**
+
+The ``$keyMapMatch`` operator matches and returns all documents that contain a
+map that contains at least one key that matches all the specified query criteria.
+Below is an example used with the primary index (``_all_docs``):
+
+.. code-block:: javascript
+
+ {
+ "_id": { "$gt": null },
+ "cameras": {
+ "$keyMapMatch": {
+ "$eq": "secondary"
+ }
+ }
+ }
+
+.. _find/condition-operators:
+
+Condition Operators
+-------------------
+
+Condition operators are specific to a field, and are used to evaluate the value
+stored in that field. For instance, the basic ``$eq`` operator matches when the
+specified field contains a value that is equal to the supplied argument.
+
+.. note::
+ For a condition operator to function correctly, the field **must exist**
+ in the document for the selector to match. As an example, ``$ne`` means
+ the specified field must exist, and is not equal to the value of the
+ argument.
+
+The basic equality and inequality operators common to most programming
+languages are supported. Strict type matching is used.
+
+In addition, some 'meta' condition operators are available. Some condition
+operators accept any valid JSON content as the argument. Other condition
+operators require the argument to be in a specific JSON format.
+
++---------------+-----------------+-------------+------------------------------------+
+| Operator type | Operator | Argument | Purpose |
++===============+=================+=============+====================================+
+| (In)equality | ``$lt`` | Any JSON | The field is less than the |
+| | | | argument. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$lte`` | Any JSON | The field is less than or equal to |
+| | | | the argument. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$eq`` | Any JSON | The field is equal to the argument.|
++---------------+-----------------+-------------+------------------------------------+
+| | ``$ne`` | Any JSON | The field is not equal to the |
+| | | | argument. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$gte`` | Any JSON | The field is greater than or equal |
+| | | | to the argument. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$gt`` | Any JSON | The field is greater than the |
+| | | | argument. |
++---------------+-----------------+-------------+------------------------------------+
+| Object | ``$exists`` | Boolean | Check whether the field exists or |
+| | | | not, regardless of its value. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$type`` | String | Check the document field's type. |
+| | | | Valid values are ``"null"``, |
+| | | | ``"boolean"``, ``"number"``, |
+| | | | ``"string"``, ``"array"``, and |
+| | | | ``"object"``. |
++---------------+-----------------+-------------+------------------------------------+
+| Array | ``$in`` | Array of | The document field must exist in |
+| | | JSON values | the list provided. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$nin`` | Array of | The document field not must exist |
+| | | JSON values | in the list provided. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$size`` | Integer | Special condition to match the |
+| | | | length of an array field in a |
+| | | | document. Non-array fields cannot |
+| | | | match this condition. |
++---------------+-----------------+-------------+------------------------------------+
+| Miscellaneous | ``$mod`` | [Divisor, | Divisor is a non-zero integer, |
+| | | Remainder] | Remainder is any integer. |
+| | | | Non-integer values result in a |
+| | | | 404. Matches documents where |
+| | | | ``field % Divisor == Remainder`` |
+| | | | is true, and only when the |
+| | | | document field is an integer. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$regex`` | String | A regular expression pattern to |
+| | | | match against the document field. |
+| | | | Only matches when the field is a |
+| | | | string value and matches the |
+| | | | supplied regular expression. The |
+| | | | matching algorithms are based on |
+| | | | the Perl Compatible Regular |
+| | | | Expression (PCRE) library. For |
+| | | | more information about what is |
+| | | | implemented, see the |
+| | | | `Erlang Regular Expression |
+| | | | <http://erlang.org/doc |
+| | | | /man/re.html>`_. |
++---------------+-----------------+-------------+------------------------------------+
+| | ``$beginsWith`` | String | Matches where the document field |
+| | | | begins with the specified prefix |
+| | | | (case-sensitive). If the document |
+| | | | field contains a non-string value, |
+| | | | the document is not matched. |
++---------------+-----------------+-------------+------------------------------------+
+
+.. warning::
+ Regular expressions do not work with indexes, so they should not be used to
+ filter large data sets. They can, however, be used to restrict a
+ :ref:`partial index <find/partial_indexes>`.
+
+.. _find/expressions:
+
+Creating Selector Expressions
+-----------------------------
+
+We have seen examples of combining selector expressions, such as :ref:`using
+explicit $and and $eq operators <find/combination_operators>`.
+
+In general, whenever you have an operator that takes an argument, that argument
+can itself be another operator with arguments of its own. This enables us to
+build up more complex selector expressions.
+
+However, only operators that define a contiguous range of values
+such as ``$eq``, ``$gt``, ``$gte``, ``$lt``, ``$lte``,
+and ``$beginsWith`` (but not ``$ne``) can be used as the basis
+of a query that can make efficient use of a ``json`` index. You should
+include at least one of these in a selector, or consider using
+a ``text`` index if greater flexibility is required.
+
+For example, if you try to perform a query that attempts to match all documents
+that have a field called `afieldname` containing a value that begins with the
+letter `A`, this will trigger a warning because no index could be used and
+the database performs a full scan of the primary index:
+
+ **Request**
+
+ .. code-block:: http
+
+ POST /movies/_find HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Content-Length: 112
+ Host: localhost:5984
+
+ {
+ "selector": {
+ "afieldname": {"$regex": "^A"}
+ }
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Thu, 01 Sep 2016 17:25:51 GMT
+ Server: CouchDB (Erlang OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "warning":"no matching index found, create an index to optimize query time",
+ "docs":[
+ ]
+ }
+
+.. warning::
+ It is always recommended that you create an appropriate index when deploying
+ in production.
+
+Most selector expressions work exactly as you would expect for the given
+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.
+
+
+Indexes
+=======
+
+Indexes are like indexes in most other database systems: they spend a little extra space to improve the performance of queries.
+
+They primarily consist of a list of fields to index, but can also contain a :ref:`selector <find/selector>` to create a :ref:`partial index <find/partial_index>`.
+
+
+.. note::
+ Mango indexes have a type, currently ``json`` or ``text``. This document
+ covers ``json`` indexes. ``text`` indexes are handled by 3rd-party software.
+
+.. _find/partial_indexes:
+
+Partial Indexes
+---------------
+
+Partial indexes allow documents to be filtered at indexing time, potentially
+offering significant performance improvements for query selectors that do not
+map cleanly to a range query on an index.
+
+Let's look at an example query:
+
+.. code-block:: javascript
+
+ {
+ "selector": {
+ "status": {
+ "$ne": "archived"
+ },
+ "type": "user"
+ }
+ }
+
+Without a partial index, this requires a full index scan to find all the
+documents of ``"type":"user"`` that do not have a status of ``"archived"``.
+This is because a normal index can only be used to match contiguous rows,
+and the ``"$ne"`` operator cannot guarantee that.
+
+To improve response times, we can create an index which excludes documents
+where ``"status": { "$ne": "archived" }`` at index time using the
+``"partial_filter_selector"`` field:
+
+.. code-block:: http
+
+ POST /db/_index HTTP/1.1
+ Content-Type: application/json
+ Content-Length: 144
+ Host: localhost:5984
+
+ {
+ "index": {
+ "partial_filter_selector": {
+ "status": {
+ "$ne": "archived"
+ }
+ },
+ "fields": ["type"]
+ },
+ "ddoc" : "type-not-archived",
+ "type" : "json"
+ }
+
+Partial indexes are not currently used by the query planner unless specified
+by a ``"use_index"`` field, so we need to modify the original query:
+
+.. code-block:: javascript
+
+ {
+ "selector": {
+ "status": {
+ "$ne": "archived"
+ },
+ "type": "user"
+ },
+ "use_index": "type-not-archived"
+ }
+
+Technically, we do not need to include the filter on the ``"status"`` field
+in the query selector - the partial index ensures this is always true -
+but including it makes the intent of the selector clearer and will make
+it easier to take advantage of future improvements to query planning
+(e.g. automatic selection of partial indexes).
+
+.. note::
+ An index with fields is only used, when the selector includes
+ all of the fields indexed. For instance, if an index contains ``["a". "b"]``
+ but the selector only requires field ``["a"]`` to exist in the matching
+ documents, the index would not be valid for the query. All indexes,
+ however, can be treated as if they include the special fields ``_id`` and
+ ``_rev``. They **never** need to be specified in the query selector.
+
+Indexes and Design Documents
+----------------------------
+
+Ultimately, indexes are stored using design documents, using the same view
+systems under the hood. If you go looking, you can find the design documents
+backing mango indexes. However, exactly how mango indexes map to design
+documents is an implementation detail, and users are encouraged to manage their
+indexes using the :ref:`api/db/find/index` family of endpoints.
(couchdb) 15/17: Some edits from @janl
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit ce216a2c1e8b9aebcc5008a061b271c3ce222900
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Fri Mar 7 13:42:15 2025 -0500
Some edits from @janl
---
src/docs/src/ddocs/index.rst | 2 +-
src/docs/src/ddocs/mango.rst | 18 ------------------
2 files changed, 1 insertion(+), 19 deletions(-)
diff --git a/src/docs/src/ddocs/index.rst b/src/docs/src/ddocs/index.rst
index 975284860..d9085011a 100644
--- a/src/docs/src/ddocs/index.rst
+++ b/src/docs/src/ddocs/index.rst
@@ -13,7 +13,7 @@
.. _indexes:
================
-Design Documents
+Querying CouchDB
================
CouchDB supports special documents within databases known as "design
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 2d3013fd7..1bc6e8bbb 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -221,24 +221,6 @@ Again, you can make the equality operator explicit.
}
}
-An example of the ``$eq`` operator used with full text indexing:
-
-.. code-block:: javascript
-
- {
- "selector": {
- "year": {
- "$eq": 2001
- }
- },
- "sort": [
- "title:string"
- ],
- "fields": [
- "title"
- ]
- }
-
An example of the ``$eq`` operator used with database indexed on the field ``"year"``:
.. code-block:: javascript
(couchdb) 07/17: An editing passing, and making use of h3
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 6c0b0d2a94f792b4b17147b34eb163e4c2fe7cc3
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Mon Feb 17 16:19:02 2025 -0500
An editing passing, and making use of h3
---
src/docs/src/ddocs/mango.rst | 37 +++++++++++++++++++++++--------------
1 file changed, 23 insertions(+), 14 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 7d5a12789..93560ab55 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -17,7 +17,7 @@ Mango Queries
In addition to :ref:`map/reduce views <viewfun>`, CouchDB supports an expressive
query system called Mango.
-The mango system consists of two major concepts:
+Mango consists of two major concepts:
* Selectors, which are the queries, and are passed to the mango endpoints
* Indexes, which are a specialization of design docs used in mango queries
@@ -43,8 +43,8 @@ of function or result.
.. warning::
- While CouchDB will happily store just about anything JSON, the mango system
- has limitations about what it can work with:
+ While CouchDB will happily store just about anything JSON, Mango has
+ limitations about what it can work with:
* Empty field names (``""``) cannot be queried ("One or more conditions is
missing a field name.")
@@ -354,7 +354,8 @@ The list of combination operators:
.. _find/and:
-**The** ``$and`` **operator**
+The ``$and`` operator
+~~~~~~~~~~~~~~~~~~~~~
``$and`` operator used with two fields:
@@ -400,7 +401,8 @@ an example using the primary index (``_all_docs``):
.. _find/or:
-**The** ``$or`` **operator**
+The ``$or`` operator
+~~~~~~~~~~~~~~~~~~~~
The ``$or`` operator matches if any of the selectors in the array match. Below
is an example used with an index on the field ``"year"``:
@@ -417,7 +419,8 @@ is an example used with an index on the field ``"year"``:
.. _find/not:
-**The** ``$not`` **operator**
+The ``$not`` operator
+~~~~~~~~~~~~~~~~~~~~~
The ``$not`` operator matches if the given selector does not match. Below is an
example used with an index on the field ``"year"``:
@@ -436,7 +439,8 @@ example used with an index on the field ``"year"``:
.. _find/nor:
-**The** ``$nor`` **operator**
+The ``$nor`` operator
+~~~~~~~~~~~~~~~~~~~~~
The ``$nor`` operator matches if the given selector does not match. Below is an
example used with an index on the field ``"year"``:
@@ -457,7 +461,8 @@ example used with an index on the field ``"year"``:
.. _find/all:
-**The** ``$all`` **operator**
+The ``$all`` operator
+~~~~~~~~~~~~~~~~~~~~~
The ``$all`` operator matches an array value if it contains all the elements of
the argument array. Below is an example used with the primary index
@@ -476,7 +481,8 @@ the argument array. Below is an example used with the primary index
.. _find/elemmatch:
-**The** ``$elemMatch`` **operator**
+The ``$elemMatch`` operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``$elemMatch`` operator matches and returns all documents that contain an
array field with at least one element matching the supplied query criteria.
@@ -495,7 +501,8 @@ Below is an example used with the primary index (``_all_docs``):
.. _find/allmatch:
-**The** ``$allMatch`` **operator**
+The ``$allMatch`` operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``$allMatch`` operator matches and returns all documents that contain an
array field with all its elements matching the supplied query criteria. Below
@@ -514,7 +521,8 @@ is an example used with the primary index (``_all_docs``):
.. _find/keymapmatch:
-**The** ``$keyMapMatch`` **operator**
+The ``$keyMapMatch`` operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``$keyMapMatch`` operator matches and returns all documents that contain a
map that contains at least one key that matches all the specified query criteria.
@@ -533,7 +541,8 @@ Below is an example used with the primary index (``_all_docs``):
.. _find/text:
-**The** ``$text`` **operator**
+The ``$text`` operator
+~~~~~~~~~~~~~~~~~~~~~~
The ``$text`` operator performs a text search using either a search or nouveau
index. The specifics of the query follow either
@@ -552,7 +561,7 @@ the same syntax).
}
}
-.. note::
+.. warning::
Queries cannot contain more than one ``$text``
@@ -812,7 +821,7 @@ it easier to take advantage of future improvements to query planning
.. note::
An index with fields is only used, when the selector includes
- all of the fields indexed. For instance, if an index contains ``["a". "b"]``
+ all of the fields indexed. For instance, if an index contains ``["a", "b"]``
but the selector only requires field ``["a"]`` to exist in the matching
documents, the index would not be valid for the query. All indexes,
however, can be treated as if they include the special fields ``_id`` and
(couchdb) 16/17: Fix docs warnings
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 0fc466bdbd8fbdc191d8e72da3005fc62e08ac95
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Fri Mar 7 13:52:15 2025 -0500
Fix docs warnings
---
src/docs/src/ddocs/mango.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 1bc6e8bbb..28da32128 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -271,6 +271,7 @@ Example of using explicit ``$and`` and ``$eq`` operators:
]
}
It is entirely up to you whether you use the implicit or explicit form. The implicit form is a little easier to write if you do that by hand. The explicit form is a little easier if you programatically contract your selectors. The end result will be the same.
+
.. _find/explicit_operators:
Explicit Operators
(couchdb) 09/17: Fix syntax
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 8e6268d8d7b244da09876a9d05380a9bcfb79e1e
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Mon Feb 17 16:57:24 2025 -0500
Fix syntax
---
src/docs/src/ddocs/mango.rst | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 522454c4b..a63d3631c 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -727,7 +727,7 @@ 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
+.. _ddoc/mango/indexes:
Indexes
=======
@@ -902,8 +902,10 @@ Example index:
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"``
+
+ * **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
(couchdb) 11/17: Fix lint
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit d96e1098c9bb3545dcc9bec2659f70df699b63dc
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Wed Feb 19 15:51:50 2025 -0500
Fix lint
---
src/docs/src/ddocs/mango.rst | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index f2be02a2e..0d4fe82fc 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -867,7 +867,11 @@ it easier to take advantage of future improvements to query planning
Text Indexes
------------
-Mango can also interact with the :ref:`Search <ddoc/search>` and :ref:`Nouveau <ddoc/nouveau>` search systems, using the :ref:`$text selector <find/text>` and the appropriate index. These indexes can be queried using either ``$text`` or :http:get:`/{db}/_design/{ddoc}/_search/{index}`/:http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
+Mango can also interact with the :ref:`Search <ddoc/search>` and
+:ref:`Nouveau <ddoc/nouveau>` search systems, using the
+:ref:`$text selector <find/text>` and the appropriate index. These indexes can
+be queried using either ``$text`` or :http:get:`/{db}/_design/{ddoc}/_search/{index}`
+/ :http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
Example index:
@@ -893,7 +897,7 @@ A Text or Nouveau index definition consists of:
* **type** (`string`): one of ``"text"``, ``"string"``, ``"number"``, ``"boolean"``
* **default_analyzer** (`string`): Analyzer to use, defaults to ``"keyword"`` *Optional*
-* **default_field**: Enables the "default field" index, boolean or object of
+* **default_field**: Enables the "default field" index, boolean or object of
``enabled`` and ``analyzer`` *Optional*
* **partial_filter_selector** (`object`): A :ref:`selector<find/selectors>`, causing this
to be a :ref:`partial index<find/partial_indexes>` *Optional*
(couchdb) 13/17: Update src/docs/src/ddocs/mango.rst
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit f26e5f7b3a3f3d21820083c97bcea1fba72191fc
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Mar 1 13:36:07 2025 -0500
Update src/docs/src/ddocs/mango.rst
Co-authored-by: Jan Lehnardt <ja...@apache.org>
---
src/docs/src/ddocs/mango.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 0bd431045..47a45dbe9 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -291,7 +291,7 @@ Example of using explicit ``$and`` and ``$eq`` operators:
}
]
}
-
+It is entirely up to you whether you use the implicit or explicit form. The implicit form is a little easier to write if you do that by hand. The explicit form is a little easier if you programatically contract your selectors. The end result will be the same.
.. _find/explicit_operators:
Explicit Operators
(couchdb) 06/17: Don't call the syntax mango
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit f090064dc29e08da03f8f576bbf1ad9015148131
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Mon Feb 17 15:57:10 2025 -0500
Don't call the syntax mango
---
src/docs/src/ddocs/mango.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 572e0c86e..7d5a12789 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -15,7 +15,7 @@ Mango Queries
=============
In addition to :ref:`map/reduce views <viewfun>`, CouchDB supports an expressive
-query syntax called Mango.
+query system called Mango.
The mango system consists of two major concepts:
(couchdb) 05/17: Fix up typos and linting
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 0c574afe9e40eae858d616f4c5658e2e4c19fa45
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Mon Feb 17 15:51:40 2025 -0500
Fix up typos and linting
---
src/docs/src/api/database/find.rst | 9 ++++-----
src/docs/src/ddocs/mango.rst | 18 +++++++++---------
src/docs/src/ddocs/nouveau.rst | 1 -
3 files changed, 13 insertions(+), 15 deletions(-)
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index 0564df2f6..b6837df6a 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -346,11 +346,10 @@ built using MapReduce Views.
indexes in the same document (similar to views). *Optional*
:query string name: Name of the index. If no name is provided, a name will
be generated automatically. *Optional*
- :query string type: Can be ``"json"``, ``"text"`` (for clouseau), or
- ``"nouveau"``. Defaults to ``"json"``.
- Text and Nouveau indexes are related to those
- features, and are only available if they're installed.
- Geospatial indexes will be supported in the future. *Optional*
+ :query string type: Can be ``"json"``, ``"text"`` (for clouseau), or
+ ``"nouveau"``. Defaults to ``"json"``. Text and Nouveau indexes are
+ related to those features, and are only available if those features are
+ installed. *Optional*
:query boolean partitioned: Determines whether a JSON index is partitioned
or global. The default value of ``partitioned`` is the ``partitioned``
property of the database. To create a global index on a
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 095dd5840..572e0c86e 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -14,7 +14,7 @@
Mango Queries
=============
-In addition to :ref:`map/reduce views <viewfun>`, CouchDB supports a expressive
+In addition to :ref:`map/reduce views <viewfun>`, CouchDB supports an expressive
query syntax called Mango.
The mango system consists of two major concepts:
@@ -49,7 +49,7 @@ of function or result.
* Empty field names (``""``) cannot be queried ("One or more conditions is
missing a field name.")
* Field names starting with ``$`` cannot be queried ("Invalid operator: $")
- * Fields at the root of the document starting with ``_`` cannot be queried
+ * Fields at the root of the document starting with ``_`` cannot be queried
("Bad special document member: _")
.. _find/selectorbasics:
@@ -535,9 +535,9 @@ Below is an example used with the primary index (``_all_docs``):
**The** ``$text`` **operator**
-The ``$text`` operator performs a text search using either a search or nouveau
-index. The specifics of the query follow either
-:ref:`search syntax <ddoc/search/syntax>` or
+The ``$text`` operator performs a text search using either a search or nouveau
+index. The specifics of the query follow either
+:ref:`search syntax <ddoc/search/syntax>` or
:ref:`nouveau syntax <ddoc/nouveau/syntax>` (which both use Lucene and implement
the same syntax).
@@ -825,7 +825,8 @@ Nouveau Indexes
Mango can also interact with the :ref:`Nouveau search system <ddoc/nouveau>`,
using the :ref:`$text selector <find/text>` and Nouveau indexes. These indexes
-can be queried using either ``$text`` or :http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
+can be queried using either ``$text`` or
+:http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
Example index:
@@ -844,15 +845,14 @@ Example index:
}
* ``fields``: ``"all_fields"`` or list of objects:
- * ``name``: not blank
+ * ``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
+* ``partial_filter_selector``: A :ref:`selector<find/selectors>`, causing this
to be a :ref:`partial index<find/partial_indexes>`
* ``selector``: A :ref:`selector<find/selectors>`
-
Indexes and Design Documents
----------------------------
diff --git a/src/docs/src/ddocs/nouveau.rst b/src/docs/src/ddocs/nouveau.rst
index 028c1f979..d091ca2e8 100644
--- a/src/docs/src/ddocs/nouveau.rst
+++ b/src/docs/src/ddocs/nouveau.rst
@@ -504,7 +504,6 @@ field in the JSON object in the request body.
"limit": 3
}
-
.. _ddoc/nouveau/syntax:
Query syntax
(couchdb) 10/17: Do an editing pass
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 9bf304bbd6535bda968070db89fdd5757cb4403c
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Wed Feb 19 15:46:05 2025 -0500
Do an editing pass
---
src/docs/src/ddocs/mango.rst | 49 ++++++++++++++++----------------------------
1 file changed, 18 insertions(+), 31 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index a63d3631c..f2be02a2e 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -47,10 +47,12 @@ of function or result.
limitations about what it can work with:
* Empty field names (``""``) cannot be queried ("One or more conditions is
- missing a field name.")
- * Field names starting with ``$`` cannot be queried ("Invalid operator: $")
+ missing a field name.").
+ * Field names starting with ``$`` must be escaped with ``\`` (eg, ``\$foo``)
+ ("Invalid operator: $").
* Fields at the root of the document starting with ``_`` cannot be queried
- ("Bad special document member: _")
+ ("Bad special document member: _"). Special fields like ``_id`` and
+ ``_rev`` can be queried.
.. _find/selectorbasics:
@@ -79,15 +81,6 @@ A simple selector, inspecting specific fields:
"cast"
]
-You can create more complex selector expressions by combining operators.
-For best performance, it is best to combine 'combination' or
-'array logical' operators, such as ``$regex``, with an operator
-that defines a contiguous range of keys such as ``$eq``,
-``$gt``, ``$gte``, ``$lt``, ``$lte``, and ``$beginsWith``
-(but not ``$ne``). For more information about creating complex
-selector expressions, see :ref:`creating selector expressions
-<find/expressions>`.
-
.. _find/twofields:
Selector with 2 fields
@@ -554,11 +547,7 @@ the same syntax).
{
"_id": { "$gt": null },
- "cameras": {
- "$keyMapMatch": {
- "$eq": "secondary"
- }
- }
+ "$text": "director:George"
}
.. warning::
@@ -743,7 +732,7 @@ They primarily consist of a list of fields to index, but can also contain a
Mango indexes have a type, currently ``json``, ``text``, ``nouveau``. The
majority of this document covers ``json`` indexes. ``text`` and ``nouveau``
are related to the :ref:`ddoc/search` and :ref:`ddoc/nouveau` systems,
- respectively. (See :ref:`ddoc/mango/indexes/nouveau`.)
+ respectively. (See :ref:`ddoc/mango/indexes/text`.)
You will also occasionally find reference to the ``special`` index type.
This represents synthetic indexes produced by CouchDB itself and refers
@@ -873,15 +862,12 @@ it easier to take advantage of future improvements to query planning
however, can be treated as if they include the special fields ``_id`` and
``_rev``. They **never** need to be specified in the query selector.
-.. _ddoc/mango/indexes/nouveau:
+.. _ddoc/mango/indexes/text:
-Nouveau Indexes
----------------
+Text Indexes
+------------
-Mango can also interact with the :ref:`Nouveau search system <ddoc/nouveau>`,
-using the :ref:`$text selector <find/text>` and Nouveau indexes. These indexes
-can be queried using either ``$text`` or
-:http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
+Mango can also interact with the :ref:`Search <ddoc/search>` and :ref:`Nouveau <ddoc/nouveau>` search systems, using the :ref:`$text selector <find/text>` and the appropriate index. These indexes can be queried using either ``$text`` or :http:get:`/{db}/_design/{ddoc}/_search/{index}`/:http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
Example index:
@@ -899,18 +885,19 @@ Example index:
}
}
-A Nouveau index definition consists of:
+A Text or Nouveau index definition consists of:
-* **fields**: ``"all_fields"`` or list of objects:
+* **fields**: The list of fields to index. ``"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``
+* **default_analyzer** (`string`): Analyzer to use, defaults to ``"keyword"`` *Optional*
+* **default_field**: Enables the "default field" index, boolean or object of
+ ``enabled`` and ``analyzer`` *Optional*
* **partial_filter_selector** (`object`): A :ref:`selector<find/selectors>`, causing this
- to be a :ref:`partial index<find/partial_indexes>`
-* **selector** (`object`): A :ref:`selector<find/selectors>`
+ to be a :ref:`partial index<find/partial_indexes>` *Optional*
+* **selector** (`object`): A :ref:`selector<find/selectors>` *Optional*
Indexes and Design Documents
----------------------------
(couchdb) 12/17: Update src/docs/src/ddocs/mango.rst
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 42618dfe2cbe2be9122a613e76f56e880d7667fa
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Mar 1 13:35:47 2025 -0500
Update src/docs/src/ddocs/mango.rst
Co-authored-by: Jan Lehnardt <ja...@apache.org>
---
src/docs/src/ddocs/mango.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 0d4fe82fc..0bd431045 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -20,7 +20,7 @@ query system called Mango.
Mango consists of two major concepts:
* Selectors, which are the queries, and are passed to the mango endpoints
-* Indexes, which are a specialization of design docs used in mango queries
+* Indexes, which are a specialization of :ref:`design docs <ddocs>` used in mango queries
There are a few important endpoints for interacting with these concepts:
(couchdb) 04/17: Document mango+nouveau
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 92622557ce9a032d5e7e8840f18c8a991cb2ec34
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Mon Feb 17 15:39:27 2025 -0500
Document mango+nouveau
---
src/docs/src/ddocs/mango.rst | 83 ++++++++++++++++++++++++++++++++++++++----
src/docs/src/ddocs/nouveau.rst | 3 ++
src/docs/src/ddocs/search.rst | 2 +
3 files changed, 81 insertions(+), 7 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index b80b3d46a..095dd5840 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -46,9 +46,11 @@ of function or result.
While CouchDB will happily store just about anything JSON, the mango system
has limitations about what it can work with:
- * Empty field names (``""``) cannot be queried ("One or more conditions is missing a field name.")
+ * Empty field names (``""``) cannot be queried ("One or more conditions is
+ missing a field name.")
* Field names starting with ``$`` cannot be queried ("Invalid operator: $")
- * Fields at the root of the document starting with ``_`` cannot be queried ("Bad special document member: _")
+ * Fields at the root of the document starting with ``_`` cannot be queried
+ ("Bad special document member: _")
.. _find/selectorbasics:
@@ -347,6 +349,8 @@ The list of combination operators:
| | | map that contains at least one key that matches |
| | | all the specified query criteria. |
+------------------+----------+--------------------------------------------------+
+| ``$text`` | String | Perform a text search |
++------------------+----------+--------------------------------------------------+
.. _find/and:
@@ -527,6 +531,31 @@ Below is an example used with the primary index (``_all_docs``):
}
}
+.. _find/text:
+
+**The** ``$text`` **operator**
+
+The ``$text`` operator performs a text search using either a search or nouveau
+index. The specifics of the query follow either
+:ref:`search syntax <ddoc/search/syntax>` or
+:ref:`nouveau syntax <ddoc/nouveau/syntax>` (which both use Lucene and implement
+the same syntax).
+
+.. code-block:: javascript
+
+ {
+ "_id": { "$gt": null },
+ "cameras": {
+ "$keyMapMatch": {
+ "$eq": "secondary"
+ }
+ }
+ }
+
+.. note::
+
+ Queries cannot contain more than one ``$text``
+
.. _find/condition-operators:
Condition Operators
@@ -696,13 +725,18 @@ Indexes are like indexes in most other database systems: they spend a little
extra space to improve the performance of queries.
They primarily consist of a list of fields to index, but can also contain a
-:ref:`selector <find/selector>` to create a
-:ref:`partial index <find/partial_index>`.
+:ref:`selector <find/selectors>` to create a
+:ref:`partial index <find/partial_indexes>`.
.. note::
- Mango indexes have a type, currently ``json``, ``text``, ``nouveau``. This
- document covers ``json`` indexes. ``text`` and ``nouveau`` are related to
- the :ref:`ddoc/search` and :ref:`ddoc/nouveau` systems, respectively.
+ Mango indexes have a type, currently ``json``, ``text``, ``nouveau``. The
+ majority of this document covers ``json`` indexes. ``text`` and ``nouveau``
+ are related to the :ref:`ddoc/search` and :ref:`ddoc/nouveau` systems,
+ respectively. (See :ref:`ddoc/mango/indexes/nouveau`.)
+
+ You will also occasionally find reference to the ``special`` index type.
+ This represents synthetic indexes produced by CouchDB itself and refers
+ exclusively to ``_all_docs``.
.. _find/partial_indexes:
@@ -784,6 +818,41 @@ it easier to take advantage of future improvements to query planning
however, can be treated as if they include the special fields ``_id`` and
``_rev``. They **never** need to be specified in the query selector.
+.. _ddoc/mango/indexes/nouveau:
+
+Nouveau Indexes
+---------------
+
+Mango can also interact with the :ref:`Nouveau search system <ddoc/nouveau>`,
+using the :ref:`$text selector <find/text>` and Nouveau indexes. These indexes
+can be queried using either ``$text`` or :http:get:`/{db}/_design/{ddoc}/_nouveau/{index}`.
+
+Example index:
+
+.. code-block:: json
+
+ {
+ "type": "nouveau",
+ "index": {
+ "fields": [
+ {"name": "foo", "type": "string"},
+ {"name": "bar", "type": "number"},
+ {"name": "baz", "type": "string"},
+ ],
+ "default_analyzer": "keyword",
+ }
+ }
+
+* ``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
+ to be a :ref:`partial index<find/partial_indexes>`
+* ``selector``: A :ref:`selector<find/selectors>`
+
+
Indexes and Design Documents
----------------------------
diff --git a/src/docs/src/ddocs/nouveau.rst b/src/docs/src/ddocs/nouveau.rst
index 949cd17a2..028c1f979 100644
--- a/src/docs/src/ddocs/nouveau.rst
+++ b/src/docs/src/ddocs/nouveau.rst
@@ -504,6 +504,9 @@ field in the JSON object in the request body.
"limit": 3
}
+
+.. _ddoc/nouveau/syntax:
+
Query syntax
============
diff --git a/src/docs/src/ddocs/search.rst b/src/docs/src/ddocs/search.rst
index 98409f527..ed269a536 100644
--- a/src/docs/src/ddocs/search.rst
+++ b/src/docs/src/ddocs/search.rst
@@ -600,6 +600,8 @@ field in the JSON object in the request body.
"limit": 3
}
+.. _ddoc/search/syntax:
+
Query syntax
============
(couchdb) 14/17: Remove the mention of _foo fields.
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 23b37f60162408c2be464a2bc1815069e4d477e1
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Mar 1 13:55:15 2025 -0500
Remove the mention of _foo fields.
Jan pointed out that these aren't allowed in general.
---
src/docs/src/ddocs/mango.rst | 3 ---
1 file changed, 3 deletions(-)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 47a45dbe9..2d3013fd7 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -50,9 +50,6 @@ of function or result.
missing a field name.").
* Field names starting with ``$`` must be escaped with ``\`` (eg, ``\$foo``)
("Invalid operator: $").
- * Fields at the root of the document starting with ``_`` cannot be queried
- ("Bad special document member: _"). Special fields like ``_id`` and
- ``_rev`` can be queried.
.. _find/selectorbasics:
(couchdb) 08/17: Rework the index documentation, bring more of it into the prose
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 637d7efb4bddc2a25cddd3f2414b9fb99af77dc4
Author: Jamie Bliss <ja...@ivyleav.es>
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
----------------------------
(couchdb) 02/17: Update index type to include nouveau
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit d0aedc0b0fcdce5cbb3af320cdf1722dab4b1293
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Sat Feb 15 12:06:04 2025 -0500
Update index type to include nouveau
---
src/docs/src/api/database/find.rst | 7 +++++--
src/docs/src/ddocs/mango.rst | 5 +++--
2 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index 9d39f50fe..7e5773622 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -347,8 +347,11 @@ built using MapReduce Views.
indexes in the same document (similar to views). *Optional*
:query string name: Name of the index. If no name is provided, a name will
be generated automatically. *Optional*
- :query string type: Can be ``"json"``, ``"text"`` (for clouseau) or
- ``"nouveau"``. Defaults to ``"json"``. *Optional*
+ :query string type: Can be ``"json"``, ``"text"`` (for clouseau), or
+ ``"nouveau"``. Defaults to ``"json"``.
+ Text and Nouveau indexes are related to those
+ features, and are only available if they're installed.
+ Geospatial indexes will be supported in the future. *Optional*
:query boolean partitioned: Determines whether a JSON index is partitioned
or global. The default value of ``partitioned`` is the ``partitioned``
property of the database. To create a global index on a
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 7c54ff94b..eb894aaaa 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -700,8 +700,9 @@ They primarily consist of a list of fields to index, but can also contain a :ref
.. note::
- Mango indexes have a type, currently ``json`` or ``text``. This document
- covers ``json`` indexes. ``text`` indexes are handled by 3rd-party software.
+ Mango indexes have a type, currently ``json``, ``text``, ``nouveau``. This
+ document covers ``json`` indexes. ``text`` and ``nouveau`` are related to
+ the :ref:`ddoc/search` and :ref:`ddoc/nouveau` systems, respectively.
.. _find/partial_indexes:
(couchdb) 17/17: Actually fix warnings
Posted by ja...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
jan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 5fd85e9ffac9bf51e23c83853b5f50ef9d80f414
Author: Jamie Bliss <ja...@ivyleav.es>
AuthorDate: Fri Mar 7 14:01:13 2025 -0500
Actually fix warnings
---
src/docs/src/ddocs/mango.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/docs/src/ddocs/mango.rst b/src/docs/src/ddocs/mango.rst
index 28da32128..dbcb5b1cf 100644
--- a/src/docs/src/ddocs/mango.rst
+++ b/src/docs/src/ddocs/mango.rst
@@ -270,6 +270,7 @@ Example of using explicit ``$and`` and ``$eq`` operators:
}
]
}
+
It is entirely up to you whether you use the implicit or explicit form. The implicit form is a little easier to write if you do that by hand. The explicit form is a little easier if you programatically contract your selectors. The end result will be the same.
.. _find/explicit_operators: