# How to use ClickHouse with Replicas Use cloud agents with ClickHouse in Replicas to analyze data, investigate slow queries, prepare tested code changes, and automate recurring reports. - Author: Connor Loi - Published: 2026-09-11 - Category: Best practices - Canonical: https://replicas.dev/blog/how-to-use-clickhouse-with-replicas 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 1. Open the Replicas **environment** you want to use and select its **Plugins** tab. 2. Install **ClickHouse** and enter your HTTPS endpoint, username, password, and optional database. 3. Use a database account with access to the tables needed for your task. For analysis, a read-only account is a useful starting point. 4. Start a workspace using that environment. Include the relevant repository if you want the agent to investigate application code. See the [plugin setup documentation](https://docs.replicas.dev/features/plugins) for connection details and the [environment guide](https://docs.replicas.dev/features/environments) for repository setup. Start with a small task to confirm access: ```text Check that you can connect to ClickHouse and inspect [database]. List the tables and columns you can access, and identify which tables look relevant to [product events / request logs / usage data]. Explain what you can establish from the schema and what still needs confirmation. Leave the database unchanged. ``` 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. ```text Using [database and event table], calculate weekly active users for [start date] through [end date], using [timezone]. An active user is a distinct [user ID column] who completed [event name]. Exclude [internal accounts / test organizations] using [documented rule]. Check the column types and event values before writing the query. Show the weekly totals, a chart, and the SQL used to produce them. Identify partial weeks and any assumptions about duplicate events or missing identifiers. Use read-only queries. ``` 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. ```text Investigate the drop in [metric] between [baseline period] and [comparison period]. Use [metric definition] and [timezone]. Break down the change by [relevant dimensions]. Check whether the periods are equally complete and whether event volume or missing fields changed. If ingestion timestamps are available, compare them with event timestamps to check for delayed data. Inspect [repository] for changes to the code that emits these events. Return the SQL, the strongest findings, and the evidence for each. Separate confirmed observations from possible explanations. Leave production data unchanged. ``` 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](https://clickhouse.com/docs/reference/system-tables/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. ```text Investigate slow queries for [application or database] during [start time] through [end time]. Check access to the query log and report which nodes and time range the available records cover. Group similar completed queries. Show execution count, median and p95 duration, total duration, rows and bytes read, and memory usage. Report failed queries separately and explain how distributed query records were handled so the totals do not double-count work. For the three most significant query patterns, inspect the relevant table definitions and explain the likely source of the cost. Return the diagnostic SQL and proposed next steps. Do not change tables, settings, or application code during this investigation. ``` 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. ```text Investigate [query or finding] in [repository and service]. The query should return [expected result and edge cases]. Trace where the application constructs and runs it. Make a focused code change, then compare the original and revised results against [development dataset]. Include empty results, duplicate events, and time boundaries where they affect correctness. Measure both versions against the same data and settings. Report the timings, rows and bytes read, and any cache or environment limits that affect the comparison. Run the relevant application checks. Open a pull request explaining the change and verification. Do not apply production schema changes. ``` 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](https://docs.replicas.dev/features/automations). 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. ```text Every Monday, report [metrics and definitions] for the previous complete Monday-to-Sunday week in [timezone]. Use [database and tables] and compare with the preceding complete week. Create a dated Google Doc with the totals, changes, charts, and SQL. Check data freshness using [ingestion timestamp or freshness rule]. Flag incomplete data before interpreting a change. If a query fails, report the failure rather than treating the missing result as zero. Add the report link to [tracking Doc]. Leave ClickHouse data unchanged. ``` 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.