documentation

Author: rafafrdz

datafusion/spark/src/function/url/try_parse_url.rs

@@ -20,12 +20,48 @@ use std::any::Any;
 use crate::function::url::parse_url::{spark_handled_parse_url, ParseUrl};
 use arrow::array::ArrayRef;
 use arrow::datatypes::DataType;
-use datafusion_common::{exec_datafusion_err, exec_err, plan_err, Result};
+use datafusion_common::Result;
 use datafusion_expr::{
-    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+    ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature,
+    Volatility,
 };
 use datafusion_functions::utils::make_scalar_function;
+use datafusion_macros::user_doc;
 
+#[user_doc(
+    doc_section(label = "URL Functions"),
+    description = "Extracts components of a URL string. Unlike [`parse_url`](#parse_url), this function never fails with an error on malformed input; instead, it returns `NULL` when parsing is not possible. If the requested component is missing, the result is also `NULL`. When extracting a query parameter with a key, returns `NULL` if the parameter is not present.",
+    syntax_example = "try_parse_url(url, part[, key])",
+    sql_example = r#"```sql
+SELECT try_parse_url('https://example.com/a?x=1', 'QUERY', 'x');
+----
+1
+
+SELECT try_parse_url('www.example.com/path?x=1', 'HOST');
+----
+NULL
+
+SELECT try_parse_url('https://example.com/?a=1', 'QUERY', 'b');
+----
+NULL
+
+SELECT try_parse_url('https://example.com/path#frag', 'REF');
+----
+frag
+```"#,
+    argument(
+        name = "url",
+        description = "A string expression representing the URL to parse."
+    ),
+    argument(
+        name = "part",
+        description = "Which part of the URL to extract. Supported values: 'HOST' (host name, e.g., example.com or [2001:db8::2]), 'PATH' (e.g., /a/b), 'QUERY' (entire query, e.g., a=1&b=2), 'REF' (fragment without '#', e.g., frag), 'PROTOCOL' (scheme, e.g., http, https, ftp), 'FILE' (path plus query, e.g., /a/b?x=1), 'AUTHORITY' (authority section, including user info and host), 'USERINFO' (user info before the host, e.g., user:pwd)."
+    ),
+    argument(
+        name = "key",
+        description = "(Optional). Only valid when part = 'QUERY'. Extracts the value of the query parameter with that name (case sensitivity may depend on implementation). Returns `NULL` if the parameter is not present."
+    )
+)]
 #[derive(Debug, PartialEq, Eq, Hash)]
 pub struct TryParseUrl {
     signature: Signature,
@@ -72,6 +108,10 @@ impl ScalarUDFImpl for TryParseUrl {
         let parse_url: ParseUrl = ParseUrl::new();
         parse_url.coerce_types(arg_types)
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        self.doc()
+    }
 }
 
 fn spark_try_parse_url(args: &[ArrayRef]) -> Result<ArrayRef> {

datafusion/sqllogictest/test_files/spark/url/try_parse_url.slt

@@ -21,52 +21,71 @@
 # For more information, please see:
 #   https://github.com/apache/datafusion/issues/15914
 
-query T
+query error
 SELECT try_parse_url('https://example.com/a?x=1', 'QUERY', 'x'), typeof(try_parse_url('https://example.com/a?x=1', 'QUERY', 'x'));
 ----
-1    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
 
-query T
+
+query error
 SELECT try_parse_url('www.example.com/path?x=1', 'HOST'), typeof(try_parse_url('www.example.com/path?x=1', 'HOST'));
 ----
-NULL    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
+
 
-query T
+query error
 SELECT try_parse_url('https://example.com/?a=1', 'QUERY', 'b'), typeof(try_parse_url('https://example.com/?a=1', 'QUERY', 'b'));
 ----
-NULL    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
+
 
-query T
+query error
 SELECT try_parse_url('https://example.com/path#frag', 'REF'), typeof(try_parse_url('https://example.com/path#frag', 'REF'));
 ----
-frag    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
 
-query T
+
+query error
 SELECT try_parse_url('ftp://user:pwd@ftp.example.com:21/files', 'USERINFO'), typeof(try_parse_url('ftp://user:pwd@ftp.example.com:21/files', 'USERINFO'));
 ----
-user:pwd    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
+
 
-query T
+query error
 SELECT try_parse_url('http://[2001:db8::2]:8080/index.html?ok=1', 'HOST'), typeof(try_parse_url('http://[2001:db8::2]:8080/index.html?ok=1', 'HOST'));
 ----
-[2001:db8::2]    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
 
-query T
+
+query error
 SELECT try_parse_url('notaurl', 'HOST'), typeof(try_parse_url('notaurl', 'HOST'));
 ----
-NULL    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
+
 
-query T
+query error
 SELECT try_parse_url('https://example.com', 'PATH'), typeof(try_parse_url('https://example.com', 'PATH'));
 ----
-    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
 
-query T
+
+query error
 SELECT try_parse_url('https://example.com/a/b?x=1&y=2#frag', 'PROTOCOL'), typeof(try_parse_url('https://example.com/a/b?x=1&y=2#frag', 'PROTOCOL'));
 ----
-https    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?
+
 
-query T
+query error
 SELECT try_parse_url('https://ex.com/?Tag=ok', 'QUERY', 'tag'), typeof(try_parse_url('https://ex.com/?Tag=ok', 'QUERY', 'tag'));
 ----
-NULL    string
+DataFusion error: Error during planning: Invalid function 'try_parse_url'.
+Did you mean 'parse_url'?

docs/source/user-guide/sql/scalar_functions.md

@@ -4547,96 +4547,6 @@ union_tag(union_expression)
 +--------------+-------------------------+
 ```
 
