cql-model 0.3.0

data/lib/cql/model/instance_methods.rb

@@ -0,0 +1,50 @@
+module Cql::Model::InstanceMethods
+  # Instantiate a new instance of this model. Do not validate the contents of
+  # cql_properties; it may contain properties that aren't declared by this model, that have
+  # a missing CQL column, or an improper name/value for their column type.
+  #
+  # @param [Hash] cql_properties typed hash of all properties associated with this model
+  def initialize(cql_properties=nil)
+    @cql_properties = cql_properties || {}
+  end
+
+  # Read a property. Property names are column names, and can therefore take any data type
+  # that a column name can take (integer, UUID, etc).
+  #
+  # @param [Object] name
+  # @return [Object] the value of the specified column, or nil
+  def [](name)
+    @cql_properties[name]
+  end
+
+  # Start an INSERT CQL statement to update model
+  # @see Cql::Model::Query::InsertStatement
+  #
+  # @param [Hash] values Hash of column values indexed by column name, optional
+  # @return [Cql::Model::Query::InsertStatement] a query object to customize (ttl, timestamp etc) or execute
+  #
+  # @example
+  #   joe.update(:age => 35).execute
+  #   joe.update.ttl(3600).execute
+  #   joe.update(:age => 36).ttl(7200).consistency('ONE').execute
+  def update(values={})
+    key_vals = self.class.primary_key.inject({}) { |h, k| h[k] = @cql_properties[k]; h }
+    Cql::Model::Query::UpdateStatement.new(self.class).update(values.merge(key_vals))
+  end
+
+  # Start an UPDATE CQL statement to update all models with given key
+  # This can update multiple models if the key is part of a composite key
+  # Updating all models with given (different) key values can be done using the '.update' class method
+  # @see Cql::Model::Query::UpdateStatement
+  #
+  # @param [Symbol|String] key Name of key used to select models to be updated
+  # @param [Hash] values Hash of column values indexed by column names, optional
+  # @return [Cql::Model::Query::UpdateStatement] a query object to customize (ttl, timestamp etc) or execute
+  #
+  # @example
+  #   joe.update_all_by(:name, :age => 25).execute # Set all joe's age to 25
+  #   joe.update_all_by(:name).ttl(3600).execute # Set all joe's TTL to one hour
+  def update_all_by(key, values={})
+    Cql::Model::Query::UpdateStatement.new(self.class).update(values.merge({ key => @cql_properties[key.to_s] }))
+  end
+end

data/lib/cql/model/query.rb

