AI API Keys

The AI API Keys page is where administrators configure the credentials for the AI providers that power Qurioz, the CHOps assistant that turns plain-English questions into ClickHouse® SQL. Without a valid, active credential on this page, Qurioz cannot reach a provider and the AI features stay dormant. Once you save a credential and make it active, anyone with access to Qurioz, and to the SQL Editor's Generate SQL button, can describe what they want in natural language and get back a ready-to-run query.

You reach the page from Control panel > AI API Keys. Only admins and super admins can open it and make changes. Other roles see the message "API key management is only available for administrators." A cloud AI provider key is a billable credential tied to your provider account, so managing it is an administrative action.

What is Qurioz?

Qurioz is CHOps's natural-language-to-SQL assistant. You type a question about your data the way you would ask a colleague, for example "show me the ten slowest queries from yesterday" or "daily insert volume per table for the last week", and Qurioz generates the ClickHouse® SQL. From there the flow mirrors the Chart Builder you already use: the generated SQL drops into an editor, you run it, pick a chart type, and save the result to a dashboard. The same engine also backs the Generate SQL button in the SQL Editor.

The goal is to shorten the path from a question to a chart. Instead of remembering the exact system table, the right aggregation, and ClickHouse®-specific functions, you describe the outcome and refine the SQL Qurioz proposes.

Qurioz is part of the free community edition. The only thing it needs is one active AI credential, configured here.

Supported providers

CHOps works with five AI providers. You choose the provider when you add a credential, provide the credential from that provider, and name the model you want to use.

Provider	What to select	Where to get a key	Typical credential
Google Gemini	GEMINI	Google AI Studio	`AIza...`
OpenAI	OPEN AI	OpenAI Platform	`sk-...`
Anthropic Claude	CLAUDE	Anthropic Console	`sk-ant-...`
Mistral	MISTRAL	Mistral Console	provider-specific
Ollama	OLLAMA	Runs on your own hardware	A base URL, such as `http://localhost:11434`

Ollama is different. It runs models on your own hardware, so there is no cloud account and no billing. Instead of an API key, you give the base URL of your Ollama server. CHOps can then list the models installed on that server, so you pick one rather than type it.

You use each cloud key with a model name that you supply as free text, because providers release and retire models often and CHOps does not hard-code a fixed list. Enter a current model string from your provider. The page shows example placeholders per provider to guide you:

Provider	Example model names (illustrative only)
Gemini	`gemini-2.5-flash`, `gemini-3.5-flash`
OpenAI	a current GPT model, for example a `mini` or `nano` variant
Claude	`claude-haiku-4-5`, `claude-sonnet-4-6`
Mistral	`mistral-large-latest`, `mistral-medium-latest`
Ollama	the models you have pulled locally, for example `llama3.2:latest`; CHOps lists them from your server

Always confirm the exact model string against your provider's documentation. A model name that the provider does not recognize is the most common reason a credential that is otherwise valid fails to generate SQL.

How keys are organized

A few rules shape how the page behaves, and they are worth knowing before you start.

Each entry has four parts: a name, a provider, a model name, and the secret value (an API key, or a base URL for Ollama).
Each name must be unique. CHOps ignores upper and lower case when it compares names. Two entries can use the same provider if their names are different.
You can store up to 5 keys. The server refuses a sixth key with the error "Maximum 5 API keys allowed." When you have 5 keys, the page does not show the Add API Key button.
Only one credential is active at a time. The active one is the single credential Qurioz and the SQL Editor use for every request. The others sit ready but idle until you activate them.
The first credential you add becomes active automatically. After that, activating a different one takes a deliberate click.
Deleting the active credential promotes another. If you delete whichever one is active, CHOps makes one of the remaining ones active, so Qurioz keeps working.

So switching providers is just a matter of activating a different saved credential. There is no restart and no config file to edit.

Adding a key

Go to Control panel > AI API Keys.
Click Add API Key. This button shows when you have fewer than 5 keys.
Enter a Name for the entry. The name can have up to 100 characters.
Select the AI Provider from the dropdown: GEMINI, OPEN AI, MISTRAL, CLAUDE, or OLLAMA.
Provide the credential in API Key Value. For a cloud provider, paste the API key. For Ollama, enter the base URL of your Ollama server in Ollama Base URL.
Enter the model name for that provider (see the examples above). For Ollama, click Fetch Models and select a model from the list. This field is required.
Click Verify AI API Key to check that the credential works (see the next section).
Click Save Key. This button is available only after a successful verification. If this is your first credential, it becomes active at once. Otherwise CHOps saves it as an inactive option you can activate later.

The name, provider, model, and value are all required. The server refuses an entry with an empty field.

Fetch Models and Ollama addresses. The Ollama base URL must start with http:// or https://. To fetch the model list, the address must be localhost, 127.0.0.1, or a public host. CHOps refuses other private and local network addresses.

Testing an API key

CHOps can check a credential against its provider before you commit to it, so you find out at once whether it works, rather than at the first question someone asks Qurioz.

What the Verify AI API Key button does. When you click Verify AI API Key, CHOps takes the provider, model, and value in the form and makes a real, minimal request to that provider. It sends a tiny prompt and waits for any reply. If the provider responds, the test reports the credential as active. If the provider rejects the request, or the model is unrecognized, the test shows the reason, for example an authentication failure or a rate limit. Testing does not save the credential or change which one is active. It only checks reachability.