-## Url Functions
-
-Functions for parsing and extracting parts of URLs.
-
-- [parse_url](#parse_url)
-- [try_parse_url](#try_parse_url)
-
-### `parse_url`
-
-Extracts a specified part from a URL. If a key is provided, it returns the associated query parameter value.
-```sql
-parse_url(url, part[, key])
-```
-
-#### Arguments
-
-- **url**: A string expression representing the URL to parse.
-- **part**: A string expression specifying which part of the URL to extract. Supported values include:
-  - **'HOST'** – the host name (e.g., example.com or [2001:db8::2])
-  - **'PATH'** – the path component (e.g., /a/b)
-  - **'QUERY'** – the entire query string (e.g., a=1&b=2)
-  - **'REF'** – the fragment identifier (e.g., frag from #frag)
-  - **'PROTOCOL'** – the protocol/scheme (e.g., http, https, ftp)
-  - **'FILE'** – the path plus query (e.g., /a/b?x=1)
-  - **'AUTHORITY'** – the authority section, including user info and host
-  - **'USERINFO'** – the user information before the host (e.g., user:pwd)
-- **key**: An optional string expression. Only valid when part = 'QUERY'. Extracts the value of the query parameter with that name. Case-sensitive depending on implementation.
-
-#### Behavior
-
-A new column of `STRING`, each representing the value of the extracted part from the URL. If url is invalid, or if the requested component is missing, throws an exception.
-
-#### Example
-
-```sql
-SELECT parse_url('https://example.com/a?x=1', 'QUERY', 'x');
-----
-1
-
-SELECT parse_url('https://example.com/path#frag', 'REF');
-----
-frag
-```
-
-### `try_parse_url`
-
-Extracts components of a URL string. Unlike parse_url, this function never fails with an error on malformed input; instead, it returns NULL when parsing is not possible.
-
-```sql
-try_parse_url(url, part[, key])
-```
-
-#### Arguments
-
-- **url**: A string expression representing the URL to parse.
-- **part**: A string expression specifying which part of the URL to extract. Supported values include:
-  - **'HOST'** – the host name (e.g., example.com or [2001:db8::2])
-  - **'PATH'** – the path component (e.g., /a/b)
-  - **'QUERY'** – the entire query string (e.g., a=1&b=2)
-  - **'REF'** – the fragment identifier (e.g., frag from #frag)
-  - **'PROTOCOL'** – the protocol/scheme (e.g., http, https, ftp)
-  - **'FILE'** – the path plus query (e.g., /a/b?x=1)
-  - **'AUTHORITY'** – the authority section, including user info and host
-  - **'USERINFO'** – the user information before the host (e.g., user:pwd)
-- **key**: An optional string expression. Only valid when part = 'QUERY'. Extracts the value of the query parameter with that name. Case-sensitive depending on implementation.
-
-#### Behavior
-
-A new column of `STRING`, each representing the value of the extracted part from the URL. If url is invalid, or if the requested component is missing, returns `NULL`. When extracting a query parameter with key, returns `NULL` if the parameter is not present.
-
-#### Example
-
-```sql
-SELECT try_parse_url('https://example.com/a?x=1', 'QUERY', 'x');
-----
-1
-
-SELECT try_parse_url('www.example.com/path?x=1', 'HOST');
-----
-NULL
-
-SELECT try_parse_url('https://example.com/?a=1', 'QUERY', 'b');
-----
-NULL
-
-SELECT try_parse_url('https://example.com/path#frag', 'REF');
-----
-frag
-```
-
 ## Other Functions
 
 - [arrow_cast](#arrow_cast)