Supported Versions: Current (16) / 15 / 14 / 13 / 12
Development Versions: devel
Unsupported versions: 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
This documentation is for an unsupported version of PostgreSQL.
You may want to view the same page for the current version, or one of the other supported versions listed above instead.

1.3. Value Expressions

Value expressions are used in a variety of contexts, such as in the target list of the SELECT command, as new column values in INSERT or UPDATE, or in search conditions in a number of commands. The result of a value expression is sometimes called a scalar, to distinguish it from the result of a table expression (which is a table). Value expressions are therefore also called scalar expressions (or even simply expressions). The expression syntax allows the calculation of values from primitive parts using arithmetic, logical, set, and other operations.

A value expression is one of the following:

  • A constant or literal value; see Section 1.1.2.

  • A column reference

  • An operator invocation:

    expression operator expression (binary infix operator)
    operator expression (unary prefix operator)
    expression operator (unary postfix operator)
    where operator follows the syntax rules of Section 1.1.3 or is one of the tokens AND, OR, and NOT. Which particular operators exist and whether they are unary or binary depends on what operators have been defined by the system or the user. Chapter 4 describes the built-in operators.
  • ( expression )
    
    Parentheses are used to group subexpressions and override precedence.
  • A positional parameter reference, in the body of a function declaration.

  • A function call

  • An aggregate expression

  • A scalar subquery. This is an ordinary SELECT in parentheses that returns exactly one row with one column. It is an error to use a subquery that returns more than one row or more than one column in the context of a value expression.

In addition to this list, there are a number of constructs that can be classified as an expression but do not follow any general syntax rules. These generally have the semantics of a function or operator and are explained in the appropriate location in Chapter 4. An example is the IS NULL clause.

We have already discussed constants in Section 1.1.2. The following sections discuss the remaining options.

1.3.1. Column References

A column can be referenced in the form:

correlation.columnname `['subscript`]'
correlation is either the name of a table, an alias for a table defined by means of a FROM clause, or the keyword NEW or OLD. (NEW and OLD can only appear in the action portion of a rule, while other correlation names can be used in any SQL statement.) The correlation name can be omitted if the column name is unique across all the tables being used in the current query. If column is of an array type, then the optional subscript selects a specific element in the array. If no subscript is provided, then the whole array is selected. Refer to the description of the particular commands in the PostgreSQL Reference Manual for the allowed syntax in each case.

1.3.2. Positional Parameters

A positional parameter reference is used to indicate a parameter in an SQL function. Typically this is used in SQL function definition statements. The form of a parameter is:

$number

For example, consider the definition of a function, dept, as

CREATE FUNCTION dept (text) RETURNS dept
  AS 'select * from dept where name = $1'
  LANGUAGE 'sql';
Here the $1 will be replaced by the first function argument when the function is invoked.

1.3.3. Function Calls

The syntax for a function call is the name of a function (which is subject to the syntax rules for identifiers of Section 1.1.1), followed by its argument list enclosed in parentheses:

function ([expression [, expression ... ]] )

For example, the following computes the square root of 2:

sqrt(2)

The list of built-in functions is in Chapter 4. Other functions may be added by the user.

1.3.4. Aggregate Expressions

An aggregate expression represents the application of an aggregate function across the rows selected by a query. An aggregate function reduces multiple inputs to a single output value, such as the sum or average of the inputs. The syntax of an aggregate expression is one of the following:

aggregate_name (expression)
aggregate_name (ALL expression)
aggregate_name (DISTINCT expression)
aggregate_name ( * )
where aggregate_name is a previously defined aggregate, and expression is any expression that does not itself contain an aggregate expression.

The first form of aggregate expression invokes the aggregate across all input rows for which the given expression yields a non-NULL value. (Actually, it is up to the aggregate function whether to ignore NULLs or not --- but all the standard ones do.) The second form is the same as the first, since ALL is the default. The third form invokes the aggregate for all distinct non-NULL values of the expression found in the input rows. The last form invokes the aggregate once for each input row regardless of NULL or non-NULL values; since no particular input value is specified, it is generally only useful for the count() aggregate function.

For example, count(*) yields the total number of input rows; count(f1) yields the number of input rows in which f1 is non-NULL; count(distinct f1) yields the number of distinct non-NULL values of f1.

The predefined aggregate functions are described in Section 4.12. Other aggregate functions may be added by the user.