Features

ClickLens provides a comprehensive suite of tools for managing and monitoring ClickHouse databases. This guide covers all major features and how to use them.

1. Discover (Kibana-like Data Exploration)

The Discover feature provides a flexible, Kibana-style interface for exploring data in any ClickHouse table—not just logs.

1.1. Components

1.1.1. Database & Table Selection

Use the dropdowns in the header to select your data source:

• ① Database Selector: Choose from available databases
• ② Table Selector: Shows tables with their engine type (e.g., MergeTree, ReplicatedMergeTree)

1.1.2. Fields Sidebar

The ④ left sidebar controls which columns appear in your query:

• Search: Filter columns by name
• Select All / None: Quick selection toggles
• Time Column Picker: Choose which DateTime column to use for time filtering
• Type Icons: Visual indicators for column types (DateTime, String, Number, Boolean)

1.1.3. Query Bar

③ Query Bar allows user to enter custom ClickHouse WHERE clause expressions:

level = 'Error'
status >= 400
host LIKE '%api%'
message ILIKE '%timeout%'
level IN ('Error', 'Fatal')

Features:

• Query History: Persisted in localStorage (up to 20 entries)
• Syntax Help: Hover over the help icon for examples
• Execute: Press Enter or click Search

1.1.4. Time Range Selector

Filter data by time using presets:

• 5m, 15m, 30m (minutes)
• 1h, 3h, 6h, 12h, 24h (hours)
• 3d, 7d (days)

1.1.5. Histogram

When a time column is selected, a bar chart shows document distribution over time:

• Click a bar to zoom into that time range
• Reset Zoom button to return to the selected preset

1.1.6. Results Grid

• Row Count: Shows "X of Y hits"
• Row Detail: Click any row to see all fields in a slide-out panel
• Load More: Offset-based pagination for large result sets

2. SQL Console

A full-featured SQL editor for writing and executing ClickHouse queries.

• ① Database selector: Choose from available databases
• ② Table selector: Shows tables with their engine type (e.g., MergeTree, ReplicatedMergeTree)
• ③ SQL editor: User can enter the query here, ClickLens could help with autocomplete and syntax highlighting.
• ④ Execution modes: Control how ClickLens enter the input queries.

2.1. Key Features

2.1.1. Multi-Tab Support

• Open multiple query tabs simultaneously
• Tabs are persisted locally (SQL content survives browser refresh)
• Each tab maintains its own result set and history

2.1.2. SQL Editor

Built on CodeMirror 6 with ClickHouse-specific enhancements:

• Syntax Highlighting: Keywords, functions, strings, numbers
• Context-Aware Autocomplete:
  • Keywords after FROM, JOIN → table suggestions
  • After USE, DATABASE → database suggestions
  • After table reference → column suggestions (async fetch)
  • Built-in functions and keywords
• Code Actions: Execute, Explain, Format

2.1.3. Execution Modes

2.1.4. Query Streaming

Large result sets are streamed to the UI using NDJSON:

• Progress indicator shows rows being fetched
• Results appear incrementally
• Cancel running queries with the Stop button

2.1.5. Explain Queries

Use the Explain dropdown to analyze query plans:

• AST: Abstract Syntax Tree
• SYNTAX: Normalized query syntax
• PLAN: Query execution plan
• PIPELINE: Processing pipeline visualization

2.1.6. Saved Queries

Save frequently-used queries for quick access:

• Click the Save icon to store a query
• Access saved queries from the Bookmarks panel
• Queries are stored server-side

2.1.7. Query History

The History panel shows recent executions with:

• SQL text
• Duration
• Rows returned / read
• Bytes read
• Memory usage
• User who ran it
• Errors (if any)

2.1.8. Time Range Insertion

Use the Time Range Selector to quickly insert time filter clauses into your SQL, properly handling the WHERE vs AND syntax.

2.1.9 Table preview

