# 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 1. Open the CMF UI. For details, see [Configure the Confluent Manager for Apache Flink UI](../../installation/ui.md#cmf-ui-config). 2. Select an environment. 3. 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](#cmf-sql-assistant-configure). 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](../../configure/compute-pools.md#cmf-compute-pools). ### 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](features-support.md#flink-sql-features-support). 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](manage-statements.md#flink-sql-statements-manage). 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](#cmf-sql-assistant-write-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](../../configure/environment-catalog.md#cmf-environment-catalog). - 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](ai/forecast.md#af-cp-forecast) and [Anomaly Detection with Confluent Manager for Apache Flink](ai/detect-anomalies.md#af-cp-anomaly-detection). 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](../../installation/helm.md#install-cmf-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`: ```yaml # sql-assistant-values.yaml cmf: sql: assistant: enabled: true ``` ```bash helm upgrade --install cmf confluentinc/confluent-manager-for-apache-flink \ --version "~2.5.0" \ -f sql-assistant-values.yaml \ --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. 1. Create a Kubernetes `Secret` that holds the API key of the model provider. Create the `Secret` in the namespace where CMF runs: ```bash kubectl create secret generic cmf-sql-assistant-llm \ --from-literal=api-key= \ --namespace ``` 2. Add the model and select it for the SQL Assistant: ```yaml # 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 ``` 3. Upgrade your CMF release: ```bash helm upgrade --install cmf confluentinc/confluent-manager-for-apache-flink \ --version "~2.5.0" \ -f sql-assistant-values.yaml \ --namespace ``` 4. 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: ```bash kubectl rollout restart deployment/confluent-manager-for-apache-flink \ --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. ```yaml 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.` 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](#cmf-sql-assistant-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)](../../configure/access-control.md#cmf-access-control) 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-`: ```bash 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](../../configure/access-control.md#cmf-access-control-compute-pools). For how prefixes match resource names, see [Resource name matching](../../configure/access-control.md#cmf-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. ## Related content - [Configure the Confluent Manager for Apache Flink UI](../../installation/ui.md#cmf-ui-config) - [Use the Interactive CLI SQL Shell with Confluent Manager for Apache Flink](use-interactive-shell.md#flink-sql-statements-interactive-cli) - [Manage Statements in Confluent Manager for Apache Flink](manage-statements.md#flink-sql-statements-manage) - [Configure Access Control for Confluent Manager for Apache Flink](../../configure/access-control.md#cmf-access-control)