cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/record/properties.rb

@@ -1,13 +1,42 @@
 module Cequel
-
   module Record
-
+    #
+    # Properties on a Cequel record acts as attributes on record instances, and
+    # are persisted as column values to Cassandra. Properties are declared
+    # explicitly on a record instance in the body.
+    #
+    # Properties can be **key columns**, **data columns**, or **collection
+    # columns**. Key columns combine to form the primary key for the record;
+    # they cannot be changed once a record has been saved. Data columns contain
+    # scalar data values like strings, integers, and timestamps. Collection
+    # columns are lists, sets, or maps that can be atomically updated.
+    #
+    # All varieties of column have a type; see {Cequel::Type} for the full
+    # list of possibilities. A collection column's type is the type of its
+    # elements (in the case of a map collection, there is both a key type and a
+    # value type).
+    #
+    # @example
+    #   class Post
+    #     key :blog_subdomain, :text
+    #     key :id, :timeuuid, auto: true
+    #
+    #     column :title, :text
+    #     column :body, :text
+    #     column :updated_at, :timestamp
+    #
+    #     list :categories, :text
+    #     set :tags, :text
+    #     map :referers, :text, :integer
+    #   end
+    #
+    # @see ClassMethods Methods for defining properties
+    #
     module Properties
-
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :default_attributes, :instance_writer => false
+        class_attribute :default_attributes, instance_writer: false
         self.default_attributes = {}
 
         class <<self; alias_method :new_empty, :new; end
@@ -17,47 +46,124 @@ module Cequel
         private :collection_proxies
       end
 
+      # @private
       module ConstructorMethods
-
         def new(*args, &block)
           new_empty.tap do |record|
             record.__send__(:initialize_new_record, *args)
             yield record if block_given?
           end
         end
-
       end
 
+      #
+      # Methods for defining columns on a record
+      #
+      # @see Properties
+      #
       module ClassMethods
-
         protected
 
+        # @!visibility public
+
+        #
+        # Define a key column. By default, the first key column defined for a
+        # record will be a partition key, and the following keys will be
+        # clustering columns. This behavior can be changed using the
+        # `:partition` option
+        #
+        # @param name [Symbol] the name of the key column
+        # @param type [Symbol] the type of the key column
+        # @param options [Options] options for the key column
+        # @option options [Boolean] :partition (false) make this a partition
+        #   key even if it is not the first key column
+        # @option options [Boolean] :auto (false) automatically initialize this
+        #   key with a UUID value for new records. Only valid for `uuid` and
+        #   `timeuuid` columns.
+        # @return [void]
+        #
+        # @note {Associations::ClassMethods#belongs_to belongs_to} implicitly
+        #   defines key columns.
+        #
+        # @see
+        #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/ddl/ddl_anatomy_table_c.html#concept_ds_cz4_lmy_zj
+        #   CQL documentation on compound primary keys
+        #
         def key(name, type, options = {})
           def_accessors(name)
           if options.fetch(:auto, false)
             unless Type[type].is_a?(Cequel::Type::Uuid)
-              raise ArgumentError, ":auto option only valid for UUID columns"
+              fail ArgumentError, ":auto option only valid for UUID columns"
             end
-            default = -> { CassandraCQL::UUID.new } if options.fetch(:auto, false)
+            default = -> { CassandraCQL::UUID.new } if options[:auto]
           end
           set_attribute_default(name, default)
         end
 
+        #
+        # Define a data column
+        #
+        # @param name [Symbol] the name of the column
+        # @param type [Symbol] the type of the column
+        # @param options [Options] options for the column
+        # @option options [Object,Proc] :default a default value for the
+        #   column, or a proc that returns a default value for the column
+        # @return [void]
+        #
         def column(name, type, options = {})
           def_accessors(name)
           set_attribute_default(name, options[:default])
         end
 
+        #
+        # Define a list column
+        #
+        # @param name [Symbol] the name of the list
+        # @param type [Symbol] the type of the elements in the list
+        # @param options [Options] options for the list
+        # @option options [Object,Proc] :default ([]) a default value for the
+        #   column, or a proc that returns a default value for the column
+        # @return [void]
+        #
+        # @see Record::List
+        # @since 1.0.0
+        #
         def list(name, type, options = {})
           def_collection_accessors(name, List)
           set_attribute_default(name, options.fetch(:default, []))
         end
 
