Firebird Null Guide: NULL behaviour and pitfalls in Firebird SQL

In Firebird 1.5 and earlier, you can only use the literal word “NULL” in a few situations, namely the ones described in the previous paragraphs plus a few others such as “cast( NULL as <datatype> )” and “select NULL from MyTable”.

In all other circumstances, Firebird will complain that NULL is an unknown token. If you really must use NULL in such a context, you have to resort to tricks like “cast( NULL as int )”, or using a field or variable that you know is NULL, etc.

Firebird 2 allows the use of NULL literals in every context where a normal value can also be entered. You can. for example, include NULL in an IN() list, write expressions like “if ( MyField = NULL ) then…​”, and so on. However, as a general rule you should not make use of these new possibilities! In almost every thinkable situation, such use of NULL literals is a sign of poor SQL design and will lead to NULL results where you meant to get true or false. In that sense the earlier, more restrictive policy was safer, although you could always bypass it with casts etc. — but at least you had to take deliberate steps to bypass it.

Firebird 3.0 introduced the BOOLEAN datatype, and specifically for Booleans (and only for Booleans), the SQL standard — and thus Firebird — defines UNKNOWN as an alias for NULL.

Where it comes to Booleans, you can use either UNKNOWN and NULL; they mean the same thing.

If the list is empty (this is only possible with a subquery), IN always returns false and NOT IN always returns true, even if the test expression is NULL. This makes sense: even if a value is unknown, it is certain not to occur in an empty list.

If the list is not empty and the test expression — called “A” in the examples below — is NULL, the following predicates will always return NULL, regardless of the expressions in the list:

The first result can be understood by writing out the entire expression as a disjunction (OR-chain) of equality tests:

which, if A is NULL, boils down to

which is NULL.

The nullness of the second predicate follows from the fact that “not (NULL)” equals NULL.

If A has a proper value, but the list contains one or more NULL expressions, things become a little more complicated:

Needless to say, if neither A nor any list expression is NULL, the result is always as expected and can only be true or false.

The table below shows all the possible results for IN and NOT IN. To use it properly, start with the first question in the left column. If the answer is No, move on to the next line. As soon as an answer is Yes, read the results from the second and third columns and you’re done.

In many contexts (e.g. within IF and WHERE clauses), a NULL result behalves like false in that the condition is not satisfied when the test expression is NULL. On the one hand this is convenient for cases where you might expect false but NULL is returned: you simply won’t notice the difference. On the other hand, this may also lead you to expect true when the expression is inverted (using NOT) and this is where you’ll run into trouble. In that sense, the most “dangerous” case in the above table is when you use an expression of the type “A NOT IN (<list>)”, with A indeed not present in the list (so you’d expect a clear true result), but the list happens to contain one or more NULLs.

The IN() predicate is often used in CHECK constraints. In that context, NULL expressions have a surprisingly different effect in Firebird versions 2.0 and higher. This will be discussed in the section CHECK constraints.

If the subselect returns an empty set, ALL returns true and ANY|SOME return false, even if the left-hand side expression is NULL. This follows from the definitions and the rules of formal logic. (Math-heads will already have noticed that ALL is equivalent to the universal (“A”) quantifier and ANY|SOME to the existential (“E”) quantifier.)

For non-empty sets, you can write out “A <op> {ANY|SOME} (<subselect>)” as

with <op> the operator used and E1, E2 etc. the items returned by the subquery.

Likewise, “A <op> ALL (<subselect>)” is the same as

This should look familiar. The first writeout is equal to that of the IN predicate, except that the operator may now be something other than ‘=’. The second is different but has the same general form. We can now work out how nullness of A and/or nullness of subselect results affect the outcome of ANY|SOME and ALL. This is done in the same way as earlier with IN, so instead of including all the steps here we will just present the result tables. Again, read the questions in the left column from top to bottom. As soon as you answer a question with “Yes”, read the result from the second column and you’re done.

