| <!doctype html> |
| <html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-querying/sql-query-context" data-has-hydrated="false"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="generator" content="Docusaurus v3.7.0"> |
| <title data-rh="true">SQL query context | Apache® Druid</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://druid.apache.org/img/druid_nav.png"><meta data-rh="true" name="twitter:image" content="https://druid.apache.org/img/druid_nav.png"><meta data-rh="true" property="og:url" content="https://druid.apache.org/docs/34.0.0/querying/sql-query-context"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="SQL query context | Apache® Druid"><meta data-rh="true" name="description" content="<!--"><meta data-rh="true" property="og:description" content="<!--"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://druid.apache.org/docs/34.0.0/querying/sql-query-context"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/34.0.0/querying/sql-query-context" hreflang="en"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/34.0.0/querying/sql-query-context" hreflang="x-default"><link rel="stylesheet" href="/css/all.css"> |
| <script src="/js/clipboard.min.js"></script><link rel="stylesheet" href="/assets/css/styles.f3140859.css"> |
| <script src="/assets/js/runtime~main.3a1a03a2.js" defer="defer"></script> |
| <script src="/assets/js/main.6815ddec.js" defer="defer"></script> |
| </head> |
| <body class="navigation-with-keyboard"> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const n=new URLSearchParams(window.location.search).entries();for(var[t,e]of n)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top navbar--dark"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/druid_nav.png" alt="Apache® Druid" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/druid_nav.png" alt="Apache® Druid" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div></a></div><div class="navbar__items navbar__items--right"><a class="navbar__item navbar__link" href="/technology">Technology</a><a class="navbar__item navbar__link" href="/use-cases">Use Cases</a><a class="navbar__item navbar__link" href="/druid-powered">Powered By</a><a class="navbar__item navbar__link" href="/docs/34.0.0/design/">Docs</a><a class="navbar__item navbar__link" href="/community/">Community</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Apache®</a><ul class="dropdown__menu"><li><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Foundation<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://apachecon.com/?ref=druid.apache.org" target="_blank" rel="noopener noreferrer" class="dropdown__link">Events<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer" class="dropdown__link">License<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Thanks<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Security<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Sponsorship<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><a class="navbar__item navbar__link" href="/downloads/">Download</a><div class="navbarSearchContainer_Bca1"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input id="search_input_react" type="search" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/34.0.0/design/">Introduction to Apache Druid</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/tutorials/">Getting started</a><button aria-label="Expand sidebar category 'Getting started'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/34.0.0/design/architecture">Design</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/ingestion/">Ingestion</a><button aria-label="Expand sidebar category 'Ingestion'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/data-management/">Data management</a><button aria-label="Expand sidebar category 'Data management'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role="button" aria-expanded="true" href="/docs/34.0.0/querying/sql">Querying</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role="button" aria-expanded="true" tabindex="0" href="/docs/34.0.0/querying/sql">Druid SQL</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql">Overview and syntax</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-functions">All functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/tips-good-queries">Tips for writing good queries</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/query-deep-storage">Query from deep storage</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-data-types">SQL data types</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-operators">Operators</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-scalar">Scalar functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-aggregations">Aggregation functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-window-functions">Window functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-array-functions">Array functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-multivalue-string-functions">Multi-value string functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-json-functions">JSON functions</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/34.0.0/querying/sql-query-context">SQL query context</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-metadata-tables">SQL metadata tables</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/sql-translation">SQL query translation</a></li></ul></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/">Native queries</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/query-processing">Query processing</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/query-execution">Query execution</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/dart">Dart engine</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/34.0.0/querying/troubleshooting">Troubleshooting</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" tabindex="0" href="/docs/34.0.0/querying/datasource">Concepts</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" tabindex="0" href="/docs/34.0.0/querying/timeseriesquery">Native query types</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" tabindex="0" href="/docs/34.0.0/querying/filters">Native query components</a></div></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/api-reference/">API reference</a><button aria-label="Expand sidebar category 'API reference'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/configuration/">Configuration</a><button aria-label="Expand sidebar category 'Configuration'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/34.0.0/api-reference/automatic-compaction-api">Operations</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/34.0.0/development/overview">Development</a><button aria-label="Expand sidebar category 'Development'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/34.0.0/release-info/release-notes">Release info</a></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/34.0.0/misc/papers-and-talks">Papers</a></li></ul></nav></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Querying</span><meta itemprop="position" content="1"></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Druid SQL</span><meta itemprop="position" content="2"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">SQL query context</span><meta itemprop="position" content="3"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>SQL query context</h1></header><div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_BuS1"><p>Apache Druid supports two query languages: Druid SQL and <a href="/docs/34.0.0/querying/">native queries</a>. |
| This document describes the SQL language.</p></div></div> |
| <p>In Apache Druid, you can control how your <a href="/docs/34.0.0/querying/sql">Druid SQL queries</a> queries run by using query context parameters. The parameters let you adjust aspects of query processing such as using approximations, selecting particular filters, controlling how lookups are executed.</p> |
| <p>For additional context parameters supported for all query types, refer to <a href="/docs/34.0.0/querying/query-context-reference">Query context reference</a>. To learn how to set the query context, see <a href="/docs/34.0.0/querying/query-context">Set query context</a>.</p> |
| <p>The table below lists the query context parameters you can use with Druid SQL.</p> |
| <table><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th></tr></thead><tbody><tr><td><code>sqlQueryId</code></td><td>SQL query ID. For HTTP client, Druid returns it in the <code>X-Druid-SQL-Query-Id</code> header.<br><br>To specify a SQL query ID, use <code>sqlQueryId</code> instead of <a href="/docs/34.0.0/querying/query-context-reference"><code>queryId</code></a>. Setting <code>queryId</code> for a SQL request has no effect. All native queries underlying SQL use an auto-generated <code>queryId</code>.</td><td>auto-generated</td></tr><tr><td><code>sqlTimeZone</code></td><td>Time zone for a connection. For example, "America/Los_Angeles" or an offset like "-08:00". This parameter affects how time functions and timestamp literals behave.</td><td>UTC</td></tr><tr><td><code>sqlStringifyArrays</code></td><td>If <code>true</code>, Druid serializes result columns with array values as JSON strings in the response instead of arrays.</td><td><code>true</code>, except for JDBC connections, where it's always <code>false</code></td></tr><tr><td><code>useApproximateCountDistinct</code></td><td>Whether to use an approximate cardinality algorithm for <code>COUNT(DISTINCT foo)</code>.</td><td><code>true</code></td></tr><tr><td><code>useGroupingSetForExactDistinct</code></td><td>Whether to use grouping sets to execute queries with multiple exact distinct aggregations.</td><td><code>false</code></td></tr><tr><td><code>useApproximateTopN</code></td><td>If <code>true</code>, Druid converts SQL queries to approximate <a href="/docs/34.0.0/querying/topnquery">TopN queries</a> wherever possible. If <code>false</code>, Druid uses exact <a href="/docs/34.0.0/querying/groupbyquery">GroupBy queries</a> instead.</td><td><code>true</code></td></tr><tr><td><code>useLexicographicTopN</code></td><td>If <code>true</code>, Druid can use <a href="/docs/34.0.0/querying/topnquery">TopN queries</a> with lexicographic dimension ordering. If <code>false</code>, Druid uses <a href="/docs/34.0.0/querying/groupbyquery">GroupBy queries</a> instead for lexicographic ordering. When both <code>useLexicographicTopN</code> and <code>useApproximateTopN</code> are <code>false</code>, TopN queries are never used.</td><td><code>false</code></td></tr><tr><td><code>enableTimeBoundaryPlanning</code></td><td>If <code>true</code>, Druid converts SQL queries to <a href="/docs/34.0.0/querying/timeboundaryquery">time boundary queries</a> wherever possible. Time boundary queries are very efficient for min-max calculation on the <code>__time</code> column in a datasource.</td><td><code>false</code></td></tr><tr><td><code>useNativeQueryExplain</code></td><td>If <code>true</code>, <code>EXPLAIN PLAN FOR</code> returns the explain plan as a JSON representation of equivalent native query, else it returns the original version of explain plan generated by Calcite.<br><br>This property is provided for backwards compatibility. We don't recommend setting this parameter unless your application depends on the older behavior.</td><td><code>true</code></td></tr><tr><td><code>sqlFinalizeOuterSketches</code></td><td>If <code>false</code> (default behavior in Druid 25.0.0 and later), <code>DS_HLL</code>, <code>DS_THETA</code>, and <code>DS_QUANTILES_SKETCH</code> return sketches in query results. If <code>true</code> (default behavior in Druid 24.0.1 and earlier), Druid finalizes sketches from these functions when they appear in query results.<br><br>This property is provided for backwards compatibility with behavior in Druid 24.0.1 and earlier. We don't recommend setting this parameter unless your application uses Druid 24.0.1 or earlier. Instead, use a function that doesn't return a sketch, such as <code>APPROX_COUNT_DISTINCT_DS_HLL</code>, <code>APPROX_COUNT_DISTINCT_DS_THETA</code>, <code>APPROX_QUANTILE_DS</code>, <code>DS_THETA_ESTIMATE</code>, or <code>DS_GET_QUANTILE</code>.</td><td><code>false</code></td></tr><tr><td><code>sqlUseBoundAndSelectors</code></td><td>If <code>false</code> (default behavior in Druid 27.0.0 and later), the SQL planner uses <a href="/docs/34.0.0/querying/filters#equality-filter">equality</a>, <a href="/docs/34.0.0/querying/filters#null-filter">null</a>, and <a href="/docs/34.0.0/querying/filters#range-filter">range</a> filters instead of <a href="/docs/34.0.0/querying/filters#selector-filter">selector</a> and <a href="/docs/34.0.0/querying/filters#bound-filter">bounds</a>. For filtering <code>ARRAY</code> typed values, <code>sqlUseBoundAndSelectors</code> must be <code>false</code>.</td><td><code>false</code>.</td></tr><tr><td><code>sqlReverseLookup</code></td><td>Whether to consider the <a href="/docs/34.0.0/querying/lookups#reverse-lookup">reverse-lookup rewrite</a> of the <code>LOOKUP</code> function during SQL planning.<br><br>Druid reverses calls to <code>LOOKUP</code> only when the number of matching keys is lower than both <code>inSubQueryThreshold</code> and <code>sqlReverseLookupThreshold</code>.</td><td><code>true</code></td></tr><tr><td><code>sqlReverseLookupThreshold</code></td><td>Maximum size of <code>IN</code> filter to create when applying a <a href="/docs/34.0.0/querying/lookups#reverse-lookup">reverse-lookup rewrite</a>. If a <code>LOOKUP</code> call matches more keys than the specified threshold, it remains unchanged.<br><br>If <code>inSubQueryThreshold</code> is lower than <code>sqlReverseLookupThreshold</code>, Druid uses <code>inSubQueryThreshold</code> threshold instead.</td><td>10000</td></tr><tr><td><code>sqlPullUpLookup</code></td><td>Whether to consider the <a href="/docs/34.0.0/querying/lookups#pull-up">pull-up rewrite</a> of the <code>LOOKUP</code> function during SQL planning.</td><td><code>true</code></td></tr><tr><td><code>enableJoinLeftTableScanDirect</code></td><td>This parameter applies to queries with joins. By default, when the left child is a simple scan with a filter, Druid runs the scan as a query, then joins it with the right child on the Broker. Setting this parameter to <code>true</code> overrides that behavior and pushes the join to the data servers instead. Even if a query doesn't explicitly include a join, this parameter may still apply since the SQL planner can translate the query into a join internally.</td><td><code>false</code></td></tr><tr><td><code>maxNumericInFilters</code></td><td>Max limit for the amount of numeric values that Druid can compare for a string type dimension when the entire SQL WHERE clause of a query translates only to an <a href="/docs/34.0.0/querying/filters#or">OR</a> of <a href="/docs/34.0.0/querying/filters#bound-filter">bound filter</a>. By default, Druid doesn't restrict the amount of numeric bound filters on string columns, although this situation may block other queries from running. Set this parameter to a smaller value to prevent Druid from running queries that have prohibitively long segment processing times. The optimal limit requires some trial and error. We recommend starting with 100. Users who submit a query that exceeds the limit of <code>maxNumericInFilters</code> should rewrite their queries to use strings in the <code>WHERE</code> clause instead of numbers. For example, <code>WHERE someString IN (‘123’, ‘456’)</code>. This value can't exceed the set system configuration <code>druid.sql.planner.maxNumericInFilters</code>. If <code>druid.sql.planner.maxNumericInFilters</code> isn't set explicitly, Druid ignores this value.</td><td><code>-1</code></td></tr><tr><td><code>inFunctionThreshold</code></td><td>At or beyond this threshold number of values, Druid converts SQL <code>IN</code> to <a href="/docs/34.0.0/querying/sql-functions#scalar_in_array"><code>SCALAR_IN_ARRAY</code></a>. A threshold of 0 forces this conversion in all cases. A threshold of <code>Integer.MAX_VALUE</code> disables this conversion. The converted function is eligible for fewer planning-time optimizations, which speeds up planning, but may prevent certain planning-time optimizations.</td><td><code>100</code></td></tr><tr><td><code>inFunctionExprThreshold</code></td><td>At or beyond this threshold number of values, SQL <code>IN</code> is eligible for execution using the native function <code>scalar_in_array</code> rather than an <code>||</code> of <code>==</code>, even if the number of values is below <code>inFunctionThreshold</code>. This property only affects translation of SQL <code>IN</code> to a <a href="/docs/34.0.0/querying/math-expr">native expression</a>. It doesn't affect translation of SQL <code>IN</code> to a <a href="/docs/34.0.0/querying/filters">native filter</a>. This property is provided for backwards compatibility purposes, and may be removed in a future release.</td><td><code>2</code></td></tr><tr><td><code>inSubQueryThreshold</code></td><td>At or beyond this threshold number of values, Druid converts SQL <code>IN</code> to <code>JOIN</code> on an inline table. <code>inFunctionThreshold</code> takes priority over this setting. A threshold of 0 forces usage of an inline table in all cases where the size of a SQL <code>IN</code> is larger than <code>inFunctionThreshold</code>. A threshold of <code>2147483647</code> disables the rewrite of SQL <code>IN</code> to <code>JOIN</code>.</td><td><code>2147483647</code></td></tr></tbody></table> |
| <h2 class="anchor anchorWithStickyNavbar_LWe7" id="learn-more">Learn more<a href="#learn-more" class="hash-link" aria-label="Direct link to Learn more" title="Direct link to Learn more"></a></h2> |
| <ul> |
| <li><a href="/docs/34.0.0/querying/query-context">Set query context</a> for how to set the query context.</li> |
| <li><a href="/docs/34.0.0/querying/query-context-reference">Query context reference</a> for available query context parameters.</li> |
| <li><a href="/docs/34.0.0/multi-stage-query/reference#context-parameters">MSQ context parameters</a> for how to set context parameters for Multi-Stage Queries.</li> |
| </ul></div></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/34.0.0/querying/sql-json-functions"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">JSON functions</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/34.0.0/querying/sql-metadata-tables"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">SQL metadata tables</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#learn-more" class="table-of-contents__link toc-highlight">Learn more</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="margin-bottom--sm"><img src="/img/favicon.png" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/favicon.png" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU"></div><div class="footer__copyright">Copyright © 2025 Apache Software Foundation. Except where otherwise noted, licensed under CC BY-SA 4.0. Apache Druid, Druid, and the Druid logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</div></div></div></footer></div> |
| </body> |
| </html> |