@@ -0,0 +1,107 @@
+module Cql::Model::Query
+  # CQL single quote character.
+  SQ         = "'"
+
+  # CQL single-quote escape sequence.
+  SQSQ       = "''"
+
+  # CQL double-quote character.
+  DQ         = '"'
+
+  # CQL double-quote escape.
+  DQDQ       = '""'
+
+  # Valid CQL identifier (can be used as a column name without double-quoting)
+  IDENTIFIER = /[a-z][a-z0-9_]*/i
+
+  module_function
+
+  # Transform a list of symbols or strings into CQL column names. Performs no safety checks!!
+  def cql_column_names(list)
+    if list.empty?
+      '*'
+    else
+      list.join(', ')
+    end
+  end
+
+  # Transform a Ruby object into its CQL identifier representation.
+  #
+  # @TODO more docs
+  #
+  def cql_identifier(value)
+    # TODO UUID, Time, ...
+    case value
+    when Symbol, String
+      if value =~ IDENTIFIER
+        value.to_s
+      else
+        "#{DQ}#{value.gsub(DQ, DQDQ)}#{DQ}"
+      end
+    when Numeric, TrueClass, FalseClass
+      "#{DQ}#{cql_value(value)}#{DQ}"
+    else
+      raise Cql::Model::SyntaxError, "Cannot convert #{value.class} to a CQL identifier"
+    end
+  end
+
+  # Transform a Ruby object into its CQL literal value representation. A literal value is anything
+  # that can appear in a CQL statement as a key or column value (but not column NAME; see
+  # #cql_identifier to convert values to column names).
+  #
+  # @param value [String,Numeric,Boolean,Array,Set,Array,#map]
+  # @return [String] the CQL equivalent of value
+  #
+  # When used as a key or column value, CQL supports the following kinds of literal value:
+  #  * unquoted identifier (treated as a string value)
+  #  * string literal
+  #  * integer number
+  #  * UUID
+  #  * floating-point number
+  #  * boolean true/false
+  #
+  # When used as a column name, any value that is not a valid identifier MUST BE ENCLOSED IN
+  # DOUBLE QUOTES. This method does not handle the double-quote escaping; see #cql_identifier
+  # for that.
+  #
+  # @see #cql_identifier
+  # @see http://www.datastax.com/docs/1.1/references/cql/cql_lexicon#keywords-and-identifiers
+  def cql_value(value, context=nil)
+    # TODO UUID, Time, ...
+    case value
+    when String
+      "#{SQ}#{value.gsub(SQ, SQSQ)}#{SQ}"
+    when Numeric, TrueClass, FalseClass
+      value.to_s
+    when Set
+      raise SyntaxError, "Set notation is not allowed outside UPDATE statements" unless (context == :update)
+      '{' + value.map { |v| cql_value(v) }.join(', ') + '}'
+    else
+      if value.respond_to?(:map)
+        if value.respond_to?(:each_pair)
+          # Pairwise map -- CQL map literal
+          '{' + value.map { |k, v| "#{cql_value(k)}: #{cql_value(v)}" }.join(', ') + '}'
+        else
+          # Single map -- CQL list (for UPDATE) or set (for WHERE...IN) literal
+          case context
+          when :update
+            '[' + value.map { |v| cql_value(v) }.join(', ') + ']'
+          else
+            '(' + value.map { |v| cql_value(v) }.join(', ') + ')'
+          end
+        end
+      else
+        raise Cql::Model::SyntaxError, "Cannot convert #{value.class} to a CQL value"
+      end
+    end
+  end
+end
+
+require 'cql/model/query/expression'
+require 'cql/model/query/comparison_expression'
+require 'cql/model/query/update_expression'
+require 'cql/model/query/statement'
+require 'cql/model/query/mutation_statement'
+require 'cql/model/query/select_statement'
+require 'cql/model/query/insert_statement'
+require 'cql/model/query/update_statement'

data/lib/cql/model/query/comparison_expression.rb

