Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
172 changes: 172 additions & 0 deletions articles/building-apps/ai/custom-backends.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
---
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]

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 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


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 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]]
== 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.

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.


=== 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.
* 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ The grid already renders java.sql.Date and Timestamp, so the stated reason for converting them is wrong

Convert JDBC date values to LocalDate and timestamp values to LocalDateTime for 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

* 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:

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💬 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


[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");
----


=== 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 adapted as described above and a [classname]`DataSource` configured for Calcite:

[source,java]
----
var provider = new CalciteDatabaseProvider(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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🗂️ 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 Spring SecurityContext are 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



[[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. 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.

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.
3 changes: 2 additions & 1 deletion articles/building-apps/ai/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<custom-backends#,Apache Calcite or a copy in a database>>, and
* deliver real-time updates to users through server push.

[TIP]
Expand Down
2 changes: 1 addition & 1 deletion articles/flow/ai-support/ai-powered-grid.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 8 additions & 1 deletion articles/flow/ai-support/controllers.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
2 changes: 2 additions & 0 deletions articles/flow/ai-support/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down
Loading