id: dynamic-configuration-api title: Dynamic configuration API sidebar_label: Dynamic configuration

import Tabs from ‘@theme/Tabs’; import TabItem from ‘@theme/TabItem’;

This document describes the API endpoints to retrieve and manage dynamic configurations for the Coordinator and Overlord in Apache® Druid.

In this topic, http://ROUTER_IP:ROUTER_PORT is a placeholder for your Router service address and port. Replace it with the information for your deployment. For example, use http://localhost:8888 for quickstart deployments.

Coordinator dynamic configuration

The Coordinator has dynamic configurations to tune certain behavior on the fly, without requiring a service restart. For information on the supported properties, see Coordinator dynamic configuration.

Get dynamic configuration

Retrieves the current Coordinator dynamic configuration. Returns a JSON object with the dynamic configuration properties.

URL

GET /druid/coordinator/v1/config

Responses

Successfully retrieved dynamic configuration

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/config"

GET /druid/coordinator/v1/config HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

{
    "millisToWaitBeforeDeleting": 900000,
    "maxSegmentsToMove": 100,
    "replicantLifetime": 15,
    "replicationThrottleLimit": 500,
    "balancerComputeThreads": 1,
    "killDataSourceWhitelist": [],
    "killPendingSegmentsSkipList": [],
    "maxSegmentsInNodeLoadingQueue": 500,
    "decommissioningNodes": [],
    "decommissioningMaxPercentOfMaxSegmentsToMove": 70,
    "pauseCoordination": false,
    "replicateAfterLoadTimeout": false,
    "maxNonPrimaryReplicantsToLoad": 2147483647,
    "useRoundRobinSegmentAssignment": true,
    "smartSegmentLoading": true,
    "debugDimensions": null,
    "turboLoadingNodes": [],
    "cloneServers": {},
    "cloneSyncCriteria": {},
    "historicalTierAliases": {
        "hot": ["hot_1", "hot_2"]
    }

}

Update dynamic configuration

Submits a JSON-based dynamic configuration spec to the Coordinator. For information on the supported properties, see Dynamic configuration.

URL

POST /druid/coordinator/v1/config

Header parameters

The endpoint supports a set of optional header parameters to populate the author and comment fields in the configuration history.

  • X-Druid-Author
    • Type: String
    • Author of the configuration change.
  • X-Druid-Comment
    • Type: String
    • Description for the update.

Responses

Successfully updated dynamic configuration

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/config" \
--header 'Content-Type: application/json' \
--data '{
  "millisToWaitBeforeDeleting": 900000,
  "maxSegmentsToMove": 5,
  "percentOfSegmentsToConsiderPerMove": 100,
  "useBatchedSegmentSampler": true,
  "replicantLifetime": 15,
  "replicationThrottleLimit": 10,
  "balancerComputeThreads": 1,
  "emitBalancingStats": true,
  "killDataSourceWhitelist": [],
  "killPendingSegmentsSkipList": [],
  "maxSegmentsInNodeLoadingQueue": 100,
  "decommissioningNodes": [],
  "decommissioningMaxPercentOfMaxSegmentsToMove": 70,
  "pauseCoordination": false,
  "replicateAfterLoadTimeout": false,
  "maxNonPrimaryReplicantsToLoad": 2147483647,
  "useRoundRobinSegmentAssignment": true,
  "turboLoadingNodes": [],
  "cloneServers": {},
  "cloneSyncCriteria": {}
}'

POST /druid/coordinator/v1/config HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 683

{
  "millisToWaitBeforeDeleting": 900000,
  "maxSegmentsToMove": 5,
  "percentOfSegmentsToConsiderPerMove": 100,
  "useBatchedSegmentSampler": true,
  "replicantLifetime": 15,
  "replicationThrottleLimit": 10,
  "balancerComputeThreads": 1,
  "emitBalancingStats": true,
  "killDataSourceWhitelist": [],
  "killPendingSegmentsSkipList": [],
  "maxSegmentsInNodeLoadingQueue": 100,
  "decommissioningNodes": [],
  "decommissioningMaxPercentOfMaxSegmentsToMove": 70,
  "pauseCoordination": false,
  "replicateAfterLoadTimeout": false,
  "maxNonPrimaryReplicantsToLoad": 2147483647,
  "useRoundRobinSegmentAssignment": true,
  "turboLoadingNodes": [],
  "cloneServers": {},
  "cloneSyncCriteria": {}
}

