+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.
+
+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
+Connection connection = DriverManager.getConnection("jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/");
+ResultSet resultSet = connection.createStatement().executeQuery("SELECT COUNT(*) AS cnt FROM druid.foo");
+while (resultSet.next()) {
+ // Do something
+}
+```
+
+Table metadata is available over JDBC using `connection.getMetaData()`.
+
+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 druid.ds WHERE foo = ?"
+}
+```
+
+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 druid.ds"}'
+```
+
+Metadata is not available over the HTTP API.
+
+### Metadata
+
+Druid brokers cache column type metadata for each dataSource and use it to plan SQL queries. This cache is updated
+on broker startup and also 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 the "metadata.COLUMNS" and "metadata.TABLES" tables. When
+`druid.sql.planner.useFallback` is disabled (the default), only full scans of this table are possible. For example, to
+retrieve column metadata, use the query:
+
+```sql
+SELECT * FROM metadata.COLUMNS
+```
+
+If `druid.sql.planner.useFallback` is enabled, full SQL is possible on metadata tables. However, useFallback is not
+recommended in production since it can generate unscalable query plans. The JDBC driver allows accessing
+table and column metadata through `connection.getMetaData()` even if useFallback is off.
+
+### Time functions
+
+Druid's SQL language supports a number of time operations, including:
+
+- `FLOOR(__time TO