Skip to content

Commit 095396b

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(DOCSP-20967): Add additional behavior details to fill operators (#692)
* (DOCSP-20967): Add comparison of fill and linearFill to fill page * add link to example * reformat * Address review suggestions * incorporate locf changes * reformatting * remove includes * updates per review feedback * updates per review feedback * address review comment
1 parent 998982f commit 095396b

File tree

4 files changed

+200
-256
lines changed

4 files changed

+200
-256
lines changed

‎source/includes/example-multiple-fill-methods.rst

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
When you use the :pipeline:`$setWindowFields` stage to fill missing
2+
values, you can set values for a different field than the field you
3+
fill from. As a result, you can use multiple fill methods in a single
4+
:pipeline:`$setWindowFields` stage and output the results in distinct
5+
fields.
6+
7+
The following pipeline populates missing ``price`` fields using
8+
|linear-interpolation| and the last-observation-carried-forward method:
9+
10+
.. code-block:: javascript
11+
12+
db.stock.aggregate( [
13+
{
14+
$setWindowFields:
15+
{
16+
sortBy: { time: 1 },
17+
output:
18+
{
19+
linearFillPrice: { $linearFill: "$price" },
20+
locfPrice: { $locf: "$price" }
21+
}
22+
}
23+
}
24+
] )
25+
26+
In the example:
27+
28+
- ``sortBy: { time: 1 }`` sorts the documents by the ``time`` field in
29+
ascending order, from earliest to latest.
30+
31+
- :ref:`output <setWindowFields-output>` specifies:
32+
33+
- ``linearFillPrice`` as a target field to be filled.
34+
35+
- ``{ $linearFill: "$price" }`` is the value for the
36+
``linearFillPrice`` field. :group:`$linearFill` fills missing
37+
``price`` values using |linear-interpolation| based on the
38+
surrounding ``price`` values in the sequence.
39+
40+
- ``locfPrice`` as a target field to be filled.
41+
42+
- ``{ $locf: "$price" }`` is the value for the ``locfPrice`` field.
43+
``locf`` stands for last observation carried forward.
44+
:group:`$locf` fills missing ``price`` values with the value from
45+
the previous document in the sequence.
46+
47+
Example output:
48+
49+
.. code-block:: javascript
50+
:copyable: false
51+
:emphasize-lines: 12,13,25,26,31,32
52+
53+
[
54+
{
55+
_id: ObjectId("620ad555394d47411658b5ef"),
56+
time: ISODate("2021-03-08T09:00:00.000Z"),
57+
price: 500,
58+
linearFillPrice: 500,
59+
locfPrice: 500
60+
},
61+
{
62+
_id: ObjectId("620ad555394d47411658b5f0"),
63+
time: ISODate("2021-03-08T10:00:00.000Z"),
64+
linearFillPrice: 507.5,
65+
locfPrice: 500
66+
},
67+
{
68+
_id: ObjectId("620ad555394d47411658b5f1"),
69+
time: ISODate("2021-03-08T11:00:00.000Z"),
70+
price: 515,
71+
linearFillPrice: 515,
72+
locfPrice: 515
73+
},
74+
{
75+
_id: ObjectId("620ad555394d47411658b5f2"),
76+
time: ISODate("2021-03-08T12:00:00.000Z"),
77+
linearFillPrice: 505,
78+
locfPrice: 515
79+
},
80+
{
81+
_id: ObjectId("620ad555394d47411658b5f3"),
82+
time: ISODate("2021-03-08T13:00:00.000Z"),
83+
linearFillPrice: 495,
84+
locfPrice: 515
85+
},
86+
{
87+
_id: ObjectId("620ad555394d47411658b5f4"),
88+
time: ISODate("2021-03-08T14:00:00.000Z"),
89+
price: 485,
90+
linearFillPrice: 485,
91+
locfPrice: 485
92+
}
93+
]

‎source/reference/operator/aggregation/fill.txt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,21 @@ For a complete example using the ``linear`` fill method, see
251251

252252
For a complete example using the ``locf`` fill method, see
253253
:ref:`fill-example-locf`.
254+
255+
Comparison of :pipeline:`$fill` and Aggregation Operators
256+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
257+
258+
To fill ``null`` and missing field values within a document you can use:
259+
260+
- The :pipeline:`$fill` stage.
261+
262+
When you use the :pipeline:`$fill` stage, the field you specify in the
263+
output is the same field used as the source data.
264+
265+
- The :group:`$linearFill` and :group:`$locf` aggregation operators.
266+
267+
When you :group:`$linearFill` or :group:`$locf`, you can set values
268+
for a different field than the field used as the source data.
254269

255270
Examples
256271
--------

‎source/reference/operator/aggregation/linearFill.txt

Lines changed: 14 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -89,17 +89,21 @@ in :pipeline:`$setWindowFields`.
8989
Comparison of :pipeline:`$fill` and :group:`$linearFill`
9090
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9191

92-
The :pipeline:`$fill` stage with ``{ method: "linear" }`` and the
93-
:group:`$linearFill` operator both fill missing values using
94-
:wikipedia:`linear interpolation <Linear_interpolation>`.
92+
To fill missing field values using
93+
:wikipedia:`linear interpolation <Linear_interpolation>`, you can use:
9594

96-
- When you use the :pipeline:`$fill` stage, the field you fill must be
97-
the same as the field you fill from.
95+
- The :pipeline:`$fill` stage with ``{ method: "linear" }``.
9896

99-
- When you use the :group:`$linearFill` operator inside of a
100-
:pipeline:`$setWindowFields` stage, you can set values for a
101-
different field than the field used as the source data. For an
102-
example, see :ref:`linearFill-example-multiple-methods`.
97+
When you use the :pipeline:`$fill` stage, the field you specify in the
98+
output is the same field used as the source data. See
99+
:ref:`fill-example-linear`.
100+
101+
- The :group:`$linearFill` operator inside of a
102+
:pipeline:`$setWindowFields` stage.
103+
104+
When you use the :group:`$linearFill` operator, you can set values
105+
for a different field than the field used as the source data. See
106+
:ref:`linearFill-example-multiple-methods`.
103107

104108
.. _linearFill-example:
105109

@@ -217,100 +221,7 @@ Example output:
217221
Use Multiple Fill Methods in a Single Stage
218222
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219223

220-
When you use the :pipeline:`$setWindowFields` stage to fill missing
221-
values, you can set values for a different field than the field you
222-
fill from. As a result, you can use multiple fill methods in a single
223-
:pipeline:`$setWindowFields` stage and output the results in distinct
224-
fields.
225-
226-
The following pipeline populates missing ``price`` fields using
227-
|linear-interpolation| and the last-observation-carried-forward method:
228-
229-
.. code-block:: javascript
230-
231-
db.stock.aggregate( [
232-
{
233-
$setWindowFields:
234-
{
235-
sortBy: { time: 1 },
236-
output:
237-
{
238-
linearFillPrice: { $linearFill: "$price" },
239-
locfPrice: { $locf: "$price" }
240-
}
241-
}
242-
}
243-
] )
244-
245-
In the example:
246-
247-
- ``sortBy: { time: 1 }`` sorts the documents by the ``time`` field in
248-
ascending order, from earliest to latest.
249-
250-
- :ref:`output <setWindowFields-output>` specifies:
251-
252-
- ``linearFillPrice`` as a target field to be filled.
253-
254-
- ``{ $linearFill: "$price" }`` is the value for the
255-
``linearFillPrice`` field. :group:`$linearFill` fills missing
256-
``price`` values using |linear-interpolation| based on the
257-
surrounding ``price`` values in the sequence.
258-
259-
- ``locfPrice`` as a target field to be filled.
260-
261-
- ``{ $locf: "$price" }`` is the value for the ``locfPrice`` field.
262-
``locf`` stands for last observation carried forward.
263-
:group:`$locf` fills missing ``price`` values with the value from
264-
the previous document in the sequence.
265-
266-
Example output:
267-
268-
.. code-block:: javascript
269-
:copyable: false
270-
:emphasize-lines: 12,13,25,26,31,32
271-
272-
[
273-
{
274-
_id: ObjectId("620ad555394d47411658b5ef"),
275-
time: ISODate("2021-03-08T09:00:00.000Z"),
276-
price: 500,
277-
linearFillPrice: 500,
278-
locfPrice: 500
279-
},
280-
{
281-
_id: ObjectId("620ad555394d47411658b5f0"),
282-
time: ISODate("2021-03-08T10:00:00.000Z"),
283-
linearFillPrice: 507.5,
284-
locfPrice: 500
285-
},
286-
{
287-
_id: ObjectId("620ad555394d47411658b5f1"),
288-
time: ISODate("2021-03-08T11:00:00.000Z"),
289-
price: 515,
290-
linearFillPrice: 515,
291-
locfPrice: 515
292-
},
293-
{
294-
_id: ObjectId("620ad555394d47411658b5f2"),
295-
time: ISODate("2021-03-08T12:00:00.000Z"),
296-
linearFillPrice: 505,
297-
locfPrice: 515
298-
},
299-
{
300-
_id: ObjectId("620ad555394d47411658b5f3"),
301-
time: ISODate("2021-03-08T13:00:00.000Z"),
302-
linearFillPrice: 495,
303-
locfPrice: 515
304-
},
305-
{
306-
_id: ObjectId("620ad555394d47411658b5f4"),
307-
time: ISODate("2021-03-08T14:00:00.000Z"),
308-
price: 485,
309-
linearFillPrice: 485,
310-
locfPrice: 485
311-
}
312-
]
313-
224+
.. include:: /includes/example-multiple-fill-methods.rst
314225

315226
Restrictions
316227
------------

0 commit comments

Comments
 (0)