@@ -0,0 +1,126 @@
+require 'set'
+
+module Cql::Model::Query
+  # @TODO docs
+  class ComparisonExpression < Expression
+    # Operators allowed in a where-clause lambda
+    OPERATORS = {
+      :==   => '=',
+      :'!=' => '!=',
+      :'>'  => '>',
+      :'<'  => '<',
+      :'>=' => '>=',
+      :'<=' => '<=',
+      :'in' => 'IN',
+    }.freeze
+
+    # Methods used to escape CQL column names that aren't valid CQL identifiers
+    TYPECASTS = [
+      :ascii,
+      :bigint,
+      :blob,
+      :boolean,
+      :counter,
+      :decimal,
+      :double,
+      :float,
+      :int,
+      :text,
+      :timestamp,
+      :uuid,
+      :timeuuid,
+      :varchar,
+      :varint
+    ].freeze
+
+    # @TODO docs
+    def initialize(*params, &block)
+      @left     = nil
+      @operator = nil
+      @right    = nil
+
+      instance_exec(*params, &block) if block
+    end
+
+    # @TODO docs
+    def to_s
+      __build__
+    end
+
+    # @TODO docs
+    def inspect
+      __build__
+    end
+
+    # This is where the magic happens. Ensure all of our operators are overloaded so they call
+    # #apply and contribute to the CQL expression that will be built.
+    OPERATORS.keys.each do |op|
+      define_method(op) do |*args|
+        __apply__(op, args)
+      end
+    end
+
+    TYPECASTS.each do |func|
+      define_method(func) do |*args|
+        __apply__(func, args)
+      end
+    end
+
+    # @TODO docs
+    def method_missing(token, *args)
+      __apply__(token, args)
+    end
+
+    private
+
+    # @TODO docs
+    def __apply__(token, args)
+      if @left.nil?
+        if args.empty?
+          # A well-behaved CQL identifier (column name that is a valid Ruby method name)
+          @left = token
+        elsif args.length == 1
+          # A CQL typecast (column name that is an integer, float, etc and must be wrapped in a decorator)
+          @left = args.first
+        else
+          ::Kernel.raise ::Cql::Model::SyntaxError.new(
+                           "Unacceptable token '#{token}'; expected a CQL identifier or typecast")
+        end
+      elsif @operator.nil?
+        # Looking for an operator + right operand
+        if OPERATORS.keys.include?(token)
+          @operator = token
+
+          if (args.size > 1) || (token == :in)
+            @right = args
+          else
+            @right = args.first
+          end
+        else
+          ::Kernel.raise ::Cql::Model::SyntaxError.new(
+                           "Unacceptable token '#{token}'; expected a CQL-compatible operator")
+        end
+      else
+        ::Kernel.raise ::Cql::Model::SyntaxError.new(
+                         "Unacceptable token '#{token}'; the expression is " +
+                           "already complete")
+      end
+
+      self
+    end
+
+    # @TODO docs
+    def __build__
+      if @left.nil? || @operator.nil? || @right.nil?
+        ::Kernel.raise ::Cql::Model::SyntaxError.new(
+                         "Cannot build a CQL expression; the Ruby expression is incomplete " +
+                           "(#{@left.inspect}, #{@operator.inspect}, #{@right.inspect})")
+      else
+        left  = ::Cql::Model::Query.cql_identifier(@left)
+        op    = OPERATORS[@operator]
+        right = ::Cql::Model::Query.cql_value(@right)
+        "#{left} #{op} #{right}"
+      end
+    end
+  end
+end

data/lib/cql/model/query/expression.rb

@@ -0,0 +1,5 @@
+module Cql::Model::Query
+  class Expression < BasicObject
+
+  end
+end

data/lib/cql/model/query/insert_statement.rb

@@ -0,0 +1,51 @@
+module Cql::Model::Query
+
+  # INSERT statement DSL
+  # << An INSERT writes one or more columns to a record in a Cassandra column family. No results are returned.
+  #    The first column name in the INSERT list must be the name of the column family key >>
+  # (from: http://www.datastax.com/docs/1.1/references/cql/INSERT)
+  #
+  # Ex:
+  # Model.create(:key => 'val', :col1 => 'value', :col2 => 42)                                         # Simple insert
+  # Model.create(:key => 'val', :key2 => 64, :col1 => 'value', :col2 => 42)                            # Composite keys
+  # Model.create(:key => 'val', :col => 'value').ttl(3600)                                             # TTL in seconds
+  # Model.create(:key => 'val', :col => 'value').timestamp(1366057256324)                              # Milliseconds since epoch timestamp
+  # Model.create(:key => 'val', :col => 'value').timestamp('2013-04-15 13:21:48')                      # ISO 8601 timestamp
+  # Model.create(:key => 'val', :col => 'value').consistency('ONE')                                    # Custom consistency (default is 'LOCAL_QUORUM')
+  # Model.create(:key => 'val', :col => 'value').ttl(3600).timestamp(1366057256324).consistency('ONE') # Multiple options
+  class InsertStatement < MutationStatement
+
+    # Specify names and values to insert.
+    #
+    # @param [Hash] values Hash of column values indexed by column name
+    def insert(values)
+      raise ArgumentError, "Cannot specify INSERT values twice" unless @values.nil?
+      @values = values
+      self
+    end
+
+    alias create insert
+
+    # Build a string representation of this CQL statement, suitable for execution by a CQL client.
+    # Do not validate the statement for completeness; Cassnadra will raise an error if a key
+    # component is missing.
+    #
+    # @return [String] a CQL INSERT statement with suitable constraints and options
+    def to_s
+      keys = @klass.primary_key.inject([]) { |h, k| h << [k, @values.delete(k)]; h }
+      if keys.any? { |k| k[1].nil? }
+        raise Cql::Model::MissingKey.new("Missing primary key(s) in INSERT statement: #{keys.select { |k| k[1].nil? }.map(&:first).map(&:inspect).join(', ')}")
+      end
+      s = "INSERT INTO #{@klass.table_name} (#{keys.map { |k| k[0] }.join(', ')}, #{@values.keys.join(', ')})"
+      s << " VALUES (#{keys.map { |k| ::Cql::Model::Query.cql_value(k[1]) }.join(', ')}, #{@values.values.map { |v| ::Cql::Model::Query.cql_value(v) }.join(', ')})"
+      options = []
+      options << "CONSISTENCY #{@consistency || @klass.write_consistency}"
+      options << "TIMESTAMP #{@timestamp}" unless @timestamp.nil?
+      options << "TTL #{@ttl}" unless @ttl.nil?
+      s << " USING #{options.join(' AND ')}"
+      s << ';'
+
+      s
+    end
+  end
+end

