timescaledb-rails 0.1.3 → 0.1.5

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

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
-require 'active_record/connection_adapters/postgresql_adapter'
-
 module Timescaledb
   module Rails
     module ActiveRecord
       # :nodoc:
       module SchemaStatements
+        # Returns an array of hypertable names defined in the database.
+        def hypertables
+          query_values('SELECT hypertable_name FROM timescaledb_information.hypertables')
+        end
+
+        # Checks to see if the hypertable exists on the database.
+        #
+        #   hypertable_exists?(:developers)
+        #
+        def hypertable_exists?(hypertable)
+          query_value(
+            <<-SQL.squish
+              SELECT COUNT(*) FROM timescaledb_information.hypertables WHERE hypertable_name = #{quote(hypertable)}
+            SQL
+          ).to_i.positive?
+        end
+
         # Converts given standard PG table into a hypertable.
         #
         #   create_hypertable('readings', 'created_at', chunk_time_interval: '7 days')
@@ -22,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.
@@ -36,24 +51,103 @@ 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}')"
+          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}');"
+          execute "ALTER TABLE #{table_name.inspect} SET (timescaledb.compress = false);"
+        end
+
+        # Add a data retention policy to given hypertable.
+        #
+        #   add_hypertable_retention_policy('events', 7.days)
+        #
+        def add_hypertable_retention_policy(table_name, drop_after)
+          execute "SELECT add_retention_policy('#{table_name}', INTERVAL '#{stringify_interval(drop_after)}');"
+        end
+
+        # Removes data retention policy from given hypertable.
+        #
+        #   remove_hypertable_retention_policy('events')
+        #
+        def remove_hypertable_retention_policy(table_name, _drop_after = nil)
+          execute "SELECT remove_retention_policy('#{table_name}');"
+        end
+
+        # Adds a policy to reorder chunks on a given hypertable index in the background.
+        #
+        #   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}');"
+        end
+
+        # Removes a policy to reorder a particular hypertable.
+        #
+        #   remove_hypertable_reorder_policy('events')
+        #
+        def remove_hypertable_reorder_policy(table_name, _index_name = nil)
+          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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    module Model
+      # :nodoc:
+      module Scopes
+        extend ActiveSupport::Concern
+
+        # rubocop:disable Metrics/BlockLength
+        included do
+          scope :last_year, lambda {
+            date = Date.current - 1.year
+
+            between(date.beginning_of_year, date.end_of_year)
+          }
+
+          scope :last_month, lambda {
+            date = Date.current - 1.month
+
+            between(date.beginning_of_month, date.end_of_month)
+          }
+
+          scope :last_week, lambda {
+            date = Date.current - 1.week
+
+            between(date.beginning_of_week, date.end_of_week)
+          }
+
+          scope :yesterday, lambda {
+            where("DATE(#{hypertable_time_column_name}) = ?", Date.current - 1.day)
+          }
+
+          scope :this_year, lambda {
+            between(Date.current.beginning_of_year, Date.current.end_of_year)
+          }
+
+          scope :this_month, lambda {
+            between(Date.current.beginning_of_month, Date.current.end_of_month)
+          }
+
+          scope :this_week, lambda {
+            between(Date.current.beginning_of_week, Date.current.end_of_week)
+          }
+
+          scope :today, lambda {
+            where("DATE(#{hypertable_time_column_name}) = ?", Date.current)
+          }
+
+          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
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/model.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'timescaledb/rails/model/finder_methods'
+require 'timescaledb/rails/model/hyperfunctions'
+require 'timescaledb/rails/model/scopes'
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    module Model
+      PUBLIC_SCHEMA_NAME = 'public'
+
+      extend ActiveSupport::Concern
+
+      include Scopes
+
+      # :nodoc:
+      module ClassMethods
+        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
+          @hypertable_name ||= table_name.split('.').last
+        end
+
+        # Returns the schema where hypertable is stored.
+        #
+        # @return [String]
+        def hypertable_schema
+          @hypertable_schema ||=
+            if table_name.split('.').size > 1
+              table_name.split('.')[0..-2].join('.')
+            else
+              PUBLIC_SCHEMA_NAME
+            end
+        end
+
+        # @return [Timescaledb::Rails::Hypertable]
+        def hypertable
+          Timescaledb::Rails::Hypertable.find_by(hypertable_where_options)
+        end
+
+        # @return [ActiveRecord::Relation<Timescaledb::Rails::Chunk>]
+        def hypertable_chunks
+          Timescaledb::Rails::Chunk.where(hypertable_where_options)
+        end
+
+        # @return [ActiveRecord::Relation<Timescaledb::Rails::Job>]
+        def hypertable_jobs
+          Timescaledb::Rails::Job.where(hypertable_where_options)
+        end
+
+        # @return [ActiveRecord::Relation<Timescaledb::Rails::Dimension>]
+        def hypertable_dimensions
+          Timescaledb::Rails::Dimension.where(hypertable_where_options)
+        end
+
+        # @return [ActiveRecord::Relation<Timescaledb::Rails::CompressionSetting>]
+        def hypertable_compression_settings
+          Timescaledb::Rails::CompressionSetting.where(hypertable_where_options)
+        end
+
+        private
+
+        # Returns hypertable name and schema.
+        #
+        # @return [Hash]
+        def hypertable_where_options
+          { hypertable_name: hypertable_name, hypertable_schema: hypertable_schema }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class Chunk < ::ActiveRecord::Base
+      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) }
+
+      def chunk_full_name
+        "#{chunk_schema}.#{chunk_name}"
+      end
+
+      def compress!
+        ::ActiveRecord::Base.connection.execute(
+          "SELECT compress_chunk('#{chunk_full_name}')"
+        )
+      end
+
+      def decompress!
+        ::ActiveRecord::Base.connection.execute(
+          "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,16 +1,23 @@
 # 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'
       has_many :jobs, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Job'
+      has_many :chunks, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Chunk'
 
       # @return [String]
       def time_column_name
@@ -24,11 +31,29 @@ module Timescaledb
         interval.is_a?(String) ? interval : interval.inspect
       end
 
+      # @return [ActiveRecord::Relation<CompressionSetting>]
+      def compression_segment_settings
+        compression_settings.segmentby_setting
+      end
+
+      # @return [ActiveRecord::Relation<CompressionSetting>]
+      def compression_order_settings
+        compression_settings.orderby_setting.where.not(attname: time_column_name)
+      end
+
       # @return [String]
       def compression_policy_interval
-        ActiveSupport::Duration.parse(compression_job.config['compress_after']).inspect
-      rescue ActiveSupport::Duration::ISO8601Parser::ParsingError
-        compression_job.config['compress_after']
+        parse_duration(compression_job.config['compress_after'])
+      end
+
+      # @return [String]
+      def reorder_policy_index_name
+        reorder_job.config['index_name']
+      end
+
+      # @return [String]
+      def retention_policy_interval
+        parse_duration(retention_job.config['drop_after'])
       end
 
       # @return [Boolean]
@@ -36,8 +61,28 @@ module Timescaledb
         compression_job.present?
       end
 
+      # @return [Boolean]
+      def reorder?
+        reorder_job.present?
+      end
+
+      # @return [Boolean]
+      def retention?
+        retention_job.present?
+      end
+
       private
 
+      # @return [Job]
+      def reorder_job
+        @reorder_job ||= jobs.policy_reorder.first
+      end
+
+      # @return [Job]
+      def retention_job
+        @retention_job ||= jobs.policy_retention.first
+      end
+
       # @return [Job]
       def compression_job
         @compression_job ||= jobs.policy_compression.first

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

@@ -8,8 +8,14 @@ module Timescaledb
       self.primary_key = 'hypertable_name'
 
       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