Make create_hypertable non-experimental

Move experimental functions for creating hypertables and dimensions to
public schema and allow the new and old interface to be overloaded.

This is done by introducing a Dimension object that contain the
information about the dimension and then pass that to the
create_hypertable function. This allow the old and the new interface to
be used interchangably.

.unreleased/feature_5761

@@ -1 +1,2 @@
 Implements: #5761 Simplify hypertable DDL API
+Thanks: @pdipesh02 for contributing to this feature

sql/ddl_api.sql

@@ -62,6 +62,25 @@ CREATE OR REPLACE FUNCTION @[email protected]_distributed_hypertable(
     data_nodes              NAME[] = NULL
 ) RETURNS TABLE(hypertable_id INT, schema_name NAME, table_name NAME, created BOOL) AS '@MODULE_PATHNAME@', 'ts_hypertable_distributed_create' LANGUAGE C VOLATILE;
 
+-- A generalized hypertable creation API that can be used to convert a PostgreSQL table
+-- with TIME/SERIAL/BIGSERIAL columns to a hypertable.
+--
+-- relation - The OID of the table to be converted
+-- partition_column - Name of the partition column
+-- partition_interval (Optional) Initial interval for the chunks
+-- partition_func (Optional) Partitioning function to be used for partition column
+-- create_default_indexes (Optional) Whether or not to create the default indexes
+-- if_not_exists (Optional) Do not fail if table is already a hypertable
+-- migrate_data (Optional) Set to true to migrate any existing data in the table to chunks
+CREATE OR REPLACE FUNCTION @[email protected]_hypertable(
+    relation                REGCLASS,
+    dimension               _timescaledb_internal.dimension_info,
+    create_default_indexes  BOOLEAN = TRUE,
+    if_not_exists           BOOLEAN = FALSE,
+    migrate_data            BOOLEAN = FALSE
+) RETURNS TABLE(hypertable_id INT, created BOOL) AS '@MODULE_PATHNAME@', 'ts_hypertable_create_general' LANGUAGE C VOLATILE;
+
+
 -- Set adaptive chunking. To disable, set chunk_target_size => 'off'.
 CREATE OR REPLACE FUNCTION @[email protected]_adaptive_chunking(
     hypertable                     REGCLASS,
@@ -70,7 +89,7 @@ CREATE OR REPLACE FUNCTION @[email protected]_adaptive_chunking(
     OUT chunk_target_size          BIGINT
 ) RETURNS RECORD AS '@MODULE_PATHNAME@', 'ts_chunk_adaptive_set' LANGUAGE C VOLATILE;
 
--- Update chunk_time_interval for a hypertable.
+-- Update chunk_time_interval for a hypertable [DEPRECATED].
 --
 -- hypertable - The OID of the table corresponding to a hypertable whose time
 --     interval should be updated
@@ -84,6 +103,20 @@ CREATE OR REPLACE FUNCTION @[email protected]_chunk_time_interval(
     dimension_name          NAME = NULL
 ) RETURNS VOID AS '@MODULE_PATHNAME@', 'ts_dimension_set_interval' LANGUAGE C VOLATILE;
 
+-- Update partition_interval for a hypertable.
+--
+-- hypertable - The OID of the table corresponding to a hypertable whose
+--     partition interval should be updated
+-- partition_interval - The new interval. For hypertables with integral/serial/bigserial
+--     time columns, this must be an integral type. For hypertables with a
+--     TIMESTAMP/TIMESTAMPTZ/DATE type, it can be integral which is treated as
+--     microseconds, or an INTERVAL type.
+CREATE OR REPLACE FUNCTION @[email protected]_partitioning_interval(
+    hypertable              REGCLASS,
+    partition_interval      ANYELEMENT,
+    dimension_name          NAME = NULL
+) RETURNS VOID AS '@MODULE_PATHNAME@', 'ts_dimension_set_interval' LANGUAGE C VOLATILE;
+
 CREATE OR REPLACE FUNCTION @[email protected]_number_partitions(
     hypertable              REGCLASS,
     number_partitions       INTEGER,
@@ -109,12 +142,23 @@ CREATE OR REPLACE FUNCTION @[email protected]_chunks(
 ) RETURNS SETOF REGCLASS AS '@MODULE_PATHNAME@', 'ts_chunk_show_chunks'
 LANGUAGE C STABLE PARALLEL SAFE;
 
--- Add a dimension (of partitioning) to a hypertable
+CREATE OR REPLACE FUNCTION @[email protected](column_name NAME, number_partitions INTEGER,
+      	  	  	   		      partition_func regproc = NULL)
+    RETURNS _timescaledb_internal.dimension_info
+    LANGUAGE C AS '@MODULE_PATHNAME@', 'ts_hash_dimension';
+
+CREATE OR REPLACE FUNCTION @[email protected](column_name NAME,
+					       partition_interval ANYELEMENT = NULL::bigint,
+       	  	  	   		       partition_func regproc = NULL)
+    RETURNS _timescaledb_internal.dimension_info
+    LANGUAGE C AS '@MODULE_PATHNAME@', 'ts_range_dimension';
+
+-- Add a dimension (of partitioning) to a hypertable [DEPRECATED]
 --
 -- hypertable - OID of the table to add a dimension to
 -- column_name - NAME of the column to use in partitioning for this dimension
 -- number_partitions - Number of partitions, for non-time dimensions
--- interval_length - Size of intervals for time dimensions (can be integral or INTERVAL)
+-- chunk_time_interval - Size of intervals for time dimensions (can be integral or INTERVAL)
 -- partitioning_func - Function used to partition the column
 -- if_not_exists - If set, and the dimension already exists, generate a notice instead of an error
 CREATE OR REPLACE FUNCTION @[email protected]_dimension(
@@ -127,6 +171,18 @@ CREATE OR REPLACE FUNCTION @[email protected]_dimension(
 ) RETURNS TABLE(dimension_id INT, schema_name NAME, table_name NAME, column_name NAME, created BOOL)
 AS '@MODULE_PATHNAME@', 'ts_dimension_add' LANGUAGE C VOLATILE;
 
+-- Add a dimension (of partitioning) to a hypertable.
+--
+-- hypertable - OID of the table to add a dimension to
+-- dimension - Dimension to add
+-- if_not_exists - If set, and the dimension already exists, generate a notice instead of an error
+CREATE OR REPLACE FUNCTION @[email protected]_dimension(
+    hypertable              REGCLASS,
+    dimension               _timescaledb_internal.dimension_info,
+    if_not_exists           BOOLEAN = FALSE
+) RETURNS TABLE(dimension_id INT, created BOOL)
+AS '@MODULE_PATHNAME@', 'ts_dimension_add_general' LANGUAGE C VOLATILE;
+
 CREATE OR REPLACE FUNCTION @[email protected]_tablespace(
     tablespace NAME,
     hypertable REGCLASS,
@@ -166,7 +222,7 @@ CREATE OR REPLACE FUNCTION @[email protected]_data_node(
     if_exists              BOOLEAN = FALSE,
     force                  BOOLEAN = FALSE,
     repartition            BOOLEAN = TRUE,
-	drop_database          BOOLEAN = FALSE
+        drop_database          BOOLEAN = FALSE
 ) RETURNS BOOLEAN AS '@MODULE_PATHNAME@', 'ts_data_node_delete' LANGUAGE C VOLATILE;
 
 -- Attach a data node to a distributed hypertable
@@ -185,7 +241,7 @@ CREATE OR REPLACE FUNCTION @[email protected]_data_node(
     if_attached            BOOLEAN = FALSE,
     force                  BOOLEAN = FALSE,
     repartition            BOOLEAN = TRUE,
-	drop_remote_data       BOOLEAN = FALSE
+        drop_remote_data       BOOLEAN = FALSE
 ) RETURNS INTEGER
 AS '@MODULE_PATHNAME@', 'ts_data_node_detach' LANGUAGE C VOLATILE;
 
@@ -222,6 +278,6 @@ CREATE OR REPLACE FUNCTION @[email protected]_data_node(
     host                   TEXT = NULL,
     database               NAME = NULL,
     port                   INTEGER = NULL,
-	available              BOOLEAN = NULL
+        available              BOOLEAN = NULL
 ) RETURNS TABLE(node_name NAME, host TEXT, port INTEGER, database NAME, available BOOLEAN)
 AS '@MODULE_PATHNAME@', 'ts_data_node_alter' LANGUAGE C VOLATILE;

sql/ddl_experimental.sql

@@ -47,55 +47,3 @@ CREATE OR REPLACE FUNCTION timescaledb_experimental.subscription_exec(
 CREATE OR REPLACE PROCEDURE timescaledb_experimental.cleanup_copy_chunk_operation(
     operation_id NAME)
 AS '@MODULE_PATHNAME@', 'ts_copy_chunk_cleanup_proc' LANGUAGE C;
-
--- A generalized hypertable creation API that can be used to convert a PostgreSQL table
--- with TIME/SERIAL/BIGSERIAL columns to a hypertable.
---
--- relation - The OID of the table to be converted
--- partition_column - Name of the partition column
--- partition_interval (Optional) Initial interval for the chunks
--- partition_func (Optional) Partitioning function to be used for partition column
--- create_default_indexes (Optional) Whether or not to create the default indexes
--- if_not_exists (Optional) Do not fail if table is already a hypertable
--- migrate_data (Optional) Set to true to migrate any existing data in the table to chunks
-CREATE OR REPLACE FUNCTION timescaledb_experimental.create_hypertable(
-    relation                REGCLASS,
-    partition_column        NAME,
-    partition_interval      ANYELEMENT = NULL::BIGINT,
-    partition_func          REGPROC = NULL,
-    create_default_indexes  BOOLEAN = TRUE,
-    if_not_exists           BOOLEAN = FALSE,
-    migrate_data            BOOLEAN = FALSE
-) RETURNS TABLE(hypertable_id INT, created BOOL) AS '@MODULE_PATHNAME@', 'ts_hypertable_create_general' LANGUAGE C VOLATILE;
-
--- Add a dimension (of partitioning) to a hypertable
---
--- hypertable - OID of the table to add a dimension to
--- column_name - NAME of the column to use in partitioning for this dimension
--- number_partitions - Number of partitions, for closed dimensions
--- partition_interval - Size of intervals for open dimensions (can be integral or INTERVAL)
--- partition_func - Function used to partition the column
--- if_not_exists - If set, and the dimension already exists, generate a notice instead of an error
-CREATE OR REPLACE FUNCTION timescaledb_experimental.add_dimension(
-    hypertable              REGCLASS,
-    column_name             NAME,
-    number_partitions       INTEGER = NULL,
-    partition_interval      ANYELEMENT = NULL::BIGINT,
-    partition_func          REGPROC = NULL,
-    if_not_exists           BOOLEAN = FALSE
-) RETURNS TABLE(dimension_id INT, created BOOL)
-AS '@MODULE_PATHNAME@', 'ts_dimension_add_general' LANGUAGE C VOLATILE;
-
--- Update partition_interval for a hypertable.
---
--- hypertable - The OID of the table corresponding to a hypertable whose
---     partition interval should be updated
--- partition_interval - The new interval. For hypertables with integral/serial/bigserial
---     time columns, this must be an integral type. For hypertables with a
---     TIMESTAMP/TIMESTAMPTZ/DATE type, it can be integral which is treated as
---     microseconds, or an INTERVAL type.
-CREATE OR REPLACE FUNCTION timescaledb_experimental.set_partitioning_interval(
-    hypertable              REGCLASS,
-    partition_interval      ANYELEMENT,
-    dimension_name          NAME = NULL
-) RETURNS VOID AS '@MODULE_PATHNAME@', 'ts_dimension_set_interval' LANGUAGE C VOLATILE;

sql/partitioning.sql

@@ -10,4 +10,3 @@ CREATE OR REPLACE FUNCTION _timescaledb_functions.get_partition_for_key(val anye
 CREATE OR REPLACE FUNCTION _timescaledb_functions.get_partition_hash(val anyelement)
     RETURNS int
     AS '@MODULE_PATHNAME@', 'ts_get_partition_hash' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
-

sql/pre_install/types.functions.sql

@@ -40,3 +40,11 @@ CREATE OR REPLACE FUNCTION _timescaledb_functions.rxid_in(cstring) RETURNS @exts
 
 CREATE OR REPLACE FUNCTION _timescaledb_functions.rxid_out(@[email protected]) RETURNS cstring
     AS '@MODULE_PATHNAME@', 'ts_remote_txn_id_out' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+
+CREATE OR REPLACE FUNCTION _timescaledb_functions.dimension_info_in(cstring)
+    RETURNS _timescaledb_internal.dimension_info
+    AS '@MODULE_PATHNAME@', 'ts_dimension_info_in' LANGUAGE C STRICT IMMUTABLE;
+
+CREATE OR REPLACE FUNCTION _timescaledb_functions.dimension_info_out(_timescaledb_internal.dimension_info)
+    RETURNS cstring
+    AS '@MODULE_PATHNAME@', 'ts_dimension_info_out' LANGUAGE C STRICT IMMUTABLE;

sql/pre_install/types.post.sql

@@ -23,3 +23,14 @@ CREATE TYPE @[email protected] (
   input = _timescaledb_functions.rxid_in,
   output = _timescaledb_functions.rxid_out
 );
+
+--
+-- Dimension type used in create_hypertable, add_dimension, etc. It is
+-- deliberately an opaque type.
+--
+CREATE TYPE _timescaledb_internal.dimension_info (
+    INPUT = _timescaledb_functions.dimension_info_in,
+    OUTPUT = _timescaledb_functions.dimension_info_out,
+    INTERNALLENGTH = VARIABLE
+);
+

sql/pre_install/types.pre.sql

@@ -12,4 +12,10 @@ CREATE TYPE _timescaledb_internal.compressed_data;
 --
 CREATE TYPE @[email protected];
 
+--
+-- Dimension type used in create_hypertable, add_dimension, etc. It is
+-- deliberately an opaque type.
+--
+CREATE TYPE _timescaledb_internal.dimension_info;
+
 --placeholder to allow creation of functions below

sql/updates/latest-dev.sql

@@ -1,25 +1,30 @@
+CREATE FUNCTION @[email protected](column_name NAME, number_partitions INTEGER,
+                                            partition_func regproc = NULL)
+RETURNS _timescaledb_internal.dimension_info LANGUAGE C AS '@MODULE_PATHNAME@', 'ts_hash_dimension';
+
+CREATE FUNCTION @[email protected](column_name NAME,
+                                             partition_interval ANYELEMENT = NULL::bigint,
+                                             partition_func regproc = NULL)
+RETURNS _timescaledb_internal.dimension_info LANGUAGE C AS '@MODULE_PATHNAME@', 'ts_range_dimension';
+
 -- API changes related to hypertable generalization
-CREATE OR REPLACE FUNCTION timescaledb_experimental.create_hypertable(
+CREATE FUNCTION @extschema@.create_hypertable(
     relation                REGCLASS,
-    partition_column        NAME,
-    partition_interval      ANYELEMENT = NULL::BIGINT,
-    partition_func          REGPROC = NULL,
+    dimension               _timescaledb_internal.dimension_info,
     create_default_indexes  BOOLEAN = TRUE,
     if_not_exists           BOOLEAN = FALSE,
     migrate_data            BOOLEAN = FALSE
-) RETURNS TABLE(hypertable_id INT, created BOOL) AS '@MODULE_PATHNAME@', 'ts_hypertable_create_general' LANGUAGE C VOLATILE;
+) RETURNS TABLE(hypertable_id INT, created BOOL)
+AS '@MODULE_PATHNAME@', 'ts_hypertable_create_general' LANGUAGE C VOLATILE;
 
-CREATE OR REPLACE FUNCTION timescaledb_experimental.add_dimension(
+CREATE FUNCTION @extschema@.add_dimension(
     hypertable              REGCLASS,
-    column_name             NAME,
-    number_partitions       INTEGER = NULL,
-    partition_interval      ANYELEMENT = NULL::BIGINT,
-    partition_func          REGPROC = NULL,
+    dimension               _timescaledb_internal.dimension_info,
     if_not_exists           BOOLEAN = FALSE
 ) RETURNS TABLE(dimension_id INT, created BOOL)
 AS '@MODULE_PATHNAME@', 'ts_dimension_add_general' LANGUAGE C VOLATILE;
 
-CREATE OR REPLACE FUNCTION timescaledb_experimental.set_partitioning_interval(
+CREATE FUNCTION @extschema@.set_partitioning_interval(
     hypertable              REGCLASS,
     partition_interval      ANYELEMENT,
     dimension_name          NAME = NULL