--- layout: doc_page --- # SQL Support for Druid ## Built-in SQL
Built-in SQL is an experimental feature. The API described here is subject to change.
Druid includes a native SQL layer with an [Apache Calcite](https://calcite.apache.org/)-based parser and planner. All parsing and planning takes place on the Broker, where SQL is converted to native Druid queries. Those native Druid queries are then passed down to data nodes. Each Druid datasource appears as a table in the "druid" schema. Datasource and column names are both case-sensitive and can optionally be quoted using double quotes. Literal strings should be quoted with single quotes, like `'foo'`. Literal strings with Unicode escapes can be written like `U&'fo\00F6'`, where character codes in hex are prefixed by a backslash. Add "EXPLAIN PLAN FOR" to the beginning of any query to see how Druid will plan that query. ### Querying with JDBC You can make Druid SQL queries using the [Avatica JDBC driver](https://calcite.apache.org/avatica/downloads/). Once you've downloaded the Avatica client jar, add it to your classpath and use the connect string: ``` jdbc:avatica:remote:url=http://BROKER:8082/druid/v2/sql/avatica/ ``` Example code: ```java // Connect to /druid/v2/sql/avatica/ on your broker. String url = "jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/"; // Set any connection context parameters you need here (see "Connection context" below). // Or leave empty for default behavior. Properties connectionProperties = new Properties(); try (Connection connection = DriverManager.getConnection(url, connectionProperties)) { try (ResultSet resultSet = connection.createStatement().executeQuery("SELECT COUNT(*) AS cnt FROM data_source")) { while (resultSet.next()) { // Do something } } } ``` Table metadata is available over JDBC using `connection.getMetaData()` or by querying the "INFORMATION_SCHEMA" tables (see below). Parameterized queries don't work properly, so avoid those. ### Querying with JSON over HTTP You can make Druid SQL queries using JSON over HTTP by POSTing to the endpoint `/druid/v2/sql/`. The request format is: ```json { "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'" } ``` You can use _curl_ to send these queries from the command-line: ```bash curl -XPOST -H'Content-Type: application/json' http://BROKER:8082/druid/v2/sql/ -d '{"query":"SELECT COUNT(*) FROM data_source"}' ``` Metadata is only available over the HTTP API by querying the "INFORMATION_SCHEMA" tables (see below). You can provide [connection context parameters](#connection-context) by adding a "context" map, like: ```json { "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'", "context" : { "sqlTimeZone" : "America/Los_Angeles" } } ``` ### Metadata Druid brokers infer table and column metadata for each dataSource from segments loaded in the cluster, and use this to plan SQL queries. This metadata is cached on broker startup and also updated periodically in the background through [SegmentMetadata queries](../querying/segmentmetadataquery.html). Background metadata refreshing is triggered by segments entering and exiting the cluster, and can also be throttled through configuration. This cached metadata is queryable through "INFORMATION_SCHEMA" tables. For example, to retrieve metadata for the Druid datasource "foo", use the query: ```sql SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE SCHEMA_NAME = 'druid' AND TABLE_NAME = 'foo' ``` See the [INFORMATION_SCHEMA tables](#information_schema-tables) section below for details on the available metadata. You can access table and column metadata through JDBC using `connection.getMetaData()`. ### Approximate queries The following SQL queries and features may be executed using approximate algorithms: - `COUNT(DISTINCT col)` and `APPROX_COUNT_DISTINCT(col)` aggregations use [HyperLogLog](http://algo.inria.fr/flajolet/Publications/FlFuGaMe07.pdf), a fast approximate distinct counting algorithm. If you need exact distinct counts, you can instead use `SELECT COUNT(*) FROM (SELECT DISTINCT col FROM data_source)`, which will use a slower and more resource intensive exact algorithm. - TopN-style queries with a single grouping column, like `SELECT col1, SUM(col2) FROM data_source GROUP BY col1 ORDER BY SUM(col2) DESC LIMIT 100`, by default will be executed as [TopN queries](topnquery.html), which use an approximate algorithm. To disable this behavior, and use exact algorithms for topN-style queries, set "useApproximateTopN" to "false", either through query context or through broker configuration. ### Time functions Druid's SQL language supports a number of time operations, including: - `FLOOR(__time TO )` for grouping or filtering on time buckets, like `SELECT FLOOR(__time TO MONTH), SUM(cnt) FROM data_source GROUP BY FLOOR(__time TO MONTH)` - `EXTRACT( FROM __time)` for grouping or filtering on time parts, like `SELECT EXTRACT(HOUR FROM __time), SUM(cnt) FROM data_source GROUP BY EXTRACT(HOUR FROM __time)` - Comparisons to `TIMESTAMP '