timescaledb-rails 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12170e03389f6ac4f3bba7816dfb20dc75a47103032ec3e3799f3c78dca25a4b
-  data.tar.gz: f26796af01f755648e952f9e851f24d05d7adb3439e3653d793beef624ea8044
+  metadata.gz: 7fc0e42b6db3e42267d014923180abf3c64a643937942b8b3f17ad9b2a3bf223
+  data.tar.gz: 96c3105df56f184894cdd7e3ca8658b083a87e8a050711c17e52eeae6c836c3e
 SHA512:
-  metadata.gz: 22c4c72512895fadb2a7701222e6b890b60a15948dc9c6b5c01ded24afff9865d6ebc954673452b55b95ac68b18c933dc2bf7aec6ac135285ecfa950d346e8e3
-  data.tar.gz: f67c442f8d2eb837566f8cc3a450d809a769343799997f3979a222bd0413c2ce89fad70b9b8f3e96267ab61e8bcf3cc2c167c15a60db1f1144ea17daf9cfee36
+  metadata.gz: 9988f806f0512c73456e531dd42dfe3f3c5765d9ee426bcf6f4b45e3098568fcac3518884abde8fb473a42cba66d73aa4558631b2806256ea4726496a212bdb9
+  data.tar.gz: e85fa03def618ed5d114275a6f2b929871ca0c0ea52e95ada85cca332baa2f1252f8a6bc3fc29be544aaa8dc8225dbcda52df83903bedd530a63b3683be30e8b

data/README.md

@@ -93,26 +93,67 @@ class AddEventReorderPolicy < ActiveRecord::Migration[7.0]
 end
 ```
 
+Create continuous aggregate
+
+```ruby
+class CreateTemperatureEventAggregate < ActiveRecord::Migration[7.0]
+  def up
+    create_continuous_aggregate(
+      :temperature_events,
+      Event.time_bucket(1.day).avg(:value).temperature.to_sql
+    )
+
+    add_continuous_aggregate_policy(:temperature_events, 1.month, 1.day, 1.hour)
+  end
+
+  def down
+    drop_continuous_aggregate(:temperature_events)
+
+    remove_continuous_aggregate_policy(:temperature_events)
+  end
+end
+```
+
+> **Reversible Migrations:**
+>
+> Above examples implement `up`/`down` methods to better document all the different APIs. Feel free to use `change` method, timescaledb-rails defines all the reverse calls for each API method so Active Record can automatically figure out how to reverse your migration.
+
 ### Models
 
 If one of your models need TimescaleDB support, just include `Timescaledb::Rails::Model`
+
 ```ruby
-class Event < ActiveRecord::Base
+class Payload < ActiveRecord::Base
   include Timescaledb::Rails::Model
+
+  self.primary_key = 'id'
 end
 ```
 
-If the hypertable does not belong to the default schema, don't forget to override `table_name`
+When hypertable belongs to a non default schema, don't forget to override `table_name`
 
 ```ruby
 class Event < ActiveRecord::Base
   include Timescaledb::Rails::Model
 
-  self.table_name = 'v1.events'
+  self.table_name = 'tdb.events'
 end
 ```
 
-If you need to query data for a specific time period, `Timescaledb::Rails::Model` incluldes useful scopes
+Using `.find` is not recommended, to achieve more performat results, use these other find methods
+
+```ruby
+# When you know the exact time value
+Payload.find_at_time(111, Time.new(2022, 01, 01, 10, 15, 30))
+
+# If you know that the record occurred after a given time
+Payload.find_after(222, 11.days.ago)
+
+# Lastly, if you want to scope the search by a time range
+Payload.find_between(333, 1.week.ago, 1.day.ago)
+```
+
+If you need to query data for a specific time period, `Timescaledb::Rails::Model` includes useful scopes
 
 ```ruby
 # If you want to get all records from last year
@@ -136,6 +177,19 @@ Here the list of all available scopes
 * yesterday
 * today
 
+If you still need to query data by other time periods, take a look at these other scopes
+
+```ruby
+# If you want to get all records that occurred in the last 30 minutes
+Event.after(30.minutes.ago) #=> [#<Event name...>, ...]
+
+# If you want to get records that occurred in the last 4 days, excluding today
+Event.between(4.days.ago, 1.day.ago) #=> [#<Event name...>, ...]
+
+# If you want to get records that occurred at a specific time
+Event.at_time(Time.new(2023, 01, 04, 10, 20, 30)) #=> [#<Event name...>, ...]
+```
+
 If you need information about your hypertable, use the following helper methods to get useful information
 
 ```ruby
@@ -165,6 +219,53 @@ chunk.compress! unless chunk.is_compressed?
 chunk.decompress! if chunk.is_compressed?
 ```
 