+        #
+        # Define a set column
+        #
+        # @param name [Symbol] the name of the set
+        # @param type [Symbol] the type of the elements in the set
+        # @param options [Options] options for the set
+        # @option options [Object,Proc] :default (Set[]) a default value for
+        #   the column, or a proc that returns a default value for the column
+        # @return [void]
+        #
+        # @see Record::Set
+        # @since 1.0.0
+        #
         def set(name, type, options = {})
           def_collection_accessors(name, Set)
           set_attribute_default(name, options.fetch(:default, ::Set[]))
         end
 
+        #
+        # Define a map column
+        #
+        # @param name [Symbol] the name of the map
+        # @param key_type [Symbol] the type of the keys in the set
+        # @param options [Options] options for the set
+        # @option options [Object,Proc] :default ({}) a default value for the
+        #   column, or a proc that returns a default value for the column
+        # @return [void]
+        #
+        # @see Record::Map
+        # @since 1.0.0
+        #
         def map(name, key_type, value_type, options = {})
           def_collection_accessors(name, Map)
           set_attribute_default(name, options.fetch(:default, {}))
@@ -108,31 +214,47 @@ module Cequel
         def set_attribute_default(name, default)
           default_attributes[name.to_sym] = default
         end
-
       end
 
-      # FIXME this isn't empty anymore! Rethink.
+      # @private
       def initialize(attributes = {}, record_collection = nil)
         @attributes, @record_collection = attributes, record_collection
         @collection_proxies = {}
       end
 
+      #
+      # @return [Array<Symbol>] list of names of attributes on this record
+      #
       def attribute_names
         @attributes.keys
       end
 
+      #
+      # @return [Hash<Symbol,Object>] map of column names to values currently
+      #   set on this record
+      #
       def attributes
         attribute_names.each_with_object({}) do |name, attributes|
           attributes[name] = read_attribute(name)
         end
       end
 
+      #
+      # Set attributes on the record. Each attribute is set via the setter
+      # method; virtual (non-column) attributes are allowed.
+      #
+      # @param attributes [Hash] map of attribute names to values
+      # @return [void]
+      #
       def attributes=(attributes)
         attributes.each_pair do |attribute, value|
           __send__(:"#{attribute}=", value)
         end
       end
 
+      #
+      # @return [Boolean] true if this record has the same type and key
+      #   attributes as the other record
       def ==(other)
         if key_values.any? { |value| value.nil? }
           super
@@ -141,6 +263,9 @@ module Cequel
         end
       end
 
+      #
+      # @return [String] string representation of the record
+      #
       def inspect
         inspected_attributes = attributes.each_pair.map do |attr, value|
           inspected_value = value.is_a?(CassandraCQL::UUID) ?
@@ -157,9 +282,9 @@ module Cequel
         @attributes.fetch(name)
       rescue KeyError
         if self.class.reflect_on_column(name)
-          raise MissingAttributeError, "missing attribute: #{name}"
+          fail MissingAttributeError, "missing attribute: #{name}"
         else
-          raise UnknownAttributeError, "unknown attribute: #{name}"
+          fail UnknownAttributeError, "unknown attribute: #{name}"
         end
       end
 
@@ -179,20 +304,18 @@ module Cequel
       end
 
       def initialize_new_record(attributes = {})
-        dynamic_defaults = default_attributes.
-          select { |name, value| value.is_a?(Proc) }
+        dynamic_defaults = default_attributes
+          .select { |name, value| value.is_a?(Proc) }
         @attributes = Marshal.load(Marshal.dump(
           default_attributes.except(*dynamic_defaults.keys)))
-          dynamic_defaults.each { |name, p| @attributes[name] = p.() }
-          @new_record = true
-          yield self if block_given?
-          self.attributes = attributes
-          loaded!
-          self
-      end
+        dynamic_defaults.each { |name, p| @attributes[name] = p.call() }
 
+        @new_record = true
+        yield self if block_given?
+        self.attributes = attributes
+        loaded!
+        self
+      end
     end
-
   end
-
 end

data/lib/cequel/record/railtie.rb

@@ -1,5 +1,7 @@
 module Cequel
   module Record
+    # @private
+    # @since 0.1.0
     class Railtie < Rails::Railtie
       config.cequel = Record
 
@@ -11,8 +13,8 @@ module Cequel
         config_path = Rails.root.join('config/cequel.yml').to_s
 
         if File.exist?(config_path)
