Repository navigation
docs: add custom backends guide for AI Grid and Chart - #6713
tomivirkki wants to merge 3 commits into
Conversation
Describe executeQuery(String, QueryPage) and count(String), which the AI-powered Grid uses to load rows lazily, and what their default implementations do. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Show how to give the LLM a SQL view of a REST API, a service, or files: through an Apache Calcite adapter or a copy of the data in a database, and how to connect either one to a DatabaseProvider. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
vaadin-review-bot
left a comment
There was a problem hiding this comment.
Reviewed the changes — left 4 comments.
| Finding | |
|---|---|
| 💬 | The guide never shows how the Calcite connection properties reach the calciteDataSource the provider is built from |
The grid already renders java.sql.Date and Timestamp, so the stated reason for converting them is wrong |
|
| 📐 | The page never says the Grid and Chart controllers require a commercial subscription |
| 🗂️ | Threading, concurrency and serialization facts about DatabaseProvider sit only in this guide, not in the reference |
| * Convert JDBC date values to [classname]`LocalDate` and timestamp values to [classname]`LocalDateTime` for the grid's date renderers. | ||
| * Relay useful SQL parse and validation errors in a [classname]`ToolException` so the LLM can correct its query. Calcite reports them as a [classname]`SqlParseException` or a [classname]`CalciteContextException` in the cause chain of the [classname]`SQLException`. Keep row values and backend details out of those messages, and use a generic message for other failures. The message of the [classname]`SQLException` itself can include the error text of your backend, so don't relay it as it is. | ||
|
|
||
| For example, these connection properties accommodate the names and the SQL that the LLM and the grid may use. Apply them when creating the Calcite connection alongside the adapter's configuration: |
There was a problem hiding this comment.
💬 The guide never shows how the Calcite connection properties reach the calciteDataSource the provider is built from
The page says "Apply them when creating the Calcite connection alongside the adapter's configuration" and shows a Properties object, but the next section jumps to new CalciteDatabaseProvider(calciteDataSource) with "a DataSource configured for Calcite". Calcite has no DataSource of its own, so the reader is left to work out the bridge: DriverManager.getConnection("jdbc:calcite:...", properties), the same settings as connect-string parameters in the JDBC URL, or a pool's dataSourceProperties.
The intro scopes adapter configuration out to Calcite's documentation, but this step is the Vaadin-side wiring the guide claims to own. One sentence naming the URL form, or a line that creates the connection from the properties, closes the gap.
custom-backends.adoc:96 · clarity
| * LLMs often use SQL keywords such as `value` or `year` as column aliases. If your parser configuration allows it, add `calcite-babel` and select Calcite's Babel parser to accept more such names. | ||
| * LLMs also group by a column alias or position and write `!=`, which Calcite rejects by default. Calcite also pads the string literals of a `CASE` or `UNION` with spaces to the same length, so such a label no longer equals a column value. The `conformance=MYSQL_5` setting accepts that SQL and doesn't pad the literals. | ||
| * Remove a trailing semicolon before running a query. Calcite rejects it, and the chart passes the LLM's SQL to [methodname]`executeQuery(String sql)` unchanged. | ||
| * Convert JDBC date values to [classname]`LocalDate` and timestamp values to [classname]`LocalDateTime` for the grid's date renderers. |
There was a problem hiding this comment.
java.sql.Date and Timestamp, so the stated reason for converting them is wrong
Convert JDBC date values to
LocalDateand timestamp values toLocalDateTimefor the grid's date renderers.
GridRenderer.addColumn() picks LocalDateRenderer for java.sql.Date and LocalDateTimeRenderer for Timestamp, converting them itself (vaadin-ai-extensions-flow/.../grid/GridRenderer.java:105-112 and :186-203); DefaultDataConverter handles both types for the chart. The JDBC provider on the Controllers page returns rs.getObject(i) raw and works, so as written this bullet suggests that example is incomplete.
If Calcite returns something else for DATE and TIMESTAMP columns, say that — I could not check Calcite's return types here. Otherwise the bullet can go.
custom-backends.adoc:93 · accuracy
|
|
||
| :preview-feature: AI integration features | ||
| :feature-flag: com.vaadin.experimental.aiComponents | ||
| include::{articles}/_preview-banner.adoc[opts=optional] |
There was a problem hiding this comment.
📐 The page never says the Grid and Chart controllers require a commercial subscription
The whole guide is about feeding GridAIController and ChartAIController, which are part of the commercial vaadin-ai-extensions-flow module. The page carries only the preview banner.
guidelines/versions-and-lifecycle.md: "Pages about a commercial component or tool include the commercial banner right after the page title, with the product named in the commercial-feature attribute." The AI-Powered Grid and Chart pages both do this, and building-apps/agentic-development/mcp/self-hosting/index.adoc shows the banner is used in Building Apps too. A reader can otherwise build the adapter, the provider and the refresh job before learning a subscription is needed.
custom-backends.adoc:15 · conventions
|
|
||
| A provider created in the view can keep backend credentials and cached data specific to one user. Share a provider between users only when every user may see the same data. If the provider keeps a JDBC connection, keep it `transient` and recreate it after session deserialization. Ensure the provider's other fields are serializable or can be restored as well. The provider can be called concurrently, for example when the grid loads a page while the LLM's next query is validated. | ||
|
|
||
| The controller also calls the provider from background threads when it validates the LLM's SQL. This happens with a streaming LLM provider or <<{articles}/flow/ai-support/llm-providers#background-execution,background execution>>. [methodname]`VaadinSession.getCurrent()` and [methodname]`UI.getCurrent()` return `null` there, and Spring Security's [classname]`SecurityContextHolder` has no authentication by default. Capture the user's credentials when the view creates the provider or its backend client, instead of looking them up during a query. |
There was a problem hiding this comment.
🗂️ Threading, concurrency and serialization facts about DatabaseProvider sit only in this guide, not in the reference
Three facts in Use the Provider hold for every DatabaseProvider, not just a custom backend:
- the controller calls the provider from background threads during validation, where
UI.getCurrent()and the SpringSecurityContextare absent - the provider can be called concurrently
- a JDBC connection field should be
transient
Would these belong in the Database Provider section of articles/flow/ai-support/controllers.adoc, with this guide linking to them? CONVENTIONS.md: "Keep a reference page complete on its own", and guidelines/information-architecture.md: "When it lacks a detail, add the detail to the reference." A reader writing a plain JDBC provider has no reason to open a guide about Calcite.
custom-backends.adoc:146 · placement
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6713.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from e43d0e3 |
Summary
DatabaseProviderthat runs SQL, and the docs did not say what to do when the data is behind a REST API, a service, or files. The new guide covers the two ways to add a SQL interface: an Apache Calcite adapter or a copy of the data in a database.DatabaseProviderthat the grid uses to load rows lazily, because the guide builds on them.Fixes #6614