[PR] alarm: clarify queryAlarms entity / layer semantics (doc only) [skywalking-query-protocol]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng opened a new pull request, #158:
URL: https://github.com/apache/skywalking-query-protocol/pull/158

   ## Summary
   
   Doc-only fix to `alarm.graphqls` so the schema text matches how the OAP backend actually filters `queryAlarms`.
   
   ### What was inaccurate
   
   - **Relation-entity match:** the previous doc said a relation entity (`{ServiceRelation, A→B}`) matches alarms 'whether the entity appears as the source or the dest of the relation' — implying `id0 OR id1`. The actual OAP backend uses **strict AND** (`id0=src AND id1=dest`), which makes the relation filter narrow to one specific edge. Operators who want 'any alarm involving service A' should pass the non-relation `{Service A}` entity (which expands to `id0=A OR id1=A`).
   - **Layer match:** the previous doc said 'a service observed under multiple normal layers (e.g., GENERAL + K8S_SERVICE) matches when any one of them is in the list' — implying multi-value storage. The OAP alarm record actually stores ONE layer per row (the alphabetically first when the alarmed service has multiple layers), so a service in `[GENERAL, K8S_SERVICE]` is filed under `GENERAL` and only `layers: [\"GENERAL\"]` matches it.
   
   ### Why doc-only
   
   Both issues are cosmetic — the GraphQL types, names, and arguments are unchanged. The fix replaces the misleading prose so:
   
   - API consumers don't expect broader matches than they get.
   - The single-layer-per-row reality is documented for operators that need it.
   
   The narrowing for relations is a deliberate OAP design choice (per-entity AND/OR semantics in the storage DAO) and shouldn't be changed without breaking the relation-filter contract.
   
   ## No schema breakage
   
   - No type renames, no argument changes, no field removals.
   - Pre-#157 clients (which didn't use `queryAlarms` at all) unaffected.
   - Post-#157 clients keep working; doc just tells them what to expect.
   
   ## Test plan
   
   - [ ] No backend changes needed — text-only fix
   - [ ] Confirm reading the doc top-to-bottom matches the apache/skywalking 11.0.0 behavior
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] alarm: clarify queryAlarms entity / layer semantics (doc only) [skywalking-query-protocol]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng closed pull request #158: alarm: clarify queryAlarms entity / layer semantics (doc only)
URL: https://github.com/apache/skywalking-query-protocol/pull/158


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org