Sample response

A successful request returns an HTTP 200 OK message code and an empty response body.

Get dynamic configuration history

Retrieves the history of changes to Coordinator dynamic configuration over an interval of time. Returns an empty array if there are no history records available.

URL

GET /druid/coordinator/v1/config/history

Query parameters

The endpoint supports a set of optional query parameters to filter results.

  • interval

    • Type: String
    • Limit the results to the specified time interval in ISO 8601 format delimited with /. For example, 2023-07-13/2023-07-19. The default interval is one week. You can change this period by setting druid.audit.manager.auditHistoryMillis in the runtime.properties file for the Coordinator.

  • count

    • Type: Integer
    • Limit the number of results to the last n entries.

Responses

Successfully retrieved history

Sample request

The following example retrieves the dynamic configuration history between 2022-07-13 and 2024-07-19. The response is limited to 10 entries.

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/config/history?interval=2022-07-13%2F2024-07-19&count=10"

GET /druid/coordinator/v1/config/history?interval=2022-07-13/2024-07-19&count=10 HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

[
    {
        "key": "coordinator.config",
        "type": "coordinator.config",
        "auditInfo": {
            "author": "",
            "comment": "",
            "ip": "127.0.0.1"
        },
        "payload": "{\"millisToWaitBeforeDeleting\":900000,\"maxSegmentsToMove\":5,\"replicantLifetime\":15,\"replicationThrottleLimit\":10,\"balancerComputeThreads\":1,\"killDataSourceWhitelist\":[],\"killPendingSegmentsSkipList\":[],\"maxSegmentsInNodeLoadingQueue\":100,\"decommissioningNodes\":[],\"decommissioningMaxPercentOfMaxSegmentsToMove\":70,\"pauseCoordination\":false,\"replicateAfterLoadTimeout\":false,\"maxNonPrimaryReplicantsToLoad\":2147483647,\"useRoundRobinSegmentAssignment\":true,\"smartSegmentLoading\":true,\"debugDimensions\":null,\"decommissioningNodes\":[]}",
        "auditTime": "2023-10-03T20:59:51.622Z"
    }
]

Broker dynamic configuration

Broker dynamic configuration is managed through the Coordinator but consumed by Brokers. These settings control broker behavior such as query blocking rules and default query context values.

Note: Broker dynamic configuration is best-effort. Settings may not be applied in certain cases, such as when a Broker has recently started and hasn't received the config yet, or if the Broker cannot contact the Coordinator. Brokers poll the configuration periodically (default every 1 minute) and also receive push updates from the Coordinator for immediate propagation. If a setting is critical and must always be applied, use the equivalent static runtime property instead.

Get broker dynamic configuration

Retrieves the current Broker dynamic configuration. Returns a JSON object with the dynamic configuration properties.

URL

GET /druid/coordinator/v1/broker/config

Responses

Successfully retrieved broker dynamic configuration

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/broker/config"

GET /druid/coordinator/v1/broker/config HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

{
  "queryBlocklist": [
    {
      "type": "default",
      "ruleName": "block-expensive-scans",
      "dataSources": ["large_table"],
      "queryTypes": ["scan"]
    }
  ],
  "queryContext": {
    "priority": 0,
    "timeout": 300000
  },
  "perSegmentTimeoutConfig": {
    "large_table": {
      "perSegmentTimeoutMs": 10000,
      "monitorOnly": false
    }
  }
}

Update broker dynamic configuration

Updates the Broker dynamic configuration.

URL

POST /druid/coordinator/v1/broker/config

Header parameters

The endpoint supports a set of optional header parameters to populate the audit log information.

  • X-Druid-Author

    • Type: String
    • Author making the config change.

  • X-Druid-Comment

    • Type: String
    • Comment describing the change.

Responses

Successfully updated configuration

Sample request