+If you need to reorder a specific chunk
+
+```ruby
+chunk = Event.hypertable_chunks.first
+
+# If an index is not specified, it will use the one from the reorder policy
+# In case there is no reorder policy index it will raise an ArgumentError
+chunk.reorder!
+
+# If an index is specified it will use that index
+chunk.reorder!(index)
+```
+
+If you need to manually refresh a continuous aggregate
+
+```ruby
+aggregate = Event.hypertable.continuous_aggregates.first
+
+aggregate.refresh!(5.days.ago, 1.day.ago)
+```
+
+### Hyperfunctions
+
+#### Time bucket
+
+You can call the time bucket function with an interval (note that leaving the target column blank will use the default time column of the hypertable)
+
+```ruby
+Event.time_bucket(1.day)
+
+Event.time_bucket('1 day')
+
+Event.time_bucket(1.day, :created_at)
+
+Event.time_bucket(1.day, 'occurred_at')
+```
+
+You may add aggregation like so:
+
+```ruby
+Event.time_bucket(1.day).avg(:column)
+Event.time_bucket(1.day).sum(:column)
+Event.time_bucket(1.day).min(:column)
+Event.time_bucket(1.day).max(:column)
+Event.time_bucket(1.day).count
+```
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests.

data/lib/timescaledb/rails/extensions/active_record/command_recorder.rb

@@ -33,6 +33,22 @@ module Timescaledb
           record(:remove_hypertable_retention_policy, args, &block)
         end
 
+        def create_continuous_aggregate(*args, &block)
+          record(:create_continuous_aggregate, args, &block)
+        end
+
+        def drop_continuous_aggregate(*args, &block)
+          record(:drop_continuous_aggregate, args, &block)
+        end
+
+        def add_continuous_aggregate_policy(*args, &block)
+          record(:add_continuous_aggregate_policy, args, &block)
+        end
+
+        def remove_continuous_aggregate_policy(*args, &block)
+          record(:remove_continuous_aggregate_policy, args, &block)
+        end
+
         def invert_create_hypertable(args, &block)
           if block.nil?
             raise ::ActiveRecord::IrreversibleMigration, 'create_hypertable is only reversible if given a block (can be empty).' # rubocop:disable Layout/LineLength
@@ -76,6 +92,30 @@ module Timescaledb
 
           [:add_hypertable_reorder_policy, args, block]
         end
+
+        def invert_create_continuous_aggregate(args, &block)
+          [:drop_continuous_aggregate, args, block]
+        end
+
+        def invert_drop_continuous_aggregate(args, &block)
+          if args.size < 2
+            raise ::ActiveRecord::IrreversibleMigration, 'drop_continuous_aggregate is only reversible if given view name and view query.' # rubocop:disable Layout/LineLength
+          end
+
+          [:create_continuous_aggregate, args, block]
+        end
+
+        def invert_add_continuous_aggregate_policy(args, &block)
+          [:remove_continuous_aggregate_policy, args, block]
+        end
+
+        def invert_remove_continuous_aggregate_policy(args, &block)
+          if args.size < 4
+            raise ::ActiveRecord::IrreversibleMigration, 'remove_continuous_aggregate_policy is only reversible if given view name, start offset, end offset and schedule interval.' # rubocop:disable Layout/LineLength
+          end
+
+          [:add_continuous_aggregate_policy, args, block]
+        end
       end
     end
   end

data/lib/timescaledb/rails/extensions/active_record/postgresql_database_tasks.rb

@@ -7,16 +7,22 @@ module Timescaledb
   module Rails
     module ActiveRecord
       # :nodoc:
+      # rubocop:disable Layout/LineLength
       module PostgreSQLDatabaseTasks
         # @override
-        def structure_dump(filename, extra_flags) # rubocop:disable Metrics/MethodLength
+        def structure_dump(filename, extra_flags)
           extra_flags = Array(extra_flags)
-          extra_flags << timescale_structure_dump_default_flags if timescale_enabled?
+          extra_flags |= timescale_structure_dump_default_flags if timescale_enabled?
 
           super(filename, extra_flags)
 
           return unless timescale_enabled?
 
+          hypertables(filename)
+          continuous_aggregates(filename)
+        end
+
+        def hypertables(filename)
           File.open(filename, 'a') do |file|
             Timescaledb::Rails::Hypertable.all.each do |hypertable|
               drop_ts_insert_trigger_statment(hypertable, file)
@@ -28,17 +34,26 @@ module Timescaledb
           end
         end
 
