Replicas cloud agents can use ClickHouse to answer questions about your data, investigate slow queries, and fix the code behind them. Connect the ClickHouse plugin, give an agent a specific question, and ask it to return the SQL and evidence alongside its answer.
With the relevant repository in the same workspace, the agent can follow a query back to the application that produces it. You can also connect Google Docs for reports and use Replicas automations for recurring analysis.
This guide covers setup and five workflows you can try with your own database. Replace the bracketed details with your tables, metric definitions, dates, and repository links.
1. Connect ClickHouse
- Open the Replicas environment you want to use and select its Plugins tab.
- Install ClickHouse and enter your HTTPS endpoint, username, password, and optional database.
- Use a database account with access to the tables needed for your task. For analysis, a read-only account is a useful starting point.
- Start a workspace using that environment. Include the relevant repository if you want the agent to investigate application code.
See the plugin setup documentation for connection details and the environment guide for repository setup.
Start with a small task to confirm access:
The connection uses your database account's permissions. Access to application tables does not necessarily include the system tables needed for query diagnostics.
2. Answer a product analytics question
Give the agent the definition of the metric you care about. “Active users” might mean users who signed in, sent a message, or completed a purchase. A query can run successfully and still answer the wrong question.
Review the metric definition and SQL together. Keep the time range and exclusions in the report so someone can reproduce the result later. If the schema cannot identify internal accounts, the report should say that the exclusion was unavailable.
3. Investigate a change in your data
A drop in reported usage could come from customer behavior, delayed ingestion, or a change in event tracking. Give Replicas a baseline and ask it to test those explanations against the available data and code.
Repository access helps connect a data change to a tracking change. For example, a renamed event may explain why an existing report stopped counting an action. A deployment near the start of a decline is a lead to investigate; the timing alone does not establish the cause.
4. Investigate slow queries
When available to your account, ClickHouse's query log provides execution details such as duration, rows read, bytes read, and memory usage. Ask the agent to establish which servers and time period the available logs cover before ranking queries. In ClickHouse Cloud, query logs are stored per node, so inspecting one node can give an incomplete view.
Execution count matters alongside individual query duration. A moderately slow query called thousands of times may deserve attention before an occasional long report. If logging is sampled or records have expired, ask the agent to explain how that limits the comparison.
5. Turn a finding into a tested code change
Once you have a specific query to improve, use a workspace with the application repository and a development dataset. Give the agent the expected result as well as the performance problem.
Check result equivalence before accepting a speedup. A faster query that drops records or changes a reporting boundary needs correction. If the improvement requires a different table layout, have the agent prepare a separate migration proposal with the affected queries and a validation plan.
6. Schedule a recurring report
After an analysis produces a useful result, save the prompt as a Replicas automation. Choose the environment with ClickHouse installed and a schedule that matches your reporting period. Add the Google Docs plugin if you want each run to create a document.
Run the automation once and check the report's dates, definitions, and document links. Keep those definitions in the saved prompt so future reports measure the same thing. When a report finds a change worth investigating, use its SQL and time range to start a focused follow-up workspace.