[UDA] Note that action signature is mandatory (github#1304)

You must include an action signature for your job, even if you don't need to use the `job_id` and `config` arguments.

Also removed some repetition that is hard to maintain. (The UDA examples have already been moved into how-to guides.) Left the UDA page in concepts for now, but these will also be migrated over time.

Also some drive-by formatting changes to test the automated formatting set-up.

Co-authored-by: Lana Brindley <[email protected]>

Author: charislam

timescaledb/how-to-guides/user-defined-actions/about-user-defined-actions.md

@@ -6,9 +6,11 @@ tags: [user-defined actions, background jobs, scheduled jobs, automation framewo
 ---
 
 # About user-defined actions
+
 With user-defined actions, you can write custom functions and procedures, and
 schedule them to run periodically. TimescaleDB natively includes some
 job-scheduling policies, such as:
+
 *   [Continuous aggregate policies][caggs] to automatically refresh continuous
     aggregates
 *   [Compression policies][compressing] to compress historical data

timescaledb/how-to-guides/user-defined-actions/create-and-register.md

@@ -6,46 +6,57 @@ tags: [user-defined actions, scheduled jobs, background jobs, automation framewo
 ---
 
 # Create and register user-defined actions
+
 Adding a user-defined action to your database is a 2-step process:
+
 1.  [Define a function or procedure](#define-a-function-or-procedure)
 1.  [Register your action with the job scheduler](#register-an-action)
 
 ## Define a function or procedure
+
 To create an action, first write the commands you want your
 [function][postgres-createfunction] or [procedure][postgres-createprocedure] to
 execute. Then wrap your commands in a `CREATE OR REPLACE` statement. You can
 also define the language of your commands in this statement. The example below
 uses PLPGSQL.
 
 The outer statement contains the action signature: `(job_id INT, config JSONB)`.
-Include the signature literally. Don't replace with an actual job ID or config
-object. You define `config` when you register your job.  `job_id` is also
-automatically generated then.
+You must include this signature even if you don't need to use those arguments in
+your action. Include it literally, don't replace it with an actual job ID or config
+object. When you register the job, you can define the config.
+The job ID is automatically generated.
 
-The following example defines a simple procedure that raises a notice. Replace
-the `RAISE NOTICE` with the commands you want to run.
+This example defines a simple procedure that raises a notice. Replace
+the `RAISE NOTICE` command with the commands you want to run.
 
 <procedure>
 
 ## Defining a procedure
-1.  Write the commands you want your job to run.
+
+1.  Write the commands you want your job to run. For example:
+
     ```sql
     BEGIN
         RAISE NOTICE 'Executing job % with config %', job_id, config;
     END
     ```
-2.  Wrap the commands in a `CREATE OR REPLACE PROCEDURE` statement. 
+
+1.  Wrap the commands in a `CREATE OR REPLACE PROCEDURE` statement. For example:
+
     ```sql
-    CREATE OR REPLACE PROCEDURE user_defined_action(job_id INT, config JSONB) LANGUAGE PLPGSQL AS
-    $$
-    BEGIN
-        RAISE NOTICE 'Executing job % with config %', job_id, config;
-    END
-    $$;
+    CREATE OR REPLACE PROCEDURE user_defined_action(job_id INT, config JSONB)
+        LANGUAGE PLPGSQL AS
+        $$
+        BEGIN
+            RAISE NOTICE 'Executing job % with config %', job_id, config;
+        END
+        $$;
+    ```
 
 </procedure>
 
 ## Register an action
+
 To make the job scheduler run your action, you need to register it. Use the
 [`add_job`][api-add_job] function. Supply the name of your action, the schedule
 you want it to run on, and the content of your config. If your job needs no
@@ -54,10 +65,13 @@ parameters, use a NULL config.
 <procedure>
 
 ## Registering an action
-1.  Add a job for your user-defined action.
+
+1.  Add a job for your user-defined action. For example:
+
     ```sql
     SELECT add_job('user_defined_action', '1h', config => '{"hypertable":"metr"}');
     ```
+
 1.  The `add_job` call returns a `job_id`. It stores the `job_id` and `config`
     in the TimescaleDB catalog.
 1.  The action runs on schedule. It also runs when you manually start it by
@@ -67,14 +81,15 @@ parameters, use a NULL config.
 </procedure>
 
 ## List current jobs
+
 To list all currently registered jobs, query
 [`timescaledb_information.jobs`][api-timescaledb_information-jobs].
+
 ```sql
 SELECT * FROM timescaledb_information.jobs;
 ```
 
 [api-add_job]: /api/:currentVersion:/actions/add_job
-[api-alter_job]: /api/:currentVersion:/actions/alter_job
 [api-run_job]: /api/:currentVersion:/actions/run_job
 [api-timescaledb_information-jobs]: /api/:currentVersion:/informational-views/jobs/
 [postgres-createfunction]: https://www.postgresql.org/docs/current/sql-createfunction.html

timescaledb/overview/core-concepts/user-defined-actions.md

@@ -10,238 +10,8 @@ tags: [user-defined actions, background jobs, scheduled jobs]
 User-defined actions allow you to run functions and procedures implemented in a
 language of your choice on a schedule within TimescaleDB. This allows
 automatic periodic tasks that are not covered by existing policies, or the
-ability to enhance existing policies with additional functionality.
+ability to enhance existing policies with additional features.
 
-User-defined actions have allow free-form configuration through a JSONB object
-which allows endless flexibility and reusability.
+To learn more about user-defined actions, see the [how-to guide][how-to].
 
-## Examples
-
-The following section provides a number of examples of user-defined actions
-that you can specify and subsequently schedule as part of TimescaleDB's
-automation framework.
-
-### Generic retention
-
-Create a generic data retention policy that applies to ALL hypertables, as opposed
-to just a single one as required by `add_retention_policy`.
-The policy could be further refined with additional filters, by adding a WHERE
-clause to the PERFORM query in the procedure definition.
-
-```sql
-CREATE OR REPLACE PROCEDURE generic_retention (job_id int, config jsonb)
-LANGUAGE PLPGSQL
-AS $$
-DECLARE
-  drop_after interval;
-BEGIN
-  SELECT jsonb_object_field_text (config, 'drop_after')::interval INTO STRICT drop_after;
-
-  IF drop_after IS NULL THEN
-    RAISE EXCEPTION 'Config must have drop_after';
-  END IF;
-
-  PERFORM drop_chunks(format('%I.%I', table_schema, table_name), older_than => drop_after)
-    FROM timescaledb_information.hypertables;
-END
-$$;
-```
-
-Register job to run daily dropping chunks on all hypertables that are older
-than 12 months.
-
-```sql
-SELECT add_job('generic_retention','1d', config => '{"drop_after":"12 month"}');
-```
-
-### Tiered storage
-
-Action that moves chunks older than a certain time to a different tablespace.
-
-```sql
-CREATE OR REPLACE PROCEDURE move_chunks (job_id int, config jsonb)
-LANGUAGE PLPGSQL
-AS $$
-DECLARE
-  ht REGCLASS;
-  lag interval;
-  destination name;
-  chunk REGCLASS;
-  tmp_name name;
-BEGIN
-  SELECT jsonb_object_field_text (config, 'hypertable')::regclass INTO STRICT ht;
-  SELECT jsonb_object_field_text (config, 'lag')::interval INTO STRICT lag;
-  SELECT jsonb_object_field_text (config, 'tablespace') INTO STRICT destination;
-
-  IF ht IS NULL OR lag IS NULL OR destination IS NULL THEN
-    RAISE EXCEPTION 'Config must have hypertable, lag and destination';
-  END IF;
-
-  FOR chunk IN
-  SELECT show.oid
-  FROM show_chunks(ht, older_than => lag)
-  SHOW (oid)
-    INNER JOIN pg_class pgc ON pgc.oid = show.oid
-    INNER JOIN pg_tablespace pgts ON pgts.oid = pgc.reltablespace
-  WHERE pgts.spcname != destination
-  LOOP
-    RAISE NOTICE 'Moving chunk: %', chunk::text;
-    EXECUTE format('ALTER TABLE %s SET TABLESPACE %I;', chunk, destination);
-  END LOOP;
-END
-$$;
-```
-
-Register job to run daily moving chunks older than 12 months on hypertable
-metrics to tablespace old_chunks.
-
-```sql
-SELECT add_job('move_chunks','1d', config => '{"hypertable":"metrics","lag":"12 month","tablespace":"old_chunks"}');
-```
-
-The above action uses the simpler `ALTER TABLE ... SET TABLESPACE` for moving
-a chunk, but it could alternatively be written in terms of TimescaleDB's
-[`move_chunk`][api-move_chunk]. The `move_chunk` function also requires an
-index as input, but performs data re-ordering as part of the move (for faster
-subsequent queries) and requires lower lock levels, so the chunk remains available
-for reads during the move.
-
-### Downsample and compress
-
-Action that downsamples and compresses chunks on hypertable `metrics`
-older than a certain age. The example query computes a simple `avg` over
-hourly data for downsampling, but this query can be arbitrarily complex.
-
-```sql
-CREATE OR REPLACE PROCEDURE downsample_compress (job_id int, config jsonb)
-LANGUAGE PLPGSQL
-AS $$
-DECLARE
-  lag interval;
-  chunk REGCLASS;
-  tmp_name name;
-BEGIN
-  SELECT jsonb_object_field_text (config, 'lag')::interval INTO STRICT lag;
-
-  IF lag IS NULL THEN
-    RAISE EXCEPTION 'Config must have lag';
-  END IF;
-
-  FOR chunk IN
-    SELECT show.oid
-    FROM show_chunks('metrics', older_than => lag) SHOW (oid)
-      INNER JOIN pg_class pgc ON pgc.oid = show.oid
-      INNER JOIN pg_namespace pgns ON pgc.relnamespace = pgns.oid
-      INNER JOIN timescaledb_information.chunks chunk ON chunk.chunk_name = pgc.relname
-        AND chunk.chunk_schema = pgns.nspname
-    WHERE chunk.is_compressed::bool = FALSE
-  LOOP
-    RAISE NOTICE 'Processing chunk: %', chunk::text;
-
-    -- build name for temp table
-    SELECT '_tmp' || relname
-    FROM pg_class
-    WHERE oid = chunk INTO STRICT tmp_name;
-
-    -- copy downsampled chunk data into temp table
-    EXECUTE format($sql$ CREATE UNLOGGED TABLE %I AS
-      SELECT time_bucket('1h', time), device_id, avg(value) FROM %s GROUP BY 1, 2;
-    $sql$, tmp_name, chunk);
-
-    -- clear original chunk
-    EXECUTE format('TRUNCATE %s;', chunk);
-
-    -- copy downsampled data back into chunk
-    EXECUTE format('INSERT INTO %s(time, device_id, value) SELECT * FROM %I;', chunk, tmp_name);
-
-    -- drop temp table
-    EXECUTE format('DROP TABLE %I;', tmp_name);
-
-    PERFORM compress_chunk (chunk);
-
-    COMMIT;
-  END LOOP;
-END
-$$;
-```
-
-Register job to run daily downsampling and compressing chunks older than
-12 months.
-
-```sql
-SELECT add_job('downsample_compress','1d', config => '{"lag":"12 month"}');
-```
-
-### Set up a table and procedure
-
-Set up a simple table and procedure:
-```sql
-CREATE TABLE IF NOT EXISTS times(time timestamptz);
-
-CREATE OR REPLACE PROCEDURE add_time(job_id int, config jsonb)
-LANGUAGE PLPGSQL
-AS $$
-BEGIN
-  INSERT INTO times VALUES (now());  
-END
-$$;
-
-CALL add_time(null, '{}');
-
-SELECT * from times;
-```
-
-Returns:
-```sql
-|time                         |
-|-----------------------------|
-|2021-12-27 10:50:28.449 -0600|
-```
-
-Register a job to run every 5 seconds and return a `job_id`:
-```sql
-SELECT add_job('add_time', '5 secs');
-```
-
-Returns:
-```sql
-|add_job|
-|-------|
-|1000   |
-```
-
-Wait for some jobs to run, then view the results:
-```sql
-SELECT * from times;
-```
-
-Returns:
-```sql
-|time                         |
-|-----------------------------|
-|2021-12-27 10:50:28.449 -0600|
-|2021-12-27 10:50:38.825 -0600|
-|2021-12-27 10:50:44.164 -0600|
-|2021-12-27 10:50:49.207 -0600|
-|...|
-```
-
-See running jobs:
-```sql
-SELECT job_id, total_runs, total_failures, total_successes
-FROM timescaledb_information.job_stats;
-```
-
-Returns:
-```sql
-|job_id|total_runs|total_failures|total_successes|
-|------|----------|--------------|---------------|
-|1000  |9         |0             |9              |
-```
-
-Stop or delete the job:
-```sql
-SELECT delete_job(1000);
-```
-
-[api-move_chunk]: /api/:currentVersion:/hypertable/move_chunk
+[how-to]: /timescaledb/:currentVersion:/how-to-guides/user-defined-actions/