Skip to content

Docs: Fix MERGE INTO example in Getting Started #14943

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
huaxingao merged 4 commits into from
Dec 30, 2025
+6 −10
Merged

Docs: Fix MERGE INTO example in Getting Started #14943

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cc9f6f4
Docs: Fix MERGE INTO example in Getting Started
varun-lakhyani Dec 29, 2025
fc1eb55
Docs: Fix Getting Started Spark SQL example to be runnable
varun-lakhyani Dec 29, 2025
a4be09d
Apply same documentation fix to Spark 3.4, 4.0, and 4.1 versions
varun-lakhyani Dec 30, 2025
5cb29e7
Retry CI as earlier gave 429
varun-lakhyani Dec 30, 2025
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
8 changes: 6 additions & 2 deletions docs/docs/spark-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ To create your first Iceberg table in Spark, use the `spark-sql` shell or `spark
```sql
-- local is the path-based catalog defined above
CREATE TABLE local.db.table (id bigint, data string) USING iceberg;
CREATE TABLE source (id bigint, data string) USING parquet;
CREATE TABLE updates (id bigint, data string) USING parquet;
```

Iceberg catalogs support the full range of SQL DDL commands, including:
Expand All @@ -76,14 +78,16 @@ Once your table is created, insert data using [`INSERT INTO`](spark-writes.md#in

```sql
INSERT INTO local.db.table VALUES (1, 'a'), (2, 'b'), (3, 'c');
INSERT INTO source VALUES (10, 'd'), (11, 'ee');
INSERT INTO updates VALUES (1, 'x'), (2, 'x'), (4, 'z');
INSERT INTO local.db.table SELECT id, data FROM source WHERE length(data) = 1;
```

Iceberg also adds row-level SQL updates to Spark, [`MERGE INTO`](spark-writes.md#merge-into) and [`DELETE FROM`](spark-writes.md#delete-from):

```sql
MERGE INTO local.db.target t USING (SELECT * FROM updates) u ON t.id = u.id
WHEN MATCHED THEN UPDATE SET t.count = t.count + u.count
MERGE INTO local.db.table t USING (SELECT * FROM updates) u ON t.id = u.id
WHEN MATCHED THEN UPDATE SET t.data = u.data
Copy link
Contributor

@huaxingao huaxingao Dec 29, 2025

Choose a reason for hiding this comment

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

To make this truly runnable (and align with TestRoundTrip’s TODO about the getting-started doc not being runnable), should we change local.db.target → local.db.table and define updates before the MERGE?

Copy link
Contributor Author

@varun-lakhyani varun-lakhyani Dec 29, 2025

Choose a reason for hiding this comment

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

Thanks. Updated the Getting Started doc to use local.db.table instead of local.db.target and added explicit CREATE TABLE and INSERT INTO statements for the source and updates tables to make the example runnable.

WHEN NOT MATCHED THEN INSERT *;
```

Expand Down
2 changes: 0 additions & 2 deletions spark/v3.4/spark-runtime/src/integration/java/org/apache/iceberg/spark/TestRoundTrip.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,6 @@ public void dropTable() {
}

// Run through our Doc's Getting Started Example
// TODO Update doc example so that it can actually be run, modifications were required for this
// test suite to run
@TestTemplate
public void testGettingStarted() throws IOException {
// Creating a table
Expand Down
2 changes: 0 additions & 2 deletions spark/v3.5/spark-runtime/src/integration/java/org/apache/iceberg/spark/TestRoundTrip.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,6 @@ public void dropTable() {
}

// Run through our Doc's Getting Started Example
// TODO Update doc example so that it can actually be run, modifications were required for this
// test suite to run
Copy link
Contributor

@huaxingao huaxingao Dec 30, 2025

Choose a reason for hiding this comment

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

shall we also update 3.4/4.0/4.1?

Copy link
Contributor Author

@varun-lakhyani varun-lakhyani Dec 30, 2025

Choose a reason for hiding this comment

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

Updated. Removed the TODO comments from all Spark versions (3.4, 3.5, 4.0, 4.1).

@TestTemplate
public void testGettingStarted() throws IOException {
// Creating a table
Expand Down
2 changes: 0 additions & 2 deletions spark/v4.0/spark-runtime/src/integration/java/org/apache/iceberg/spark/TestRoundTrip.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,6 @@ public void dropTable() {
}

// Run through our Doc's Getting Started Example
// TODO Update doc example so that it can actually be run, modifications were required for this
// test suite to run
@TestTemplate
public void testGettingStarted() throws IOException {
// Creating a table
Expand Down
2 changes: 0 additions & 2 deletions spark/v4.1/spark-runtime/src/integration/java/org/apache/iceberg/spark/TestRoundTrip.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,6 @@ public void dropTable() {
}

// Run through our Doc's Getting Started Example
// TODO Update doc example so that it can actually be run, modifications were required for this
// test suite to run
@TestTemplate
public void testGettingStarted() throws IOException {
// Creating a table
Expand Down