This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 9d92d9381a Publish built docs triggered by
360175aec4f5dfa43f6d1ab2f4665a4bd397ae83
9d92d9381a is described below
commit 9d92d9381a3da327186890e5a589bda3a78ee59f
Author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
AuthorDate: Tue Oct 17 20:17:15 2023 +0000
Publish built docs triggered by 360175aec4f5dfa43f6d1ab2f4665a4bd397ae83
---
_sources/user-guide/expressions.md.txt | 144 ++++++++++--------
searchindex.js | 2 +-
user-guide/expressions.html | 259 ++++++++++++++++++---------------
3 files changed, 232 insertions(+), 173 deletions(-)
diff --git a/_sources/user-guide/expressions.md.txt
b/_sources/user-guide/expressions.md.txt
index dbd8c814b4..28104dbfd4 100644
--- a/_sources/user-guide/expressions.md.txt
+++ b/_sources/user-guide/expressions.md.txt
@@ -22,60 +22,99 @@
DataFrame methods such as `select` and `filter` accept one or more logical
expressions and there are many functions
available for creating logical expressions. These are documented below.
-Expressions can be chained together using a fluent-style API:
+:::{tip}
+Most functions and methods may receive and return an `Expr`, which can be
chained together using a fluent-style API:
```rust
// create the expression `(a > 6) AND (b < 7)`
col("a").gt(lit(6)).and(col("b").lt(lit(7)))
```
+:::
+
## Identifiers
-| Function | Notes |
-| -------- | -------------------------------------------- |
-| col | Reference a column in a dataframe `col("a")` |
+| Syntax | Description |
+| ---------- | -------------------------------------------- |
+| col(ident) | Reference a column in a dataframe `col("a")` |
+
+:::{note}
+ident
+: A type which implement `Into<Column>` trait
+:::
## Literal Values
-| Function | Notes |
-| -------- | -------------------------------------------------- |
-| lit | Literal value such as `lit(123)` or `lit("hello")` |
+| Syntax | Description |
+| ---------- | -------------------------------------------------- |
+| lit(value) | Literal value such as `lit(123)` or `lit("hello")` |
+
+:::{note}
+value
+: A type which implement `Literal`
+:::
## Boolean Expressions
-| Function | Notes |
-| -------- | ----------------------------------------- |
-| and | `and(expr1, expr2)` or `expr1.and(expr2)` |
-| or | `or(expr1, expr2)` or `expr1.or(expr2)` |
-| not | `not(expr)` or `expr.not()` |
+| Syntax | Description |
+| ------------------- | ----------- |
+| and(x, y), x.and(y) | Logical AND |
+| or(x, y), x.or(y) | Logical OR |
+| !x, not(x), x.not() | Logical NOT |
+
+:::{note}
+`!` is a bitwise or logical complement operator in Rust, but it only works as
a logical NOT in expression API.
+:::
+
+:::{note}
+Since `&&` and `||` are existed as logical operators in Rust, but those are
not overloadable and not works with expression API.
+:::
-## Bitwise expressions
+## Bitwise Expressions
-| Function | Notes
|
-| ------------------- |
------------------------------------------------------------------------- |
-| bitwise_and | `bitwise_and(expr1, expr2)` or
`expr1.bitwise_and(expr2)` |
-| bitwise_or | `bitwise_or(expr1, expr2)` or
`expr1.bitwise_or(expr2)` |
-| bitwise_xor | `bitwise_xor(expr1, expr2)` or
`expr1.bitwise_xor(expr2)` |
-| bitwise_shift_right | `bitwise_shift_right(expr1, expr2)` or
`expr1.bitwise_shift_right(expr2)` |
-| bitwise_shift_left | `bitwise_shift_left(expr1, expr2)` or
`expr1.bitwise_shift_left(expr2)` |
+| Syntax | Description |
+| ------------------------------------------- | ----------- |
+| x & y, bitwise_and(x, y), x.bitand(y) | AND |
+| x \| y, bitwise_or(x, y), x.bitor(y) | OR |
+| x ^ y, bitwise_xor(x, y), x.bitxor(y) | XOR |
+| x << y, bitwise_shift_left(x, y), x.shl(y) | Left shift |
+| x >> y, bitwise_shift_right(x, y), x.shr(y) | Right shift |
## Comparison Expressions
-| Function | Notes |
-| -------- | --------------------- |
-| eq | `expr1.eq(expr2)` |
-| gt | `expr1.gt(expr2)` |
-| gt_eq | `expr1.gt_eq(expr2)` |
-| lt | `expr1.lt(expr2)` |
-| lt_eq | `expr1.lt_eq(expr2)` |
-| not_eq | `expr1.not_eq(expr2)` |
+| Syntax | Description |
+| ----------- | --------------------- |
+| x.eq(y) | Equal |
+| x.not_eq(y) | Not Equal |
+| x.gt(y) | Greater Than |
+| x.gt_eq(y) | Greater Than or Equal |
+| x.lt(y) | Less Than |
+| x.lt_eq(y) | Less Than or Equal |
+
+:::{note}
+Comparison operators (`<`, `<=`, `==`, `>=`, `>`) could be overloaded by the
`PartialOrd` and `PartialEq` trait in Rust,
+but these operators always return a `bool` which makes them not work with the
expression API.
+:::
+
+## Arithmetic Expressions
+
+| Syntax | Description |
+| ---------------- | -------------- |
+| x + y, x.add(y) | Addition |
+| x - y, x.sub(y) | Subtraction |
+| x \* y, x.mul(y) | Multiplication |
+| x / y, x.div(y) | Division |
+| x % y, x.rem(y) | Remainder |
+| -x, x.neg() | Negation |
+
+:::{note}
+In Rust, the keyword `mod` is reserved and cannot be used as an identifier.
+To avoid any conflicts and ensure code completion works smoothly, we use
`mod_` instead.
+:::
## Math Functions
-In addition to the math functions listed here, some Rust operators are
implemented for expressions, allowing
-expressions such as `col("a") + col("b")` to be used.
-
-| Function | Notes |
+| Syntax | Description |
| --------------------- | ------------------------------------------------- |
| abs(x) | absolute value |
| acos(x) | inverse cosine |
@@ -114,11 +153,10 @@ expressions such as `col("a") + col("b")` to be used.
| tanh(x) | hyperbolic tangent |
| trunc(x) | truncate toward zero |
-### Math functions usage notes:
-
+:::{note}
Unlike to some databases the math functions in Datafusion works the same way
as Rust math functions, avoiding failing on corner cases e.g
-```
+```sql
❯ select log(-1), log(0), sqrt(-1);
+----------------+---------------+-----------------+
| log(Int64(-1)) | log(Int64(0)) | sqrt(Int64(-1)) |
@@ -127,27 +165,19 @@ Unlike to some databases the math functions in Datafusion
works the same way as
+----------------+---------------+-----------------+
```
-## Bitwise Operators
-
-| Operator | Notes |
-| -------- | ----------------------------------------------- |
-| & | Bitwise AND => `(expr1 & expr2)` |
-| | | Bitwise OR => <code>(expr1 | expr2)</code> |
-| # | Bitwise XOR => `(expr1 # expr2)` |
-| << | Bitwise left shift => `(expr1 << expr2)` |
-| >> | Bitwise right shift => `(expr1 << expr2)` |
+:::
## Conditional Expressions
-| Function | Notes
[...]
-| -------- |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| coalesce | Returns the first of its arguments that is not null. Null is
returned only if all arguments are null. It is often used to substitute a
default value for null values when data is retrieved for display.
[...]
-| case | CASE expression. The expression may chain multiple `when`
expressions and end with an `end` or `otherwise` expression. Example:</br>
<pre><code>case(col("a") % lit(3))</br> .when(lit(0),
lit("A"))</br> .when(lit(1),
lit("B"))</br> .when(lit(2),
lit("C"))</br> .end()</code></pre>or, end with
`otherwise` to match any other conditions:
<pre><code>case(col("b").gt(lit(100)))</br> &nb [...]
-| nullif | Returns a null value if `value1` equals `value2`; otherwise it
returns `value1`. This can be used to perform the inverse operation of the
`coalesce` expression.
[...]
+| Syntax
| Description
[...]
+|
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| coalesce([value, ...])
| Returns the first of its arguments that is not
null. Null is returned only if all arguments are null. It is often used to
substitute a default value for null values when data is retrieved for display.
[...]
+|
case(expr)</br> .when(expr)</br> .end(),</br>case(expr)</br> .when(expr)</br> .otherwise(expr)
| CASE expression. The expression may chain multiple `when` expressions and
end with an `end` or `otherwise` expression. Example:</br>
<pre><code>case(col("a") % lit(3))</br> .when(lit(0),
lit("A"))</br> .when(lit(1),
lit("B"))</br> . [...]
+| nullif(value1, value2)
| Returns a null value if `value1` equals
`value2`; otherwise it returns `value1`. This can be used to perform the
inverse operation of the `coalesce` expression.
[...]
## String Expressions
-| Function | Notes
|
+| Syntax | Description
|
| ---------------------------------------------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| ascii(character) | Returns a numeric
representation of the character (`character`). Example: `ascii('a') -> 97`
|
| bit_length(text) | Returns the length of the
string (`text`) in bits. Example: `bit_length('spider') -> 48`
|
@@ -182,7 +212,7 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## Array Expressions
-| Function | Notes
|
+| Syntax | Description
|
| ------------------------------------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| array_append(array, element) | Appends an element to the end of an
array. `array_append([1, 2, 3], 4) -> [1, 2, 3, 4]`
|
| array_concat(array[, ..., array_n]) | Concatenates arrays.
`array_concat([1, 2, 3], [4, 5, 6]) -> [1, 2, 3, 4, 5, 6]`
|
@@ -213,14 +243,14 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## Regular Expressions
-| Function | Notes
|
+| Syntax | Description
|
| -------------- |
----------------------------------------------------------------------------- |
| regexp_match | Matches a regular expression against a string and returns
matched substrings. |
| regexp_replace | Replaces strings that match a regular expression
|
## Temporal Expressions
-| Function | Notes
|
+| Syntax | Description
|
| -------------------- |
------------------------------------------------------ |
| date_part | Extracts a subfield from the date.
|
| date_trunc | Truncates the date to a specified level of precision.
|
@@ -233,7 +263,7 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## Other Expressions
-| Function | Notes
|
+| Syntax | Description
|
| ---------------------------- |
----------------------------------------------------------------------------------------------------------
|
| array([value1, ...]) | Returns an array of fixed size with each
argument (`[value1, ...]`) on it. |
| in_list(expr, list, negated) | Returns `true` if (`expr`) belongs or not
belongs (`negated`) to a list (`list`), otherwise returns false. |
@@ -246,7 +276,7 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## Aggregate Functions
-| Function | Notes
|
+| Syntax |
Description
|
| ----------------------------------------------------------------- |
---------------------------------------------------------------------------------------
|
| avg(expr) |
Сalculates the average value for `expr`.
|
| approx_distinct(expr) |
Calculates an approximate count of the number of distinct values for `expr`.
|
@@ -270,7 +300,7 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## Subquery Expressions
-| Function | Notes
|
+| Syntax | Description
|
| --------------- |
---------------------------------------------------------------------------------------------
|
| exists | Creates an `EXISTS` subquery expression
|
| in_subquery | `df1.filter(in_subquery(col("foo"), df2))?` is the
equivalent of the SQL `WHERE foo IN <df2>` |
@@ -280,7 +310,7 @@ Unlike to some databases the math functions in Datafusion
works the same way as
## User-Defined Function Expressions
-| Function | Notes
|
+| Syntax | Description
|
| ----------- |
------------------------------------------------------------------------- |
| create_udf | Creates a new UDF with a specific signature and specific
return type. |
| create_udaf | Creates a new UDAF with a specific signature, state type and
return type. |
diff --git a/searchindex.js b/searchindex.js
index bf3f9753b1..4ba55d0ea9 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Search.setIndex({"docnames": ["contributor-guide/architecture",
"contributor-guide/communication", "contributor-guide/index",
"contributor-guide/quarterly_roadmap", "contributor-guide/roadmap",
"contributor-guide/specification/index",
"contributor-guide/specification/invariants",
"contributor-guide/specification/output-field-name-semantic", "index",
"library-user-guide/adding-udfs", "library-user-guide/building-logical-plans",
"library-user-guide/catalogs", "library-user-guide/custom-tab [...]
\ No newline at end of file
+Search.setIndex({"docnames": ["contributor-guide/architecture",
"contributor-guide/communication", "contributor-guide/index",
"contributor-guide/quarterly_roadmap", "contributor-guide/roadmap",
"contributor-guide/specification/index",
"contributor-guide/specification/invariants",
"contributor-guide/specification/output-field-name-semantic", "index",
"library-user-guide/adding-udfs", "library-user-guide/building-logical-plans",
"library-user-guide/catalogs", "library-user-guide/custom-tab [...]
\ No newline at end of file
diff --git a/user-guide/expressions.html b/user-guide/expressions.html
index 1059d9d6d2..16129bac32 100644
--- a/user-guide/expressions.html
+++ b/user-guide/expressions.html
@@ -363,7 +363,7 @@
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#bitwise-expressions">
- Bitwise expressions
+ Bitwise Expressions
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
@@ -372,20 +372,13 @@
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
- <a class="reference internal nav-link" href="#math-functions">
- Math Functions
+ <a class="reference internal nav-link" href="#arithmetic-expressions">
+ Arithmetic Expressions
</a>
- <ul class="nav section-nav flex-column">
- <li class="toc-h3 nav-item toc-entry">
- <a class="reference internal nav-link" href="#math-functions-usage-notes">
- Math functions usage notes:
- </a>
- </li>
- </ul>
</li>
<li class="toc-h2 nav-item toc-entry">
- <a class="reference internal nav-link" href="#bitwise-operators">
- Bitwise Operators
+ <a class="reference internal nav-link" href="#math-functions">
+ Math Functions
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
@@ -483,85 +476,110 @@
<h1>Expression API<a class="headerlink" href="#expression-api" title="Link to
this heading">¶</a></h1>
<p>DataFrame methods such as <code class="docutils literal notranslate"><span
class="pre">select</span></code> and <code class="docutils literal
notranslate"><span class="pre">filter</span></code> accept one or more logical
expressions and there are many functions
available for creating logical expressions. These are documented below.</p>
-<p>Expressions can be chained together using a fluent-style API:</p>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>Most functions and methods may receive and return an <code class="docutils
literal notranslate"><span class="pre">Expr</span></code>, which can be chained
together using a fluent-style API:</p>
<div class="highlight-rust notranslate"><div
class="highlight"><pre><span></span><span class="c1">// create the expression
`(a > 6) AND (b < 7)`</span>
<span class="n">col</span><span class="p">(</span><span
class="s">"a"</span><span class="p">).</span><span
class="n">gt</span><span class="p">(</span><span class="n">lit</span><span
class="p">(</span><span class="mi">6</span><span class="p">)).</span><span
class="n">and</span><span class="p">(</span><span class="n">col</span><span
class="p">(</span><span class="s">"b"</span><span
class="p">).</span><span class="n">lt</span><span class="p">(</span><span
class="n">lit</ [...]
</pre></div>
</div>
+</div>
<section id="identifiers">
<h2>Identifiers<a class="headerlink" href="#identifiers" title="Link to this
heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>col</p></td>
+<tr class="row-even"><td><p>col(ident)</p></td>
<td><p>Reference a column in a dataframe <code class="docutils literal
notranslate"><span class="pre">col("a")</span></code></p></td>
</tr>
</tbody>
</table>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<dl class="simple myst">
+<dt>ident</dt><dd><p>A type which implement <code class="docutils literal
notranslate"><span class="pre">Into<Column></span></code> trait</p>
+</dd>
+</dl>
+</div>
</section>
<section id="literal-values">
<h2>Literal Values<a class="headerlink" href="#literal-values" title="Link to
this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>lit</p></td>
+<tr class="row-even"><td><p>lit(value)</p></td>
<td><p>Literal value such as <code class="docutils literal notranslate"><span
class="pre">lit(123)</span></code> or <code class="docutils literal
notranslate"><span class="pre">lit("hello")</span></code></p></td>
</tr>
</tbody>
</table>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<dl class="simple myst">
+<dt>value</dt><dd><p>A type which implement <code class="docutils literal
notranslate"><span class="pre">Literal</span></code></p>
+</dd>
+</dl>
+</div>
</section>
<section id="boolean-expressions">
<h2>Boolean Expressions<a class="headerlink" href="#boolean-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>and</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">and(expr1,</span> <span class="pre">expr2)</span></code> or <code
class="docutils literal notranslate"><span
class="pre">expr1.and(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>and(x, y), x.and(y)</p></td>
+<td><p>Logical AND</p></td>
</tr>
-<tr class="row-odd"><td><p>or</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">or(expr1,</span> <span class="pre">expr2)</span></code> or <code
class="docutils literal notranslate"><span
class="pre">expr1.or(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>or(x, y), x.or(y)</p></td>
+<td><p>Logical OR</p></td>
</tr>
-<tr class="row-even"><td><p>not</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">not(expr)</span></code> or <code class="docutils literal
notranslate"><span class="pre">expr.not()</span></code></p></td>
+<tr class="row-even"><td><p>!x, not(x), x.not()</p></td>
+<td><p>Logical NOT</p></td>
</tr>
</tbody>
</table>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p><code class="docutils literal notranslate"><span
class="pre">!</span></code> is a bitwise or logical complement operator in
Rust, but it only works as a logical NOT in expression API.</p>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Since <code class="docutils literal notranslate"><span
class="pre">&&</span></code> and <code class="docutils literal
notranslate"><span class="pre">||</span></code> are existed as logical
operators in Rust, but those are not overloadable and not works with expression
API.</p>
+</div>
</section>
<section id="bitwise-expressions">
-<h2>Bitwise expressions<a class="headerlink" href="#bitwise-expressions"
title="Link to this heading">¶</a></h2>
+<h2>Bitwise Expressions<a class="headerlink" href="#bitwise-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>bitwise_and</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">bitwise_and(expr1,</span> <span class="pre">expr2)</span></code> or
<code class="docutils literal notranslate"><span
class="pre">expr1.bitwise_and(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x & y, bitwise_and(x, y), x.bitand(y)</p></td>
+<td><p>AND</p></td>
</tr>
-<tr class="row-odd"><td><p>bitwise_or</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">bitwise_or(expr1,</span> <span class="pre">expr2)</span></code> or
<code class="docutils literal notranslate"><span
class="pre">expr1.bitwise_or(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>x | y, bitwise_or(x, y), x.bitor(y)</p></td>
+<td><p>OR</p></td>
</tr>
-<tr class="row-even"><td><p>bitwise_xor</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">bitwise_xor(expr1,</span> <span class="pre">expr2)</span></code> or
<code class="docutils literal notranslate"><span
class="pre">expr1.bitwise_xor(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x ^ y, bitwise_xor(x, y), x.bitxor(y)</p></td>
+<td><p>XOR</p></td>
</tr>
-<tr class="row-odd"><td><p>bitwise_shift_right</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">bitwise_shift_right(expr1,</span> <span
class="pre">expr2)</span></code> or <code class="docutils literal
notranslate"><span
class="pre">expr1.bitwise_shift_right(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>x << y, bitwise_shift_left(x, y),
x.shl(y)</p></td>
+<td><p>Left shift</p></td>
</tr>
-<tr class="row-even"><td><p>bitwise_shift_left</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">bitwise_shift_left(expr1,</span> <span
class="pre">expr2)</span></code> or <code class="docutils literal
notranslate"><span
class="pre">expr1.bitwise_shift_left(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x >> y, bitwise_shift_right(x, y),
x.shr(y)</p></td>
+<td><p>Right shift</p></td>
</tr>
</tbody>
</table>
@@ -570,40 +588,78 @@ available for creating logical expressions. These are
documented below.</p>
<h2>Comparison Expressions<a class="headerlink" href="#comparison-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>eq</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.eq(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x.eq(y)</p></td>
+<td><p>Equal</p></td>
</tr>
-<tr class="row-odd"><td><p>gt</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.gt(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>x.not_eq(y)</p></td>
+<td><p>Not Equal</p></td>
</tr>
-<tr class="row-even"><td><p>gt_eq</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.gt_eq(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x.gt(y)</p></td>
+<td><p>Greater Than</p></td>
</tr>
-<tr class="row-odd"><td><p>lt</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.lt(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>x.gt_eq(y)</p></td>
+<td><p>Greater Than or Equal</p></td>
</tr>
-<tr class="row-even"><td><p>lt_eq</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.lt_eq(expr2)</span></code></p></td>
+<tr class="row-even"><td><p>x.lt(y)</p></td>
+<td><p>Less Than</p></td>
</tr>
-<tr class="row-odd"><td><p>not_eq</p></td>
-<td><p><code class="docutils literal notranslate"><span
class="pre">expr1.not_eq(expr2)</span></code></p></td>
+<tr class="row-odd"><td><p>x.lt_eq(y)</p></td>
+<td><p>Less Than or Equal</p></td>
</tr>
</tbody>
</table>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Comparison operators (<code class="docutils literal notranslate"><span
class="pre"><</span></code>, <code class="docutils literal
notranslate"><span class="pre"><=</span></code>, <code class="docutils
literal notranslate"><span class="pre">==</span></code>, <code class="docutils
literal notranslate"><span class="pre">>=</span></code>, <code
class="docutils literal notranslate"><span class="pre">></span></code>)
could be overloaded by the <code class="docutils literal notra [...]
+but these operators always return a <code class="docutils literal
notranslate"><span class="pre">bool</span></code> which makes them not work
with the expression API.</p>
+</div>
+</section>
+<section id="arithmetic-expressions">
+<h2>Arithmetic Expressions<a class="headerlink" href="#arithmetic-expressions"
title="Link to this heading">¶</a></h2>
+<table class="table">
+<thead>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p>x + y, x.add(y)</p></td>
+<td><p>Addition</p></td>
+</tr>
+<tr class="row-odd"><td><p>x - y, x.sub(y)</p></td>
+<td><p>Subtraction</p></td>
+</tr>
+<tr class="row-even"><td><p>x * y, x.mul(y)</p></td>
+<td><p>Multiplication</p></td>
+</tr>
+<tr class="row-odd"><td><p>x / y, x.div(y)</p></td>
+<td><p>Division</p></td>
+</tr>
+<tr class="row-even"><td><p>x % y, x.rem(y)</p></td>
+<td><p>Remainder</p></td>
+</tr>
+<tr class="row-odd"><td><p>-x, x.neg()</p></td>
+<td><p>Negation</p></td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>In Rust, the keyword <code class="docutils literal notranslate"><span
class="pre">mod</span></code> is reserved and cannot be used as an identifier.
+To avoid any conflicts and ensure code completion works smoothly, we use <code
class="docutils literal notranslate"><span class="pre">mod_</span></code>
instead.</p>
+</div>
</section>
<section id="math-functions">
<h2>Math Functions<a class="headerlink" href="#math-functions" title="Link to
this heading">¶</a></h2>
-<p>In addition to the math functions listed here, some Rust operators are
implemented for expressions, allowing
-expressions such as <code class="docutils literal notranslate"><span
class="pre">col("a")</span> <span class="pre">+</span> <span
class="pre">col("b")</span></code> to be used.</p>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -717,62 +773,35 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
</tr>
</tbody>
</table>
-<section id="math-functions-usage-notes">
-<h3>Math functions usage notes:<a class="headerlink"
href="#math-functions-usage-notes" title="Link to this heading">¶</a></h3>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
<p>Unlike to some databases the math functions in Datafusion works the same
way as Rust math functions, avoiding failing on corner cases e.g</p>
-<div class="highlight-default notranslate"><div
class="highlight"><pre><span></span>❯ select log(-1), log(0), sqrt(-1);
-+----------------+---------------+-----------------+
-| log(Int64(-1)) | log(Int64(0)) | sqrt(Int64(-1)) |
-+----------------+---------------+-----------------+
-| NaN | -inf | NaN |
-+----------------+---------------+-----------------+
+<div class="highlight-sql notranslate"><div
class="highlight"><pre><span></span><span class="err">❯</span><span class="w">
</span><span class="k">select</span><span class="w"> </span><span
class="n">log</span><span class="p">(</span><span class="o">-</span><span
class="mi">1</span><span class="p">),</span><span class="w"> </span><span
class="n">log</span><span class="p">(</span><span class="mi">0</span><span
class="p">),</span><span class="w"> </span><span class="n">sqrt</span><span
clas [...]
+<span class="o">+</span><span
class="c1">----------------+---------------+-----------------+</span>
+<span class="o">|</span><span class="w"> </span><span
class="n">log</span><span class="p">(</span><span class="n">Int64</span><span
class="p">(</span><span class="o">-</span><span class="mi">1</span><span
class="p">))</span><span class="w"> </span><span class="o">|</span><span
class="w"> </span><span class="n">log</span><span class="p">(</span><span
class="n">Int64</span><span class="p">(</span><span class="mi">0</span><span
class="p">))</span><span class="w"> </span><span class="o">|</s [...]
+<span class="o">+</span><span
class="c1">----------------+---------------+-----------------+</span>
+<span class="o">|</span><span class="w"> </span><span
class="n">NaN</span><span class="w"> </span><span
class="o">|</span><span class="w"> </span><span class="o">-</span><span
class="n">inf</span><span class="w"> </span><span
class="o">|</span><span class="w"> </span><span class="n">NaN</span><span
class="w"> </span><span class="o">|</span>
+<span class="o">+</span><span
class="c1">----------------+---------------+-----------------+</span>
</pre></div>
</div>
-</section>
-</section>
-<section id="bitwise-operators">
-<h2>Bitwise Operators<a class="headerlink" href="#bitwise-operators"
title="Link to this heading">¶</a></h2>
-<table class="table">
-<thead>
-<tr class="row-odd"><th class="head"><p>Operator</p></th>
-<th class="head"><p>Notes</p></th>
-</tr>
-</thead>
-<tbody>
-<tr class="row-even"><td><p>&</p></td>
-<td><p>Bitwise AND => <code class="docutils literal notranslate"><span
class="pre">(expr1</span> <span class="pre">&</span> <span
class="pre">expr2)</span></code></p></td>
-</tr>
-<tr class="row-odd"><td><p>|</p></td>
-<td><p>Bitwise OR => <code>(expr1 | expr2)</code></p></td>
-</tr>
-<tr class="row-even"><td><p>#</p></td>
-<td><p>Bitwise XOR => <code class="docutils literal notranslate"><span
class="pre">(expr1</span> <span class="pre">#</span> <span
class="pre">expr2)</span></code></p></td>
-</tr>
-<tr class="row-odd"><td><p><<</p></td>
-<td><p>Bitwise left shift => <code class="docutils literal
notranslate"><span class="pre">(expr1</span> <span class="pre"><<</span>
<span class="pre">expr2)</span></code></p></td>
-</tr>
-<tr class="row-even"><td><p>>></p></td>
-<td><p>Bitwise right shift => <code class="docutils literal
notranslate"><span class="pre">(expr1</span> <span class="pre"><<</span>
<span class="pre">expr2)</span></code></p></td>
-</tr>
-</tbody>
-</table>
+</div>
</section>
<section id="conditional-expressions">
<h2>Conditional Expressions<a class="headerlink"
href="#conditional-expressions" title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
-<tr class="row-even"><td><p>coalesce</p></td>
+<tr class="row-even"><td><p>coalesce([value, …])</p></td>
<td><p>Returns the first of its arguments that is not null. Null is returned
only if all arguments are null. It is often used to substitute a default value
for null values when data is retrieved for display.</p></td>
</tr>
-<tr class="row-odd"><td><p>case</p></td>
+<tr class="row-odd"><td><p>case(expr)</br> .when(expr)</br>
.end(),</br>case(expr)</br> .when(expr)</br> .otherwise(expr)</p></td>
<td><p>CASE expression. The expression may chain multiple <code
class="docutils literal notranslate"><span class="pre">when</span></code>
expressions and end with an <code class="docutils literal notranslate"><span
class="pre">end</span></code> or <code class="docutils literal
notranslate"><span class="pre">otherwise</span></code> expression.
Example:</br> <pre><code>case(col(“a”) % lit(3))</br> .when(lit(0),
lit(“A”))</br> .when(lit(1), lit(“B”))</br> .when(lit(2), lit(“C”))</b
[...]
</tr>
-<tr class="row-even"><td><p>nullif</p></td>
+<tr class="row-even"><td><p>nullif(value1, value2)</p></td>
<td><p>Returns a null value if <code class="docutils literal
notranslate"><span class="pre">value1</span></code> equals <code
class="docutils literal notranslate"><span class="pre">value2</span></code>;
otherwise it returns <code class="docutils literal notranslate"><span
class="pre">value1</span></code>. This can be used to perform the inverse
operation of the <code class="docutils literal notranslate"><span
class="pre">coalesce</span></code> expression.</p></td>
</tr>
</tbody>
@@ -782,8 +811,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>String Expressions<a class="headerlink" href="#string-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -884,8 +913,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Array Expressions<a class="headerlink" href="#array-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -974,8 +1003,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Regular Expressions<a class="headerlink" href="#regular-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -992,8 +1021,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Temporal Expressions<a class="headerlink" href="#temporal-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -1028,8 +1057,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Other Expressions<a class="headerlink" href="#other-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -1064,8 +1093,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Aggregate Functions<a class="headerlink" href="#aggregate-functions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -1133,8 +1162,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>Subquery Expressions<a class="headerlink" href="#subquery-expressions"
title="Link to this heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
@@ -1160,8 +1189,8 @@ expressions such as <code class="docutils literal
notranslate"><span class="pre"
<h2>User-Defined Function Expressions<a class="headerlink"
href="#user-defined-function-expressions" title="Link to this
heading">¶</a></h2>
<table class="table">
<thead>
-<tr class="row-odd"><th class="head"><p>Function</p></th>
-<th class="head"><p>Notes</p></th>
+<tr class="row-odd"><th class="head"><p>Syntax</p></th>
+<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
