From 63cc7e585874897c14bd525c32fc48207abbf6ee Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 9 Jul 2026 15:47:58 -0700 Subject: [PATCH] Clarify DB batch operation and collection notes --- docs/db/cassandra.md | 5 +++-- docs/db/cosmosdb.md | 5 +++-- docs/db/database-metrics.md | 20 ++++++++++++-------- docs/db/database-spans.md | 10 ++++++---- docs/registry/attributes/db.md | 10 ++++++---- model/db/registry.yaml | 10 ++++++---- 6 files changed, 36 insertions(+), 24 deletions(-) diff --git a/docs/db/cassandra.md b/docs/db/cassandra.md index f91be8b0ff..c48212da61 100644 --- a/docs/db/cassandra.md +++ b/docs/db/cassandra.md @@ -83,8 +83,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. diff --git a/docs/db/cosmosdb.md b/docs/db/cosmosdb.md index cc4b655248..2fa685c1b3 100644 --- a/docs/db/cosmosdb.md +++ b/docs/db/cosmosdb.md @@ -403,8 +403,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. diff --git a/docs/db/database-metrics.md b/docs/db/database-metrics.md index 7e4e7280dd..5801a0a035 100644 --- a/docs/db/database-metrics.md +++ b/docs/db/database-metrics.md @@ -104,8 +104,9 @@ The collection name SHOULD NOT be extracted from `db.query.text`, when the database system supports query text with multiple collections in non-batch operations. -For batch operations, if the individual operations are known to have the same -collection name then that collection name SHOULD be used. +For batch operations, when the individual collection names are known to be the same +(without extracting them from `db.query.text`; see above), +that collection name SHOULD be used. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using `|` as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. @@ -123,8 +124,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. @@ -293,8 +295,9 @@ The collection name SHOULD NOT be extracted from `db.query.text`, when the database system supports query text with multiple collections in non-batch operations. -For batch operations, if the individual operations are known to have the same -collection name then that collection name SHOULD be used. +For batch operations, when the individual collection names are known to be the same +(without extracting them from `db.query.text`; see above), +that collection name SHOULD be used. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using `|` as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. @@ -312,8 +315,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. diff --git a/docs/db/database-spans.md b/docs/db/database-spans.md index 2309038595..3f9f20c209 100644 --- a/docs/db/database-spans.md +++ b/docs/db/database-spans.md @@ -141,8 +141,9 @@ The collection name SHOULD NOT be extracted from `db.query.text`, when the database system supports query text with multiple collections in non-batch operations. -For batch operations, if the individual operations are known to have the same -collection name then that collection name SHOULD be used. +For batch operations, when the individual collection names are known to be the same +(without extracting them from `db.query.text`; see above), +that collection name SHOULD be used. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using `|` as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. @@ -160,8 +161,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. diff --git a/docs/registry/attributes/db.md b/docs/registry/attributes/db.md index 8cdf828c58..11e7002321 100644 --- a/docs/registry/attributes/db.md +++ b/docs/registry/attributes/db.md @@ -37,8 +37,9 @@ The collection name SHOULD NOT be extracted from `db.query.text`, when the database system supports query text with multiple collections in non-batch operations. -For batch operations, if the individual operations are known to have the same -collection name then that collection name SHOULD be used. +For batch operations, when the individual collection names are known to be the same +(without extracting them from `db.query.text`; see above), +that collection name SHOULD be used. **[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated from the most general to the most specific namespace component, using `|` as a separator between the components. Any missing components (and their associated separators) SHOULD be omitted. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. @@ -77,8 +78,9 @@ in non-batch operations. If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. -For batch operations, if the individual operations are known to have the same operation name -then that operation name SHOULD be used prepended by `BATCH `, +For batch operations, when the individual operation names are known to be the same +(without extracting them from `db.query.text`; see above), +that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. diff --git a/model/db/registry.yaml b/model/db/registry.yaml index 3943ce09f1..428013414a 100644 --- a/model/db/registry.yaml +++ b/model/db/registry.yaml @@ -17,8 +17,9 @@ groups: when the database system supports query text with multiple collections in non-batch operations. - For batch operations, if the individual operations are known to have the same - collection name then that collection name SHOULD be used. + For batch operations, when the individual collection names are known to be the same + (without extracting them from `db.query.text`; see above), + that collection name SHOULD be used. examples: ["public.users", "customers"] - id: db.namespace type: string @@ -52,8 +53,9 @@ groups: If spaces can occur in the operation name, multiple consecutive spaces SHOULD be normalized to a single space. - For batch operations, if the individual operations are known to have the same operation name - then that operation name SHOULD be used prepended by `BATCH `, + For batch operations, when the individual operation names are known to be the same + (without extracting them from `db.query.text`; see above), + that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. examples: ["findAndModify", "HMSET", "SELECT"]