curl -X POST "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/broker/config" \
-H "Content-Type: application/json" \
-H "X-Druid-Author: admin" \
-H "X-Druid-Comment: Add query blocklist rules and set default context" \
-d '{
  "queryBlocklist": [
    {
      "type": "default",
      "ruleName": "block-expensive-scans",
      "dataSources": ["large_table", "huge_dataset"],
      "queryTypes": ["scan"]
    },
    {
      "type": "default",
      "ruleName": "block-debug-queries",
      "contextMatches": {
        "debug": "true"
      }
    }
  ],
  "queryContext": {
    "priority": 0,
    "timeout": 300000
  },
  "perSegmentTimeoutConfig": {
    "large_table": {
      "perSegmentTimeoutMs": 10000
    },
    "huge_dataset": {
      "perSegmentTimeoutMs": 5000,
      "monitorOnly": true
    }
  }
}'

POST /druid/coordinator/v1/broker/config HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
X-Druid-Author: admin
X-Druid-Comment: Add query blocklist rules and set default context

{
  "queryBlocklist": [
    {
      "type": "default",
      "ruleName": "block-expensive-scans",
      "dataSources": ["large_table", "huge_dataset"],
      "queryTypes": ["scan"]
    },
    {
      "type": "default",
      "ruleName": "block-debug-queries",
      "contextMatches": {
        "debug": "true"
      }
    }
  ],
  "queryContext": {
    "priority": 0,
    "timeout": 300000
  },
  "perSegmentTimeoutConfig": {
    "large_table": {
      "perSegmentTimeoutMs": 10000
    },
    "huge_dataset": {
      "perSegmentTimeoutMs": 5000,
      "monitorOnly": true
    }
  }
}

Sample response

A successful request returns an HTTP 200 OK message code and an empty response body.

Broker dynamic configuration properties

The following table shows the dynamic configuration properties for the Broker.

PropertyDescriptionDefault
queryBlocklistList of rules to block queries based on datasource, query type, and/or query context parameters. Each rule defines criteria that are combined with AND logic. Blocked queries return an HTTP 403 error. See Query blocklist rules for details.none
queryContextMap of default query context key-value pairs applied to all queries on this broker. These values override static defaults set via runtime properties (druid.query.default.context.*) but are overridden by context values supplied in individual query payloads. Useful for setting cluster-wide defaults such as priority or timeout without restarting. See Query context reference for available keys.none
perSegmentTimeoutConfigMap of datasource names to per-segment timeout configurations. When a query targets a datasource in this map, the Broker injects the configured perSegmentTimeout into the query context before forwarding to Historicals. See Per-segment timeout configuration for details.none

Query blocklist rules

Query blocklist rules allow you to block specific queries based on datasource, query type, and/or query context parameters. This feature is useful for preventing expensive or problematic queries from impacting cluster performance.

Each rule in the queryBlocklist array is a JSON object. The type field selects the rule implementation. If omitted, it defaults to "default". A query is blocked if it matches ANY rule in the blocklist (OR logic between rules).

Note: The "type" field is not required for "default" rules (existing configs without it continue to work), but including it explicitly is recommended for clarity.

default type

The built-in rule type. Blocks queries by matching on datasource, query type, and/or query context parameters.

PropertyDescriptionRequiredDefault
typeRule type identifier. Not required — rules without a "type" field are treated as "default" for backwards compatibility with existing configurations.No"default"
ruleNameUnique name identifying this blocklist rule. Used in error messages when queries are blocked.YesN/A
dataSourcesList of datasource names to match. A query matches if it references any datasource in this list.NoMatches all datasources
queryTypesList of query types to match (e.g., scan, timeseries, groupBy, topN). A query matches if its type is in this list.NoMatches all query types
contextMatchesMap of query context parameter key-value pairs to match. A query matches if all specified context parameters match the provided values (case-sensitive string comparison).NoMatches all contexts

Matching behavior:

  • A query must match ALL specified criteria within a rule (AND logic) to be blocked by that rule
  • If any criterion is omitted, empty, or null, it matches everything (e.g., omitting queryTypes or setting it to null matches all query types)
  • For context matching: if a rule specifies context parameters, queries with missing or null values for those keys will not match
  • At least one criterion must be specified per rule to prevent accidentally blocking all queries
