AstraLuma commented on code in PR #5432: URL: https://github.com/apache/couchdb/pull/5432#discussion_r1976472978
########## src/docs/src/ddocs/mango.rst: ########## @@ -0,0 +1,913 @@ +.. 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 an expressive +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 + +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, Mango 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 ``$`` 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: + +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" + ] + +.. _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: Review Comment: I have absolutely no idea how this invokes full text indexing. I traced it back to the original docs repo, looks like it was copied from Cloudant. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@couchdb.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