If you think these results look a lot like what we saw with IN(), you’re right: with the ‘=’ operator, ANY is the same as IN. In the same way, “<> ALL” is equivalent to NOT IN.

EXISTS tells you whether a subquery returns at least one row of data. Suppose you want a list of farmers who are also landowners. You could get one like this:

This query returns the names of all farmers who also figure in the Landowners table. The EXISTS predicate returns true if the result set of the subselect contains at least one row. If it is empty, EXISTS returns false. EXISTS never returns NULL, because a result set always either has rows, or hasn’t. Of course the subselect’s search condition may evolve to NULL for certain rows, but that doesn’t cause any uncertainty: such a row won’t be included in the subresult set.

NOT EXISTS always returns the opposite of EXISTS: false or true, never NULL. NOT EXISTS returns false immediately if it gets a true result on the subquery’s search condition. Before returning true it must step through the entire set.

SINGULAR is an InterBase/Firebird extension to the SQL standard. It is often described as returning true if exactly one row in the subquery meets the search condition. By analogy with EXISTS this would make you expect that SINGULAR too will only ever return true or false. After all, a result set has either exactly 1 row or a different number of rows. Unfortunately, all versions of Firebird up to and including 2.0 have a bug that causes NULL results in a number of cases. The behaviour is pretty inconsistent, but at the same time fully reproducible. For instance, on a column A containing (1, NULL, 1), a SINGULAR test with subselect “A=1” returns NULL, but the same test on a column with (1, 1, NULL) returns false. Notice that only the insertion order is different here!

To make matters worse, all versions prior to 2.0 sometimes return NULL for NOT SINGULAR where false or true is returned for SINGULAR. In 2.0, this at least doesn’t happen anymore: it’s either false vs. true or twice NULL.

The code has been fixed for Firebird 2.1; from that version onward SINGULAR will return:

Whether the other rows yield false, NULL or a combination thereof, is irrelevant.

NOT SINGULAR will always return the opposite of SINGULAR (as is already the case in 2.0).

In the meantime, if there’s any chance that the search condition may evolve to NULL for one or more rows, you should always add an IS NOT NULL condition to your [NOT] SINGULAR clauses, e.g. like this:

A GROUP BY clause can be used to report the frequencies with which values occur in a table. In that case you use the same field name several times in the query statement. Let’s say you have a table TT with a column A whose contents are { 3, 8, NULL, 6, 8, -1, NULL, 3, 1 }. To get a frequencies report, you could use:

which would give you this result:

Oops — something went wrong with the NULL count, but what? Remember that COUNT(FieldName) skips all NULL fields, so with COUNT(A) the count of the <null> group can only ever be 0. Reformulate your query like this:

and the correct value will be returned (in casu 2).

In Firebird 1.0, unique keys are subject to the same restrictions as primary keys: the column(s) involved must be defined as NOT NULL. For unique indices, this is not necessary. However, when a unique index is created the table may not contain any NULLs or duplicate values, or the creation will fail. Once the index is in place, insertion of NULLs or duplicate values is no longer possible.

In Firebird 1.5 and higher, unique keys and unique indices allow NULLs, and what’s more: they even allow multiple NULLs. With a single-column key or index, you can insert as many NULLs as you want in that column, but you can insert each non-NULL value only once.

If the key or index is defined on multiple columns in Firebird 1.5 and higher:

If you are using an existing database with one or more of the functions listed above under Firebird 2.0 or higher, and you want to benefit from the improved NULL handling, run the script ib_udf_upgrade.sql against your database. It is located in the Firebird misc\upgrade\ib_udf directory.

The COALESCE function in Firebird 1.5 and higher can convert NULL to most anything else. This enables you to perform an on-the-fly conversion and use the result in your further processing, without the need for “if (MyExpression is null) then” or similar constructions. The function signature is:

COALESCE returns the value of the first non-NULL expression in the argument list. If all the expressions are NULL, it returns NULL.

This is how you would use COALESCE to construct a person’s full name from the first, middle and last names, assuming that some middle name fields may be NULL:

