[SigEvents] Add description to KI (Knowledge Indicators) queries by tonyghiani · Pull Request #257457 · elastic/kibana

tonyghiani · 2026-03-12T15:48:39Z

📓 Summary

This PR adds a description field to significant event queries so that each query carries a natural-language explanation of what it detects and why it matters. The LLM now generates descriptions alongside queries during the AI generation flow, and users can view and edit descriptions through the manual creation form, the generated event preview, and the discovery query details flyout.

Existing queries without a description are migrated on read via the storage adapter's migrateSource callback, which back-fills an empty string.

🧪 Testing

Create a significant event manually via the stream detail flyout and verify the description field appears, can be filled in, and is persisted after save.
Trigger AI generation and confirm generated queries include descriptions visible in the expanded preview; edit a description and verify the change is saved.
Open an existing query (created before this change) in the discovery details flyout and confirm it shows an empty description placeholder without errors; edit and save a description from there.

Summary by CodeRabbit

Release Notes

New Features
- Added description field to queries throughout the system, allowing users to provide contextual information about what each query detects and why it matters.
- Enabled editing and viewing of query descriptions in UI components including forms, flyouts, and detail panels.

elasticmachine · 2026-03-12T15:48:45Z

Pinging @elastic/actionable-obs-team (Team:actionable-obs)

…:tonyghiani/kibana into feat/add-description-to-query-generation

ruflin

Did a manual test and works as expected.

coderabbitai · 2026-03-13T18:58:14Z

📝 Walkthrough

Walkthrough

The PR adds a description string field to the significant events/queries system across OpenAPI schemas, TypeScript types, server-side storage and query handling, and UI components, making it required in the AI generation schema while optional in base query definitions and storage migrations.

Changes

Cohort / File(s)	Summary
OpenAPI Documentation `oas_docs/output/kibana.yaml`, `oas_docs/output/kibana.serverless.yaml`	Added description field to multiple object schemas within path definitions at various nesting levels.
Type & Schema Definitions `x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/generate_significant_events.ts`, `x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/prompt.ts`, `x-pack/platform/packages/shared/kbn-streams-schema/src/api/significant_events/index.ts`, `x-pack/platform/packages/shared/kbn-streams-schema/src/queries/index.ts`	Added required description field to Query interface and GeneratedSignificantEventQuery, made optional in StreamQueryBase schema, and updated AI prompt schema to include description as a required field.
Prompt & Task Documentation `x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/system_prompt.text`, `x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/task_description.text`	Updated documentation and examples to describe the new description field requirement for queries, including usage guidelines.
Server Field Constants & Storage `x-pack/platform/plugins/shared/streams/server/lib/streams/assets/fields.ts`, `x-pack/platform/plugins/shared/streams/server/lib/streams/assets/storage_settings.ts`	Added QUERY_DESCRIPTION constant and integrated it into storage schema as a text field.
Server Query Handling `x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_client.ts`, `x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_service.ts`, `x-pack/platform/plugins/shared/streams/server/lib/significant_events/generate_significant_events.ts`	Implemented description field mapping in storage/in-memory conversion, added migration back-fill logic, and propagated description in generated query results.
Server API & Task Integration `x-pack/platform/plugins/shared/streams/server/lib/tasks/task_definitions/onboarding.ts`, `x-pack/platform/plugins/shared/streams/server/routes/queries/route.ts`	Added description field to persisted query payloads during generation and upsert operations.
UI Components `x-pack/platform/plugins/shared/streams_app/public/components/significant_events_discovery/components/queries_table/query_details_flyout.tsx`, `x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/add_significant_event_flyout.tsx`, `x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/generated_flow_form/generated_event_preview.tsx`, `x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/manual_flow_form/manual_flow_form.tsx`	Added description field to query details flyout, manually created event forms, and generated preview UI with text area inputs for editing and display.
Tests `x-pack/platform/test/api_integration_deployment_agnostic/apis/streams/queries.ts`, `x-pack/platform/test/api_integration_deployment_agnostic/apis/streams/significant_events.ts`	Updated test objects to include empty description field in query assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

