Project: YugabyteDB (App Definition and Development / Database)
File: invocation-syntax-semantics.md

title: Window function syntax and semantics linkTitle: Invocation syntax and semantics headerTitle: Window function invocationSQL syntax and semantics description: This section specifies the syntax and semantics of the OVER clause and the WINDOW clause. You may also invoke aggregate functions t_is way. menu: v2.18: identifier: window-functions-aggregate-functions-syntax-semantics parent: window-functions weight: 20 type: docs {{< note title="The rules described in this section also govern the invocation of aggregate functions." >}} The dedicated section explains that one kind of aggregate functionso-called ordinary aggregate functions, exemplified by and can optionally be invoked using the identical syntax that you use to invoke window functions. That dedicated section has many examples. See also the sections and in the present Window functions main section. {{< /note >}} {{< note title="A note on orthography" >}} Notice these three different orthography styles: `OVER` is a keyword that names a clause. You write such a keyword in a SQL statement. is the name of a rule within the overall SQL grammar. You never type such a name in a SQL statement. It is written in bold lower case with underscores, as appropriate, between the English words. Because such a rule is always shown as a link, you can jump directly to the rule in the page. This page shows every single one of the SQL rules. It so happens that the rule starts with the keyword `WINDOW` and might therefore, according to the context of use, be referred to alternatively as the `WINDOW` clause. is a pure term of art. It is written in italic lower case with spaces, as appropriate, between the English words. You neither write it in a SQL statement nor use it to look up anything in the page. Because such a term of art is always shown as a link, you can jump directly to its definition within this "Window function invocationSQL syntax and semantics" page. {{< /note >}} The following three diagrams, , , and rule, are reproduced from the section that describes the . {{%ebnf localrefs="window_definition"%}} select_start, window_clause, fnoverwindow {{%/ebnf%}} As promised in the `SELECT` statement section, this section explains the rule and its use as the argument of either the `OVER` keyword or the `WINDOW` keyword. A can be used only at these two syntax spots, within the enclosing syntax of a subquery. {{%ebnf localrefs="frame_clause" %}} window_definition {{%/ ebnf %}} {{% ebnf %}} frame_clause, frame_bounds, frame_start, frame_end, frame_bound, frame_exclusion {{%/ ebnf %}} A window function can be invoked only at the syntax spot in a subquery that the diagram for the rule shows. An may be invoked in this way as an alternative to its more familiar invocation as a regular `SELECT` list item in conjunction with the `GROUP BY` clause. (The invocation of an aggregate function in conjunction with the `GROUP BY` clause is governed by the `ordinaryaggregatefninvocation` rule or the `withingroupaggregatefn_invocation` rule.) The number, data types, and meanings of a window function's formal parameters are function-specific. The eleven window functions are classified into functional groups, and summarized, in the two tables at the end of the section

Each entry links to the formal account of the function which also provides runnable code examples. Notice that, among the dedicated window functions (as opposed to aggregate functions that may be invoked as window functions), only takes an argument. Every other dedicated window function is invoked with an empty parentheses pair. Some aggregate functions (like, for example, ) take more than one argument. When an aggregate function is invoke as a window function, the keyword `DISTINCT` is not allowed within the parenthesized list of arguments. The attempt causes this error: ``` 0A000: DISTINCT is not implemented for window functions ``` The syntax diagram for the shows that it uses three complementary specifications: The `PARTITION BY` clause defines the maximal subsets, of what the subquery-level `WHERE` clause defines, that are operated upon, in turn, by a window function (or by an aggregate function in window mode). Tautologically, this maximal subset is referred to as the . In the limit, when the `PARTITION BY` clause is omitted, the maximal subset is identical with what the `WHERE` clause defines. The window `ORDER BY` clause defines how the rows are to be ordered within the . The defines a further narrowing of the , referred to as the . The is anchored to the current row within the . In the degenerate case, the coincides with the and is therefore insensitive to the position of the current row. In summary, the defines the as the scope within which a function's meaning (window function or aggregate function in window mode) is defined. The is then further characterized by the ordering of its rows, the extent of the , and how this moves with the current row. The `FILTER` clause's `WHERE` clause has the same syntax and semantics as it does at the regular `WHERE` clause syntax spot immediately after a subquery's `FROM` list. Notice that the `FILTER` clause is legal only for the invocation of an aggregate function. Here is an example: ```plpgsql select class, k, count(*) filter(where k%2 = 0) over (partition by class) as n from t1 order by class, k; ``` If you want to run this, then create a data set using the `ysqlsh` script that presents. Using the `FILTER` clause in the invocation of a window function causes this compilation error: ``` 0A000: FILTER is not implemented for non-aggregate window functions ``` The `PARTITION BY` clause groups the rows that the subquery defines into , which are processed separately by the window function. (This holds, too, when an aggregate function is invoked in this way.) It works similarly to a query-level `GROUP BY` clause, except that its expressions are always just expressions and cannot be output-column names or numbers. If the `PARTITION BY` clause is omitted, then all rows are treated as a single . The window `ORDER BY` clause determines the order in which the rows of a are processed by the window function. It works similarly to a query-level `ORDER BY` clause; but it cannot use output-column names or