+        def continuous_aggregates(filename)
+          File.open(filename, 'a') do |file|
+            Timescaledb::Rails::ContinuousAggregate.all.each do |continuous_aggregate|
+              create_continuous_aggregate_statement(continuous_aggregate, file)
+              add_continuous_aggregate_policy_statement(continuous_aggregate, file)
+            end
+          end
+        end
+
         def drop_ts_insert_trigger_statment(hypertable, file)
           file << "---\n"
-          file << "--- Drop ts_insert_blocker previously created by pg_dump to avoid pg errors, create_hypertable will re-create it again.\n" # rubocop:disable Layout/LineLength
+          file << "--- Drop ts_insert_blocker previously created by pg_dump to avoid pg errors, create_hypertable will re-create it again.\n"
           file << "---\n\n"
-          file << "DROP TRIGGER IF EXISTS ts_insert_blocker ON #{hypertable.hypertable_name};\n"
+          file << "DROP TRIGGER IF EXISTS ts_insert_blocker ON #{hypertable.hypertable_schema}.#{hypertable.hypertable_name};\n"
         end
 
         def create_hypertable_statement(hypertable, file)
           options = hypertable_options(hypertable)
 
-          file << "SELECT create_hypertable('#{hypertable.hypertable_name}', '#{hypertable.time_column_name}', #{options});\n\n" # rubocop:disable Layout/LineLength
+          file << "SELECT create_hypertable('#{hypertable.hypertable_schema}.#{hypertable.hypertable_name}', '#{hypertable.time_column_name}', #{options});\n\n"
         end
 
         def add_hypertable_compression_statement(hypertable, file)
@@ -46,20 +61,35 @@ module Timescaledb
 
           options = hypertable_compression_options(hypertable)
 
-          file << "ALTER TABLE #{hypertable.hypertable_name} SET (#{options});\n\n"
-          file << "SELECT add_compression_policy('#{hypertable.hypertable_name}', INTERVAL '#{hypertable.compression_policy_interval}');\n\n" # rubocop:disable Layout/LineLength
+          file << "ALTER TABLE #{hypertable.hypertable_schema}.#{hypertable.hypertable_name} SET (#{options});\n\n"
+          file << "SELECT add_compression_policy('#{hypertable.hypertable_schema}.#{hypertable.hypertable_name}', INTERVAL '#{hypertable.compression_policy_interval}');\n\n"
         end
 
         def add_hypertable_reorder_policy_statement(hypertable, file)
           return unless hypertable.reorder?
 
-          file << "SELECT add_reorder_policy('#{hypertable.hypertable_name}', '#{hypertable.reorder_policy_index_name}');\n\n" # rubocop:disable Layout/LineLength
+          file << "SELECT add_reorder_policy('#{hypertable.hypertable_schema}.#{hypertable.hypertable_name}', '#{hypertable.reorder_policy_index_name}');\n\n"
         end
 
         def add_hypertable_retention_policy_statement(hypertable, file)
           return unless hypertable.retention?
 
-          file << "SELECT add_retention_policy('#{hypertable.hypertable_name}', INTERVAL '#{hypertable.retention_policy_interval}');\n\n" # rubocop:disable Layout/LineLength
+          file << "SELECT add_retention_policy('#{hypertable.hypertable_schema}.#{hypertable.hypertable_name}', INTERVAL '#{hypertable.retention_policy_interval}');\n\n"
+        end
+
+        def create_continuous_aggregate_statement(continuous_aggregate, file)
+          file << "CREATE MATERIALIZED VIEW #{continuous_aggregate.view_schema}.#{continuous_aggregate.view_name} WITH (timescaledb.continuous) AS\n"
+          file << "#{continuous_aggregate.view_definition.strip.indent(2)}\n\n"
+        end
+
+        def add_continuous_aggregate_policy_statement(continuous_aggregate, file)
+          return unless continuous_aggregate.refresh?
+
+          start_offset = continuous_aggregate.refresh_start_offset
+          end_offset = continuous_aggregate.refresh_end_offset
+          schedule_interval = continuous_aggregate.refresh_schedule_interval
+
+          file << "SELECT add_continuous_aggregate_policy('#{continuous_aggregate.view_schema}.#{continuous_aggregate.view_name}', start_offset => INTERVAL '#{start_offset}', end_offset => INTERVAL '#{end_offset}', schedule_interval => INTERVAL '#{schedule_interval}');\n\n"
         end
 
         def hypertable_options(hypertable)
@@ -93,11 +123,18 @@ module Timescaledb
           hypertable.compression_segment_settings.map(&:attname)
         end
 
-        # Returns `pg_dump` flag to exclude `_timescaledb_internal` schema tables.
+        # Returns `pg_dump` flags to exclude `_timescaledb_internal` schema tables and
+        # exclude the corresponding continuous aggregate views.
         #
-        # @return [String]
+        # @return [Array<String>]
         def timescale_structure_dump_default_flags
