From 2c751ccba53de8dd1c6f9f34ea86b9099be9b6f0 Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Mon, 16 Nov 2026 11:25:37 +0200 Subject: [PATCH 1/7] docs: document the paging methods of DatabaseProvider 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 --- articles/flow/ai-support/ai-powered-grid.adoc | 2 +- articles/flow/ai-support/controllers.adoc | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/articles/flow/ai-support/ai-powered-grid.adoc b/articles/flow/ai-support/ai-powered-grid.adoc index 8cf04ff188..09b7fa7f51 100644 --- a/articles/flow/ai-support/ai-powered-grid.adoc +++ b/articles/flow/ai-support/ai-powered-grid.adoc @@ -15,7 +15,7 @@ section-nav: commercial :commercial-feature: AI-Powered Grid include::{articles}/_commercial-banner.adoc[opts=optional] -When an LLM request completes, the queued query is executed and the grid re-renders with dynamically generated columns, type-appropriate renderers, right-aligned numeric columns, lazy loading via SQL `LIMIT`/`OFFSET`, and optional column grouping. +When an LLM request completes, the queued query is executed and the grid re-renders with dynamically generated columns, type-appropriate renderers, right-aligned numeric columns, lazy loading one page at a time through the [classname]`DatabaseProvider`, and optional column grouping. == Basic Usage diff --git a/articles/flow/ai-support/controllers.adoc b/articles/flow/ai-support/controllers.adoc index be37af0aa1..e21496524d 100644 --- a/articles/flow/ai-support/controllers.adoc +++ b/articles/flow/ai-support/controllers.adoc @@ -48,11 +48,18 @@ Only one controller can be attached per orchestrator. If you need tools from sev [classname]`DatabaseProvider` is the bridge between the LLM and an application database. The built-in grid and chart controllers use it to let the LLM discover the schema and run SQL queries on demand. Critically, the data flow is asymmetric: the LLM sees the schema so it can write valid queries, but the query results are rendered in the [classname]`Grid` or [classname]`Chart` component -- the rows themselves are never sent back to the LLM. -The interface defines two methods: +The interface defines two methods to implement: * [methodname]`getSchema()` -- returns a plain-text description of the tables, columns, and SQL dialect. The LLM uses this to write valid queries. * [methodname]`executeQuery(String sql)` -- executes a SQL query and returns the rows as a list of column-name-to-value maps. These rows are handed to the grid or chart for rendering; they do not appear in any prompt as such. +[since:com.vaadin:vaadin@V25.4]#Two more methods have default implementations.# The grid uses them to load rows lazily: + +* [methodname]`executeQuery(String sql, QueryPage page)` -- returns one page of the query's rows: at most `limit` rows from `offset`, sorted by the page's sort orders. +* [methodname]`count(String sql)` -- returns the number of rows the query produces. + +The defaults extend the query's SQL with `ORDER BY`, `LIMIT`, and `OFFSET`, or with `COUNT(*)`, and run the result through [methodname]`executeQuery(String sql)`. Override them when your database pages or counts differently, or when it can do so more efficiently. + The following example is a straightforward JDBC implementation: [source,java] From fb80224d89a0db97ae2ec6d0c43a7683e11ad46c Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Mon, 16 Nov 2026 16:31:12 +0200 Subject: [PATCH 2/7] docs: add a guide on custom backends for the AI-powered Grid and Chart 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 Co-Authored-By: Claude Opus 5.5 --- .../building-apps/ai/custom-backends.adoc | 167 ++++++++++++++++++ articles/building-apps/ai/index.adoc | 3 +- articles/flow/ai-support/index.adoc | 2 + 3 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 articles/building-apps/ai/custom-backends.adoc diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc new file mode 100644 index 0000000000..ef9a101dbd --- /dev/null +++ b/articles/building-apps/ai/custom-backends.adoc @@ -0,0 +1,167 @@ +--- +title: Custom Backends +page-title: Custom Backends for AI-Powered Grids and Charts | Vaadin +description: Give the LLM a SQL view of a REST API, a service, or files through an Apache Calcite adapter or a copy in a database. +meta-description: Connect Vaadin's AI-powered Grid and Chart to backends without SQL. Use a built-in Apache Calcite adapter or a database copy, and integrate a DatabaseProvider. +order: 30 +section-nav: badge-preview +--- + + += [since:com.vaadin:vaadin@V25.4]#Custom Backends for AI-Powered Grids and Charts# + +:preview-feature: AI integration features +:feature-flag: com.vaadin.experimental.aiComponents +include::{articles}/_preview-banner.adoc[opts=optional] + +The <<{articles}/flow/ai-support/ai-powered-grid#,AI-powered Grid>> and <<{articles}/flow/ai-support/ai-powered-chart#,Chart>> let users explore data in natural language. The LLM reads a schema description and writes SQL. A <<{articles}/flow/ai-support/controllers#database-provider,[classname]`DatabaseProvider`>> runs the query. When your data lives behind a REST API, in a service, or in files, it may have no SQL interface. + +This guide covers two ways to add that interface: an https://calcite.apache.org[Apache Calcite] adapter or a copy of the data in a database. Calcite's documentation covers adapter configuration and development. This guide focuses on connecting the resulting SQL interface to Vaadin. + + +== Prerequisites + +* An application with an AI-powered Grid or Chart, set up as described on <<{articles}/flow/ai-support/ai-powered-grid#,AI-Powered Grid>> or <<{articles}/flow/ai-support/ai-powered-chart#,AI-Powered Chart>>. +* The `com.vaadin.experimental.aiComponents` <<{articles}/flow/configuration/feature-flags#,feature flag>> enabled: add `com.vaadin.experimental.aiComponents=true` to [filename]`src/main/resources/vaadin-featureflags.properties`. +* Access to the backend, through an adapter or a client that can read the data to copy into a database. + + +== Choose an Approach + +For a data source with a JDBC driver, use a JDBC provider like the one on the <<{articles}/flow/ai-support/controllers#database-provider,Controllers>> page. For a backend that runs SQL through its own API, implement [classname]`DatabaseProvider` with that client. Override [methodname]`executeQuery(String sql, QueryPage page)` and [methodname]`count(String sql)` when it pages or counts in its own way. + +For data without a SQL interface, compare the two approaches: + +[cols="1,2,2",options="header"] +|=== +| |Calcite Adapter |Database Copy + +|Query execution +|The adapter sends supported operations to the backend, and Calcite runs the rest +|The database runs queries against the copied data + +|Freshness +|Queries read from the backend, subject to any caching in the adapter or client +|The data as of the last refresh of the copy + +|Access rights +|Configure the adapter's backend access for the users whose data it serves +|The copy needs its own access controls. A shared copy exposes the same rows to every user who can query it + +|Several sources +|Calcite can expose several sources as tables for queries that join or aggregate their data +|Tables that are copied from several sources can be joined in the database + +|What you maintain +|Adapter configuration and a database provider. A custom adapter also requires implementation and maintenance +|A scheduled job that fills the copy, and a JDBC provider +|=== + +Use <<#calcite,Calcite>> when a suitable built-in adapter can query the backend with the required performance and access controls. If none is available, compare the work of building a custom adapter with <<#database-copy,copying the data into a database>>. A copy suits data that can be refreshed periodically and queried independently of the original backend. + + +[[calcite]] +== Run the Queries with Calcite + +Calcite presents data from an adapter as SQL tables and exposes a JDBC interface. Your [classname]`DatabaseProvider` uses that interface to run the LLM's queries. + + +[[backend-adapters]] +=== Choose and Configure an Adapter + +Start with Calcite's https://calcite.apache.org/docs/adapter.html#schema-adapters[built-in adapters]. These include adapters for MongoDB, Elasticsearch, and Cassandra, as well as a https://calcite.apache.org/docs/file_adapter.html[file adapter]. Follow the selected adapter's documentation for its dependencies, connection settings, schema configuration, and supported operations. Calcite's https://calcite.apache.org/docs/model.html[model reference] and https://calcite.apache.org/docs/adapter.html#jdbc-connect-string-parameters[JDBC connection reference] describe the shared configuration options. + +The adapter translates the SQL operations it supports into the backend's own queries, so the backend's rules apply to them. Not every SQL operation has an exact counterpart in the backend, for example a `LIKE` pattern or a date comparison. For such an operation, the adapter's translation decides the result, or the adapter rejects the query. Check which operations the adapter's documentation lists as supported, and test the kinds of queries that users ask, as described in <<#check-queries,Check Paging and Query Performance>>. + +For development, follow the https://calcite.apache.org/docs/tutorial.html[Calcite adapter tutorial]. For a REST API or a service, the smallest custom adapter is a table that implements [interfacename]`ScannableTable` and returns the objects from your backend client as rows. Calcite then filters, sorts, and groups all the rows in memory, so this suits data that is small enough to load in full. The same Vaadin integration applies to built-in and custom adapters. + + +=== Connect the Adapter to a Database Provider + +Adapt the JDBC provider on the <<{articles}/flow/ai-support/controllers#database-provider,Controllers>> page to use the Calcite connection configured for your adapter. Return the adapter's SQL schema description from [methodname]`getSchema()` and run queries through [methodname]`executeQuery(String sql)`. The provider returns rows as maps whose keys are the SQL column labels. + +Configure the adapter and its backend credentials for read-only access to the data users may query. Follow the Controllers page's guidance on schema scope and error messages. + +Several details matter when the SQL comes from the LLM and the grid: + +* Use a quoting policy compatible with the double quotes that the grid uses for names. Calcite's `lex=MYSQL_ANSI` setting also makes unquoted names case-insensitive. +* 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. +* 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. Keep row values and backend details out of those messages, and use a generic message for other failures. + +For example, these connection properties accommodate names the LLM and grid may use. Apply them when creating the Calcite connection alongside the adapter's configuration: + +[source,java] +---- +var properties = new Properties(); +properties.setProperty("lex", "MYSQL_ANSI"); +properties.setProperty("parserFactory", + "org.apache.calcite.sql.parser.babel.SqlBabelParserImpl#FACTORY"); +---- + + +=== Describe the Schema for the LLM + +The text that [methodname]`getSchema()` returns is all the LLM knows about your data. Follow the general advice on the <<{articles}/flow/ai-support/controllers#database-provider,Controllers>> page. Describe the tables and columns exposed by the adapter, their relationships, and any restrictions that affect queries. + +Name Apache Calcite as the SQL dialect and use its https://calcite.apache.org/docs/reference.html[SQL reference] for syntax and types. Tell the LLM how to write date and timestamp literals, for example: + +[source,java] +---- +return """ + Tables: + products(id INT, name VARCHAR, category VARCHAR, price DECIMAL) + orders(id INT, product_id INT, quantity INT, ordered_on DATE) + orders.product_id refers to products.id. + Dialect: Apache Calcite. + Compare dates with DATE literals, for example ordered_on >= DATE '2025-01-01'. + Compare timestamps with TIMESTAMP literals, for example TIMESTAMP '2025-01-01 00:00:00'. + Put aliases that are SQL keywords in double quotes, for example ordered_on AS "date". + """; +---- + +Even with the Babel parser, some names such as `date` and `order` require double quotes. This applies to column names and to aliases chosen by the LLM. Also avoid column names that are SQL functions written without parentheses, such as `user` or `current_date`. An unquoted `SELECT user FROM tickets` returns the function's value instead of the column. Rename these columns in the exposed schema or tell the LLM to quote them. + + +[[use-the-provider]] +=== Use the Provider + +Create the provider in the view and pass it to a [classname]`GridAIController` or a [classname]`ChartAIController`. For example, with the JDBC provider from the Controllers page and a [classname]`DataSource` configured for Calcite: + +[source,java] +---- +var provider = new JdbcDatabaseProvider(calciteDataSource); +var controller = new GridAIController(grid, provider); +---- + +Attach the controller to the orchestrator as described on <<{articles}/flow/ai-support/ai-powered-grid#,AI-Powered Grid>> and <<{articles}/flow/ai-support/ai-powered-chart#,AI-Powered Chart>>. + +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. + + +[[check-queries]] +=== Check Paging and Query Performance + +The grid uses [methodname]`executeQuery(String sql, QueryPage page)` and [methodname]`count(String sql)` to load rows lazily. Their defaults add sorting, paging, and counting to the SQL before calling [methodname]`executeQuery(String sql)`. + +Check that the adapter https://calcite.apache.org/docs/adapter.html#pushing-operations-down-to-your-table[pushes] the grid's sorting, paging, and counting to the backend. Override the provider's paging and counting methods when the backend can perform them more efficiently. + +A grid render can query the backend several times: for a sample row, for the row count, and for each page. The chart calls [methodname]`executeQuery(String sql)` for each series query and receives its full result. Queries also run when the LLM proposes them for validation. Account for these repeated calls when choosing an adapter and any caching. Keep caches scoped to the user's access rights. + +Test the provider directly with SQL before involving an LLM. Include joins, date conditions, `<>` and `LIKE` conditions, aggregates, sorted and unsorted pages, and counts. Check both the returned rows and the work the backend performs. + + +[[database-copy]] +== Copy the Data into a Database + +The application can keep a copy of the data in a database and let the database run the LLM's SQL. Queries then run independently of the original backend, and the application controls when to refresh the copy. The trade-off is that the grid and the chart show the data as of the last refresh of the copy. + +The copy doesn't carry over the access rights of the backend either. One account reads the backend to fill the copy, and every user of the grid or the chart can query all its rows. Copy only data that all these users may see. + +Any database with a JDBC driver can hold the copy, such as a schema of its own in the database the application already uses, or an embedded database. + +Fill the copy with a scheduled job that replaces its rows in one transaction, so that the grid and the chart never read a half-filled table. + +Query the copy with a JDBC provider like the one on the <<{articles}/flow/ai-support/controllers#database-provider,Controllers>> page, and describe the tables of the copy in its [methodname]`getSchema()`. Give the provider a database account that can only read the copy, as that page advises. diff --git a/articles/building-apps/ai/index.adoc b/articles/building-apps/ai/index.adoc index c646ff35b9..6ff0815b96 100644 --- a/articles/building-apps/ai/index.adoc +++ b/articles/building-apps/ai/index.adoc @@ -16,7 +16,8 @@ You'll learn how to: * connect your application to an AI client with popular Java libraries such as Spring AI and LangChain4j, * use the xref:{articles}/flow/ai-support#[AI support features] to connect LLM providers to Vaadin UI components with minimal boilerplate, * choose Vaadin components that create intuitive, AI-powered workflows -- such as `MessageInput`, `MessageList`, and `UploadManager`, -* let users explore application data through natural language with <<{articles}/flow/ai-support/ai-powered-grid#,AI-powered Grid>> and <<{articles}/flow/ai-support/ai-powered-chart#,AI-powered Chart>>, or fill a form from a prompt or an attached document with the <<{articles}/flow/ai-support/ai-powered-form#,AI Form Filler>>, and +* let users explore application data through natural language with <<{articles}/flow/ai-support/ai-powered-grid#,AI-powered Grid>> and <<{articles}/flow/ai-support/ai-powered-chart#,AI-powered Chart>>, or fill a form from a prompt or an attached document with the <<{articles}/flow/ai-support/ai-powered-form#,AI Form Filler>>, +* expose a REST API or another backend without SQL to the AI-powered Grid and Chart with <>, and * deliver real-time updates to users through server push. [TIP] diff --git a/articles/flow/ai-support/index.adoc b/articles/flow/ai-support/index.adoc index d0b536f69e..2d7d4d6d73 100644 --- a/articles/flow/ai-support/index.adoc +++ b/articles/flow/ai-support/index.adoc @@ -33,6 +33,8 @@ AI integration consists of four parts: The orchestrator, LLM providers, component interfaces, and the [classname]`AIController` interface are free and open source (the `vaadin-ai-core-flow` module). The built-in Grid, Chart, and Form controllers are part of the commercial `vaadin-ai-extensions-flow` module and require a commercial Vaadin subscription. +The Grid and Chart controllers read their data with SQL. To give them data that has no SQL interface, such as a REST API, a service, or files, see <<{articles}/building-apps/ai/custom-backends#,Custom Backends for AI-Powered Grids and Charts>>. + Add the UI components to your layout and pass them to the orchestrator through its builder. The orchestrator wires them together and manages the LLM interaction. From 1a18e031e2a18c4f1d1f8af698b15c00ac7608cf Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Thu, 19 Nov 2026 16:20:53 +0200 Subject: [PATCH 3/7] docs: add Calcite settings and safety notes to custom backends guide Co-Authored-By: Claude Fable 5.2 --- articles/building-apps/ai/custom-backends.adoc | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc index ef9a101dbd..643a687307 100644 --- a/articles/building-apps/ai/custom-backends.adoc +++ b/articles/building-apps/ai/custom-backends.adoc @@ -57,7 +57,7 @@ For data without a SQL interface, compare the two approaches: |A scheduled job that fills the copy, and a JDBC provider |=== -Use <<#calcite,Calcite>> when a suitable built-in adapter can query the backend with the required performance and access controls. If none is available, compare the work of building a custom adapter with <<#database-copy,copying the data into a database>>. A copy suits data that can be refreshed periodically and queried independently of the original backend. +Use <<#calcite,Calcite>> when a suitable built-in adapter can query the backend with the required performance and access controls. If none is available, compare the work of building a custom adapter with <<#database-copy,copying the data into a database>>. A custom adapter is small when it loads all the rows and lets Calcite do the rest. One that sends filters, sorting, and paging to the backend, as large data requires, takes much more work. A copy suits data that can be refreshed periodically and queried independently of the original backend. [[calcite]] @@ -71,6 +71,8 @@ Calcite presents data from an adapter as SQL tables and exposes a JDBC interface Start with Calcite's https://calcite.apache.org/docs/adapter.html#schema-adapters[built-in adapters]. These include adapters for MongoDB, Elasticsearch, and Cassandra, as well as a https://calcite.apache.org/docs/file_adapter.html[file adapter]. Follow the selected adapter's documentation for its dependencies, connection settings, schema configuration, and supported operations. Calcite's https://calcite.apache.org/docs/model.html[model reference] and https://calcite.apache.org/docs/adapter.html#jdbc-connect-string-parameters[JDBC connection reference] describe the shared configuration options. +Calcite and Vaadin both depend on the Jackson annotations, in different versions. Spring Boot's dependency management aligns them. In a project without Spring Boot, check the resolved version with `mvn dependency:tree`. If it's the older one from Calcite, Vaadin's JSON handling fails with a [classname]`NoClassDefFoundError`. In that case, exclude `com.fasterxml.jackson.core:jackson-annotations` from every Calcite dependency you declare. + The adapter translates the SQL operations it supports into the backend's own queries, so the backend's rules apply to them. Not every SQL operation has an exact counterpart in the backend, for example a `LIKE` pattern or a date comparison. For such an operation, the adapter's translation decides the result, or the adapter rejects the query. Check which operations the adapter's documentation lists as supported, and test the kinds of queries that users ask, as described in <<#check-queries,Check Paging and Query Performance>>. For development, follow the https://calcite.apache.org/docs/tutorial.html[Calcite adapter tutorial]. For a REST API or a service, the smallest custom adapter is a table that implements [interfacename]`ScannableTable` and returns the objects from your backend client as rows. Calcite then filters, sorts, and groups all the rows in memory, so this suits data that is small enough to load in full. The same Vaadin integration applies to built-in and custom adapters. @@ -86,15 +88,18 @@ Several details matter when the SQL comes from the LLM and the grid: * Use a quoting policy compatible with the double quotes that the grid uses for names. Calcite's `lex=MYSQL_ANSI` setting also makes unquoted names case-insensitive. * 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. -* Relay useful SQL parse and validation errors in a [classname]`ToolException` so the LLM can correct its query. Keep row values and backend details out of those messages, and use a generic message for other failures. +* 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 names the LLM and grid may use. Apply them when creating the Calcite connection alongside the adapter's configuration: +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: [source,java] ---- var properties = new Properties(); properties.setProperty("lex", "MYSQL_ANSI"); +properties.setProperty("conformance", "MYSQL_5"); properties.setProperty("parserFactory", "org.apache.calcite.sql.parser.babel.SqlBabelParserImpl#FACTORY"); ---- @@ -126,11 +131,11 @@ Even with the Babel parser, some names such as `date` and `order` require double [[use-the-provider]] === Use the Provider -Create the provider in the view and pass it to a [classname]`GridAIController` or a [classname]`ChartAIController`. For example, with the JDBC provider from the Controllers page and a [classname]`DataSource` configured for Calcite: +Create the provider in the view and pass it to a [classname]`GridAIController` or a [classname]`ChartAIController`. For example, with the JDBC provider adapted as described above and a [classname]`DataSource` configured for Calcite: [source,java] ---- -var provider = new JdbcDatabaseProvider(calciteDataSource); +var provider = new CalciteDatabaseProvider(calciteDataSource); var controller = new GridAIController(grid, provider); ---- @@ -146,7 +151,7 @@ The controller also calls the provider from background threads when it validates The grid uses [methodname]`executeQuery(String sql, QueryPage page)` and [methodname]`count(String sql)` to load rows lazily. Their defaults add sorting, paging, and counting to the SQL before calling [methodname]`executeQuery(String sql)`. -Check that the adapter https://calcite.apache.org/docs/adapter.html#pushing-operations-down-to-your-table[pushes] the grid's sorting, paging, and counting to the backend. Override the provider's paging and counting methods when the backend can perform them more efficiently. +Check that the adapter https://calcite.apache.org/docs/adapter.html#pushing-operations-down-to-your-table[pushes] the grid's sorting, paging, and counting to the backend. A table that only implements [interfacename]`ScannableTable` pushes nothing: each query reads all the table's rows from the backend, so cache them for a short time. Override the provider's paging and counting methods when the backend can perform them more efficiently. A grid render can query the backend several times: for a sample row, for the row count, and for each page. The chart calls [methodname]`executeQuery(String sql)` for each series query and receives its full result. Queries also run when the LLM proposes them for validation. Account for these repeated calls when choosing an adapter and any caching. Keep caches scoped to the user's access rights. From 5047a117cba6780f9930c700453b260a3c680dc6 Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Thu, 19 Nov 2026 17:02:28 +0200 Subject: [PATCH 4/7] docs: show how the Calcite connection properties are applied --- articles/building-apps/ai/custom-backends.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc index 643a687307..c1c2965f07 100644 --- a/articles/building-apps/ai/custom-backends.adoc +++ b/articles/building-apps/ai/custom-backends.adoc @@ -102,6 +102,7 @@ properties.setProperty("lex", "MYSQL_ANSI"); properties.setProperty("conformance", "MYSQL_5"); properties.setProperty("parserFactory", "org.apache.calcite.sql.parser.babel.SqlBabelParserImpl#FACTORY"); +var connection = DriverManager.getConnection("jdbc:calcite:", properties); ---- @@ -131,11 +132,11 @@ Even with the Babel parser, some names such as `date` and `order` require double [[use-the-provider]] === Use the Provider -Create the provider in the view and pass it to a [classname]`GridAIController` or a [classname]`ChartAIController`. For example, with the JDBC provider adapted as described above and a [classname]`DataSource` configured for Calcite: +Create the provider in the view and pass it to a [classname]`GridAIController` or a [classname]`ChartAIController`. For example, with the JDBC provider adapted as described above, which opens its Calcite connections with those properties: [source,java] ---- -var provider = new CalciteDatabaseProvider(calciteDataSource); +var provider = new CalciteDatabaseProvider(properties); var controller = new GridAIController(grid, provider); ---- From 229869c319a4374640758128e045a477f266f382 Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Thu, 19 Nov 2026 17:02:33 +0200 Subject: [PATCH 5/7] docs: drop the date conversion advice from the custom backends guide --- articles/building-apps/ai/custom-backends.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc index c1c2965f07..2f2bef5846 100644 --- a/articles/building-apps/ai/custom-backends.adoc +++ b/articles/building-apps/ai/custom-backends.adoc @@ -90,7 +90,6 @@ Several details matter when the SQL comes from the LLM and the grid: * 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. * 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: From 0890137e3cfb6411164a57477c5f0fb439d63fd3 Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Thu, 19 Nov 2026 17:02:49 +0200 Subject: [PATCH 6/7] docs: add the commercial banner to the custom backends guide --- articles/building-apps/ai/custom-backends.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc index 2f2bef5846..7052cd1275 100644 --- a/articles/building-apps/ai/custom-backends.adoc +++ b/articles/building-apps/ai/custom-backends.adoc @@ -4,12 +4,15 @@ page-title: Custom Backends for AI-Powered Grids and Charts | Vaadin description: Give the LLM a SQL view of a REST API, a service, or files through an Apache Calcite adapter or a copy in a database. meta-description: Connect Vaadin's AI-powered Grid and Chart to backends without SQL. Use a built-in Apache Calcite adapter or a database copy, and integrate a DatabaseProvider. order: 30 -section-nav: badge-preview +section-nav: commercial badge-preview --- = [since:com.vaadin:vaadin@V25.4]#Custom Backends for AI-Powered Grids and Charts# +:commercial-feature: the AI-powered Grid and Chart +include::{articles}/_commercial-banner.adoc[opts=optional] + :preview-feature: AI integration features :feature-flag: com.vaadin.experimental.aiComponents include::{articles}/_preview-banner.adoc[opts=optional] From 8c3c53a2efd0d8f3079572f5974c92aeadd4c871 Mon Sep 17 00:00:00 2001 From: Tomi Virkki Date: Thu, 19 Nov 2026 17:03:22 +0200 Subject: [PATCH 7/7] docs: move DatabaseProvider threading facts to the reference --- articles/building-apps/ai/custom-backends.adoc | 4 ++-- articles/flow/ai-support/controllers.adoc | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/articles/building-apps/ai/custom-backends.adoc b/articles/building-apps/ai/custom-backends.adoc index 7052cd1275..1ab9b390c8 100644 --- a/articles/building-apps/ai/custom-backends.adoc +++ b/articles/building-apps/ai/custom-backends.adoc @@ -144,9 +144,9 @@ var controller = new GridAIController(grid, provider); Attach the controller to the orchestrator as described on <<{articles}/flow/ai-support/ai-powered-grid#,AI-Powered Grid>> and <<{articles}/flow/ai-support/ai-powered-chart#,AI-Powered Chart>>. -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. +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 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. +The controllers call the provider concurrently and from background threads, where the user's session and security context aren't available. See <<{articles}/flow/ai-support/controllers#database-provider,Database Provider>> for the details. Capture the user's credentials when the view creates the provider or its backend client, instead of looking them up during a query. [[check-queries]] diff --git a/articles/flow/ai-support/controllers.adoc b/articles/flow/ai-support/controllers.adoc index e21496524d..b358fdb4fa 100644 --- a/articles/flow/ai-support/controllers.adoc +++ b/articles/flow/ai-support/controllers.adoc @@ -111,6 +111,8 @@ The example returns a hardcoded string for clarity, but [methodname]`getSchema() When a query fails -- for example, because it references an unknown column -- the exception type determines what the LLM learns about the failure. The example above [since:com.vaadin:vaadin@V25.3]#throws a `ToolException`#, whose message is relayed to the LLM so it can correct the query on its next attempt; any other exception is replaced with a generic error message. See <<#tool-error-handling,Tool Error Handling>>. +The controllers call the provider on more than one thread. They validate a query during the tool call that proposes it, which runs on a background thread with a streaming LLM provider or <>. [methodname]`VaadinSession.getCurrent()` and [methodname]`UI.getCurrent()` return `null` there, and Spring Security's [classname]`SecurityContextHolder` has no authentication by default. The grid loads its rows on the UI thread, which can happen while the next query is validated. The provider can therefore be called concurrently. + .Read-Only Database Access [IMPORTANT] The LLM writes the SQL that gets executed. Always back a [classname]`DatabaseProvider` implementation with a database account that has read-only access to the tables and views you intend to expose. This prevents the LLM from modifying or deleting data and limits the impact of a prompt-injection attempt that tries to trick the LLM into running destructive statements.