Functions & Operators

This page explains BigQuery expressions, including functions and operators.

Function call syntax

Functions have a function name, can accept zero or more arguments and use function call syntax:

function_name( [arg1][, ...] )

Notation:

• A comma followed by an ellipsis within square brackets "[, ... ]" indicates that the preceding item can repeat in a comma-separated list.

The following rules apply to all functions unless explicitly indicated otherwise in the function description:

• For functions that accept numeric types, if one operand is a floating point operand and the other operand is another numeric type, both operands are converted to FLOAT64 before the function is evaluated.
• If an operand is NULL, the result is NULL, with the exception of the IS operators.
• For functions that are time zone sensitive (as indicated in the function description), the default time zone, UTC, is used if a time zone is not specified.

Conversion rules

"Conversion" includes, but is not limited to, casting and coercion.

• Casting is explicit conversion and uses the CAST() function.
• Coercion is implicit conversion, which BigQuery performs automatically under the conditions described below.
• There is a third group of conversion functions that have their own function names, such as UNIX_DATE().

The table below summarizes all possible CAST and coercion possibilities for BigQuery data types. "Coercion To" applies to all expressions of a given data type (e.g. a column) , but literals and parameters can also be coerced. See Literal Coercion and Parameter Coercion for details.

Casting

Syntax:

CAST(expr AS typename)

Cast syntax is used in a query to indicate that the result type of an expression should be converted to some other type.

Example:

CAST(x=1 AS STRING)

This results in "true" if x is 1, "false" for any other non-NULL value, and NULL if x is NULL.

Casts between supported types that do not successfully map from the original value to the target domain produce runtime errors. For example, casting BYTES to STRING where the byte sequence is not valid UTF-8 results in a runtime error.

When casting an expression x of the following types, these rules apply:

Safe casting

When using CAST, a query can fail if BigQuery is unable to perform the cast. For example, the following query generates an error:

SELECT CAST("apple" AS INT64) AS not_a_number;

If you want to protect your queries from these types of errors, you can use SAFE_CAST. SAFE_CAST is identical to CAST, except it returns NULL instead of raising an error.

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

If you are casting from bytes to strings, you can also use the function, SAFE_CONVERT_BYTES_TO_STRING. Any invalid UTF-8 characters are replaced with the unicode replacement character, U+FFFD. See SAFE_CONVERT_BYTES_TO_STRING for more information.

Casting hex strings to integers

If you are working with hex strings (0x123), you can cast those strings as integers:

SELECT '0x123' as hex_value, CAST('0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | 291        |
+-----------+------------+

SELECT '0x123' as hex_value, CAST('-0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | -291       |
+-----------+------------+

Casting date types

BigQuery supports casting date types to/from strings as follows:

CAST(date_expression AS STRING)
CAST(string_expression AS DATE)

Casting from a date type to a string is independent of time zone and is of the form YYYY-MM-DD. When casting from string to date, the string must conform to the supported date literal format, and is independent of time zone. If the string expression is invalid or represents a date that is outside of the supported min/max range, then an error is produced.

Casting timestamp types

BigQuery supports casting timestamp types to/from strings as follows:

CAST(timestamp_expression AS STRING)
CAST(string_expression AS TIMESTAMP)

When casting from timestamp types to string, the timestamp is interpreted using the default time zone, UTC. The number of subsecond digits produced depends on the number of trailing zeroes in the subsecond part: the CAST function will truncate zero, three, or six digits.

When casting from string to a timestamp, string_expression must conform to the supported timestamp literal formats, or else a runtime error occurs. The string_expression may itself contain a time_zone—see time zones. If there is a time zone in the string_expression, that time zone is used for conversion, otherwise the default time zone, UTC, is used. If the string has fewer than six digits, then it is implicitly widened.

An error is produced if the string_expression is invalid, has more than six subsecond digits (i.e. precision greater than microseconds), or represents a time outside of the supported timestamp range.

Casting between date and timestamp types

BigQuery supports casting between date and timestamp types as follows:

CAST(date_expression AS TIMESTAMP)
CAST(timestamp_expression AS DATE)

Casting from a date to a timestamp interprets date_expression as of midnight (start of the day) in the default time zone, UTC. Casting from a timestamp to date effectively truncates the timestamp as of the default time zone.

Coercion

BigQuery coerces the result type of an expression to another type if needed to match function signatures. For example, if function func() is defined to take a single argument of type INT64 and an expression is used as an argument that has a result type of FLOAT64, then the result of the expression will be coerced to INT64 type before func() is computed.

Literal coercion

BigQuery supports the following literal coercions:

Literal coercion is needed when the actual literal type is different from the type expected by the function in question. For example, if function func() takes a DATE argument, then the expression func("2014-09-27") is valid because the STRING literal "2014-09-27" is coerced to DATE.

Literal conversion is evaluated at analysis time, and gives an error if the input literal cannot be converted successfully to the target type.

Note: String literals do not coerce to numeric types.

Parameter coercion

BigQuery supports the following parameter coercions:

If the parameter value cannot be coerced successfully to the target type, an error is provided.

Additional conversion functions

BigQuery provides the following additional conversion functions:

• DATE functions
• DATETIME functions
• TIME functions
• TIMESTAMP functions

Aggregate functions

An aggregate function is a function that performs a calculation on a set of values. COUNT, MIN and MAX are examples of aggregate functions.

SELECT COUNT(*) as total_count, COUNT(fruit) as non_null_count,
       MIN(fruit) as min, MAX(fruit) as max
FROM UNNEST([NULL, "apple", "pear", "orange"]) as fruit;

+-------------+----------------+-------+------+
| total_count | non_null_count | min   | max  |
+-------------+----------------+-------+------+
| 4           | 3              | apple | pear |
+-------------+----------------+-------+------+

The following sections describe the aggregate functions that BigQuery supports.

ANY_VALUE

ANY_VALUE(expression)

Description

Returns any value from the input or NULL if there are zero input rows. The value returned is non-deterministic, which means you might receive a different result each time you use this function.

Supported Argument Types

Any

Returned Data Types

Matches the input data type.

Examples

SELECT ANY_VALUE(fruit) as example
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+---------+
| example |
+---------+
| apple   |
+---------+

APPROX_COUNT_DISTINCT

APPROX_COUNT_DISTINCT(expression)

Description

Returns the approximate result for COUNT(DISTINCT expression). The value returned is a statistical estimate—not necessarily the actual value.

This function is less accurate than COUNT(DISTINCT expression), but performs better on huge input.

Supported Argument Types

All data types except:

• ARRAY
• STRUCT
• FLOAT64

Returned Data Types

INT64

Examples

SELECT APPROX_COUNT_DISTINCT(x) as approx_distinct
FROM UNNEST([0, 1, 1, 2, 3, 5]) as x;

+-----------------+
| approx_distinct |
+-----------------+
| 5               |
+-----------------+

APPROX_QUANTILES

APPROX_QUANTILES(expression, number)

Description

Returns the approximate boundaries for a group of expression values, where number represents the number of quantiles to create. This function returns an array of number + 1 elements, where the first element is the approximate minimum and the last element is the approximate maximum.

Supported Argument Types

expression can be any supported data type except:

• ARRAY
• STRUCT

number must be INT64.

Returned Data Types

An ARRAY of the type specified by the expression parameter.

This function ignores NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows.

Examples

SELECT APPROX_QUANTILES(x, 2) as approx_quantiles
FROM UNNEST([NULL, NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) as x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 5, 10]       |
+------------------+

APPROX_TOP_COUNT

APPROX_TOP_COUNT(expression, number)

Description

Returns the approximate top elements of expression. The number parameter specifies the number of elements returned.

Supported Argument Types

expression can be of any data type that the GROUP BY clause supports.

number must be INT64.

Returned Data Types

An ARRAY of type STRUCT. The STRUCT contains two fields. The first field contains an input value. The second field contains an INT64 specifying the number of times the input was returned.

Returns NULL if there are zero input rows.

Examples

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST(["apple", "apple", "pear", "pear", "pear", "banana"]) as x;

+-------------------------+
| approx_top_count        |
+-------------------------+
| [{pear, 3}, {apple, 2}] |
+-------------------------+

NULL handling

APPROX_TOP_COUNT does not ignore NULLs in the input. For example:

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST([NULL, "pear", "pear", "pear", "apple", NULL]) as x;

+------------------------+
| approx_top_count       |
+------------------------+
| [{pear, 3}, {NULL, 2}] |
+------------------------+

ARRAY_AGG

ARRAY_AGG(expression)

Description

Returns an ARRAY of all expression values, including NULLs and NaNs. The order of the elements in the output array is non-deterministic, which means you might receive a different result each time you use this function.

Supported Argument Types

All data types except ARRAY.

Returned Data Types

ARRAY

If there are zero input rows, this function returns NULL.

Examples

SELECT ARRAY_AGG(x*2) as array_agg
FROM UNNEST([1, 2, 3, 4, 5]) as x;

+------------------+
| array_agg        |
+------------------+
| [2, 4, 6, 8, 10] |
+------------------+

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression)

Description

Concatenates elements from expression of type ARRAY, returning a single ARRAY as a result. The order of the elements in the output array is non-deterministic, which means you might receive a different result each time you use this function.

Supported Argument Types

ARRAY

Returned Data Types

ARRAY

This function ignores NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows.

Examples

SELECT ARRAY_CONCAT_AGG(x) AS array_concat_agg
FROM (SELECT [1,2] x
      UNION ALL
      SELECT [3,4] x);

+-------------------+
| array_concat_agg  |
+-------------------+
| [1, 2, 3, 4]      |
+-------------------+

AVG

AVG(expression)

Description

Returns the average of non-NULL input values, or NaN if the input contains a NaN.

Supported Argument Types

Any numeric input type, such as INT64. Note that, for floating point input types, the return result is non-deterministic, which means you might receive a different result each time you use this function.

Returned Data Types

FLOAT64

Examples

SELECT AVG(x) as avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) as x;

+-----+
| avg |
+-----+
| 3   |
+-----+

BIT_AND

BIT_AND(expression)

Description

Performs a bitwise AND operation on expression and returns the result.

Supported Argument Types

INT64

Returned Data Types

INT64

Examples

SELECT BIT_AND(x) as bit_and FROM UNNEST([0xF001, 0x00A1]) as x;

+---------+
| bit_and |
+---------+
| 1       |
+---------+

BIT_OR

BIT_OR(expression)

Description

Performs a bitwise OR operation on expression and returns the result.

Supported Argument Types

INT64

Returned Data Types

INT64

Examples

SELECT BIT_OR(x) as bit_or FROM UNNEST([0xF001, 0x00A1]) as x;

+--------+
| bit_or |
+--------+
| 61601  |
+--------+

BIT_XOR

BIT_XOR(expression)

Description

Performs a bitwise XOR operation on expression and returns the result.

Supported Argument Types

INT64

Returned Data Types

INT64

Examples

SELECT BIT_XOR(x) as bit_xor FROM UNNEST([0xF001, 0x00A1]) as x;

+---------+
| bit_xor |
+---------+
| 61600   |
+---------+

COUNT(expression)

COUNT(expression)

Description

Returns 0 if there are zero input rows or expression evaluates to NULL for all rows.

Supported Argument Types

Any data type

Return Data Types

INT64

Examples

SELECT COUNT(x) as count
FROM UNNEST([1, 2, NULL, 4, 5]) as x;

+-------+
| count |
+-------+
| 4     |
+-------+

COUNT(*)

COUNT(*)

Description

Returns the number of rows in the input.

Supported Argument Types

Not applicable

Return Data Types

INT64

Examples

SELECT COUNT(*) as count
FROM UNNEST([1, 2, NULL, 4, 5]) as x;

+-------+
| count |
+-------+
| 5     |
+-------+

COUNTIF

COUNTIF(expression)

Description

Returns the count of TRUE values for expression. Returns 0 if there are zero input rows or expression evaluates to FALSE for all rows.

Supported Argument Types

BOOL

Return Data Types

INT64

Examples

SELECT COUNTIF(x<0) num_negative, COUNTIF(x>0) num_positive
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) as x;

+--------------+--------------+
| num_negative | num_positive |
+--------------+--------------+
| 3            | 4            |
+--------------+--------------+

LOGICAL_AND

LOGICAL_AND(expression)

Description

Returns the logical AND of all non-NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows.

Supported Argument Types

BOOL

Return Data Types

BOOL

Examples

SELECT LOGICAL_AND(x) as logical_and FROM UNNEST([true, false, true]) as x;

+-------------+
| logical_and |
+-------------+
| false       |
+-------------+

LOGICAL_OR

LOGICAL_OR(expression)

Description

Returns the logical OR of all non-NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows.

Supported Argument Types

BOOL

Return Data Types

BOOL

Examples

SELECT LOGICAL_OR(x) as logical_or FROM UNNEST([true, false, true]) as x;

