Skip to content

Improve descriptions for X/Y schemas #261474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
markov00 wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Improve descriptions for X/Y schemas #261474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a0740a
Improve descriptions for X/Y schemas
markov00 Apr 7, 2026
a135d9c
Merge branch 'main' into 2026_04_07-better_descriptions_for_x_y
mbondyra Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions ...platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/shared.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,14 +140,20 @@ export function mergeAllMetricsWithChartDimensionSchemaWithStaticOps<T extends P
]);
}

export function mergeAllBucketsWithChartDimensionSchema<T extends Props>(baseSchema: T) {
return schema.oneOf([
bucketDateHistogramOperationSchema.extends(baseSchema),
bucketTermsOperationSchema.extends(baseSchema),
bucketHistogramOperationSchema.extends(baseSchema),
bucketRangesOperationSchema.extends(baseSchema),
bucketFiltersOperationSchema.extends(baseSchema),
]);
export function mergeAllBucketsWithChartDimensionSchema<T extends Props>(
baseSchema: T,
oneOfOptions?: { meta?: { description?: string } }
) {
return schema.oneOf(
[
bucketDateHistogramOperationSchema.extends(baseSchema),
bucketTermsOperationSchema.extends(baseSchema),
bucketHistogramOperationSchema.extends(baseSchema),
bucketRangesOperationSchema.extends(baseSchema),
bucketFiltersOperationSchema.extends(baseSchema),
],
oneOfOptions
);
}

/**
Expand Down
73 changes: 59 additions & 14 deletions src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/xy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -593,24 +593,48 @@ const xyDataLayerSchemaNoESQL = schema.object(
...dataSourceSchema,
...xyDataLayerSharedSchema,
breakdown_by: schema.maybe(
mergeAllBucketsWithChartDimensionSchema({
collapse_by: schema.maybe(collapseBySchema),
color: schema.maybe(colorMappingSchema),
aggregate_first: schema.maybe(
schema.boolean({
meta: { description: 'Whether to aggregate before splitting series' },
})
),
})
mergeAllBucketsWithChartDimensionSchema(
{
collapse_by: schema.maybe(collapseBySchema),
color: schema.maybe(colorMappingSchema),
aggregate_first: schema.maybe(
schema.boolean({
meta: { description: 'Whether to aggregate before splitting series' },
})
),
},
{
meta: {
description:
'Splits each y metric into multiple series by the values of this dimension. For example, breaking down by a host.name field creates one series per host. Unlike x (which defines the domain axis), breakdown_by creates separate visual series within the same chart.',
},
}
)
),
y: schema.arrayOf(
mergeAllMetricsWithChartDimensionSchemaWithRefBasedOps({
axis_id: schema.maybe(yAxisIdReferenceSchema),
color: schema.maybe(staticColorSchema),
}),
{ meta: { description: 'Array of metrics to display on Y-axis' }, maxSize: 100 }
{
meta: {
description:
'Dependent axis (metric): the measured values. Always use y for metrics regardless of chart orientation — chart orientation is controlled by the type field (e.g. bar vs bar_horizontal), not by swapping x and y.',
Copy link
Copy Markdown
Contributor

@mbondyra mbondyra Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, let's check if that works, but I feel like this is a lot of tokens with a description this long. I wonder if only adding "range" and "domain" wouldn't be good enough 😅 I'll try to check tomorrow!

Copy link
Copy Markdown
Contributor Author

@markov00 markov00 Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't even considering token length here, just asked to produce and validate a good description that was non ambigious for an LLM.
I would really not recommend changing the description to reduce the number of tokens just for that, this is not something we evaluate and control. If we need this level of optimization probably we should create a "llm_description" meta that is minimal and just works for LLMs

Copy link
Copy Markdown
Contributor

@mbondyra mbondyra Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I just checked and unfortunately this description doesn't affect the agent action at all 🫠 I tried to tweak it, but looks like nothing works and we have to do it at agent level. Please feel free to merge this, we'll fix it on our end.

},
maxSize: 100,
}
),
x: schema.maybe(
mergeAllBucketsWithChartDimensionSchema(
{},
{
meta: {
description:
'Independent axis (dimension): the variable that data is grouped or bucketed by. Always use x for the dimension regardless of chart orientation — for horizontal bar charts, set type to bar_horizontal instead of swapping x and y.',
},
}
)
),
x: schema.maybe(mergeAllBucketsWithChartDimensionSchema({})),
},
{
meta: {
Expand All @@ -635,7 +659,12 @@ const xyDataLayerSchemaESQL = schema.object(
color: schema.maybe(colorMappingSchema),
collapse_by: schema.maybe(collapseBySchema),
},
{ meta: { description: 'ES|QL column for breakdown' } }
{
meta: {
description:
'Splits each y metric into multiple series by the values of this ES|QL column. For example, breaking down by a host.name column creates one series per host. Unlike x (which defines the domain axis), breakdown_by creates separate visual series within the same chart.',
},
}
)
),
y: schema.arrayOf(
Expand All @@ -646,9 +675,25 @@ const xyDataLayerSchemaESQL = schema.object(
},
{ meta: { description: 'ES|QL column for Y-axis metric' } }
),
{ meta: { description: 'Array of ES|QL columns for Y-axis metrics' }, maxSize: 100 }
{
meta: {
description:
'Dependent axis (metric): the measured values. Always use y for metrics regardless of chart orientation — chart orientation is controlled by the type field (e.g. bar vs bar_horizontal), not by swapping x and y.',
},
maxSize: 100,
}
),
x: schema.maybe(
esqlColumnWithFormatSchema.extends(
{},
{
meta: {
description:
'Independent axis (dimension): the variable that data is grouped or bucketed by. Always use x for the dimension regardless of chart orientation — for horizontal bar charts, set type to bar_horizontal instead of swapping x and y.',
},
}
)
),
x: schema.maybe(esqlColumnWithFormatSchema),
},
{
meta: {
Expand Down
Loading