Docs

Docs

AI-Powered Grid

Use GridAIController to let users populate a Grid from the application database using natural language.

GridAIController populates a Grid (Vaadin’s component for displaying tabular data) with data from the application database based on natural-language requests. Backed by a DatabaseProvider, the controller lets the LLM inspect the database schema and run SQL queries that drive the grid.

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.

Basic Usage

Create a grid typed as Grid<AIDataRow>, construct a controller with the grid and a DatabaseProvider, and attach it to an orchestrator. AIDataRow is a framework-owned row type — you never construct instances yourself.

Source code
Java
Grid<AIDataRow> grid = new Grid<>();
MessageInput messageInput = new MessageInput();

DatabaseProvider databaseProvider = new JdbcDatabaseProvider(dataSource);
GridAIController controller = new GridAIController(grid, databaseProvider);

AIOrchestrator.builder(provider, systemPrompt)
        .withInput(messageInput)
        .withController(controller)
        .build();

add(messageInput, grid);

A message list is not required — the grid itself is the output surface. Example prompts:

  • "Show product name and category grouped under Product, and monthly revenue."

  • "List the top 10 highest-paid employees with name, salary, and hire date."

  • "Show me all employees in the Sales department."

Tip
Built-In Workflow Instructions
The controller already informs the LLM of the workflow it needs. You can focus your own system prompt on application-specific behavior.

Query Validation

Before queueing an update, the controller runs a lightweight probe against the database to validate the LLM’s query. If the probe fails, the error is returned to the LLM so that it can correct the query on the next turn. Invalid queries never reach the grid.

Persisting Grid State

Grid state is a single SQL query represented by the GridState record. Capture it with getState() and restore it later with restoreState(). Register a state change listener to persist the state automatically after each successful AI request:

Source code
Java
controller.addStateChangeListener(state ->
        sessionStore.save(sessionId, state));

// Restore on a new session
GridState saved = sessionStore.load(sessionId);
if (saved != null) {
    controller.restoreState(saved);
}

sessionStore here is a placeholder for your own storage — a database table, a file, a VaadinSession attribute, or whatever fits your application.

addStateChangeListener() fires only when the grid is updated by the LLM, not when restoreState() is called. The current state is also automatically included in session serialization, so no extra save/restore code is needed for in-session persistence.

Reconnecting After Deserialization

GridAIController is not serializable. After session restore, create a new controller, pass it to reconnect() together with the new provider, and optionally re-apply the saved state:

Source code
Java
GridAIController controller = new GridAIController(grid, databaseProvider);
orchestrator.reconnect(provider)
        .withController(controller)
        .apply();

Updated –