Merge pull request #211 from stackql/feature/web-content-updates

updated window diagrams

Author: jeffreyaven

docs/language-spec/functions/aggregate/avg.md

@@ -63,4 +63,25 @@ AND zone = 'australia-southeast1-a'
 GROUP BY json_extract(tags, '$.instanceType');
 ```
 
+### Use `AVG` as a window function to calculate moving averages
+
+```sql
+-- Calculate moving average of commit activity
+WITH weekly_totals AS (
+    SELECT
+        week,
+        SUM(json_each.value) as commits_this_week
+    FROM github.repos.stats_commit_activity, JSON_EACH(days)
+    WHERE owner = 'stackql'
+      AND repo = 'stackql'
+    GROUP BY week
+)
+SELECT
+    week,
+    commits_this_week,
+    ROUND(AVG(commits_this_week) OVER (ORDER BY week ROWS BETWEEN 3 PRECEDING AND CURRENT ROW), 1) as four_week_moving_avg
+FROM weekly_totals
+ORDER BY week;
+```
+
 For more information, see [https://www.sqlite.org/lang_aggfunc.html#avg](https://www.sqlite.org/lang_aggfunc.html#avg).

docs/language-spec/functions/aggregate/count.md

@@ -61,4 +61,21 @@ AND zone = 'australia-southeast1-a'
 GROUP BY json_extract(tags, '$.instanceType');
 ```
 
