Use the SQL Assistant with Confluent Manager for Apache Flink

The SQL Assistant is a page in the Confluent Manager for Apache Flink® (CMF) UI where you write and run Flink SQL statements in a conversation. Each statement stays in the conversation together with its results, so you can build on earlier queries.

When your CMF administrator connects CMF to a large language model (LLM), you can also describe what you want in plain language, and the model writes the Flink SQL statement for you. The model sees the whole conversation, including earlier statements, their results, and their errors, and takes them into account in its next answer.

Without an LLM, the SQL Assistant works as a SQL shell in the browser. You type statements, run them, and see the results below each statement.

Important

The SQL Assistant is a preview feature in CMF 2.5. Its behavior, configuration, and REST API might change in future releases.

Use the SQL Assistant

Open the SQL Assistant

Open the CMF UI. For details, see Configure the Confluent Manager for Apache Flink UI.
Select an environment.
In the navigation menu of the environment, click SQL Assistant.

If the menu has no SQL Assistant entry, the feature is turned off for your CMF deployment. Ask your CMF administrator to turn it on, as described in Configure the SQL Assistant.

The page lists the conversations of the environment. Select a conversation to continue it, or click New conversation to start a new one.

Select a compute pool

Each conversation runs its statements on one compute pool of the environment. Select the pool in the Compute pool list before you run the first statement. The list shows whether each pool is shared or dedicated. You can switch a conversation to another compute pool later.

If you select a shared compute pool that is suspended, the first statement fails with an error that includes a Start compute pool button. Click it, wait until the pool is running, and then run the statement again.

For more information about compute pools, see Manage Compute Pools in Confluent Manager for Apache Flink.

Write and run SQL

In SQL mode, type a Flink SQL statement and press Enter to run it. Press Shift+Enter to start a new line. You can run every statement that CMF supports. For the list, see Features & Support for Statements in Confluent Manager for Apache Flink.

The results appear below the statement:

Statements that read metadata, such as SHOW TABLES or DESCRIBE, show their result right away. SHOW CREATE TABLE and SHOW CREATE VIEW show the statement text as code.
A SELECT statement shows its rows as they arrive. The SQL Assistant shows at most 100 rows per statement. Your administrator can change this limit. When a streaming SELECT statement reaches the limit, the SQL Assistant stops it. To stop a statement earlier, click Stop.
An INSERT INTO statement or a statement set writes into its target table and returns no results. A streaming statement of this kind keeps running in the background after you leave the conversation, until you stop it.

Every statement that the SQL Assistant runs is a regular CMF statement. Its name starts with sql-assistant-, followed by an ID of the conversation and the position of the statement in the conversation. You can find these statements on the statements page of the environment and manage them like any other statement. For details, see Manage Statements in Confluent Manager for Apache Flink.

The conversation saves the rows that each statement returned. When you reopen the conversation later, these rows show as saved results from a previous run.

Statement settings

Under each statement, Settings shows the parallelism, Flink configuration, and statement properties that the statement runs with. Before you run a statement, click Edit to change these settings. If the environment sets Flink configuration for all of its statements, the environment’s values take precedence.

Ask in natural language

When your administrator has configured an LLM, the SQL Assistant has two modes: AI and SQL. Use SQL to write statements yourself, as described in Write and run SQL. Use AI to describe what you want, for example:

“Which tables are in the marketplace database?”
“What are the columns of the orders table?”
“Show me the five customers with the most orders in the last hour.”
“What is a watermark?”

The assistant answers in one of the following ways:

With a Flink SQL statement, usually together with a short explanation. You can edit the statement before you run it. If you do, the model receives your change.
With a text answer, for example when you ask about a Flink concept or about the results of an earlier statement.
With a question and a list of options, when the model needs more information from you. Select one or more options, or type your own answer.

Multi-step requests

To answer some requests, the assistant first needs to look at the data. It then proposes a series of statements, called steps. For example, it might describe a table, then select a few rows from it, and only then write the statement that answers your question.

When a step runs, the SQL Assistant collects rows until it has the number of rows, or has waited the length of time, that the model requested. A status line shows the progress. The SQL Assistant then sends the rows to the model, which proposes the next step or gives its answer. To end this process at any time, click Stop agent.

Approve statements

By default, the assistant waits for you to click Run on each statement it writes. To let it run steps on its own, turn on Auto-accept.

With Auto-accept turned on, the assistant runs a statement automatically only if the statement reads data or metadata (SELECT, SHOW, or DESCRIBE) and you have not edited the statement or its settings. The assistant never runs the following statements on its own:

Statements that change something, such as CREATE TABLE, ALTER TABLE, or DROP TABLE.
Statements that write data, such as INSERT INTO and statement sets.
Statements that might have a syntax error, or that CMF does not support.

For these statements, the button reads Approve & Run, and a note explains why the statement waits. Review the statement, and then click Approve & Run.

Note

The model can write statements that are wrong or that do something other than you intended. Review each statement before you approve it.

Errors and corrections

When a step fails, the SQL Assistant sends the error to the model, which then proposes a fix. With Auto-accept turned on, the same happens when the statement that answers your request fails. After three failed attempts in a row, the assistant stops and asks you to edit the SQL or rephrase your request.