-          '--exclude-schema=_timescaledb_internal'
+          flags = ['--exclude-schema=_timescaledb_internal']
+
+          Timescaledb::Rails::ContinuousAggregate.pluck(:view_schema, :view_name).each do |view_schema, view_name|
+            flags << "--exclude-table=#{view_schema}.#{view_name}"
+          end
+
+          flags
         end
 
         # @return [Boolean]
@@ -105,6 +142,7 @@ module Timescaledb
           Timescaledb::Rails::Hypertable.table_exists?
         end
       end
+      # rubocop:enable Layout/LineLength
     end
   end
 end

data/lib/timescaledb/rails/extensions/active_record/schema_dumper.rb

@@ -7,7 +7,46 @@ module Timescaledb
   module Rails
     module ActiveRecord
       # :nodoc:
-      module SchemaDumper
+      module SchemaDumper # rubocop:disable Metrics/ModuleLength
+        # @override
+        def tables(stream)
+          super
+
+          continuous_aggregates(stream)
+          stream
+        end
+
+        def continuous_aggregates(stream)
+          return unless timescale_enabled?
+
+          Timescaledb::Rails::ContinuousAggregate.all.each do |continuous_aggregate|
+            continuous_aggregate(continuous_aggregate, stream)
+            continuous_aggregate_policy(continuous_aggregate, stream)
+          end
+        end
+
+        def continuous_aggregate(continuous_aggregate, stream)
+          stream.puts "  create_continuous_aggregate #{continuous_aggregate.view_name.inspect}, <<-SQL"
+          stream.puts "  #{continuous_aggregate.view_definition.strip.indent(2)}"
+          stream.puts '  SQL'
+          stream.puts
+        end
+
+        def continuous_aggregate_policy(continuous_aggregate, stream)
+          return unless continuous_aggregate.refresh?
+
+          options = [
+            continuous_aggregate.view_name.inspect,
+            continuous_aggregate.refresh_start_offset.inspect,
+            continuous_aggregate.refresh_end_offset.inspect,
+            continuous_aggregate.refresh_schedule_interval.inspect
+          ]
+
+          stream.puts "  add_continuous_aggregate_policy #{options.join(', ')}"
+          stream.puts
+        end
+
+        # @override
         def table(table, stream)
           super(table, stream)
 

data/lib/timescaledb/rails/extensions/active_record/schema_statements.rb

@@ -37,7 +37,7 @@ module Timescaledb
             create_table(table_name, id: false, primary_key: primary_key, force: force, **options, &block)
           end
 
-          execute "SELECT create_hypertable('#{table_name}', '#{time_column_name}', #{options_as_sql})"
+          execute "SELECT create_hypertable('#{table_name}', '#{time_column_name}', #{options_as_sql});"
         end
 
         # Enables compression and sets compression options.
@@ -51,17 +51,18 @@ module Timescaledb
           options << "timescaledb.compress_orderby = '#{order_by}'" unless order_by.nil?
           options << "timescaledb.compress_segmentby = '#{segment_by}'" unless segment_by.nil?
 
-          execute "ALTER TABLE #{table_name} SET (#{options.join(', ')})"
+          execute "ALTER TABLE #{table_name} SET (#{options.join(', ')});"
 
-          execute "SELECT add_compression_policy('#{table_name}', INTERVAL '#{compress_after.inspect}')"
+          execute "SELECT add_compression_policy('#{table_name}', INTERVAL '#{stringify_interval(compress_after)}');"
         end
 
-        # Disables compression from given table.
+        # Removes compression policy and disables compression from given hypertable.
         #
         #   remove_hypertable_compression('events')
         #
         def remove_hypertable_compression(table_name, compress_after = nil, segment_by: nil, order_by: nil) # rubocop:disable Lint/UnusedMethodArgument
-          execute "SELECT remove_compression_policy('#{table_name.inspect}');"
+          execute "SELECT remove_compression_policy('#{table_name}');"
+          execute "ALTER TABLE #{table_name.inspect} SET (timescaledb.compress = false);"
         end
 
         # Add a data retention policy to given hypertable.
@@ -69,7 +70,7 @@ module Timescaledb
         #   add_hypertable_retention_policy('events', 7.days)
         #
         def add_hypertable_retention_policy(table_name, drop_after)
-          execute "SELECT add_retention_policy('#{table_name}', INTERVAL '#{drop_after.inspect}')"
+          execute "SELECT add_retention_policy('#{table_name}', INTERVAL '#{stringify_interval(drop_after)}');"
         end
 
         # Removes data retention policy from given hypertable.
@@ -77,7 +78,7 @@ module Timescaledb
         #   remove_hypertable_retention_policy('events')
         #
         def remove_hypertable_retention_policy(table_name, _drop_after = nil)
