The Firebird 5.0 Language Reference | Date And Time Functions

Procedural SQL (PSQL) StatementsAggregate Functions

`EXTRACT()`

Extracts a datetime unit from a datetime value

Result type

SMALLINT or NUMERIC

Syntax

EXTRACT (<part> FROM <datetime>)

<part> ::=
    YEAR | MONTH | QUARTER | WEEK
  | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND
  | TIMEZONE_HOUR | TIMEZONE_MINUTE
<datetime> ::= a DATE, TIME or TIMESTAMP expression

Table 1. `EXTRACT` Function Parameters
Parameter	Description
part	Date/time unit
datetime	An expression of the `DATE`, `TIME` or `TIMESTAMP` type

Extracts and returns an element from a DATE, TIME or TIMESTAMP expression.

Returned Data Types and Ranges

The returned data types and possible ranges are shown in the table below.If you try to extract a part that isn’t present in the date/time argument (e.g. SECOND from a DATE or YEAR from a TIME), an error occurs.

Table 1. Types and ranges of `EXTRACT` results
Part	Type	Range	Comment
`YEAR`	`SMALLINT`	1-9999
`MONTH`	`SMALLINT`	1-12
`QUARTER`	`SMALLINT`	1-4
`WEEK`	`SMALLINT`	1-53
`DAY`	`SMALLINT`	1-31
`WEEKDAY`	`SMALLINT`	0-6	0 = Sunday
`YEARDAY`	`SMALLINT`	0-365	0 = January 1
`HOUR`	`SMALLINT`	0-23
`MINUTE`	`SMALLINT`	0-59
`SECOND`	`NUMERIC(9,4)`	0.0000-59.9999	includes millisecond as fraction
`MILLISECOND`	`NUMERIC(9,1)`	0.0-999.9
`TIMEZONE_HOUR`	`SMALLINT`	-23 - +23
`TIMEZONE_MINUTE`	`SMALLINT`	-59 - +59

`MILLISECOND`

Extracts the millisecond value from a TIME or TIMESTAMP.The data type returned is NUMERIC(9,1).

Note	If you extract the millisecond from [fblangref50-contextvars-current-time], be aware that this variable defaults to seconds precision, so the result will always be 0.Extract from `CURRENT_TIME(3)` or [fblangref50-contextvars-current-timestamp] to get milliseconds precision.

`WEEK`

Extracts the ISO-8601 week number from a DATE or TIMESTAMP.ISO-8601 weeks start on a Monday and always have the full seven days.Week 1 is the first week that has a majority (at least 4) of its days in the new year.The first 1-3 days of the year may belong to the last week (52 or 53) of the previous year.Likewise, a year’s final 1-3 days may belong to week 1 of the following year.

Caution

Be careful when combining WEEK and YEAR results.For instance, 30 December 2008 lies in week 1 of 2009, so extract(week from date '30 Dec 2008') returns 1.However, extracting YEAR always gives the calendar year, which is 2008.In this case, WEEK and YEAR are at odds with each other.The same happens when the first days of January belong to the last week of the previous year.

Please also notice that WEEKDAY is not ISO-8601 compliant: it returns 0 for Sunday, whereas ISO-8601 specifies 7.

See also

Data Types for Dates and Times

`FIRST_DAY()`

Returns the first day of a time period containing a datetime value

Result Type

DATE, TIMESTAMP (with or without time zone)

Syntax

FIRST_DAY(OF <period> FROM date_or_timestamp)

<period> ::= YEAR | MONTH | QUARTER | WEEK

Table 1. `FIRST_DAY` Function Parameters
Parameter	Description
date_or_timestamp	Expression of type `DATE`, `TIMESTAMP WITHOUT TIME ZONE` or `TIMESTAMP WITH TIME ZONE`

FIRST_DAY returns a date or timestamp (same as the type of date_or_timestamp) with the first day of the year, month or week of a given date or timestamp value.

Note	The first day of the week is considered as Sunday, following the same rules as for [fblangref50-scalarfuncs-extract] with `WEEKDAY`. When a timestamp is passed, the return value preserves the time part.