data/lib/cql/model/query/mutation_statement.rb

@@ -0,0 +1,48 @@
+module Cql::Model::Query
+
+  # Common parent to InsertStatement and UpdateStatment
+  # provide helpers for managing common DSL settings
+  class MutationStatement < Statement
+
+    # Instantiate statement
+    #
+    # @param [Class] klass
+    # @param [Cql::Client] CQL client used to execute statement
+    def initialize(klass, client=nil)
+      super(klass, client)
+      @values    = nil
+      @ttl       = nil
+      @timestamp = nil
+    end
+
+    # DSL for setting TTL value
+    #
+    # @param [Fixnum] ttl_value TTL value in seconds
+    def ttl(ttl_value)
+      raise ArgumentError, "Cannot specify TTL twice" unless @ttl.nil?
+      @ttl = ttl_value
+      self
+    end
+
+    # DSL for setting timestamp value
+    #
+    # @param [Fixnum|String] timestamp_value (number of milliseconds since epoch or ISO 8601 date time value)
+    def timestamp(timestamp_value)
+      raise ArgumentError, "Cannot specify timestamp twice" unless @timestamp.nil?
+      @timestamp = timestamp_value
+      self
+    end
+
+    # Execute this statement on the CQL client connection
+    # INSERT statements do not return a result
+    #
+    # @return [true] always returns true
+    def execute
+      @client.execute(to_s)
+      true
+    end
+
+  end
+
+end
+

data/lib/cql/model/query/select_statement.rb