If the window `ORDER BY` clause is omitted, then rows are processed in an unspecified order so that the results of any window function invoked in this way would be unpredictable and therefore meaningless. Aggregation functions invoked in this way might be sensitive to what the window `ORDER BY` clause says. This will be the case when, for example, the is smaller than the whole and moves with the current row. The section provides an example. The has many variants. Only one basic variant is needed in the `OVER` clause that you use to invoke a window function. The other variants are useful in the `OVER` clause that you use to invoke an aggregate function. For completeness, those variants are described on this page. The specifies the set of rows constituting the so-called . In general, this will be a subset of the rows in the current . Look at the two tables at the end of the section . The functions in the first group, , are not sensitive to what the specifies and always use all of the rows in the current . Yugabyte recommends that you therefore omit the in the `OVER` clause that you use to invoke these functions. The functions in the second group, , make obvious sense when the scope within which the specified row is found is the entire . If you have one of the very rare use cases where the output that you want is produced by a different , then specify what you want explicitly. Otherwise, because it isn't the default, you must specify that the includes the entire current like this: ``` range between unbounded preceding and unbounded following ``` Use cases where the 's many other variants are useful arise when an aggregate function is invoked using the `OVER` clause. One example is given in the section . Another example, that uses `count(*)`, is given in the code that explains the meaning of the function. Otherwise, see the main section. The can be specified in `RANGE`, `ROWS` or `GROUPS` mode; in each case, it runs from the to the . If is omitted, then the end defaults to `CURRENT ROW`. A of `UNBOUNDED PRECEDING` means that the starts with the first row of the . Similarly, a of `UNBOUNDED FOLLOWING` means that the ends with the last row of the . In `RANGE` or `GROUPS` mode, a of `CURRENT ROW` means that the starts with the first member of the current row's peer group. A peer group is a set of rows that the window `ORDER BY` clause sorts with the same rank as the current row. And a of `CURRENT ROW` means that the ends with the last row in the current row's peer group. In `ROWS` mode, `CURRENT ROW` simply means the current row. For the `PRECEDING` and `FOLLOWING` modes of the and clauses, the argument must be an expression that doesn't include any variables, aggregate functions, or window functions. The meaning of the value depends on the `RANGE | ROWS | GROUPS` mode: In `ROWS` mode, the value must be a `NOT NULL`, non-negative