[Streams] Add field descriptions and documentation-only field overrides #255136: Directly related feature work adding description property to OpenAPI schemas, stream query types, storage wiring, and UI components across the same codebase.
Streams rally track: Set up streams through Kibana #254747: Related through modification of the same streams server query handling code (query_service.ts, storage, and migrations).

Suggested labels

Team:obs-onboarding, Feature:Streams

Suggested reviewers

flash1293
diogolima-elastic
mohamedhamed-ahmed

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a description field to significant event queries (KI queries), which aligns directly with the changeset across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

📝 Coding Plan

Generate coding plan for human review comments

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (2)

x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_service.ts (1)

112-115: Harden description migration to normalize invalid values, not only missing keys.

Using in alone skips cases where query.description exists but is null/non-string.

Suggested hardening

-          if (!(QUERY_DESCRIPTION in migrated)) {
+          if (typeof migrated[QUERY_DESCRIPTION] !== 'string') {
             migrated = { ...migrated, [QUERY_DESCRIPTION]: '' };
           }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_service.ts`
around lines 112 - 115, The migration should normalize invalid description
values, not only add missing keys: replace the current check using "in" with a
guard that sets migrated[QUERY_DESCRIPTION] to '' whenever its type is not a
string (covers undefined, null, and non-string values); update the code around
the migrated object (the block referencing QUERY_DESCRIPTION and the local
variable migrated) to coerce any non-string description to an empty string.

x-pack/platform/plugins/shared/streams/server/routes/queries/route.ts (1)

101-103: Default description during upsert writes to keep stored shape consistent.

If omitted by older callers, this currently persists sparse docs and defers normalization to migration.

Suggested write-side default

-      description: body.description,
+      description: body.description ?? '',

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@x-pack/platform/plugins/shared/streams/server/routes/queries/route.ts` around
lines 101 - 103, Upsert handler in route.ts is persisting documents without a
description when body.description is omitted; change the write to default
description to an empty string so stored docs keep a consistent shape by writing
description: body.description ?? '' alongside title and esql (locate the
upsert/create handler that constructs the object with title, description, esql
using the body variable).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In
`@x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_service.ts`:
- Around line 112-115: The migration should normalize invalid description
values, not only add missing keys: replace the current check using "in" with a
guard that sets migrated[QUERY_DESCRIPTION] to '' whenever its type is not a
string (covers undefined, null, and non-string values); update the code around
the migrated object (the block referencing QUERY_DESCRIPTION and the local
variable migrated) to coerce any non-string description to an empty string.

In `@x-pack/platform/plugins/shared/streams/server/routes/queries/route.ts`:
- Around line 101-103: Upsert handler in route.ts is persisting documents
without a description when body.description is omitted; change the write to
default description to an empty string so stored docs keep a consistent shape by
writing description: body.description ?? '' alongside title and esql (locate the
upsert/create handler that constructs the object with title, description, esql
using the body variable).

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 78261a9c-225b-49a1-b5bb-3d8b6d3a3231

📥 Commits

Reviewing files that changed from the base of the PR and between 78e3709 and 7f93291.

📒 Files selected for processing (21)

oas_docs/output/kibana.serverless.yaml
oas_docs/output/kibana.yaml
x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/generate_significant_events.ts
x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/prompt.ts
x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/system_prompt.text
x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/task_description.text
x-pack/platform/packages/shared/kbn-streams-schema/src/api/significant_events/index.ts
x-pack/platform/packages/shared/kbn-streams-schema/src/queries/index.ts
x-pack/platform/plugins/shared/streams/server/lib/significant_events/generate_significant_events.ts
x-pack/platform/plugins/shared/streams/server/lib/streams/assets/fields.ts
x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_client.ts
x-pack/platform/plugins/shared/streams/server/lib/streams/assets/query/query_service.ts
x-pack/platform/plugins/shared/streams/server/lib/streams/assets/storage_settings.ts
x-pack/platform/plugins/shared/streams/server/lib/tasks/task_definitions/onboarding.ts
x-pack/platform/plugins/shared/streams/server/routes/queries/route.ts
x-pack/platform/plugins/shared/streams_app/public/components/significant_events_discovery/components/queries_table/query_details_flyout.tsx
x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/add_significant_event_flyout.tsx
x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/generated_flow_form/generated_event_preview.tsx
x-pack/platform/plugins/shared/streams_app/public/components/stream_detail_significant_events_view/add_significant_event_flyout/manual_flow_form/manual_flow_form.tsx
x-pack/platform/test/api_integration_deployment_agnostic/apis/streams/queries.ts
x-pack/platform/test/api_integration_deployment_agnostic/apis/streams/significant_events.ts

x-pack/platform/packages/shared/kbn-streams-ai/src/significant_events/prompt.ts

x-pack/platform/packages/shared/kbn-streams-schema/src/queries/index.ts

...ic/components/significant_events_discovery/components/queries_table/query_details_flyout.tsx

cesco-f

LGTM

elasticmachine · 2026-03-16T09:40:20Z

⏳ Build in-progress, with failures

Buildkite Build
Commit: 05cb82c

Failed CI Steps

Check OAS Snapshot

History

elasticmachine · 2026-03-16T12:54:59Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: febced0

Failed CI Steps

FTR Configs #111

Test Failures

[job] [logs] FTR Configs #111 / Endpoint plugin @ess @serverless @skipInServerlessMKI When attempting to call an endpoint api "after all" hook in "@ess @serverless @skipInServerlessMKI When attempting to call an endpoint api"

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/streams-schema`	314	315	+1

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
`datasetQuality`	569.4KB	569.4KB	+50.0B
`streamsApp`	1.8MB	1.8MB	+1.8KB
total			+1.8KB

Unknown metric groups

API count

id	before	after	diff
`@kbn/streams-schema`	356	357	+1

History

…7457) ## 📓 Summary This PR adds a `description` field to significant event queries so that each query carries a natural-language explanation of what it detects and why it matters. The LLM now generates descriptions alongside queries during the AI generation flow, and users can view and edit descriptions through the manual creation form, the generated event preview, and the discovery query details flyout. Existing queries without a description are migrated on read via the storage adapter's `migrateSource` callback, which back-fills an empty string. ## 🧪 Testing - Create a significant event manually via the stream detail flyout and verify the description field appears, can be filled in, and is persisted after save. - Trigger AI generation and confirm generated queries include descriptions visible in the expanded preview; edit a description and verify the change is saved. - Open an existing query (created before this change) in the discovery details flyout and confirm it shows an empty description placeholder without errors; edit and save a description from there.  ## Summary by CodeRabbit ## Release Notes * **New Features** * Added description field to queries throughout the system, allowing users to provide contextual information about what each query detects and why it matters. * Enabled editing and viewing of query descriptions in UI components including forms, flyouts, and detail panels.  --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Nicolas Ruflin <ruflin@elastic.co>

…stic#257457) ## 📓 Summary This PR adds a `description` field to significant event queries so that each query carries a natural-language explanation of what it detects and why it matters. The LLM now generates descriptions alongside queries during the AI generation flow, and users can view and edit descriptions through the manual creation form, the generated event preview, and the discovery query details flyout. Existing queries without a description are migrated on read via the storage adapter's `migrateSource` callback, which back-fills an empty string. ## 🧪 Testing - Create a significant event manually via the stream detail flyout and verify the description field appears, can be filled in, and is persisted after save. - Trigger AI generation and confirm generated queries include descriptions visible in the expanded preview; edit a description and verify the change is saved. - Open an existing query (created before this change) in the discovery details flyout and confirm it shows an empty description placeholder without errors; edit and save a description from there.  ## Summary by CodeRabbit ## Release Notes * **New Features** * Added description field to queries throughout the system, allowing users to provide contextual information about what each query detects and why it matters. * Enabled editing and viewing of query descriptions in UI components including forms, flyouts, and detail panels.  --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Nicolas Ruflin <ruflin@elastic.co>

tonyghiani added 2 commits March 12, 2026 14:56

feat(sig-events): add query description logic

ab2faf8

feat(sig-events): add query description in UI

022a359

tonyghiani requested review from a team as code owners March 12, 2026 15:48

tonyghiani and others added 3 commits March 12, 2026 15:51

refactor(sig-events): move description into query base

e57b233

refactor(sig-events): remove duplicate form label

86defb4

Changes from make api-docs

274d692

elastic-vault-github-plugin-prod bot requested a review from a team as a code owner March 12, 2026 16:16

florent-leborgne requested a review from mdbirnstiehl March 12, 2026 16:41

mdbirnstiehl approved these changes Mar 12, 2026

View reviewed changes

tonyghiani added 3 commits March 12, 2026 17:57

refactor(sig-events): fix test

eb5098c

Merge branch 'feat/add-description-to-query-generation' of github.com…

543709c

…:tonyghiani/kibana into feat/add-description-to-query-generation

refactor(sig-events): fix test

26f870e

ruflin added the Team:SigEvents Project team working on Significant Events label Mar 13, 2026

ruflin approved these changes Mar 13, 2026

View reviewed changes

Merge branch 'main' into feat/add-description-to-query-generation

7f93291

coderabbitai bot reviewed Mar 13, 2026

View reviewed changes

tonyghiani added 4 commits March 15, 2026 23:39

Merge branch 'main' into feat/add-description-to-query-generation

645f87e

refactor(sig-events): fix test

ce90d6a

refactor(sig-events): set default description

7cdc457

refactor(sig-events): set default description

18f9a4d

cesco-f reviewed Mar 16, 2026

View reviewed changes

tonyghiani added 2 commits March 16, 2026 10:24

refactor(sig-events): address pr comments

db56784

Merge branch 'main' into feat/add-description-to-query-generation

05cb82c

cesco-f approved these changes Mar 16, 2026

View reviewed changes

Changes from make api-docs

e2a6d67

tonyghiani and others added 6 commits March 16, 2026 10:44

Merge branch 'main' into feat/add-description-to-query-generation

a35a665

refactor(sig-events): minor default changes

9d14d07

Changes from node scripts/eslint_all_files --no-cache --fix

2305e0f

refactor(sig-events): type checks

dc2c949

Merge branch 'main' into feat/add-description-to-query-generation

297f5fd

refactor(sig-events): test

febced0

tonyghiani merged commit 521a5ff into elastic:main Mar 16, 2026
18 checks passed

tonyghiani deleted the feat/add-description-to-query-generation branch March 16, 2026 13:29

kibanamachine added the v9.4.0 label Mar 16, 2026

coderabbitai bot mentioned this pull request Mar 17, 2026

[SigEvents][Evals] Tighten existing evaluators and rename KI/rule terminology #258209

Merged

3 tasks

Conversation

tonyghiani commented Mar 12, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📓 Summary

🧪 Testing

Summary by CodeRabbit

Release Notes

Uh oh!

elasticmachine commented Mar 12, 2026

Uh oh!

ruflin left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cesco-f left a comment

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Mar 16, 2026

⏳ Build in-progress, with failures

Failed CI Steps

History

Uh oh!

elasticmachine commented Mar 16, 2026

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

Public APIs missing comments

Async chunks

API count

History

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

tonyghiani commented Mar 12, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 13, 2026 •

edited

Loading