Or, to create an as-informal-as-possible name from a table that also includes nicknames, and assuming that both nickname and first name may be NULL:

COALESCE will only help you out in situations where NULL can be treated in the same way as some allowed value for the datatype. If NULL needs special handling, different from any other value, your only option is to use an IF or CASE construct after all.

Firebird 1.0 doesn’t have COALESCE. However, you can use four UDFs that provide a good part of its functionality. These UDFs reside in the fbudf lib and they are:

The *NVL functions take exactly two arguments. Like COALESCE, they return the first argument if it’s not NULL; otherwise, they return the second. Please note that the Firebird 1.0 fbudf lib — and therefore, the *NVL function set — is only available for Windows.

The NULLIF internal function takes two arguments. If their values are equal, the function returns NULL. Otherwise, it returns the value of the first argument.

A typical use is e.g.

which will give you the average weight of the FatPeople population, without counting those with weight -1. (Remember that aggregate functions like AVG exclude all NULL fields from the computation.)

Elaborating on this example, suppose that until now you have used the value -1 to indicate “weight unknown” because you weren’t comfortable with NULLs. After reading this guide, you may feel brave enough to give the command:

Now unknown weights will really be unknown.

Firebird 1.0 doesn’t have the NULLIF internal function. Instead, it has four user-defined functions in the fbudf lib that serve the same purpose:

Please note that the Firebird 1.0 fbudf lib — and therefore, the *nullif function set — is only available for Windows.

This is by far the preferred method in general, but it causes some special problems if used on a populated table, as you will see in a moment. First, add the field with the following statement:

Or, if you want to name the constraint explicitly (this makes it easier if you ever want to drop it later):

The behaviour depends on the Firebird version.

In Firebird 2.5 and earlier, despite the NOT NULL constraint, the new ID fields that have been added to the existing rows will all be NULL. In this special case, Firebird allows invalid data to be present in a column. It will even write the NULLs to a backup without complaining, but it will refuse to restore them, precisely because of the constraint violation.

In Firebird 3.0 and higher, adding a NOT NULL column without a default to a table with existing rows will result in error “Cannot make field <field-name> of table <table-name> NOT NULL because there are NULLs present”.

Using a CHECK constraint is another way to disallow NULL entries in a column:

If you do it this way, a subsequent SELECT will return:

Well, at least now you can see that the fields are NULL! Firebird does not enforce CHECK constraints on existing rows when you add new fields. The same is true if you add checks to existing fields with ADD CONSTRAINT or ADD CHECK.

This time, Firebird not only tolerates the presence and the backing up of the NULL entries, but it will also restore them. Firebird’s gbak tool does restore CHECK constraints, but doesn’t apply them to the existing data in the backup.

This restorability of your NULL data despite the presence of the CHECK constraint is consistent with the fact that Firebird allows them to be present in the first place, and to be backed up as well. But from a pragmatical point of view, there’s a downside: you can now go through cycle after cycle of backup and restore, and your “illegal” data will survive without you even receiving a warning. So again: make sure that your existing rows obey the new rule immediately after adding the constrained column. The “default” trick won’t work here; you’ll just have to remember to set the right value(s) yourself. If you forget it now, chances are that your outlawed NULLs will survive for a long time, as there won’t be any wake-up calls later on.

Instead of specifying data types and constraints directly, you can also use domains, e.g. like this:

Or like this:

For the presence of NULLs in the added columns, returning of false 0's, effects of default values etc., it makes no difference at all whether you take the domain route or the direct approach. The only difference is that domain-based constraints can’t be removed at the column level. So if you ever want to drop the constraint later, you must either switch the column to another domain or built-in type again, or remove the constraint from the entire domain. The latter operation is described in the section Changing the nullability of a domain.

In Firebird 3.0 and higher, you can make an existing column NOT NULL using:

In Firebird 2.5 and older, you cannot add NOT NULL to an existing column, but there’s a simple workaround. Suppose the current type is int, then this:

will change the column type to “int not null”. This trick also works in Firebird 3.0 and higher.