Custom types (extensions)

Extensions can register additional rule types by adding Jackson subtypes to the QueryBlocklistRule interface. A custom rule is selected by setting "type" to its registered name:

{
  "type": "myCustomRule",
  "ruleName": "rate-limit-heavy-users",
  ...
}

Custom types define their own matching semantics — they may use different criteria and logic than the default type described above. If a rule references a type whose extension is not loaded, deserialization fails with an error rather than silently falling back to the default type.

Error response:

When a query is blocked, the Broker returns an HTTP 403 error with a message indicating the query ID and the rule that blocked it:

{
  "error": "Forbidden",
  "errorMessage": "Query[abc-123-def] blocked by rule[block-expensive-scans]",
  "persona": "USER",
  "category": "FORBIDDEN"
}

Per-segment timeout configuration

Per-segment timeout configuration allows operators to set per-datasource segment processing timeouts without restarting the cluster. This is useful when different datasources have different performance characteristics — for example, allowing longer timeouts for larger datasets.

Each entry in the perSegmentTimeoutConfig map is keyed by datasource name and has the following properties:

PropertyDescriptionRequiredDefault
perSegmentTimeoutMsPer-segment processing timeout in milliseconds. Must be greater than 0.YesN/A
monitorOnlyWhen true, the timeout value is logged but not enforced. Useful for observing the impact of a timeout before enabling enforcement.Nofalse

Precedence order (highest to lowest):

  1. User-supplied perSegmentTimeout in the query context
  2. Per-datasource value from perSegmentTimeoutConfig
  3. Cluster-wide default from druid.query.default.context.perSegmentTimeout

Note: For queries involving multiple datasources (e.g. joins or unions), the timeout from the first matching datasource is applied. The match order is non-deterministic. To avoid this, configure the same timeout for all datasources involved in such queries, or set perSegmentTimeout explicitly in the query context.

Example configuration:

{
  "perSegmentTimeoutConfig": {
    "large_datasource": {
      "perSegmentTimeoutMs": 10000
    },
    "critical_datasource": {
      "perSegmentTimeoutMs": 5000,
      "monitorOnly": true
    }
  }
}

To clear all per-datasource timeouts, POST an empty map:

{
  "perSegmentTimeoutConfig": {}
}

Get broker dynamic configuration history

Retrieves the history of changes to Broker dynamic configuration over an interval of time. Returns an empty array if there are no history records available.

URL

GET /druid/coordinator/v1/broker/config/history

Query parameters

The endpoint supports a set of optional query parameters to filter results.

  • interval

    • Type: String
    • Limit the results to the specified time interval in ISO 8601 format delimited with /. For example, 2023-07-13/2023-07-19. The default interval is one week. You can change this period by setting druid.audit.manager.auditHistoryMillis in the runtime.properties file for the Coordinator.

  • count

    • Type: Integer
    • Limit the number of results to the last n entries.

Responses

Successfully retrieved history

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/broker/config/history?count=10"

GET /druid/coordinator/v1/broker/config/history?count=10 HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

[
  {
    "key": "broker.config",
    "type": "broker.config",
    "auditInfo": {
      "author": "admin",
      "comment": "Add query blocklist rules",
      "ip": "127.0.0.1"
    },
    "payload": "{\"queryBlocklist\":[{\"type\":\"default\",\"ruleName\":\"block-expensive-scans\",\"dataSources\":[\"large_table\"],\"queryTypes\":[\"scan\"]}],\"queryContext\":{\"priority\":0,\"timeout\":300000},\"perSegmentTimeoutConfig\":{\"large_table\":{\"perSegmentTimeoutMs\":10000,\"monitorOnly\":false}}}",
    "auditTime": "2024-03-06T12:00:00.000Z"
  }
]

Overlord dynamic configuration

The Overlord has dynamic configurations to tune how Druid assigns tasks to workers. For information on the supported properties, see Overlord dynamic configuration.

Get dynamic configuration

Retrieves the current Overlord dynamic configuration. Returns a JSON object with the dynamic configuration properties. Returns an empty response body if there is no current Overlord dynamic configuration.