Examples of `FIRST_DAY`

select
  first_day(of month from current_date),
  first_day(of year from current_timestamp),
  first_day(of week from date '2017-11-01'),
  first_day(of quarter from date '2017-11-01')
from rdb$database;

`LAST_DAY()`

Returns the last day of a time period containing a datetime value

Result Type

DATE, TIMESTAMP (with or without time zone)

Syntax

LAST_DAY(OF <period> FROM date_or_timestamp)

<period> ::= YEAR | MONTH | QUARTER | WEEK

Table 1. `LAST_DAY` Function Parameters
Parameter	Description
date_or_timestamp	Expression of type `DATE`, `TIMESTAMP WITHOUT TIME ZONE` or `TIMESTAMP WITH TIME ZONE`

LAST_DAY returns a date or timestamp (same as the type of date_or_timestamp) with the last day of the year, month or week of a given date or timestamp value.

Note	The last day of the week is considered as Saturday, following the same rules as for [fblangref50-scalarfuncs-extract] with `WEEKDAY`. When a timestamp is passed, the return value preserves the time part.

Examples of `LAST_DAY`

select
  last_day(of month from current_date),
  last_day(of year from current_timestamp),
  last_day(of week from date '2017-11-01'),
  last_day(of quarter from date '2017-11-01')
from rdb$database;

Type Casting Functions

`CAST()`

Converts a value from one data type to another

Result type

As specified by target_type

Syntax

CAST (<expression> AS <target_type>)

<target_type> ::= <domain_or_non_array_type> | <array_datatype>

<domain_or_non_array_type> ::=
  !! See Scalar Data Types Syntax !!

<array_datatype> ::=
  !! See Array Data Types Syntax !!

Table 1. `CAST` Function Parameters
Parameter	Description
expression	SQL expression
sql_datatype	SQL data type

CAST converts an expression to the desired data type or domain.If the conversion is not possible, an error is raised.

“Shorthand” Syntax

Alternative syntax, supported only when casting a string literal to a DATE, TIME or TIMESTAMP:

datatype 'date/timestring'

This syntax was already available in InterBase, but was never properly documented.In the SQL standard, this feature is called “datetime literals”.

Note	Since Firebird 4.0, the use of `'NOW'`, `'YESTERDAY'` and `'TOMORROW'` in the shorthand cast is no longer allowed;only literals defining a fixed moment in time are supported.

Allowed Type Conversions

The following table shows the type conversions possible with CAST.

Table 1. Possible Type-castings with `CAST`
From	To
Numeric types	Numeric types `[VAR]CHAR` `BLOB`
`[VAR]CHAR` `BLOB`	`[VAR]CHAR` `BLOB` Numeric types `DATE` `TIME` `TIMESTAMP`
`DATE` `TIME`	`[VAR]CHAR` `BLOB` `TIMESTAMP`
`TIMESTAMP`	`[VAR]CHAR` `BLOB` `DATE` `TIME`

Keep in mind that sometimes information is lost, for instance when you cast a TIMESTAMP to a DATE.Also, the fact that types are CAST-compatible is in itself no guarantee that a conversion will succeed.“CAST(123456789 as SMALLINT)” will definitely result in an error, as will “CAST('Judgement Day' as DATE)”.

Casting Parameters

You can also cast statement parameters to a data type:

cast (? as integer)

This gives you control over the type of the parameter set up by the engine.Please notice that with statement parameters, you always need a full-syntax cast — shorthand casts are not supported.

Casting to a Domain or its Type

Casting to a domain or its base type are supported.When casting to a domain, any constraints (NOT NULL and/or CHECK) declared for the domain must be satisfied, or the cast will fail.Please be aware that a CHECK passes if it evaluates to TRUE or NULL!So, given the following statements:

create domain quint as int check (value >= 5000);
select cast (2000 as quint) from rdb$database;     -- (1)
select cast (8000 as quint) from rdb$database;     -- (2)
select cast (null as quint) from rdb$database;     -- (3)