-          config = YAML::load(ERB.new(IO.read(config_path)).result)[Rails.env].
-            deep_symbolize_keys
+          config = YAML.load(ERB.new(IO.read(config_path)).result)[Rails.env]
+            .deep_symbolize_keys
         else
           config = {host: '127.0.0.1:9160'}
         end
@@ -23,6 +25,17 @@ module Cequel
         Record.connection = connection
       end
 
+      initializer "cequel.add_new_relic" do
+        begin
+          require 'new_relic/agent/method_tracer'
+        rescue LoadError => e
+          Rails.logger.debug(
+            "New Relic not installed; skipping New Relic integration")
+        else
+          require 'cequel/metal/new_relic_instrumentation'
+        end
+      end
+
       rake_tasks do
         require "cequel/record/tasks"
       end

data/lib/cequel/record/record_set.rb

@@ -1,86 +1,379 @@
 module Cequel
-
   module Record
-
+    #
+    # This class represents a subset of records from a particular table. Record
+    # sets encapsulate a CQL query, and are constructed using a chained builder
+    # interface.
+    #
+    # The primary mechanism for specifying which rows should be returned by a
+    # CQL query is by specifying values for one or more primary key columns. A
+    # record set acts like a deeply-nested hash, where each primary key column
+    # is a level of nesting. The {#[]} method is used to narrow the result set
+    # by successive primary key values.
+    #
+    # If {#[]} is used successively to specify all of the columns of a primary
+    # key, the result will be a single {Record} or a {LazyRecordCollection},
+    # depending on whether multiple values were specified for one of the key
+    # columns. In either case, the record instances will be unloaded.
+    #
+    # Certain methods have behavior that is dependent on which primary keys
+    # have been specified using {#[]}. In many methods, such as {#[]},
+    # {#values_at}, {#before}, {#after}, {#from}, {#upto}, and {#in}, the
+    # *first unscoped primary key column* serves as implicit context for the
+    # method: the value passed to those methods is an exact or bounding value
+    # for that column.
+    #
+    # CQL does not allow ordering by arbitrary columns; the ordering of a table
+    # is determined by its clustering column(s). You read records in reverse
+    # clustering order using {#reverse}.
+    #
+    # Record sets are enumerable collections; under the hood, results are
+    # paginated. This pagination can be made explicit using {#find_in_batches}.
+    # RecordSets do not store their records in memory; each time {#each} or an
+    # `Enumerable` method is called, the database is queried.
+    #
+    # All `RecordSet` methods are also exposed directly on {Record}
+    # classes. So, for instance, `Post.limit(10)` or `Post.select(:id, :title)`
+    # work as expected.
+    #
+    # Conversely, you may call any class method of a record class on a record
+    # set that targets that class. The class method will be executed in the
+    # context of the record set that the method is called on. See below for
+    # examples.
+    #
+    # @example Model class used for further examples
+    #   class Post
+    #     include Cequel::Record
+    #
+    #     belongs_to :blog # defines key :blog_subdomain
+    #     key :id, :timeuuid, auto: true
+    #
+    #     column :title, :text
+    #     column :author_id, :integer, index: true
+    #
+    #     def self.for_author(author)
+    #       where(:author_id, author.id)
+    #     end
+    #   end
+    #
+    # @example A record set scoped to all posts
+    #   Post.all # returns a record set with no scope restrictions
+    #
+    # @example The first ten posts
+    #   # returns a ten-element array of loaded posts
+    #   Post.first(10)
+    #
+    #   # returns a record set scoped to yield the first 10 posts
+    #   Post.limit(10)
+    #
+    # @example The posts in the "cassandra" blog
+    #   # returns a record set where blog_subdomain = "cassandra"
+    #   Post['cassandra']
+    #
+    # @example The post in the "cassandra" blog with id `params[:id]`
+    #   # returns an unloaded Post instance
+    #   Post['cassandra'][params[:id]]
+    #
+    # @example The posts in the "cassandra" blog with ids `id1, id2`
+    #   # returns a LazyRecordCollection containing two unloaded Post instances
+    #   Post['cassandra'].values_at('id1', 'id2')
+    #
+    # @example The posts in the "cassandra" blog in descending order of id
+    #   # returns a LazyRecordCollection where blog_subdomain="cassandra" in
+    #   # descending order of creation
+    #   Post['cassandra'].reverse
+    #
+    # @example The posts in the "cassandra" blog created in the last week
+    #   # returns a LazyRecordCollection where blog_subdomain="cassandra" and
+    #   the timestamp encoded in the uuid is in the last week. This only works
+    #   for timeuuid clustering columns
+    #   Post['cassandra'].reverse.after(1.week.ago)
+    #
+    # @example 10 posts by a given author
+    #   # Scoped to 10 posts where author_id=author.id. Results will not be in
+    #   # a defined order because the partition key is not specified
+    #   Post.for_author(author).limit(10)
+    #
+    # @see Scoped
+    # @see LazyRecordCollection
+    # @since 1.0.0
+    #
     class RecordSet < SimpleDelegator
