Skip to content

Document config_merge on alter_job() (2.29.0) #417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
atovpeko merged 1 commit into from
Jul 28, 2026
Merged

Document config_merge on alter_job() (2.29.0) #417

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions src/content/docs/reference/timescaledb/jobs-automation/alter_job.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,38 +68,39 @@
SELECT alter_job(1000, next_start => '2020-03-15 09:00:00.0+00');
```

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

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

```sql
-- Find the job ID for the columnstore policy:
SELECT job_id, hypertable_name, config
FROM timescaledb_information.jobs
WHERE proc_name = 'policy_compression';
```

When you set `config`, the value you pass replaces the existing configuration in full. A {C.COLUMNSTORE} policy keeps required
keys such as `hypertable_id` in `config`, so passing only the key you want to change drops the others and the call fails with
`ERROR: could not find hypertable_id in config for job`. To change a single key, merge it into the current `config` with
[`jsonb_set`](https://www.postgresql.org/docs/current/functions-json.html) instead:

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

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):
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):

```sql
SELECT alter_job(job_id, config => jsonb_set(config, '{drop_after}', '"2 years"'))
SELECT alter_job(job_id, config_merge => '{"drop_after": "2 years"}')
FROM timescaledb_information.jobs
WHERE proc_name = 'policy_retention' AND hypertable_name = 'conditions';
```

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).
Use `config` only when you want to replace the configuration in full. Policies keep required keys such as
`hypertable_id` in `config`, so passing just the key you want to change drops the rest and the call fails with
`ERROR: could not find hypertable_id in config for job`. On earlier versions, where `config_merge` is not available,
patch the current `config` with [`jsonb_set`](https://www.postgresql.org/docs/current/functions-json.html) instead.

Some settings cannot be changed this way at all. 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).

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

Expand All @@ -114,10 +115,7 @@
AND hypertable_name = '<cagg_name>';

-- Enable compress_after_refresh:
SELECT alter_job(<job_id>,
config => jsonb_set(
(SELECT config FROM _timescaledb_catalog.bgw_job WHERE id = <job_id>),
'{compress_after_refresh}', 'true'));
SELECT alter_job(<job_id>, config_merge => '{"compress_after_refresh": true}');
```

## Arguments
Expand All @@ -133,6 +131,7 @@
retry_period => <interval>,
scheduled => true | false,
config => '<jsonb_config>',
config_merge => '<jsonb_config>',
next_start => <timestamptz>,
if_exists => true | false,
check_config => '<procedure_name>',
Expand All @@ -151,6 +150,7 @@
| `retry_period` |INTERVAL| - | ✖ | The amount of time the scheduler waits between retries of the job on failure. |
| `scheduled` |BOOLEAN| `true` | ✖ | Set to `false` to exclude this job from being run as a background job. |
| `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> |
| `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`. |

Check warning on line 153 in src/content/docs/reference/timescaledb/jobs-automation/alter_job.mdx

View workflow job for this annotation

GitHub Actions / Vale

Vale: Google.Acronyms 

Spell out 'JOB', if it's unfamiliar to the audience.

Check warning on line 153 in src/content/docs/reference/timescaledb/jobs-automation/alter_job.mdx

View workflow job for this annotation

GitHub Actions / Vale

Vale: Google.Acronyms 

Spell out 'JSONB', if it's unfamiliar to the audience.
| `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()`. |
| `if_exists` |BOOLEAN| `false` | ✖ | Set to `true` to issue a notice instead of an error if the job does not exist. |
| `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`. |
Expand Down
Loading