only cast number 1 will result in an error.

When the TYPE OF modifier is used, the expression is cast to the base type of the domain, ignoring any constraints.With domain quint defined as above, the following two casts are equivalent and will both succeed:

select cast (2000 as type of quint) from rdb$database;
select cast (2000 as int) from rdb$database;

If TYPE OF is used with a (VAR)CHAR type, its character set and collation are retained:

create domain iso20 varchar(20) character set iso8859_1;
create domain dunl20 varchar(20) character set iso8859_1 collate du_nl;
create table zinnen (zin varchar(20));
commit;
insert into zinnen values ('Deze');
insert into zinnen values ('Die');
insert into zinnen values ('die');
insert into zinnen values ('deze');

select cast(zin as type of iso20) from zinnen order by 1;
-- returns Deze -> Die -> deze -> die

select cast(zin as type of dunl20) from zinnen order by 1;
-- returns deze -> Deze -> die -> Die

Warning

If a domain’s definition is changed, existing CASTs to that domain or its type may become invalid.If these CASTs occur in PSQL modules, their invalidation may be detected.See the note The RDB$VALID_BLR field, in Appendix A.

Casting to a Column’s Type

It is also possible to cast expressions to the type of an existing table or view column.Only the type itself is used;in the case of string types, this includes the character set but not the collation.Constraints and default values of the source column are not applied.

create table ttt (
  s varchar(40) character set utf8 collate unicode_ci_ai
);
commit;

select cast ('Jag har många vänner' as type of column ttt.s)
from rdb$database;

Warning

Warnings

If a column’s definition is altered, existing CASTs to that column’s type may become invalid.If these CASTs occur in PSQL modules, their invalidation may be detected.See the note The RDB$VALID_BLR field, in Appendix A.

Cast Examples

A full-syntax cast:

select cast ('12' || '-June-' || '1959' as date) from rdb$database

A shorthand string-to-date cast:

update People set AgeCat = 'Old'
  where BirthDate < date '1-Jan-1943'

Notice that you can drop even the shorthand cast from the example above, as the engine will understand from the context (comparison to a DATE field) how to interpret the string:

update People set AgeCat = 'Old'
  where BirthDate < '1-Jan-1943'

However, this is not always possible.The cast below cannot be dropped, otherwise the engine would find itself with an integer to be subtracted from a string:

select cast('today' as date) - 7 from rdb$database

Bitwise Functions

`BIN_AND()`

Bitwise AND

Result type

integer type (the widest type of the arguments)

Note	`SMALLINT` result is returned only if all the arguments are explicit `SMALLINT`s or `NUMERIC(n, 0)` with n <= 4;otherwise small integers return an `INTEGER` result.

Syntax

BIN_AND (number, number [, number ...])

Table 1. `BIN_AND` Function Parameters
Parameter	Description
number	A number of an integer type

Returns the result of the bitwise AND operation on the argument(s).

`BIN_NOT()`

Bitwise NOT

Result type

integer type matching the argument

Note	`SMALLINT` result is returned only if all the arguments are explicit `SMALLINT`s or `NUMERIC(n, 0)` with n <= 4;otherwise small integers return an `INTEGER` result.

Syntax

BIN_NOT (number)

Table 1. `BIN_NOT` Function Parameter
Parameter	Description
number	A number of an integer type

Returns the result of the bitwise NOT operation on the argument, i.e. one’s complement.

`BIN_OR()`

Bitwise OR

Result type

integer type (the widest type of the arguments)

Note	`SMALLINT` result is returned only if all the arguments are explicit `SMALLINT`s or `NUMERIC(n, 0)` with n <= 4;otherwise small integers return an `INTEGER` result.

Syntax

BIN_OR (number, number [, number ...])

Table 1. `BIN_OR` Function Parameters
Parameter	Description
number	A number of an integer type

Returns the result of the bitwise OR operation on the argument(s).

`BIN_SHL()`

Bitwise left-shift

Result type

BIGINT or INT128 depending on the first argument

Syntax

BIN_SHL (number, shift)