Context size

Every message, statement, and result in a conversation is part of what the SQL Assistant sends to the model with the next request. If your administrator has set the context size of the model, the page shows a Context gauge with the approximate number of tokens the last request used, and the limit of the model. When a conversation gets too long for the model, the SQL Assistant rejects the next message. Start a new conversation to continue.

What the model knows

In addition to the conversation, the model gets the following information:

The names of the catalogs, databases, and tables that statements in the environment can access. For the environment catalog, this also includes views, user-defined functions, and models. For more information, see Manage Environment Catalogs in Confluent Manager for Apache Flink.
A Flink SQL reference for the Flink version of the compute pool, which the model can look up when it needs it. The reference covers statements, built-in functions, and configuration options.
How to use the forecasting and anomaly detection functions. For details, see Forecast Data Trends with Confluent Platform for Apache Flink and Anomaly Detection with Confluent Manager for Apache Flink.

The list of catalogs, databases, and tables is refreshed every 15 minutes by default. If you created a table a few minutes ago, the model might not know it yet. Mention the table in your message, or ask the model to run SHOW TABLES.

Manage conversations

Conversations belong to the environment, not to a single user. Everyone who has access to the SQL Assistant in an environment can open, continue, rename, and delete every conversation in it.

Rename a conversation: The assistant suggests a title based on the first messages. To set your own title, rename the conversation. After that, the assistant no longer changes the title.
Copy a conversation: Use Copy conversation as Markdown to copy the whole conversation, including statements and results, to the clipboard. To copy a single response, use Copy as Markdown on that response.
Delete a conversation: Deleting a conversation also deletes its saved results. You can’t restore a deleted conversation. Statements of the conversation that are still running are stopped, but not deleted.

Configure the SQL Assistant

You configure the SQL Assistant with Helm values in the cmf section of your CMF values file:

cmf.sql.assistant turns the SQL Assistant on and selects the model it uses.
cmf.ai.models lists the models that CMF can call. You give each entry a name and refer to it by that name.

For general installation steps, see Install Confluent Manager for Apache Flink with Helm.

Turn on the SQL Assistant

The SQL Assistant is turned off by default. To turn it on without an LLM, set cmf.sql.assistant.enabled to true:

# sql-assistant-values.yaml
cmf:
  sql:
    assistant:
      enabled: true

helm upgrade --install cmf confluentinc/confluent-manager-for-apache-flink \
    --version "~2.5.0" \
    -f sql-assistant-values.yaml \
    --namespace <your-cmf-namespace>

The SQL Assistant entry then appears in the navigation menu of each environment. Without a model, users can only write and run SQL, and CMF doesn’t call any LLM.

Connect an LLM

To let users ask in natural language, add a model entry under cmf.ai.models and set cmf.sql.assistant.model to the name of the entry. The following steps use a Gemini model from Google as an example.

Create a Kubernetes Secret that holds the API key of the model provider. Create the Secret in the namespace where CMF runs:

kubectl create secret generic cmf-sql-assistant-llm \
    --from-literal=api-key=<your-api-key> \
    --namespace <your-cmf-namespace>

Add the model and select it for the SQL Assistant:

# sql-assistant-values.yaml
cmf:
  ai:
    models:
      gemini-flash:
        provider: google-genai
        model: gemini-2.5-flash
        maxInputTokens: 1048576
        apiKey:
          kubernetesSecretName: cmf-sql-assistant-llm
          kubernetesSecretProperty: api-key
  sql:
    assistant:
      enabled: true
      model: gemini-flash

Upgrade your CMF release:

helm upgrade --install cmf confluentinc/confluent-manager-for-apache-flink \
    --version "~2.5.0" \
    -f sql-assistant-values.yaml \
    --namespace <your-cmf-namespace>

Open the SQL Assistant in the CMF UI. The page now offers the AI mode.

CMF checks the model configuration when it starts. It does not start if cmf.sql.assistant.model names an entry that doesn’t exist, if the entry has no provider or model, or if it can’t read the API key from the Secret. The CMF log names the setting that caused the error. CMF never falls back to SQL-only mode because of a configuration error.

CMF reads the API key when it starts. After you change the key in the Secret, restart CMF:

kubectl rollout restart deployment/confluent-manager-for-apache-flink \
    --namespace <your-cmf-namespace>

Choose a model

The SQL Assistant asks the model to reply in a fixed JSON format and to write Flink SQL, which differs in many details from other SQL dialects. Models that follow instructions poorly, which is common for small models, produce more errors and need more correction rounds. Try the model you plan to use with typical questions from your users before you make it available to them.

Model providers

The provider setting of a model entry selects how CMF calls the model.

Provider	Use for	`endpoint`	API key
`google-genai`	Gemini models through the Gemini API from Google.	Ignored.	Required.
`openai`	Models of the OpenAI API.	Optional. Defaults to `https://api.openai.com/v1`.	Required.
`openai-compatible`	Servers that offer an OpenAI-compatible API, such as vLLM or LiteLLM.	Required, including the API version path, for example `http://vllm.ai.svc:8000/v1`.	Optional.
`ollama`	Models served by Ollama.	Required, for example `http://ollama.ai.svc:11434`.	Not used.

