# URL functions

> 26 URL functions in NYXDB: names, aliases, signatures and behaviour.

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

26 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 |
| --- | --- |
| [`url_cut_fragment`](#url_cut_fragment) | Removes the hash delimiter and fragment from a complete URL string. |
| [`url_cut_parameter`](#url_cut_parameter) | Deletes every query field whose raw name exactly matches the supplied key. |
| [`url_cut_query_string`](#url_cut_query_string) | Deletes URL query parameters while keeping any fragment suffix. |
| [`url_cut_query_string_and_fragment`](#url_cut_query_string_and_fragment) | Keeps only a URL’s portion before its query or fragment suffix. |
| [`url_cut_to_first_significant_subdomain`](#url_cut_to_first_significant_subdomain) | Returns the registrable domain and public suffix from a deeper URL host. |
| [`url_cut_www`](#url_cut_www) | Rewrites a URL after dropping a leading www authority label. |
| [`url_decode_component`](#url_decode_component) | Restores percent-escaped URL bytes while preserving literal plus characters. |
| [`url_decode_form_component`](#url_decode_form_component) | Decodes form escapes and translates plus separators back to spaces. |
| [`url_domain`](#url_domain) | Extracts a URL’s host name while excluding scheme, credentials and port. |
| [`url_domain_without_www`](#url_domain_without_www) | Obtains a host name after removing its leading www label. |
| [`url_encode_component`](#url_encode_component) | Escapes a UTF-8 component for placement inside a URL. |
| [`url_encode_form_component`](#url_encode_form_component) | Prepares form text with plus signs for spaces and percent escapes for reserved bytes. |
| [`url_extract_parameter`](#url_extract_parameter) | Returns the first raw query value associated with a requested URL field. |
| [`url_extract_parameter_names`](#url_extract_parameter_names) | Lists query field names in their original order, retaining repetitions. |
| [`url_extract_parameters`](#url_extract_parameters) | Splits the raw query into ordered key-and-value segments. |
| [`url_first_significant_subdomain`](#url_first_significant_subdomain) | Finds the registrable host label immediately before a recognized public suffix. |
| [`url_fragment`](#url_fragment) | Retrieves the text following a URL’s hash delimiter. |
| [`url_hierarchy`](#url_hierarchy) | Builds successive absolute resource prefixes from a URL’s ordered path segments. |
| [`url_path`](#url_path) | Isolates the slash-led resource path without query parameters or fragment text. |
| [`url_path_full`](#url_path_full) | Returns the resource suffix including its path, query and fragment. |
| [`url_path_hierarchy`](#url_path_hierarchy) | Expands a resource path into cumulative prefixes without scheme or authority. |
| [`url_port`](#url_port) | Reads an explicit numeric URL port, with zero or a supplied default when absent. |
| [`url_protocol`](#url_protocol) | Returns the scheme label preceding a URL’s authority or path. |
| [`url_query_string`](#url_query_string) | Extracts raw URL parameter text between the question mark and fragment delimiter. |
| [`url_query_string_and_fragment`](#url_query_string_and_fragment) | Reads a URL’s query suffix together with any following fragment. |
| [`url_top_level_domain`](#url_top_level_domain) | Identifies the final domain label in a URL host. |

## url_cut_fragment

Removes the hash delimiter and fragment from a complete URL string.

```text
url_cut_fragment(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `cut_fragment` |
| 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. |

Preserves the scheme, authority, path and query while cutting at the fragment delimiter. A URL without a fragment is returned unchanged, including an otherwise empty input. NULL returns NULL and nonstring input raises TYPE_MISMATCH; percent-encoded hash bytes are not treated as delimiters.

**Example**

```sql
url_cut_fragment('https://example.com/products?a=1#details')
-- → 'https://example.com/products?a=1'
```

## url_cut_parameter

Deletes every query field whose raw name exactly matches the supplied key.

```text
url_cut_parameter(url:string,name:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `string` |
| Aliases | `cut_url_parameter` |
| 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. |

Removes all occurrences of the named query parameter and repairs the remaining query separators. A missing name leaves the URL unchanged, with path and fragment preserved; comparison does not implicitly decode escapes. NULL arguments yield NULL, and arguments outside the string overload raise TYPE_MISMATCH.

**Example**

```sql
url_cut_parameter('https://example.com/products?a=1&b=2&a=3', 'a')
-- → 'https://example.com/products?b=2'
```

## url_cut_query_string

Deletes URL query parameters while keeping any fragment suffix.

```text
url_cut_query_string(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `cut_query_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. |

Removes the question-mark delimiter and query content, preserving the rest of the URL including its fragment. Input without a query remains unchanged, and NULL remains NULL. No parameter decoding is performed; invalid argument types raise TYPE_MISMATCH rather than triggering a resource request.

**Example**

```sql
url_cut_query_string('https://example.com/products?a=1#details')
-- → 'https://example.com/products#details'
```

## url_cut_query_string_and_fragment

Keeps only a URL’s portion before its query or fragment suffix.

```text
url_cut_query_string_and_fragment(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `cut_query_string_and_fragment` |
| 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. |

Removes query content and fragment content together, including their delimiters. If neither suffix exists, the original string is returned; NULL input yields NULL. Escaped delimiter characters remain part of the retained data, and a nonstring argument raises TYPE_MISMATCH.

**Example**

```sql
url_cut_query_string_and_fragment('https://example.com/products?a=1#details')
-- → 'https://example.com/products'
```

## url_cut_to_first_significant_subdomain

Returns the registrable domain and public suffix from a deeper URL host.

```text
url_cut_to_first_significant_subdomain(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `cut_to_first_significant_subdomain` |
| 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. |

Cuts away labels preceding the significant domain while retaining that label and its recognized public suffix. The suffix table is version-pinned, and a host without a usable domain yields empty text. SQL NULL remains NULL; nonstring input raises TYPE_MISMATCH, with no network lookup involved.

**Example**

```sql
url_cut_to_first_significant_subdomain('https://shop.example.co.uk/products')
-- → 'example.co.uk'
```

## url_cut_www

Rewrites a URL after dropping a leading www authority label.

```text
url_cut_www(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `cut_www` |
| 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. |

Removes the initial www label from the host while preserving scheme, port, path, query and fragment. Hosts without that label are left as supplied, and NULL remains NULL. The operation is a pure string transformation; nonstring values raise TYPE_MISMATCH.

**Example**

```sql
url_cut_www('https://www.example.com/products')
-- → 'https://example.com/products'
```

## url_decode_component

Restores percent-escaped URL bytes while preserving literal plus characters.

```text
url_decode_component(text:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `decode_url_component`, `decodeURLComponent` |
| 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. |

Decodes percent triplets within one component and returns the resulting UTF-8 text. Unlike form decoding, a plus sign is retained as a plus. NULL produces NULL, and malformed escapes or invalid decoded text raise INVALID_ENCODING instead of being silently replaced.

**Example**

```sql
url_decode_component('red%20blue+')
-- → 'red blue+'
```

## url_decode_form_component

Decodes form escapes and translates plus separators back to spaces.

```text
url_decode_form_component(text:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `decode_url_form_component` |
| 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. |

First interprets literal plus characters as spaces and decodes valid percent triplets into text bytes. An escaped %2B remains a literal plus, preserving the distinction from an unescaped separator. NULL propagates; malformed escapes or invalid UTF-8 output raise INVALID_ENCODING.

**Example**

```sql
url_decode_form_component('red+blue%2B')
-- → 'red blue+'
```

## url_domain

Extracts a URL’s host name while excluding scheme, credentials and port.

```text
url_domain(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `domain` |
| 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 the textual authority host without performing DNS resolution or percent-decoding unrelated components. A missing host produces an empty string and a NULL URL produces NULL. Input outside the string overload raises TYPE_MISMATCH; an explicit port is not part of the returned domain.

**Example**

```sql
url_domain('https://shop.example.com:8443/products')
-- → 'shop.example.com'
```

## url_domain_without_www

Obtains a host name after removing its leading www label.

```text
url_domain_without_www(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `domain_without_www`, `domainWithoutWWW` |
| 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. |

Extracts the authority host and removes a leading www label when present, leaving other subdomains intact. A URL without a host returns empty text; SQL NULL remains NULL. This is lexical decomposition rather than a DNS lookup, and nonstring input raises TYPE_MISMATCH.

**Example**

```sql
url_domain_without_www('https://www.example.com/products')
-- → 'example.com'
```

## url_encode_component

Escapes a UTF-8 component for placement inside a URL.

```text
url_encode_component(text:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `encode_url_component`, `encodeURLComponent` |
| 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. |

Percent-encodes bytes requiring escaping while leaving unreserved characters literal. A space becomes %20 and a literal plus is escaped rather than treated as a form separator. NULL returns NULL, incompatible input types raise TYPE_MISMATCH and expansion beyond the value budget raises RESOURCE_LIMIT.

**Example**

```sql
url_encode_component('red blue')
-- → 'red%20blue'
```

## url_encode_form_component

Prepares form text with plus signs for spaces and percent escapes for reserved bytes.

```text
url_encode_form_component(text:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `encode_url_form_component` |
| 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. |

Encodes a single application-form component from its UTF-8 bytes. Spaces become plus signs, while literal plus characters become %2B so that decoding is unambiguous. NULL remains NULL; TYPE_MISMATCH rejects incompatible values and RESOURCE_LIMIT bounds the expanded string.

**Example**

```sql
url_encode_form_component('red blue+')
-- → 'red+blue%2B'
```

## url_extract_parameter

Returns the first raw query value associated with a requested URL field.

```text
url_extract_parameter(url:string,name:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `string` |
| Aliases | `extract_url_parameter`, `extractURLParameter` |
| 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. |

Scans parameters in source order and chooses the first exactly matching name. An absent name or an explicitly empty value yields an empty string; decoding percent escapes requires a separate operation. SQL NULL propagates and nonstring arguments raise TYPE_MISMATCH.

**Example**

```sql
url_extract_parameter('https://example.com/products?id=7&id=9', 'id')
-- → '7'
```

## url_extract_parameter_names

Lists query field names in their original order, retaining repetitions.

```text
url_extract_parameter_names(url:string) -> array(string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `array(string)` |
| Aliases | `extract_url_parameter_names` |
| 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 an array of raw names from the query component, excluding the fragment. Names are not deduplicated or percent-decoded, and a URL without parameters returns an empty array. NULL gives NULL; incompatible arguments raise TYPE_MISMATCH and excessive expansion raises RESOURCE_LIMIT.

**Example**

```sql
url_extract_parameter_names('https://example.com/products?a=1&b=2&a=3')
-- → ['a', 'b', 'a']
```

## url_extract_parameters

Splits the raw query into ordered key-and-value segments.

```text
url_extract_parameters(url:string) -> array(string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `array(string)` |
| Aliases | `extract_url_parameters` |
| 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. |

Produces one array element per query segment, preserving the equals sign and any percent escapes. The fragment is excluded, duplicate fields remain distinct, and an absent query produces an empty array. NULL propagates; TYPE_MISMATCH rejects nonstrings and RESOURCE_LIMIT bounds the materialized output.

**Example**

```sql
url_extract_parameters('https://example.com/products?a=1&b=2#details')
-- → ['a=1', 'b=2']
```

## url_first_significant_subdomain

Finds the registrable host label immediately before a recognized public suffix.

```text
url_first_significant_subdomain(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `first_significant_subdomain` |
| 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. |

Uses the version-pinned public-suffix rules to select the first significant domain label. Additional host labels to its left are ignored, and a missing eligible domain produces empty text. NULL propagates and nonstring input raises TYPE_MISMATCH; results do not depend on live DNS or network-fetched suffix data.

**Example**

```sql
url_first_significant_subdomain('https://shop.example.co.uk/products')
-- → 'example'
```

## url_fragment

Retrieves the text following a URL’s hash delimiter.

```text
url_fragment(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `fragment` |
| 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 fragment content without the leading hash character and preserves any percent escapes. When the fragment is absent or empty, the result is an empty string rather than NULL. SQL NULL propagates; wrong argument types raise TYPE_MISMATCH, and no client-side navigation occurs.

**Example**

```sql
url_fragment('https://example.com/products#details')
-- → 'details'
```

## url_hierarchy

Builds successive absolute resource prefixes from a URL’s ordered path segments.

```text
url_hierarchy(url:string) -> array(string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `array(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 the authority-root URL followed by progressively longer path prefixes in source order. It does not fetch resources or resolve a hierarchy through the network, and NULL input returns NULL. Query and fragment are not path levels; incompatible input raises TYPE_MISMATCH and oversized output raises RESOURCE_LIMIT.

**Example**

```sql
url_hierarchy('https://example.com/products/7')
-- → ['https://example.com/', 'https://example.com/products/',
--   'https://example.com/products/7']
```

## url_path

Isolates the slash-led resource path without query parameters or fragment text.

```text
url_path(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `path` |
| 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 the path component exactly as represented, retaining percent escapes for explicit later decoding. Missing path content produces an empty string and SQL NULL produces NULL. The function does not normalize dot segments or request the resource; nonstring input raises TYPE_MISMATCH.

**Example**

```sql
url_path('https://example.com/products/7?view=short#details')
-- → '/products/7'
```

## url_path_full

Returns the resource suffix including its path, query and fragment.

```text
url_path_full(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `path_full` |
| 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. |

Removes the scheme and authority while preserving the remaining path-oriented URL suffix with its delimiters. If no such suffix exists the result is empty; NULL remains NULL. It performs no percent decoding or navigation, and a nonstring argument raises TYPE_MISMATCH.

**Example**

```sql
url_path_full('https://example.com/products?id=7#details')
-- → '/products?id=7#details'
```

## url_path_hierarchy

Expands a resource path into cumulative prefixes without scheme or authority.

```text
url_path_hierarchy(url:string) -> array(string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `array(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. |

Lists successive slash-led path levels while excluding URL authority, query and fragment components. The output preserves source order and percent escapes, and a missing path produces an empty array. NULL returns NULL; TYPE_MISMATCH rejects other logical types and RESOURCE_LIMIT bounds prefix expansion.

**Example**

```sql
url_path_hierarchy('https://example.com/products/7')
-- → ['/products/', '/products/7']
```

## url_port

Reads an explicit numeric URL port, with zero or a supplied default when absent.

```text
url_port(url:string) -> uint16
url_port(url:string,default_port:uint16) -> uint16
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary` |
| Returns | `uint16` |
| Aliases | `port` |
| 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 the authority port as uint16 and uses the optional default only when no port is specified. Without a default, an absent port gives zero rather than an inferred protocol port. NULL propagates and malformed or out-of-range explicit port text raises INVALID_ARGUMENT.

**Example**

```sql
url_port('https://example.com/products', 443)
-- → 443
```

## url_protocol

Returns the scheme label preceding a URL’s authority or path.

```text
url_protocol(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `protocol` |
| 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. |

Extracts the scheme without its colon or slash delimiters. A URL with no scheme yields an empty string, while a NULL argument yields NULL. It does not infer https from a hostname or contact the resource; incompatible argument types raise TYPE_MISMATCH.

**Example**

```sql
url_protocol('https://example.com/products')
-- → 'https'
```

## url_query_string

Extracts raw URL parameter text between the question mark and fragment delimiter.

```text
url_query_string(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `query_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 the complete query component without its leading question mark or a following fragment. Names and values remain escaped and are not interpreted as a map. An absent query yields empty text, SQL NULL yields NULL, and incompatible argument types raise TYPE_MISMATCH.

**Example**

```sql
url_query_string('https://example.com/products?a=1&b=2#details')
-- → 'a=1&b=2'
```

## url_query_string_and_fragment

Reads a URL’s query suffix together with any following fragment.

```text
url_query_string_and_fragment(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `query_string_and_fragment` |
| 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. |

Starts after the query delimiter and preserves the subsequent hash and fragment when present. With no query component the query-oriented extraction returns empty text; a NULL input stays NULL. Percent escapes are left untouched, and nonstring arguments raise TYPE_MISMATCH.

**Example**

```sql
url_query_string_and_fragment('https://example.com/products?a=1#details')
-- → 'a=1#details'
```

## url_top_level_domain

Identifies the final domain label in a URL host.

```text
url_top_level_domain(url:string) -> string
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `string` |
| Aliases | `top_level_domain`, `topLevelDomain` |
| 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. |

Extracts the rightmost host label as the top-level domain without including its preceding dot. A missing domain yields empty text, and NULL produces NULL. It does not return an entire multi-label public suffix or perform DNS validation; incompatible input types raise TYPE_MISMATCH.

**Example**

```sql
url_top_level_domain('https://shop.example.com/products')
-- → 'com'
```

---

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