Skip to content

Commit 848d2b7

Browse files
jeffreyavenjeffreyaven
authored
Merge pull request #210 from stackql/claude/document-window-functions-ctes-019g6NmiVwgRwnB1ADS83M2f
move window function examples to dedicated windowing_functions.md
2 parents f4747f4 + b222fef commit 848d2b7

File tree

7 files changed

+184
-119
lines changed

7 files changed

+184
-119
lines changed

‎docs/language-spec/functions/window/dense_rank.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ WHERE owner = 'stackql'
5757
ORDER BY contributions DESC;
5858
```
5959

60-
### Compare DENSE_RANK with RANK and ROW_NUMBER
60+
### Compare `DENSE_RANK` with `RANK` and `ROW_NUMBER`
6161

6262
```sql
6363
-- Compare RANK vs DENSE_RANK vs ROW_NUMBER for contributors

‎docs/language-spec/functions/window/rank.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ WHERE owner = 'stackql'
5555
AND repo = 'stackql';
5656
```
5757

58-
### Compare RANK with DENSE_RANK and ROW_NUMBER
58+
### Compare `RANK` with `DENSE_RANK` and `ROW_NUMBER`
5959

6060
```sql
6161
-- Compare RANK vs DENSE_RANK vs ROW_NUMBER for contributors
@@ -70,7 +70,7 @@ WHERE owner = 'stackql'
7070
AND repo = 'stackql';
7171
```
7272

73-
### Rank contributors within each repository using PARTITION BY
73+
### Rank contributors within each repository using `PARTITION BY`
7474

7575
```sql
7676
-- Rank contributors within each repo

‎docs/language-spec/functions/window/row_number.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ WHERE owner = 'stackql'
6969
ORDER BY created_at;
7070
```
7171

72-
### Compare ROW_NUMBER with RANK and DENSE_RANK
72+
### Compare `ROW_NUMBER` with `RANK` and `DENSE_RANK`
7373

7474
```sql
7575
-- Compare RANK vs DENSE_RANK vs ROW_NUMBER for contributors

‎docs/language-spec/select.md‎

Lines changed: 3 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import RailroadDiagram from '/js/RailroadDiagram/RailroadDiagram.js';
1515
Returns an instance or instances of a resource.
1616

1717
See also:
18-
[[ StackQL Resource Hierarchy ]](/docs/getting-started/resource-hierarchy) [[` WITH (CTEs) `]](/docs/language-spec/with) [[ Window Functions ]](/docs/language-spec/functions/window/row_number)
18+
[[ StackQL Resource Hierarchy ]](/docs/getting-started/resource-hierarchy) [[` WITH (CTEs) `]](/docs/language-spec/with) [[` Window Functions `]](/docs/language-spec/windowing_functions)
1919

2020
* * *
2121

@@ -32,7 +32,7 @@ type="select"
3232

3333
```sql
3434
[ WITH [ RECURSIVE ] <cteName> [ ( <columnList> ) ] AS ( <selectStatement> ) [, ...] ]
35-
SELECT { * | <fieldList> | <windowFunction> OVER ( <windowSpec> ) }
35+
SELECT { * | <fieldList> }
3636
FROM { <multipartIdentifier> | <joinStatement(s)> }
3737
[ WHERE <expression> ]
3838
[ GROUP BY <fieldList> ]
@@ -42,13 +42,6 @@ FROM { <multipartIdentifier> | <joinStatement(s)> }
4242
[ UNION <selectStatement> ];
4343
```
4444

45-
*windowSpec::=*
46-
47-
```sql
48-
[ PARTITION BY <fieldList> ] [ ORDER BY <fieldList> [ ASC | DESC ] ]
49-
[ ROWS BETWEEN <frameStart> AND <frameEnd> ]
50-
```
51-
5245
* * *
5346