-          execute "SELECT remove_retention_policy('#{table_name}')"
+          execute "SELECT remove_retention_policy('#{table_name}');"
         end
 
         # Adds a policy to reorder chunks on a given hypertable index in the background.
@@ -85,7 +86,7 @@ module Timescaledb
         #   add_hypertable_reorder_policy('events', 'index_events_on_created_at_and_name')
         #
         def add_hypertable_reorder_policy(table_name, index_name)
-          execute "SELECT add_reorder_policy('#{table_name}', '#{index_name}')"
+          execute "SELECT add_reorder_policy('#{table_name}', '#{index_name}');"
         end
 
         # Removes a policy to reorder a particular hypertable.
@@ -93,14 +94,60 @@ module Timescaledb
         #   remove_hypertable_reorder_policy('events')
         #
         def remove_hypertable_reorder_policy(table_name, _index_name = nil)
-          execute "SELECT remove_reorder_policy('#{table_name}')"
+          execute "SELECT remove_reorder_policy('#{table_name}');"
+        end
+
+        # Creates a continuous aggregate
+        #
+        #   create_continuous_aggregate(
+        #     'temperature_events', "SELECT * FROM events where event_type = 'temperature'"
+        #   )
+        #
+        def create_continuous_aggregate(view_name, view_query)
+          execute "CREATE MATERIALIZED VIEW #{view_name} WITH (timescaledb.continuous) AS #{view_query};"
+        end
+
+        # Drops a continuous aggregate
+        #
+        #   drop_continuous_aggregate('temperature_events')
+        #
+        def drop_continuous_aggregate(view_name, _view_query = nil)
+          execute "DROP MATERIALIZED VIEW #{view_name};"
+        end
+
+        # Adds refresh continuous aggregate policy
+        #
+        #   add_continuous_aggregate_policy('temperature_events', 1.month, 1.day, 1.hour)
+        #
+        def add_continuous_aggregate_policy(view_name, start_offset, end_offset, schedule_interval)
+          start_offset = start_offset.nil? ? 'NULL' : "INTERVAL '#{stringify_interval(start_offset)}'"
+          end_offset = end_offset.nil? ? 'NULL' : "INTERVAL '#{stringify_interval(end_offset)}'"
+          schedule_interval = schedule_interval.nil? ? 'NULL' : "INTERVAL '#{stringify_interval(schedule_interval)}'"
+
+          execute "SELECT add_continuous_aggregate_policy('#{view_name}', start_offset => #{start_offset}, end_offset => #{end_offset}, schedule_interval => #{schedule_interval});" # rubocop:disable Layout/LineLength
+        end
+
+        # Removes refresh continuous aggregate policy
+        #
+        #   remove_continuous_aggregate_policy('temperature_events')
+        #
+        def remove_continuous_aggregate_policy(view_name, _start_offset = nil,
+                                               _end_offset = nil, _schedule_interval = nil)
+          execute "SELECT remove_continuous_aggregate_policy('#{view_name}');"
+        end
+
+        private
+
+        # @param [ActiveSupport::Duration|String] interval
+        def stringify_interval(interval)
+          interval.is_a?(ActiveSupport::Duration) ? interval.inspect : interval
         end
 
         # @return [String]
         def hypertable_options_to_sql(options)
           sql_statements = options.map do |option, value|
             case option
-            when :chunk_time_interval then "chunk_time_interval => INTERVAL '#{value}'"
+            when :chunk_time_interval then "chunk_time_interval => INTERVAL '#{stringify_interval(value)}'"
             when :if_not_exists then  "if_not_exists => #{value ? 'TRUE' : 'FALSE'}"
             end
           end

