Skip to content

Minor: fix Aggregation Docs from review #12880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alamb merged 3 commits into from
Oct 16, 2024
Merged

Minor: fix Aggregation Docs from review #12880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc792d1
fix aggregate docs
jonathanc-n Oct 11, 2024
f953d58
fmt fix
jonathanc-n Oct 11, 2024
750d7de
Merge remote-tracking branch 'apache/main' into fix-aggregate-docs
alamb Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/approx_distinct.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@ fn get_approx_distinct_doc() -> &'static Documentation {
+-----------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/approx_median.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ fn get_approx_median_doc() -> &'static Documentation {
+-----------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/approx_percentile_cont.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ fn get_approx_percentile_cont_doc() -> &'static Documentation {
| 65.0 |
+-------------------------------------------------+
```"#)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
Copy link
Member

@findepi findepi Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

curious, what does "The" stand for?

Copy link
Contributor

@Omega359 Omega359 Oct 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

datafusion/datafusion/expr/src/udf_docs.rs

Line 148 in a8d3fae

/// Add a standard "expression" argument to the documentation

Copy link
Member

@findepi findepi Oct 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the link. "The" still looks weird to me. I guess it gets concatenated with something else.

if i follow the link correctly, this gets passed as expression_type argument, but "The" does not look like expression type.

Could we have an overload so that "The" is not needed?
eg with_standard_sole_argument could produce "The expression to operate on. Can be a constant, column, or function, and any combination of operators." without requiring "The" from the caller.

Copy link
Contributor

@Omega359 Omega359 Oct 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, it really does look strange. .with_standard_argument("expression", None) / with_standard_argument("expression", Some("String")) ?

.with_argument("percentile", "Percentile to compute. Must be a float value between 0 and 1 (inclusive).")
.with_argument("centroids", "Number of centroids to use in the t-digest algorithm. _Default is 100_. A higher number results in more accurate approximation but requires more memory.")
.build()
Expand Down
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ fn get_approx_percentile_cont_with_weight_doc() -> &'static Documentation {
+----------------------------------------------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.with_argument("weight", "Expression to use as weight. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_argument("percentile", "Percentile to compute. Must be a float value between 0 and 1 (inclusive).")
.build()
Expand Down
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/array_agg.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ fn get_array_agg_doc() -> &'static Documentation {
+-----------------------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
8 changes: 4 additions & 4 deletions datafusion/functions-aggregate/src/average.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,17 +253,17 @@ fn get_avg_doc() -> &'static Documentation {
"Returns the average of numeric values in the specified column.",
)
.with_syntax_example("avg(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT avg(column_name) FROM table_name;
+---------------------------+
| avg(column_name) |
+---------------------------+
| 42.75 |
+---------------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_argument("Aliases: ", "`mean`")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
16 changes: 10 additions & 6 deletions datafusion/functions-aggregate/src/bool_and_or.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,15 +191,17 @@ fn get_bool_and_doc() -> &'static Documentation {
"Returns true if all non-null input values are true, otherwise false.",
)
.with_syntax_example("bool_and(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT bool_and(column_name) FROM table_name;
+----------------------------+
| bool_and(column_name) |
+----------------------------+
| true |
+----------------------------+
```"#)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
```"#,
)
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down Expand Up @@ -338,15 +340,17 @@ fn get_bool_or_doc() -> &'static Documentation {
"Returns true if any non-null input value is true, otherwise false.",
)
.with_syntax_example("bool_or(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT bool_or(column_name) FROM table_name;
+----------------------------+
| bool_or(column_name) |
+----------------------------+
| true |
+----------------------------+
```"#)
.with_standard_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
```"#,
)
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
10 changes: 6 additions & 4 deletions datafusion/functions-aggregate/src/correlation.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,16 +124,18 @@ fn get_corr_doc() -> &'static Documentation {
"Returns the coefficient of correlation between two numeric values.",
)
.with_syntax_example("corr(expression1, expression2)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT corr(column1, column2) FROM table_name;
+--------------------------------+
| corr(column1, column2) |
+--------------------------------+
| 0.85 |
+--------------------------------+
```"#)
.with_argument("expression1", "First expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_argument("expression2", "Second expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
```"#,
)
.with_standard_argument("expression1", "First")
.with_standard_argument("expression2", "Second")
.build()
.unwrap()
})
Expand Down
2 changes: 1 addition & 1 deletion datafusion/functions-aggregate/src/count.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,7 @@ fn get_count_doc() -> &'static Documentation {
| 120 |
+------------------+
```"#)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
22 changes: 11 additions & 11 deletions datafusion/functions-aggregate/src/covariance.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,21 +138,20 @@ fn get_covar_samp_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_STATISTICAL)
.with_description(
"Returns the sample covariance of a set of number pairs.",
)
.with_description("Returns the sample covariance of a set of number pairs.")
.with_syntax_example("covar_samp(expression1, expression2)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT covar_samp(column1, column2) FROM table_name;
+-----------------------------------+
| covar_samp(column1, column2) |
+-----------------------------------+
| 8.25 |
+-----------------------------------+
```"#,
```"#,
)
.with_argument("expression1", "First expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_argument("expression2", "Second expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression1", "First")
.with_standard_argument("expression2", "Second")
.build()
.unwrap()
})
Expand Down Expand Up @@ -239,17 +238,18 @@ fn get_covar_pop_doc() -> &'static Documentation {
"Returns the population covariance of a set of number pairs.",
)
.with_syntax_example("covar_pop(expression1, expression2)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT covar_pop(column1, column2) FROM table_name;
+-----------------------------------+
| covar_pop(column1, column2) |
+-----------------------------------+
| 7.63 |
+-----------------------------------+
```"#,
```"#,
)
.with_argument("expression1", "First expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_argument("expression2", "Second expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression1", "First")
.with_standard_argument("expression2", "Second")
.build()
.unwrap()
})
Expand Down
4 changes: 2 additions & 2 deletions datafusion/functions-aggregate/src/first_last.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ fn get_first_value_doc() -> &'static Documentation {
+-----------------------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down Expand Up @@ -519,7 +519,7 @@ fn get_last_value_doc() -> &'static Documentation {
+-----------------------------------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
9 changes: 4 additions & 5 deletions datafusion/functions-aggregate/src/median.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,11 +165,10 @@ fn get_median_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_GENERAL)
.with_description(
"Returns the median value in the specified column.",
)
.with_description("Returns the median value in the specified column.")
.with_syntax_example("median(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT median(column_name) FROM table_name;
+----------------------+
| median(column_name) |
Expand All @@ -178,7 +177,7 @@ fn get_median_doc() -> &'static Documentation {
+----------------------+
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
22 changes: 10 additions & 12 deletions datafusion/functions-aggregate/src/min_max.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,20 +345,19 @@ fn get_max_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_GENERAL)
.with_description(
"Returns the maximum value in the specified column.",
)
.with_description("Returns the maximum value in the specified column.")
.with_syntax_example("max(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT max(column_name) FROM table_name;
+----------------------+
| max(column_name) |
+----------------------+
| 150 |
+----------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down Expand Up @@ -1176,20 +1175,19 @@ fn get_min_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_GENERAL)
.with_description(
"Returns the minimum value in the specified column.",
)
.with_description("Returns the minimum value in the specified column.")
.with_syntax_example("min(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT min(column_name) FROM table_name;
+----------------------+
| min(column_name) |
+----------------------+
| 12 |
+----------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
18 changes: 9 additions & 9 deletions datafusion/functions-aggregate/src/stddev.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,20 +146,19 @@ fn get_stddev_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_STATISTICAL)
.with_description(
"Returns the standard deviation of a set of numbers.",
)
.with_description("Returns the standard deviation of a set of numbers.")
.with_syntax_example("stddev(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT stddev(column_name) FROM table_name;
+----------------------+
| stddev(column_name) |
+----------------------+
| 12.34 |
+----------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down Expand Up @@ -273,16 +272,17 @@ fn get_stddev_pop_doc() -> &'static Documentation {
"Returns the population standard deviation of a set of numbers.",
)
.with_syntax_example("stddev_pop(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT stddev_pop(column_name) FROM table_name;
+--------------------------+
| stddev_pop(column_name) |
+--------------------------+
| 10.56 |
+--------------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
11 changes: 5 additions & 6 deletions datafusion/functions-aggregate/src/sum.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,20 +248,19 @@ fn get_sum_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder()
.with_doc_section(DOC_SECTION_GENERAL)
.with_description(
"Returns the sum of all values in the specified column.",
)
.with_description("Returns the sum of all values in the specified column.")
.with_syntax_example("sum(expression)")
.with_sql_example(r#"```sql
.with_sql_example(
r#"```sql
> SELECT sum(column_name) FROM table_name;
+-----------------------+
| sum(column_name) |
+-----------------------+
| 12345 |
+-----------------------+
```"#,
```"#,
)
.with_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.")
.with_standard_argument("expression", "The")
.build()
.unwrap()
})
Expand Down
Loading