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/23 18:18:43 UTC
(datafusion) branch gh-readonly-queue/main/pr-25553-0af758ff2a5690c26f443af4dd0fd2c3de797993 created (now c2e81739c3)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a change to branch gh-readonly-queue/main/pr-25553-0af758ff2a5690c26f443af4dd0fd2c3de797993
in repository https://gitbox.apache.org/repos/asf/datafusion.git
at c2e81739c3 docs: document DELETE and UPDATE in the SQL reference (#25553)
This branch includes the following new commits:
new c2e81739c3 docs: document DELETE and UPDATE in the SQL reference (#25553)
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org
(datafusion) 01/01: docs: document DELETE and UPDATE in the SQL reference (#25553)
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-25553-0af758ff2a5690c26f443af4dd0fd2c3de797993
in repository https://gitbox.apache.org/repos/asf/datafusion.git
commit c2e81739c37c96d01513f8592143ac7ad2d9851b
Author: mck <mc...@apache.org>
AuthorDate: Wed Sep 23 18:18:32 2026 +0000
docs: document DELETE and UPDATE in the SQL reference (#25553)
## Which issue does this PR close?
Documentation follow-up for #19142. Split from #24567 at the reviewer's
request.
## Rationale for this change
The SQL reference does not document `DELETE` or `UPDATE`. SQL users need
their syntax, result format, and table support.
Add syntax, examples, table support, and concise links to known
limitations. Split from #24567
## What changes are included in this PR?
- Add syntax and examples for `DELETE` and `UPDATE`.
- Explain affected-row counts, `NULL` predicates, and assignment
semantics.
- Summarize table support and link to known limitations.
Provider implementation documentation remains in #24567.
## What is the testing strategy for this PR?
`cargo fmt --all`, the documentation formatter.
## Are there any user-facing changes?
SQL reference documentation only.
---
docs/source/user-guide/sql/dml.md | 91 +++++++++++++++++++++++++++++++++++++++
1 file changed, 91 insertions(+)
diff --git a/docs/source/user-guide/sql/dml.md b/docs/source/user-guide/sql/dml.md
index 4934bc2674..cd5947d983 100644
--- a/docs/source/user-guide/sql/dml.md
+++ b/docs/source/user-guide/sql/dml.md
@@ -136,3 +136,94 @@ INSERT INTO <i><b>table_name</i></b> { VALUES ( <i><b>expression</i></b> [, ...]
| 2 |
+-------+
```
+
+## DELETE
+
+Removes rows from a table.
+
+<pre>
+DELETE FROM <i><b>table_name</b></i> [ WHERE <i><b>condition</b></i> ]
+</pre>
+
+`DELETE` returns the number of removed rows in a column named `count`.
+
+If you omit the `WHERE` clause, DataFusion removes all rows.
+
+DataFusion removes a row only if the condition is true for that row. SQL three-valued logic applies: if the condition evaluates to `NULL`, the row remains. For example, `WHERE value > 15` keeps a row with a `NULL` value, because `NULL > 15` is `NULL`.
+
+Not all tables support `DELETE`. See [Table support for DELETE and UPDATE](#table-support-for-delete-and-update).
+
+### Examples
+
+Remove the rows that match a condition:
+
+```sql
+> DELETE FROM target_table WHERE id > 1;
++-------+
+| count |
++-------+
+| 2 |
++-------+
+```
+
+Remove all rows:
+
+```sql
+> DELETE FROM target_table;
++-------+
+| count |
++-------+
+| 3 |
++-------+
+```
+
+## UPDATE
+
+Changes the values of existing rows.
+
+<pre>
+UPDATE <i><b>table_name</b></i> SET <i><b>column</b></i> = <i><b>expression</b></i> [, ...] [ WHERE <i><b>condition</b></i> ]
+</pre>
+
+`UPDATE` returns the number of affected rows in a column named `count`.
+
+If you omit the `WHERE` clause, DataFusion changes all rows. The three-valued logic of `DELETE` also applies here.
+
+Each assignment expression reads the row values from before the statement. `SET a = b, b = a` therefore exchanges the two values.
+
+Not all tables support `UPDATE`. See [Table support for DELETE and UPDATE](#table-support-for-delete-and-update).
+
+### Examples
+
+Set one column in the rows that match a condition:
+
+```sql
+> UPDATE target_table SET name = 'Baz' WHERE id = 2;
++-------+
+| count |
++-------+
+| 1 |
++-------+
+```
+
+Set two columns, one from an expression:
+
+```sql
+> UPDATE target_table SET value = value * 2, name = 'Doubled' WHERE id < 3;
++-------+
+| count |
++-------+
+| 2 |
++-------+
+```
+
+## Table support for DELETE and UPDATE
+
+Not all table providers support `DELETE` and `UPDATE`. In-memory tables created with `CREATE TABLE` support both statements. File-based tables created with `CREATE EXTERNAL TABLE` and views do not. Support for custom table providers depends on the provider.
+
+### Known limitations
+
+- Subqueries in `DELETE` and `UPDATE` conditions can affect unintended rows: [#24654](https://github.com/apache/datafusion/issues/24654).
+- `EXPLAIN DELETE` and `EXPLAIN UPDATE` can modify in-memory tables: [#24656](https://github.com/apache/datafusion/issues/24656).
+- `DELETE` ignores `LIMIT`: [#24998](https://github.com/apache/datafusion/issues/24998).
+- `UPDATE ... FROM` is not supported: [#19950](https://github.com/apache/datafusion/issues/19950).
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org