data/lib/timescaledb/rails/model/aggregate_functions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    module Model
+      # :nodoc:
+      module AggregateFunctions
+        def count(alias_name = 'count')
+          select("COUNT(1) AS #{alias_name}")
+        end
+
+        def avg(column_name, alias_name = 'avg')
+          select("AVG(#{column_name}) AS #{alias_name}")
+        end
+
+        def sum(column_name, alias_name = 'sum')
+          select("SUM(#{column_name}) AS #{alias_name}")
+        end
+
+        def min(column_name, alias_name = 'min')
+          select("MIN(#{column_name}) AS #{alias_name}")
+        end
+
+        def max(column_name, alias_name = 'max')
+          select("MAX(#{column_name}) AS #{alias_name}")
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/model/finder_methods.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    module Model
+      # :nodoc:
+      module FinderMethods
+        # Adds a warning message to avoid calling find without filtering by time.
+        #
+        # @override
+        def find(*args)
+          warn "WARNING: Calling `.find` without filtering by `#{hypertable_time_column_name}` could cause performance issues, use built-in find_(at_time|between|after) methods for more performant results." # rubocop:disable Layout/LineLength
+
+          super
+        end
+
+        # Finds records by primary key and chunk time.
+        #
+        # @param [Array<Integer>, Integer] id The primary key values.
+        # @param [Time, Date, Integer] time The chunk time value.
+        def find_at_time(id, time)
+          at_time(time).find(id)
+        end
+
+        # Finds records by primary key and chunk time occurring between given time range.
+        #
+        # @param [Array<Integer>, Integer] id The primary key values.
+        # @param [Time, Date, Integer] from The chunk from time value.
+        # @param [Time, Date, Integer] to The chunk to time value.
+        def find_between(id, from, to)
+          between(from, to).find(id)
+        end
+
+        # Finds records by primary key and chunk time occurring after given time.
+        #
+        # @param [Array<Integer>, Integer] id The primary key values.
+        # @param [Time, Date, Integer] from The chunk from time value.
+        def find_after(id, from)
+          after(from).find(id)
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/model/hyperfunctions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'timescaledb/rails/model/aggregate_functions'
+
+module Timescaledb
+  module Rails
+    module Model
+      # :nodoc:
+      module Hyperfunctions
+        TIME_BUCKET_ALIAS = 'time_bucket'
+
+        # @return [ActiveRecord::Relation<ActiveRecord::Base>]
+        def time_bucket(interval, target_column = nil)
+          target_column ||= hypertable_time_column_name
+
+          select("time_bucket('#{format_interval_value(interval)}', #{target_column}) as #{TIME_BUCKET_ALIAS}")
+            .group(TIME_BUCKET_ALIAS)
+            .order(TIME_BUCKET_ALIAS)
+            .extending(AggregateFunctions)
+        end
+
+        private
+
+        def format_interval_value(value)
+          value.is_a?(ActiveSupport::Duration) ? value.inspect : value
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/model/scopes.rb

@@ -12,19 +12,19 @@ module Timescaledb
           scope :last_year, lambda {
             date = Date.current - 1.year
 
-            between_time_column(date.beginning_of_year, date.end_of_year)
+            between(date.beginning_of_year, date.end_of_year)
           }
 
           scope :last_month, lambda {
             date = Date.current - 1.month
 
-            between_time_column(date.beginning_of_month, date.end_of_month)
+            between(date.beginning_of_month, date.end_of_month)
           }
 
           scope :last_week, lambda {
             date = Date.current - 1.week
 
-            between_time_column(date.beginning_of_week, date.end_of_week)
+            between(date.beginning_of_week, date.end_of_week)
           }
 
           scope :yesterday, lambda {
@@ -32,24 +32,31 @@ module Timescaledb
           }
 
           scope :this_year, lambda {
-            between_time_column(Date.current.beginning_of_year, Date.current.end_of_year)
+            between(Date.current.beginning_of_year, Date.current.end_of_year)
           }
 
           scope :this_month, lambda {
-            between_time_column(Date.current.beginning_of_month, Date.current.end_of_month)
+            between(Date.current.beginning_of_month, Date.current.end_of_month)
           }
 
           scope :this_week, lambda {
-            between_time_column(Date.current.beginning_of_week, Date.current.end_of_week)
+            between(Date.current.beginning_of_week, Date.current.end_of_week)
           }
 
           scope :today, lambda {
             where("DATE(#{hypertable_time_column_name}) = ?", Date.current)
           }
 
-          # @!visibility private
-          scope :between_time_column, lambda { |from, to|
-            where("DATE(#{hypertable_time_column_name}) BETWEEN ? AND ?", from, to)
+          scope :after, lambda { |time|
+            where("#{hypertable_time_column_name} > ?", time)
+          }
+
+          scope :at_time, lambda { |time|
+            where(hypertable_time_column_name => time)
+          }
+
+          scope :between, lambda { |from, to|
+            where(hypertable_time_column_name => from..to)
           }
         end
         # rubocop:enable Metrics/BlockLength

data/lib/timescaledb/rails/model.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'timescaledb/rails/model/finder_methods'
+require 'timescaledb/rails/model/hyperfunctions'
 require 'timescaledb/rails/model/scopes'
 
 module Timescaledb
@@ -14,25 +16,32 @@ module Timescaledb
 
       # :nodoc:
       module ClassMethods
-        delegate :time_column_name, to: :hypertable, prefix: true
+        include FinderMethods
+        include Hyperfunctions
+
+        # @return [String]
+        def hypertable_time_column_name
+          @hypertable_time_column_name ||= hypertable&.time_column_name
+        end
 
         # Returns only the name of the hypertable, table_name could include
         # the schema path, we need to remove it.
         #
         # @return [String]
         def hypertable_name
-          table_name.split('.').last
+          @hypertable_name ||= table_name.split('.').last
         end
 
         # Returns the schema where hypertable is stored.
         #
         # @return [String]
         def hypertable_schema
-          if table_name.split('.').size > 1
-            table_name.split('.')[0..-2].join('.')
-          else
-            PUBLIC_SCHEMA_NAME
-          end
+          @hypertable_schema ||=
+            if table_name.split('.').size > 1
+              table_name.split('.')[0..-2].join('.')
+            else
+              PUBLIC_SCHEMA_NAME
+            end
         end
 
         # @return [Timescaledb::Rails::Hypertable]

data/lib/timescaledb/rails/models/chunk.rb

@@ -7,6 +7,8 @@ module Timescaledb
       self.table_name = 'timescaledb_information.chunks'
       self.primary_key = 'hypertable_name'
 
+      belongs_to :hypertable, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Hypertable'
+
       scope :compressed, -> { where(is_compressed: true) }
       scope :decompressed, -> { where(is_compressed: false) }
 
@@ -25,6 +27,23 @@ module Timescaledb
           "SELECT decompress_chunk('#{chunk_full_name}')"
         )
       end
