From 9e609401a5035ab3fc465061682e82b42c63dffd Mon Sep 17 00:00:00 2001
From: Gabor Szarnyas <szarnyasg@gmail.com>
Date: Fri, 3 May 2024 11:12:02 +0200
Subject: [PATCH] Document duplicate key issues when updating lists

Fixes #2811
---
 docs/sql/data_types/list.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/sql/data_types/list.md b/docs/sql/data_types/list.md
index 95244273739..9b845a16697 100644
--- a/docs/sql/data_types/list.md
+++ b/docs/sql/data_types/list.md
@@ -60,6 +60,23 @@ comparing a `NULL` nested value to a non-`NULL` nested value produces a `NULL` r
 Comparing nested value _members_, however, uses the internal nested value rules for `NULL`s,
 and a `NULL` nested value member will compare above a non-`NULL` nested value member.
 
+## Updating Lists
+
+Updates on lists are internally represented as an insert and a delete operation.
+Therefore, updating list values may lead to a duplicate key error on primary/unique keys.
+See the following example:
+
+```sql
+CREATE TABLE tbl (id INTEGER PRIMARY KEY, lst INTEGER[], comment VARCHAR);
+INSERT INTO tbl VALUES (1, [12, 34], 'asd');
+UPDATE tbl SET lst = [56, 78] WHERE id = 1;
+```
+
+```console
+Constraint Error: Duplicate key "id: 1" violates primary key constraint.
+If this is an unexpected constraint violation please double check with the known index limitations section in our documentation (https://duckdb.org/docs/sql/indexes).
+```
+
 ## Functions
 
 See [Nested Functions](../../sql/functions/nested).