-
       extend Forwardable
       extend Cequel::Util::HashAccessors
       include Enumerable
       include BulkWrites
 
+      # @private
       def self.default_attributes
-        {:scoped_key_values => [], :select_columns => []}
+        {scoped_key_values: [], select_columns: []}
       end
 
+      # @return [Class] the Record class that this collection yields instances
+      #   of
       attr_reader :target_class
-      attr_writer :unloaded_records
 
+      #
+      # @param target_class [Class] the Record class that this collection
+      #   yields instances of
+      # @param attributes [Hash] initial scoping attributes
+      #
+      # @api private
+      #
       def initialize(target_class, attributes = {})
         attributes = self.class.default_attributes.merge!(attributes)
         @target_class, @attributes = target_class, attributes
         super(target_class)
       end
 
+      #
+      # @return [RecordSet] self
+      #
       def all
         self
       end
 
+      #
+      # @overload select
+      #
+      #   @yieldparam record [Record] each record in the record set
+      #   @return [Array] records that pass the test given by the block
+      #
+      #   @see
+      #     http://ruby-doc.org/core-2.0.0/Enumerable.html#method-i-select
+      #     Enumerable#select
+      #
+      # @overload select(*columns)
+      #   Restrict which columns are selected when records are retrieved from
+      #   the database
+      #
+      #   @param columns [Symbol] column names
+      #   @return [RecordSet] record set with the given column selections
+      #     applied
+      #
+      #   @see
+      #     http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/select_r.html
+      #     CQL SELECT documentation
+      #
+      # @return [Array,RecordSet]
+      #
       def select(*columns)
         return super if block_given?
         scoped { |attributes| attributes[:select_columns].concat(columns) }
       end
 
+      #
+      # Restrict the number of records that the RecordSet can contain.
+      #
+      # @param count [Integer] the maximum number of records to return
+      # @return [RecordSet] record set with limit applied
+      #
+      # @see
+      #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/select_r.html
+      #   CQL SELECT documentation
+      #
       def limit(count)
-        scoped(:row_limit => count)
-      end
-
+        scoped(row_limit: count)
+      end
+
+      #
+      # Filter the record set to records containing a given value in an indexed
+      # column
+      #
+      # @param column_name [Symbol] column for filter
+      # @param value value to match in given column
+      # @return [RecordSet] record set with filter applied
+      # @raise [IllegalQuery] if this record set is already filtered by an
+      #   indexed column
+      # @raise [ArgumentError] if the specified column is not an data column
+      #   with a secondary index
+      #
+      # @note This should only be used with data columns that have secondary
+      #   indexes. To filter a record set using a primary key, use {#[]}
+      # @note Only one secondary index filter can be used in a given query
+      # @note Secondary index filters cannot be mixed with primary key filters
+      #
       def where(column_name, value)
         column = target_class.reflect_on_column(column_name)
-        raise IllegalQuery,
-          "Can't scope by more than one indexed column in the same query" if scoped_indexed_column
-        raise ArgumentError,
-          "No column #{column_name} configured for #{target_class.name}" unless column
-        raise ArgumentError,
-          "Use the `at` method to restrict scope by primary key" unless column.data_column?
-        raise ArgumentError,
-          "Can't scope by non-indexed column #{column_name}" unless column.indexed?
+        if scoped_indexed_column
+          fail IllegalQuery,
+               "Can't scope by more than one indexed column in the same query"
+        end
+        unless column
+          fail ArgumentError,
+               "No column #{column_name} configured for #{target_class.name}"
+        end
+        unless column.data_column?
+          fail ArgumentError,
+               "Use the `at` method to restrict scope by primary key"
+        end
+        unless column.indexed?
+          fail ArgumentError,
+               "Can't scope by non-indexed column #{column_name}"
+        end
         scoped(scoped_indexed_column: {column_name => column.cast(value)})
       end
 
+      #
+      # @deprecated Use {#[]} instead
+      #
+      # Scope to values for one or more primary key columns
+      #
+      # @param scoped_key_values values for primary key columns
+      # @return (see #[])
+      #
       def at(*scoped_key_values)
         warn "`at` is deprecated. Use `[]` instead"