+### Use `COUNT` as a window function to calculate cumulative counts
+
+```sql
+-- Track cumulative issue counts over time
+SELECT
+    number,
+    title,
+    state,
+    created_at,
+    COUNT(*) OVER (ORDER BY created_at) as cumulative_issues,
+    COUNT(*) OVER (PARTITION BY state ORDER BY created_at) as cumulative_by_state
+FROM github.issues.issues
+WHERE owner = 'stackql'
+  AND repo = 'stackql'
+ORDER BY created_at;
+```
+
 For more information, see [https://www.sqlite.org/lang_aggfunc.html#count](https://www.sqlite.org/lang_aggfunc.html#count).

docs/language-spec/functions/aggregate/max.md

@@ -91,4 +91,20 @@ WHERE project = 'stackql-demo'
 AND zone = 'australia-southeast1-a';
 ```
 
+### Use `MAX` as a window function to find maximum values within partitions
+
+```sql
+-- Find the most recent issue in each state
+SELECT
+    number,
+    title,
+    state,
+    created_at,
+    MAX(created_at) OVER (PARTITION BY state) as latest_in_state
+FROM github.issues.issues
+WHERE owner = 'stackql'
+  AND repo = 'stackql'
+ORDER BY state, created_at DESC;
+```
+
 For more information, see [https://www.sqlite.org/lang_aggfunc.html#max_agg](https://www.sqlite.org/lang_aggfunc.html#max_agg) or [https://www.sqlite.org/lang_corefunc.html#max_scalar](https://www.sqlite.org/lang_corefunc.html#max_scalar)

docs/language-spec/functions/aggregate/min.md

@@ -91,4 +91,20 @@ WHERE project = 'stackql-demo'
 AND zone = 'australia-southeast1-a';
 ```
 
+### Use `MIN` as a window function to find minimum values within partitions
+
+```sql
+-- Find the earliest issue in each state
+SELECT
+    number,
+    title,
+    state,
+    created_at,
+    MIN(created_at) OVER (PARTITION BY state) as earliest_in_state
+FROM github.issues.issues
+WHERE owner = 'stackql'
+  AND repo = 'stackql'
+ORDER BY state, created_at;
+```
+
 For more information, see [https://www.sqlite.org/lang_aggfunc.html#min_agg](https://www.sqlite.org/lang_aggfunc.html#min_agg) or [https://www.sqlite.org/lang_corefunc.html#min_scalar](https://www.sqlite.org/lang_corefunc.html#min_scalar)

docs/language-spec/functions/aggregate/sum.md

@@ -69,4 +69,19 @@ AND zone = 'australia-southeast1-a'
 GROUP BY json_extract(tags, '$.instanceType');
 ```
 
+### Use `SUM` as a window function to calculate running totals
+
+```sql
+-- Calculate running total and percentage of contributions
+SELECT
+    login,
+    contributions,
+    SUM(contributions) OVER (ORDER BY contributions DESC) as running_total,
+    SUM(contributions) OVER () as total_contributions,
+    ROUND(100.0 * contributions / SUM(contributions) OVER (), 2) as pct_of_total
+FROM github.repos.contributors
+WHERE owner = 'stackql'
+  AND repo = 'stackql';
+```
+
 For more information, see [https://www.sqlite.org/lang_aggfunc.html#sumunc](https://www.sqlite.org/lang_aggfunc.html#sumunc).

docs/language-spec/select.md

@@ -32,11 +32,12 @@ type="select"
 
 ```sql
 [ WITH [ RECURSIVE ] <cteName> [ ( <columnList> ) ] AS ( <selectStatement> ) [, ...] ]
-SELECT { * | <fieldList> }
+SELECT { * | <fieldList> | <windowFunctionCall> [ AS <alias> ] }
 FROM { <multipartIdentifier> | <joinStatement(s)> }
 [ WHERE <expression> ]
 [ GROUP BY <fieldList> ]
 [ HAVING <expression> ]
+[ WINDOW <windowName> AS ( <windowSpec> ) [, ...] ]
 [ ORDER BY <fieldList> [ ASC | DESC ] ]
 [ LIMIT <integer> ]
 [ UNION <selectStatement> ];

docs/language-spec/windowing_functions.md

@@ -10,6 +10,7 @@ keywords:
 description: Query and Deploy Cloud Infrastructure and Resources using SQL
 image: "/img/stackql-featured-image.png"
 ---
+import RailroadDiagram from '/js/RailroadDiagram/RailroadDiagram.js';
 
 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.
 
@@ -26,21 +27,59 @@ Window functions use the `OVER` clause to define the window specification:
 SELECT <windowFunction> OVER ( <windowSpec> ) FROM <multipartIdentifier>;
 ```
 
-*windowSpec::=*
+*windowFunctionCall::=*
+
+<RailroadDiagram 
+type="windowFunctionCall"
+/>
+
+### Window Function
+
+Window functions are specialized functions that perform calculations across a set of rows defined by the window specification. They can be either dedicated window functions (like `ROW_NUMBER` or `LAG`) or aggregate functions (like `SUM` or `COUNT`) used with an `OVER` clause.
 
 ```sql
-[ PARTITION BY <fieldList> ] [ ORDER BY <fieldList> [ ASC | DESC ] ]
-[ ROWS BETWEEN <frameStart> AND <frameEnd> ]
+{ <aggregateFunction> | ROW_NUMBER() | RANK() | DENSE_RANK() | PERCENT_RANK() 
+  | CUME_DIST() | NTILE(<int>) | LAG(<expr> [,<offset> [,<default>]]) 
+  | LEAD(<expr> [,<offset> [,<default>]]) | FIRST_VALUE(<expr>) 
+  | LAST_VALUE(<expr>) | NTH_VALUE(<expr>, <int>) }
+```  
+
+*windowFunction::=*
+
+<RailroadDiagram 
+type="windowFunction"
+/>
+
+### Window Specification
+
+The window specification defines how rows are partitioned, ordered, and framed for the window function calculation. `PARTITION BY` divides rows into groups, `ORDER BY` determines the sequence within each partition, and the optional frame clause specifies which rows relative to the current row are included in the calculation.
+
+```sql
+[ <windowName> ]
+[ PARTITION BY <fieldList> ]
+[ ORDER BY <fieldList> [ ASC | DESC ] ]
+[ { ROWS | RANGE | GROUPS } 
+    { UNBOUNDED PRECEDING | <int> PRECEDING | CURRENT ROW }
+  | { ROWS | RANGE | GROUPS } BETWEEN 
+    { UNBOUNDED PRECEDING | <int> PRECEDING | CURRENT ROW | <int> FOLLOWING }
+    AND
+    { <int> PRECEDING | CURRENT ROW | <int> FOLLOWING | UNBOUNDED FOLLOWING } ]
 ```
 
+*windowSpec::=*
+
+<RailroadDiagram 
+type="windowSpec"
+/>
+
 ## Available Window Functions
 
 | Category | Functions |
 |----------|-----------|
-| **Ranking** | `ROW_NUMBER()`, `RANK()`, `DENSE_RANK()`, `NTILE()` |
-| **Offset** | `LAG()`, `LEAD()`, `FIRST_VALUE()`, `LAST_VALUE()`, `NTH_VALUE()` |
-| **Distribution** | `PERCENT_RANK()`, `CUME_DIST()` |
-| **Aggregate** | `SUM()`, `COUNT()`, `AVG()`, `MIN()`, `MAX()` with `OVER` clause |
+| **Ranking** | [__`ROW_NUMBER()`__](/docs/language-spec/functions/window/row_number), [__`RANK()`__](/docs/language-spec/functions/window/rank), [__`DENSE_RANK()`__](/docs/language-spec/functions/window/dense_rank), [__`NTILE()`__](/docs/language-spec/functions/window/ntile) |
+| **Offset** | [__`LAG()`__](/docs/language-spec/functions/window/lag), [__`LEAD()`__](/docs/language-spec/functions/window/lead), [__`FIRST_VALUE()`__](/docs/language-spec/functions/window/first_value), [__`LAST_VALUE()`__](/docs/language-spec/functions/window/last_value), [__`NTH_VALUE()`__](/docs/language-spec/functions/window/nth_value) |
+| **Distribution** | [__`PERCENT_RANK()`__](/docs/language-spec/functions/window/percent_rank), [__`CUME_DIST()`__](/docs/language-spec/functions/window/cume_dist) |
+| **Aggregate** | [__`SUM()`__](/docs/language-spec/functions/aggregate/sum), [__`COUNT()`__](/docs/language-spec/functions/aggregate/count), [__`AVG()`__](/docs/language-spec/functions/aggregate/avg), [__`MIN()`__](/docs/language-spec/functions/aggregate/min), [__`MAX()`__](/docs/language-spec/functions/aggregate/max) with the __`OVER`__ clause |
 
 * * *
 

docs/language-spec/with.md

@@ -24,7 +24,13 @@ See also:
 *withClause::=*
 
 <RailroadDiagram
-type="with"
+type="withClause"
+/>
+
+*cteDefinition::=*
+
+<RailroadDiagram
+type="cteDefinition"
 />
 
 &nbsp;