None and null
SurrealDB uses two types called None and Null to represent two different ways in which data may not exist. While these may appear similar, they have different meanings and are used in different contexts.
None values
None is used to denote that “something does not exist”, for example, a field which is not present on a record. Because of this, values of None can not be stored within records, meaning uses of None are typically limited to SurrealQL statements where it is used to denote a value or response that does not exist.
Example
Setting a record field to None is analogous to using UNSET to remove the field entirely. While inside the query it may appear that None is being written to the children field, what is actually happening is that the children field is being removed from the record.
CREATE person:two;
CREATE person:one SET children = [person:two];
UPDATE person:one SET children = NONE;
SELECT * FROM person;
Output
[
{ id: person:one },
{ id: person:two }
]
Null values
Null values are used to denote that “something exists, but has no value”. This is useful when a field is present on a record, but the value of that field is unknown or not applicable. Unlike None, Null is written into records and can be stored as a value.
Example
Setting a record field to Null will create the field on the record, but denotes that the field is considered empty. In this example, the children field is present on the record, but the value of that field is null.
CREATE person SET children = null;
Output
[
{
children: NULL,
id: person:dgwjn0ldg8ep3e8y39jw
}
]
When to use None or Null
How you use None or Null is largely dependent on the context in which you are working.
If you are writing SurrealQL and need to denote something that does not exist, such as the absence of a field, use None.
If you are working with data and need to represent a value which is empty, use Null. This is particularly useful when needing to deserialize SurrealQL output into a type in another programming language that requires a field name to be present.
NONE as a datatype
Available since: v3.0.0
Since SurrealDB 3.0, NONE has been usable as a datatype of its own. This allows syntax like the following to be used without returning a parsing error.
DEFINE FUNCTION fn::do_stuff() -> NONE {
};
DEFINE FIELD middle_name ON TABLE user TYPE string | NONE;
DEFINE FIELD value ON temperature TYPE float | decimal | NONE;