Table 1. `BIN_SHL` Function Parameters
Parameter	Description
number	A number of an integer type
shift	The number of bits the number value is shifted by

Returns the first argument bitwise left-shifted by the second argument, i.e. a << b or a·2^b.

See also

[fblangref50-scalarfuncs-bin-shr]

`BIN_SHR()`

Bitwise right-shift with sign extension

Result type

BIGINT or INT128 depending on the first argument

Syntax

BIN_SHR (number, shift)

Table 1. `BIN_SHR` Function Parameters
Parameter	Description
number	A number of an integer type
shift	The number of bits the number value is shifted by

Returns the first argument bitwise right-shifted by the second argument, i.e. a >> b or a/2^b.

The operation performed is an arithmetic right shift (x86 SAR), meaning that the sign of the first operand is always preserved.

See also

[fblangref50-scalarfuncs-bin-shl]

`BIN_XOR()`

Bitwise XOR

Result type

integer type (the widest type of the arguments)

Note	`SMALLINT` result is returned only if all the arguments are explicit `SMALLINT`s or `NUMERIC(n, 0)` with n <= 4;otherwise small integers return an `INTEGER` result.

Syntax

BIN_XOR (number, number [, number ...])

Table 1. `BIN_XOR` Function Parameters
Parameter	Description
number	A number of an integer type

Returns the result of the bitwise XOR operation on the argument(s).

UUID Functions

`CHAR_TO_UUID()`

Converts a string UUID to its binary representation

Result type

BINARY(16)

Syntax

CHAR_TO_UUID (ascii_uuid)

Table 1. `CHAR_TO_UUID` Function Parameter
Parameter	Description
ascii_uuid	A 36-character representation of UUID.‘`-`’ (hyphen) in positions 9, 14, 19 and 24;valid hexadecimal digits in any other positions, e.g. 'A0bF4E45-3029-2a44-D493-4998c9b439A3'

Converts a human-readable 36-char UUID string to the corresponding 16-byte UUID.

`CHAR_TO_UUID` Examples

select char_to_uuid('A0bF4E45-3029-2a44-D493-4998c9b439A3') from rdb$database
-- returns A0BF4E4530292A44D4934998C9B439A3 (16-byte string)

select char_to_uuid('A0bF4E45-3029-2A44-X493-4998c9b439A3') from rdb$database
-- error: -Human readable UUID argument for CHAR_TO_UUID must
--         have hex digit at position 20 instead of "X (ASCII 88)"

`GEN_UUID()`

Generates a random binary UUID

Result type

BINARY(16)

Syntax

GEN_UUID ()

Returns a universally unique ID as a 16-byte character string.

`GEN_UUID` Example

select gen_uuid() from rdb$database
-- returns e.g. 017347BFE212B2479C00FA4323B36320 (16-byte string)

`UUID_TO_CHAR()`

Converts a binary UUID to its string representation

Result type

CHAR(36)

Syntax

UUID_TO_CHAR (uuid)

Table 1. `UUID_TO_CHAR` Function Parameters
Parameter	Description
uuid	16-byte UUID

Converts a 16-byte UUID to its 36-character, human-readable ASCII representation.

`UUID_TO_CHAR` Examples

select uuid_to_char(x'876C45F4569B320DBCB4735AC3509E5F') from rdb$database
-- returns '876C45F4-569B-320D-BCB4-735AC3509E5F'

select uuid_to_char(gen_uuid()) from rdb$database
-- returns e.g. '680D946B-45FF-DB4E-B103-BB5711529B86'

select uuid_to_char('Firebird swings!') from rdb$database
-- returns '46697265-6269-7264-2073-77696E677321'

Functions for Sequences (Generators)

`GEN_ID()`

Increments a sequence (generator) value and returns its new value

Result type

BIGINT — dialect 2 and 3
INTEGER — dialect 1

Syntax

GEN_ID (generator-name, step)

Table 1. `GEN_ID` Function Parameters
Parameter	Description
generator-name	Identifier name of a generator (sequence)
step	An integer expression of the increment