This brings the meaning that the starts or ends the specified number of rows before or after the current row. In `GROUPS` mode, the value must again be a `NOT NULL`, non-negative integer. Here, this brings the meaning that the starts or ends the specified number of peer groups before or after the current row's peer group. Recall that there's always a logical requirement to include a window `ORDER BY` clause in the window definition that is used to invoke a window function. In `GROUPS` mode, whatever is your intended use of the window definition, you get this error if it doesn't include a window `ORDER BY` clause: ``` 42P20: GROUPS mode requires an ORDER BY clause ``` In `RANGE` mode, these options require that the window `ORDER BY` clause specify exactly one column. The value specifies the maximum difference between the value of that column in the current row and its value in the preceding or following rows of the . The expression must yield a value whose data type depends upon that of the ordering column. For numeric ordering columns (like `int`, `double precision`, and so on), it is typically of the same data type as the ordering column; but for date-time ordering columns it is an `interval`. For example, if the ordering column is `date` or `timestamp`, you could specify `RANGE BETWEEN '1 day' PRECEDING AND '10 days' FOLLOWING`. Here too, the value must be `NOT NULL` and non-negative. The meaning of non-negative depends on the data type. In all cases, the distance to the start and end of the is limited by the distance to the start and end of the , so that for rows near the boundaries, the might contain fewer rows than elsewhere. Notice that in both `ROWS` and `GROUPS` mode, `0 PRECEDING` and `0 FOLLOWING` is equivalent to `CURRENT ROW`. This normally holds in `RANGE` mode too, for an appropriate meaning of zero specific to the data type. The clause allows rows around the current row to be excluded from the , even if they would be included according to what the and clauses say. `EXCLUDE CURRENT ROW` excludes the current row from the . `EXCLUDE GROUP` excludes all the rows in the current row's peer group. `EXCLUDE TIES` excludes any peers of the current row, but not the current row itself. `EXCLUDE NO OTHERS` simply specifies explicitly the default behavior of not excluding the current row or its peers. Omitting the is the same as specifying ``` RANGE UNBOUNDED PRECEDING ``` and this means the same as ``` RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW ``` If the window `ORDER BY` clause is specified, then this default meaning sets the to be all rows from the start up through the last row in the current row's peer group. And if the window `ORDER BY` clause is omitted this means that all rows of the are included in the , because all rows become peers of the current row. Notes: The clause cannot be `UNBOUNDED FOLLOWING` The clause cannot be `UNBOUNDED PRECEDING`, and cannot appear before the

For example `RANGE BETWEEN CURRENT ROW AND offset PRECEDING` causes this error: ``` 42P20: frame starting from current row cannot have preceding rows ``` However, `ROWS BETWEEN 7 PRECEDING AND 8 PRECEDING` is allowed, even though it would never select any rows. If the `FILTER` clause is specified, then only the input rows for which it evaluates to true are fed to the window function; other rows are discarded. As noted above, only window aggregate functions invoked using the `OVER` clause accept a `FILTER` clause. This shows the use of a window function with an `OVER` clause that directly specifies the : ``` select ... somewindowfunction(...) over (partition by <column list 1> order by <column list 2>) as a1, ... from ... ``` Notice that the syntax spot occupied by "somewindowfunction" may be occupied only by a window function or an aggregate function. See the section for runnable examples of this syntax variant. If any other kind of function, for example "sqrt()", occupies this syntax spot, then it draws this specific compilation error: ``` 42809: OVER specified, but sqrt is not a window function nor an aggregate function ``` And if any other expression is used at this syntax spot, then it causes this generic compilation error: ``` 42601: syntax error at or near "over" ``` This shows the use of two window functions with `OVER` clauses that each reference the same that is defined separately in a `WINDOW` clause. ``` select ... windowfn1(...) over w as a1, windowfn2(...) over w as a2, ... from ... window w as ( partition by <column list 1> -- PARTITION BY clause order by <column list 2> -- ORDER BY clause range between unbounded preceding and unbounded following -- frame_clause ) ... ``` For a runnable example of this syntax variant, see . Notice that the syntax rules allow both this: ``` windowfn1(...) over w as a1 ``` and this: ``` windowfn1(...) over (w) as a1 ``` The parentheses around the window's identifier convey no meaning, Yugabyte recommends that you don't use this form because doing so will make anybody who reads your code wonder if it does convey a meaning. This shows how a generic that is defined in a `WINDOW` clause is specialized in a particular `OVER` clause that references it. ``` select ... (window_fn(...) over w) as a1, (aggregatefn1(...) over (w range between unbounded preceding and unbounded following)) as a2, (aggregatefn1(...) over (w range between unbounded preceding and current row)) as a3, ... from ... window w as (partition by <column list 1> order by <column list 2>) ... ``` This shows how the specialization technique that the third example showed can be used in successively in the `WINDOW` clause. ``` select ... (window_fn(...) over w1) as a1, (aggregatefn1(...) over w2) as a2, (aggregatefn1(...) over w3) as a3, ... from ... window w1 as (partition by <column list 1> order by <column list 2>), w2 as (w1 range between unbounded preceding and unbounded following), w3 as (w1 range between unbounded preceding and current row) ``` For a runnable example of this fourth syntax variant, see .