Retention rules API

This topic describes the API endpoints for managing retention rules in Apache Druid. You can configure retention rules in the Druid web console or API.

Druid uses retention rules to determine what data is retained in the cluster. Druid supports load, drop, and broadcast rules. For more information, see Using rules to drop and retain data.

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.

Update retention rules for a datasource

Updates one or more retention rules for a datasource. The request body takes an array of retention rule objects. For details on defining retention rules, see the following sources:

This request overwrites any existing rules for the datasource. Druid reads rules in the order in which they appear; for more information, see rule structure.

Note that this endpoint returns an HTTP 200 OK even if the datasource does not exist.

URL

POST /druid/coordinator/v1/rules/{dataSource}

Header parameters

The endpoint supports a set of optional header parameters to populate the author and comment fields in the auditInfo property for audit history.

  • X-Druid-Author (optional)
    • Type: String
    • A string representing the author making the configuration change.
  • X-Druid-Comment (optional)
    • Type: String
    • A string describing the update.

Responses

  • 200 SUCCESS

Successfully updated retention rules for specified datasource

Sample request

The following example sets a set of broadcast, load, and drop retention rules for the kttm1 datasource.

  • cURL
  • HTTP
  1. curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/rules/kttm1" \
  2. --header 'X-Druid-Author: doc intern' \
  3. --header 'X-Druid-Comment: submitted via api' \
  4. --header 'Content-Type: application/json' \
  5. --data '[
  6.     {
  7.         "type": "broadcastForever"
  8.     },
  9.     {
  10.         "type": "loadForever",
  11.         "tieredReplicants": {
  12.             "_default_tier": 2
  13.         },
  14.         "useDefaultTierForNull": true
  15.     },
  16.     {
  17.         "type": "dropByPeriod",
  18.         "period": "P1M"
  19.     }
  20. ]'
  1. POST /druid/coordinator/v1/rules/kttm1 HTTP/1.1
  2. Host: http://ROUTER_IP:ROUTER_PORT
  3. X-Druid-Author: doc intern
  4. X-Druid-Comment: submitted via api
  5. Content-Type: application/json
  6. Content-Length: 273
  8. [
  9.     {
  10.         "type": "broadcastForever"
  11.     },
  12.     {
  13.         "type": "loadForever",
  14.         "tieredReplicants": {
  15.             "_default_tier": 1
  16.         },
  17.         "useDefaultTierForNull": true
  18.     },
  19.     {
  20.         "type": "dropByPeriod",
  21.         "period": "P1M"
  22.     }
  23. ]

Sample response

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

Update default retention rules for all datasources

Updates one or more default retention rules for all datasources. Submit retention rules as an array of objects in the request body. For details on defining retention rules, see the following sources:

This request overwrites any existing rules for all datasources. To remove default retention rules for all datasources, submit an empty rule array in the request body. Rules are read in the order in which they appear; for more information, see rule structure.

URL

POST /druid/coordinator/v1/rules/_default

Header parameters

The endpoint supports a set of optional header parameters to populate the author and comment fields in the auditInfo property for audit history.

  • X-Druid-Author (optional)
    • Type: String
    • A string representing the author making the configuration change.
  • X-Druid-Comment (optional)
    • Type: String
    • A string describing the update.

Responses

  • 200 SUCCESS
  • 500 SERVER ERROR

Successfully updated default retention rules

Error with request body

Sample request

The following example updates the default retention rule for all datasources with a loadByInterval rule.

  • cURL
  • HTTP
  1. curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/rules/_default" \
  2. --header 'Content-Type: application/json' \
  3. --data '[
  4.     {
  5.         "type": "loadByInterval",
  6.         "tieredReplicants": {},
  7.         "useDefaultTierForNull": false,
  8.         "interval": "2010-01-01/2020-01-01"
  9.     }
  10. ]'
  1. POST /druid/coordinator/v1/rules/_default HTTP/1.1
  2. Host: http://ROUTER_IP:ROUTER_PORT
  3. Content-Type: application/json
  4. Content-Length: 205
  6. [
  7.     {
  8.         "type": "loadByInterval",
  9.         "tieredReplicants": {},
  10.         "useDefaultTierForNull": false,
  11.         "interval": "2010-01-01/2020-01-01"
  12.     }
  13. ]