5447
## Examples
@@ -134,81 +127,7 @@ AND resourceGroupName = 'vmss-flex'
134127
AND JSON_EXTRACT(c.properties,'$.priority') is null;
135128
```
136129

137-
### Using Window Functions to rank results
138-
139-
Use window functions like `ROW_NUMBER`, `RANK`, and `DENSE_RANK` to assign rankings to rows based on column values.
140-
141-
```sql
142-
-- Rank contributors by contribution count
143-
SELECT
144-
login,
145-
contributions,
146-
ROW_NUMBER() OVER (ORDER BY contributions DESC) as row_num,
147-
RANK() OVER (ORDER BY contributions DESC) as rank,
148-
DENSE_RANK() OVER (ORDER BY contributions DESC) as dense_rank
149-
FROM github.repos.contributors
150-
WHERE owner = 'stackql'
151-
AND repo = 'stackql';
152-
```
153-
154-
For more information on window functions, see [Window Functions](/docs/language-spec/functions/window/row_number).
155-
156-
### Using Window Functions for running totals and percentages
157-
158-
Aggregate functions like `SUM` and `COUNT` can be used as window functions to calculate running totals and percentages.
159-
160-
```sql
161-
-- Running total and percentage of contributions
162-
SELECT
163-
login,
164-
contributions,
165-
SUM(contributions) OVER (ORDER BY contributions DESC) as running_total,
166-
SUM(contributions) OVER () as total_contributions,
167-
ROUND(100.0 * contributions / SUM(contributions) OVER (), 2) as pct_of_total
168-
FROM github.repos.contributors
169-
WHERE owner = 'stackql'
170-
AND repo = 'stackql';
171-
```
172-
173-
### Using `LAG` and `LEAD` to compare rows
174-
175-
Use `LAG` and `LEAD` window functions to access values from previous or subsequent rows.
176-
177-
```sql
178-
-- Compare each release to previous release
179-
SELECT
180-
tag_name,
181-
name,
182-
published_at,
183-
LAG(tag_name, 1) OVER (ORDER BY published_at) as previous_release,
184-
LEAD(tag_name, 1) OVER (ORDER BY published_at) as next_release,
185-
julianday(published_at) - julianday(LAG(published_at, 1) OVER (ORDER BY published_at)) as days_since_last_release
186-
FROM github.repos.releases
187-
WHERE owner = 'stackql'
188-
AND repo = 'stackql'
189-
ORDER BY published_at;
190-
```
191-
192-
### Using `NTILE` to create groups
193-
194-
Use `NTILE` to divide rows into a specified number of groups.
195-
196-
```sql
197-
-- Group contributors into quartiles
198-
SELECT
199-
login,
200-
contributions,
201-
NTILE(4) OVER (ORDER BY contributions DESC) as quartile,
202-
CASE NTILE(4) OVER (ORDER BY contributions DESC)
203-
WHEN 1 THEN 'Top Contributors'
204-
WHEN 2 THEN 'Active Contributors'
205-
WHEN 3 THEN 'Moderate Contributors'
206-
WHEN 4 THEN 'Occasional Contributors'
207-
END as tier
208-
FROM github.repos.contributors
209-
WHERE owner = 'stackql'
210-
AND repo = 'stackql';
211-
```
130+
For more information on window functions, see [Window Functions](/docs/language-spec/windowing_functions).
212131

213132
### Using Common Table Expressions (CTEs) with `WITH`
214133

@@ -240,27 +159,3 @@ ORDER BY total_contributions DESC;
240159
```
241160

242161
For more information on CTEs, see [WITH (CTEs)](/docs/language-spec/with).
243-
244-
### Using CTEs with Window Functions for analytics
245-
246-
Combine CTEs with window functions for advanced analytics queries.
247-
248-
```sql
249-
-- Calculate moving average of commit activity
250-
WITH weekly_totals AS (
251-
SELECT
252-
week,
253-
SUM(json_each.value) as commits_this_week
254-
FROM github.repos.stats_commit_activity, JSON_EACH(days)
255-
WHERE owner = 'stackql'
256-
AND repo = 'stackql'
257-
GROUP BY week
258-
)
259-
SELECT
260-
week,
261-
commits_this_week,
262-
ROUND(AVG(commits_this_week) OVER (ORDER BY week ROWS BETWEEN 3 PRECEDING AND CURRENT ROW), 1) as four_week_moving_avg,
263-
SUM(commits_this_week) OVER (ORDER BY week) as cumulative_commits
264-
FROM weekly_totals
265-
ORDER BY week;
266-
```

