DOCSP-35937 aggregations builder 4.3 #2876

ccho-mongodb · 2024-04-16T20:24:58Z

JIRA: https://jira.mongodb.org/browse/DOCSP-35937

Staging:
https://preview-mongodbcchomongodb.gatsbyjs.io/laravel/DOCSP-35937-Aggregations-Builder-4.3/fundamentals/aggregation-builder/

Checklist

Add tests and ensure they pass
Add an entry to the CHANGELOG.md file
Update documentation for new features

…-Builder-4.3

docs/fundamentals/aggregation-builder.txt

rustagir

pretty much looks good, left a few comments/questions!

rustagir · 2024-04-17T13:12:02Z

docs/fundamentals/aggregation-builder.txt

+An aggregation pipeline is a data processing pipeline that takes documents
+as input, sequentially performs transformations and computations on the data,


Suggested change

An aggregation pipeline is a data processing pipeline that takes documents

as input, sequentially performs transformations and computations on the data,

An aggregation pipeline is a data processing pipeline that

sequentially performs transformations and computations on input data,

rustagir · 2024-04-17T13:14:44Z

docs/fundamentals/aggregation-builder.txt

+This section features the following examples of common aggregation stages and
+of an aggregation pipeline:


Suggested change

This section features the following examples of common aggregation stages and

of an aggregation pipeline:

This section features the following examples, which demonstrate how to use common

aggregation stages and combine stages to make an aggregation pipeline:

rustagir · 2024-04-17T15:32:59Z

docs/fundamentals/aggregation-builder.txt

+   This example stage performs a similar grouping to an equivalent
+   ``distinct()`` query builder method. To learn more about the ``distinct()``
+   method, see the :ref:`laravel-distinct-usage` usage example.


Suggested change

This example stage performs a similar grouping to an equivalent

``distinct()`` query builder method. To learn more about the ``distinct()``

method, see the :ref:`laravel-distinct-usage` usage example.

This example stage performs a similar task as the

``distinct()`` query builder method. To learn more about the ``distinct()``

method, see the :ref:`laravel-distinct-usage` usage example.

rustagir · 2024-04-17T15:33:48Z

docs/fundamentals/aggregation-builder.txt

+You can chain the ``project()`` method to your aggregation pipeline to specify
+which fields from the documents to display by this stage.
+
+To specify fields to include, pass the name of a field and a truthy value,


Q: could including words like "truthy" and "falsy" confuse readers?

I think it's a relatively common term and not obscure jargon. I provided examples in the qualifying phrase immediately after. Let me know if you had something else in mind for clarifying this.

rustagir · 2024-04-17T15:34:39Z

docs/fundamentals/aggregation-builder.txt

+- Add the ``year`` field to the documents and set the value to the year
+  extracted from the ``birthday`` field.


S: could be more descriptive

Suggested change

- Add the ``year`` field to the documents and set the value to the year

extracted from the ``birthday`` field.

- Add the ``birth_year`` field to the documents and set the value to the year

extracted from the ``birthday`` field.

If you change this, change the year_avg field to birth_year_avg

Thanks, will update the example to use birth_year and birth_year_avg field names.

rustagir · 2024-04-17T15:35:08Z

docs/fundamentals/aggregation-builder.txt

+- Match all documents in the collection since the ``match()`` stage
+  is omitted.


Q: is this line necessary? It could be confusing to mention things that the pipeline does NOT include

I thought it would be good to reinforce the information provided in the admonition in the Match Stage Example section. I think it is relevant to the description of what the pipeline does and might cause readers to question what documents are part of the pipeline if omitted.

Let me know if you think it would be better to omit it.

I think it could work better as a note, potentially, but I am ok with leaving as is too!

Good idea, will move it to an admonition.

rustagir

lgtm with a few small suggestions, also happy to discuss my last comment

rustagir · 2024-04-17T17:28:02Z

docs/fundamentals/aggregation-builder.txt

+
+In this guide, you can learn how to perform aggregations and construct
+pipelines by using the {+odm-short+} aggregation builder. The aggregation
+builder lets you use a typesafe syntax to construct a MongoDB


Suggested change

builder lets you use a typesafe syntax to construct a MongoDB

builder lets you use a type-safe syntax to construct a MongoDB

rustagir · 2024-04-17T17:28:12Z

docs/fundamentals/aggregation-builder.txt

+performs transformations and computations on input data, and outputs the
+results as a new set of documents.


Suggested change

performs transformations and computations on input data, and outputs the

results as a new set of documents.

performs transformations and computations on input data, then outputs the

results as a new document or set of documents.

rustagir · 2024-04-17T17:28:50Z

docs/fundamentals/aggregation-builder.txt

+An aggregation pipeline is composed of **aggregation stages**, which are
+operators that process input data and output data that the next stage uses as
+its input.


Suggested change

An aggregation pipeline is composed of **aggregation stages**, which are

operators that process input data and output data that the next stage uses as

its input.

An aggregation pipeline is composed of **aggregation stages**, which use

operators to process input data and produce data that the next stage uses as

its input.