-        scoped_key_values.
-          inject(self) { |record_set, key_value| record_set[key_value] }
-      end
-
-      def [](*new_scoped_key_values)
-        new_scoped_key_values =
-          new_scoped_key_values.map(&method(:cast_range_key))
+        scoped_key_values
+          .reduce(self) { |record_set, key_value| record_set[key_value] }
+      end
+
+      #
+      # Restrict this record set to a given value for the next unscoped
+      # primary key column
+      #
+      # Record sets can be thought of like deeply-nested hashes, where each
+      # primary key column is a level of nesting. For instance, if a table
+      # consists of a single record with primary key `(blog_subdomain,
+      # permalink) = ("cassandra", "cequel")`, the record set can be thought of
+      # like so:
+      #
+      # ```ruby
+      # {
+      #   "cassandra" => {
+      #     "cequel" => #<Post blog_subdomain: "cassandra",
+      #                        permalink: "cequel", title: "Cequel">
+      #   }
+      # }
+      # ```
+      #
+      # If `[]` is invoked enough times to specify all primary keys, then an
+      # unloaded `Record` instance is returned; this is the same behavior you
+      # would expect from a `Hash`. If only some subset of the primary keys
+      # have been specified, the result is still a `RecordSet`.
+      #
+      # @param primary_key_value value for the first unscoped primary key
+      # @return [RecordSet] record set with primary key filter applied, if not
+      #   all primary keys are specified
+      # @return [Record] unloaded record, if all primary keys are specified
+      #
+      # @example Partially specified primary key
+      #   Post['cequel'] # returns a RecordSet
+      #
+      # @example Fully specified primary key
+      #   Post['cequel']['cassandra'] # returns an unloaded Record
+      #
+      # @note Accepting multiple arguments is deprecated behavior. Use
+      #   {#values_at} instead.
+      #
+      def [](*primary_key_value)
+        if primary_key_value.many?
+          warn "Calling #[] with multiple arguments is deprecated. Use " \
+               "#values_at"
+          return values_at(*primary_key_value)
+        end
 
-        new_scoped_key_values =
-          new_scoped_key_values.first if new_scoped_key_values.one?
+        primary_key_value = cast_range_key(primary_key_value.first)
 
-        scoped { |attributes| attributes[:scoped_key_values] <<
-          new_scoped_key_values }.resolve_if_fully_specified
+        scope_and_resolve do |attributes|
+          attributes[:scoped_key_values] << primary_key_value
+        end
       end
+      alias_method :/, :[]
+
+      #
+      # Restrict the records in this record set to those containing any of a
+      # set of values
+      #
+      # @param primary_key_values values to match in the next unscoped primary
+      #   key
+      # @return [RecordSet] record set with primary key scope applied if not
+      #   all primary key columns are specified
+      # @return [LazyRecordCollection] collection of unloaded records if all
+      #   primary key columns are specified
+      # @raise IllegalQuery if the scoped key column is neither the last
+      #   partition key column nor the last clustering column
+      #
+      # @see #[]
+      #
+      def values_at(*primary_key_values)
+        unless next_unscoped_key_column_valid_for_in_query?
+          fail IllegalQuery,
+               "Only the last partition key column and the last clustering " \
+               "column can match multiple values"
+        end
 
-      def find(*scoped_key_values)
-        self[*scoped_key_values].load!
-      end
+        primary_key_values = primary_key_values.map(&method(:cast_range_key))
 
-      def /(scoped_key_value)
-        self[scoped_key_value]
+        scope_and_resolve do |attributes|
+          attributes[:scoped_key_values] << primary_key_values
+        end
       end
 
+      #
+      # Return a loaded Record or collection of loaded Records with the
+      # specified primary key values
+      #
+      # @param scoped_key_values one or more values for the final primary key
+      #   column
+      # @return [Record] if a single key is specified, return the loaded
+      #   record at that key
+      # @return [LazyRecordCollection] if multiple keys are specified, return a
+      #   collection of loaded records at those keys
+      # @raise [RecordNotFound] if not all the keys correspond to records in
+      #   the table
+      # @raise [ArgumentError] if not all primary key columns have been
+      #   specified
+      #
+      # @note This should only be called when all but the last column in the
+      #   primary key is already specified in this record set
+      def find(*scoped_key_values)
+        (scoped_key_values.one? ?
+          self[scoped_key_values.first] :
+          values_at(*scoped_key_values)).load!
+      end
+
+      #
+      # Restrict records to ones whose value in the first unscoped primary key
+      # column are strictly greater than the given start_key.
+      #
+      # @param start_key the exclusive lower bound for the key column
+      # @return [RecordSet] record set with lower bound applied
+      #
+      # @see #from
+      #
       def after(start_key)
         scoped(lower_bound: bound(true, false, start_key))
       end
 
