Skip to content

Commit 39c0fd7

Browse files
atovpekoatovpeko
committed
Lead with config_merge for changing a single policy setting
1 parent c889477 commit 39c0fd7

1 file changed

Lines changed: 18 additions & 18 deletions

File tree

  • src/content/docs/reference/timescaledb/jobs-automation

‎src/content/docs/reference/timescaledb/jobs-automation/alter_job.mdx‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -68,38 +68,39 @@ another crash.
6868
SELECT alter_job(1000, next_start => '2020-03-15 09:00:00.0+00');
6969
```
7070

71-
- **Alter a {C.COLUMNSTORE} policy**:
71+
- **Change a policy's configuration**:
7272

73-
You can pause and restart a {C.COLUMNSTORE} policy, change how often the policy runs and the {C.JOB} scheduling. To do this:
73+
Each policy stores its settings in a `config` JSON object. To change a single setting, use `config_merge`
74+
<SinceRelease version="2.29.0" product="tsdb" />. The keys you pass are merged into the existing configuration, and the
75+
keys you leave out are unchanged:
7476

7577
```sql
7678
-- Find the job ID for the columnstore policy:
7779
SELECT job_id, hypertable_name, config
7880
FROM timescaledb_information.jobs
7981
WHERE proc_name = 'policy_compression';
80-
```
81-
82-
When you set `config`, the value you pass replaces the existing configuration in full. A {C.COLUMNSTORE} policy keeps required
83-
keys such as `hypertable_id` in `config`, so passing only the key you want to change drops the others and the call fails with
84-
`ERROR: could not find hypertable_id in config for job`. To change a single key, merge it into the current `config` with
85-
[`jsonb_set`](https://www.postgresql.org/docs/current/functions-json.html) instead:
8682

87-
```sql
88-
-- For example, to convert chunks to the columnstore after 30 days instead of 7:
89-
SELECT alter_job(job_id, config => jsonb_set(config, '{compress_after}', '"30 days"'))
83+
-- Convert chunks to the columnstore after 30 days instead of 7:
84+
SELECT alter_job(job_id, config_merge => '{"compress_after": "30 days"}')
9085
FROM timescaledb_information.jobs
9186
WHERE proc_name = 'policy_compression' AND hypertable_name = 'conditions';
9287
```
9388

94-
The same applies to other policy types. For example, to change `drop_after` on a [data retention policy](/reference/timescaledb/data-retention/add_retention_policy):
89+
This works the same for every policy type. For example, to change `drop_after` on a [data retention policy](/reference/timescaledb/data-retention/add_retention_policy):
9590

9691
```sql
97-
SELECT alter_job(job_id, config => jsonb_set(config, '{drop_after}', '"2 years"'))
92+
SELECT alter_job(job_id, config_merge => '{"drop_after": "2 years"}')
9893
FROM timescaledb_information.jobs
9994
WHERE proc_name = 'policy_retention' AND hypertable_name = 'conditions';
10095
```
10196

102-
However, to change the `after` or `created_before`, the compression settings, or the {C.HYPERTABLE} the policy is acting on, you must [remove the {C.COLUMNSTORE} policy](/reference/timescaledb/hypercore/remove_columnstore_policy) and [add a new one](/reference/timescaledb/hypercore/add_columnstore_policy).
97+
Use `config` only when you want to replace the configuration in full. Policies keep required keys such as
98+
`hypertable_id` in `config`, so passing just the key you want to change drops the rest and the call fails with
99+
`ERROR: could not find hypertable_id in config for job`. On earlier versions, where `config_merge` is not available,
100+
patch the current `config` with [`jsonb_set`](https://www.postgresql.org/docs/current/functions-json.html) instead.
101+
102+
Some settings cannot be changed this way at all. To change the `after` or `created_before`, the compression settings, or
103+
the {C.HYPERTABLE} the policy is acting on, you must [remove the {C.COLUMNSTORE} policy](/reference/timescaledb/hypercore/remove_columnstore_policy) and [add a new one](/reference/timescaledb/hypercore/add_columnstore_policy).
103104

104105
- **Convert {C.CAGG} {C.CHUNK}s to the {C.COLUMNSTORE} after each refresh**:
105106

@@ -114,10 +115,7 @@ another crash.
114115
AND hypertable_name = '<cagg_name>';
115116

116117
-- Enable compress_after_refresh:
117-
SELECT alter_job(<job_id>,
118-
config => jsonb_set(
119-
(SELECT config FROM _timescaledb_catalog.bgw_job WHERE id = <job_id>),
120-
'{compress_after_refresh}', 'true'));
118+
SELECT alter_job(<job_id>, config_merge => '{"compress_after_refresh": true}');
121119
```
122120

123121
## Arguments
@@ -133,6 +131,7 @@ SELECT alter_job(
133131
retry_period => <interval>,
134132
scheduled => true | false,
135133
config => '<jsonb_config>',
134+
config_merge => '<jsonb_config>',
136135
next_start => <timestamptz>,
137136
if_exists => true | false,
138137
check_config => '<procedure_name>',
@@ -151,6 +150,7 @@ SELECT alter_job(
151150
| `retry_period` |INTERVAL| - | ✖ | The amount of time the scheduler waits between retries of the job on failure. |
152151
| `scheduled` |BOOLEAN| `true` | ✖ | Set to `false` to exclude this job from being run as a background job. |
153152
| `config` |JSONB| - | ✖| {C.JOB_CAP}-specific configuration, passed to the function when it runs. For the {C.COLUMNSTORE} policy this includes: <ul><li>`maxchunks_to_compress`: integer, defaults to `0` (no limit). The maximum number of {C.CHUNK}s to add to the {C.COLUMNSTORE} during a policy run.</li><li>`compress_after`: see [`add_columnstore_policy`](/reference/timescaledb/hypercore/add_columnstore_policy#arguments).</li><li>`compress_created_before`: see [`add_columnstore_policy`](/reference/timescaledb/hypercore/add_columnstore_policy#arguments).</li></ul> For the {C.CAGG} refresh policy this includes <ul><li>`compress_after_refresh`: boolean, defaults to `false`. When `true`, {C.TIMESCALE_DB} converts the {C.CAGG} {C.CHUNK}s in the refresh window to the {C.COLUMNSTORE} at the end of each scheduled refresh. Since 2.27.0.</li></ul> |
153+
| `config_merge` |JSONB| - | ✖| Since 2.29.0. Merge these keys into the {C.JOB}'s existing `config` instead of replacing it. The keys you pass take precedence, and the keys you leave out are unchanged. Cannot be combined with `config`. |
154154
| `next_start` |TIMESTAMPTZ| - | ✖ | The next time at which to run the job. The job can be paused by setting this value to `infinity`, and restarted with a value of `now()`. |
155155
| `if_exists` |BOOLEAN| `false` | ✖ | Set to `true` to issue a notice instead of an error if the job does not exist. |
156156
| `check_config` | REGPROC | - | ✖ | A function that takes a single argument, the `JSONB` `config` structure. The function is expected to raise an error if the configuration is not valid, and return nothing otherwise. Can be used to validate the configuration when updating a job. Only functions, not procedures, are allowed as values for `check_config`. |

0 commit comments

Comments
 (0)