+
+      # @param index [String] The name of the index to order by
+      #
+      def reorder!(index = nil)
+        if index.blank? && !hypertable.reorder?
+          raise ArgumentError, 'Index name is required if reorder policy is not set'
+        end
+
+        index ||= hypertable.reorder_policy_index_name
+
+        options = ["'#{chunk_full_name}'"]
+        options << "'#{index}'" if index.present?
+
+        ::ActiveRecord::Base.connection.execute(
+          "SELECT reorder_chunk(#{options.join(', ')})"
+        )
+      end
     end
   end
 end

data/lib/timescaledb/rails/models/concerns/durationable.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    module Models
+      # :nodoc:
+      module Durationable
+        extend ActiveSupport::Concern
+
+        HOUR_MINUTE_SECOND_REGEX = /^\d+:\d+:\d+$/.freeze
+
+        # @return [String]
+        def parse_duration(duration)
+          duration_in_seconds = duration_in_seconds(duration)
+
+          duration_to_interval(
+            ActiveSupport::Duration.build(duration_in_seconds)
+          )
+        rescue ActiveSupport::Duration::ISO8601Parser::ParsingError
+          duration
+        end
+
+        private
+
+        # Converts different interval formats into seconds.
+        #
+        #   duration_in_seconds('P1D')      #=> 86400
+        #   duration_in_seconds('24:00:00') #=> 86400
+        #   duration_in_seconds(1.day)      #=> 86400
+        #
+        # @param [ActiveSupport::Duration|String] duration
+        # @return [Integer]
+        def duration_in_seconds(duration)
+          return duration.to_i if duration.is_a?(ActiveSupport::Duration)
+
+          if (duration =~ HOUR_MINUTE_SECOND_REGEX).present?
+            hours, minutes, seconds = duration.split(':').map(&:to_i)
+
+            (hours.hour + minutes.minute + seconds.second).to_i
+          else
+            ActiveSupport::Duration.parse(duration).to_i
+          end
+        end
+
+        # Converts given duration into a human interval readable format.
+        #
+        #   duration_to_interval(1.day)              #=> '1 day'
+        #   duration_to_interval(2.weeks + 6.days)   #=> '20 days'
+        #   duration_to_interval(1.years + 3.months) #=> '1 year 3 months'
+        #
+        # @param [ActiveSupport::Duration] duration
+        # @return [String]
+        def duration_to_interval(duration)
+          parts = duration.parts
+
+          # Combine days and weeks if both present
+          #
+          #   "1 week 2 days" => "9 days"
+          parts[:days] += parts.delete(:weeks) * 7 if parts.key?(:weeks) && parts.key?(:days)
+
+          parts.map do |(unit, quantity)|
+            "#{quantity} #{humanize_duration_unit(unit.to_s, quantity)}"
+          end.join(' ')
+        end
+
+        # Pluralize or singularize given duration unit based on given count.
+        #
+        # @param [String] duration_unit
+        # @param [Integer] count
+        def humanize_duration_unit(duration_unit, count)
+          count > 1 ? duration_unit.pluralize : duration_unit.singularize
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/models/continuous_aggregate.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'timescaledb/rails/models/concerns/durationable'
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class ContinuousAggregate < ::ActiveRecord::Base
+      include Timescaledb::Rails::Models::Durationable
+
+      self.table_name = 'timescaledb_information.continuous_aggregates'
+      self.primary_key = 'materialization_hypertable_name'
+
+      has_many :jobs, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Job'
+
+      # Manually refresh a continuous aggregate.
+      #
+      # @param [DateTime] start_time
+      # @param [DateTime] end_time
+      #
+      def refresh!(start_time = 'NULL', end_time = 'NULL')
+        ::ActiveRecord::Base.connection.execute(
+          "CALL refresh_continuous_aggregate('#{view_name}', #{start_time}, #{end_time});"
+        )
+      end
+
+      # @return [String]
+      def refresh_start_offset
+        parse_duration(refresh_job.config['start_offset'])
+      end
+
+      # @return [String]
+      def refresh_end_offset
+        parse_duration(refresh_job.config['end_offset'])
+      end
+
+      # @return [String]
+      def refresh_schedule_interval
+        interval = refresh_job.schedule_interval
+
+        interval.is_a?(String) ? parse_duration(interval) : interval.inspect
+      end
+
+      # @return [Boolean]
+      def refresh?
+        refresh_job.present?
+      end
+
+      private
+
+      # @return [Job]
+      def refresh_job
+        @refresh_job ||= jobs.policy_refresh_continuous_aggregate.first
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/models/hypertable.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
+require 'timescaledb/rails/models/concerns/durationable'
+
 module Timescaledb
   module Rails
     # :nodoc:
     class Hypertable < ::ActiveRecord::Base