+------------+
| logical_or |
+------------+
| true       |
+------------+

MAX

MAX(expression)

Description

Returns the maximum value of non-NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows. Returns NaN if the input contains a NaN.

Supported Argument Types

Any data type except: STRUCT ARRAY

Return Data Types

Same as the data type used as the input values.

Examples

SELECT MAX(x) as max
FROM UNNEST([8, NULL, 37, 6, NULL, 55]) as x;

+-----+
| max |
+-----+
| 55  |
+-----+

MIN

MIN(expression)

Description

Returns the minimum value of non-NULL expressions. Returns NULL if there are zero input rows or expression evaluates to NULL for all rows. Returns NaN if the input contains a NaN.

Supported Argument Types

Any data type except: STRUCT ARRAY

Return Data Types

Same as the data type used as the input values.

Examples

SELECT MIN(x) as min
FROM UNNEST([8, NULL, 37, 6, NULL, 55]) as x;

+-----+
| min |
+-----+
| 6   |
+-----+

STRING_AGG

STRING_AGG(expression)
STRING_AGG(expression, delimiter)

Description

Returns a value (either STRING or BYTES) obtained by concatenating non-null values.

If a delimiter is specified, concatenated values are separated by that delimiter; otherwise, a comma is used as a delimiter.

Supported Argument Types

STRING BYTES

Return Data Types

STRING BYTES

Examples

SELECT STRING_AGG(fruit) AS string_agg
FROM UNNEST(["apple", "pear", "banana"]) as fruit;

+-------------------+
| string_agg        |
+-------------------+
| apple,pear,banana |
+-------------------+

SELECT STRING_AGG(fruit, "|") AS string_agg
FROM UNNEST(["apple", "pear", "banana"]) as fruit;

+-------------------+
| string_agg        |
+-------------------+
| apple|pear|banana |
+-------------------+

SUM

SUM(expression)

Description

Returns the sum of non-null values.

If the expression is a floating point value, the sum is non-deterministic, which means you might receive a different result each time you use this function.

Supported Argument Types

Any supported numeric data types.

Return Data Types

Returns INT64 if the input is an integer.

Returns FLOAT64 if the input is a floating point value.

Returns NULL if the input contains only NULLs.

Returns Inf if the input contains Inf.

Returns -Inf if the input contains -Inf.

Returns NaN if the input contains a NaN.

Returns NaN if the input contains a combination of Inf and -Inf.

Examples

SELECT SUM(x) as sum
FROM UNNEST([1,2,3,4,5]) as x;

+-----+
| sum |
+-----+
| 15  |
+-----+

Using DISTINCT with aggregate functions

BigQuery supports DISTINCT with all aggregate functions.

Using ORDER BY with aggregate functions

BigQuery supports ORDER BY in the following functions:

• ARRAY_AGG
• STRING_AGG
• ARRAY_CONCAT_AGG

When using ORDER BY, NULLs are the minimum possible value.

NOTE: If you use ORDER BY in ARRAY_CONCAT_AGG, the ordering is applied to the input rows, not the array elements inside.

Example

SELECT ARRAY_AGG(x*2 ORDER BY x) as array_agg
FROM UNNEST([1, 2, 3, 4, 5]) as x;

+------------------+
| array_agg        |
+------------------+
| [2, 4, 6, 8, 10] |
+------------------+

Using LIMIT with aggregate functions

BigQuery supports LIMIT in the following functions:

• ARRAY_AGG
• STRING_AGG
• ARRAY_CONCAT_AGG

If an aggregate function ignores NULLs, such as STRING_AGG, LIMIT is applied after NULLs are removed.

Example

SELECT ARRAY_AGG(x*2 LIMIT 2) as array_agg
FROM UNNEST([1, 2, 3, 4, 5]) as x;

+------------------+
| array_agg        |
+------------------+
| [2, 4]           |
+------------------+

For ARRAY_CONCAT_AGG, the LIMIT modifier is applied to the input arrays, not the elements within the arrays. An empty array counts as 1. A NULL array is not counted.

Examples

SELECT ARRAY_CONCAT_AGG(x LIMIT 2) AS array_concat_agg FROM (
  SELECT [1, 2, 3] x
  UNION ALL SELECT NULL
  UNION ALL SELECT [4, 5, 6]
  UNION ALL SELECT [7, 8]
);

+--------------------+
| array_concat_agg   |
+--------------------+
| [1, 2, 3, 4, 5, 6] |
+--------------------+

SELECT ARRAY_CONCAT_AGG(x LIMIT 2) AS array_concat_agg FROM (
  SELECT [1, 2, 3] x
  UNION ALL SELECT []
  UNION ALL SELECT [4, 5, 6]
  UNION ALL SELECT [7, 8]
);

+------------------+
| array_concat_agg |
+------------------+
| [1, 2, 3]        |
+------------------+

Order of operations for aggregate modifiers

If you create a statement that contains more than one aggregate modifier, they are applied in the following order:

1. DISTINCT
2. ORDER BY
3. LIMIT

Statistical Aggregate Functions

BigQuery supports the following statistical aggregate functions.

CORR

CORR(X1, X2)

Description

Returns the Pearson coefficient of correlation of a set of number pairs. For each number pair, the first number is the dependent variable and the second number is the independent variable. The return result is between -1 and 1. A result of 0 indicates no correlation.

This function ignores any input pairs that contain one or more NULL values.

This function returns NULL if inputs consist of a single pair of values. This occurs after all pairs containing a NULL value are ignored.

Supported Input Types

FLOAT64

Return Data Type

FLOAT64

COVAR_POP

COVAR_POP(X1, X2)

Description

Returns the population covariance of a set of number pairs. The first number is the dependent variable; the second number is the independent variable. The return result is between -Inf and +Inf.

This function ignores any input pairs that contain one or more NULL values.

This function returns NULL if inputs consist of a single pair of values. This occurs after all pairs containing a NULL value are ignored.

Supported Input Types

FLOAT64

Return Data Type

FLOAT64

COVAR_SAMP

COVAR_SAMP(X1, X2)

Description

Returns the sample covariance of a set of number pairs. The first number is the dependent variable; the second number is the independent variable. The return result is between -Inf and +Inf.

This function ignores any input pairs that contain one or more NULL values. If all pairs are ignored, this function returns NULL.

Supported Input Types

FLOAT64

Return Data Type

FLOAT64

Analytic Functions

In databases, an analytic function is a function that computes aggregate values over a group of rows. Unlike aggregate functions, which return a single aggregate value for a group of rows, analytic functions return a single value for each row by computing the function over a group of input rows.

Analytic functions are a powerful mechanism for succinctly representing complex analytic operations, and they enable efficient evaluations that otherwise would involve expensive self-JOINs or computation outside the SQL query.

Analytic functions are also called "(analytic) window functions" in the SQL standard and some commercial databases. This is because an analytic function is evaluated over a group of rows, referred to as a window or window frame. In some other databases, they may be referred to as Online Analytical Processing (OLAP) functions.

Simplified syntax:

analytic_function_name ( [ argument_list ] )
  OVER (
    [ PARTITION BY partition_expression_list ]
    [ ORDER BY expression [{ ASC | DESC }] [, ...] ]
    [ window_frame_clause ]
  )

Compared to a normal BigQuery function, an analytic function requires an OVER clause, which defines the window frame that the analytic function is evaluated over. The OVER clause contains the following three optional clauses. BigQuery evaluates the sub-clauses of an OVER clause in the order in which they are written.

• A PARTITION BY clause divides the input rows into partitions, similar to GROUP BY but without actually combining rows with the same key.
• An ORDER BY clause specifies the ordering within each partition.
• A window_frame_clause defines the window frame within the current partition.

The OVER clause can also be empty (OVER()) in which case the window frame includes all input rows.

Analytic functions are evaluated after aggregation (GROUP BY and non-analytic aggregate functions).

Example: Consider a company who wants to create a leaderboard for each department that shows a "seniority ranking" for each employee, i.e. showing which employees have been there the longest. The table Employees contains columns Name, StartDate, and Department.

The following query calculates the rank of each employee within their department:

SELECT firstname, department, startdate,
  RANK() OVER ( PARTITION BY department ORDER BY startdate ) AS rank
FROM Employees;

The conceptual computing process is illustrated in Figure 1.

Figure 1: Analytic Function Illustration

BigQuery evaluates the sub-clauses of an OVER clause in the order in which they appear:

1. PARTITION BY: The table is first split into 3 partitions by department.
2. ORDER BY: The employee rows in each partition are ordered by startdate.
3. Framing: None. The window frame clause is disallowed for RANK(), as it is for all numbering functions.
4. RANK(): The seniority ranking is computed for each row over the window frame.

Analytic Function Syntax

analytic_function_name ( [ argument_list ] )
  OVER { window_name | ( [ window_specification ] ) }

window_specification:
  [ window_name ]
  [ PARTITION BY partition_expression_list ]
  [ ORDER BY expression [{ ASC | DESC }] [, ...] ]
  [ window_frame_clause ]

window_frame_clause:
{ ROWS | RANGE }
{
  { UNBOUNDED PRECEDING | numeric_expression PRECEDING | CURRENT ROW }
  |
  { BETWEEN window_frame_boundary_start AND window_frame_boundary_end }
}

