Search Shortcut cmd + k | ctrl + k
urlpattern
Downloads 1.1kthis week
GitHub stars 9
Extension descriptor (YAML)

WHATWG URLPattern API for matching and extracting components from URLs using pattern syntax

Maintainer(s): teaguesterling

Installing and Loading 

INSTALL urlpattern FROM community;
LOAD urlpattern;

Example 

-- Test if a URL matches a pattern
SELECT urlpattern_test('https://example.com/users/:id', 'https://example.com/users/123');
-- true

-- Extract a named group from a URL
SELECT urlpattern_extract('https://example.com/users/:id', 'https://example.com/users/123', 'id');
-- '123'

-- Get full match results with all components
SELECT urlpattern_exec('/posts/:slug', '/posts/hello-world');
-- {matched: true, pathname: '/posts/hello-world', groups: {slug: 'hello-world'}, ...}

-- Use the URLPATTERN type for validated patterns
SELECT urlpattern_test(urlpattern('/api/:version/*'), '/api/v2/users/list');
-- true

About urlpattern

The URLPattern extension implements the WHATWG URLPattern API for DuckDB, enabling powerful URL matching, extraction, parsing, and construction.

Features

  • Custom URLPATTERN type with validation and implicit casting from VARCHAR
  • Pattern matching with named groups (:name), wildcards (*), and regex groups
  • URL parsing into components (protocol, host, path, query, hash)
  • URL building and modification from components
  • Query parameter extraction as MAP or individual values
  • Pattern caching for improved performance (~320k matches/sec)

Key Functions

Function Description
urlpattern_test(pattern, url) Test if URL matches pattern
urlpattern_extract(pattern, url, group) Extract a named group
urlpattern_exec(pattern, url) Get full match results as STRUCT
url_parse(url) Parse URL into struct with all components
url_build(...) Build URL from named components
url_modify(url, ...) Modify existing URL components
url_search_params(url) Get query parameters as MAP

Pattern Syntax

URLPattern uses a syntax similar to Express.js routes:

  • :name - Named parameter (matches any segment)
  • * - Wildcard (matches everything)
  • /path/:id - Path-only patterns match any protocol/host

For full documentation, see duckdb-urlpattern.readthedocs.io.

Added Functions

function_name function_type description comment examples
url_build scalar Build a URL string from named component parameters. NULL [url_build(protocol := 'https', hostname := 'example.com', pathname := '/api')]
url_hash scalar Get the hash/fragment component of a URL. NULL [url_hash('https://example.com#section')]
url_host scalar Get the host (hostname and port) component of a URL. NULL [url_host('https://example.com:8080')]
url_hostname scalar Get the hostname component of a URL. NULL [url_hostname('https://example.com:8080')]
url_href scalar Get the normalized full href of a URL. NULL [url_href('https://example.com/path')]
url_modify scalar Modify components of an existing URL string. NULL [url_modify('https://example.com/api', pathname := '/v2')]
url_origin scalar Get the origin (scheme + host) of a URL. NULL [url_origin('https://example.com/path')]
url_parse scalar Parse a URL string into a STRUCT of its components. NULL [url_parse('https://user:[email protected]:8080/path?q=1#hash')]
url_password scalar Get the password component of a URL. NULL [url_password('https://user:[email protected]')]
url_pathname scalar Get the pathname component of a URL. NULL [url_pathname('https://example.com/api/v1')]
url_port scalar Get the port component of a URL. NULL [url_port('https://example.com:8080')]
url_protocol scalar Get the protocol component of a URL. NULL [url_protocol('https://example.com')]
url_resolve scalar Resolve a relative URL against a base URL. NULL [url_resolve('https://example.com/dir/', '../other')]
url_search scalar Get the query string component of a URL. NULL [url_search('https://example.com?q=1')]
url_search_param scalar Extract the value of a specific query parameter from a URL. NULL [url_search_param('https://example.com?a=1&b=2', 'a')]
url_search_params scalar Extract all query search parameters from a URL as a MAP. NULL [url_search_params('https://example.com?a=1&b=2')]
url_username scalar Get the username component of a URL. NULL [url_username('https://user:[email protected]')]
url_valid scalar Check if a URL string is valid. NULL [url_valid('https://example.com')]
urlpattern scalar Construct a URLPATTERN from a pattern string. NULL [urlpattern('/users/:id')]
urlpattern_exec scalar Execute pattern matching on a URL and return matched components and groups as a STRUCT. NULL [urlpattern_exec(urlpattern('/users/:id'), '/users/123')]
urlpattern_extract scalar Extract matched component value from a URL using URLPattern. NULL [urlpattern_extract(urlpattern('/users/:id'), '/users/123', 'id')]
urlpattern_hash scalar Get the hash/fragment pattern of a URLPattern. NULL [urlpattern_hash(urlpattern('https://example.com/#'))]
urlpattern_hostname scalar Get the hostname pattern of a URLPattern. NULL [urlpattern_hostname(urlpattern('https://example.com/*'))]
urlpattern_init scalar Initialize a URLPATTERN with named component patterns. NULL [urlpattern_init(pathname := '/users/:id')]
urlpattern_pathname scalar Get the pathname pattern of a URLPattern. NULL [urlpattern_pathname(urlpattern('/users/:id'))]
urlpattern_port scalar Get the port pattern of a URLPattern. NULL [urlpattern_port(urlpattern('https://example.com:8080/*'))]
urlpattern_protocol scalar Get the protocol pattern of a URLPattern. NULL [urlpattern_protocol(urlpattern('https://example.com/*'))]
urlpattern_search scalar Get the search/query pattern of a URLPattern. NULL [urlpattern_search(urlpattern('https://example.com/?q='))]
urlpattern_test scalar Test if a URL matches a URLPattern. NULL [urlpattern_test(urlpattern('/users/:id'), '/users/123')]

Overloaded Functions

This extension does not add any function overloads.

Added Types

type_name type_size logical_type type_category internal
URLPATTERN 16 VARCHAR STRING true

Added Settings

This extension does not add any settings.