| 1 | # Database Query Functions |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | Database query functions provide deep visibility into SQL and NoSQL database performance through Netdata's Live tab. They help you identify problematic queries, detect deadlocks, and understand error patterns—all from the Netdata dashboard. |
| 6 | |
| 7 | | Capability | Description | |
| 8 | |------------------------|----------------------------------------------------------------------------------------------| |
| 9 | | **Top Queries** | Identify the most expensive queries by execution time, I/O, rows processed, or other metrics | |
| 10 | | **Running Queries** | See currently executing queries in real-time | |
| 11 | | **Deadlock Detection** | View the latest detected deadlock with full transaction details | |
| 12 | | **Error Attribution** | Correlate SQL errors with the queries that caused them | |
| 13 | |
| 14 | ## Supported Databases |
| 15 | |
| 16 | | Database | Top Queries | Running Queries | Deadlock Info | Error Info | Integration Docs | |
| 17 | |----------------------|:-----------:|:---------------:|:-------------:|:----------:|--------------------------------------------------------------------------------------------| |
| 18 | | ClickHouse | ✅ | - | - | - | [ClickHouse](/src/go/plugin/go.d/collector/clickhouse/integrations/clickhouse.md) | |
| 19 | | CockroachDB | ✅ | ✅ | - | - | [CockroachDB](/src/go/plugin/go.d/collector/cockroachdb/integrations/cockroachdb.md) | |
| 20 | | Couchbase | ✅ | - | - | - | [Couchbase](/src/go/plugin/go.d/collector/couchbase/integrations/couchbase.md) | |
| 21 | | Elasticsearch | ✅ | - | - | - | [Elasticsearch](/src/go/plugin/go.d/collector/elasticsearch/integrations/elasticsearch.md) | |
| 22 | | MongoDB | ✅ | - | - | - | [MongoDB](/src/go/plugin/go.d/collector/mongodb/integrations/mongodb.md) | |
| 23 | | Microsoft SQL Server | ✅ | - | ✅ | ✅* | [MSSQL](/src/go/plugin/go.d/collector/mssql/integrations/microsoft_sql_server.md) | |
| 24 | | MySQL | ✅ | - | ✅ | ✅* | [MySQL](/src/go/plugin/go.d/collector/mysql/integrations/mysql.md) | |
| 25 | | MariaDB | ✅ | - | ✅ | ✅* | [MariaDB](/src/go/plugin/go.d/collector/mysql/integrations/mariadb.md) | |
| 26 | | Percona Server | ✅ | - | ✅ | ✅* | [Percona](/src/go/plugin/go.d/collector/mysql/integrations/percona_mysql.md) | |
| 27 | | Oracle Database | ✅ | ✅ | - | - | [Oracle](/src/go/plugin/go.d/collector/oracledb/integrations/oracle_db.md) | |
| 28 | | PostgreSQL | ✅ | ✅ | - | ✅** | [PostgreSQL](/src/go/plugin/go.d/collector/postgres/integrations/postgresql.md) | |
| 29 | | ProxySQL | ✅ | - | - | - | [ProxySQL](/src/go/plugin/go.d/collector/proxysql/integrations/proxysql.md) | |
| 30 | | Redis | ✅ | - | - | - | [Redis](/src/go/plugin/go.d/collector/redis/integrations/redis.md) | |
| 31 | | RethinkDB | - | ✅ | - | - | [RethinkDB](/src/go/plugin/go.d/collector/rethinkdb/integrations/rethinkdb.md) | |
| 32 | | YugabyteDB | ✅ | ✅ | - | - | [YugabyteDB](/src/go/plugin/go.d/collector/yugabytedb/integrations/yugabytedb.md) | |
| 33 | |
| 34 | *\* Error Info is integrated directly into Top Queries results—each query row shows its associated errors.* |
| 35 | |
| 36 | *\*\* PostgreSQL error info requires [pg_stat_monitor](https://docs.percona.com/pg-stat-monitor/) (Percona). The collector auto-detects and uses it when available.* |
| 37 | |
| 38 | ## Function Types |
| 39 | |
| 40 | ### Top Queries |
| 41 | |
| 42 | Retrieves **accumulated query statistics** over a time window. These are aggregated metrics (total calls, total time, average time, etc.) from the database's query statistics infrastructure—not real-time snapshots. |
| 43 | |
| 44 | **Filter options** vary by database but typically include: |
| 45 | |
| 46 | - Execution time (total, average) |
| 47 | - Call count |
| 48 | - Rows processed (read, written, returned) |
| 49 | - I/O metrics (logical reads, physical reads) |
| 50 | - Resource usage (CPU, memory, locks) |
| 51 | |
| 52 | The number of queries returned is configurable (default: 500). This is a two-stage process: |
| 53 | |
| 54 | 1. **Server-side**: Database returns the top N queries ranked by your chosen metric |
| 55 | 2. **Client-side**: UI can further sort, filter, and explore the returned data |
| 56 | |
| 57 | ### Running Queries |
| 58 | |
| 59 | Shows **currently executing queries** at the moment of request. Essential for diagnosing stuck queries, long-running transactions, or unexpected load. |
| 60 | |
| 61 | **Supported**: CockroachDB, Oracle, PostgreSQL, RethinkDB, YugabyteDB |
| 62 | |
| 63 | ### Deadlock Info |
| 64 | |
| 65 | Displays the **most recently detected deadlock**—not a historical list. When a new deadlock occurs, it replaces the previous one. |
| 66 | |
| 67 | **Supported**: MySQL/MariaDB/Percona, Microsoft SQL Server |
| 68 | |
| 69 | Information provided: |
| 70 | |
| 71 | - Deadlock timestamp and ID |
| 72 | - Participating transactions |
| 73 | - Victim transaction (rolled back) |
| 74 | - Query text and lock details |
| 75 | - Wait resource |
| 76 | |
| 77 | ### Error Info |
| 78 | |
| 79 | Shows **recent SQL errors** from the database's error history. Error attribution is embedded directly in Top Queries results—each query row includes error details when available. |
| 80 | |
| 81 | **Supported**: MySQL/MariaDB/Percona, Microsoft SQL Server, PostgreSQL (with pg_stat_monitor) |
| 82 | |
| 83 | Attribution status values: |
| 84 | |
| 85 | - `enabled` — Error details available for this query |
| 86 | - `no_data` — No recent errors for this query |
| 87 | - `not_enabled` — Error tracking not configured |
| 88 | - `not_supported` — Database version lacks required features |
| 89 | |
| 90 | ## Security Considerations |
| 91 | |
| 92 | ### Query Text Exposure |
| 93 | |
| 94 | Some databases normalize queries (replacing literals with placeholders), while others show actual values that may contain sensitive data: |
| 95 | |
| 96 | | Database | Query Text | |
| 97 | |-----------------------|:-------------------------------------------:| |
| 98 | | ClickHouse | Normalized | |
| 99 | | CockroachDB | ⚠️ Raw | |
| 100 | | Couchbase | ⚠️ Raw | |
| 101 | | Elasticsearch | ⚠️ Raw | |
| 102 | | MongoDB | ⚠️ Raw | |
| 103 | | Microsoft SQL Server | ⚠️ Raw | |
| 104 | | MySQL/MariaDB/Percona | Normalized (Top Queries), ⚠️ Raw (Deadlock) | |
| 105 | | Oracle | ⚠️ Raw | |
| 106 | | PostgreSQL | Normalized | |
| 107 | | ProxySQL | Normalized | |
| 108 | | Redis | ⚠️ Raw | |
| 109 | | RethinkDB | ⚠️ Raw | |
| 110 | | YugabyteDB | ⚠️ Raw | |
| 111 | |
| 112 | **Legend**: |
| 113 | |
| 114 | - **Normalized**: Literals replaced with placeholders (`SELECT * FROM users WHERE id = ?`) |
| 115 | - **⚠️ Raw**: May contain actual values (`SELECT * FROM users WHERE id = 12345`) |
| 116 | |
| 117 | :::caution |
| 118 | |
| 119 | Error messages may contain sensitive values regardless of query normalization. Ensure appropriate access controls are in place. |
| 120 | |
| 121 | ::: |
| 122 | |
| 123 | ### Recommendations |
| 124 | |
| 125 | 1. **Disable unneeded functions** — Each integration supports configuration options to disable specific functions |
| 126 | 2. **Use Netdata Cloud access controls** — Assign users to appropriate Rooms and Roles |
| 127 | 3. **Use dedicated database users** — Grant only the permissions required for monitoring |
| 128 | |
| 129 | ## Getting Started |
| 130 | |
| 131 | Each database requires specific setup. Click the integration link in the table above for: |
| 132 | |
| 133 | - Prerequisites and permissions required |
| 134 | - Configuration options |
| 135 | - Available metrics and columns |
| 136 | - Database-specific notes |
| 137 | |
| 138 | ## Related Documentation |
| 139 | |
| 140 | - [Live View](/docs/top-monitoring-netdata-functions.md) |
| 141 | - [Processes Function](/docs/functions/processes.md) |