URL

GET /druid/indexer/v1/worker

Responses

Successfully retrieved dynamic configuration

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/worker"

GET /druid/indexer/v1/worker HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

{
    "type": "default",
    "selectStrategy": {
        "type": "fillCapacityWithCategorySpec",
        "workerCategorySpec": {
            "categoryMap": {},
            "strong": true
        }
    },
    "autoScaler": null
}

Update dynamic configuration

Submits a JSON-based dynamic configuration spec to the Overlord. For information on the supported properties, see Overlord dynamic configuration.

URL

POST /druid/indexer/v1/worker

Header parameters

The endpoint supports a set of optional header parameters to populate the author and comment fields in the configuration history.

  • X-Druid-Author
    • Type: String
    • Author of the configuration change.
  • X-Druid-Comment
    • Type: String
    • Description for the update.

Responses

Successfully updated dynamic configuration

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/worker" \
--header 'Content-Type: application/json' \
--data '{
  "type": "default",
  "selectStrategy": {
    "type": "fillCapacityWithCategorySpec",
    "workerCategorySpec": {
      "categoryMap": {},
      "strong": true
    }
  },
  "autoScaler": null
}'

POST /druid/indexer/v1/worker HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 196

{
  "type": "default",
  "selectStrategy": {
    "type": "fillCapacityWithCategorySpec",
    "workerCategorySpec": {
      "categoryMap": {},
      "strong": true
    }
  },
  "autoScaler": null
}

Sample response

A successful request returns an HTTP 200 OK message code and an empty response body.

Get dynamic configuration history

Retrieves the history of changes to Overlord dynamic configuration over an interval of time. Returns an empty array if there are no history records available.

URL

GET /druid/indexer/v1/worker/history

Query parameters

The endpoint supports a set of optional query parameters to filter results.

  • interval

    • Type: String
    • Limit the results to the specified time interval in ISO 8601 format delimited with /. For example, 2023-07-13/2023-07-19. The default interval is one week. You can change this period by setting druid.audit.manager.auditHistoryMillis in the runtime.properties file for the Overlord.

  • count

    • Type: Integer
    • Limit the number of results to the last n entries.

Responses

Successfully retrieved history

Sample request

The following example retrieves the dynamic configuration history between 2022-07-13 and 2024-07-19. The response is limited to 10 entries.

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/worker/history?interval=2022-07-13%2F2024-07-19&count=10"

GET /druid/indexer/v1/worker/history?interval=2022-07-13%2F2024-07-19&count=10 HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

[
    {
        "key": "worker.config",
        "type": "worker.config",
        "auditInfo": {
            "author": "",
            "comment": "",
            "ip": "127.0.0.1"
        },
        "payload": "{\"type\":\"default\",\"selectStrategy\":{\"type\":\"fillCapacityWithCategorySpec\",\"workerCategorySpec\":{\"categoryMap\":{},\"strong\":true}},\"autoScaler\":null}",
        "auditTime": "2023-10-03T21:49:49.991Z"
    }
]

Get an array of worker nodes in the cluster

Returns an array of all the worker nodes in the cluster along with its corresponding metadata.

GET /druid/indexer/v1/workers

Responses

Successfully retrieved worker nodes

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/workers"

GET /druid/indexer/v1/workers HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

[
    {
        "worker": {
            "scheme": "http",
            "host": "localhost:8091",
            "ip": "198.51.100.0",
            "capacity": 2,
            "version": "0",
            "category": "_default_worker_category"
        },
        "currCapacityUsed": 0,
        "currParallelIndexCapacityUsed": 0,
        "availabilityGroups": [],
        "runningTasks": [],
        "lastCompletedTaskTime": "2023-09-29T19:13:05.505Z",
        "blacklistedUntil": null
    }
]

Get scaling events

Returns Overlord scaling events if autoscaling runners are in use. Returns an empty response body if there are no Overlord scaling events.

URL

GET /druid/indexer/v1/scaling

Responses

Successfully retrieved scaling events

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/scaling"

GET /druid/indexer/v1/scaling HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT

Sample response

A successful request returns a 200 OK response and an array of scaling events.