From e8a0d021e667f4fcd7f5ebbfb1ef43e26a6d8ee6 Mon Sep 17 00:00:00 2001 From: "U-tellus\\cwestin" Date: Fri, 24 Feb 2012 15:56:52 -0800 Subject: [PATCH] DOCS-134 --- source/applications/aggregation.rst | 81 +++++----- source/reference/aggregation.rst | 230 +++++++++++++++------------- 2 files changed, 165 insertions(+), 146 deletions(-) diff --git a/source/applications/aggregation.rst b/source/applications/aggregation.rst index c3252c8dc3f..4c84cc815da 100644 --- a/source/applications/aggregation.rst +++ b/source/applications/aggregation.rst @@ -12,11 +12,11 @@ Overview The MongoDB aggregation framework provides a means to calculate aggregate values without having to use :doc:`map/reduce `. While map/reduce is powerful, using map/reduce is -more difficult than necessary for simple aggregation tasks, such as +more difficult than necessary for many simple aggregation tasks, such as totaling or averaging field values. If you're familiar with :term:`SQL`, the aggregation framework -provides similar functionality as "``GROUPBY``" and related SQL +provides similar functionality to "``GROUP BY``" and related SQL operators as well as simple forms of "self joins." Additionally, the aggregation framework provides projection capabilities to reshape the returned data. Using projections and aggregation, you can add computed @@ -38,10 +38,10 @@ underpin the aggregation framework: :term:`pipelines ` and Pipelines ~~~~~~~~~ -A pipeline is process that applies a sequence of documents when using -the aggregation framework. For those familiar with UNIX-like shells -(e.g. bash,) the concept is analogous to the pipe (i.e. "``|``") used -to string operations together. +Conceptually, documents from a collection are passed through an +aggregation pipeline, and are transformed as they pass through it. +For those familiar with UNIX-like shells (e.g. bash,) the concept is +analogous to the pipe (i.e. "``|``") used to string text filters together. In a shell environment the pipe redirects a stream of characters from the output of one process to the input of the next. The MongoDB @@ -49,12 +49,11 @@ aggregation pipeline streams MongoDB documents from one :doc:`pipeline operator ` to the next to process the documents. -All pipeline operators processes a stream of documents, and the +All pipeline operators process a stream of documents, and the pipeline behaves as if the operation scans a :term:`collection` and -passes all matching documents into the "top" of the pipeline. Then, -each operator in the pipleine transforms each document as it passes -through the pipeline. At the end of the pipeline, the aggregation -framework returns documents in the same manner as all other queries. +passes all matching documents into the "top" of the pipeline. +Each operator in the pipleine transforms each document as it passes +through the pipeline. .. note:: @@ -72,6 +71,7 @@ framework returns documents in the same manner as all other queries. - :agg:pipeline:`$unwind` - :agg:pipeline:`$group` - :agg:pipeline:`$sort` +TODO I'd remove references to $out, since we don't have it yet - :agg:pipeline:`$out` .. _aggregation-expressions: @@ -79,17 +79,18 @@ framework returns documents in the same manner as all other queries. Expressions ~~~~~~~~~~~ -Expressions calculate values based on inputs from the pipeline, and -return their results to the pipeline. The aggregation framework -defines expressions in :term:`JSON` using a prefix format. +Expressions calculate values based on documents passing through the pipeline, +and contribute their results to documents flowing through the pipeline. +The aggregation framework defines expressions in :term:`JSON` using a prefix +format. Often, expressions are stateless and are only evaluated when seen by the aggregation process. Stateless expressions perform operations such -as: adding the values of two fields together, or extracting the year +as adding the values of two fields together or extracting the year from a date. The :term:`accumulator` expressions *do* retain state, and the -:agg:pipeline:`$group` operator uses maintains state (e.g. counts, +:agg:pipeline:`$group` operator maintains that state (e.g. totals, maximums, minimums, and related data.) as documents progress through the :term:`pipeline`. @@ -104,17 +105,17 @@ Invocation ~~~~~~~~~~ Invoke an :term:`aggregation` operation with the :func:`aggregate` -wrapper in the :program:`mongo` shell for the :dbcommand:`aggregate` +wrapper in the :program:`mongo` shell or the :dbcommand:`aggregate` :term:`database command`. Always call :func:`aggregate` on a collection object, which will determine the documents that contribute to the beginning of the aggregation :term:`pipeline`. The arguments to -the :func:`aggregate` function specify a sequence :ref:`pipeline +the :func:`aggregate` function specify a sequence of :ref:`pipeline operators `, where each :ref:`pipeline operator ` may have a number of operands. First, consider a :term:`collection` of documents named "``article``" -using the following schema or and format: +using the following format: .. code-block:: javascript @@ -169,7 +170,10 @@ The aggregation operation in the previous section returns a if there was an error As a document, the result is subject to the current :ref:`BSON -Document size `. If you expect the +Document size `. + +TODO $out is not going to be available in 2.2, so I'd eliminate this reference + If you expect the aggregation framework to return a larger result, consider using the use the :agg:pipeline:`$out` pipeline operator to write the output to a collection. @@ -181,22 +185,21 @@ Early Filtering ~~~~~~~~~~~~~~~ Because you will always call :func:`aggregate` on a -:term:`collection` object, which inserts the *entire* collection into -the aggregation pipeline, you may want to increase efficiency in some -situations by avoiding scanning an entire collection. +:term:`collection` object, which logically inserts the *entire* collection into +the aggregation pipeline, you may want to optimize the operation +by avoiding scanning the entire collection whenever possible. If your aggregation operation requires only a subset of the data in a -collection, use the :agg:pipeline:`$match` to limit the items in the -pipeline, as in a query. These :agg:pipeline:`$match` operations will use -suitable indexes to access the matching element or elements in a -collection. - -When :agg:pipeline:`$match` appears first in the :term:`pipeline`, the -:dbcommand:`pipeline` begins with results of a :term:`query` rather than -the entire contents of a collection. - +collection, use the :agg:pipeline:`$match` to restrict which items go in +to the top of the +pipeline, as in a query. When placed early in a pipeline, these +:agg:pipeline:`$match` operations will use +suitable indexes to scan only the matching documents in a collection. + +TODO we don't do the following yet, but there's a ticket for it. Should we +leave it out for now? :term:`Aggregation` operations have an optimization phase, before -execution, attempts to re-arrange the pipeline by moving +execution, which attempts to re-arrange the pipeline by moving :agg:pipeline:`$match` operators towards the beginning to the greatest extent possible. For example, if a :term:`pipeline` begins with a :agg:pipeline:`$project` that renames fields, followed by a @@ -221,7 +224,7 @@ must fit in memory. :agg:pipeline:`$group` has similar characteristics: Before any :agg:pipeline:`$group` passes its output along the pipeline, it must -receive the entity of its input. For the case of :agg:pipeline:`$group` +receive the entirety of its input. For the case of :agg:pipeline:`$group` this frequently does not require as much memory as :agg:pipeline:`$sort`, because it only needs to retain one record for each unique key in the grouping specification. @@ -236,14 +239,14 @@ Sharded Operation The aggregation framework is compatible with sharded collections. -When the operating on a sharded collection, the aggregation pipeline -splits into two parts. The aggregation framework pushes all of the +When operating on a sharded collection, the aggregation pipeline +splits the pipeline into two parts. The aggregation framework pushes all of the operators up to and including the first :agg:pipeline:`$group` or -:agg:pipeline:`$sort` to each shard using the results received from the -shards. [#match-sharding]_ Then, a second pipeline on the +:agg:pipeline:`$sort` to each shard. +[#match-sharding]_ Then, a second pipeline on the :program:`mongos` runs. This pipeline consists of the first :agg:pipeline:`$group` or :agg:pipeline:`$sort` and any remaining pipeline -operators +operators; this is run on the results received from the shards. The :program:`mongos` pipeline merges :agg:pipeline:`$sort` operations from the shards. The :agg:pipeline:`$group`, brings any “sub-totals” diff --git a/source/reference/aggregation.rst b/source/reference/aggregation.rst index 024b750ac0c..17470941f18 100644 --- a/source/reference/aggregation.rst +++ b/source/reference/aggregation.rst @@ -8,7 +8,7 @@ Aggregation Framework Operators The aggregation framework provides the ability to project, process, and/or control the output of the query, without using ":term:`map -reduce`." Aggregation uses a syntax that closely resembles the same +reduce`." Aggregation uses a syntax that resembles the same syntax and form as "regular" MongoDB database queries. This documentation provides an overview of all aggregation operators, @@ -23,9 +23,9 @@ their use, and their behavior. Pipeline -------- -Pipeline operators appear in an array and documents pass through these -operators in a sequence. All examples in this section, assume that the -aggregation pipeline beings with a collection named "``article`` that +Pipeline operators appear in an array. Conceptually, documents pass through +these operators in a sequence. All examples in this section assume that the +aggregation pipeline begins with a collection named "``article`` which contains documents that resemble the following: .. code-block:: javascript @@ -119,8 +119,8 @@ The current pipeline operators are: "``comments``" and "``other``" fields along the pipeline. The :pipeline:`$project` enters **exclusive** mode when the - first field in the projection is an exclusion. When the first field - is an **inclusion** the projection is inclusive. + first field in the projection (that isn't "``_id``") is an exclusion. + When the first field is an **inclusion** the projection is inclusive. .. note:: @@ -147,7 +147,7 @@ The current pipeline operators are: .. note:: - You must enclose expression that defines the computed field in + You must enclose the expression that defines the computed field in braces, so that it resembles an object and conforms to JavaScript syntax. @@ -165,16 +165,17 @@ The current pipeline operators are: ); - This operation renames the "``pageViews``" field "``page_views``", + This operation renames the "``pageViews``" field as "``page_views``", and renames the "``foo``" field in the "``other``" sub-document as the top-level field "``florable``". The field references used for - renaming fields are a direct expression and do not use an operator + renaming fields are direct expressions and do not use an operator or surrounding braces. All aggregation field references can use dotted paths to refer to fields in nested documents. Finally, you can use the :pipeline:`$project` to create and - populates new sub-documents. Consider the following example that - creates a new field named ``stats`` that holds a number of values: + populate new sub-documents. Consider the following example that + creates a new object-valued field named ``stats,`` which holds a number + of values: .. code-block:: javascript @@ -189,14 +190,14 @@ The current pipeline operators are: }} ); - This projection selects the ``title`` field and places + This projection includes the ``title`` field and places :pipeline:`$project` into "inclusive" mode. Then, it creates the ``stats`` documents with the following fields: - "``pv``" which includes and renames the "``pageViews``" from the top level of the original documents. - - "``foo``" which includes the "``foo``" document from the - "``other``" sub-document of the original documents. + - "``foo``" which includes the value of "``other.foo``" from the + original documents. - "``dpv``" which is a computed field that adds 10 to the value of the "``pageViews``" field in the original document using the :expression:`$add` aggregation expression. @@ -204,7 +205,7 @@ The current pipeline operators are: .. note:: Because of the :term:`BSON` requirement to preserve field order, - projections output fields in the same order that they were + projections output fields in the same order that they appeared in the input. Furthermore, when the aggregation framework adds computed values to a document, they will follow all fields from the original and appear in the order that they appeared in the @@ -214,11 +215,11 @@ The current pipeline operators are: Provides a query-like interface to filter documents out of the aggregation :term:`pipeline`. The :pipeline:`$match` drops - documents that do not match the statement from the aggregation + documents that do not match the condition from the aggregation pipeline, and it passes documents that match along the pipeline unaltered. - The syntax passed to the :pipeline:`$match` is always identical + The syntax passed to the :pipeline:`$match` is identical to the :term:`query` syntax. Consider the following prototype form: .. code-block:: javascript @@ -246,7 +247,7 @@ The current pipeline operators are: ); Here, all documents return when the ``score`` field holds a value - that is greater than 50, but less than or equal to 90. + that is greater than 50 and less than or equal to 90. .. seealso:: :mongodb:operator:`$gt` and :mongodb:operator:`$lte`. @@ -283,13 +284,13 @@ The current pipeline operators are: .. pipeline:: $skip - Skips over a number of :term:`JSON document ` that - pass through the :pipeline:`$limit` in the - :term:`pipeline`. before passing all of the remaining input. + Skips over the specified number of :term:`JSON document `s + that pass through the :pipeline:`$skip` in the + :term:`pipeline` before passing all of the remaining input. :pipeline:`$skip` takes a single numeric (positive whole number) value as a parameter. Once the operation has skipped the specified - number of documents it passes all remaining documents along the + number of documents it passes all the remaining documents along the :term:`pipeline` without alteration. Consider the following example: @@ -307,7 +308,7 @@ The current pipeline operators are: Peels off the elements of an array individually, and returns a stream of documents. :pipeline:`$unwind` returns one document for - every member of the unwound array, within every source + every member of the unwound array within every source document. Take the following aggregation command: .. code-block:: javascript @@ -326,7 +327,7 @@ The current pipeline operators are: The dollar sign (i.e. "``$``") must proceed the field specification handed to the :pipeline:`$unwind` operator. - In the above aggregation :pipeline:`$project`, and selects + In the above aggregation :pipeline:`$project` selects (inclusively) the ``author``, ``title``, and ``tags`` fields, as well as the ``_id`` field implicitly. Then the pipeline passes the results of the projection to the :pipeline:`$unwind` operator, @@ -373,8 +374,7 @@ The current pipeline operators are: with :pipeline:`$group`. - The effects of an unwind can be undone with the - :pipeline:`$push` or :pipeline:`$group` pipeline - operators. + :pipeline:`$group` pipeline operators. - If you specify a target field for :pipeline:`$unwind` that does not exist in an input document, the document passes @@ -397,15 +397,13 @@ The current pipeline operators are: The output of :pipeline:`$group` depends on how you define groups. Begin by specifying an identifier (i.e. a "``_id``" field) for the group you're creating with this pipeline. You can specify - a single field from the documents in the pipeline, or specify a - previously computed value. + a single field from the documents in the pipeline, a previously computed + value, or an aggregate key made up from several incoming fields. - Every group expression must specify an "``_id``" field, which is - naturally unique. You may specify the "``_id``" field as a dotted + Every group expression must specify an "``_id``" field. + You may specify the "``_id``" field as a dotted field path reference, a document with multiple fields enclosed in - braces (i.e. "``{``" and "``}``"), or constant with a single - value. Always prefix the "``_id``" with a dollar sign - (i.e. "``$``".) + braces (i.e. "``{``" and "``}``"), or a constant value. .. note:: @@ -425,12 +423,12 @@ The current pipeline operators are: ); This groups by the "``author``" field and computes two fields, the - first "``docsPerAuthor``" is a counter field that increments for + first "``docsPerAuthor``" is a counter field that adds one for each document with a given author field using the :group:`$sum` - function. The "``viewsPerAuthor``" field derives from summation of - all of the "``pageViews``" fields in the grouped documents. + function. The "``viewsPerAuthor``" field is the sum of + all of the "``pageViews``" fields in the documents for each group. - Each field that the :pipeline:`$group` must use one of the group + Each field defined for the :pipeline:`$group` must use one of the group aggregation function listed below to generate its composite value: .. group:: $addToSet @@ -441,7 +439,7 @@ The current pipeline operators are: .. group:: $first - Returns the first value it sees for its field argument. + Returns the first value it sees for its group. .. note:: @@ -451,7 +449,7 @@ The current pipeline operators are: .. group:: $last - Returns the last value it sees for its field argument. + Returns the last value it sees for its group. .. note:: @@ -469,6 +467,11 @@ The current pipeline operators are: Returns the lowest value among all values of the field in all documents selected by this group. + .. group:: $avg + + Returns the average of all the values of the field in all documents + selected by this group. + .. group:: $push Returns an array of all the values found in the selected field @@ -478,17 +481,18 @@ The current pipeline operators are: .. group:: $sum - Returns the total or summation of all values for a specified - filed in the grouped documents, as in the second use above. + Returns the sum of all the values for a specified + field in the grouped documents, as in the second use above. Alternately, if you specify a value as an argument, :group:`$sum` will increment this field by the specified value for every document in the grouping. Typically, as in the first - use above, specify a value of "``1`` " to create a *counter.* + use above, specify a value of "``1`` " in order to count members of the + group. .. warning:: - The aggregation system stores :pipeline:`$group` operations in + The aggregation system currently stores :pipeline:`$group` operations in memory, which may cause problems when processing a larger number of groups. @@ -500,7 +504,7 @@ The current pipeline operators are: .. code-block:: javascript - db.( + db..aggregate( { $sort : { } } ); @@ -511,7 +515,7 @@ The current pipeline operators are: The sorting configuration is identical to the specification of an :term:`index`. Within a document, specify a field or fields that you want to sort by and a value of "``1``" or "``-1``" to specify - an ascending or descending sort receptively. See the following + an ascending or descending sort respectively. See the following example: .. code-block:: javascript @@ -521,29 +525,34 @@ The current pipeline operators are: ); This operation sorts the documents in the "``users``" collection, - in ascending order according by the "``age``" field and then in - descending order according to the value in the "``posts``" field. + in descending order according by the "``age``" field and then in + ascending order according to the value in the "``posts``" field. .. note:: The :pipeline:`$sort` cannot begin sorting documents until previous operators in the pipeline have returned all output. - .. warning:: The entire sort operation as of the current release - operates entirely in memory, which may cause problems when + .. warning:: Unless an index can be used, the sort operation as of the + current release operates entirely in memory, which may cause problems when sorting large numbers of documents. +TODO We haven't settled on the syntax for $out, so I wouldn't even include +it at this time. We're still not sure what all the options will be, but it's +bound to be more complex than this because we want to have some of the existing +map/reduce options available. + .. pipeline:: $out .. note:: The :pipeline:`$out` is not implemented as of version - 2.1.0. Follow :issue:`SERVER-3254` to track the progress of + 2.2.0. Follow :issue:`SERVER-3254` to track the progress of development for :pipeline:`$out`. Use :pipeline:`$out` to write the contents of the - :term:`pipeline`, without concluding the aggregation - procedure. Specify the name of a collection as an argument to + :term:`pipeline`, without concluding the aggregation pipeline. + Specify the name of a collection as an argument to :pipeline:`$out`. Consider the following trivial example: .. code-block:: javascript @@ -562,18 +571,18 @@ The current pipeline operators are: Expressions ----------- -These operators perform transformations within the :term:`aggregation +These operators calculate values within the :term:`aggregation framework`. Boolean Operators ~~~~~~~~~~~~~~~~~ -The three boolean operators accept take Booleans as arguments and +The three boolean operators accept Booleans as arguments and return Booleans as results. .. note:: - These operators convert non-boolean to Boolean values according to + These operators convert non-booleans to Boolean values according to the BSON standards. Here, "Null," undefined, and "zero" values become "false," while non-zero numeric values, strings, dates, objects, and other types become "true." @@ -585,8 +594,8 @@ return Booleans as results. .. note:: - :expression:`$and` uses short-circuit logic: the operation will - stops evaluating after encountering the first ``false`` expression. + :expression:`$and` uses short-circuit logic: the operation + stops evaluation after encountering the first ``false`` expression. .. expression:: $not @@ -601,36 +610,35 @@ return Booleans as results. .. note:: - :expression:`$or` uses short-circuit logic: the operation will - stops evaluating after encountering the first ``false`` - expression. + :expression:`$or` uses short-circuit logic: the operation + stops evaluation after encountering the first ``true`` expression. Comparison Operators ~~~~~~~~~~~~~~~~~~~~ These operators perform comparisons between two values and return a -Boolean, in most cases, reflecting that comparison. +Boolean, in most cases, reflecting the result of that comparison. -All comparison operators take a pair of numbers or an array with a -pair of strings. Except for :expression:`$cmp`, all comparison -operators return a Boolean value. :expression:`$cmp` returns an -integer. +All comparison operators take an array with a pair of values. Comparisons +can be made between numbers, strings, and dates. Except for +:expression:`$cmp`, all comparison operators return a +Boolean value. :expression:`$cmp` returns an integer. .. expression:: $cmp - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns an integer. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - - A negative number if the first number is less than the second. + - A negative number if the first value is less than the second. - - A positive number if the first number is greater than the second. + - A positive number if the first value is greater than the second. - - ``0`` if the the values are equal. + - ``0`` if the two values are equal. .. expression:: $eq - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the values are equivalent. @@ -638,8 +646,8 @@ integer. .. expression:: $gt - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the first value is *greater than* the second value. @@ -648,8 +656,8 @@ integer. .. expression:: $gte - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the first value is *greater than or equal* to the second value. @@ -658,8 +666,8 @@ integer. .. expression:: $lt - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the first value is *less than* the second value. @@ -668,8 +676,8 @@ integer. .. expression:: $lte - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the first value is *less than or equal to* the second value. @@ -679,8 +687,8 @@ integer. .. expression:: $ne - Takes two values, either a pair of numbers or an array with a pair - of strings, and returns a Boolean. The returned value is: + Takes two values in an array, either a pair of numbers, a pair of strings, + or a pair of dates, and returns an integer. The returned value is: - ``true`` when the values are **not equivalent**. @@ -730,16 +738,11 @@ Arithmetic Operators number of days and decrements the date, returning the resulting date. -.. expression:: $avg - - Takes an array of numbers and returns and computes the arithmetic - mean. :expression:`$avg` returns the average. String Operators ~~~~~~~~~~~~~~~~ -These operators manipulate strings within aggregation :term:`pipeline` -operators. +These operators manipulate strings within projection expressions. .. expression:: $strcasecmp @@ -751,9 +754,9 @@ operators. .. note:: - :expression:`$strcasecmp` capitalizes all strings, and thus - provides a case-*insensitive* comparison. Use :expression:`$cmp` - for a case sensitive comparison. + :expression:`$strcasecmp` internally capitalizes strings before + comparing them, and thus provides a case-*insensitive* comparison. + Use :expression:`$cmp` for a case sensitive comparison. .. expression:: $substr @@ -767,55 +770,68 @@ operators. Takes a single string and converts that string to lowercase, returning the result. All uppercase letters become lowercase. + .. note:: + + :expression:`$toLower` may not make sense when applied to glyphs outside + the roman alphabet. + .. expression:: $toUpper Takes a single string and converts that string to uppercase, returning the result. All lowercase letters become uppercase. -.. seealso:: ":expression:`$add`" can also manipulate string objects. + .. note:: + + :expression:`$toUpper` may not make sense when applied to glyphs outside + the roman alphabet. + + +.. seealso:: ":expression:`$add`" which can be used to concatenate strings. Date Operators ~~~~~~~~~~~~~~ All date operators, except :expression:`$add` and -:expression:`$subtract`, take a "Date" typed object as a single -argument and return a JavaScript "long" typed number object. +:expression:`$subtract`, take a "Date" typed value as a single +argument and return a JavaScript "long" number. .. expression:: $dayOfMonth - Takes a date object and returns the day of the month as a number + Takes a date and returns the day of the month as a number between 1 and 31. .. expression:: $dayOfWeek - Takes a date object and returns the day of the week as a number + Takes a date and returns the day of the week as a number between 1 and 7. .. expression:: $dayOfYear - Takes a date object and returns the day of the year as a number + Takes a date and returns the day of the year as a number between 1 and 366. .. expression:: $hour - Takes a date object and returns the hour between 0 and 23. + Takes a date and returns the hour between 0 and 23. + +TODO need to add $isoDate. See my addition to the wiki. .. expression:: $minute - Takes a date object and returns the minute between 0 and 59. + Takes a date and returns the minute between 0 and 59. .. expression:: $month - Takes a date object and returns the month as a number between 1 and 12. + Takes a date and returns the month as a number between 1 and 12. .. expression:: $second - Takes a date object and returns the second between 0 and 59. + Takes a date and returns the second between 0 and 59. .. expression:: $week - Takes a date object and returns the week of the year as a number + Takes a date and returns the week of the year as a number between 0 and 53. Weeks start on Sundays and the days before the first Sunday of the @@ -823,7 +839,7 @@ argument and return a JavaScript "long" typed number object. .. expression:: $year - Takes a date object and returns a four digit number. + Takes a date and returns a four digit number. .. seealso:: ":expression:`$add`" and ":expression:`$subtract` can also manipulate date objects. @@ -841,7 +857,7 @@ Multi-Expressions .. expression:: $cond Takes an array with three expressions, where the first expression - evaluates to a Boolean value. If the first expression is true, - :expression:`$cond` returns the second expression. If the first - expression is false, :expression:`$cond` evaluates and returns the - third expression. + evaluates to a Boolean value. If the first expression evaluates to true, + :expression:`$cond` returns the value of the second expression. If the + first expression evaluates to false, :expression:`$cond` evaluates and + returns the third expression.