window_frame_boundary_start:
{ UNBOUNDED PRECEDING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_boundary_end:
{ UNBOUNDED FOLLOWING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

Analytic functions can appear as a scalar expression or a scalar expression operand in only two places in the query:

• The SELECT list. If the analytic function appears in the SELECT list, its argument_list cannot refer to aliases introduced in the same SELECT list.
• The ORDER BY clause. If the analytic function appears in the ORDER BY clause of the query, its argument_list can refer to SELECT list aliases.

Additionally, an analytic function cannot refer to another analytic function in its argument_list or its OVER clause, even if indirectly through an alias.

Invalid:

SELECT ROW_NUMBER() OVER () AS alias1
FROM Singers
ORDER BY ROW_NUMBER() OVER(PARTITION BY alias1)

In the query above, the analytic function alias1 resolves to an analytic function: ROW_NUMBER() OVER().

OVER Clause

Syntax:

OVER { window_name | ( [ window_specification ] ) }

window_specification:
  [ window_name ]
  [ PARTITION BY partition_expression_list ]
  [ ORDER BY sort_specification_list ]
  [ window_frame_clause ]

The OVER clause has three possible components:

• PARTITION BY clause
• ORDER BY clause
• A window_frame_clause or a window_name, which refers to a window_specification defined in a WINDOW clause.

If the OVER clause is empty, OVER(), the analytic function is computed over a single partition which contains all input rows, meaning that it will produce the same result for each output row.

PARTITION BY Clause

Syntax:

PARTITION BY expression [, ... ]

The PARTITION BY clause breaks up the input rows into separate partitions, over which the analytic function is independently evaluated. Multiple expressions are allowed in the PARTITION BY clause.

expression must also have a resulting data type that supports partitioning. This means the expression cannot be any of the following data types:

• Floating point
• Struct
• Array

This list is almost identical to the list of data types that GROUP BY does not support, with the additional exclusion of floating point types (see "Groupable" in the Data Type Properties table at the top of BigQuery Data Types).

If no PARTITION BY clause is present, BigQuery treats the entire input as a single partition.

ORDER BY Clause

Syntax:

ORDER BY expression [ ASC | DESC ] [, ... ]

The ORDER BY clause defines an ordering within each partition. If no ORDER BY clause is present, row ordering within a partition is non-deterministic. Some analytic functions require ORDER BY; this is noted in the section for each family of analytic functions. Even if an ORDER BY clause is present, some functions are not sensitive to ordering within a window frame (e.g. COUNT).

The ORDER BY clause within an OVER clause is consistent with the normal ORDER BY clause in that:

• There can be multiple expressions.
• expression must have a type that supports ordering.
• An optional ASC/DESC specification is allowed for each expression.
• NULL values order as the minimum possible value (first for ASC, last for DESC)

Data type support is identical to the normal ORDER BY clause in that the following types do not support ordering:

• Array
• Struct

If the OVER clause contains an ORDER BY clause but no window_frame_clause, then the ORDER BY implicitly defines window_frame_clause as:

RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW

If neither window_frame_clause nor the ORDER BY clause is present, the window frame defaults to the entire partition.

Window Frame Clause

Syntax:

{ ROWS | RANGE }
{
  { UNBOUNDED PRECEDING | numeric_expression PRECEDING | CURRENT ROW }
  |
  { BETWEEN window_frame_boundary_start AND window_frame_boundary_end }
}

window_frame_boundary_start:
{ UNBOUNDED PRECEDING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_boundary_end:
{ UNBOUNDED FOLLOWING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_clause defines the window frame, around the current row within a partition, over which the analytic function is evaluated. window_frame_clause allows both physical window frames (defined by ROWS) and logical window frames (defined by RANGE). If the OVER clause contains an ORDER BY clause but no window_frame_clause, then the ORDER BY implicitly defines window_frame_clause as:

RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW

If neither window_frame_clause nor the ORDER BY clause is present, the window frame defaults to the entire partition.

The numeric_expression can only be a constant or a query parameter, both of which must have a non-negative value. Otherwise, BigQuery provides an error.

Examples of window frame clauses:

ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING

• Includes the entire partition.
• Example use: Compute a grand total over the partition.

ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW

• Includes all the rows in the partition before or including the current row.
• Example use: Compute a cumulative sum.

ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING

• Includes all rows between two before and two after the current row.
• Example use: Compute a moving average.

If window_frame_spec uses the BETWEEN clause:

• window_frame_boundary_start must specify a boundary that begins no later than that of the window_frame_boundary_end. This has the following consequences:
  1. If window_frame_boundary_start contains CURRENT ROW, window_frame_boundary_end cannot contain PRECEDING.
  2. If window_frame_boundary_start contains FOLLOWING, window_frame_boundary_end cannot contain CURRENT ROW or PRECEDING.
• window_frame_boundary_start has no default value.

Otherwise, the specified window_frame_spec boundary represents the start of the window frame and the end of the window frame boundary defaults to 'CURRENT ROW'. Thus,

ROWS 10 PRECEDING

is equivalent to

ROWS BETWEEN 10 PRECEDING AND CURRENT ROW

ROWS

ROWS-based window frames compute the window frame based on physical offsets from the current row. For example, the window frame below defines a window frame of size five (at most) around the current row.

ROWS BETWEEN 2 PRECEDING and 2 FOLLOWING

The numeric_expression in window_frame_clause is interpreted as a number of rows from the current row, and must be a constant, non-negative integer. It may also be a query parameter.

If the window frame for a given row extends beyond the beginning or end of the partition, then the window frame will only include rows from within that partition.

Example: Consider the following table with columns z, x, and y.

Consider the following analytic function:

SUM(x) OVER (PARTITION BY y ORDER BY z ROWS BETWEEN 1 PRECEDING AND 1
FOLLOWING)

The PARTITION BY clause splits the table into 3 partitions based on their y value, and the ORDER BY orders the rows within each partition by their z value.

Partition 1 of 3:

Partition 2 of 3:

Partition 3 of 3:

In the tables below, bold indicates the row currently being evaluated, and colored cells indicates all the rows in the window frame for that row.

• For the first row in the y = AA partition, the window frame includes only 2 rows since there is no preceding row, even though the window_frame_spec indicates a window size of 3. The result of the analytic function is 7 for the first row.

• For the second row in the partition, the window frame includes all 3 rows. The result of the analytic function is 9 for the second row.

• For the last row in the partition, the window frame includes only 2 rows since there is no following row. The result of the analytic function is 4 for the third row.

RANGE

RANGE-based window frames compute the window frame based on a logical range of rows around the current row based on the current row's ORDER BY key value. The provided range value is added or subtracted to the current row's key value to define a starting or ending range boundary for the window frame.

The ORDER BY clause must be specified unless the window is:

RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.

numeric_expression in the window_frame_clause is interpreted as an offset from the current row's value of the ORDER BY key. numeric_expression must have numeric type. DATE and TIMESTAMP are not currently supported. In addition, the numeric_expression must be a constant, non-negative integer or a parameter.

In a RANGE-based window frame, there can be at most one expression in the ORDER BY clause, and expression must have a numeric type.

Example of a RANGE-based window frame where there is a single partition:

SELECT x, COUNT(*) OVER ( ORDER BY x
  RANGE BETWEEN 2 PRECEDING AND 2 FOLLOWING ) AS count_x
FROM T;

In the tables below, bold indicates the row currently being evaluated, and colored cells indicates all the rows in the window frame for that row.

• For row 1, x = 5 and therefore COUNT(*) will only include rows where 3 <=x <= 7

• For row 2, x = 2 and therefore COUNT(*) will only include rows where 0 <= x <= 4

• For row 3, x = 11 and therefore COUNT(*) will only include rows where 9 <= x <= 13

WINDOW Clause

Syntax:

WINDOW window_definition [, ...]
window_definition: window_name AS ( window_specification )

A WINDOW clause defines a list of named windows whose window_name can be referenced in analytic functions in the SELECT list. This is useful when you want to use the same window_frame_clause for multiple analytic functions.

The WINDOW clause can appear only at the end of a SELECT clause, as shown in Query Syntax.

Named Windows

Once you define a WINDOW clause, you can use the named windows in analytic functions, but only in the SELECT list; you cannot use named windows in the ORDER BY clause. Named windows can appear either by themselves or embedded within an OVER clause. Named windows can refer to SELECT list aliases.

Examples:

SELECT SUM(x) OVER window_name FROM ...

SELECT SUM(x) OVER (
  window_name
  PARTITION BY...
  ORDER BY...
  window_frame_clause)
FROM ...

When embedded within an OVER clause, the window_specification associated with window_name must be compatible with the PARTITION BY, ORDER BY, and window_frame_clause that are in the same OVER clause.

The following rules apply to named windows:

• You can refer to named windows only in the SELECT list; you cannot refer to them in an ORDER BY clause, an outer query, or any subquery.
• A window W1 (named or unnamed) may reference a named window NW2, with the following rules:
  1. If W1 is a named window, then the referenced named window NW2 must precede W1 in the same WINDOW clause.
  2. W1 cannot contain a PARTITION BY clause
  3. It cannot be true that both W1 and NW2 contain an ORDER BY clause
  4. NW2 cannot contain a window_frame_clause.
• If a (named or unnamed) window W1 references a named window NW2, then the resulting window specification is defined using:
  1. The PARTITION BY from NW2, if there is one.
  2. The ORDER BY from W1 or NW2, if either is specified; it is not possible for them to both have an ORDER BY clause.
  3. The window_frame_clause from W1, if there is one.

Supported Functions

Numbering Functions

Numbering functions assign integer values to each row based on their position within the specified window.

OVER clause requirements:

• PARTITION BY: Optional.
• ORDER BY: Required, except for ROW_NUMBER().
• window_frame_clause: Disallowed.

If two rows are tied in the ordering, they are peers. The concept of peers is relevant for the functions RANK(), DENSE_RANK(), and CUME_DIST.

Example of RANK(), DENSE_RANK(), and ROW_NUMBER():

SELECT x,
  RANK() OVER (ORDER BY x ASC) AS rank,
  DENSE_RANK() OVER (ORDER BY x ASC) AS dense_rank,
  ROW_NUMBER() OVER (PARTITION BY x ORDER BY y) AS row_num
FROM ...

• RANK():For x=5, rank returns 4, since RANK() increments by the number of peers in the previous window ordering group.
• DENSE_RANK(): For x=5, dense_rank returns 3, since DENSE_RANK() always increments by 1, never skipping a value.
• ROW_NUMBER():For x=5, row_num returns 4.

Navigation Functions

Navigation functions generally compute some value_expression over a different row in the window frame from the current row. The OVER clause syntax varies across navigation functions.

OVER clause requirements:

• PARTITION BY: Optional.
• ORDER BY: Required
• window_frame_clause:
  1. Disallowed for LEAD and LAG
  2. Optional for FIRST_VALUE, LAST_VALUE, and NTH_VALUE.

For all navigation functions, the result data type is the same type as value_expression.

FIRST_VALUE

FIRST_VALUE (value_expression)

Description

Returns the value of the value_expression for the first row in the current window frame.

Supported Argument Types

value_expression can be any data type that an expression can return.

Return Data Type

ANY

Examples

The following example computes the fastest time for each division.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  TIMESTAMP_DIFF(finish_time, fastest_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  FIRST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS fastest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | fastest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 0                |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 436              |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 891              |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 956              |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 1109             |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 0                |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 426              |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 691              |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 733              |
+-----------------+-------------+----------+--------------+------------------+

LAST_VALUE

LAST_VALUE (value_expression)

Description

Returns the value of the value_expression for the last row in the current window frame.

Supported Argument Types

value_expression can be any data type that an expression can return.

Return Data Type

ANY

Examples

The following example computes the slowest time for each division.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', slowest_time) AS slowest_time,
  TIMESTAMP_DIFF(slowest_time, finish_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  LAST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS slowest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | slowest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 03:10:14     | 1109             |
| Nikki Leith     | 02:59:01    | F30-34   | 03:10:14     | 673              |
| Jen Edwards     | 03:06:36    | F30-34   | 03:10:14     | 218              |
| Meghan Lederer  | 03:07:41    | F30-34   | 03:10:14     | 153              |
| Lauren Reasoner | 03:10:14    | F30-34   | 03:10:14     | 0                |
| Lisa Stelzner   | 02:54:11    | F35-39   | 03:06:24     | 733              |
| Lauren Matthews | 03:01:17    | F35-39   | 03:06:24     | 307              |
| Desiree Berry   | 03:05:42    | F35-39   | 03:06:24     | 42               |
| Suzy Slane      | 03:06:24    | F35-39   | 03:06:24     | 0                |
+-----------------+-------------+----------+--------------+------------------+

NTH_VALUE

NTH_VALUE (value_expression, constant_integer_expression)

Description

Returns the value of value_expression at the Nth row of the current window frame, where Nth is defined by constant_integer_expression. Returns NULL if there is no such row.

Supported Argument Types

• value_expression can be any data type that can be returned from an expression.
• constant_integer_expression can be any constant expression that returns an integer.

Return Data Type

ANY

Examples

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  FORMAT_TIMESTAMP('%X', second_fastest) AS second_fastest
FROM (
  SELECT name,
  finish_time,
  division,finishers,
  FIRST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS fastest_time,
  NTH_VALUE(finish_time, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) as second_fastest
  FROM finishers);

+-----------------+-------------+----------+--------------+----------------+
| name            | finish_time | division | fastest_time | second_fastest |
+-----------------+-------------+----------+--------------+----------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | NULL           |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 02:59:01       |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 02:59:01       |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 02:59:01       |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 02:59:01       |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 02:59:01       |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 03:01:17       |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 03:01:17       |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 03:01:17       |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 03:01:17       |
+-----------------+-------------+----------+--------------+----------------+

LEAD

LEAD (value_expression, [, offset [, default_expression]])

Description

Returns the value of the value_expression on a subsequent row. Changing the offset value changes which subsequent row is returned; the default value is 1, indicating the next row in the window frame. An error occurs if offset is NULL or a negative value.

The optional default_expression is used if there isn't a row in the window frame at the specified offset. This expression must be a constant expression and its type must be implicitly coercible to the type of value_expression. If left unspecified, default_expression defaults to NULL.

Supported Argument Types

• value_expression can be any data type that can be returned from an expression.
• offset must be a non-negative integer literal or parameter.
• default_expression must be compatible with the value expression type.

Return Data Type

ANY

Examples

The following example illustrates a basic use of the LEAD function.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS followed_by
FROM finishers;

+-----------------+-------------+----------+-----------------+
| name            | finish_time | division | followed_by     |
+-----------------+-------------+----------+-----------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL            |
| Sophia Liu      | 02:51:45    | F30-34   | Nikki Leith     |
| Nikki Leith     | 02:59:01    | F30-34   | Jen Edwards     |
| Jen Edwards     | 03:06:36    | F30-34   | Meghan Lederer  |
| Meghan Lederer  | 03:07:41    | F30-34   | Lauren Reasoner |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL            |
| Lisa Stelzner   | 02:54:11    | F35-39   | Lauren Matthews |
| Lauren Matthews | 03:01:17    | F35-39   | Desiree Berry   |
| Desiree Berry   | 03:05:42    | F35-39   | Suzy Slane      |
| Suzy Slane      | 03:06:24    | F35-39   | NULL            |
+-----------------+-------------+----------+-----------------+

This next example uses the optional offset parameter.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | NULL             |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL             |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | NULL             |
| Suzy Slane      | 03:06:24    | F35-39   | NULL             |
+-----------------+-------------+----------+------------------+

The following example replaces NULL values with a default value.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody           |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | Nobody           |
| Lauren Reasoner | 03:10:14    | F30-34   | Nobody           |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | Nobody           |
| Suzy Slane      | 03:06:24    | F35-39   | Nobody           |
+-----------------+-------------+----------+------------------+

LAG

LAG (value_expression, [, offset [, default_expression]])

Description

Returns the value of the value_expression on a preceding row. Changing the offset value changes which preceding row is returned; the default value is 1, indicating the previous row in the window frame. An error occurs if offset is NULL or a negative value.

The optional default_expression is used if there isn't a row in the window frame at the specified offset. This expression must be a constant expression and its type must be implicitly coercible to the type of value_expression. If left unspecified, default_expression defaults to NULL.

Supported Argument Types

• value_expression can be any data type that can be returned from an expression.
• offset must be a non-negative integer literal or parameter.
• default_expression must be compatible with the value expression type.

Return Data Type

ANY

Examples

The following example illustrates a basic use of the LAG function.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS preceding_runner
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | preceding_runner |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | NULL             |
| Nikki Leith     | 02:59:01    | F30-34   | Sophia Liu       |
| Jen Edwards     | 03:06:36    | F30-34   | Nikki Leith      |
| Meghan Lederer  | 03:07:41    | F30-34   | Jen Edwards      |
| Lauren Reasoner | 03:10:14    | F30-34   | Meghan Lederer   |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL             |
| Lauren Matthews | 03:01:17    | F35-39   | Lisa Stelzner    |
| Desiree Berry   | 03:05:42    | F35-39   | Lauren Matthews  |
| Suzy Slane      | 03:06:24    | F35-39   | Desiree Berry    |
+-----------------+-------------+----------+------------------+

This next example uses the optional offset parameter.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL              |
| Sophia Liu      | 02:51:45    | F30-34   | NULL              |
| Nikki Leith     | 02:59:01    | F30-34   | NULL              |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL              |
| Lauren Matthews | 03:01:17    | F35-39   | NULL              |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

The following example replaces NULL values with a default value.

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody            |
| Sophia Liu      | 02:51:45    | F30-34   | Nobody            |
| Nikki Leith     | 02:59:01    | F30-34   | Nobody            |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | Nobody            |
| Lauren Matthews | 03:01:17    | F35-39   | Nobody            |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

Aggregate Analytic Functions

BigQuery supports the following aggregate functions as analytic functions:

• ANY_VALUE
• AVG
• COUNT(EXPRESSION)
• COUNT
• COUNTIF
• MAX
• MIN
• SUM

With these functions, the OVER clause is simply appended to the aggregate function call; the function call syntax remains otherwise unchanged. Like their aggregate function counterparts, these analytic functions perform aggregations, but specifically over the relevant window frame for each row. The result data types of these analytic functions are the same as their aggregate function counterparts.

OVER clause requirements:

• PARTITION BY: Optional.
• ORDER BY: Optional. Disallowed if DISTINCT is present.
• window_frame_clause: Optional. Disallowed if DISTINCT is present.

Example:

COUNT(*) OVER (ROWS UNBOUNDED PRECEDING)

SUM(DISTINCT x) OVER ()

Mathematical functions

Mathematical functions:

• Return NULL if any of the input parameters is NULL.
• Return NaN if any of the arguments is NaN.

Special cases for IEEE_DIVIDE(X, Y)

The following table lists special cases for IEEE_DIVIDE(X,Y).

Special cases for POW(X, Y) and POWER(X, Y)

The following are special cases for POW(X, Y) and POWER(X, Y).

Special cases for LOG(X, Y)

Rounding functions

Example behavior of BigQuery rounding functions:

Trigonometric and hyperbolic functions

Special cases for ATAN2()

Special cases for trigonometric and hyperbolic rounding functions

Hash functions

MD5

MD5(input)

Description

Computes the hash of the input using the MD5 algorithm. The input can either be STRING or BYTES. The string version treats the input as an array of bytes.

This function returns 16 bytes.

Return type

BYTES

Example

SELECT MD5("Hello World") as md5;

+-------------------------------------------------+
| md5                                             |
+-------------------------------------------------+
| \xb1\n\x8d\xb1d\xe0uA\x05\xb7\xa9\x9b\xe7.?\xe5 |
+-------------------------------------------------+

SHA1

SHA1(input)

Description

Computes the hash of the input using the SHA-1 algorithm. The input can either be STRING or BYTES. The string version treats the input as an array of bytes.

This function returns 20 bytes.

Return type

BYTES

Example

SELECT SHA1("Hello World") as sha1;

+-----------------------------------------------------------+
| sha1                                                      |
+-----------------------------------------------------------+
| \nMU\xa8\xd7x\xe5\x02/\xabp\x19w\xc5\xd8@\xbb\xc4\x86\xd0 |
+-----------------------------------------------------------+

SHA256

SHA256(input)

Description

Computes the hash of the input using the SHA-256 algorithm. The input can either be STRING or BYTES. The string version treats the input as an array of bytes.

This function returns 32 bytes.

Return type

BYTES

Example

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

Description

Computes the hash of the input using the SHA-512 algorithm. The input can either be STRING or BYTES. The string version treats the input as an array of bytes.

This function returns 32 bytes.

Return type

BYTES

Example

SELECT SHA512("Hello World") as sha512;

String functions

These string functions work on two different values: STRING and BYTES data types. STRING values must be well-formed UTF-8.

Functions that return position values, such as STRPOS, encode those positions as INT64. The value 1 refers to the first character (or byte), 2 refers to the second, and so on. The value 0 indicates an invalid index. When working on STRING types, the returned positions refer to character positions.

All string comparisons are done byte-by-byte, without regard to Unicode canonical equivalence.

BYTE_LENGTH

BYTE_LENGTH(value)

Description

Returns the length of the value in bytes, regardless of whether the type of the value is STRING or BYTES.

Return type

INT64

Examples

WITH example AS
  (SELECT "абвгд" AS characters, b"абвгд" AS bytes)

SELECT
  characters,
  BYTE_LENGTH(characters) AS string_example,
  bytes,
  BYTE_LENGTH(bytes) AS bytes_example
FROM example;

+------------+----------------+-------+---------------+
| characters | string_example | bytes | bytes_example |
+------------+----------------+-------+---------------+
| абвгд      | 10             | абвгд | 10            |
+------------+----------------+-------+---------------+

CHAR_LENGTH

CHAR_LENGTH(value)

Description

Returns the length of the STRING in characters.

Return type

INT64

Examples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHAR_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

Description

Synonym for CHAR_LENGTH.

Return type

INT64

Examples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHARACTER_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

Description

Takes an array of extended ASCII character values and returns BYTES.

To convert from BYTES to an array of code points, see TO_CODE_POINTS.

Return type

BYTES

Examples

The following is a basic example using CODE_POINTS_TO_BYTES.

SELECT CODE_POINTS_TO_BYTES([65, 98, 67, 100]) AS bytes;

+-------+
| bytes |
+-------+
| AbCd  |
+-------+

The following example uses a rotate-by-13 places (ROT13) algorithm to encode a string.

SELECT CODE_POINTS_TO_BYTES(ARRAY_AGG(
  (SELECT
      CASE
        WHEN chr BETWEEN b'a' and b'z'
          THEN TO_CODE_POINTS(b'a')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'a')[offset(0)],26)
        WHEN chr BETWEEN b'A' and b'Z'
          THEN TO_CODE_POINTS(b'A')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'A')[offset(0)],26)
        ELSE code
      END
   FROM
     (SELECT code, CODE_POINTS_TO_BYTES([code]) chr)
  ) ORDER BY OFFSET)) AS encoded_string
FROM UNNEST(TO_CODE_POINTS(b'Test String!')) code WITH OFFSET;

+----------------+
| encoded_string |
+----------------+
| Grfg Fgevat!   |
+----------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Description

Takes an array of code points and returns a STRING.

To convert from a string to an array of code points, see TO_CODE_POINTS.

Return type

STRING

Example

The following is a basic example using CODE_POINTS_TO_STRING.

SELECT CODE_POINTS_TO_STRING([65, 255, 513, 1024]) AS string;

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+

The following example computes the frequency of letters in a set of words.

WITH Words AS (
  SELECT word
  FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word
)
SELECT
  CODE_POINTS_TO_STRING([code_point]) AS letter,
  COUNT(*) AS letter_count
FROM Words,
  UNNEST(TO_CODE_POINTS(word)) AS code_point
GROUP BY 1
ORDER BY 2 DESC;

+--------+--------------+
| letter | letter_count |
+--------+--------------+
| a      | 5            |
| f      | 3            |
| r      | 2            |
| b      | 2            |
| l      | 2            |
| o      | 2            |
| g      | 1            |
| z      | 1            |
| e      | 1            |
| m      | 1            |
| i      | 1            |
+--------+--------------+

CONCAT

CONCAT(value1[, ...])

Description

Concatenates one or more values into a single result.

Return type

STRING or BYTES

Examples

With Employees AS
  (SELECT
    "John" AS first_name,
    "Doe" AS last_name
  UNION ALL
  SELECT
    "Jane" AS first_name,
    "Smith" AS last_name
  UNION ALL
  SELECT
    "Joe" AS first_name,
    "Jackson" AS last_name)

SELECT
  CONCAT(first_name, " ", last_name)
  AS full_name
FROM Employees;

+---------------------+
| full_name           |
+---------------------+
| John Doe            |
| Jane Smith          |
| Joe Jackson         |
+---------------------+

ENDS_WITH

ENDS_WITH(value1, value2)

Description

Takes two values. Returns TRUE if the second value is a suffix of the first.

Return type

BOOL

Examples

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  ENDS_WITH(item, "e") as example
FROM items;

+---------+
| example |
+---------+
|    True |
|   False |
|    True |
+---------+

LENGTH

LENGTH(value)

Description

Returns the length of the value. The returned value is in characters for STRING arguments and in bytes for the BYTES argument.

Return type

INT64

Examples

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  LENGTH(characters) AS string_example,
  LENGTH(CAST(characters AS BYTES)) AS bytes_example
FROM example;

+------------+----------------+---------------+
| characters | string_example | bytes_example |
+------------+----------------+---------------+
| абвгд      |              5 |            10 |
+------------+----------------+---------------+

LOWER

LOWER(value)

Description

For STRING arguments, returns the original string with all alphabetic characters in lowercase. Mapping between lowercase and uppercase is done according to the Unicode Character Database without taking into account language-specific mappings.

For BYTES arguments, the argument is treated as ASCII text, with all bytes greater than 127 left intact.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT
    "FOO" as item
  UNION ALL
  SELECT
    "BAR" as item
  UNION ALL
  SELECT
    "BAZ" as item)

SELECT
  LOWER(item) AS example
FROM items;

+---------+
| example |
+---------+
| foo     |
| bar     |
| baz     |
+---------+

LTRIM

LTRIM(value1[, value2])

Description

Identical to TRIM, but only removes leading characters.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", LTRIM(item), "#") as example
FROM items;

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  LTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  LTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regex)