rustagir · 2024-04-17T17:31:35Z

docs/fundamentals/aggregation-builder.txt

+To specify an ascending sort, set the field value to the ``Sort::Asc`` enum.
+
+To specify a descending sort, set the field value to the ``Sort::Desc`` enum.


S; combine into one sentence to shorten this section/reduce breaks

rustagir · 2024-04-17T17:33:03Z

docs/fundamentals/aggregation-builder.txt

+- Match all documents in the collection since the ``match()`` stage
+  is omitted.


I think it could work better as a note, potentially, but I am ok with leaving as is too!

rustagir · 2024-04-17T17:36:56Z

docs/fundamentals/aggregation-builder.txt

+The following function accepts the name of a field that contains a date
+and returns an expression that extracts the year from the date:


S: I think this section should provide an example of a functionality that is not directly achievable from one aggregation operator, $year in this case. For example, could this example extract the year and add a fixed number to calculate something like the year they turned 18? Or a field to tell if they were born in the 20th century or 21st century or something like that.

Thanks -- I think that's a great idea and I had thought of other ideas. However, I intentionally decided on something less complex to focus on documenting the custom operator factory usage.

…ot used

GromNaN

LGTM, with a suggestion.

GromNaN · 2024-04-18T11:06:27Z

docs/fundamentals/aggregation-builder.txt

+**aggregation pipeline**.
+
+An aggregation pipeline is a data processing pipeline that sequentially
+performs transformations and computations on input data, then outputs the


"input data" sounds like data that you send with the command. It think this working could be better: "data from the MongoDB database"

ccho-mongodb · 2024-04-18T22:52:19Z

Thanks for fixing the unit tests!

Chris Cho and others added 15 commits April 12, 2024 09:29

DOCSP-35937: aggregation builder page

db97da9

aggregation pipeline

f827314

rst fixes

3c93a24

wip

a5175d5

fix targets

d474fcc

apply phpcbf formatting

629ad29

grammar and misc fixes

b5658bf

wip

e757c00

apply phpcbf formatting

d3df926

Merge remote-tracking branch 'upstream' into DOCSP-35937-Aggregations…

1597aff

…-Builder-4.3

move into fundamentals

ab93e16

WIP

94457eb

add custom operator factory section

2b62498

grammar fixes

4c3cdf1

fix indent

684118e

ccho-mongodb added the docs label Apr 16, 2024

GromNaN reviewed Apr 17, 2024

View reviewed changes

docs/fundamentals/aggregation-builder.txt Show resolved Hide resolved

docs/fundamentals/aggregation-builder.txt Outdated Show resolved Hide resolved

docs/fundamentals/aggregation-builder.txt Show resolved Hide resolved

Chris Cho added 2 commits April 17, 2024 11:21

fixes

fb5b578

tweaks

80fac91

rustagir requested changes Apr 17, 2024

View reviewed changes

Chris Cho added 2 commits April 17, 2024 12:31

PRR fixes

c2e4354

additional fixes

2e54a6f

ccho-mongodb requested a review from rustagir April 17, 2024 16:51

rustagir approved these changes Apr 17, 2024

View reviewed changes

PRR fixes

4aa8b80

ccho-mongodb marked this pull request as ready for review April 17, 2024 18:06

ccho-mongodb requested a review from a team as a code owner April 17, 2024 18:06

ccho-mongodb requested a review from GromNaN April 17, 2024 18:06

GromNaN added 2 commits April 18, 2024 13:00

Tests don't need to be run in separate process when require_once is n…

469fe97

…ot used

Remove unused variable

809ec09

Move redundant fixture setup to setUp method

ee2625a

GromNaN approved these changes Apr 18, 2024

View reviewed changes

Chris Cho added 2 commits April 18, 2024 18:53

PRR fixes

515d18c

landing page fix

6a6f20a

ccho-mongodb merged commit 8bc235c into mongodb:4.3 Apr 18, 2024

		An aggregation pipeline is a data processing pipeline that takes documents
		as input, sequentially performs transformations and computations on the data,

		This section features the following examples of common aggregation stages and
		of an aggregation pipeline:

		- Add the ``year`` field to the documents and set the value to the year
		extracted from the ``birthday`` field.

		- Match all documents in the collection since the ``match()`` stage
		is omitted.

	builder lets you use a typesafe syntax to construct a MongoDB
	builder lets you use a type-safe syntax to construct a MongoDB

		performs transformations and computations on input data, and outputs the
		results as a new set of documents.

		To specify an ascending sort, set the field value to the ``Sort::Asc`` enum.

		To specify a descending sort, set the field value to the ``Sort::Desc`` enum.

		The following function accepts the name of a field that contains a date
		and returns an expression that extracts the year from the date:

DOCSP-35937 aggregations builder 4.3 #2876

DOCSP-35937 aggregations builder 4.3 #2876

Uh oh!

Conversation

ccho-mongodb commented Apr 16, 2024

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb commented Apr 18, 2024

Uh oh!

Uh oh!

ccho-mongodb Apr 17, 2024 •

edited

Loading