+      #
+      # Restrict records to ones whose value in the first unscoped primary key
+      # column are strictly less than the given end_key.
+      #
+      # @param end_key the exclusive upper bound for the key column
+      # @return [RecordSet] record set with upper bound applied
+      #
+      # @see #upto
+      #
       def before(end_key)
         scoped(upper_bound: bound(false, false, end_key))
       end
 
+      #
+      # Restrict records to those whose value in the first unscoped primary key
+      # column are in the given range. Will accept both inclusive ranges
+      # (`1..5`) and end-exclusive ranges (`1...5`). If you need a range with
+      # an exclusive start value, use {#after}, which can be combined with
+      # {#before} or {#from} to create a range.
+      #
+      # @param range [Range] range of values for the key column
+      # @return [RecordSet] record set with range restriction applied
+      #
+      # @see #after
+      # @see #before
+      # @see #from
+      # @see #upto
+      #
       def in(range)
         scoped(
           lower_bound: bound(true, true, range.first),
@@ -88,53 +381,138 @@ module Cequel
         )
       end
 
+      #
+      # Restrict records to those whose value in the first unscoped primary key
+      # column are greater than or equal to the given start key.
+      #
+      # @param start_key the inclusive lower bound for values in the key column
+      # @return [RecordSet] record set with the lower bound applied
+      #
+      # @see #after
+      #
       def from(start_key)
         unless partition_specified?
-          raise IllegalQuery,
-            "Can't construct exclusive range on partition key #{range_key_name}"
+          fail IllegalQuery,
+               "Can't construct exclusive range on partition key " \
+               "#{range_key_name}"
         end
         scoped(lower_bound: bound(true, true, start_key))
       end
 
+      #
+      # Restrict records to those whose value in the first unscoped primary key
+      # column are less than or equal to the given start key.
+      #
+      # @param end_key the inclusive upper bound for values in the key column
+      # @return [RecordSet] record set with the upper bound applied
+      #
+      # @see #before
+      #
       def upto(end_key)
         unless partition_specified?
-          raise IllegalQuery,
-            "Can't construct exclusive range on partition key #{range_key_name}"
+          fail IllegalQuery,
+               "Can't construct exclusive range on partition key " \
+               "#{range_key_name}"
         end
         scoped(upper_bound: bound(false, true, end_key))
       end
 
+      #
+      # Reverse the order in which records will be returned from the record set
+      #
+      # @return [RecordSet] record set with order reversed
+      #
+      # @note This method can only be called on record sets whose partition key
+      #   columns are fully specified. See {#[]} for a discussion of partition
+      #   key scoping.
+      #
       def reverse
         unless partition_specified?
-          raise IllegalQuery,
-            "Can't reverse without scoping to partition key #{range_key_name}"
+          fail IllegalQuery,
+               "Can't reverse without scoping to partition key " \
+               "#{range_key_name}"
         end
         scoped(reversed: !reversed?)
       end
 
+      #
+      # @overload first
+      #   @return [Record] the first record in this record set
+      #
+      # @overload first(count)
+      #   @param count [Integer] how many records to return
+      #   @return [Array] the first `count` records of the record set
+      #
+      # @return [Record,Array]
+      #
       def first(count = nil)
         count ? limit(count).entries : limit(1).each.first
       end
 
+      #
+      # @overload last
+      #   @return [Record] the last record in this record set
+      #
+      # @overload last(count)
+      #   @param count [Integer] how many records to return
+      #   @return [Array] the last `count` records in the record set in
+      #     ascending order
+      #
+      # @return [Record,Array]
+      #
       def last(count = nil)
         reverse.first(count).tap do |results|
           results.reverse! if count
         end
       end
 
+      #
+      # @return [Integer] the total number of records in this record set
+      #
       def count
         data_set.count
       end
 
+      #
+      # Enumerate over the records in this record set
+      #
+      # @yieldparam record [Record] each successive record in the record set
+      # @return [Enumerator] if no block given
+      # @return [void]
+      #
+      # @see find_each
+      #
       def each(&block)
         find_each(&block)
       end
 