ClickLens also supports easy table preview feature. By clicking the table name in the sidebar, you can navigate this table's structure and data (only the first 100 rows).

3. Table Explorer

Browse and inspect your ClickHouse schema in detail.

3.1. Navigation

1. Select a database from the left sidebar
2. Click a table to view its details
3. Use the tabs to explore different aspects

3.2. Table Detail Tabs

4. Monitoring

Real-time cluster health and performance monitoring.

Available Tabs

• ① The Cluster status: shows the number of shards, replicas, as well as the cluster name.
• ② The Overall healthcheck: ClickLens performs multiple checks: uptime, readonly replicas, parts to check, max parts per partition, active queries, memory usage, and replication delay.
• ③ Multiple Graphs: these graphs are based on ClickHouse built-in advanced monitoring dashboards (opens in a new tab). ClickLens selects metrics following the ClickHouse operations documentation (opens in a new tab).

Because the demo cluster does not include ClickHouse Keeper/ZooKeeper, the screenshots show errors. This is expected behavior.

5. Query Analytics

Analyze query performance and identify slow queries.

5.1. Available Views

• ① Filter by user: Filters queries executed by a specific user.
• ② Filter by execution duration: Enter a minimum duration to show only queries that took longer.
• ③ Filter by query type: Filter by query type (INSERT, CREATE, SELECT, ALTER, DROP).
• ④ Filter by status: Filter by execution status ('Success' or 'Error').

5.2. Query Cancellation

• ① Refresh Control: Like other components (logging & monitoring), user can control the refresh behavior by using the Refresh Control. It's very similar to Grafana and Kibana.
• ② Kill action: From the Running Queries view, you can kill queries using the KILL QUERY command. This requires the canKillQueries permission.

6. Logging

View and search through ClickHouse logs.

• ① Time range: Select the time range for logs.
• ② Filter by log level: Filter to show only specific log levels (e.g., ERROR).
• ③ Filter by component: Enter a component name to filter logs.
• ④ Filter by message: Enter part of a message to search (uses WHERE LIKE '%string%').
• Live Mode: Auto-refresh uses efficient streaming to prepend only new logs.

The system.crash_log table does not exist in the database by default, it is created only when fatal errors occur.

7. Access Control

Manage ClickHouse users and roles.

In ClickHouse, Access control management is supported via RBAC approach. The entities that are part of ClickHouse RBAC are

• User Account – Identifies individual end users or applications that connect and access data in ClickHouse
• Role – Roles hold the information about privileges, settings, and constraints for the users
• Settings profile – Group of settings that will be applied to the user or a role
• Quotas – Limit the resource usage for a role or user over a period of time

The above illustration shows the access entities and the possible assignment of access entities among themselves. In ClickHouse, it is possible to

• Grant roles, settings profile, and any specific privilege to users
• Grant settings profile and any specific privilege to any role

While this approach can help in implementing RBAC, the strict enforcement of the Principle of Least Privilege is entirely in the hands of the database admin. This is because, let’s say, we have two users A and B, with the same role. They can end up having different sets of privileges and settings because it is possible to grant settings profiles and any specific privileges to individual users. We can enforce the upcoming RBAC approach to ensure consistency and strict implementation of the Principle of Least Privilege.

ClickLens chooses the different approach, simpler and more effective. This will ensure that we have a consistent set of privileges and enforce the Principle of Least Privilege effectively.

• We shall grant only the roles to users
• We shall grant privileges and settings profile to roles

Available views

User can view all ClickHouse's users here.

Create/Edit user and grant role(s).

View roles. There are two types of roles:

• ① Feature roles: System-managed roles that enable UI features. These are read-only and can be viewed by clicking on each role.

• ② Custom roles: User-created roles containing two types of permissions: inherited roles and data privileges. This allows for flexible role configuration.

8. Settings

View ClickHouse server and session settings.

Available views

9. Profile

Users can view their information and change the password.