This is an automated email from the ASF dual-hosted git repository.
comphead pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 6ac199919f doc-gen: migrate window functions documentation to
attribute based (#13739)
6ac199919f is described below
commit 6ac199919f323f1121f1662349ed93de3446c72a
Author: zjregee <[email protected]>
AuthorDate: Fri Dec 13 13:15:01 2024 +0800
doc-gen: migrate window functions documentation to attribute based (#13739)
* doc-gen: migrate window functions documentation
Signed-off-by: zjregee <[email protected]>
* fix: update Cargo.lock
---------
Signed-off-by: zjregee <[email protected]>
---
datafusion-cli/Cargo.lock | 28 ++++++++++++++-------------
datafusion/functions-window/Cargo.toml | 2 ++
datafusion/functions-window/src/cume_dist.rs | 20 ++++++++-----------
datafusion/functions-window/src/ntile.rs | 25 ++++++++++++------------
datafusion/functions-window/src/row_number.rs | 23 +++++++---------------
5 files changed, 44 insertions(+), 54 deletions(-)
diff --git a/datafusion-cli/Cargo.lock b/datafusion-cli/Cargo.lock
index 67880c55c2..89a2e6384f 100644
--- a/datafusion-cli/Cargo.lock
+++ b/datafusion-cli/Cargo.lock
@@ -881,9 +881,9 @@ dependencies = [
[[package]]
name = "bstr"
-version = "1.11.0"
+version = "1.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index";
-checksum = "1a68f1f47cdf0ec8ee4b941b2eee2a80cb796db73118c0dd09ac63fbe405be22"
+checksum = "786a307d683a5bf92e6fd5fd69a7eb613751668d1d8d67d802846dfe367c62c8"
dependencies = [
"memchr",
"regex-automata",
@@ -1512,8 +1512,10 @@ name = "datafusion-functions-window"
version = "43.0.0"
dependencies = [
"datafusion-common",
+ "datafusion-doc",
"datafusion-expr",
"datafusion-functions-window-common",
+ "datafusion-macros",
"datafusion-physical-expr",
"datafusion-physical-expr-common",
"log",
@@ -2210,7 +2212,7 @@ dependencies = [
"http 1.2.0",
"hyper 1.5.1",
"hyper-util",
- "rustls 0.23.19",
+ "rustls 0.23.20",
"rustls-native-certs 0.8.1",
"rustls-pki-types",
"tokio",
@@ -3112,7 +3114,7 @@ dependencies = [
"quinn-proto",
"quinn-udp",
"rustc-hash",
- "rustls 0.23.19",
+ "rustls 0.23.20",
"socket2",
"thiserror 2.0.6",
"tokio",
@@ -3130,7 +3132,7 @@ dependencies = [
"rand",
"ring",
"rustc-hash",
- "rustls 0.23.19",
+ "rustls 0.23.20",
"rustls-pki-types",
"slab",
"thiserror 2.0.6",
@@ -3224,9 +3226,9 @@ dependencies = [
[[package]]
name = "redox_syscall"
-version = "0.5.7"
+version = "0.5.8"
source = "registry+https://github.com/rust-lang/crates.io-index";
-checksum = "9b6dfecf2c74bce2466cabf93f6664d6998a69eb21e39f4207930065b27b771f"
+checksum = "03a862b389f93e68874fbf580b9de08dd02facb9a788ebadaf4a3fd33cf58834"
dependencies = [
"bitflags 2.6.0",
]
@@ -3308,7 +3310,7 @@ dependencies = [
"percent-encoding",
"pin-project-lite",
"quinn",
- "rustls 0.23.19",
+ "rustls 0.23.20",
"rustls-native-certs 0.8.1",
"rustls-pemfile 2.2.0",
"rustls-pki-types",
@@ -3427,9 +3429,9 @@ dependencies = [
[[package]]
name = "rustls"
-version = "0.23.19"
+version = "0.23.20"
source = "registry+https://github.com/rust-lang/crates.io-index";
-checksum = "934b404430bb06b3fae2cba809eb45a1ab1aecd64491213d7c3301b88393f8d1"
+checksum = "5065c3f250cbd332cd894be57c40fa52387247659b14a2d6041d121547903b1b"
dependencies = [
"once_cell",
"ring",
@@ -3617,9 +3619,9 @@ dependencies = [
[[package]]
name = "semver"
-version = "1.0.23"
+version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index";
-checksum = "61697e0a1c7e512e84a621326239844a24d8207b4669b41bc18b32ea5cbf988b"
+checksum = "3cb6eb87a131f756572d7fb904f6e7b68633f09cca868c5df1c4b8d1a694bbba"
[[package]]
name = "seq-macro"
@@ -4060,7 +4062,7 @@ version = "0.26.1"
source = "registry+https://github.com/rust-lang/crates.io-index";
checksum = "5f6d0975eaace0cf0fcadee4e4aaa5da15b5c079146f2cffb67c113be122bf37"
dependencies = [
- "rustls 0.23.19",
+ "rustls 0.23.20",
"tokio",
]
diff --git a/datafusion/functions-window/Cargo.toml
b/datafusion/functions-window/Cargo.toml
index 262c21fcec..fc1bc51bcc 100644
--- a/datafusion/functions-window/Cargo.toml
+++ b/datafusion/functions-window/Cargo.toml
@@ -39,8 +39,10 @@ path = "src/lib.rs"
[dependencies]
datafusion-common = { workspace = true }
+datafusion-doc = { workspace = true }
datafusion-expr = { workspace = true }
datafusion-functions-window-common = { workspace = true }
+datafusion-macros = { workspace = true }
datafusion-physical-expr = { workspace = true }
datafusion-physical-expr-common = { workspace = true }
log = { workspace = true }
diff --git a/datafusion/functions-window/src/cume_dist.rs
b/datafusion/functions-window/src/cume_dist.rs
index 2523fd1cfe..d777f7932b 100644
--- a/datafusion/functions-window/src/cume_dist.rs
+++ b/datafusion/functions-window/src/cume_dist.rs
@@ -21,18 +21,18 @@ use datafusion_common::arrow::array::{ArrayRef,
Float64Array};
use datafusion_common::arrow::datatypes::DataType;
use datafusion_common::arrow::datatypes::Field;
use datafusion_common::Result;
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
use datafusion_expr::{
Documentation, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
};
use datafusion_functions_window_common::field;
use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
use field::WindowUDFFieldArgs;
use std::any::Any;
use std::fmt::Debug;
use std::iter;
use std::ops::Range;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
define_udwf_and_expr!(
CumeDist,
@@ -41,6 +41,11 @@ define_udwf_and_expr!(
);
/// CumeDist calculates the cume_dist in the window function with order by
+#[user_doc(
+ doc_section(label = "Ranking Functions"),
+ description = "Relative rank of the current row: (number of rows preceding
or peer with current row) / (total rows).",
+ syntax_example = "cume_dist()"
+)]
#[derive(Debug)]
pub struct CumeDist {
signature: Signature,
@@ -86,19 +91,10 @@ impl WindowUDFImpl for CumeDist {
}
fn documentation(&self) -> Option<&Documentation> {
- Some(get_cume_dist_doc())
+ self.doc()
}
}
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_cume_dist_doc() -> &'static Documentation {
- DOCUMENTATION.get_or_init(|| {
- Documentation::builder(DOC_SECTION_RANKING, "Relative rank of the
current row: (number of rows preceding or peer with current row) / (total
rows).", "cume_dist()")
- .build()
- })
-}
-
#[derive(Debug, Default)]
pub(crate) struct CumeDistEvaluator;
diff --git a/datafusion/functions-window/src/ntile.rs
b/datafusion/functions-window/src/ntile.rs
index 06bf32f985..180f7ab02c 100644
--- a/datafusion/functions-window/src/ntile.rs
+++ b/datafusion/functions-window/src/ntile.rs
@@ -19,7 +19,7 @@
use std::any::Any;
use std::fmt::Debug;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
use crate::utils::{
get_scalar_value_from_args, get_signed_integer, get_unsigned_integer,
@@ -27,12 +27,12 @@ use crate::utils::{
use datafusion_common::arrow::array::{ArrayRef, UInt64Array};
use datafusion_common::arrow::datatypes::{DataType, Field};
use datafusion_common::{exec_err, DataFusionError, Result};
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
use datafusion_expr::{
Documentation, Expr, PartitionEvaluator, Signature, Volatility,
WindowUDFImpl,
};
use datafusion_functions_window_common::field;
use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
use field::WindowUDFFieldArgs;
get_or_init_udwf!(
@@ -45,6 +45,15 @@ pub fn ntile(arg: Expr) -> Expr {
ntile_udwf().call(vec![arg])
}
+#[user_doc(
+ doc_section(label = "Ranking Functions"),
+ description = "Integer ranging from 1 to the argument value, dividing the
partition as equally as possible",
+ syntax_example = "ntile(expression)",
+ argument(
+ name = "expression",
+ description = "An integer describing the number groups the partition
should be split into"
+ )
+)]
#[derive(Debug)]
pub struct Ntile {
signature: Signature,
@@ -78,16 +87,6 @@ impl Default for Ntile {
}
}
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_ntile_doc() -> &'static Documentation {
- DOCUMENTATION.get_or_init(|| {
- Documentation::builder(DOC_SECTION_RANKING, "Integer ranging from 1 to
the argument value, dividing the partition as equally as possible",
"ntile(expression)")
- .with_argument("expression","An integer describing the number
groups the partition should be split into")
- .build()
- })
-}
-
impl WindowUDFImpl for Ntile {
fn as_any(&self) -> &dyn Any {
self
@@ -135,7 +134,7 @@ impl WindowUDFImpl for Ntile {
}
fn documentation(&self) -> Option<&Documentation> {
- Some(get_ntile_doc())
+ self.doc()
}
}
diff --git a/datafusion/functions-window/src/row_number.rs
b/datafusion/functions-window/src/row_number.rs
index 72d4e02323..8f462528db 100644
--- a/datafusion/functions-window/src/row_number.rs
+++ b/datafusion/functions-window/src/row_number.rs
@@ -23,17 +23,16 @@ use datafusion_common::arrow::compute::SortOptions;
use datafusion_common::arrow::datatypes::DataType;
use datafusion_common::arrow::datatypes::Field;
use datafusion_common::{Result, ScalarValue};
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
use datafusion_expr::{
Documentation, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
};
use datafusion_functions_window_common::field;
use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
use field::WindowUDFFieldArgs;
use std::any::Any;
use std::fmt::Debug;
use std::ops::Range;
-use std::sync::OnceLock;
define_udwf_and_expr!(
RowNumber,
@@ -42,6 +41,11 @@ define_udwf_and_expr!(
);
/// row_number expression
+#[user_doc(
+ doc_section(label = "Ranking Functions"),
+ description = "Number of the current row within its partition, counting
from 1.",
+ syntax_example = "row_number()"
+)]
#[derive(Debug)]
pub struct RowNumber {
signature: Signature,
@@ -62,19 +66,6 @@ impl Default for RowNumber {
}
}
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_row_number_doc() -> &'static Documentation {
- DOCUMENTATION.get_or_init(|| {
- Documentation::builder(
- DOC_SECTION_RANKING,
- "Number of the current row within its partition, counting from 1.",
- "row_number()",
- )
- .build()
- })
-}
-
impl WindowUDFImpl for RowNumber {
fn as_any(&self) -> &dyn Any {
self
@@ -107,7 +98,7 @@ impl WindowUDFImpl for RowNumber {
}
fn documentation(&self) -> Option<&Documentation> {
- Some(get_row_number_doc())
+ self.doc()
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