@@ -0,0 +1,143 @@
+module Cql::Model::Query
+
+  # SELECT statement DSL
+  # << A SELECT expression reads one or more records from a Cassandra column family and returns a result-set of rows.
+  #    Each row consists of a row key and a collection of columns corresponding to the query. >>
+  # (from: http://www.datastax.com/docs/1.1/references/cql/SELECT)
+  #
+  # Ex:
+  # Model.select(:col1, :col2)
+  # Model.select(:col1, :col2).where { name == 'Joe' }
+  # Model.select(:col1, :col2).where { name == 'Joe' }.and { age.in(33,34,35) }
+  # Model.select(:col1, :col2).where { name == 'Joe' }.and { age.in(33,34,35) }.order_by(:age).desc
+  class SelectStatement < Statement
+
+    # Instantiate statement
+    #
+    # @param [Class] klass Model class
+    # @param [Cql::Client] CQL client used to execute statement
+    def initialize(klass, client=nil)
+      super(klass, client)
+      @columns = nil
+      @where   = []
+      @order   = ''
+      @limit   = nil
+    end
+
+    # Create or append to the WHERE clause for this statement. The block that you pass will define the constraint
+    # and any where() parameters will be forwarded to the block as yield parameters. This allows late binding of
+    # variables in the WHERE clause, e.g. for prepared statements.
+    #
+    # @param [Object] *params parameters to be forwarded to the block
+    # @yield the block will be evaluated in the context of a ComparisonExpression to capture a CQL expression that will be appended to the WHERE clause
+    #
+    # @return [SelectStatement] always returns self
+    #
+    # @example find people named Joe
+    #    where { name == "Joe" }
+    #
+    # @example find people older than 33 who are named Joe or Fred
+    #    where { age > 33 }.and { name.in("Joe", "Fred") }
+    #
+    # @example find people older than 33
+    #    where { age > 33 }
+    #
+    # @example find by a late-bound search term (e.g. for a named scope)
+    #    where(age_chosen_by_user) { |chosen| age > chosen }
+    #
+    # @example find by a column name that is not a valid Ruby identifier
+    #    where { timestamp(12345) == "logged in" }
+    #
+    # @see ComparisonExpression
+    # @see Cql::Model::ClassMethods#scope
+    def where(*params, &block)
+      @where << ComparisonExpression.new(*params, &block)
+      self
+    end
+
+    alias and where
+
+    # Specify the order in which result rows should be returned.
+    #
+    # @param [Array] *params glob of column names (symbols, strings, or Ruby values that correspond to valid column names)
+    # @return [SelectStatement] always returns self
+    def order(*columns)
+      raise ArgumentError, "Cannot specify ORDER BY twice" unless @order.empty?
+      @order = ::Cql::Model::Query.cql_column_names(columns)
+      self
+    end
+
+    alias order_by order
+
+    # @TODO docs
+    def asc
+      raise ArgumentError, "Cannot specify ASC / DESC twice" if @order =~ /ASC|DESC$/
+      raise ArgumentError, "Must specify ORDER BY before ASC" if @order.empty?
+      @order << " ASC"
+      self
+    end
+
+    # @TODO docs
+    def desc
+      raise ArgumentError, "Cannot specify ASC / DESC twice" if @order =~ /ASC|DESC$/
+      raise ArgumentError, "Must specify ORDER BY before DESC" if @order.empty?
+      @order << " DESC"
+      self
+    end
+
+    # @TODO docs
+    def limit(lim)
+      raise ArgumentError, "Cannot specify LIMIT twice" unless @limit.nil?
+      @limit = lim
+      self
+    end
+
+    # @TODO docs
+    def select(*columns)
+      raise ArgumentError, "Cannot specify SELECT column names twice" unless @columns.nil?
+      @columns = ::Cql::Model::Query.cql_column_names(columns)
+      self
+    end
+
+    # @return [String] a CQL SELECT statement with suitable constraints and options
+    def to_s
+      s = "SELECT #{@columns || '*'} FROM #{@klass.table_name}"
+
+      s << " USING CONSISTENCY " << (@consistency || @klass.write_consistency)
+
+      unless @where.empty?
+        s << " WHERE " << @where.map { |w| w.to_s }.join(' AND ')
+      end
+
+      s << " ORDER BY " << @order unless @order.empty?
+      s << " LIMIT #{@limit}" unless @limit.nil?
+      s << ';'
+    end
+
+    # Execute this SELECT statement on the CQL client connection and yield each row of the
+    # result set as a raw-data Hash.
+    #
+    # @yield each row of the result set
+    # @yieldparam [Hash] row a Ruby Hash representing the column names and values for a given row
+    # @return [true] always returns true
+    def execute(&block)
+      @client.execute(to_s).each_row(&block).size
+
+      true
+    end
+
+    alias each_row execute
+
+    # Execute this SELECT statement on the CQL client connection and yield each row of the
+    # as an instance of CQL::Model.
+    #
+    # @yield each row of the result set
+    # @yieldparam [Hash] row a Ruby Hash representing the column names and values for a given row
+    # @return [true] always returns true
+    def each(&block)
+      each_row do |row|
+        block.call(@klass.new(row))
+      end
+    end
+  end
+end