# IP address functions

> 12 IP address functions in NYXDB: names, aliases, signatures and behaviour.

{/* AUTO-GENERATED from the function catalog. DO NOT EDIT — overwritten on every build. */}

12 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

| Function | Summary |
| --- | --- |
| [`ip_cut_ipv6`](#ip_cut_ipv6) | Masks trailing IPv6 or mapped-IPv4 bytes before returning address text. |
| [`ip_ipv4_cidr_to_range`](#ip_ipv4_cidr_to_range) | Finds the first and last IPv4 addresses covered by a prefix length. |
| [`ip_ipv4_num_to_string`](#ip_ipv4_num_to_string) | Formats a 32-bit network address as four dotted decimal octets. |
| [`ip_ipv4_string_to_num`](#ip_ipv4_string_to_num) | Parses dotted IPv4 text into its unsigned network-order integer. |
| [`ip_ipv4_to_ipv6`](#ip_ipv4_to_ipv6) | Embeds a typed IPv4 value in the IPv4-mapped IPv6 address range. |
| [`ip_ipv6_cidr_to_range`](#ip_ipv6_cidr_to_range) | Expands an IPv6 network prefix into inclusive lower and upper addresses. |
| [`ip_ipv6_num_to_string`](#ip_ipv6_num_to_string) | Renders sixteen network-order address bytes in canonical IPv6 notation. |
| [`ip_ipv6_string_to_num`](#ip_ipv6_string_to_num) | Parses compressed colon-separated address notation into a fixed binary representation. |
| [`ip_is_ip_address_in_range`](#ip_is_ip_address_in_range) | Checks membership of an address in a textual IPv4 or IPv6 CIDR network. |
| [`ip_is_ipv4_string`](#ip_is_ipv4_string) | Recognizes strict dotted-decimal address syntax without converting the result. |
| [`ip_is_ipv6_string`](#ip_is_ipv6_string) | Tests whether textual input denotes a valid IPv6 address. |
| [`ip_reverse_dns_query`](#ip_reverse_dns_query) | Builds a PTR lookup name from an address without contacting DNS. |

## ip_cut_ipv6

Masks trailing IPv6 or mapped-IPv4 bytes before returning address text.

```text
ip_cut_ipv6(address:fixed_string(16),ipv6_bytes:uint8,ipv4_bytes:uint8) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/ternary` |
| Returns | `string` |
| Aliases | `cut_ipv6` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Takes sixteen address bytes plus separate suffix-byte counts for ordinary IPv6 and IPv4-mapped input. It zeros the selected trailing bytes before formatting and returns NULL when any argument is NULL. A mask exceeding the relevant address width raises INVALID_ARGUMENT; the operation is pure formatting rather than anonymization with secret state.

**Example**

```sql
ip_cut_ipv6(
  cast(X '00000000000000000000000000000001' AS fixed_string(16)),
  1,
  1
)
-- → '::'
```

## ip_ipv4_cidr_to_range

Finds the first and last IPv4 addresses covered by a prefix length.

```text
ip_ipv4_cidr_to_range(address:ipv4,prefix:uint8) -> tuple(ipv4,ipv4)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `tuple(ipv4,ipv4)` |
| Aliases | `ipv4_cidr_to_range` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Clears or sets the host bits to return an inclusive tuple of native ipv4 bounds. Prefix zero spans the full address space, and prefix thirty-two selects only the supplied address. NULL propagates; prefixes outside zero through thirty-two raise INVALID_ARGUMENT.

**Example**

```sql
ip_ipv4_cidr_to_range(cast('192.0.2.7' AS ipv4), 24)
-- → (192.0.2.0, 192.0.2.255)
```

## ip_ipv4_num_to_string

Formats a 32-bit network address as four dotted decimal octets.

```text
ip_ipv4_num_to_string(address:uint32) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `ipv4_num_to_string`, `IPv4NumToString` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Interprets the uint32 in network-order significance and emits canonical dotted-decimal IPv4 text. No hostname resolution occurs and every uint32 bit pattern is a representable address. NULL returns NULL, while an argument outside the required unsigned width raises TYPE_MISMATCH.

**Example**

```sql
ip_ipv4_num_to_string(cast(3232235777 AS UINT32))
-- → '192.168.1.1'
```

## ip_ipv4_string_to_num

Parses dotted IPv4 text into its unsigned network-order integer.

```text
ip_ipv4_string_to_num(text:string) -> uint32
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `uint32` |
| Aliases | `ipv4_string_to_num`, `IPv4StringToNum` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Requires a strict four-octet address with each decimal component in range, rather than accepting a hostname or abbreviated network syntax. Invalid text raises INVALID_IP_ADDRESS and SQL NULL produces NULL. The uint32 result orders the first displayed octet as the most significant byte.

**Example**

```sql
ip_ipv4_string_to_num('192.168.1.1')
-- → 3232235777
```

## ip_ipv4_to_ipv6

Embeds a typed IPv4 value in the IPv4-mapped IPv6 address range.

```text
ip_ipv4_to_ipv6(address:ipv4) -> ipv6
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `ipv6` |
| Aliases | `ipv4_to_ipv6`, `IPv4ToIPv6` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Constructs the standard mapped prefix followed by the IPv4 address’s thirty-two bits. The result is a native ipv6 value, preserving the source address without a DNS query or textual heuristic. NULL returns NULL and non-ipv4 inputs raise TYPE_MISMATCH until explicitly converted.

**Example**

```sql
ip_ipv4_to_ipv6(cast('192.0.2.1' AS ipv4))
-- → ::ffff:192.0.2.1
```

## ip_ipv6_cidr_to_range

Expands an IPv6 network prefix into inclusive lower and upper addresses.

```text
ip_ipv6_cidr_to_range(address:ipv6,prefix:uint8) -> tuple(ipv6,ipv6)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `tuple(ipv6,ipv6)` |
| Aliases | `ipv6_cidr_to_range` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns two ipv6 values by replacing every bit after the prefix with zero or one. A full-length prefix produces identical endpoints, while length zero covers all 128-bit addresses. NULL arguments yield NULL and a length greater than 128 raises INVALID_ARGUMENT.

**Example**

```sql
ip_ipv6_cidr_to_range(cast('::1' AS ipv6), 128)
-- → (::1, ::1)
```

## ip_ipv6_num_to_string

Renders sixteen network-order address bytes in canonical IPv6 notation.

```text
ip_ipv6_num_to_string(address:fixed_string(16)) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `ipv6_num_to_string`, `IPv6NumToString` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Interprets fixed_string(16) as an IPv6 address and applies canonical compressed text formatting. The function only formats supplied bits and never performs network lookup. NULL propagates; a value with the wrong byte length or logical descriptor raises TYPE_MISMATCH.

**Example**

```sql
ip_ipv6_num_to_string(
  cast(X '00000000000000000000000000000001' AS fixed_string(16))
)
-- → '::1'
```

## ip_ipv6_string_to_num

Parses compressed colon-separated address notation into a fixed binary representation.

```text
ip_ipv6_string_to_num(text:string) -> fixed_string(16)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `fixed_string(16)` |
| Aliases | `ipv6_string_to_num`, `IPv6StringToNum` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Parses an IPv6 address, expands compressed groups and stores its bits in fixed_string(16). Malformed address text raises INVALID_IP_ADDRESS rather than returning zero bytes. SQL NULL remains NULL, and the binary output has no host-dependent endianness or trailing terminator.

**Example**

```sql
hex_encode(ip_ipv6_string_to_num('::1'))
-- → '00000000000000000000000000000001'
```

## ip_is_ip_address_in_range

Checks membership of an address in a textual IPv4 or IPv6 CIDR network.

```text
ip_is_ip_address_in_range(address:string,cidr:string) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `bool` |
| Aliases | `is_ip_address_in_range`, `isIPAddressInRange` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Parses both the address and CIDR, then compares their network bits using the stated prefix length. Incompatible address families do not match; malformed addresses, networks or prefix lengths raise INVALID_IP_ADDRESS. SQL NULL propagates and no stored CIDR type or network request is introduced.

**Example**

```sql
ip_is_ip_address_in_range('192.0.2.9', '192.0.2.0/24')
-- → true
```

## ip_is_ipv4_string

Recognizes strict dotted-decimal address syntax without converting the result.

```text
ip_is_ipv4_string(text:string) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bool` |
| Aliases | `is_ipv4_string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns true only for valid IPv4 text under the parser’s strict octet rules. Malformed input produces false rather than INVALID_IP_ADDRESS, and NULL produces NULL. Hostnames and IPv6 literals are false; a nonstring argument raises TYPE_MISMATCH.

**Example**

```sql
ip_is_ipv4_string('192.0.2.1')
-- → true
```

## ip_is_ipv6_string

Tests whether textual input denotes a valid IPv6 address.

```text
ip_is_ipv6_string(text:string) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `bool` |
| Aliases | `is_ipv6_string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Valid compressed or expanded IPv6 syntax returns true; malformed groups and plain IPv4 notation return false. The predicate does not resolve hostnames and deliberately avoids parse exceptions for invalid text. NULL remains NULL, while incompatible argument types raise TYPE_MISMATCH.

**Example**

```sql
ip_is_ipv6_string('2001:db8::1')
-- → true
```

## ip_reverse_dns_query

Builds a PTR lookup name from an address without contacting DNS.

```text
ip_reverse_dns_query(ipv4) -> string
ip_reverse_dns_query(ipv6) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `reverse_dns_query` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

An IPv4 address becomes reversed decimal octets under in-addr.arpa, while IPv6 becomes reversed hexadecimal nibbles under ip6.arpa. The output is only the query name, so it is deterministic and eligible for stateless continuous evaluation. NULL returns NULL and incompatible source types raise TYPE_MISMATCH.

**Example**

```sql
ip_reverse_dns_query(cast('192.0.2.1' AS ipv4))
-- → '1.2.0.192.in-addr.arpa'
```

---

Source: https://nyxdb.io/docs/functions/ip/