Verify before you save. The page enables Save Key only after a successful verification. A passing test confirms three things at once: the credential is valid, the model name is spelled correctly and available to your account, and your provider account is in good standing (not rate-limited or blocked).

What a failed test usually means. A failure almost always comes down to one of these: a wrong or revoked key, a model name the provider does not recognize for your account, a provider account with no active billing, or a temporary rate limit. For Ollama, a failure usually means the base URL is wrong or the server is unreachable. The troubleshooting table maps the symptoms to fixes.

Switching the active provider

With more than one credential saved, the page lists each one under Saved API Keys and marks the active one with Active. To change which provider Qurioz uses, click Set as active on a different one. That credential at once becomes the one behind every Qurioz request and every SQL Editor Generate SQL action. Nothing else needs to change, and users do not reconnect or reload.

This makes it easy, for example, to keep a fast and inexpensive model active for everyday use and switch to a more capable model only for harder questions, or to fail over to a second provider if your primary one has an outage.

Editing and deleting keys

Edit (Edit key) a saved credential to change its name, provider, model name, or value, for example after you rotate the key at the provider. Click Verify AI API Key again, then click Update Key.
Delete (Delete key) a credential you no longer use. Confirm the delete in the Confirm Delete dialog. If it was the active one, CHOps promotes another automatically. If it was your only one, Qurioz goes dormant until you add a new one.

The server checks that a key exists before it edits, deletes, activates, or reveals it. If the key does not exist, for example because another admin deleted it, CHOps shows the error "API key not found." Reload the page to see the current list.

How the key is stored

CHOps encrypts every AI provider credential with AES-256-GCM before it writes it to its SQLite database, the same encryption it applies to ClickHouse® connection passwords. The encryption key is derived from your ENCRYPTION_SECRET, so the database file on its own is not enough to read a stored credential. If you rotate ENCRYPTION_SECRET, the credentials stored before can no longer be decrypted and you must re-enter them, exactly as you would re-enter ClickHouse® credentials.

For day-to-day use, the secret value never leaves the server. Qurioz calls the provider from the CHOps backend, and ordinary status checks (such as which provider is active) return only the provider name and model, never the value. The decrypted value is available only to admin-level users, through the explicit "reveal" endpoints the page uses to pre-fill an edit form. Treat the ability to open this page as equivalent to holding the credentials.

The Qurioz workflow

Once an active credential is configured, the end-to-end flow looks like this:

Open Qurioz, or use Generate SQL in the SQL Editor, and type a question in plain language.
Qurioz sends your question, with the relevant schema context, to the active provider and receives a ClickHouse® SQL statement.
The generated SQL appears in an editor. You can read it, edit it, and run it.
Run the query to see the results.
Choose a chart type and mapping, then save the chart to a dashboard.

Because CHOps always shows the generated SQL before it runs, you stay in control. Qurioz proposes, and you decide whether to run, adjust, or discard.

Good practices

Treat every cloud key as a secret. Gemini, OpenAI, Claude, and Mistral bill for usage. Anyone who extracts an active key could run up charges on your account. Ollama runs locally and does not bill, but still protect its endpoint.
Use a dedicated provider project. Create the key under a project or workspace you use only for CHOps, so its usage and billing are easy to track and cap.
Set spending limits at the provider. Configure quotas or budget alerts with your cloud provider, so an unexpected spike in Qurioz usage cannot produce a surprise bill.
Verify after every change. CHOps asks for a verification when you add or edit a credential. Also run a short Qurioz question after you switch the active one.
Always review generated SQL before you run it. Qurioz proposes queries, but you are responsible for what runs against your cluster. Read the SQL, especially for anything beyond a SELECT.
Rotate keys from time to time, and at once if you suspect a leak. Generate a new key at the provider, update it here, test it, and revoke the old one at the provider.

Troubleshooting

Symptom	Likely cause	Fix
Qurioz says AI is not configured	No credential saved, or none is active	Add a credential on this page, activate it, and confirm the test passes.
Verification fails with an authentication error	The key is wrong, revoked, or does not match the selected provider	Generate a fresh key at the provider's console, make sure the provider dropdown matches, and re-enter it.
Verification passes but generation fails on a real question	The provider does not recognize the model name for your account	Correct the model string to a current model your provider account can use, then re-test.
Verification or generation fails with a rate-limit or quota error	The provider account hit a usage limit	Wait and retry, or raise quotas and check billing at the provider.
Ollama verification fails to connect	The base URL is wrong, or the Ollama server is not running or not reachable	Check the base URL and that the Ollama server is up and reachable from the CHOps server.
Provider reports "service unavailable"	A temporary provider outage or high demand	Retry later, or switch the active credential to a different provider.
"Unsupported AI provider"	The saved provider is not one of the five supported options	Recreate the credential using GEMINI, OPEN AI, CLAUDE, MISTRAL, or OLLAMA.
A key worked before but stopped after maintenance	Someone changed `ENCRYPTION_SECRET`, so CHOps can no longer decrypt the stored credentials	Re-enter each AI credential on this page and re-test.
Generated SQL references missing tables or looks wrong	The model lacked enough schema context or misread the request	Rephrase the question more specifically, or edit the SQL by hand before you run it.