+      #
+      # Enumerate over the records in this record set, with control over how
+      # the database is queried
+      #
+      # @param (see #find_rows_in_batches)
+      # @yieldparam (see #each)
+      # @option (see #find_rows_in_batches)
+      # @return (see #each)
+      #
+      # @see #find_in_batches
+      #
       def find_each(options = {})
         return enum_for(:find_each, options) unless block_given?
         find_each_row(options) { |row| yield target_class.hydrate(row) }
       end
 
+      #
+      # Enumerate over the records in this record set in batches. Note that the
+      # given batch_size controls the maximum number of records that can be
+      # returned per query, but no batch is guaranteed to be exactly the given
+      # `batch_size`
+      #
+      # @param (see #find_rows_in_batches)
+      # @option (see #find_rows_in_batches)
+      # @yieldparam batch [Array<Record>] batch of records
+      # @return (see #each)
+      #
       def find_in_batches(options = {})
         return enum_for(:find_in_batches, options) unless block_given?
         find_rows_in_batches(options) do |rows|
@@ -142,13 +520,39 @@ module Cequel
         end
       end
 
+      #
+      # Enumerate over the row data for each record in this record set, without
+      # hydrating an actual {Record} instance. Useful for operations where
+      # speed is at a premium.
+      #
+      # @param (see #find_rows_in_batches)
+      # @option (see #find_rows_in_batches)
+      # @yieldparam row [Hash<Symbol,Object>] a hash of column names to values
+      #   for each row
+      # @return (see #each)
+      #
+      # @see #find_rows_in_batches
+      #
       def find_each_row(options = {}, &block)
         return enum_for(:find_each_row, options) unless block
         find_rows_in_batches(options) { |rows| rows.each(&block) }
       end
 
+      #
+      # Enumerate over batches of row data for the records in this record set.
+      #
+      # @param options [Options] options for querying the database
+      # @option options [Integer] :batch_size (1000) the maximum number of rows
+      #   to return per batch query
+      # @yieldparam batch [Array<Hash<Symbol,Object>>] a batch of rows
+      # @return (see #each)
+      #
+      # @see #find_each_row
+      # @see #find_in_batches
+      #
       def find_rows_in_batches(options = {}, &block)
         return find_rows_in_single_batch(options, &block) if row_limit
+        options.assert_valid_keys(:batch_size)
         batch_size = options.fetch(:batch_size, 1000)
         batch_record_set = base_record_set = limit(batch_size)
         more_results = true
@@ -165,26 +569,46 @@ module Cequel
         end
       end
 
+      #
+      # @return [Cequel::Metal::DataSet] the data set underlying this record
+      #   set
+      #
       def data_set
         @data_set ||= construct_data_set
       end
 
+      #
+      # @return [Hash] map of key column names to the values that have been
+      #   specified in this record set
+      #
       def scoped_key_attributes
         Hash[scoped_key_columns.map { |col| col.name }.zip(scoped_key_values)]
       end
 
+      # (see BulkWrites#delete_all)
+      def delete_all
+        if partition_specified?
+          data_set.delete
+        else
+          super
+        end
+      end
+
       def_delegators :entries, :inspect
 
+      # @private
       def ==(other)
         entries == other.to_a
       end
 
       protected
+
       attr_reader :attributes
-      hattr_reader :attributes, :select_columns, :scoped_key_values, :row_limit,
-        :lower_bound, :upper_bound, :scoped_indexed_column
+      hattr_reader :attributes, :select_columns, :scoped_key_values,
+                   :row_limit, :lower_bound, :upper_bound,
+                   :scoped_indexed_column
       protected :select_columns, :scoped_key_values, :row_limit, :lower_bound,
-        :upper_bound, :scoped_indexed_column
+                :upper_bound, :scoped_indexed_column
       hattr_inquirer :attributes, :reversed
       protected :reversed?
 
@@ -194,16 +618,16 @@ module Cequel
 
       def find_nested_batches_from(row, options, &block)
         if next_range_key_column
-          at(row[range_key_name]).
-            next_batch_from(row).
-            find_rows_in_batches(options, &block)
+          at(row[range_key_name])
+            .next_batch_from(row)
+            .find_rows_in_batches(options, &block)
         end
       end
 
       def find_rows_in_single_batch(options = {})
         if options.key?(:batch_size)
