You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/09/08 22:54:50 UTC
(datafusion) branch asf-site updated: Publish built docs triggered by c29363fc05d08848ad99f53b2b50856603ff39ed
This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 1ee2963e6d Publish built docs triggered by c29363fc05d08848ad99f53b2b50856603ff39ed
1ee2963e6d is described below
commit 1ee2963e6d2191c717797620feaf066ab408c2a0
Author: github-actions[bot] <gi...@users.noreply.github.com>
AuthorDate: Tue Sep 8 22:54:45 2026 +0000
Publish built docs triggered by c29363fc05d08848ad99f53b2b50856603ff39ed
---
.../library-user-guide/upgrading/56.0.0.md.txt | 30 ++++++++++++++++++++++
library-user-guide/upgrading/56.0.0.html | 27 +++++++++++++++++++
searchindex.js | 2 +-
3 files changed, 58 insertions(+), 1 deletion(-)
diff --git a/_sources/library-user-guide/upgrading/56.0.0.md.txt b/_sources/library-user-guide/upgrading/56.0.0.md.txt
index 61940bf726..8de2abc5a0 100644
--- a/_sources/library-user-guide/upgrading/56.0.0.md.txt
+++ b/_sources/library-user-guide/upgrading/56.0.0.md.txt
@@ -225,6 +225,36 @@ The output type of the `floor` and `ceil` UDFs has been changed from the exact i
Change the expected type or wrap the expression in `CAST`. It's recommended to avoid relying on decimal's exact precision and scale.
+### `map_extract` / `element_at` return an empty list for absent keys
+
+`map_extract` (and its alias `element_at`) previously returned a single-element
+list containing `NULL` when the key was not present in the map. It now returns
+an empty list, matching the documented behavior and DuckDB. Two related cases
+changed at the same time, also matching DuckDB:
+
+- A `NULL` map input now yields `NULL` instead of `[NULL]`.
+- A `NULL` lookup key now yields `[]` instead of `[NULL]`.
+
+A key that is present with a `NULL` value still returns `[NULL]`, so absent
+keys and `NULL` values are now distinguishable.
+
+**Migration guide:**
+
+```sql
+-- Before
+SELECT map_extract(MAP {'a': 1}, 'missing'); -- [NULL]
+
+-- After
+SELECT map_extract(MAP {'a': 1}, 'missing'); -- []
+```
+
+Expressions that assumed the result always has exactly one element, for
+example by checking its length, unnesting it, or comparing it to `[NULL]`,
+should treat an empty list as the absent-key case instead.
+
+See [issue #24981](https://github.com/apache/datafusion/issues/24981) and
+[issue #24983](https://github.com/apache/datafusion/issues/24983) for details.
+
### `DataFrame::from_columns` accepts `IntoIterator`
`DataFrame::from_columns` now accepts any `IntoIterator<Item = (&str, ArrayRef)>`
diff --git a/library-user-guide/upgrading/56.0.0.html b/library-user-guide/upgrading/56.0.0.html
index a44cd99142..ec2fffe8a0 100644
--- a/library-user-guide/upgrading/56.0.0.html
+++ b/library-user-guide/upgrading/56.0.0.html
@@ -637,6 +637,32 @@ terminal provider instead (the walk falls back on its own).</p></li>
<p><strong>Migration guide:</strong></p>
<p>Change the expected type or wrap the expression in <code class="docutils literal notranslate"><span class="pre">CAST</span></code>. It’s recommended to avoid relying on decimal’s exact precision and scale.</p>
</section>
+<section id="map-extract-element-at-return-an-empty-list-for-absent-keys">
+<h3><code class="docutils literal notranslate"><span class="pre">map_extract</span></code> / <code class="docutils literal notranslate"><span class="pre">element_at</span></code> return an empty list for absent keys<a class="headerlink" href="#map-extract-element-at-return-an-empty-list-for-absent-keys" title="Link to this heading">#</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">map_extract</span></code> (and its alias <code class="docutils literal notranslate"><span class="pre">element_at</span></code>) previously returned a single-element
+list containing <code class="docutils literal notranslate"><span class="pre">NULL</span></code> when the key was not present in the map. It now returns
+an empty list, matching the documented behavior and DuckDB. Two related cases
+changed at the same time, also matching DuckDB:</p>
+<ul class="simple">
+<li><p>A <code class="docutils literal notranslate"><span class="pre">NULL</span></code> map input now yields <code class="docutils literal notranslate"><span class="pre">NULL</span></code> instead of <code class="docutils literal notranslate"><span class="pre">[NULL]</span></code>.</p></li>
+<li><p>A <code class="docutils literal notranslate"><span class="pre">NULL</span></code> lookup key now yields <code class="docutils literal notranslate"><span class="pre">[]</span></code> instead of <code class="docutils literal notranslate"><span class="pre">[NULL]</span></code>.</p></li>
+</ul>
+<p>A key that is present with a <code class="docutils literal notranslate"><span class="pre">NULL</span></code> value still returns <code class="docutils literal notranslate"><span class="pre">[NULL]</span></code>, so absent
+keys and <code class="docutils literal notranslate"><span class="pre">NULL</span></code> values are now distinguishable.</p>
+<p><strong>Migration guide:</strong></p>
+<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="c1">-- Before</span>
+<span class="k">SELECT</span><span class="w"> </span><span class="n">map_extract</span><span class="p">(</span><span class="k">MAP</span><span class="w"> </span><span class="err">{</span><span class="s1">'a'</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="err">}</span><span class="p">,</span><span class="w"> </span><span class="s1">'missing'</span><span class="p">);</span><span class="w"> </span><span class="c1">-- [NULL]</span>
+
+<span class="c1">-- After</span>
+<span class="k">SELECT</span><span class="w"> </span><span class="n">map_extract</span><span class="p">(</span><span class="k">MAP</span><span class="w"> </span><span class="err">{</span><span class="s1">'a'</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="err">}</span><span class="p">,</span><span class="w"> </span><span class="s1">'missing'</span><span class="p">);</span><span class="w"> </span><span class="c1">-- []</span>
+</pre></div>
+</div>
+<p>Expressions that assumed the result always has exactly one element, for
+example by checking its length, unnesting it, or comparing it to <code class="docutils literal notranslate"><span class="pre">[NULL]</span></code>,
+should treat an empty list as the absent-key case instead.</p>
+<p>See <a class="reference external" href="https://github.com/apache/datafusion/issues/24981">issue #24981</a> and
+<a class="reference external" href="https://github.com/apache/datafusion/issues/24983">issue #24983</a> for details.</p>
+</section>
<section id="dataframe-from-columns-accepts-intoiterator">
<h3><code class="docutils literal notranslate"><span class="pre">DataFrame::from_columns</span></code> accepts <code class="docutils literal notranslate"><span class="pre">IntoIterator</span></code><a class="headerlink" href="#dataframe-from-columns-accepts-intoiterator" title="Link to this heading">#</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">DataFrame::from_columns</span></code> now accepts any <code class="docutils literal notranslate"><span class="pre">IntoIterator<Item</span> <span class="pre">=</span> <span class="pre">(&str,</span> <span class="pre">ArrayRef)></span></code>
@@ -718,6 +744,7 @@ to be updated to account for the new generic API.</p>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#defaultstatisticsprovider-is-deprecated"><code class="docutils literal notranslate"><span class="pre">DefaultStatisticsProvider</span></code> is deprecated</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#statisticsregistry-compute-and-compute-base-are-deprecated"><code class="docutils literal notranslate"><span class="pre">StatisticsRegistry::compute</span></code> and <code class="docutils literal notranslate"><span class="pre">compute_base</span></code> are deprecated</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#api-change-for-floor-and-ceil-udf">API change for <code class="docutils literal notranslate"><span class="pre">floor</span></code> and <code class="docutils literal notranslate"><span class="pre">ceil</span></code> UDF</a></li>
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#map-extract-element-at-return-an-empty-list-for-absent-keys"><code class="docutils literal notranslate"><span class="pre">map_extract</span></code> / <code class="docutils literal notranslate"><span class="pre">element_at</span></code> return an empty list for absent keys</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dataframe-from-columns-accepts-intoiterator"><code class="docutils literal notranslate"><span class="pre">DataFrame::from_columns</span></code> accepts <code class="docutils literal notranslate"><span class="pre">IntoIterator</span></code></a></li>
</ul>
</li>
diff --git a/searchindex.js b/searchindex.js
index c0ddf88f9e..82fb87aabf 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Search.setIndex({"alltitles":{"!=":[[77,"op-neq"]],"!~":[[77,"op-re-not-match"]],"!~*":[[77,"op-re-not-match-i"]],"!~~":[[77,"id19"]],"!~~*":[[77,"id20"]],"#":[[77,"op-bit-xor"]],"%":[[77,"op-modulo"]],"&":[[77,"op-bit-and"]],"(relation, name) tuples in logical fields and logical columns are unique":[[16,"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]],"*":[[77,"op-multiply"]],"+":[[77,"op-plus"]],"-":[[77,"op-minus"]],"/":[[77,"op-divide"]],"1. Array Literal Con [...]
\ No newline at end of file
+Search.setIndex({"alltitles":{"!=":[[77,"op-neq"]],"!~":[[77,"op-re-not-match"]],"!~*":[[77,"op-re-not-match-i"]],"!~~":[[77,"id19"]],"!~~*":[[77,"id20"]],"#":[[77,"op-bit-xor"]],"%":[[77,"op-modulo"]],"&":[[77,"op-bit-and"]],"(relation, name) tuples in logical fields and logical columns are unique":[[16,"relation-name-tuples-in-logical-fields-and-logical-columns-are-unique"]],"*":[[77,"op-multiply"]],"+":[[77,"op-plus"]],"-":[[77,"op-minus"]],"/":[[77,"op-divide"]],"1. Array Literal Con [...]
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org