From a03b57ea79e5062430cb0437f2a26bce7eabe682 Mon Sep 17 00:00:00 2001
From: Johannes Misch <johannes.misch@tenzir.com>
Date: Mon, 25 Aug 2025 12:25:44 +0200
Subject: [PATCH] Document new duplicate key behavior

Companion to https://github.com/tenzir/tenzir/pull/5445
---
 src/partials/operators/ParsingOptions.mdx | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/partials/operators/ParsingOptions.mdx b/src/partials/operators/ParsingOptions.mdx
index 187901d5..d55f0f95 100644
--- a/src/partials/operators/ParsingOptions.mdx
+++ b/src/partials/operators/ParsingOptions.mdx
@@ -1,5 +1,25 @@
 import Base from "../ParsingOptionsBase.mdx";
 
+### Duplicate Keys
+
+If the parser encounters a duplicate key in an event, it will transparently
+upgrade the field to be a list of values instead. If the values are of different
+type, conversions to a common type will be attempted, such as to a common number
+type. Ultimately values will be stringified if they do not share a common type.
+
+For a simple example, consider this JSON file:
+```json title="Example JSON with duplicate key" {2}
+{ "key": 7 }
+{ "key": 0.0, "key": 1 }
+{ "key": 42 }
+```
+The event with a duplicate key has the respective value upgraded to a list:
+```tql {2}
+{ key: 7 }
+{ key: [0.0, 1.0] }
+{ key: 42 }
+```
+
 ### `merge = bool (optional)`
 
 Merges all incoming events into a single schema\* that converges over time. This
@@ -8,4 +28,6 @@ to huge schemas filled with nulls and imprecise results. Use with caution.
 
 \*: In selector mode, only events with the same selector are merged.
 
+In merging mode, a repeated key will always overwrite the previous value.
+
 <Base />