Sample response

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

Get an array of all retention rules

Retrieves all current retention rules in the cluster including the default retention rule. Returns an array of objects for each datasource and their associated retention rules.

URL

GET /druid/coordinator/v1/rules

Responses

  • 200 SUCCESS

Successfully retrieved retention rules

Sample request

  • cURL
  • HTTP
  1. curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/rules"
  1. GET /druid/coordinator/v1/rules HTTP/1.1
  2. Host: http://ROUTER_IP:ROUTER_PORT

Sample response

View the response

  1. {
  2.   "_default": [
  3.       {
  4.           "tieredReplicants": {
  5.               "_default_tier": 2
  6.           },
  7.           "type": "loadForever"
  8.       }
  9.   ],
  10.   "social_media": [
  11.       {
  12.           "interval": "2023-01-01T00:00:00.000Z/2023-02-01T00:00:00.000Z",
  13.           "type": "dropByInterval"
  14.       }
  15.   ],
  16.   "wikipedia_api": [],
  17. }

Get an array of retention rules for a datasource

Retrieves an array of rule objects for a single datasource. Returns an empty array if there are no retention rules.

Note that this endpoint returns an HTTP 200 OK message code even if the datasource doesn’t exist.

URL

GET /druid/coordinator/v1/rules/{dataSource}

Query parameters

  • full (optional)
    • Includes the default retention rule for the datasource in the response.

Responses

  • 200 SUCCESS

Successfully retrieved retention rules

Sample request

The following example retrieves the custom retention rules and default retention rules for datasource with the name social_media.

  • cURL
  • HTTP
  1. curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/rules/social_media?full=null"
  1. GET /druid/coordinator/v1/rules/social_media?full=null HTTP/1.1
  2. Host: http://ROUTER_IP:ROUTER_PORT

Sample response

View the response

  1. [
  2.   {
  3.       "interval": "2020-01-01T00:00:00.000Z/2022-02-01T00:00:00.000Z",
  4.       "type": "dropByInterval"
  5.   },
  6.   {
  7.       "interval": "2010-01-01T00:00:00.000Z/2020-01-01T00:00:00.000Z",
  8.       "tieredReplicants": {
  9.           "_default_tier": 2
  10.       },
  11.       "type": "loadByInterval"
  12.   },
  13.   {
  14.       "tieredReplicants": {
  15.           "_default_tier": 2
  16.       },
  17.       "type": "loadForever"
  18.   }
  19. ]

Get audit history for all datasources

Retrieves the audit history of rules for all datasources over an interval of time. The default interval is 1 week. You can change this period by setting druid.audit.manager.auditHistoryMillis in the runtime.properties file for the Coordinator.

URL

GET /druid/coordinator/v1/rules/history

Query parameters

Note that the following query parameters cannot be chained.

  • interval (optional)
    • Type: ISO 8601.
    • Limits the number of results to the specified time interval. Delimit with /. For example, 2023-07-13/2023-07-19.
  • count (optional)
    • Type: Int
    • Limits the number of results to the last n entries.

Responses

  • 200 SUCCESS
  • 400 BAD REQUEST
  • 404 NOT FOUND

Successfully retrieved audit history

Request in the incorrect format

count query parameter too large

Sample request

The following example retrieves the audit history for all datasources from 2023-07-13 to 2023-07-19.

  • cURL
  • HTTP
  1. curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/rules/history?interval=2023-07-13%2F2023-07-19"
  1. GET /druid/coordinator/v1/rules/history?interval=2023-07-13/2023-07-19 HTTP/1.1
  2. Host: http://ROUTER_IP:ROUTER_PORT

Sample response

