# None and Null

None means a missing field; null means an empty stored value - how SurrealDB distinguishes them in SurrealQL.

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.

```surql
CREATE person:two;
CREATE person:one SET children = [person:two];
UPDATE person:one SET children = NONE;
SELECT * FROM person;
```

```surql title="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`.

```surql
CREATE person SET children = null;
```

```surql title="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 deserialise SurrealQL output into a type in another programming language that requires a field name to be present.

## NONE as a datatype

_(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.

```surql
DEFINE FUNCTION fn::do_stuff() -> NONE {
  // Code that should return nothing
};

DEFINE FIELD middle_name
  ON TABLE user TYPE string | NONE; // Equivalent to option<string>

DEFINE FIELD value ON temperature TYPE float | decimal | NONE; // Equivalent to option<float|decimal>
```