chore(docs): add example and update language in aggregateWindow (#4874)

* chore(docs): add example and update language in aggregateWindow * chore(docs): make fmt * chore(docs): updated window location for tests * chore(docs): updated window location for tests * chore(docs): updated window location for tests * chore(docs): fix typo
influxdata · Jun 15, 2022 · 1c65530 · 1c65530
1 parent f3ba2d7
commit 1c65530
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 8 deletions.
diff --git a/interpreter/interpreter_test.go b/interpreter/interpreter_test.go
@@ -883,8 +883,8 @@ func TestStack(t *testing.T) {
 			FunctionName: "window",
 			Location: ast.SourceLocation{
 				File:   "universe/universe.flux",
-				Start:  ast.Position{Line: 3716, Column: 12},
-				End:    ast.Position{Line: 3716, Column: 51},
+				Start:  ast.Position{Line: 3759, Column: 12},
+				End:    ast.Position{Line: 3759, Column: 51},
 				Source: `window(every: inf, timeColumn: timeDst)`,
 			},
 		},

diff --git a/libflux/go/libflux/buildinfo.gen.go b/libflux/go/libflux/buildinfo.gen.go
@@ -596,7 +596,7 @@ var sourceHashes = map[string]string{
 	"stdlib/universe/union_heterogeneous_test.flux":                                               "3298ba8e24903621505c78f4c48e4148f2d7c45e507e19ab46f547756a3173f4",
 	"stdlib/universe/union_test.flux":                                                             "f853a7bf588fedceee217d931733eb5f3b86b1f4717c2af24d59890b3c86f71c",
 	"stdlib/universe/unique_test.flux":                                                            "516e9fea81513c8cbb0c7a23545c9080e56c00149cc40bfc2187c649bfa4c958",
-	"stdlib/universe/universe.flux":                                                               "c8a3bbd18143113965ca29f94e8ff86c68eea21427fb1e971b4b8334ff2f8802",
+	"stdlib/universe/universe.flux":                                                               "af52e8214deefa8d3606df936a9b0f912d16dbe69300b07c243758f93580f2f1",
 	"stdlib/universe/universe_truncateTimeColumn_test.flux":                                       "8acb700c612e9eba87c0525b33fd1f0528e6139cc912ed844932caef25d37b56",
 	"stdlib/universe/window_aggregate_test.flux":                                                  "cd0a1a7e788a50fa04289aa6e8b557f6c960eaf6ae95f9d8c0ff3044a48b4beb",
 	"stdlib/universe/window_default_start_align_test.flux":                                        "0aaf612796fbb5ac421579151ad32a8861f4494a314ea615d0ccedd18067b980",

diff --git a/stdlib/universe/universe.flux b/stdlib/universe/universe.flux
@@ -3599,8 +3599,8 @@ _fillEmpty = (tables=<-, createEmpty) =>
     else
         tables
 
-// aggregateWindow groups data into fixed windows of time and applies an
-// aggregate or selector function to each window.
+// aggregateWindow downsamples data by grouping data into fixed windows of time
+// and applying an aggregate or selector function to each window.
 //
 // All columns not in the group key other than the specified `column` are dropped
 // from output tables. This includes `_time`. `aggregateWindow()` uses the
@@ -3609,11 +3609,11 @@ _fillEmpty = (tables=<-, createEmpty) =>
 // `aggregateWindow()` requires `_start` and `_stop` columns in input data.
 // Use `range()` to assign `_start` and `_stop` values.
 //
-// #### Window by calendar months and years
+// #### Downsample by calendar months and years
 // `every`, `period`, and `offset` parameters support all valid duration units,
 // including calendar months (`1mo`) and years (`1y`).
 //
-// #### Window by week
+// #### Downsample by week
 // When windowing by week (`1w`), weeks are determined using the Unix epoch
 // (1970-01-01T00:00:00Z UTC). The Unix epoch was on a Thursday, so all
 // calculated weeks begin on Thursday.
@@ -3675,7 +3675,7 @@ _fillEmpty = (tables=<-, createEmpty) =>
 // >     )
 // ```
 //
-// ### Window and aggregate by calendar month
+// ### Downsample by calendar month
 // ```
 // # import "sampledata"
 // #
@@ -3686,6 +3686,49 @@ _fillEmpty = (tables=<-, createEmpty) =>
 // >     |> aggregateWindow(every: 1mo, fn: mean)
 // ```
 //
+// ### Downsample by calendar week starting on Monday
+//
+// Flux increments weeks from the Unix epoch, which was a Thursday.
+// Because of this, by default, all `1w` windows begin on Thursday.
+// Use the `offset` parameter to shift the start of weekly windows to the
+// desired day of the week.
+//
+// | Week start | Offset |
+// | :--------- | :----: |
+// | Monday     |  -3d   |
+// | Tuesday    |  -2d   |
+// | Wednesday  |  -1d   |
+// | Thursday   |   0d   |
+// | Friday     |   1d   |
+// | Saturday   |   2d   |
+// | Sunday     |   3d   |
+//
+// ```js
+// # import "array"
+// #
+// # data =
+// #     array.from(
+// #         rows: [
+// #             {_time: 2022-01-01T00:00:00Z, tag: "t1", _value: 2.0},
+// #             {_time: 2022-01-03T00:00:00Z, tag: "t1", _value: 2.2},
+// #             {_time: 2022-01-06T00:00:00Z, tag: "t1", _value: 4.1},
+// #             {_time: 2022-01-09T00:00:00Z, tag: "t1", _value: 3.8},
+// #             {_time: 2022-01-11T00:00:00Z, tag: "t1", _value: 1.7},
+// #             {_time: 2022-01-12T00:00:00Z, tag: "t1", _value: 2.1},
+// #             {_time: 2022-01-15T00:00:00Z, tag: "t1", _value: 3.8},
+// #             {_time: 2022-01-16T00:00:00Z, tag: "t1", _value: 4.2},
+// #             {_time: 2022-01-20T00:00:00Z, tag: "t1", _value: 5.0},
+// #             {_time: 2022-01-24T00:00:00Z, tag: "t1", _value: 5.8},
+// #             {_time: 2022-01-28T00:00:00Z, tag: "t1", _value: 3.9},
+// #         ],
+// #     )
+// #         |> range(start: 2022-01-01T00:00:00Z, stop: 2022-01-31T23:59:59Z)
+// #         |> group(columns: ["tag"])
+// #
+// < data
+// >     |> aggregateWindow(every: 1w, offset: -3d, fn: mean)
+// ```
+//
 // ## Metadata
 // introduced: 0.7.0
 // tags: transformations, aggregates, selectors