willholley commented on code in PR #5432: URL: https://github.com/apache/couchdb/pull/5432#discussion_r1959548494
########## src/docs/src/ddocs/mango.rst: ########## @@ -0,0 +1,922 @@ +.. 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 ``$`` 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>`. Review Comment: this note on performance applies only to `json` index types only (likely predates support for `text`/`nouveau` indexes) -- 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