If step equals 0, the function will leave the value of the generator unchanged and return its current value.

The SQL-compliant NEXT VALUE FOR syntax is preferred, except when an increment other than the configured increment of the sequence is needed.

Warning

If the value of the step parameter is less than zero, it will decrease the value of the generator.You should be cautious with such manipulations in the database, as they could compromise data integrity (meaning, subsequent insert statements could fail due to generating of duplicate id values).

Note	In dialect 1, the result type is `INTEGER`, in dialect 2 and 3 it is `BIGINT`.

`GEN_ID` Example

new.rec_id = gen_id(gen_recnum, 1);

Conditional Functions

`COALESCE()`

Returns the first non-NULL argument

Result type

Depends on input

Syntax

COALESCE (<exp1>, <exp2> [, <expN> ... ])

Table 1. `COALESCE` Function Parameters
Parameter	Description
exp1, exp2 … expN	A list of expressions of compatible types

The COALESCE function takes two or more arguments and returns the value of the first non-NULL argument.If all the arguments evaluate to NULL, the result is NULL.

`COALESCE` Examples

This example picks the Nickname from the Persons table.If it happens to be NULL, it goes on to FirstName.If that too is NULL, “'Mr./Mrs.'” is used.Finally, it adds the family name.All in all, it tries to use the available data to compose a full name that is as informal as possible.This scheme only works if absent nicknames and first names are NULL: if one of them is an empty string, COALESCE will happily return that to the caller.That problem can be fixed by using [fblangref50-scalarfuncs-nullif].

select
  coalesce (Nickname, FirstName, 'Mr./Mrs.') || ' ' || LastName
    as FullName
from Persons

`DECODE()`

Shorthand “simple CASE”-equivalent function

Result type

Depends on input

Syntax

DECODE(<testexpr>,
  <expr1>, <result1>
  [<expr2>, <result2> ...]
  [, <defaultresult>])

Table 1. `DECODE` Function Parameters
Parameter	Description
testexpr	An expression of any compatible type that is compared to the expressions expr1, expr2 … exprN
expr1, expr2, … exprN	Expressions of any compatible types, to which the testexpr expression is compared
result1, result2, … resultN	Returned values of any type
defaultresult	The expression to be returned if none of the conditions is met

DECODE is a shorthand for the so-called “simple CASE” construct, in which a given expression is compared to a number of other expressions until a match is found.The result is determined by the value listed after the matching expression.If no match is found, the default result is returned, if present, otherwise NULL is returned.

The equivalent CASE construct:

CASE <testexpr>
  WHEN <expr1> THEN <result1>
  [WHEN <expr2> THEN <result2> ...]
  [ELSE <defaultresult>]
END

Caution

Matching is done with the ‘=’ operator, so if testexpr is NULL, it won’t match any of the exprs, not even those that are NULL.

`DECODE` Examples

select name,
  age,
  decode(upper(sex),
         'M', 'Male',
         'F', 'Female',
         'Unknown'),
  religion
from people

See also

CASE, Simple CASE

`IIF()`

Ternary conditional function

Result type

Depends on input

Syntax

IIF (<condition>, ResultT, ResultF)

Table 1. `IIF` Function Parameters
Parameter	Description
condition	A true\|false expression
resultT	The value returned if the condition is true
resultF	The value returned if the condition is false

IIF takes three arguments.If the first evaluates to true, the second argument is returned;otherwise the third is returned.

IIF could be likened to the ternary “<condition> ? resultT : resultF” operator in C-like languages.

Note	`IIF(<condition>, resultT, resultF)` is a shorthand for “`CASE WHEN <condition> THEN resultT ELSE resultF END`”.

`IIF` Examples

select iif( sex = 'M', 'Sir', 'Madam' ) from Customers

`MAXVALUE()`

Returns the maximum value of its arguments

Result type

Varies according to input — result will be of the same data type as the first expression in the list (expr1).

Syntax

MAXVALUE (<expr1> [, ... , <exprN> ])