In Firebird 2.5 and older, uf the table already had records, any NULLs in the column will remain NULL, and again most Firebird clients will report them as 0 to the user. The situation is almost exactly the same as when you add a NOT NULL column (see Adding a NOT NULL field). The only difference is that if you give the domain (and therefore the column) a default value, this time you can’t be sure that it will be applied to the existing NULL entries. Tests show that sometimes the default is applied to all NULLs, sometimes to none, and in a few cases to some of the existing entries but not to others! Bottom line: if you change a column’s type and the new type includes a default, double-check the existing entries — especially if they “seem to be” 0 or zero-equivalents.

In Firebird 3.0 and higher, attempts to mark a column with NULL values as NOT NULL will fail with error “Cannot make field <field-name> of table <table-name> NOT NULL because there are NULLs present”.

To add a CHECK constraint to a column, use one of the following syntaxes:

The second form is preferred because it gives you an easy handle to drop the check, but the constraints themselves function exactly the same. As you may have expected, existing NULLs in the column will remain, can be backed up and restored, etc. etc. — see Adding a CHECKed column.

In Firebird 3.0 and higher, you can drop a NOT NULL constraint from a table using:

If the ID column is based on a domain which also has a NOT NULL constraint, the column will still be constrained. You will need to drop the NOT NULL constraint from the domain as well, or replace the domain with a nullable domain, to make the column really nullable, see the next section.

For Firebird 2.5 and earlier, dropping the NOT NULL constraint is more involved.

If you gave the NOT NULL constraint a name when you created it, you can simply drop it:

If you forgot the name, you can retrieve it with isql’s `SHOW TABLE command (i.c. SHOW TABLE ADVENTURES); other clients may have their own provisions to let you find or browse constraint names.

If you didn’t name the constraint explicitly, Firebird has created a name for it, but SHOW TABLE won’t display it. You have to use this piece of SQL to dig it up:

Make sure to uppercase the names of your table and field if they were defined case-insensitively (that is, as a regular identifier). Otherwise, match the case exactly but don’t enclose the names in double-quotes like you would do in a regular query. Also don’t include the angle brackets (<>). Once you have the constraint name, you can drop it just like in the previous example.

If you used a CHECK constraint to make the column non-nullable, you can simply drop it again:

If you haven’t named the constraint yourself but added the CHECK directly to the column or table, you must first find out its name before you can drop it. This can be done with the isql “SHOW TABLE” command (in this case: SHOW TABLE STK). Unlike NOT NULL constraints, CHECKs will also be shown if they were created without a user-defined name.

In Firebird 2.0 and higher, you test for null-encompassing equality with DISTINCT. This has already been discussed, but here’s a quick recap. Two expressions are considered:

[NOT] DISTINCT always returns true or false, never NULL or something else. Examples:

Skip the next section if you’re not interested in the pre-Firebird-2 stuff.

Pre-2.0 versions of Firebird don’t support this use of DISTINCT. Consequently, the tests are a little more complicated and there are some pitfalls to avoid.

The correct equality test for pre-2.0 Firebird versions is:

or, if you want to make the precedence of the operations explicit:

A word of warning though: if exactly one of A and B is NULL, the test expression becomes NULL, not false! This is OK in an if statement, and we can even add an else clause which will be executed if A and B are not equal (including when one is NULL and the other isn’t):

But don’t get the bright idea of inverting the expression and using it as an inequality test:

The above code will work correctly if A and B are both NULL or both non-NULL. But it will fail to execute the then clause if exactly one of them is NULL.

If you only want something to be done if A and B are different, either use one of the correct expressions shown above and put a dummy statement in the then clause (starting at 1.5, an empty begin …​ end block is also allowed), or use this longer test expression:

Remember, all this is only necessary in pre-2.0 Firebird versions. From version 2 onward, the inequality test is simply “if (A is distinct from B)”.

Please keep in mind that with Firebird 1.5 and earlier:

In an IF or WHERE context, these NULL results act as false — which is fine for our purposes. But remember that an inversion with NOT() will also return NULL — not “true”. Also, if you use the 1.5-and-earlier tests within CHECK constraints in Firebird 2.0 or higher, be sure to read the section CHECK constraints, if you haven’t done so already.

EXECUTE STATEMENT with a NULL argument crashed Firebird 1.5 and 1.5.1 servers. Fixed in 1.5.2.

In 1.0.0, EXTRACT from a NULL date would crash the server. Fixed in 1.0.2.

FIRST and SKIP crash a Firebird 1.5 or lower server if given a NULL argument. Fixed in 2.0.

Using LIKE with a NULL escape character would crash the server. Fixed in 1.5.1.

NULLs can exist in NOT NULL columns in the following situations, in Firebird 2.5 and earlier:

Firebird allows these NULLs to stay, also backs them up, but refuses to restore them with gbak. See Adding a NOT NULL field and Making an existing column NOT NULL.

If a NOT NULL column contains NULLs (see previous bug), the server will still describe it as non-nullable to the client. Since most clients don’t question this assurance from the server, they will present these NULLs as 0 (or equivalent) to the user. See False reporting of NULLs as zeroes.

The following bug appeared in Firebird 1.5: if you had a table with some rows, and you added a NOT NULL column (which automatically creates NULL entries in the existing rows — see above), you could make that column the primary key even though it had NULL entries. In 1.0 this didn’t work because of the stricter rules for UNIQUE indices. Fixed in 2.0.

The engine describes SUBSTRING result columns as non-nullable in the following two cases:

This is incorrect because even with a known string, substrings may be NULL, namely if the one of the other arguments is NULL. In versions 1.* this bug didn’t bite: the FROM and FOR args had to be literal values, so they could never be NULL. But as from Firebird 2.0, any expression that resolves to the required data type is allowed. And although the engine correctly returns NULL whenever any argument is NULL, it describes the result column as non-nullable, so most clients show the result as an empty string.

This bug seems to be fixed in 2.1.

Gbak -n[o_validity] restored NOT NULL constraints in early Firebird versions. Fixed in 1.5.1.

Let A be the expression on the left-hand side and S the result set of the subselect. In versions prior to 2.0, “IN”, “= ANY” and “= SOME” return false instead of NULL if an index is active on the subselect column and:

See the warnings in the IN and ANY sections. Workaround: use “<> ALL” instead. Fixed in 2.0.

With every operator except ‘<>’, ALL may return wrong results if an index is active on the subselect column. This can happen with our without NULLs involved. See the ALL bug warning. Fixed in 2.0.

Firebird 2.0 has the following bug: if a SELECT DISTINCT is combined with an [ASC] NULLS LAST or DESC NULLS FIRST ordering, and the ordering field(s) form(s) the beginning (but not the whole) of the select list, every field in the ORDER BY clause that is followed by a field with a different (or no) ordering gets the NULLs placed at the default relative location, ignoring the NULLS XXX directive. Fixed in 2.0.1 and 2.1.

This should definitely be considered a bug. If an angle is unknown, don’t tell me that its cosine is 1! Although the history of these functions is known, and we can understand why they behave like they do (see User-Defined Functions (UDFs)), it’s still wrong. Incorrect results are returned and this should not happen. Most of the math functions in ib_udf, as well as some others, have this bug.

This is the complement of the previous bug. The LPAD UDF for instance returns NULL if you want to pad an empty string with 10 dots. This function and others are fixed in 2.0, with the annotation that you must explicitly declare them with the NULL keyword, or they’ll show the old — buggy — behaviour. LTRIM and RTRIM trim empty strings to NULL in Firebird 1.0. This is fixed in 1.5 at the expense of returning '' when trimming a NULL string, and only fully fixed in 2.0 (if declared with the NULL keyword).

NOT SINGULAR sometimes returns NULL where SINGULAR returns true or false. Fixed in 2.0.

SINGULAR may wrongly return NULL, in an inconsistent but reproducible manner. Fixed in 2.1.

See the section on SINGULAR.