Add example for new generalized API (#2904)

* Add note about new interface availability Add note about dimension info constructors only available in 2.13 and later to all places where the new interface is used. Add example of using partitioning function with dimension builders. Correcting some parameter names for dimension builders. * Update api/dimension_info.md Co-authored-by: alejandrodnm <[email protected]> Signed-off-by: Mats Kindahl <[email protected]> --------- Signed-off-by: Mats Kindahl <[email protected]> Co-authored-by: alejandrodnm <[email protected]>
timescale · Dec 25, 2023 · bd9be6d · bd9be6d
1 parent f924e3c
commit bd9be6d
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 8 deletions.
diff --git a/api/add_dimension.md b/api/add_dimension.md
@@ -120,6 +120,10 @@ SELECT create_hypertable('conditions', by_range('time'));
 SELECT add_dimension('conditions', by_hash('location', 4));
 ```
 
+<Highlight type="note">
+The `by_range` and `by_hash` dimension builders are an addition to TimescaleDB 2.13.
+</Highlight>
+
 Convert table `conditions` to hypertable with range partitioning on
 `time` then add three additional dimensions: one hash partitioning on
 `location`, one range partition on `time_received`, and one hash

diff --git a/api/create_hypertable.md b/api/create_hypertable.md
@@ -120,7 +120,7 @@ CREATE FUNCTION report_reported(report)
   IMMUTABLE AS
   'SELECT $1.reported';
 
-SELECT create_hypertable('measurements', by_range('report', time_partitioning_func => 'report_reported'));
+SELECT create_hypertable('measurements', by_range('report', partition_func => 'report_reported'));
 ```
 
 Time partition table `events`, on a column type `jsonb` (`event`), which has
@@ -133,7 +133,7 @@ CREATE FUNCTION event_started(jsonb)
   IMMUTABLE AS
   $func$SELECT ($1->>'started')::timestamptz$func$;
 
-SELECT create_hypertable('events', by_range('event', time_partitioning_func => 'event_started'));
+SELECT create_hypertable('events', by_range('event', partition_func => 'event_started'));
 ```
 
 [create_distributed_hypertable]: /api/:currentVersion:/distributed-hypertables/create_distributed_hypertable

diff --git a/api/dimension_info.md b/api/dimension_info.md
@@ -13,8 +13,8 @@ range and partitioning by hash.
 
 <Highlight type="tip">
 For incompatible data types (for example, `jsonb`) you can specify a function to
-the `time_partitioning_func` argument which can extract a compatible
-data type
+the `partition_func` argument of the dimension build to extract a compatible
+data type. Look in the example section below.
 </Highlight>
 
 ## Partition Function
@@ -82,6 +82,35 @@ column type is summarized below.
 | `INT`                        | INT              | 100000        |
 | `BIGINT`                     | BIGINT           | 1000000       |
 
+### Examples
+
+The simplest usage is to partition on a time column:
+
+```sql
+SELECT create_hypertable('my_table', by_range('time'));
+```
+
+In this case, the dimension builder can be excluded since
+`create_hypertable` by default assumes that a single provided column
+is range partitioned by time.
+
+If you have a table with a non-time column containing the time, for
+example a JSON column, you can add a partition function to extract the
+time. 
+
+```sql
+CREATE TABLE my_table (
+   metric_id serial not null,
+   data jsonb,
+);
+
+CREATE FUNCTION get_time(jsonb) RETURNS timestamptz AS $$
+  SELECT ($1->>'time')::timestamptz
+$$ LANGUAGE sql IMMUTABLE;
+
+SELECT create_hypertable('my_table', by_range('data', '1 day', 'get_time'));
+```
+
 ## by_hash()
 
 ### Required Arguments

diff --git a/api/dimensions.md b/api/dimensions.md
@@ -88,7 +88,7 @@ num_partitions    | 2
 ```
 
 <Highlight type="note">
-The `by_range` and `by_hash` dimension builder is an addition to TimescaleDB 2.13.
+The `by_range` and `by_hash` dimension builders are an addition to TimescaleDB 2.13.
 </Highlight>
 
 Get information about dimensions of a hypertable that has two time-based dimensions.

diff --git a/api/time_bucket_ng.md b/api/time_bucket_ng.md
@@ -181,7 +181,13 @@ ORDER BY bucket;
 ```
 
 <Highlight type="note">
-The `by_range` dimension builder is an addition to TimescaleDB 2.13.
+The `by_range` dimension builder is an addition to TimescaleDB
+2.13. For simpler cases, like this one, you can also create the
+hypertable using the old syntax:
+
+```sql
+SELECT create_hypertable('<table name>', '<time column name>');
+```
 </Highlight>
 
 For more information, see the [continuous aggregates documentation][caggs].

diff --git a/migrate/dual-write-and-backfill/dual-write-from-postgres.md b/migrate/dual-write-and-backfill/dual-write-from-postgres.md
@@ -103,12 +103,19 @@ psql -X -d "$TARGET" \
 
 For each table which should be converted to a hypertable in the target
 database, execute:
-```
+```sql
 SELECT create_hypertable('<table name>', by_range('<time column name>'));
 ```
 
 <Highlight type="note">
-The `by_range` dimension builder is an addition to TimescaleDB 2.13.
+
+The `by_range` dimension builder is an addition to TimescaleDB
+2.13. For simpler cases, like this one, you can also create the
+hypertable using the old syntax:
+
+```sql
+SELECT create_hypertable('<table name>', '<time column name>');
+```
 </Highlight>
 
 For more information about the options which you can pass to