The following example registers an OpenAI model and a model on a self-hosted Ollama server. Only the entry that cmf.sql.assistant.model names is used.

cmf:
  ai:
    models:
      gpt:
        provider: openai
        model: gpt-5-mini
        apiKey:
          kubernetesSecretName: cmf-sql-assistant-llm
          kubernetesSecretProperty: api-key
      local-llama:
        provider: ollama
        model: llama3.3
        endpoint: http://ollama.ai.svc:11434
  sql:
    assistant:
      enabled: true
      model: local-llama

The CMF pod must be able to reach the endpoint of the model. If you restrict the outgoing traffic of CMF with a Kubernetes NetworkPolicy, allow traffic to the model endpoint. The cmf.sql.models.allowedEndpoints setting does not apply to the SQL Assistant. That setting only controls which endpoints Flink jobs can call for models created with CREATE MODEL.

Configuration reference

SQL Assistant settings

Helm value	Default	Description
`cmf.sql.assistant.enabled`	`false`	Shows the SQL Assistant in the UI and serves its REST API.
`cmf.sql.assistant.model`	Not set	Name of an entry in `cmf.ai.models`. When not set, users can only write and run SQL, and CMF doesn’t call any model.
`cmf.sql.assistant.maxResultRows`	`100`	The maximum number of rows that the SQL Assistant collects for one statement. This limit applies to the rows that users see, the rows that the conversation saves, and the rows that the model receives.
`cmf.sql.assistant.schemaCacheTtl`	`15m`	How long CMF keeps the list of catalogs, databases, and tables that it sends to the model, before it reads the list again. Use a duration such as `90s`, `15m`, or `1h`.

Model settings

Each entry under cmf.ai.models.<name> supports the following settings.

Helm value	Default	Description
`provider`	None	Required. One of `google-genai`, `openai`, `openai-compatible`, or `ollama`.
`model`	None	Required. The model ID of the provider, for example `gemini-2.5-flash`.
`endpoint`	None	Base URL of the model server. Whether you need it depends on the provider. For details, see Model providers.
`apiKey.kubernetesSecretName`	None	Name of the Kubernetes `Secret` that holds the API key. The `Secret` must be in the namespace where CMF runs.
`apiKey.kubernetesSecretProperty`	None	Key in the Secret that holds the API key.
`apiKey.value`	None	The API key itself. Use this for development only, because Helm writes the value as plain text into the CMF `ConfigMap`. If you set both `value` and a `Secret`, CMF uses `value`.
`maxInputTokens`	None	The context size of the model, in tokens. When set, the UI shows how much of the context a conversation uses, and CMF rejects messages that would exceed it. Look up the value in the documentation of your model.
`timeout`	`2m`	The maximum time for one request to the model, including retries.
`options.temperature`	Provider default	The sampling temperature that CMF passes to the model. CMF ignores other keys under `options`.

The effective configuration view of the CMF UI hides the API key and the values under options.

Grant access to the SQL Assistant

When role-based access control (RBAC) is enabled, CMF checks the permissions of a user on statements in the environment before it lets the user work with the SQL Assistant:

To list and open conversations, a user needs the View permission on statements whose names start with sql-assistant-.
To start, continue, rename, or delete conversations, and to run the statements of a conversation, a user needs the Create/Edit permission on these statements.

A role binding on all statements of the environment covers the SQL Assistant. To give a user access to the SQL Assistant without access to other statements, bind the DeveloperManage role to the statement name prefix sql-assistant-:

confluent iam rbac role-binding create \
    --principal User:u-analyst \
    --role DeveloperManage \
    --cmf CMF-id \
    --flink-environment prod-env \
    --prefix \
    --resource FlinkStatement:sql-assistant-

To run statements on a shared compute pool, the user also needs the View permission on that compute pool. For details, see Compute pools. For how prefixes match resource names, see Resource name matching.

Data sent to the model provider

When a model is configured, CMF sends the following data to the model provider with each request:

The messages of the conversation, and the statements, results, and error messages it contains. Results are limited to maxResultRows rows per statement.
The names of the catalogs, databases, tables, views, functions, and models that statements in the environment can access. Column names and table data reach the model through the results of statements such as DESCRIBE or SELECT.

CMF does not filter or mask this data, with one exception: CMF replaces API keys in CREATE MODEL and ALTER MODEL statements with ****** before it saves the statement or sends it to the model. If your data must not leave your network, use a model that you host yourself, with the ollama or openai-compatible provider.

The model can’t run statements. It returns only text, a question, or a statement. Statements run only when a user runs them, or when Auto-accept runs a read-only statement, and they always run with the permissions of that user.

CMF stores conversations, including their results, in the CMF database. When you delete an environment, CMF deletes its conversations.

REST API

The CMF UI uses REST endpoints under /cmf/api/v1alpha1/environments/{envName}/sql-assistant/. These endpoints are versioned as v1alpha1 and might change in any release. The SQL Assistant is not available in the Confluent CLI.