-          raise ArgumentError,
-            "Can't pass :batch_size argument with a limit in the scope"
+          fail ArgumentError,
+               "Can't pass :batch_size argument with a limit in the scope"
         else
           data_set.entries.tap do |batch|
             yield batch if batch.any? && block_given?
@@ -251,10 +675,21 @@ module Cequel
         scoped_key_values.length >= target_class.partition_key_columns.length
       end
 
+      def partition_exactly_specified?
+        scoped_key_values.length == target_class.partition_key_columns.length
+      end
+
       def multiple_records_specified?
         scoped_key_values.any? { |values| values.is_a?(Array) }
       end
 
+      def next_unscoped_key_column_valid_for_in_query?
+        next_unscoped_key_column = unscoped_key_columns.first
+
+        next_unscoped_key_column == partition_key_columns.last ||
+          next_unscoped_key_column == clustering_columns.last
+      end
+
       def resolve_if_fully_specified
         if fully_specified?
           if multiple_records_specified?
@@ -267,27 +702,28 @@ module Cequel
         end
       end
 
-      # Try to order results by the first clustering column. Fall back to partition key if none exist.
       def order_by_column
-        target_class.clustering_columns.first.name if target_class.clustering_columns.any?
+        if target_class.clustering_columns.any?
+          target_class.clustering_columns.first.name
+        end
       end
 
       def selects_collection_columns?
         select_columns.any? do |column_name|
-          target_class.reflect_on_column(column_name).
-            is_a?(Cequel::Schema::CollectionColumn)
+          target_class.reflect_on_column(column_name).collection_column?
         end
       end
 
       def select_non_collection_columns!
         if selects_collection_columns?
-          raise ArgumentError,
-            "Can't scope by multiple keys when selecting a collection column."
+          fail ArgumentError,
+               "Can't scope by multiple keys when selecting a collection " \
+               "column."
         end
         if select_columns.empty?
-          non_collection_columns = target_class.columns.
-            reject { |column| column.is_a?(Cequel::Schema::CollectionColumn) }.
-            map { |column| column.name }
+          non_collection_columns = target_class.columns
+            .reject { |column| column.collection_column? }
+            .map { |column| column.name }
           select(*non_collection_columns)
         else
           self
@@ -295,6 +731,7 @@ module Cequel
       end
 
       private
+
       def_delegators :target_class, :connection
       def_delegator :range_key_column, :cast, :cast_range_key
       private :connection, :cast_range_key
@@ -304,22 +741,7 @@ module Cequel
       end
 
       def construct_data_set
-        data_set = connection[target_class.table_name]
-        data_set = data_set.limit(row_limit) if row_limit
-        data_set = data_set.select(*select_columns) if select_columns
-        if scoped_key_values
-          key_conditions = Hash[scoped_key_names.zip(scoped_key_values)]
-          data_set = data_set.where(key_conditions)
-        end
-        if lower_bound
-          data_set = data_set.where(*lower_bound.to_cql_with_bind_variables)
-        end
-        if upper_bound
-          data_set = data_set.where(*upper_bound.to_cql_with_bind_variables)
-        end
-        data_set = data_set.order(order_by_column => :desc) if reversed?
-        data_set = data_set.where(scoped_indexed_column) if scoped_indexed_column
-        data_set
+        DataSetBuilder.build_for(self)
       end
 
       def bound(gt, inclusive, value)
@@ -327,13 +749,19 @@ module Cequel
       end
 
       def cast_range_key_for_bound(value)
-        if range_key_column.type?(Type::Timeuuid) && !value.is_a?(CassandraCQL::UUID)
+        if range_key_column.type?(Type::Timeuuid) &&
+           !value.is_a?(CassandraCQL::UUID)
+
           Type::Timestamp.instance.cast(value)
         else
           cast_range_key(value)
         end
       end
 
+      def load!
+        fail ArgumentError, "Not all primary key columns have specified values"
+      end
+
       def scoped(new_attributes = {}, &block)
         attributes_copy = Marshal.load(Marshal.dump(attributes))
         attributes_copy.merge!(new_attributes)
@@ -341,15 +769,16 @@ module Cequel
         RecordSet.new(target_class, attributes_copy)
       end
 
+      def scope_and_resolve(&block)
+        scoped(&block).resolve_if_fully_specified
+      end
+
       def key_attributes_for_each_row
         return enum_for(:key_attributes_for_each_row) unless block_given?
         select(*key_column_names).find_each do |record|
           yield record.key_attributes
         end
       end
-
     end
-
   end
-
 end