‎docs/language-spec/windowing_functions.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Window Functions
3+
hide_title: false
4+
hide_table_of_contents: false
5+
keywords:
6+
- stackql
7+
- infrastructure-as-code
8+
- configuration-as-data
9+
- cloud inventory
10+
description: Query and Deploy Cloud Infrastructure and Resources using SQL
11+
image: "/img/stackql-featured-image.png"
12+
---
13+
14+
Window functions perform calculations across a set of rows that are related to the current row. Unlike aggregate functions that return a single result for a group of rows, window functions return a value for each row while considering a "window" of related rows.
15+
16+
See also:
17+
[[` SELECT `]](/docs/language-spec/select) [[` WITH (CTEs) `]](/docs/language-spec/with) [[ Window Function Reference ]](/docs/language-spec/functions/window/row_number)
18+
19+
* * *
20+
21+
## Syntax
22+
23+
Window functions use the `OVER` clause to define the window specification:
24+
25+
```sql
26+
SELECT <windowFunction> OVER ( <windowSpec> ) FROM <multipartIdentifier>;
27+
```
28+
29+
*windowSpec::=*
30+
31+
```sql
32+
[ PARTITION BY <fieldList> ] [ ORDER BY <fieldList> [ ASC | DESC ] ]
33+
[ ROWS BETWEEN <frameStart> AND <frameEnd> ]
34+
```
35+
36+
## Available Window Functions
37+
38+
| Category | Functions |
39+
|----------|-----------|
40+
| **Ranking** | `ROW_NUMBER()`, `RANK()`, `DENSE_RANK()`, `NTILE()` |
41+
| **Offset** | `LAG()`, `LEAD()`, `FIRST_VALUE()`, `LAST_VALUE()`, `NTH_VALUE()` |
42+
| **Distribution** | `PERCENT_RANK()`, `CUME_DIST()` |
43+
| **Aggregate** | `SUM()`, `COUNT()`, `AVG()`, `MIN()`, `MAX()` with `OVER` clause |
44+
45+
* * *
46+
47+
## Examples
48+
49+
### Ranking with `ROW_NUMBER`, `RANK`, and `DENSE_RANK`
50+
51+
Use ranking functions to assign rankings to rows based on column values.
52+
53+
```sql
54+
-- Rank contributors by contribution count
55+
SELECT
56+
login,
57+
contributions,
58+
ROW_NUMBER() OVER (ORDER BY contributions DESC) as row_num,
59+
RANK() OVER (ORDER BY contributions DESC) as rank,
60+
DENSE_RANK() OVER (ORDER BY contributions DESC) as dense_rank
61+
FROM github.repos.contributors
62+
WHERE owner = 'stackql'
63+
AND repo = 'stackql';
64+
```
65+
66+
### Running totals and percentages
67+
68+
Aggregate functions like `SUM` and `COUNT` can be used as window functions to calculate running totals and percentages.
69+
70+
```sql
71+
-- Running total and percentage of contributions
72+
SELECT
73+
login,
74+
contributions,
75+
SUM(contributions) OVER (ORDER BY contributions DESC) as running_total,
76+
SUM(contributions) OVER () as total_contributions,
77+
ROUND(100.0 * contributions / SUM(contributions) OVER (), 2) as pct_of_total
78+
FROM github.repos.contributors
79+
WHERE owner = 'stackql'
80+
AND repo = 'stackql';
81+
```
82+
83+
### Comparing rows with `LAG` and `LEAD`
84+
85+
Use `LAG` and `LEAD` to access values from previous or subsequent rows.
86+
87+
```sql
88+
-- Compare each release to previous release
89+
SELECT
90+
tag_name,
91+
name,
92+
published_at,
93+
LAG(tag_name, 1) OVER (ORDER BY published_at) as previous_release,
94+
LEAD(tag_name, 1) OVER (ORDER BY published_at) as next_release,
95+
julianday(published_at) - julianday(LAG(published_at, 1) OVER (ORDER BY published_at)) as days_since_last_release
96+
FROM github.repos.releases
97+
WHERE owner = 'stackql'
98+
AND repo = 'stackql'
99+
ORDER BY published_at;
100+
```
101+
102+
### Creating groups with `NTILE`
103+
104+
Use `NTILE` to divide rows into a specified number of groups.
105+
106+
```sql
107+
-- Group contributors into quartiles
108+
SELECT
109+
login,
110+
contributions,
111+
NTILE(4) OVER (ORDER BY contributions DESC) as quartile,
112+
CASE NTILE(4) OVER (ORDER BY contributions DESC)
113+
WHEN 1 THEN 'Top Contributors'
114+
WHEN 2 THEN 'Active Contributors'
115+
WHEN 3 THEN 'Moderate Contributors'
116+
WHEN 4 THEN 'Occasional Contributors'
117+
END as tier
118+
FROM github.repos.contributors
119+
WHERE owner = 'stackql'
120+
AND repo = 'stackql';
121+
```
122+
123+
### Using `PARTITION BY` for grouped analysis
124+
125+
Use `PARTITION BY` to perform window calculations within groups.
126+
127+
```sql
128+
-- Track cumulative issues by state
129+
SELECT
130+
number,
131+
title,
132+
state,
133+
created_at,
134+
ROW_NUMBER() OVER (ORDER BY created_at) as issue_sequence,
135+
COUNT(*) OVER (ORDER BY created_at) as cumulative_issues,
136+
COUNT(*) OVER (PARTITION BY state ORDER BY created_at) as cumulative_by_state
137+
FROM github.issues.issues
138+
WHERE owner = 'stackql'
139+
AND repo = 'stackql'
140+
ORDER BY created_at;
141+
```
142+
143+
### Using window frames
144+
145+
Specify a frame clause to control which rows are included in the window calculation.
146+
147+
```sql
148+
-- Calculate moving average of commit activity
149+
WITH weekly_totals AS (
150+
SELECT
151+
week,
152+
SUM(json_each.value) as commits_this_week
153+
FROM github.repos.stats_commit_activity, JSON_EACH(days)
154+
WHERE owner = 'stackql'
155+
AND repo = 'stackql'
156+
GROUP BY week
157+
)
158+
SELECT
159+
week,
160+
commits_this_week,
161+
ROUND(AVG(commits_this_week) OVER (ORDER BY week ROWS BETWEEN 3 PRECEDING AND CURRENT ROW), 1) as four_week_moving_avg,
162+
SUM(commits_this_week) OVER (ORDER BY week) as cumulative_commits
163+
FROM weekly_totals
164+
ORDER BY week;
165+
```
166+
167+
For detailed documentation on each window function, see the [Window Function Reference](/docs/language-spec/functions/window/row_number).
168+
169+
For more information, see [https://sqlite.org/windowfunctions.html](https://sqlite.org/windowfunctions.html).

‎docs/language-spec/with.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ FROM weekly_totals
8686
ORDER BY week;
8787
```
8888

89-
### Combining data from multiple sources with UNION ALL
89+
### Combining data from multiple sources with `UNION ALL`
9090

9191
CTEs are useful for combining data from multiple sources before performing analysis.
9292

‎sidebars.js‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,25 +46,26 @@ const sidebars = {
4646
label: 'Language Specification',
4747
items: [
4848
'language-spec/select',
49-
'language-spec/with',
5049
'language-spec/insert',
5150
'language-spec/update',
52-
'language-spec/replace',
5351
'language-spec/delete',
52+
'language-spec/replace',
5453
'language-spec/show',
5554
'language-spec/describe',
5655
'language-spec/exec',
5756
'language-spec/createview',
5857
'language-spec/refreshview',
59-
'language-spec/dropview',
58+
'language-spec/dropview',
59+
'language-spec/with',
6060
'language-spec/registry',
61+
'language-spec/windowing_functions',
6162
{
6263
type: 'category',
63-
label: 'Functions',
64+
label: 'Built-in Functions',
6465
items: [{type: 'autogenerated', dirName: 'language-spec/functions'}]
65-
},
66-
'language-spec/lexical-structure',
66+
},
6767
'language-spec/data-types',
68+
'language-spec/lexical-structure',
6869
'language-spec/keywords',
6970
'language-spec/utility-commands',
7071
]

0 commit comments

Comments
 (0)