[ES|QL] Displays The Function License Availability In Our Inline Docs #229961

bartoval · 2025-07-30T13:13:04Z

Summary

This PR is part of #216791

Provide iDocs badges for functions or function-signatures with license

examples:
CATEGORIZE (license at function level)

ST_EXTENT_AGG (licence at signature level)

Note: We don't yet know if there can be signatures with multiple different licenses, but the script supports this possibility
This plus does not bring any disadvantages so it is worth having it ready.

bartoval · 2025-07-30T13:15:58Z

@florent-leborgne
Are these messages correct?

src/platform/packages/shared/kbn-esql-ast/src/definitions/utils/documentation.ts

bartoval · 2025-07-30T13:20:18Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+
+function createLicenseTooltip(license: LicenseInfo): string {
+  let tooltip = i18n.translate('languageDocumentation.licenseRequiredTooltip', {
+    defaultMessage: 'This feature requires {license} license',


Are internationalization files modified automatically? I don't know Mandarin or Japanese

Shame!

They are being taken care of from the translations team!

elasticmachine · 2025-07-30T13:24:14Z

Pinging @elastic/kibana-esql (Team:ESQL)

bartoval · 2025-07-30T14:52:40Z

src/platform/packages/private/kbn-language-documentation/tsconfig.json

    "@kbn/i18n",
    "@kbn/test-jest-helpers",
    "@kbn/shared-ux-markdown",
+    "@kbn/esql-ast",


Do we want to avoid this? I need it to add the right types instead of any

The CI might complain actually, let's see how it goes

So it didnt. Regardless I would like to avoid it to keep the package as simple as possible I think. 🤔 Mostly because you added them only for the script.

As you added it only for the script I think it is ok to create these interfaces again here and only the paths. You mostly want the license property. I don't have a strong opinion but I think if we can avoid the kbn-ast dependency would be better

florent-leborgne · 2025-07-30T16:43:10Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+
+function createLicenseTooltip(license: LicenseInfo): string {
+  let tooltip = i18n.translate('languageDocumentation.licenseRequiredTooltip', {
+    defaultMessage: 'This feature requires {license} license',


Super ideally these sentences would say:
"This feature requires a Platinum subscription."
"This feature requires an Enterprise subscription."

We should use "subscription" instead of "license" (that's the term we use on the website and in the product UI)

It feels a lot more natural with "a" or "an" before the subscription name. Is this possible to add this logic?

Can we put subscription names in title case? (not full caps, just with the first letter capitalized - in the tooltip I mean, I think it's forced to full caps for the badge label anyways)

yes we can. Here the result

stratoula

Looks great, just some small comments about readability and I think I prefer to avoid the kbn-ast dependency for this package

stratoula · 2025-07-31T05:39:06Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_docs.ts

+ * Aggregates licenses from an array of signatures into a map.
+ * The map's key is the license name, and the value is a Set of associated parameter types.
+ */
+function aggregateLicensesFromSignatures(signatures: Signature[]): Map<string, Set<string>> {


Can we move this function and the next one to a utils file? It would be easier to read the script. The getLicenseInfo too with the types too

stratoula · 2025-07-31T05:51:26Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+
+  let tooltip = i18n.translate('languageDocumentation.licenseRequiredTooltip', {
+    defaultMessage:
+      'This feature requires {articleType, select, vowel {an} other {a}} {license} subscription',


So react-intl doesnt handle the indefinite article and we have to do it on our own?

It seems it doesnt :(

I assume this won’t be the only case where we need this. Why don’t we create a utility component based on formatMessage that handles this kind of usage?.

We will use it for ESQL but it could potentially be extended into a more general-purpose component within Kibana.

I’m thinking of something simple—just a few lines—that encapsulates this pattern

<FormattedMessageWithArticleType id="some.message" defaultMessage="This report includes [article]{userType}[/article] and [article]{eventType}[/article]." values={{ userType: 'administrator', eventType: 'error', }} />

with this format we parse [article] and manage the logic

yes I think this is a good idea but as this is a territory of another team let's proceed with this PR as it is for now.

stratoula · 2025-07-31T05:52:11Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+}
+
+// Helper function to get licenses array from either format
+function getLicensesArray(license: MultipleLicenseInfo | undefined): LicenseInfo[] {


Can we also move all these functions inside the utils folder?

stratoula · 2025-07-31T06:04:55Z

src/platform/packages/private/kbn-language-documentation/tsconfig.json

    "@kbn/i18n",
    "@kbn/test-jest-helpers",
    "@kbn/shared-ux-markdown",
+    "@kbn/esql-ast",


So it didnt. Regardless I would like to avoid it to keep the package as simple as possible I think. 🤔 Mostly because you added them only for the script.

As you added it only for the script I think it is ok to create these interfaces again here and only the paths. You mostly want the license property. I don't have a strong opinion but I think if we can avoid the kbn-ast dependency would be better

bartoval · 2025-07-31T09:15:37Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+  }
+
+  let tooltip = i18n.translate('languageDocumentation.licenseRequiredTooltip', {
+    defaultMessage: 'This feature requires {articleType} {license} subscription',


I simplified the logic

florent-leborgne

Copy LGTM, thank you for the changes 🙏

florent-leborgne · 2025-07-31T10:55:14Z

.../packages/private/kbn-language-documentation/src/components/shared/documentation_content.tsx

+
+  if (license.isSignatureSpecific && license?.paramsWithLicense?.length) {
+    tooltip += ` ${i18n.translate('languageDocumentation.licenseParamsNote', {
+      defaultMessage: ' only for specific values: {params}',


Suggested change

defaultMessage: ' only for specific values: {params}',

defaultMessage: ' to use the following values: {params}',

Suggestion, feel free to ignore if you think it doesn't work for the various possible scenarios

👍🏼
added.

elasticmachine · 2025-07-31T15:02:23Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 8bb8af0

Failed CI Steps

FTR Configs #127

Test Failures

[job] [logs] FTR Configs #127 / discover/group3 discover request counts data view mode should send no more than 3 requests (documents + chart + other bucket) when changing to a breakdown field with an other bucket

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
`esql`	128	129	+1
`lens`	1425	1426	+1
`stackAlerts`	275	276	+1
`unifiedSearch`	435	436	+1
total			+4

Async chunks

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

id	before	after	diff
`esql`	257.6KB	261.0KB	+3.3KB
`unifiedSearch`	339.9KB	343.3KB	+3.3KB
total			+6.7KB

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`esql`	9.4KB	9.4KB	+1.0B
`kbnUiSharedDeps-srcJs`	3.8MB	3.8MB	+284.0B
`unifiedSearch`	22.4KB	22.4KB	+26.0B
total			+311.0B

History

cc @bartoval

stratoula

Now it is a beauty and you added tests too 😍 LGTM!

…elastic#229961) ## Summary This PR is part of elastic#216791 Provide iDocs badges for functions or function-signatures with license examples: CATEGORIZE (license at function level) <img width="639" height="459" alt="doc_categorize" src="https://github.com/user-attachments/assets/80abcbd3-f80c-4ff3-9f49-e966390be666" /> ST_EXTENT_AGG (licence at signature level) <img width="704" height="626" alt="doc_st_extent_agg" src="https://github.com/user-attachments/assets/c5ad8db3-92f9-42bb-a9e8-a55101ccb6b4" /> **Note: We don't yet know if there can be signatures with multiple different licenses, but the script supports this possibility** This plus does not bring any disadvantages so it is worth having it ready. --------- Co-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>

bartoval added 2 commits July 30, 2025 10:07

feat: add function license info to idoc

0ad5f9b

refactor: adapt the script to handle multi signature licenses

1cfed46

bartoval self-assigned this Jul 30, 2025

bartoval requested a review from a team as a code owner July 30, 2025 13:13

stratoula changed the title ~~Esql add idoc function license~~ [ES|QL] Display the function license availability in our inline docs Jul 30, 2025

stratoula changed the title ~~[ES|QL] Display the function license availability in our inline docs~~ [ES|QL] Displays the function license availability in our inline docs Jul 30, 2025

bartoval commented Jul 30, 2025

View reviewed changes

src/platform/packages/shared/kbn-esql-ast/src/definitions/utils/documentation.ts Show resolved Hide resolved

bartoval commented Jul 30, 2025

View reviewed changes

bartoval added release_note:fix backport:skip This PR does not require backporting Feature:ES|QL ES|QL related features in Kibana Team:ESQL ES|QL related features in Kibana t// labels Jul 30, 2025

florent-leborgne self-requested a review July 30, 2025 14:10

fix: resolve build errors

6ba0e37

bartoval force-pushed the esql_add_idoc_function_license branch from ebd7e80 to 6ba0e37 Compare July 30, 2025 14:50

bartoval commented Jul 30, 2025

View reviewed changes

florent-leborgne reviewed Jul 30, 2025

View reviewed changes

bartoval and others added 2 commits July 30, 2025 19:27

refactor:add ICU syntax and title case in the tooltip

d66ed6a

Merge branch 'main' into esql_add_idoc_function_license

4f3690b

stratoula reviewed Jul 31, 2025

View reviewed changes

Merge branch 'elastic:main' into esql_add_idoc_function_license

4d318e1

bartoval force-pushed the esql_add_idoc_function_license branch 3 times, most recently from 28ffc5c to aa7c559 Compare July 31, 2025 09:09

bartoval commented Jul 31, 2025

View reviewed changes

fix: resolve PR comments

ca204d8

bartoval force-pushed the esql_add_idoc_function_license branch 2 times, most recently from ebb4f32 to 83ad8f1 Compare July 31, 2025 10:27

bartoval mentioned this pull request Jul 31, 2025

[ES|QL] Check the license + tier and suggest based on it #216791

Closed

9 tasks

florent-leborgne approved these changes Jul 31, 2025

View reviewed changes

remove old package reference

6a636ca

bartoval force-pushed the esql_add_idoc_function_license branch from 83ad8f1 to 6a636ca Compare July 31, 2025 11:02

bartoval added 2 commits July 31, 2025 13:44

Merge branch 'main' into esql_add_idoc_function_license

fb2a8ce

Merge branch 'main' into esql_add_idoc_function_license

8bb8af0

bartoval requested a review from stratoula July 31, 2025 15:04

stratoula approved these changes Jul 31, 2025

View reviewed changes

bartoval merged commit 2f3138b into elastic:main Jul 31, 2025
12 checks passed

kibanamachine added the v9.2.0 label Jul 31, 2025

bartoval changed the title ~~[ES|QL] Displays the function license availability in our inline docs~~ [ES|QL] Displays The Function License Availability In Our Inline Docs Aug 1, 2025

wildemat mentioned this pull request Aug 7, 2025

pr 230826 #231022

Closed

10 tasks

bartoval deleted the esql_add_idoc_function_license branch November 6, 2025 21:04

	defaultMessage: ' only for specific values: {params}',
	defaultMessage: ' to use the following values: {params}',

[ES|QL] Displays The Function License Availability In Our Inline Docs #229961

[ES|QL] Displays The Function License Availability In Our Inline Docs #229961

Uh oh!

Conversation

bartoval commented Jul 30, 2025

Summary

Uh oh!

bartoval commented Jul 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Jul 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florent-leborgne Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stratoula left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartoval Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartoval Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florent-leborgne left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Jul 31, 2025

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

Module Count

Async chunks

Page load bundle

History

Uh oh!

stratoula left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

florent-leborgne Jul 30, 2025 •

edited

Loading

bartoval Jul 31, 2025 •

edited

Loading

bartoval Jul 31, 2025 •

edited

Loading