> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NVL

> Returns the first value when it is not NULL, otherwise the replacement value.

<div className="e6-meta"><span className="e6-eyebrow e6-eyebrow--quiet">Scalar function</span></div>

**Aliases:** [`ifnull`](/query/sql/functions/conditional/ifnull)

Returns replacement when value is NULL; returns NULL when both values are NULL.

## Syntax

### Scalar

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
nvl(value, replacement)
```

* All result alternatives must have compatible types. Matching types are preserved; mixed types may be converted to a common type. Use explicit casts to choose the result type.

## Arguments

| Name | Type | Required | Description |
| - | - | - | - |
| value | BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE, DECIMAL(p, s), STRING, BINARY, DATE, TIME, TIMESTAMP, ARRAY, MAP or STRUCT | Yes | Value to inspect. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |
| replacement | BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE, DECIMAL(p, s), STRING, BINARY, DATE, TIME, TIMESTAMP, ARRAY, MAP or STRUCT | Yes | Value to use when value is NULL. Must convert to the same SQL type as the other arguments in this comparison or result branch. Use explicit CAST when mixing types. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |

## Returns

* Type: Common SQL type after conversion of value and replacement
* NULL behavior: Returns replacement when value is NULL; returns NULL when both values are NULL.

## Properties

| Property | Value |
| - | - |
| Deterministic | Yes |
| Supports window usage | No |
| Exact result | Partial (Selection is exact; the selected value may be cast to a common type.) |

## Usage notes

* IFNULL requires compatible same-type arguments. Use explicit casts when the two arguments have different types.
* INTEGER and INT mean the same type; STRING means VARCHAR text. NULL can be used with a supported type. Cast NULL explicitly when its type would otherwise be unclear.
* Query tools may report a DECIMAL result as DOUBLE or a TIME result as INTEGER. The returned value still keeps its decimal precision and scale, or its time type. A reported type does not convert the value.
* Deterministic: The same inputs and settings produce the same result.

## Examples

### Typical behavior

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT nvl(CAST(NULL AS INT), 7) AS "value", nvl(3, 7) AS present;
```

| value | present |
| - | - |
| 7 | 3 |

### Supply a string default

In the result table, `''` denotes an empty string.

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT nvl(CAST(NULL AS VARCHAR), 'unknown') AS missing, nvl('', 'unknown') AS empty_string;
```

| missing | empty\_string |
| - | - |
| unknown | `''` |

## Limitations

* The two arguments must admit a common type.

## Related functions

* [coalesce](/query/sql/functions/conditional/coalesce)
* [nvl2](/query/sql/functions/conditional/nvl2)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.