View the response

  1. [
  2.   {
  3.       "key": "social_media",
  4.       "type": "rules",
  5.       "auditInfo": {
  6.           "author": "console",
  7.           "comment": "test",
  8.           "ip": "127.0.0.1"
  9.       },
  10.       "payload": "[{\"interval\":\"2023-01-01T00:00:00.000Z/2023-02-01T00:00:00.000Z\",\"type\":\"dropByInterval\"}]",
  11.       "auditTime": "2023-07-13T18:05:33.066Z"
  12.   },
  13.   {
  14.       "key": "social_media",
  15.       "type": "rules",
  16.       "auditInfo": {
  17.           "author": "console",
  18.           "comment": "test",
  19.           "ip": "127.0.0.1"
  20.       },
  21.       "payload": "[]",
  22.       "auditTime": "2023-07-18T18:10:21.203Z"
  23.   },
  24.   {
  25.       "key": "wikipedia_api",
  26.       "type": "rules",
  27.       "auditInfo": {
  28.           "author": "console",
  29.           "comment": "test",
  30.           "ip": "127.0.0.1"
  31.       },
  32.       "payload": "[{\"tieredReplicants\":{\"_default_tier\":2},\"type\":\"loadForever\"}]",
  33.       "auditTime": "2023-07-18T18:10:44.519Z"
  34.   },
  35.   {
  36.       "key": "wikipedia_api",
  37.       "type": "rules",
  38.       "auditInfo": {
  39.           "author": "console",
  40.           "comment": "test",
  41.           "ip": "127.0.0.1"
  42.       },
  43.       "payload": "[]",
  44.       "auditTime": "2023-07-18T18:11:02.110Z"
  45.   },
  46.   {
  47.       "key": "social_media",
  48.       "type": "rules",
  49.       "auditInfo": {
  50.           "author": "console",
  51.           "comment": "test",
  52.           "ip": "127.0.0.1"
  53.       },
  54.       "payload": "[{\"interval\":\"2023-07-03T18:49:54.848Z/2023-07-03T18:49:55.861Z\",\"type\":\"dropByInterval\"}]",
  55.       "auditTime": "2023-07-18T18:32:50.060Z"
  56.   },
  57.   {
  58.       "key": "social_media",
  59.       "type": "rules",
  60.       "auditInfo": {
  61.           "author": "console",
  62.           "comment": "test",
  63.           "ip": "127.0.0.1"
  64.       },
  65.       "payload": "[{\"interval\":\"2020-01-01T00:00:00.000Z/2022-02-01T00:00:00.000Z\",\"type\":\"dropByInterval\"}]",
  66.       "auditTime": "2023-07-18T18:34:09.657Z"
  67.   },
  68.   {
  69.       "key": "social_media",
  70.       "type": "rules",
  71.       "auditInfo": {
  72.           "author": "console",
  73.           "comment": "test",
  74.           "ip": "127.0.0.1"
  75.       },
  76.       "payload": "[{\"interval\":\"2020-01-01T00:00:00.000Z/2022-02-01T00:00:00.000Z\",\"type\":\"dropByInterval\"},{\"tieredReplicants\":{\"_default_tier\":2},\"type\":\"loadForever\"}]",
  77.       "auditTime": "2023-07-18T18:38:37.223Z"
  78.   },
  79.   {
  80.       "key": "social_media",
  81.       "type": "rules",
  82.       "auditInfo": {
  83.           "author": "console",
  84.           "comment": "test",
  85.           "ip": "127.0.0.1"
  86.       },
  87.       "payload": "[{\"interval\":\"2020-01-01T00:00:00.000Z/2022-02-01T00:00:00.000Z\",\"type\":\"dropByInterval\"},{\"interval\":\"2010-01-01T00:00:00.000Z/2020-01-01T00:00:00.000Z\",\"tieredReplicants\":{\"_default_tier\":2},\"type\":\"loadByInterval\"}]",
  88.       "auditTime": "2023-07-18T18:49:43.964Z"
  89.   }
  90. ]