SQL query context
- SQL query context parameters
- Setting the query context
  - Example using JSON API
  - Example using JDBC

SQL query context

info

Apache Druid supports two query languages: Druid SQL and native queries. This document describes the SQL language.

Druid supports query context parameters which affect SQL query planning. See Query context for general query context parameters for all query types.

SQL query context parameters

Configure Druid SQL query planning using the parameters in the table below.

Parameter	Description	Default value
`sqlQueryId`	Unique identifier given to this SQL query. For HTTP client, it will be returned in `X-Druid-SQL-Query-Id` header. To specify a unique identifier for SQL query, use `sqlQueryId` instead of queryId. Setting `queryId` for a SQL request has no effect. All native queries underlying SQL use an auto-generated `queryId`.	auto-generated
`sqlTimeZone`	Sets the time zone for this connection, which will affect how time functions and timestamp literals behave. Should be a time zone name like “America/Los_Angeles” or offset like “-08:00”.	`druid.sql.planner.sqlTimeZone` on the Broker (default: UTC)
`sqlStringifyArrays`	When set to true, result columns which return array values will be serialized into a JSON string in the response instead of as an array	true, except for JDBC connections, where it is always false
`useApproximateCountDistinct`	Whether to use an approximate cardinality algorithm for `COUNT(DISTINCT foo)`.	`druid.sql.planner.useApproximateCountDistinct` on the Broker (default: true)
`useGroupingSetForExactDistinct`	Whether to use grouping sets to execute queries with multiple exact distinct aggregations.	`druid.sql.planner.useGroupingSetForExactDistinct` on the Broker (default: false)
`useApproximateTopN`	Whether to use approximate TopN queries when a SQL query could be expressed as such. If false, exact GroupBy queries will be used instead.	`druid.sql.planner.useApproximateTopN` on the Broker (default: true)
`enableTimeBoundaryPlanning`	If true, SQL queries will get converted to TimeBoundary queries wherever possible. TimeBoundary queries are very efficient for min-max calculation on `__time` column in a datasource	`druid.query.default.context.enableTimeBoundaryPlanning` on the Broker (default: false)
`useNativeQueryExplain`	If true, `EXPLAIN PLAN FOR` will return the explain plan as a JSON representation of equivalent native query(s), else it will return the original version of explain plan generated by Calcite. This property is provided for backwards compatibility. It is not recommended to use this parameter unless you were depending on the older behavior.	`druid.sql.planner.useNativeQueryExplain` on the Broker (default: true)
`sqlFinalizeOuterSketches`	If false (default behavior in Druid 25.0.0 and later), `DS_HLL`, `DS_THETA`, and `DS_QUANTILES_SKETCH` return sketches in query results, as documented. If true (default behavior in Druid 24.0.1 and earlier), sketches from these functions are finalized when they appear in query results. This property is provided for backwards compatibility with behavior in Druid 24.0.1 and earlier. It is not recommended to use this parameter unless you were depending on the older behavior. Instead, use a function that does not return a sketch, such as `APPROX_COUNT_DISTINCT_DS_HLL`, `APPROX_COUNT_DISTINCT_DS_THETA`, `APPROX_QUANTILE_DS`, `DS_THETA_ESTIMATE`, or `DS_GET_QUANTILE`.	`druid.query.default.context.sqlFinalizeOuterSketches` on the Broker (default: false)
`sqlUseBoundAndSelectors`	If false (default behavior if `druid.generic.useDefaultValueForNull=false` in Druid 27.0.0 and later), the SQL planner will use equality, null, and range filters instead of selector and bounds. This value must be set to `false` for correct behavior for filtering `ARRAY` typed values.	Defaults to same value as `druid.generic.useDefaultValueForNull`, which is `false`

Setting the query context

The query context parameters can be specified as a “context” object in the JSON API or as a JDBC connection properties object. See examples for each option below.

Example using JSON API

{
  "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP '2000-01-01 00:00:00'",
  "context" : {
    "sqlTimeZone" : "America/Los_Angeles"
  }
}

Example using JDBC

String url = "jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/";
// Set any query context parameters you need here.
Properties connectionProperties = new Properties();
connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
connectionProperties.setProperty("useCache", "false");
try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {
  // create and execute statements, process result sets, etc
}