Table 1. `MAXVALUE` Function Parameters
Parameter	Description
expr1 … exprN	List of expressions of compatible types

Returns the maximum value from a list of numerical, string, or date/time expressions.This function fully supports text BLOBs of any length and character set.

If one or more expressions resolve to NULL, MAXVALUE returns NULL.This behaviour differs from the aggregate function MAX.

`MAXVALUE` Examples

SELECT MAXVALUE(PRICE_1, PRICE_2) AS PRICE
  FROM PRICELIST

See also

[fblangref50-scalarfuncs-minvalue]

`MINVALUE()`

Returns the minimum value of its arguments

Result type

Varies according to input — result will be of the same data type as the first expression in the list (expr1).

Syntax

MINVALUE (<expr1> [, ... , <exprN> ])

Table 1. `MINVALUE` Function Parameters
Parameter	Description
expr1 … exprN	List of expressions of compatible types

Returns the minimum value from a list of numerical, string, or date/time expressions.This function fully supports text BLOBs of any length and character set.

If one or more expressions resolve to NULL, MINVALUE returns NULL.This behaviour differs from the aggregate function MIN.

`MINVALUE` Examples

SELECT MINVALUE(PRICE_1, PRICE_2) AS PRICE
  FROM PRICELIST

See also

[fblangref50-scalarfuncs-maxvalue]

`NULLIF()`

Conditional NULL function

Result type

Depends on input

Syntax

NULLIF (<exp1>, <exp2>)

Table 1. `NULLIF` Function Parameters
Parameter	Description
exp1	An expression
exp2	Another expression of a data type compatible with exp1

NULLIF returns the value of the first argument, unless it is equal to the second.In that case, NULL is returned.

`NULLIF` Example

select avg( nullif(Weight, -1) ) from FatPeople

This will return the average weight of the persons listed in FatPeople, excluding those having a weight of -1, since AVG skips NULL data.Presumably, -1 indicates “weight unknown” in this table.A plain AVG(Weight) would include the -1 weights, thus skewing the result.

EXTRACT()

EXTRACT()

Returned Data Types and Ranges

MILLISECOND

WEEK

FIRST_DAY()

Examples of FIRST_DAY

LAST_DAY()

Examples of LAST_DAY

Type Casting Functions

CAST()

“Shorthand” Syntax

Allowed Type Conversions

Casting Parameters

Casting to a Domain or its Type

Casting to a Column’s Type

Cast Examples

Bitwise Functions

BIN_AND()

BIN_NOT()

BIN_OR()

BIN_SHL()

BIN_SHR()

BIN_XOR()

UUID Functions

CHAR_TO_UUID()

CHAR_TO_UUID Examples

GEN_UUID()

GEN_UUID Example

UUID_TO_CHAR()

UUID_TO_CHAR Examples

Functions for Sequences (Generators)

GEN_ID()

GEN_ID Example

Conditional Functions

COALESCE()

COALESCE Examples

DECODE()

DECODE Examples

IIF()

IIF Examples

MAXVALUE()

MAXVALUE Examples

MINVALUE()

MINVALUE Examples

NULLIF()

NULLIF Example

`EXTRACT()`

`MILLISECOND`

`WEEK`

`FIRST_DAY()`

Examples of `FIRST_DAY`

`LAST_DAY()`

Examples of `LAST_DAY`

`CAST()`

`BIN_AND()`

`BIN_NOT()`

`BIN_OR()`

`BIN_SHL()`

`BIN_SHR()`

`BIN_XOR()`

`CHAR_TO_UUID()`

`CHAR_TO_UUID` Examples

`GEN_UUID()`

`GEN_UUID` Example

`UUID_TO_CHAR()`

`UUID_TO_CHAR` Examples

`GEN_ID()`

`GEN_ID` Example

`COALESCE()`

`COALESCE` Examples

`DECODE()`

`DECODE` Examples

`IIF()`

`IIF` Examples

`MAXVALUE()`

`MAXVALUE` Examples

`MINVALUE()`

`MINVALUE` Examples

`NULLIF()`

`NULLIF` Example