You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/ISSUE_TEMPLATE/broken_link_report.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,4 +6,6 @@ labels: bug, automated issue, link check
6
6
assignees: atovpeko
7
7
---
8
8
9
-
The broken link check failed. Check [the workflow logs](https://github.com/timescale/docs/actions/workflows/daily-link-checker.yml) to identify the failing links.
9
+
The broken link check failed. Check [the workflow logs][the-workflow-logs] to identify the failing links.
Copy file name to clipboardExpand all lines: .github/styles/templates/procedure.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,8 +26,8 @@ If necessary, a paragraph or two explaining more about how things work.
26
26
27
27
This section shows you how to:
28
28
29
-
*[Verb \<what the user will do>](#verb-what-the-user-will-do)
30
-
*[Verb \<what the user will do if the procedure is cut into logical sections>](#verb-what-the-user-will-do-if-the-procedure-is-cut-into-logical-sections)
29
+
*[Verb \<what the user will do>][verb-what-the-user-will-do-link]
30
+
*[Verb \<what the user will do if the procedure is cut into logical sections>][verb-what-the-user-will-do-if-the-procedure-is-cut-into-logical-sections-link]
31
31
32
32
## Prerequisites
33
33
@@ -99,8 +99,11 @@ of the same thing:
99
99
You have \<what the user will do in this section>.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+8-6Lines changed: 8 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,7 @@ Each major doc section has a dedicated directory with `.md` files inside, repres
46
46
Beneath the front matter, describe the error and its solution in regular Markdown. You can also use any other components allowed within the docs site.
47
47
48
48
The entry shows up on the troubleshooting pages for its associated products and topics. If the page doesn't already exist, add an entry for it in the page
49
-
index, setting `type` to `placeholder`. See [Navigation tree](#navigation-tree).
49
+
index, setting `type` to `placeholder`. See [Edit the navigation hierarchy][navigation-tree-link].
50
50
51
51
## Edit the navigation hierarchy
52
52
@@ -77,7 +77,7 @@ The navigation hierarchy of a doc section is governed by `page-index/page-index.
77
77
},
78
78
```
79
79
80
-
See [Use $CLOUD_LONG section navigation][use-navigation] for reference.
80
+
See [Use Tiger Data products navigation][use-navigation] for reference.
81
81
82
82
To change the structure, add or delete pages in a section, modify the corresponding `page-index.js`. An entry in a `page-index.js` includes the following fields:
83
83
@@ -153,12 +153,14 @@ To make a documentation page more visible and clear for Google:
153
153
154
154
The previous documentation source is in the deprecated repository called [docs.timescale.com-content][legacy-source].
Copy file name to clipboardExpand all lines: _code-samples/toolkit/two-step_aggregation.md
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,13 +18,13 @@ The inner aggregate call creates a machine-readable partial form that can be use
18
18
While the one-step calling convention is easier for the simple case, it becomes much more difficult and hard to reason about for slightly more complex use-cases detailed in the next section. We wanted the calling convention to remain consistent and easy to reason about so you can take advantage of the same functions even as you start doing more complicated analyses. This also to keeps the docs consistent and prevents adding special cases everywhere.
19
19
20
20
## Why We Use Two-Step Aggregates <aid="two-step-philosophy"></a>
21
-
Interestingly, almost all $PG aggregates do a version of this [under the hood already](https://www.postgresql.org/docs/current/xaggr.html), where they have an internal state used for aggregation and then a final function that displays the output to the user.
21
+
Interestingly, almost all $PG aggregates do a version of this [under the hood already][under-the-hood-already], where they have an internal state used for aggregation and then a final function that displays the output to the user.
22
22
23
23
So why do we make this calling convention explicit?
24
24
25
25
1. It allows different accessor function calls to use the same internal state and not redo work.
26
26
2. It cleanly distinguishes the parameters that affect the aggregate and those that only affect the accessor.
27
-
3. It makes it explicit how and when aggregates can be re-aggregated or "stacked" on themselves with logically consistent results. This also helps them better integrate with [continuous aggregates](/use-timescale/latest/continuous-aggregates).
27
+
3. It makes it explicit how and when aggregates can be re-aggregated or "stacked" on themselves with logically consistent results. This also helps them better integrate with [continuous aggregates][continuous-aggregates].
28
28
4. It allows for better retrospective analysis of downsampled data in continuous aggregates.
29
29
30
30
That might have been gibberish to some, so let's unpack it a bit.
@@ -92,11 +92,11 @@ SELECT
92
92
approx_percentile(0.5, uddsketch(100, 0.01, val)) as less_accurate_median -- modify the terms for the aggregate get a new approximation
93
93
FROM foo;
94
94
```
95
-
Here we can see which parameters are for the `uddsketch` aggregate (the number of buckets and the target error), and which arguments are for`approx_percentile` (the approx_percentile we want to extract). The optimizer will correctly combine the calls for the first two `uddsketch` calls but not for the third. It is also more clear to the user what is going on, and that I can't set my target error at read time, but rather only at calculation time (this is especially helpful for understanding the behavior of [continuous aggregates][continuous-aggregates]).
95
+
Here we can see which parameters are for the `uddsketch` aggregate (the number of buckets and the target error), and which arguments are for`approx_percentile` (the approx_percentile we want to extract). The optimizer will correctly combine the calls for the first two `uddsketch` calls but not for the third. It is also more clear to the user what is going on, and that I can't set my target error at read time, but rather only at calculation time (this is especially helpful for understanding the behavior of [continuous aggregates][caggs]).
96
96
97
97
Combining all of these into one function, so we can use the one-step approach, can get unwieldy and unclear very quickly (ie imagine something like `approx_percentile_uddsketch(0.5, 1000, 0.001)`).
98
98
<br>
99
-
### Stacked aggregates and [continuous aggregate][continuous-aggregates] integration <aid="philosophy-reagg"></a>
99
+
### Stacked aggregates and [continuous aggregate][caggs] integration <aid="philosophy-reagg"></a>
100
100
Aggregates can be divided into two classes: ones that are "stackable" in their final form and ones that are not.
101
101
What I'm calling stackable aggregates are ones like `sum`, `min`, `max` etc. that can be re-aggregated on themselves at different groupings without losing their meaning, ie:
102
102
@@ -125,7 +125,7 @@ Or to say it more succinctly: the `sum` of a `sum` is the `sum` but the `avg` of
125
125
126
126
This is not to say that the `avg` of an `avg` is not a useful piece of information, it can be in some cases, but it isn't always what you want and it can be difficult to actually get the true value for non-stackable aggregates, for instance, for `avg` we can take the `count` and `sum` and divide the `sum` by the `count`, but for many aggregates this is not so obvious and for something like `percentile_agg`__LINK__ with a one-step aggregate, the user would simply have to re-implement most of the algorithm in SQL in order to get the result they want.
127
127
128
-
Two-step aggregates expose the internal, re-aggregateable form to the user so they can much more easily do this work, so we've tried to provide two-step aggregates wherever we can. This is especially useful for working with [continuous aggregates][continuous-aggregates], so if I create a continuous aggregate like so:
128
+
Two-step aggregates expose the internal, re-aggregateable form to the user so they can much more easily do this work, so we've tried to provide two-step aggregates wherever we can. This is especially useful for working with [continuous aggregates][caggs], so if I create a continuous aggregate like so:
129
129
130
130
```SQL , ignore
131
131
CREATE MATERIALIZED VIEW foo_15
@@ -151,6 +151,8 @@ GROUP BY id, time_bucket('1 day'::interval, bucket)
151
151
##### NB: There are some two-step aggregates like `tdigest`__ADD LINK? and expose and other bits...__ when we document that function where two-step aggregation can lead to more error or different results, because the algorithm is not deterministic in its re-aggregation, but we will note that clearly in the documentation when that happens, it is unusual.
152
152
153
153
### Retrospective analysis over downsampled data <aid="philosophy-retro"></a>
154
-
[Continuous aggregates][continuous-aggregates] (or separate aggregation tables powered by a cron job or a [custom job](__LINK__) ) aren't just used for speeding up queries, they're also used for [data retention](__LINK__). But this can mean that they are very difficult to modify as your data ages. Unfortunately this is also when you are learning more things about the analysis you want to do on your data. By keeping them in their raw aggregate form, the user has the flexibility to apply different accessors to do retrospective analysis. With a one-step aggregate the user needs to determine, say, which percentiles are important when we create the continous aggregate, with a two-step aggregate the user can simply determine they're going to want an approximate percentile, and then determine when doing the analysis whether they want the median, the 90th, 95th or 1st percentile. No need to modify the aggregate or try to re-calculate from data that may no longer exist in the system.
154
+
[Continuous aggregates][caggs] (or separate aggregation tables powered by a cron job or a custom jobaren't just used for speeding up queries, they're also used for data retention. But this can mean that they are very difficult to modify as your data ages. Unfortunately this is also when you are learning more things about the analysis you want to do on your data. By keeping them in their raw aggregate form, the user has the flexibility to apply different accessors to do retrospective analysis. With a one-step aggregate the user needs to determine, say, which percentiles are important when we create the continuous aggregate, with a two-step aggregate the user can simply determine they're going to want an approximate percentile, and then determine when doing the analysis whether they want the median, the 90th, 95th or 1st percentile. No need to modify the aggregate or try to re-calculate from data that may no longer exist in the system.
0 commit comments