+      include Timescaledb::Rails::Models::Durationable
+
       self.table_name = 'timescaledb_information.hypertables'
       self.primary_key = 'hypertable_name'
 
+      has_many :continuous_aggregates, foreign_key: 'hypertable_name',
+                                       class_name: 'Timescaledb::Rails::ContinuousAggregate'
       has_many :compression_settings, foreign_key: 'hypertable_name',
                                       class_name: 'Timescaledb::Rails::CompressionSetting'
       has_many :dimensions, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Dimension'
@@ -86,13 +92,6 @@ module Timescaledb
       def time_dimension
         @time_dimension ||= dimensions.time.first
       end
-
-      # @return [String]
-      def parse_duration(duration)
-        ActiveSupport::Duration.parse(duration).inspect
-      rescue ActiveSupport::Duration::ISO8601Parser::ParsingError
-        duration
-      end
     end
   end
 end

data/lib/timescaledb/rails/models/job.rb

@@ -10,10 +10,12 @@ module Timescaledb
       POLICY_COMPRESSION = 'policy_compression'
       POLICY_REORDER = 'policy_reorder'
       POLICY_RETENTION = 'policy_retention'
+      POLICY_REFRESH_CONTINUOUS_AGGREGATE = 'policy_refresh_continuous_aggregate'
 
       scope :policy_compression, -> { where(proc_name: POLICY_COMPRESSION) }
       scope :policy_reorder, -> { where(proc_name: POLICY_REORDER) }
       scope :policy_retention, -> { where(proc_name: POLICY_RETENTION) }
+      scope :policy_refresh_continuous_aggregate, -> { where(proc_name: POLICY_REFRESH_CONTINUOUS_AGGREGATE) }
     end
   end
 end

data/lib/timescaledb/rails/models.rb

@@ -2,6 +2,7 @@
 
 require_relative './models/chunk'
 require_relative './models/compression_setting'
+require_relative './models/continuous_aggregate'
 require_relative './models/dimension'
 require_relative './models/hypertable'
 require_relative './models/job'

data/lib/timescaledb/rails/version.rb

@@ -3,6 +3,6 @@
 module Timescaledb
   # :nodoc:
   module Rails
-    VERSION = '0.1.4'
+    VERSION = '0.1.5'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timescaledb-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Iván Etchart
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-30 00:00:00.000000000 Z
+date: 2023-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -139,10 +139,15 @@ files:
 - lib/timescaledb/rails/extensions/active_record/schema_dumper.rb
 - lib/timescaledb/rails/extensions/active_record/schema_statements.rb
 - lib/timescaledb/rails/model.rb
+- lib/timescaledb/rails/model/aggregate_functions.rb
+- lib/timescaledb/rails/model/finder_methods.rb
+- lib/timescaledb/rails/model/hyperfunctions.rb
 - lib/timescaledb/rails/model/scopes.rb
 - lib/timescaledb/rails/models.rb
 - lib/timescaledb/rails/models/chunk.rb
 - lib/timescaledb/rails/models/compression_setting.rb
+- lib/timescaledb/rails/models/concerns/durationable.rb
+- lib/timescaledb/rails/models/continuous_aggregate.rb
 - lib/timescaledb/rails/models/dimension.rb
 - lib/timescaledb/rails/models/hypertable.rb
 - lib/timescaledb/rails/models/job.rb
@@ -169,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.0.3.1
 signing_key: 
 specification_version: 4
 summary: TimescaleDB Rails integration