| <!doctype html> |
| <html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-design/router"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="generator" content="Docusaurus v2.4.1"> |
| <title data-rh="true">Router Process | 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/latest/design/router"><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="Router Process | 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/latest/design/router"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/latest/design/router" hreflang="en"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/latest/design/router" hreflang="x-default"><link rel="preconnect" href="https://www.google-analytics.com"> |
| <link rel="preconnect" href="https://www.googletagmanager.com"> |
| <script async src="https://www.googletagmanager.com/gtag/js?id=UA-131010415-1"></script> |
| <script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","UA-131010415-1",{})</script> |
| |
| |
| |
| |
| <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.7.2/css/all.css"> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.4/clipboard.min.js"></script><link rel="stylesheet" href="/assets/css/styles.546f39eb.css"> |
| <link rel="preload" href="/assets/js/runtime~main.26d714fb.js" as="script"> |
| <link rel="preload" href="/assets/js/main.bd54ee66.js" as="script"> |
| </head> |
| <body class="navigation-with-keyboard"> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</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="themedImage_ToTc themedImage--light_HNdA"><img src="/img/druid_nav.png" alt="Apache® Druid" class="themedImage_ToTc themedImage--dark_i4oU"></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 aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/latest/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="searchBox_ZlJk"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input type="search" id="search_input_react" 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 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><main class="docMainContainer_gTbr docMainContainerEnhanced_Uz_u"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><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>Router Process</h1></header><p>The Apache Druid Router process can be used to route queries to different Broker processes. By default, the broker routes queries based on how <a href="/docs/latest/operations/rule-configuration">Rules</a> are set up. For example, if 1 month of recent data is loaded into a <code>hot</code> cluster, queries that fall within the recent month can be routed to a dedicated set of brokers. Queries outside this range are routed to another set of brokers. This set up provides query isolation such that queries for more important data are not impacted by queries for less important data.</p><p>For query routing purposes, you should only ever need the Router process if you have a Druid cluster well into the terabyte range.</p><p>In addition to query routing, the Router also runs the <a href="/docs/latest/operations/web-console">web console</a>, a management UI for datasources, segments, tasks, data processes (Historicals and MiddleManagers), and coordinator dynamic configuration. The user can also run SQL and native Druid queries within the console.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="configuration">Configuration<a href="#configuration" class="hash-link" aria-label="Direct link to Configuration" title="Direct link to Configuration"></a></h3><p>For Apache Druid Router Process Configuration, see <a href="/docs/latest/configuration/#router">Router Configuration</a>.</p><p>For basic tuning guidance for the Router process, see <a href="/docs/latest/operations/basic-cluster-tuning#router">Basic cluster tuning</a>.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="http-endpoints">HTTP endpoints<a href="#http-endpoints" class="hash-link" aria-label="Direct link to HTTP endpoints" title="Direct link to HTTP endpoints"></a></h3><p>For a list of API endpoints supported by the Router, see <a href="/docs/latest/api-reference/legacy-metadata-api#datasource-information">Legacy metadata API reference</a>.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="running">Running<a href="#running" class="hash-link" aria-label="Direct link to Running" title="Direct link to Running"></a></h3><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">org.apache.druid.cli.Main server router</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="router-as-management-proxy">Router as management proxy<a href="#router-as-management-proxy" class="hash-link" aria-label="Direct link to Router as management proxy" title="Direct link to Router as management proxy"></a></h3><p>The Router can be configured to forward requests to the active Coordinator or Overlord process. This may be useful for |
| setting up a highly available cluster in situations where the HTTP redirect mechanism of the inactive -> active |
| Coordinator/Overlord does not function correctly (servers are behind a load balancer, the hostname used in the redirect |
| is only resolvable internally, etc.).</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="enabling-the-management-proxy">Enabling the management proxy<a href="#enabling-the-management-proxy" class="hash-link" aria-label="Direct link to Enabling the management proxy" title="Direct link to Enabling the management proxy"></a></h4><p>To enable this functionality, set the following in the Router's runtime.properties:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.managementProxy.enabled=true</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h4 class="anchor anchorWithStickyNavbar_LWe7" id="management-proxy-routing">Management proxy routing<a href="#management-proxy-routing" class="hash-link" aria-label="Direct link to Management proxy routing" title="Direct link to Management proxy routing"></a></h4><p>The management proxy supports implicit and explicit routes. Implicit routes are those where the destination can be |
| determined from the original request path based on Druid API path conventions. For the Coordinator the convention is |
| <code>/druid/coordinator/*</code> and for the Overlord the convention is <code>/druid/indexer/*</code>. These are convenient because they mean |
| that using the management proxy does not require modifying the API request other than issuing the request to the Router |
| instead of the Coordinator or Overlord. Most Druid API requests can be routed implicitly.</p><p>Explicit routes are those where the request to the Router contains a path prefix indicating which process the request |
| should be routed to. For the Coordinator this prefix is <code>/proxy/coordinator</code> and for the Overlord it is <code>/proxy/overlord</code>. |
| This is required for API calls with an ambiguous destination. For example, the <code>/status</code> API is present on all Druid |
| processes, so explicit routing needs to be used to indicate the proxy destination.</p><p>This is summarized in the table below:</p><table><thead><tr><th>Request Route</th><th>Destination</th><th>Rewritten Route</th><th>Example</th></tr></thead><tbody><tr><td><code>/druid/coordinator/*</code></td><td>Coordinator</td><td><code>/druid/coordinator/*</code></td><td><code>router:8888/druid/coordinator/v1/datasources</code> -> <code>coordinator:8081/druid/coordinator/v1/datasources</code></td></tr><tr><td><code>/druid/indexer/*</code></td><td>Overlord</td><td><code>/druid/indexer/*</code></td><td><code>router:8888/druid/indexer/v1/task</code> -> <code>overlord:8090/druid/indexer/v1/task</code></td></tr><tr><td><code>/proxy/coordinator/*</code></td><td>Coordinator</td><td><code>/*</code></td><td><code>router:8888/proxy/coordinator/status</code> -> <code>coordinator:8081/status</code></td></tr><tr><td><code>/proxy/overlord/*</code></td><td>Overlord</td><td><code>/*</code></td><td><code>router:8888/proxy/overlord/druid/indexer/v1/isLeader</code> -> <code>overlord:8090/druid/indexer/v1/isLeader</code></td></tr></tbody></table><h3 class="anchor anchorWithStickyNavbar_LWe7" id="router-strategies">Router strategies<a href="#router-strategies" class="hash-link" aria-label="Direct link to Router strategies" title="Direct link to Router strategies"></a></h3><p>The Router has a configurable list of strategies for how it selects which Brokers to route queries to. The order of the strategies matter because as soon as a strategy condition is matched, a Broker is selected.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="timeboundary">timeBoundary<a href="#timeboundary" class="hash-link" aria-label="Direct link to timeBoundary" title="Direct link to timeBoundary"></a></h4><div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"type"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token string" style="color:rgb(195, 232, 141)">"timeBoundary"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Including this strategy means all timeBoundary queries are always routed to the highest priority Broker.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="priority">priority<a href="#priority" class="hash-link" aria-label="Direct link to priority" title="Direct link to priority"></a></h4><div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"type"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token string" style="color:rgb(195, 232, 141)">"priority"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"minPriority"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token number" style="color:rgb(247, 140, 108)">0</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"maxPriority"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token number" style="color:rgb(247, 140, 108)">1</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Queries with a priority set to less than minPriority are routed to the lowest priority Broker. Queries with priority set to greater than maxPriority are routed to the highest priority Broker. By default, minPriority is 0 and maxPriority is 1. Using these default values, if a query with priority 0 (the default query priority is 0) is sent, the query skips the priority selection logic.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="manual">manual<a href="#manual" class="hash-link" aria-label="Direct link to manual" title="Direct link to manual"></a></h4><p>This strategy reads the parameter <code>brokerService</code> from the query context and routes the query to that broker service. If no valid <code>brokerService</code> is specified in the query context, the field <code>defaultManualBrokerService</code> is used to determine target broker service given the value is valid and non-null. A value is considered valid if it is present in <code>druid.router.tierToBrokerMap</code> |
| This strategy can route both Native and SQL queries (when enabled).</p><p><em>Example</em>: A strategy that routes queries to the Broker "druid:broker-hot" if no valid <code>brokerService</code> is found in the query context.</p><div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"type"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"manual"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"defaultManualBrokerService"</span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"druid:broker-hot"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h4 class="anchor anchorWithStickyNavbar_LWe7" id="javascript">JavaScript<a href="#javascript" class="hash-link" aria-label="Direct link to JavaScript" title="Direct link to JavaScript"></a></h4><p>Allows defining arbitrary routing rules using a JavaScript function. The function is passed the configuration and the query to be executed, and returns the tier it should be routed to, or null for the default tier.</p><p><em>Example</em>: a function that sends queries containing more than three aggregators to the lowest priority Broker.</p><div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token punctuation" style="color:rgb(199, 146, 234)">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"type"</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"javascript"</span><span class="token punctuation" style="color:rgb(199, 146, 234)">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> </span><span class="token property">"function"</span><span class="token plain"> </span><span class="token operator" style="color:rgb(137, 221, 255)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(195, 232, 141)">"function (config, query) { if (query.getAggregatorSpecs && query.getAggregatorSpecs().size() >= 3) { var size = config.getTierToBrokerMap().values().size(); if (size > 0) { return config.getTierToBrokerMap().values().toArray()[size-1] } else { return config.getDefaultBrokerServiceName() } } else { return null } }"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"></span><span class="token punctuation" style="color:rgb(199, 146, 234)">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="theme-admonition theme-admonition-info alert alert--info admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><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_S0QG"><p> JavaScript-based functionality is disabled by default. Please refer to the Druid <a href="/docs/latest/development/javascript">JavaScript programming guide</a> for guidelines about using Druid's JavaScript functionality, including instructions on how to enable it.</p></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="routing-of-sql-queries-using-strategies">Routing of SQL queries using strategies<a href="#routing-of-sql-queries-using-strategies" class="hash-link" aria-label="Direct link to Routing of SQL queries using strategies" title="Direct link to Routing of SQL queries using strategies"></a></h3><p>To enable routing of SQL queries using strategies, set <code>druid.router.sql.enable</code> to <code>true</code>. The broker service for a |
| given SQL query is resolved using only the provided Router strategies. If not resolved using any of the strategies, the |
| Router uses the <code>defaultBrokerServiceName</code>. This behavior is slightly different from native queries where the Router |
| first tries to resolve the broker service using strategies, then load rules and finally using the <code>defaultBrokerServiceName</code> |
| if still not resolved. When <code>druid.router.sql.enable</code> is set to <code>false</code> (default value), the Router uses the |
| <code>defaultBrokerServiceName</code>.</p><p>Setting <code>druid.router.sql.enable</code> does not affect either Avatica JDBC requests or native queries. |
| Druid always routes native queries using the strategies and load rules as documented. |
| Druid always routes Avatica JDBC requests based on connection ID.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="avatica-query-balancing">Avatica query balancing<a href="#avatica-query-balancing" class="hash-link" aria-label="Direct link to Avatica query balancing" title="Direct link to Avatica query balancing"></a></h3><p>All Avatica JDBC requests with a given connection ID must be routed to the same Broker, since Druid Brokers do not share connection state with each other.</p><p>To accomplish this, Druid provides two built-in balancers that use rendezvous hashing and consistent hashing of a request's connection ID respectively to assign requests to Brokers.</p><p>Note that when multiple Routers are used, all Routers should have identical balancer configuration to ensure that they make the same routing decisions.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="rendezvous-hash-balancer">Rendezvous hash balancer<a href="#rendezvous-hash-balancer" class="hash-link" aria-label="Direct link to Rendezvous hash balancer" title="Direct link to Rendezvous hash balancer"></a></h4><p>This balancer uses <a href="https://en.wikipedia.org/wiki/Rendezvous_hashing" target="_blank" rel="noopener noreferrer">Rendezvous Hashing</a> on an Avatica request's connection ID to assign the request to a Broker.</p><p>To use this balancer, specify the following property:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.avatica.balancer.type=rendezvousHash</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>If no <code>druid.router.avatica.balancer</code> property is set, the Router will also default to using the Rendezvous Hash Balancer.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="consistent-hash-balancer">Consistent hash balancer<a href="#consistent-hash-balancer" class="hash-link" aria-label="Direct link to Consistent hash balancer" title="Direct link to Consistent hash balancer"></a></h4><p>This balancer uses <a href="https://en.wikipedia.org/wiki/Consistent_hashing" target="_blank" rel="noopener noreferrer">Consistent Hashing</a> on an Avatica request's connection ID to assign the request to a Broker.</p><p>To use this balancer, specify the following property:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.avatica.balancer.type=consistentHash</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>This is a non-default implementation that is provided for experimentation purposes. The consistent hasher has longer setup times on initialization and when the set of Brokers changes, but has a faster Broker assignment time than the rendezvous hasher when tested with 5 Brokers. Benchmarks for both implementations have been provided in <code>ConsistentHasherBenchmark</code> and <code>RendezvousHasherBenchmark</code>. The consistent hasher also requires locking, while the rendezvous hasher does not.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="example-production-configuration">Example production configuration<a href="#example-production-configuration" class="hash-link" aria-label="Direct link to Example production configuration" title="Direct link to Example production configuration"></a></h3><p>In this example, we have two tiers in our production cluster: <code>hot</code> and <code>_default_tier</code>. Queries for the <code>hot</code> tier are routed through the <code>broker-hot</code> set of Brokers, and queries for the <code>_default_tier</code> are routed through the <code>broker-cold</code> set of Brokers. If any exceptions or network problems occur, queries are routed to the <code>broker-cold</code> set of brokers. In our example, we are running with a c3.2xlarge EC2 instance. We assume a <code>common.runtime.properties</code> already exists.</p><p>JVM settings:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">-server</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Xmx13g</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Xms13g</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:NewSize=256m</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:MaxNewSize=256m</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:+UseConcMarkSweepGC</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:+PrintGCDetails</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:+PrintGCTimeStamps</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:+UseLargePages</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:+HeapDumpOnOutOfMemoryError</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-XX:HeapDumpPath=/mnt/galaxy/deploy/current/</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Duser.timezone=UTC</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Dfile.encoding=UTF-8</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Djava.io.tmpdir=/mnt/tmp</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Dcom.sun.management.jmxremote.port=17071</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Dcom.sun.management.jmxremote.authenticate=false</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">-Dcom.sun.management.jmxremote.ssl=false</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Runtime.properties:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.host=#{IP_ADDR}:8080</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.plaintextPort=8080</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.service=druid/router</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.defaultBrokerServiceName=druid:broker-cold</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.coordinatorServiceName=druid:coordinator</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.tierToBrokerMap={"hot":"druid:broker-hot","_default_tier":"druid:broker-cold"}</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.http.numConnections=50</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.http.readTimeout=PT5M</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"># Number of threads used by the Router proxy http client</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.router.http.numMaxThreads=100</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">druid.server.http.numThreads=100</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"></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="#configuration" class="table-of-contents__link toc-highlight">Configuration</a></li><li><a href="#http-endpoints" class="table-of-contents__link toc-highlight">HTTP endpoints</a></li><li><a href="#running" class="table-of-contents__link toc-highlight">Running</a></li><li><a href="#router-as-management-proxy" class="table-of-contents__link toc-highlight">Router as management proxy</a></li><li><a href="#router-strategies" class="table-of-contents__link toc-highlight">Router strategies</a></li><li><a href="#routing-of-sql-queries-using-strategies" class="table-of-contents__link toc-highlight">Routing of SQL queries using strategies</a></li><li><a href="#avatica-query-balancing" class="table-of-contents__link toc-highlight">Avatica query balancing</a></li><li><a href="#example-production-configuration" class="table-of-contents__link toc-highlight">Example production configuration</a></li></ul></div></div></div></div></main></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="themedImage_ToTc themedImage--light_HNdA footer__logo"><img src="/img/favicon.png" class="themedImage_ToTc themedImage--dark_i4oU footer__logo"></div><div class="footer__copyright">Copyright © 2023 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> |
| <script src="/assets/js/runtime~main.26d714fb.js"></script> |
| <script src="/assets/js/main.bd54ee66.js"></script> |
| </body> |
| </html> |
