{"id":13696334,"url":"https://github.com/grafana/clickhouse-datasource","last_synced_at":"2025-10-07T09:59:02.785Z","repository":{"id":37457433,"uuid":"427493431","full_name":"grafana/clickhouse-datasource","owner":"grafana","description":"Grafana Plugin for ClickHouse","archived":false,"fork":false,"pushed_at":"2025-10-03T14:15:12.000Z","size":5573,"stargazers_count":184,"open_issues_count":61,"forks_count":88,"subscribers_count":137,"default_branch":"main","last_synced_at":"2025-10-04T21:38:00.708Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-11-12T20:52:24.000Z","updated_at":"2025-10-02T17:39:01.000Z","dependencies_parsed_at":"2023-11-14T20:27:25.542Z","dependency_job_id":"2e38b91a-6af8-4c94-92a5-79590f1e14d8","html_url":"https://github.com/grafana/clickhouse-datasource","commit_stats":{"total_commits":452,"total_committers":46,"mean_commits":9.826086956521738,"dds":0.5973451327433628,"last_synced_commit":"7b50309aefba12ef9f2b980e2f9f255001b98db0"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":"grafana/grafana-starter-datasource-backend","purl":"pkg:github/grafana/clickhouse-datasource","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fclickhouse-datasource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fclickhouse-datasource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fclickhouse-datasource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fclickhouse-datasource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/clickhouse-datasource/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fclickhouse-datasource/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278755161,"owners_count":26040034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-02T18:00:38.555Z","updated_at":"2025-10-07T09:59:02.738Z","avatar_url":"https://github.com/grafana.png","language":"TypeScript","funding_links":[],"categories":["Integrations"],"sub_categories":["Data Visualization and Analysis"],"readme":"# Official ClickHouse data source for Grafana\n\nThe ClickHouse data source plugin allows you to query and visualize ClickHouse data in Grafana.\n\n\u003cimg alt=\"Grafana Dashboard Screenshot - Query Analysis\" src=\"https://github.com/grafana/clickhouse-datasource/assets/5509570/d129936e-afac-4002-8963-61c15825c154\" width=\"400\" \u003e\n\n\u003cimg alt=\"Grafana Dashboard Screenshot - Data Analysis\" src=\"https://github.com/grafana/clickhouse-datasource/assets/5509570/5911f72b-0a52-4e1e-9cd4-3905ac0623cd\" width=\"400\" \u003e\n\n## Version compatibility\n\nUsers on Grafana `v9.x` and higher of Grafana can use `v4`.\nUsers on Grafana `v8.x` are encouraged to continue using `v2.2.0` of the plugin.\n\n\n\\* *As of 2.0 this plugin will only support ad hoc filters when using ClickHouse 22.7+*\n\n## Installation\n\nFor detailed instructions on how to install the plugin on Grafana Cloud or locally,\nplease checkout the [Plugin installation docs](https://grafana.com/docs/grafana/latest/plugins/installation/).\n\n## Configuration\n\n### ClickHouse user for the data source\n\nSet up an ClickHouse user account with [readonly](https://clickhouse.com/docs/en/operations/settings/permissions-for-queries#settings_readonly) permission and access to\ndatabases and tables you want to query.\nPlease note that Grafana does not validate that queries are safe. Queries can contain any SQL statement.\nFor example, statements like `ALTER TABLE system.users DELETE WHERE name='sadUser'`\nand `DROP TABLE sadTable;` would be executed.\n\nTo configure a readonly user, follow these steps:\n1. Create a `readonly` user profile following the [Creating Users and Roles in ClickHouse](https://clickhouse.com/docs/en/operations/access-rights) guide.\n2. Ensure the `readonly` user has enough permission to modify the `max_execution_time` setting required by the underlying [clickhouse-go client](https://github.com/ClickHouse/clickhouse-go/).\n3. If you're using a public Clickhouse instance, it's not recommended to set `readonly=2` in the `readonly` profile. Instead, leave `readonly=1` and set the constraint type of `max_execution_time` to [changeable_in_readonly](https://clickhouse.com/docs/en/operations/settings/constraints-on-settings) to allow modification of this setting.\n\n### ClickHouse protocol support\n\nThe plugin supports both `Native` (default) and `HTTP` transport protocols.\nThis can be enabled in the configuration via the `protocol` configuration parameter.\nBoth protocols exchange data with ClickHouse using optimized native format.\n\nNote that the default ports for `HTTP/S` and `Native` differ:\n\n- HTTP - 8123\n- HTTPS - 8443\n- Native - 9000\n- Native with TLS - 9440\n\n### Manual configuration via UI\n\nOnce the plugin is installed on your Grafana instance, follow\n[these instructions](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)\nto add a new ClickHouse data source, and enter configuration options.\n\n### With a configuration file\n\nIt is possible to configure data sources using configuration files with Grafana’s provisioning system.\nTo read about how it works, refer to\n[Provisioning Grafana data sources](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).\n\nHere are some provisioning examples for this data source using basic authentication:\n\n```yaml\napiVersion: 1\ndatasources:\n  - name: ClickHouse\n    type: grafana-clickhouse-datasource\n    jsonData:\n      defaultDatabase: database\n      port: 9000\n      host: localhost\n      username: username\n      tlsSkipVerify: false\n      # tlsAuth: \u003cbool\u003e\n      # tlsAuthWithCACert: \u003cbool\u003e\n      # secure: \u003cbool\u003e\n      # dialTimeout: \u003cseconds\u003e\n      # queryTimeout: \u003cseconds\u003e\n      # protocol: \u003cnative|http\u003e\n      # defaultTable: \u003cstring\u003e\n      # httpHeaders:\n      # - name: X-Example-Header\n      #   secure: false\n      #   value: \u003cstring\u003e\n      # - name: Authorization\n      #   secure: true\n      # logs:\n      #   defaultDatabase: \u003cstring\u003e\n      #   defaultTable: \u003cstring\u003e\n      #   otelEnabled: \u003cbool\u003e\n      #   otelVersion: \u003cstring\u003e\n      #   timeColumn: \u003cstring\u003e\n      #   ...Column: \u003cstring\u003e\n      # traces:\n      #   defaultDatabase: \u003cstring\u003e\n      #   defaultTable: \u003cstring\u003e\n      #   otelEnabled: \u003cbool\u003e\n      #   otelVersion: \u003cstring\u003e\n      #   durationUnit: \u003cseconds|milliseconds|microseconds|nanoseconds\u003e\n      #   traceIdColumn: \u003cstring\u003e\n      #   ...Column: \u003cstring\u003e\n    secureJsonData:\n      password: password\n      # tlsCACert: \u003cstring\u003e\n      # tlsClientCert: \u003cstring\u003e\n      # tlsClientKey: \u003cstring\u003e\n      # secureHttpHeaders.Authorization: \u003cstring\u003e\n```\n\n## Building queries\n\nQueries can be built using the raw SQL editor or the query builder.\nQueries can contain macros which simplify syntax and allow for\ndynamic SQL generation.\n\n### Time series\n\nTime series visualization options are selectable after adding a `datetime`\nfield type to your query. This field will be used as the timestamp. You can\nselect time series visualizations using the visualization options. Grafana\ninterprets timestamp rows without explicit time zone as UTC. Any column except\n`time` is treated as a value column.\n\n#### Multi-line time series\n\nTo create multi-line time series, the query must return at least 3 fields in\nthe following order:\n- field 1:  `datetime` field with an alias of `time`\n- field 2:  value to group by\n- field 3+: the metric values\n\nFor example:\n```sql\nSELECT log_time AS time, machine_group, avg(disk_free) AS avg_disk_free\nFROM mgbench.logs1\nGROUP BY machine_group, log_time\nORDER BY log_time\n```\n\n### Tables\n\nTable visualizations will always be available for any valid ClickHouse query.\n\n### Visualizing logs with the Logs Panel\n\nTo use the Logs panel your query must return a timestamp and string values. To default to the logs visualization in Explore mode, set the timestamp alias to *log_time*.\n\nFor example:\n```sql\nSELECT log_time AS log_time, machine_group, toString(avg(disk_free)) AS avg_disk_free\nFROM logs1\nGROUP BY machine_group, log_time\nORDER BY log_time\n```\n\nTo force rendering as logs, in absence of a `log_time` column, set the Format to `Logs` (available from 2.2.0).\n\n### Visualizing traces with the Traces Panel\n\nEnsure your data meets the [requirements of the traces panel](https://grafana.com/docs/grafana/latest/explore/trace-integration/#data-api). This applies if using the visualization or Explore view.\n\nSet the Format to `Trace` when constructing the query (available from 2.2.0).\n\nIf using the [Open Telemetry Collector and ClickHouse exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter), the following query produces the required column names (these are case sensitive):\n\n```sql\nSELECT\n  TraceId AS traceID,\n  SpanId AS spanID,\n  SpanName AS operationName,\n  ParentSpanId AS parentSpanID,\n  ServiceName AS serviceName,\n  Duration / 1000000 AS duration,\n  Timestamp AS startTime,\n  arrayMap(key -\u003e map('key', key, 'value', SpanAttributes[key]), mapKeys(SpanAttributes)) AS tags,\n  arrayMap(key -\u003e map('key', key, 'value', ResourceAttributes[key]), mapKeys(ResourceAttributes)) AS serviceTags,\n  if(StatusCode IN ('Error', 'STATUS_CODE_ERROR'), 2, 0) AS statusCode\nFROM otel.otel_traces\nWHERE TraceId = '61d489320c01243966700e172ab37081'\nORDER BY startTime ASC\n```\n\n### Macros\n\nTo simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.\n\nHere is an example of a query with a macro that will use Grafana's time filter:\n```sql\nSELECT date_time, data_stuff\nFROM test_data\nWHERE $__timeFilter(date_time)\n```\n\n| Macro                                        | Description                                                                                                                                                                         | Output example                                                                                        |\n|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|\n| *$__dateFilter(columnName)*                  | Replaced by a conditional that filters the data (using the provided column) based on the date range of the panel                                                                    | `date \u003e= toDate('2022-10-21') AND date \u003c= toDate('2022-10-23')`                                       |\n| *$__timeFilter(columnName)*                  | Replaced by a conditional that filters the data (using the provided column) based on the time range of the panel in seconds                                                         | `time \u003e= toDateTime(1415792726) AND time \u003c= toDateTime(1447328726)`                                   |\n| *$__timeFilter_ms(columnName)*               | Replaced by a conditional that filters the data (using the provided column) based on the time range of the panel in milliseconds                                                    | `time \u003e= fromUnixTimestamp64Milli(1415792726123) AND time \u003c= fromUnixTimestamp64Milli(1447328726456)` |\n| *$__dateTimeFilter(dateColumn, timeColumn)*  | Shorthand that combines $__dateFilter() AND $__timeFilter() using separate Date and DateTime columns.                                                                               | `$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)`                                             |\n| *$__fromTime*                                | Replaced by the starting time of the range of the panel casted to `DateTime`                                                                                                        | `toDateTime(1415792726)`                                                                              |\n| *$__toTime*                                  | Replaced by the ending time of the range of the panel casted to `DateTime`                                                                                                          | `toDateTime(1447328726)`                                                                              |\n| *$__fromTime_ms*                             | Replaced by the starting time of the range of the panel casted to `DateTime64(3)`                                                                                                   | `fromUnixTimestamp64Milli(1415792726123)`                                                             |\n| *$__toTime_ms*                               | Replaced by the ending time of the range of the panel casted to `DateTime64(3)`                                                                                                     | `fromUnixTimestamp64Milli(1447328726456)`                                                             |\n| *$__interval_s*                              | Replaced by the interval in seconds                                                                                                                                                 | `20`                                                                                                  |\n| *$__timeInterval(columnName)*                | Replaced by a function calculating the interval based on window size in seconds, useful when grouping                                                                               | `toStartOfInterval(toDateTime(column), INTERVAL 20 second)`                                           |\n| *$__timeInterval_ms(columnName)*             | Replaced by a function calculating the interval based on window size in milliseconds, useful when grouping                                                                          | `toStartOfInterval(toDateTime64(column, 3), INTERVAL 20 millisecond)`                                 |\n| *$__conditionalAll(condition, $templateVar)* | Replaced by the first parameter when the template variable in the second parameter does not select every value. Replaced by the 1=1 when the template variable selects every value. | `condition` or `1=1`                                                                                  |\n\nThe plugin also supports notation using braces {}. Use this notation when queries are needed inside parameters.\n\n\n### Templates and variables\n\nTo add a new ClickHouse query variable, refer to [Add a query\nvariable](https://grafana.com/docs/grafana/latest/variables/variable-types/add-query-variable/).\n\nAfter creating a variable, you can use it in your ClickHouse queries by using\n[Variable syntax](https://grafana.com/docs/grafana/latest/variables/syntax/).\nFor more information about variables, refer to [Templates and\nvariables](https://grafana.com/docs/grafana/latest/variables/).\n\n### Importing dashboards for ClickHouse\n\nFollow these\n[instructions](https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard)\nto import a dashboard.\n\nYou can also find available, pre-made dashboards by navigating to the data\nsources configuration page, selecting the ClickHouse data source and clicking\non the Dashboards tab.\n\nWe distribute the following dashboards with the plugin. These are aimed at assisting with support analysis of a ClickHouse cluster and do not rely on external datasets. The querying user requires access to the `system` database.\n\n1. Cluster Analysis - an overview of configured clusters, merges, mutations and data replication.\n2. Data Analysis - an overview of current databases and tables, including their respective sizes, partitions and parts.\n3. Query Analysis - an analysis of queries by type, performance and resource consumption.\n\n### Ad Hoc Filters\n\nAd hoc filters are only supported with version 22.7+ of ClickHouse.\n\nAd hoc filters allow you to add key/value filters that are automatically added\nto all metric queries that use the specified data source, without being\nexplicitly used in queries.\n\nBy default, Ad Hoc filters will be populated with all Tables and Columns.  If\nyou have a default database defined in the Datasource settings, all Tables from\nthat database will be used to populate the filters. As this could be\nslow/expensive, you can introduce a second variable to allow limiting the\nAd Hoc filters. It should be a `constant` type named `clickhouse_adhoc_query`\nand can contain: a comma delimited list of databases, just one database, or a\ndatabase.table combination to show only columns for a single table.\n\nFor more information on Ad Hoc filters, check the [Grafana\ndocs](https://grafana.com/docs/grafana/latest/variables/variable-types/add-ad-hoc-filters/)\n\n#### Using a query for Ad Hoc filters\n\nThe second `clickhouse_adhoc_query` also allows any valid Clickhouse query. The\nquery results will be used to populate your ad-hoc filter's selectable filters.\nYou may choose to hide this variable from view as it serves no further purpose.\n\nFor example, if `clickhouse_adhoc_query` is set to `SELECT DISTINCT\nmachine_name FROM mgbench.logs1` you would be able to select which machine\nnames are filtered for in the dashboard.\n\n## Learn more\n\n* Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/).\n* Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/).\n* Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/).\n* Set up alerting; refer to [Alerts overview](https://grafana.com/docs/grafana/latest/alerting/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fclickhouse-datasource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fclickhouse-datasource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fclickhouse-datasource/lists"}