Description

Returns TRUE if value is a partial match for the regular expression, regex. You can search for a full match by using ^ (beginning of text) and $ (end of text).

If the regex argument is invalid, the function returns an error.

Note: BigQuery provides regular expression support using the re2 library; see that documentation for its regular expression syntax.

Return type

BOOL

Examples

SELECT
  email,
  REGEXP_CONTAINS(email, r"@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+") AS is_valid
FROM
  (SELECT
    ["[email protected]", "[email protected]", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| [email protected] | true     |
| [email protected] | true     |
| www.example.net | false    |
+-----------------+----------+

# Performs a full match, using ^ and $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")
    AS valid_email_address
FROM
  (SELECT
    ["[email protected]", "[email protected]", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+---------------------+
| email           | valid_email_address |
+-----------------+---------------------+
| [email protected] | true                |
| [email protected] | true                |
| www.example.net | false               |
+-----------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

Description

Returns the first substring in value that matches the regular expression, regex. Returns NULL if there is no match.

If the regular expression contains a capturing group, the function returns the substring that is matched by that capturing group. If the expression does not contain a capturing group, the function returns the entire matching substring.

Returns an error if:

• The regular expression is invalid
• The regular expression has more than one capturing group

Note: BigQuery provides regular expression support using the re2 library; see that documentation for its regular expression syntax.

Return type

STRING or BYTES

Examples

WITH email_addresses AS
  (SELECT "[email protected]" as email
  UNION ALL
  SELECT "[email protected]" as email
  UNION ALL
  SELECT "[email protected]" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+")
  AS user_name
FROM email_addresses;

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+

WITH email_addresses AS
  (SELECT "[email protected]" as email
  UNION ALL
  SELECT "[email protected]" as email
  UNION ALL
  SELECT "[email protected]" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.([a-zA-Z0-9-.]+$)")
  AS top_level_domain
FROM email_addresses;

+------------------+
| top_level_domain |
+------------------+
| com              |
| org              |
| net              |
+------------------+

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regex)

Description

Returns an array of all substrings of value that match the regular expression, regex.

The REGEXP_EXTRACT_ALL function only returns non-overlapping matches. For example, using this function to extract ana from banana returns only one substring, not two.

Note: BigQuery provides regular expression support using the re2 library; see that documentation for its regular expression syntax.

Return type

An ARRAY of either STRINGs or BYTES

Examples

WITH code_markdown AS
  (SELECT "Try `function(x)` or `function(y)`" as code)

SELECT
  REGEXP_EXTRACT_ALL(code, "`(.+?)`") AS example
FROM code_markdown;

+----------------------------+
| example                    |
+----------------------------+
| [function(x), function(y)] |
+----------------------------+

REGEXP_REPLACE

REGEXP_REPLACE(value, regex, replacement)

Description

Returns a STRING where all substrings of value that match regular expression regex are replaced with replacement.

You can use backslashed-escaped digits (\1 to \9) within the replacement argument to insert text matching the corresponding parenthesized group in the regex pattern. Use \0 to refer to the entire matching text.

Note: To add a backslash in your regular expression, you must first escape it. For example, SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1"); returns aXc.

The REGEXP_REPLACE function only replaces non-overlapping matches. For example, replacing ana within banana results in only one replacement, not two.

If the regex argument is not a valid regular expression, this function returns an error.

Note: BigQuery provides regular expression support using the re2 library; see that documentation for its regular expression syntax.

Return type

STRING or BYTES

Examples

WITH markdown AS
  (SELECT "# Heading" as heading
  UNION ALL
  SELECT "# Another heading" as heading)

SELECT
  REGEXP_REPLACE(heading, r"^# ([a-zA-Z0-9\s]+$)", "<h1>\\1</h1>")
  AS html
FROM markdown;

+--------------------------+
| html                     |
+--------------------------+
| <h1>Heading</h1>         |
| <h1>Another heading</h1> |
+--------------------------+

REPLACE

REPLACE(original_value, from_value, to_value)

Description

Replaces all occurrences of from_value with to_value in original_value. If from_value is empty, no replacement is made.

Return type

STRING or BYTES

Examples

WITH desserts AS
  (SELECT "apple pie" as dessert
  UNION ALL
  SELECT "blackberry pie" as dessert
  UNION ALL
  SELECT "cherry pie" as dessert)

SELECT
  REPLACE (dessert, "pie", "cobbler") as example
FROM desserts;

+--------------------+
| example            |
+--------------------+
| apple cobbler      |
| blackberry cobbler |
| cherry cobbler     |
+--------------------+

RTRIM

RTRIM(value1[, value2])

Description

Identical to TRIM, but only removes trailing characters.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  RTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+

WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

SELECT
  RTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

Description

Converts a sequence of bytes to a string. Any invalid UTF-8 characters are replaced with the Unicode replacement character, U+FFFD.

Return type

STRING

Examples

The following statement returns the Unicode replacement character, �.

SELECT SAFE_CONVERT_BYTES_TO_STRING(b'\xc2') as safe_convert;

SPLIT

SPLIT(value[, delimiter])

Description

Splits value using the delimiter argument.

For STRING, the default delimiter is ,.

For BYTES, you must specify a delimiter.

Splitting on an empty delimiter produces an array of UTF-8 characters for STRING values, and an array of BYTES for BYTES values.

Splitting an empty STRING returns an ARRAY with a single empty STRING.

Return type

ARRAY of type STRING or ARRAY of type BYTES

Examples

WITH letters AS
  (SELECT "a b c d" as letter_group
  UNION ALL
  SELECT "e f g h" as letter_group
  UNION ALL
  SELECT "i j k l" as letter_group)

SELECT SPLIT(letter_group, " ") as example
FROM letters;

+----------------------+
| example              |
+----------------------+
| [a, b, c, d]         |
| [e, f, g, h]         |
| [i, j, k, l]         |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

Description

Takes two values. Returns TRUE if the second value is a prefix of the first.

Return type

BOOL

Examples

WITH items AS
  (SELECT "foo" as item
  UNION ALL
  SELECT "bar" as item
  UNION ALL
  SELECT "baz" as item)

SELECT
  STARTS_WITH(item, "b") as example
FROM items;

+---------+
| example |
+---------+
|   False |
|    True |
|    True |
+---------+

STRPOS

STRPOS(value1, value2)

Description

Returns the 1-based index of the first occurrence of value2 inside value1. Returns 0 if value2 is not found.

Return type

INT64

Examples

WITH email_addresses AS
  (SELECT
    "[email protected]" AS email_address
  UNION ALL
  SELECT
    "[email protected]" AS email_address
  UNION ALL
  SELECT
    "[email protected]" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

SELECT
  STRPOS(email_address, "@") AS example
FROM email_addresses;

+---------+
| example |
+---------+
|       4 |
|       7 |
|      10 |
|       0 |
+---------+

SUBSTR

SUBSTR(value, position[, length])

Description

Returns a substring of the supplied value. The position argument is an integer specifying the starting position of the substring, with position = 1 indicating the first character or byte. The length argument is the maximum number of characters for STRING arguments, or bytes for BYTES arguments.

If position is negative, the function counts from the end of value, with -1 indicating the last character.

If position is a position off the left end of the STRING (position = 0 or position < -LENGTH(value)), the function starts from position = 1. If length exceeds the length of value, returns fewer than length characters.

If length is less than 0, the function returns an error.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2) as example
FROM items;

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2, 2) as example
FROM items;

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, -2) as example
FROM items;

+---------+
| example |
+---------+
| le      |
| na      |
| ge      |
+---------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Description

Takes a value and returns an array of INT64.

• If value is a STRING, each element in the returned array represents a code point. Each code point falls within the range of [0, 0xD7FF] and [0xE000, 0x10FFFF].
• If value is BYTES, each element in the array is an extended ASCII character value in the range of [0, 255].

To convert from an array of code points to a STRING or BYTES, see CODE_POINTS_TO_STRING or CODE_POINTS_TO_BYTES.

Return type

ARRAY of INT64

Examples

The following example gets the code points for each element in an array of words.

SELECT word, TO_CODE_POINTS(word) AS code_points
FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word;

+---------+------------------------------------+
| word    | code_points                        |
+---------+------------------------------------+
| foo     | [102, 111, 111]                    |
| bar     | [98, 97, 114]                      |
| baz     | [98, 97, 122]                      |
| giraffe | [103, 105, 114, 97, 102, 102, 101] |
| llama   | [108, 108, 97, 109, 97]            |
+---------+------------------------------------+

The following example converts integer representations of BYTES to their corresponding ASCII character values.

SELECT word, TO_CODE_POINTS(word) AS bytes_value_as_integer
FROM UNNEST([b'\x00\x01\x10\xff', b'\x66\x6f\x6f']) AS word;

+------------------+------------------------+
| word             | bytes_value_as_integer |
+------------------+------------------------+
| \x00\x01\x10\xff | [0, 1, 16, 255]        |
| foo              | [102, 111, 111]        |
+------------------+------------------------+

The following example demonstrates the difference between a BYTES result and a STRING result.

SELECT TO_CODE_POINTS(b'Ā') AS b_result, TO_CODE_POINTS('Ā') AS s_result;

+------------+----------+
| b_result   | s_result |
+------------+----------+
| [196, 128] | [256]    |
+------------+----------+

Notice that the character, Ā, is represented as a two-byte Unicode sequence. As a result, the BYTES version of TO_CODE_POINTS returns an array with two elements, while the STRING version returns an array with a single element.

TRIM

TRIM(value1[, value2])

Description

Removes all leading and trailing characters that match value2. If value2 is not specified, all leading and trailing whitespace characters (as defined by the Unicode standard) are removed. If the first argument is of type BYTES, the second argument is required.

If value2 contains more than one character or byte, the function removes all leading or trailing characters or bytes contained in value2.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", TRIM(item), "#") as example
FROM items;

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  TRIM(item, "*") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  TRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

UPPER

UPPER(value)

Description

For STRING arguments, returns the original string with all alphabetic characters in uppercase. Mapping between uppercase and lowercase is done according to the Unicode Character Database without taking into account language-specific mappings.

For BYTES arguments, the argument is treated as ASCII text, with all bytes greater than 127 left intact.

Return type

STRING or BYTES

Examples

WITH items AS
  (SELECT
    "foo" as item
  UNION ALL
  SELECT
    "bar" as item
  UNION ALL
  SELECT
    "baz" as item)

SELECT
  UPPER(item) AS example
FROM items;

+---------+
| example |
+---------+
| FOO     |
| BAR     |
| BAZ     |
+---------+

String FORMAT()

BigQuery supports a FORMAT() function for formatting strings. This function is similar to the C printf function. It produces a STRING from a format string that contains zero or more format specifiers, along with a variable length list of additional arguments that matches the format specifiers. Here are some examples:

format("%d", 10)

10

format("|%10d|", 11)

|           11|

format("+%010d+", 12)

+0000000012+

format("-%s-", 'abcd efg')

-abcd efg-

format("%f %E", 1.1, 2.2)

1.100000 2.200000E+00

format("%t", date "2015-09-01")

2015-09-01

format("%t", timestamp "2015-09-01 12:34:56
America/Los_Angeles")

2015-09-01 19:34:56+00

The FORMAT() function does not provide fully customizable formatting for all types and values, nor formatting that is sensitive to locale.

If custom formatting is necessary for a type, you must first format it using type-specific format functions, such as FORMAT_DATE() or FORMAT_TIMESTAMP(). For example:

FORMAT("date: %s!", FORMAT_DATE("%B %d, %Y", date '2015-01-02'))

Returns

date: January 02, 2015!

Syntax

The FORMAT() syntax takes a format string and variable length list of arguments and produces a STRING result:

FORMAT(<format_string>, ...)

The <format_string> expression can contain zero or more format specifiers. Each format specifier is introduced by the % symbol, and must map to one or more of the remaining arguments. For the most part, this is a one-to-one mapping, except when the * specifier is present. For example, %.*i maps to two arguments—a length argument and a signed integer argument. If the number of arguments related to the format specifiers is not the same as the number of arguments, an error occurs.

Supported format specifiers

The FORMAT() function format specifier follows this prototype:

%[flags][width][.precision]specifier

The supported format specifiers are identified in the following table. Extensions from printf() are identified in italics.

^*The specifiers o, x, and X raise an error if negative values are used.

The format specifier can optionally contain the sub-specifiers identified above in the specifier prototype.

These sub-specifiers must comply with the following specifications.

Flags

Flags may be specified in any order. Duplicate flags are not an error. When flags are not relevant for some element type, they are ignored.

Width

Precision

%t and %T behavior

The %t and %T format specifiers are defined for all types. The width, precision, and flags act as they do for %s: the width is the minimum width and the STRING will be padded to that size, and precision is the maximum width of content to show and the STRING will be truncated to that size, prior to padding to width.

%t is always meant to be a readable form of the value.

%T is always a valid SQL literal of a similar type, such as a wider numeric type. The literal will not include casts or a type name, except for the special case of non-finite floating point values.

The STRING is formatted as follows:

Error conditions

If a format specifier is invalid, or is not compatible with the related argument type, or the wrong number or arguments are provided, then an error is produced. For example, the following FORMAT_STRING expressions are invalid:

FORMAT('%s', 1)

FORMAT('%')

NULL argument handling

A NULL format string results in a NULL output STRING. Any other arguments are ignored in this case.

The function generally produces a NULL value if a NULL argument is present. For example, FORMAT('%i', <NULL expression>) produces a NULL STRING as output.

However, there are some exceptions: if the format specifier is %t or %T (both of which produce STRINGs that effectively match CAST and literal value semantics), a NULL value produces 'NULL' (without the quotes) in the result STRING. For example, the function:

FORMAT('00-%t-00', <NULL expression>)

Returns

00-NULL-00

Additional semantic rules

FLOAT64 values can be +/-inf or NaN. When an argument has one of those values, the result of the format specifiers %f, %F, %e, %E, %g, %G, and %t are inf, -inf, or nan (or the same in uppercase) as appropriate. This is consistent with how BigQuery casts these values to STRING. For %T, BigQuery returns quoted strings for FLOAT64 values that don't have non-string literal representations.

JSON functions

BigQuery supports functions that help you retrieve data stored in JSON-formatted strings. These functions are:

• JSON_EXTRACT(json_string_expr, json_path_string_literal), which returns JSON values as STRINGs.
• JSON_EXTRACT_SCALAR(json_string_expr, json_path_string_literal), which returns scalar JSON values as STRINGs.

The json_string_expr parameter must be a JSON-formatted string. For example:

{"class" : {"students" : [{"name" : "Jane"}]}}

The json_path_string_literal parameter identifies the value or values you want to obtain from the JSON-formatted string. You construct this parameter using the JSONPath format. As part of this format, this parameter must start with a $ symbol, which refers to the outermost level of the JSON-formatted string. You can identify child values using dot or bracket notation. If the JSON object is an array, you can use brackets to specify the array index.

Both functions return NULL if the json_path_string_literal parameter does not match a value in json_string_expr. If the selected value for JSON_EXTRACT_SCALAR is not scalar, such as an object or an array, the function returns NULL.

If the JSONPath is invalid, these functions raise an error.

In cases where a JSON key uses invalid JSONPath characters, you can escape those characters using single quotes and brackets, [' ']. For example:

SELECT JSON_EXTRACT_SCALAR('{"a.b": {"c": "world"}}', "$['a.b'].c") as hello;

+-------+
| hello |
+-------+
| world |
+-------+

Examples

SELECT JSON_EXTRACT(json_text, '$') AS json_text_string
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------------------------------------------------+
| json_text_string                                          |
+-----------------------------------------------------------+
| {"class":{"students":[{"name":"Jane"}]}}                  |
| {"class":{"students":[]}}                                 |
| {"class":{"students":[{"name":"John"},{"name":"Jamie"}]}} |
+-----------------------------------------------------------+

SELECT JSON_EXTRACT(json_text, '$.class.students[0]') AS first_student
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+

SELECT JSON_EXTRACT(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| {"first":"Jamie"} |
+-------------------+

SELECT JSON_EXTRACT(json_text, "$.class['students']") AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+

SELECT JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

Array functions

ARRAY_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

Description

Concatenates one or more arrays into a single array.

Return type

ARRAY

Examples

SELECT ARRAY_CONCAT([1, 2], [3, 4], [5, 6]) as count_to_six;

+--------------------------------------------------+
| count_to_six                                     |
+--------------------------------------------------+
| [1, 2, 3, 4, 5, 6]                               |
+--------------------------------------------------+

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

Description

Returns the size of the array. Returns 0 for an empty array. Returns NULL if the array_expression is NULL.

Return type

INT64

Examples

WITH items AS
  (SELECT ["apples", "bananas", NULL, "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

+---------------------------------+------+
| list                            | size |
+---------------------------------+------+
| [apples, bananas, NULL, grapes] | 4    |
| [coffee, tea, milk]             | 3    |
| [cake, pie]                     | 2    |
+---------------------------------+------+

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

Description

Returns a concatenation of the elements in array_expression as a STRING. The value for array_expression can either be an array of STRING or BYTES data types.

If the null_text parameter is used, the function replaces any NULL values in the array with the value of null_text.

If the null_text parameter is not used, the function omits the NULL value and its preceding delimiter.

Examples

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk              |
| cake--pie                      |
+--------------------------------+

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--', 'MISSING') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk               |
| cake--pie--MISSING             |
+--------------------------------+

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

Description

Returns an array of values. The start_expression and end_expression parameters determine the inclusive start and end of the array.

The GENERATE_ARRAY function accepts the following data types as inputs:

• FLOAT64
• INT64

The step_expression parameter determines the increment used to generate array values. The default value for this parameter is 1.

This function returns an error if step_expression is set to 0, or if any input is NaN.

Return Data Type

ARRAY

Examples

The following returns an array of integers, with a default step of 1.

SELECT GENERATE_ARRAY(1, 5) AS example_array;

+-----------------+
| example_array   |
+-----------------+
| [1, 2, 3, 4, 5] |
+-----------------+

The following returns an array using a user-specified step size.

SELECT GENERATE_ARRAY(0, 10, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| [0, 3, 6, 9]  |
+---------------+

The following returns an array using a negative value, -3 for its step size.

SELECT GENERATE_ARRAY(10, 0, -3) AS example_array;

+---------------+
| example_array |
+---------------+
| [10, 7, 4, 1] |
+---------------+

The following returns an array using the same value for the start_expression and end_expression.

SELECT GENERATE_ARRAY(4, 4, 10) AS example_array;

+---------------+
| example_array |
+---------------+
| [4]           |
+---------------+

The following returns an empty array, because the start_expression is greater than the end_expression, and the step_expression value is positive.

SELECT GENERATE_ARRAY(10, 0, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

The following returns a NULL array, because one of its inputs is NULL.

SELECT GENERATE_ARRAY(5, NULL, 1) AS example_array;

+---------------+
| example_array |
+---------------+
| NULL          |
+---------------+

The following returns multiple arrays.

SELECT GENERATE_ARRAY(start, 5) AS example_array
FROM UNNEST([3, 4, 5]) AS start;

+---------------+
| example_array |
+---------------+
| [3, 4, 5]     |
| [4, 5]        |
| [5]           |
+---------------+

GENERATE_DATE_ARRAY

GENERATE_DATE_ARRAY(start_date, end_date[, INTERVAL INT64_expr date_part])

Description

Returns an array of dates. The start_date and end_date parameters determine the inclusive start and end of the array.

The GENERATE_DATE_ARRAY function accepts the following data types as inputs:

• start_date must be a DATE
• end_date must be a DATE
• INT64_expr must be an INT64
• date_part must be either DAY, WEEK, MONTH, QUARTER, or YEAR.

The INT64_expr parameter determines the increment used to generate dates. The default value for this parameter is 1 day.

This function returns an error if INT64_expr is set to 0, or if any input is NaN.

Return Data Type

An ARRAY containing 0 or more DATE values.

Examples

The following returns an array of dates, with a default step of 1.

SELECT GENERATE_DATE_ARRAY('2016-10-05', '2016-10-08') AS example;

+--------------------------------------------------+
| example                                          |
+--------------------------------------------------+
| [2016-10-05, 2016-10-06, 2016-10-07, 2016-10-08] |
+--------------------------------------------------+

The following returns an array using a user-specified step size.

SELECT GENERATE_DATE_ARRAY(
 '2016-10-05', '2016-10-09, INTERVAL 2 DAY) AS example;

+--------------------------------------+
| example                              |
+--------------------------------------+
| [2016-10-05, 2016-10-07, 2016-10-09] |
+--------------------------------------+

The following returns an array using a negative value, -3 for its step size.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL -3 DAY) AS example;

+--------------------------+
| example                  |
+--------------------------+
| [2016-10-05, 2016-10-02] |
+--------------------------+

The following returns an array using the same value for the start_dateand end_date.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-05', INTERVAL 8 DAY) AS example;

+--------------+
| example      |
+--------------+
| [2016-10-05] |
+--------------+

The following returns an empty array, because the start_date is greater than the end_date, and the step value is positive.

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

The following returns a NULL array, because one of its inputs is NULL.

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

The following returns an array of dates, using MONTH as the date_part interval:

SELECT GENERATE_DATE_ARRAY('2016-01-01',
  '2016-12-31', INTERVAL 2 MONTH) AS example;

+--------------------------------------------------------------------------+
| example                                                                  |
+--------------------------------------------------------------------------+
| [2016-01-01, 2016-03-01, 2016-05-01, 2016-07-01, 2016-09-01, 2016-11-01] |
+--------------------------------------------------------------------------+

The following uses non-constant dates to generate an array.

WITH StartsAndEnds AS (
  SELECT DATE '2016-01-01' AS date_start, DATE '2016-01-31' AS date_end
  UNION ALL SELECT DATE "2016-04-01", DATE "2016-04-30"
  UNION ALL SELECT DATE "2016-07-01", DATE "2016-07-31"
  UNION ALL SELECT DATE "2016-10-01", DATE "2016-10-31"
)
SELECT GENERATE_DATE_ARRAY(date_start, date_end, INTERVAL 1 WEEK) AS date_range
FROM StartsAndEnds;

+--------------------------------------------------------------+
| date_range                                                   |
+--------------------------------------------------------------+
| [2016-01-01, 2016-01-08, 2016-01-15, 2016-01-22, 2016-01-29] |
| [2016-04-01, 2016-04-08, 2016-04-15, 2016-04-22, 2016-04-29] |
| [2016-07-01, 2016-07-08, 2016-07-15, 2016-07-22, 2016-07-29] |
| [2016-10-01, 2016-10-08, 2016-10-15, 2016-10-22, 2016-10-29] |
+--------------------------------------------------------------+

OFFSET and ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

Description

Accesses an ARRAY element by position and returns the element. OFFSET means that the numbering starts at zero, ORDINAL means that the numbering starts at one.

A given array can be interpreted as either 0-based or 1-based. When accessing an array element, you must preface the array position with OFFSET or ORDINAL, respectively; there is no default behavior.

Both OFFSET and ORDINAL generate an error if the index is out of range.

Return type

Varies depending on the elements in the ARRAY.

Examples

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM items;

+----------------------------------+-----------+-----------+
| list                             | offset_1  | ordinal_1 |
+----------------------------------+-----------+-----------+
| [apples, bananas, pears, grapes] | bananas   | apples    |
| [coffee, tea, milk]              | tea       | coffee    |
| [cake, pie]                      | pie       | cake      |
+----------------------------------+-----------+-----------+

SAFE_OFFSET and SAFE_ORDINAL

array_expression[SAFE_OFFSET(zero_based_offset)]
array_expression[SAFE_ORDINAL(one_based_offset)]

Description

Identical to OFFSET and ORDINAL, except returns NULL if the index is out of range.

Return type

Varies depending on the elements in the ARRAY.

Example

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list,
  list[SAFE_OFFSET(3)] as safe_offset_3,
  list[SAFE_ORDINAL(3)] as safe_ordinal_3
FROM items;

+----------------------------------+---------------+----------------+
| list                             | safe_offset_3 | safe_ordinal_3 |
+----------------------------------+---------------+----------------+
| [apples, bananas, pears, grapes] | grapes        | pears          |
| [coffee, tea, milk]              | NULL          | milk           |
| [cake, pie]                      | NULL          | NULL           |
+----------------------------------+---------------+----------------+

DATE functions

BigQuery supports the following DATE functions.

CURRENT_DATE

CURRENT_DATE([time_zone])

Description

Returns the current date as of the specified or default timezone.

This function supports an optional time_zone parameter. This parameter is a string representing the timezone to use. If no timezone is specified, the default timezone, UTC, is used. See Timezone definitions for information on how to specify a time zone.

If the time_zone parameter evaluates to NULL, this function returns NULL.

Return Data Type

DATE

Example

SELECT CURRENT_DATE() as the_date;

+--------------+
| the_date     |
+--------------+
| 2016-12-25   |
+--------------+

EXTRACT

EXTRACT(part FROM date_expression)

Description

Returns the value corresponding to the specified date part. The part must be one of:

• DAYOFWEEK (Returns 1-7, where 1=Sunday ... 7=Saturday)
• DAY
• DAYOFYEAR
• MONTH
• QUARTER (Returns 1-4)
• YEAR

Return Data Type

INT64

Example

SELECT EXTRACT(DAY FROM DATE '2013-12-25') as the_day;

+---------+
| the_day |
+---------+
| 25      |
+---------+

DATE (year, month, day)

DATE(year, month, day)

Description

Constructs a DATE from INT64 values representing the year, month, and day.

Return Data Type

DATE

Example

SELECT DATE(2016, 12, 25) as date;

+------------+
| date       |
+------------+
| 2016-12-25 |
+------------+

DATE (timestamp)

DATE(timestamp_expression[, timezone])

Description

Converts a timestamp_expression to a DATE data type. Supports an optional parameter to specify a timezone. See Timezone definitions for information on how to specify a time zone.

Return Data Type

DATE

Example

SELECT DATE(TIMESTAMP "2008-12-25 15:30:00+07", "America/Los_Angeles") as date;

+------------+
| date       |
+------------+
| 2008-12-25 |
+------------+

DATE_ADD

DATE_ADD(date_expression, INTERVAL INT64_expr date_part)

Description

Adds a specified time interval to a DATE.

DATE_ADD supports the following date_part values:

• DAY
• WEEK. Equivalent to 7 DAYs.
• MONTH
• QUARTER
• YEAR

Special handling is required for MONTH, QUARTER, and YEAR parts when the date is at (or near) the last day of the month. If the resulting month has fewer days than the original date's day, then the result day is the last day of the new month.

Return Data Type

DATE

Example

SELECT DATE_ADD(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_later;

+--------------------+
| five_days_later    |
+--------------------+
| 2008-12-30         |
+--------------------+

DATE_SUB

DATE_SUB(date_expression, INTERVAL INT64_expr date_part)

Description

Subtracts a specified time interval from a DATE.

DATE_SUB supports the following date_part values:

• DAY
• WEEK. Equivalent to 7 DAYs.
• MONTH
• QUARTER
• YEAR

Special handling is required for MONTH, QUARTER, and YEAR parts when the date is at (or near) the last day of the month. If the resulting month has fewer days than the original date's day, then the result day is the last day of the new month.

Return Data Type

DATE

Example

SELECT DATE_SUB(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_ago;

+---------------+
| five_days_ago |
+---------------+
| 2008-12-20    |
+---------------+

DATE_DIFF

DATE_DIFF(date_expression, date_expression, date_part)

Description

Computes the number of specified date_part differences between two date expressions. This can be thought of as the number of date_part boundaries crossed between the two dates. If the first date occurs before the second date, then the result is negative.

DATE_DIFF supports the following date_part values:

• DAY
• MONTH
• QUARTER
• YEAR

Return Data Type

INT64

Example

SELECT DATE_DIFF(DATE "2010-07-07", DATE "2008-12-25", DAY) as days_diff;

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

Description

Truncates the date to the specified granularity.

DATE_TRUNC supports the following values for date_part:

• DAY
• WEEK
• MONTH
• QUARTER
• YEAR

Return Data Type

DATE

Example

SELECT DATE_TRUNC(DATE '2008-12-25', MONTH) as month;

+------------+
| month      |
+------------+
| 2008-12-01 |
+------------+

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(INT64_expression)

Description

Interprets INT64_expression as the number of days since 1970-01-01.

Return Data Type

DATE

Example

SELECT DATE_FROM_UNIX_DATE(14238) as date_from_epoch;

+-----------------+
| date_from_epoch |
+-----------------+
| 2008-12-25      |
+-----------------+

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

Description

Formats the date_expr according to the specified format_string.

See Supported Format Elements For DATE for a list of format elements that this function supports.

Return Data Type

STRING

Example

SELECT FORMAT_DATE("%x", DATE "2008-12-25") as US_format;

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

Description

Uses a format_string and a string representation of a date to return a DATE object.

When using PARSE_DATE, keep the following in mind:

• Unspecified fields. Any unspecified field is initialized from 1970-01-01.
• Case insensitive names. Names, such as Monday, February, and so on, are case insensitive.
• Whitespace. One or more consecutive white spaces in the format string matches zero or more consecutive white spaces in the date string. In addition, leading and trailing white spaces in the date string are always allowed -- even if they are not in the format string.
• Format precedence. When two (or more) format elements have overlapping information (for example both %F and %Y affect the year), the last one generally overrides any earlier ones.

See Supported Format Elements For DATE for a list of format elements that this function supports.

Return Data Type

DATE

Example

SELECT PARSE_DATE("%x", "12/25/08") as parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

UNIX_DATE

UNIX_DATE(date_expression)

Description

Returns the number of days since 1970-01-01.

Return Data Type

INT64

Example

SELECT UNIX_DATE(DATE "2008-12-25") as days_from_epoch;

+-----------------+
| days_from_epoch |
+-----------------+
| 14238           |
+-----------------+

Supported Format Elements for DATE

Unless otherwise noted, DATE functions that use format strings support the following elements:

DATETIME functions

BigQuery supports the following DATETIME functions.

DATETIME (year, month, hour, minute, second)

DATETIME(year, month, day, hour, minute, second)

Description

Constructs a DATETIME object using INT64 values representing the year, month, day, hour, minute, and second.

Return Data Type

DATETIME

Example

SELECT DATETIME(2008, 12, 25, 15, 30, 00) as datetime;

+---------------------+
| datetime            |
+---------------------+
| 2008-12-25 15:30:00 |
+---------------------+

DATETIME (date, time)

DATETIME(date_expression, time_expression)

Description

Constructs a DATETIME object using a DATE object and a TIME object.

Return Data Type

DATETIME

Example

DATETIME(DATE "2008-12-25", TIME "15:30:00") as datetime;

+---------------------+
| datetime            |
+---------------------+
| 2008-12-25 15:30:00 |
+---------------------+

DATETIME (timestamp, timezone)

DATETIME(timestamp_expression, timezone)

Description

Constructs a DATETIME object using a TIMESTAMP object and a timezone.

Return Data Type

DATETIME

Example

SELECT DATETIME(TIMESTAMP "2008-12-25 15:30:00+00", "America/Los_Angeles")
AS datetime;

+---------------------+
| datetime            |
+---------------------+
| 2008-12-25 07:30:00 |
+---------------------+

DATETIME_ADD

DATETIME_ADD(datetime_expression, INTERVAL INT64_expr part)

Description

Adds INT64_expr units of part to the DATETIME object.

DATETIME_ADD supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK. Equivalent to 7 DAYs.
• MONTH
• QUARTER
• YEAR

Special handling is required for MONTH, QUARTER, and YEAR parts when the date is at (or near) the last day of the month. If the resulting month has fewer days than the original DATETIME's day, then the result day is the last day of the new month.

Return Data Type

DATETIME

Example

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_ADD(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_date               | later                  |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:40:00    |
+-----------------------------+------------------------+

DATETIME_SUB

DATETIME_SUB(datetime_expression, INTERVAL INT64_expr part)

Description

Subtracts INT64_expr units of part from the DATETIME.

DATETIME_SUB supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK. Equivalent to 7 DAYs.
• MONTH
• QUARTER
• YEAR

Special handling is required for MONTH, QUARTER, and YEAR parts when the date is at (or near) the last day of the month. If the resulting month has fewer days than the original DATETIME's day, then the result day is the last day of the new month.

Return Data Type

DATETIME

Example

SELECT
  DATETIME "2008-12-25 15:30:00 as original_date,
  DATETIME_SUB(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date               | earlier                |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:20:00    |
+-----------------------------+------------------------+

DATETIME_DIFF

DATETIME_DIFF(datetime_expression, datetime_expression, part)

Description

Returns the number of whole specified part intervals between two DATETIME objects. Throws an error if the computation overflows the result type, such as if the difference in microseconds between the two DATETIME objects would overflow an INT64 value.

DATETIME_DIFF supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• MONTH
• QUARTER
• YEAR

Return Data Type

INT64

Example

SELECT
  DATETIME "2010-07-07 10:20:00" as first_datetime,
  DATETIME '2008-12-25 15:30:00" as second_datetime,
  DATETIME_DIFF(DATETIME "2010-07-07 10:20:00",
    DATETIME "2008-12-25 15:30:00", DAY) as difference;

+----------------------------+------------------------+------------------------+
| first_datetime             | second_datetime        | difference             |
+----------------------------+------------------------+------------------------+
| 2010-07-07 10:20:00        | 2008-12-25 15:30:00    | 559                    |
+----------------------------+------------------------+------------------------+

DATETIME_TRUNC

DATETIME_TRUNC(datetime_expression, part)

Description

Truncates a DATETIME object to the granularity of part.

DATETIME_TRUNC supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK
• MONTH
• QUARTER
• YEAR

Return Data Type

DATETIME

Example

SELECT
  DATETIME "2008-12-25 15:30:00" as original,
  DATETIME_TRUNC(DATETIME "2008-12-25 15:30:00", DAY) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 2008-12-25 15:30:00        | 2008-12-25 00:00:00    |
+----------------------------+------------------------+

FORMAT_DATETIME

FORMAT_DATETIME(format_string, datetime_expression)

Description

Formats a DATETIME object according to the specified format_string. See Supported Format Elements For DATETIME for a list of format elements that this function supports.

Return Data Type

STRING

Example

SELECT
  FORMAT_DATETIME("%c", DATETIME "2008-12-25 15:30:00")
  AS formatted;

PARSE_DATETIME

PARSE_DATETIME(format_string, string)

Description

Uses a format_string and a string representation of a timestamp to return a TIMESTAMP object. See Supported Format Elements For DATETIME for a list of format elements that this function supports.

When using PARSE_DATETIME, keep the following in mind:

• Unspecified fields. Any unspecified field is initialized from 1970-01-01 00:00:00.0. For instance, if the year is unspecified then it defaults to 1970, and so on.
• Case insensitive names. Names, such as Monday, February, and so on, are case insensitive.
• Whitespace. One or more consecutive white spaces in the format string matches zero or more consecutive white spaces in the DATETIME string. In addition, leading and trailing white spaces in the DATETIME string are always allowed—even if they are not in the format string.
• Format precedence. When two (or more) format elements have overlapping information (for example both %F and %Y affect the year), the last one generally overrides any earlier ones, with some exceptions (see the descriptions of %s, %C, and %y).

Return Data Type

DATETIME

Supported format elements for DATETIME

Unless otherwise noted, DATETIME functions that use format strings support the following elements:

TIME functions

BigQuery supports the following TIME functions.

TIME (hour, minute, second)

TIME(hour, minute, second)

Description

Constructs a TIME object using INT64 values representing the hour, minute, and second.

Return Data Type

TIME

Example

SELECT TIME(15, 30, 00) as time;

+---------------------+
| time                |
+---------------------+
| 15:30:00            |
+---------------------+

TIME (timestamp)

TIME(timestamp, [timezone])

Description

Constructs a TIME object using a TIMESTAMP object. Takes an optional timezone parameter.

Return Data Type

TIME

Example

SELECT TIME(TIMESTAMP "2008-12-25 15:30:00-08", "America/Los_Angeles") as time;

+---------------------+
| time                |
+---------------------+
| 15:30:00            |
+---------------------+

TIME_ADD

TIME_ADD(time_expression, INTERVAL INT64_expr part)

Description

Adds INT64_expr units of part to the TIME object.

TIME_ADD supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

This function automatically adjusts when values fall outside of the 00:00:00 to 24:00:00 boundary. For example, if you add an hour to 23:30:00, the returned value is 00:30:00.

Return Data Types

TIME

Example

SELECT
  TIME "15:30:00" as original_time,
  TIME_ADD(TIME "15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_time               | later                  |
+-----------------------------+------------------------+
| 15:30:00                    | 15:40:00               |
+-----------------------------+------------------------+

TIME_SUB

TIME_SUB(time_expression, INTERVAL INT_expr part)

Description

Subtracts INT64_expr units of part from the TIME object.

TIME_SUB supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

This function automatically adjusts when values fall outside of the 00:00:00 to 24:00:00 boundary. For example, if you subtract an hour from 00:30:00, the returned value is 23:30:00.

Return Data Type

TIME

Example

SELECT
  TIME "15:30:00" as original_date,
  TIME_SUB(TIME "15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date                | earlier                |
+-----------------------------+------------------------+
| 15:30:00                    | 15:20:00               |
+-----------------------------+------------------------+

TIME_DIFF

TIME_DIFF(time_expression, time_expression, part)

Description

Returns the number of whole specified part intervals between two TIME objects. Throws an error if the computation overflows the result type, such as if the difference in microseconds between the two time objects would overflow an INT64 value.

TIME_DIFF supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Return Data Type

INT64

Example

SELECT
  TIME "15:30:00" as first_time,
  TIME "14:35:00" as second_time,
  TIME_DIFF(TIME "15:30:00", TIME "14:35:00, MINUTE) as difference;

+----------------------------+------------------------+------------------------+
| first_time                 | second_time            | difference             |
+----------------------------+------------------------+------------------------+
| 15:30:00                   | 14:35:00               | 55                     |
+----------------------------+------------------------+------------------------+

TIME_TRUNC

TIME_TRUNC(time_expression, part)

Description

Truncates a TIME object to the granularity of part.

TIME_TRUNC supports the following values for part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR

Return Data Type

TIME

Example

SELECT
  TIME "15:30:00" as original,
  TIME_TRUNC(TIME "15:30:00", HOUR) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 15:30:00                   | 15:00:00               |
+----------------------------+------------------------+

Supported format elements for TIME

Unless otherwise noted, TIME functions that use format strings support the following elements:

TIMESTAMP functions

BigQuery supports the following TIMESTAMP functions.

NOTE: These functions return a runtime error if overflow occurs; result values are bounded by the defined date and timestamp min/max values.

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

Description

Parentheses are optional. This function handles leap seconds by smearing them across a window of 20 hours around the inserted leap second. CURRENT_TIMESTAMP() produces a TIMESTAMP value that is continuous, non-ambiguous, has exactly 60 seconds per minute and does not repeat values over the leap second.

Supported Input Types

Not applicable

Result Data Type

TIMESTAMP

Example

SELECT CURRENT_TIMESTAMP() as now;

+-------------------------------+
| now                           |
+-------------------------------+
| 2016-05-16 18:12:47.145482+00 |
+-------------------------------+

EXTRACT

EXTRACT(part FROM timestamp_expression [AT TIME ZONE tz_spec])

Description

Returns an INT64 value that corresponds to the specified part from a supplied timestamp_expression.

Allowed part values are:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAYOFWEEK
• DAY
• DAYOFYEAR
• MONTH
• QUARTER
• YEAR
• DATE
• DATETIME
• TIME

Returned values truncate lower order time periods—for example, when extracting seconds, the millisecond and microsecond values are truncated.

See Timezone definitions for information on how to specify a time zone.

Return Data Type

Generally INT64 . Returns DATE if part is DATE.

Example

SELECT EXTRACT(DAY
  FROM TIMESTAMP "2008-12-25 15:30:00" AT TIME ZONE "America/Los_Angeles")
  AS the_day;

+------------+
| the_day    |
+------------+
| 25         |
+------------+

STRING

STRING(timestamp_expression[, timezone])

Description

Converts a timestamp_expression to a STRING data type. Supports an optional parameter to specify a timezone. See Timezone definitions for information on how to specify a time zone.

Return Data Type

STRING

Example

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles") as string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 15:30:00-08        |
+-------------------------------+

TIMESTAMP (string)

TIMESTAMP(string_expression[, timezone])

Description

Converts a string_expression to a TIMESTAMP data type. Supports an optional parameter to specify a timezone. See Timezone definitions for information on how to specify a time zone.

Return Data Type

TIMESTAMP

Example

SELECT TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 23:30:00 UTC |
+-------------------------+

TIMESTAMP (date)

TIMESTAMP(date_expression[, timezone])

Description

Converts a date_expression to a TIMESTAMP data type. Supports an optional parameter to specify a timezone. See Timezone definitions for information on how to specify a time zone.

Return Data Type

TIMESTAMP

Example

SELECT TIMESTAMP(DATE "2008-12-25", "America/Los_Angeles") as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 08:00:00 UTC |
+-------------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL INT64_expr date_part)

Description

Adds INT64_expr units of date_part to the timestamp, independent of any time zone.

TIMESTAMP_ADD supports the following values for date_part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Equivalent to 60 MINUTEs.

Return Data Types

TIMESTAMP

Example

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_ADD(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS later;

+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:40:00+00 |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL INT_expr date_part)

Description

Subtracts INT64_expr units of date_part from the timestamp, independent of any time zone.

TIMESTAMP_SUB supports the following values for date_part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Equivalent to 60 MINUTEs.

Return Data Type

TIMESTAMP

Example

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_SUB(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS earlier;

+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:20:00+00 |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression, timestamp_expression, date_part)

Description

Returns the number of whole specified date_part intervals between two timestamps. Throws an error if the computation overflows the result type, such as if the difference in microseconds between the two timestamps would overflow an INT64 value.

TIMESTAMP_DIFF supports the following values for date_part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR. Equivalent to 60 MINUTEs.

Return Data Type

INT64

Example

SELECT
  TIMESTAMP "2010-07-07 10:20:00 UTC" as first_timestamp,
  TIMESTAMP "2008-12-25 15:30:00 UTC" as second_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00 UTC",
    TIMESTAMP "2008-12-25 15:30:00 UTC", HOUR) AS hours;

+------------------------+------------------------+-------+
| first_timestamp        | second_timestamp       | hours |
+------------------------+------------------------+-------+
| 2010-07-07 10:20:00+00 | 2008-12-25 15:30:00+00 | 13410 |
+------------------------+------------------------+-------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part, [, time_zone])

Description

Truncates a timestamp to the granularity of date_part.

TIMESTAMP_TRUNC supports the following values for date_part:

• MICROSECOND
• MILLISECOND
• SECOND
• MINUTE
• HOUR
• DAY
• WEEK
• MONTH
• QUARTER
• YEAR

In addition, TIMESTAMP_TRUNC function supports an optional time_zone parameter. This parameter applies to the following date_parts:

• MINUTE
• HOUR
• DAY
• WEEK
• MONTH
• QUARTER
• YEAR

Use this parameter if you want to use a time zone other than the default timezone, UTC, as part of the truncate operation.

Return Data Type

TIMESTAMP

Example

SELECT
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'UTC') as utc,
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'America/Los_Angeles') as la;

+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25 00:00:00+00 | 2008-12-25 08:00:00+00 |
+------------------------+------------------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

Description

Formats a timestamp according to the specified format_string.

See Supported Format Elements For TIMESTAMP for a list of format elements that this function supports.

Return Data Type

STRING

Example

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles")
  AS formatted;

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 07:30:00 2008 |
+--------------------------+

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, string[, time_zone])

Description

Uses a format_string and a string representation of a timestamp to return a TIMESTAMP object.

When using PARSE_TIMESTAMP, keep the following in mind:

• Unspecified fields. Any unspecified field is initialized from 1970-01-01 00:00:00.0. This initialization value uses the time zone specified by the function's time zone argument, if present. If not, the initialization value uses the default time zone, UTC. For instance, if the year is unspecified then it defaults to 1970, and so on.
• Case insensitive names. Names, such as Monday, February, and so on, are case insensitive.
• Whitespace. One or more consecutive white spaces in the format string matches zero or more consecutive white spaces in the timestamp string. In addition, leading and trailing white spaces in the timestamp string are always allowed -- even if they are not in the format string.
• Format precedence. When two (or more) format elements have overlapping information (for example both %F and %Y affect the year), the last one generally overrides any earlier ones, with some exceptions (see the descriptions of %s, %C, and %y).

See Supported Format Elements For TIMESTAMP for a list of format elements that this function supports.

Return Data Type

TIMESTAMP

Example

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008", "America/Los_Angeles") as parsed;

+-------------------------+
| parsed                  |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_SECONDS (INT64)

TIMESTAMP_SECONDS(INT64_expression)

Description

Interprets INT64_expression as the number of seconds since 1970-01-01 00:00:00 UTC.

Return Data Type

TIMESTAMP

Example

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(INT64_expression)

Description

Interprets INT64_expression as the number of milliseconds since 1970-01-01 00:00:00 UTC.

Return Data Type

TIMESTAMP

Example

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(INT64_expression)

Description

Interprets INT64_expression as the number of microseconds since 1970-01-01 00:00:00 UTC.

Return Data Type

TIMESTAMP

Example

SELECT TIMESTAMP_MICROS(1230219000000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

Description

Returns the number of seconds since 1970-01-01 00:00:00 UTC. Truncates higher levels of precision.

Return Data Type

INT64

Example

SELECT UNIX_SECONDS(TIMESTAMP "2008-12-25 15:30:00") as seconds;

+------------+
| seconds    |
+------------+
| 1230219000 |
+------------+

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

Description

Returns the number of milliseconds since 1970-01-01 00:00:00 UTC. Truncates higher levels of precision.

Return Data Type

INT64

Example

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00 UTC") as millis;

+---------------+
| millis        |
+---------------+
| 1230219000000 |
+---------------+

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

Description

Returns the number of microseconds since 1970-01-01 00:00:00 UTC. Truncates higher levels of precision.

Return Data Type

INT64

Example

SELECT UNIX_MICROS(TIMESTAMP "2008-12-25 15:30:00") as micros;

+------------------+
| micros           |
+------------------+
| 1230219000000000 |
+------------------+

Supported format elements for TIMESTAMP

Unless otherwise noted, TIMESTAMP functions that use format strings support the following elements:

Timezone definitions

Certain date and timestamp functions allow you to override the default time zone and specify a different one. You can specify a timezone by supplying its UTC offset using the following format:

(+|-)H[H][:M[M]]

For example:

-08:00

Security functions

BigQuery supports the following security functions.

SESSION_USER

SESSION_USER()

Description

Returns the email address of whoever is executing the query.

Return Data Type

STRING

Example

SELECT SESSION_USER() as user;

+----------------------+
| user                 |
+----------------------+
| [email protected]     |
+----------------------+

NET functions

NET.HOST

NET.HOST(url)

Description

Takes a URL as a STRING and returns the host as a STRING. For best results, URL values should comply with the format as defined by RFC 3986. If the URL value does not comply with RFC 3986 formatting, this function makes a best effort to parse the input and return a relevant result. If the function cannot parse the input, it returns NULL.

Note: The function does not perform any normalization.

Return Data Type

STRING

Example

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:[email protected]:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Google.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL; unsupported"
);

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

Description

Takes a URL as a STRING and returns the public suffix (such as com, org, or net) as a STRING. For best results, URL values should comply with the format as defined by RFC 3986. If the URL value does not comply with RFC 3986 formatting, this function makes a best effort to parse the input and return a relevant result.

This function returns NULL if any of the following is true:

• It cannot parse the host from the input;
• The parsed host contains adjacent dots in the middle (not leading or trailing);
• The parsed host does not contain any public suffix.

Before looking up the public suffix, this function temporarily normalizes the host by converting upper case English letters to lower case and encoding all non-ASCII characters with Punycode. The function then returns the public suffix as part of the original host instead of the normalized host.

Note: The function does not perform Unicode normalization.

Note: The public suffix data may change over time. Consequently, input that produces a NULL result now may produce a non-NULL value in the future.

Return Data Type

STRING

Example

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:[email protected]:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Google.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL; unsupported"
);

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

Description

Takes a URL as a STRING and returns the registered or registerable domain (the public suffix plus one preceding label), as a STRING. For best results, URL values should comply with the format as defined by RFC 3986. If the URL value does not comply with RFC 3986 formatting, this function makes a best effort to parse the input and return a relevant result.

This function returns NULL if any of the following is true:

• It cannot parse the host from the input;
• The parsed host contains adjacent dots in the middle (not leading or trailing);
• The parsed host does not contain any public suffix;
• The parsed host contains only a public suffix without any preceding label.

Before looking up the public suffix, this function temporarily normalizes the host by converting upper case English letters to lower case and encoding all non-ASCII characters with Punycode. The function then returns the registered or registerable domain as part of the original host instead of the normalized host.

Note: The function does not perform Unicode normalization.

Note: The public suffix data may change over time. Consequently, input that produces a NULL result now may produce a non-NULL value in the future.

Return Data Type

STRING

Example

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:[email protected]:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Google.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL; unsupported"
);

Operators

Operators are represented by special characters or keywords; they do not use function call syntax. An operator manipulates any number of data inputs, also called operands, and returns a result.

Common conventions:

• Unless otherwise specified, all operators return NULL when one of the operands is NULL.
• All operators will throw an error if the computation result overflows.
• This includes floating point operators: +/-inf and NaN may only be returned if one of the operands is +/-inf or NaN.

The following table lists all BigQuery operators from highest to lowest precedence, i.e the order in which they will be evaluated within a statement.

Operators with the same precedence are left associative. This means that those operators are grouped together starting from the left and moving right. For example, the expression:

x AND y AND z

is interpreted as

( ( x AND y ) AND z )

The expression:

x * y / z

is interpreted as:

( ( x * y ) / z )

All comparison operators have the same priority and are grouped using left associativity. However, comparison operators are not associative. As a result, it is recommended that you use parentheses to improve readability and ensure expressions are resolved as desired. For example:

(x < y) IS FALSE

is recommended over:

x < y IS FALSE

Element access operators

Arithmetic operators

All arithmetic operators accept input of numeric type T, and the result type has type T unless otherwise indicated in the description below:

Result types for Addition and Multiplication:

Result types for Subtraction:

Result types for Division:

Result types for Unary Minus:

Bitwise operators

Logical operators

All logical operators allow only BOOL input.

Comparison operators

Comparisons always return BOOL. Comparisons require both operands to be the same type; if they are different, they are coerced to a common type for the comparison. Comparable data types are defined in Data Types.

STRUCTs support only 4 comparison operators: equal (=), not equal (!= and <>), and IN.

The following rules apply when comparing these data types:

• FLOAT64 : If one or both operands are NaN then FALSE is returned.
• BOOL: FALSE is less than TRUE.
• STRING: Strings are compared codepoint-by-codepoint, which means that canonically equivalent strings are only guaranteed to compare as equal if they have been normalized first.
• NULL: The convention holds here: any operation with a NULL input returns NULL.

When comparing values that have the STRUCT data type, it's possible that one or more fields are NULL. In such cases:

• If the two STRUCTs have the same fields, the operation returns NULL.
• If the two STRUCTs have different fields, the operation returns FALSE.

The following table demonstrates how STRUCT data types are compared when they have fields that are NULL valued.

IN operators

The IN operator supports the following syntaxes:

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

Arguments on either side of the IN operator are general expressions. It is common to use literals on the right side expression; however, this is not required.

The semantics of:

x IN (y, z, ...)

are defined as equivalent to:

(x = y) OR (x = z) OR ...

and the subquery and array forms are defined similarly.

x NOT IN ...

is equivalent to:

NOT(x IN ...)

The UNNEST form treats an array scan like UNNEST in the FROM clause:

x [NOT] IN UNNEST(<array expression>)

This form is often used with ARRAY parameters. For example:

x IN UNNEST(@array_parameter)

Note: A NULL ARRAY will be treated equivalently to an empty ARRAY.

When using the IN operator, the following semantics apply:

• IN with an empty right side expression is always FALSE
• IN with a NULL left side expression and a non-empty right side expression is always NULL
• IN with a NULL in the IN-list can only return TRUE or NULL, never FALSE
• NULL IN (NULL) returns NULL
• IN UNNEST(<NULL array>) returns FALSE (not NULL)

IN can be used with multi-part keys by using the struct constructor syntax. For example:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

See the Struct Type section of the Data Types topic for more information on this syntax.

IS operators

IS operators return TRUE or FALSE for the condition they are testing. They never return NULL, even for NULL inputs, unlike the IS_INF and IS_NAN functions defined in Mathematical Functions. If NOT is present, the output BOOL value is inverted.

Conditional expressions

Conditional expressions impose constraints on the evaluation order of their inputs. In essence, they are evaluated left to right, with short-circuiting, and only evaluate the output value that was chosen. In contrast, all inputs to regular functions are evaluated before calling the function. Short-circuiting in conditional expressions can be exploited for error handling or performance tuning.

Expression subqueries

There are four types of expression subqueries, i.e. subqueries that are used as expressions. Expression subqueries return NULL or a single value, as opposed to a column or table, and must be surrounded by parentheses. For a fuller discussion of subqueries, see Subqueries.

Examples

The following examples of expression subqueries assume that t.int_array has type ARRAY<INT64>.