(skywalking-banyandb) branch main updated: docs: clarify stream element_id query behavior (#1079)

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hanahmily pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-banyandb.git


The following commit(s) were added to refs/heads/main by this push:
     new 798f9cbdf docs: clarify stream element_id query behavior (#1079)
798f9cbdf is described below

commit 798f9cbdffdc5913769fa4a1ff7c6e7607fb8bea
Author: Tanay Paul <14...@users.noreply.github.com>
AuthorDate: Mon Apr 20 18:37:22 2026 +0530

    docs: clarify stream element_id query behavior (#1079)
---
 docs/interacting/bydbctl/query/stream.md | 14 ++++++++++++++
 docs/interacting/client.md               | 11 ++++++++++-
 docs/operation/troubleshooting/query.md  |  4 ++--
 3 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/interacting/bydbctl/query/stream.md b/docs/interacting/bydbctl/query/stream.md
index a373d926d..d7754c782 100644
--- a/docs/interacting/bydbctl/query/stream.md
+++ b/docs/interacting/bydbctl/query/stream.md
@@ -75,6 +75,20 @@ stream:
   updatedAt: null
 ```
 
+## Element identity and deduplication
+
+Each stream element has an internal element identity in addition to the series ID and timestamp.
+
+- If a write request carries `element_id`, BanyanDB derives the element identity from it.
+- If `element_id` is omitted, BanyanDB generates the element identity on the server side.
+
+This affects query results in two ways:
+
+- Two elements with the same entity and timestamp but different element identities are still distinct stream elements, so both may appear in the result.
+- BanyanDB deduplicates query results by element identity during scan and merge. Re-ingesting the same payload without a stable `element_id` creates a new element identity, so the query result treats it as a separate element.
+
+See [Client APIs](../../client.md#stream-element-identity) for the write-side behavior.
+
 ## Examples
 
 The following examples use above schema to show how to query data in a stream and cover some common use cases:
diff --git a/docs/interacting/client.md b/docs/interacting/client.md
index af40db7fe..3675654c2 100644
--- a/docs/interacting/client.md
+++ b/docs/interacting/client.md
@@ -8,4 +8,13 @@ All Protocol Buffer (`.proto`) definitions used by the client are maintained in
 [BanyanDB Client Proto Definitions Repository](https://github.com/apache/skywalking-banyandb-client-proto).
 
 Since version **0.10.0**, BanyanDB introduces **schema-based validation** for all write operations.  
-Each write request must strictly follow the schema definitions defined in the database to ensure data consistency and integrity.
\ No newline at end of file
+Each write request must strictly follow the schema definitions defined in the database to ensure data consistency and integrity.
+
+## Stream element identity
+
+For stream writes, `element_id` is optional.
+
+- If the client sets `element_id`, BanyanDB derives the internal element identity from the group, stream name, and `element_id` value. Use a stable `element_id` when retries or re-sends should refer to the same logical element.
+- If the client omits `element_id`, BanyanDB generates a server-side element ID for that write. This is convenient for append-only ingestion, but repeated writes without a stable `element_id` are treated as different elements.
+
+See [Query Streams](./bydbctl/query/stream.md#element-identity-and-deduplication) for how element identity affects query results.
diff --git a/docs/operation/troubleshooting/query.md b/docs/operation/troubleshooting/query.md
index de9b1ce94..abe084fe7 100644
--- a/docs/operation/troubleshooting/query.md
+++ b/docs/operation/troubleshooting/query.md
@@ -53,8 +53,8 @@ Please refer to the [Troubleshooting No Data Issue](./no-data.md) guide to ident
 
 `Stream`, `Measure` and `Trace` handle duplicate data differently:
 
-- `Stream`: If the same data is ingested multiple times, the `Stream` will store all the data points. The query results will include all the duplicate data points with the same entity and timestamp.
-- `Measure`: If the same data is ingested multiple times, the `Measure` will store the latest data point. It uses a internal `version` field to determine the latest data point.
+- `Stream`: `Stream` stores elements even when they share the same entity and timestamp. Query results are deduplicated by `element_id`, not by timestamp alone. Elements with different `element_id` values remain distinct. If clients omit `element_id`, BanyanDB generates one for each write, so repeated writes without a stable `element_id` appear as separate elements in query results.
+- `Measure`: If the same data is ingested multiple times, the `Measure` will store the latest data point. It uses an internal `version` field to determine the latest data point.
 
 `Measure` data version is determined by: