cequel 1.0.0.rc1 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d15e60b9c3a9725632fe70d140449a03dc1e033
-  data.tar.gz: cc8dd115c0639388ee13b77437b3a7ae6addb2ef
+  metadata.gz: 4988b87b5a5a9fc843dcaaf3bdfb3a5842b20cc8
+  data.tar.gz: ce93eaeb725d23f31a22dc3f8e2e84fc4d9ec0e7
 SHA512:
-  metadata.gz: 7b710ee3238b02cc47f0b57a9804ee4f729c1cd807e809b7134888f44b066f59330714aaf7460bafae1d702d2eba47f7dff3ac3b8e2f18b30f03bb3e259498c0
-  data.tar.gz: 870947477a6da3d0f72aae1d6f4154293c41da41b1bf7419c4906737ed86d70ebc9598901a2eec2a121a0412955b7c00e4b5cd03df3dd9228597653b64347bd9
+  metadata.gz: b738d10a75bd0f977eeff27c119ccd9d7980c66e2e1bdf004ef74e980dc847514ea7083cd9432f28b4d1099a151c635a71f50cd1f1757d6a20c16c42074504a0
+  data.tar.gz: be8264f1142625d8755a149550f68a9c2dc66b93c7a6a562f0c893043dbaf859ab879632911c8b753b96cdd07ea025b2348f12a237e07bdc4c7cad27015093a8

data/lib/cequel.rb

@@ -1,3 +1,5 @@
+require 'delegate'
+
 require 'active_support/core_ext'
 require 'cassandra-cql/1.2'
 require 'connection_pool'
@@ -9,7 +11,23 @@ require 'cequel/type'
 require 'cequel/util'
 require 'cequel/record'
 
+#
+# Cequel is a library providing robust data modeling and query building
+# capabilities for Cassandra using CQL3.
+#
+# @see Cequel::Record Cequel::Record, an object-row mapper for CQL3
+# @see Cequel::Metal Cequel::Metal, a query builder for CQL3 statements
+# @see Cequel::Schema Cequel::Schema::Keyspace, which provides full read-write
+#   access to the database schema defined in Cassandra
+#
 module Cequel
+  #
+  # Get a handle to a keyspace
+  #
+  # @param (see Metal::Keyspace#initialize)
+  # @option (see Metal::Keyspace#initialize)
+  # @return [Metal::Keyspace] a handle to a keyspace
+  #
   def self.connect(configuration = nil)
     Metal::Keyspace.new(configuration || {})
   end

data/lib/cequel/errors.rb

@@ -1,6 +1,10 @@
 module Cequel
-  Error = Class.new(StandardError)
-  EmptySubquery = Class.new(Error)
-  InvalidSchemaMigration = Class.new(Error)
-  MissingKeyError = Class.new(Error)
+  #
+  # @since 1.0.0
+  #
+  # Raised when the schema defined in Cassandra cannot be modified to match
+  # the schema defined in the application (e.g., changing the type of a primary
+  # key)
+  #
+  InvalidSchemaMigration = Class.new(StandardError)
 end

data/lib/cequel/metal.rb

@@ -1,7 +1,10 @@
 require 'cequel/metal/batch'
+require 'cequel/metal/batch_manager'
 require 'cequel/metal/cql_row_specification'
 require 'cequel/metal/data_set'
+require 'cequel/metal/logging'
 require 'cequel/metal/keyspace'
+require 'cequel/metal/logger'
 require 'cequel/metal/row'
 require 'cequel/metal/row_specification'
 require 'cequel/metal/statement'
@@ -12,6 +15,17 @@ require 'cequel/metal/inserter'
 require 'cequel/metal/updater'
 
 module Cequel
+  #
+  # The Cequel::Metal layer provides a low-level interface to the Cassandra
+  # database. Most of the functionality is exposed via the DataSet class, which
+  # encapsulates a table with optional filtering, and provides an interface for
+  # constructing read and write queries. The Metal layer is not schema-aware,
+  # and relies on the user to construct valid CQL queries.
+  #
+  # @see Keyspace
+  # @see DataSet
+  # @since 1.0.0
+  #
   module Metal
   end
 end

data/lib/cequel/metal/batch.rb

@@ -1,26 +1,30 @@
 require 'stringio'
 
 module Cequel
-
   module Metal
-
     #
     # Encapsulates a batch operation
     #
     # @see Keyspace::batch
+    # @api private
     #
     class Batch
-
       #
-      # @param keyspace [Keyspace] the keyspace that this batch will be executed on
+      # @param keyspace [Keyspace] the keyspace that this batch will be
+      #   executed on
       # @param options [Hash]
-      # @option options (see Keyspace#batch)
+      # @option options [Integer] :auto_apply If specified, flush the batch
+      #   after this many statements have been added.
+      # @option options [Boolean] :unlogged (false) Whether to use an [unlogged
+      #   batch](http://www.datastax.com/documentation/cql/3.0/webhelp/cql/cql_reference/batch_r.html).
+      #   Logged batches guarantee atomicity (but not isolation) at the
+      #   cost of a performance penalty; unlogged batches are useful for bulk
+      #   write operations but behave the same as discrete writes.
       # @see Keyspace#batch
-      # @todo support batch-level consistency options
       #
       def initialize(keyspace, options = {})
         @keyspace = keyspace
-        @auto_apply = options.fetch(:auto_apply, false)
+        @auto_apply = options[:auto_apply]
         @unlogged = options.fetch(:unlogged, false)
         reset
       end
@@ -39,7 +43,7 @@ module Cequel
         end
       end
 
-      # 
+      #
       # Send the batch to Cassandra
       #
       def apply
@@ -51,10 +55,19 @@ module Cequel
         @keyspace.execute(*@statement.args)
       end
 
+      #
+      # Is this an unlogged batch?
+      #
+      # @return [Boolean]
       def unlogged?
         @unlogged
       end
 
+      #
+      # Is this a logged batch?
+      #
+      # @return [Boolean]
+      #
       def logged?
         !unlogged?
       end
@@ -69,9 +82,6 @@ module Cequel
       def begin_statement
         "BEGIN #{"UNLOGGED " if unlogged?}BATCH\n"
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/batch_manager.rb

@@ -0,0 +1,74 @@
+module Cequel
+  module Metal
+    #
+    # Manage a current batch per thread. Used by {Keyspace}
+    #
+    # @api private
+    #
+    class BatchManager
+      #
+      # @param keyspace [Keyspace] keyspace to make writes to
+      # @api private
+      #
+      def initialize(keyspace)
+        @keyspace = keyspace
+      end
+
+      #
+      # Execute write operations in a batch. Any inserts, updates, and deletes
+      # inside this method's block will be executed inside a CQL BATCH
+      # operation.
+      #
+      # @param options [Hash]
+      # @option (see Batch#initialize)
+      # @yield context within which all write operations will be batched
+      # @return return value of block
+      # @raise [ArgumentError] if attempting to start a logged batch while
+      #   already in an unlogged batch, or vice versa.
+      #
+      # @example Perform inserts in a batch
+      #   DB.batch do
+      #     DB[:posts].insert(:id => 1, :title => 'One')
+      #     DB[:posts].insert(:id => 2, :title => 'Two')
+      #   end
+      #
+      # @note If this method is created while already in a batch of the same
+      #   type (logged or unlogged), this method is a no-op.
+      #
+      def batch(options = {})
+        new_batch = Batch.new(keyspace, options)
+
+        if current_batch
+          if current_batch.unlogged? && new_batch.logged?
+            fail ArgumentError,
+                 "Already in an unlogged batch; can't start a logged batch."
+          end
+          return yield
+        end
+
+        begin
+          self.current_batch = new_batch
+          yield.tap { new_batch.apply }
+        ensure
+          self.current_batch = nil
+        end
+      end
+
+      private
+
+      attr_reader :keyspace
+
+      def current_batch
+        ::Thread.current[batch_key]
+      end
+
+      def current_batch=(batch)
+        ::Thread.current[batch_key] = batch
+      end
+
+      def batch_key
+        :"cequel-batch-#{object_id}"
+      end
+    end
+  end
+end

data/lib/cequel/metal/cql_row_specification.rb

@@ -1,26 +1,39 @@
 module Cequel
-
   module Metal
-
+    #
+    # Encapsulates a row specification (`WHERE` clause) specified by a CQL
+    # string
     #
     # @api private
     #
     class CqlRowSpecification
-
+      #
+      # Build a new row specification
+      #
+      # @param (see #initialize)
+      # @return [Array<CqlRowSpecification>]
+      #
       def self.build(condition, bind_vars)
         [new(condition, bind_vars)]
       end
 
+      #
+      # Create a new row specification
+      #
+      # @param [String] condition CQL string representing condition
+      # @param [Array] bind_vars Bind variables
+      #
       def initialize(condition, bind_vars)
         @condition, @bind_vars = condition, bind_vars
       end
 
+      #
+      # CQL and bind variables for this condition
+      #
+      # @return [Array] CQL string followed by zero or more bind variables
       def cql
         [@condition, *@bind_vars]
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/data_set.rb

@@ -1,29 +1,58 @@
-module Cequel
+require 'forwardable'
 
+module Cequel
   module Metal
-
     #
-    # Encapsulates a data set, specified as a column family and optionally
+    # Encapsulates a data set, specified as a table and optionally
     # various query elements.
     #
-    # @todo Support ALTER, CREATE, CREATE INDEX, DROP
+    # @example Data set representing entire contents of a table
+    #   data_set = database[:posts]
+    #
+    # @example Data set limiting rows returned
+    #   data_set = database[:posts].limit(10)
+    #
+    # @example Data set targeting only one partition
+    #   data_set = database[:posts].where(blog_subdomain: 'cassandra')
+    #
+    # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/select_r.html CQL documentation for SELECT
     #
     class DataSet
-
       include Enumerable
       extend Forwardable
 
-      attr_reader :keyspace, :table_name, :select_columns, :ttl_columns,
-        :writetime_columns, :row_specifications, :sort_order, :row_limit
+      # @return [Keyspace] keyspace that this data set's table resides in
+      attr_reader :keyspace
+      # @return [Symbol] name of the table that this data set retrieves data
+      #   from
+      attr_reader :table_name
+      # @return [Array<Symbol>] columns that this data set restricts result
+      #   rows to; empty if none
+      attr_reader :select_columns
+      # @return [Array<Symbol>] columns that this data set will select the TTLs
+      #   of
+      attr_reader :ttl_columns
+      # @return [Array<Symbol>] columns that this data set will select the
+      #   writetimes of
+      attr_reader :writetime_columns
+      # @return [Array<RowSpecification>] row specifications limiting the
+      #   result rows returned by this data set
+      attr_reader :row_specifications
+      # @return [Hash<Symbol,Symbol>] map of column names to sort directions
+      attr_reader :sort_order
+      # @return [Integer] maximum number of rows to return, `nil` if no limit
+      attr_reader :row_limit
 
       def_delegator :keyspace, :execute, :execute_cql
+      private :execute_cql
       def_delegator :keyspace, :write
 
       #
       # @param table_name [Symbol] column family for this data set
-      # @param keyspace [Keyspace] keyspace this data set's column family lives in
+      # @param keyspace [Keyspace] keyspace this data set's table lives in
       #
       # @see Keyspace#[]
+      # @api private
       #
       def initialize(table_name, keyspace)
         @table_name, @keyspace = table_name, keyspace
@@ -34,22 +63,61 @@ module Cequel
       #
       # Insert a row into the column family.
       #
-      # @param [Hash] data column-value pairs. The first entry *must* be the key column.
-      # @param [Options] options options for persisting the row
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param data [Hash] column-value pairs
+      # @param options [Options] options for persisting the row
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @note `INSERT` statements will succeed even if a row at the specified
+      #   primary key already exists. In this case, column values specified in
+      #   the insert will overwrite the existing row.
+      # @note If a enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/insert_r.html CQL documentation for INSERT
       #
       def insert(data, options = {})
         inserter(options) { insert(data) }.execute
       end
 
       #
-      # Update rows
+      # Upsert data into one or more rows
+      #
+      # @overload update(column_values, options = {})
+      #   Update the rows specified in the data set with new values
+      #
+      #   @param column_values [Hash] map of column names to new values
+      #   @param options [Options] options for persisting the column data
+      #   @option (see #generate_upsert_options)
+      #
+      #   @example
+      #     posts.where(blog_subdomain: 'cassandra', permalink: 'cequel').
+      #       update(title: 'Announcing Cequel 1.0')
+      #
+      # @overload update(options = {}, &block)
+      #   Construct an update statement consisting of multiple operations
+      #
+      #   @param options [Options] options for persisting the data
+      #   @option (see #generate_upsert_options)
+      #   @yield DSL context for adding write operations
+      #
+      #   @see Updater
+      #   @since 1.0.0
+      #
+      #   @example
+      #     posts.where(blog_subdomain: 'bigdata', permalink: 'cql').update do
+      #       set(title: 'Announcing Cequel 1.0')
+      #       list_append(categories: 'ORMs')
+      #     end
       #
-      # @param [Hash] data column-value pairs
-      # @param [Options] options options for persisting the column data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @return [void]
+      #
+      # @note `UPDATE` statements will succeed even if targeting a row that
+      #   does not exist. In this case a new row will be created.
+      # @note This statement will fail unless one or more rows are fully
+      #   specified by primary key using `where`
+      # @note If a enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/update_r.html CQL documentation for UPDATE
       #
       def update(*args, &block)
         if block
@@ -60,24 +128,63 @@ module Cequel
         end
       end
 
-      def increment(data, options = {})
-        incrementer(options) { increment(data) }.execute
+      #
+      # Increment one or more counter columns
+      #
+      # @param deltas [Hash<Symbol,Integer>] map of counter column names to
+      #   amount by which to increment each column
+      # @return [void]
+      #
+      # @example
+      #   post_analytics.
+      #     where(blog_subdomain: 'cassandra', permalink: 'cequel').
+      #     increment(pageviews: 10, tweets: 2)
+      #
+      # @note This can only be used on counter tables
+      # @since 0.5.0
+      # @see #decrement
+      # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/../cql_using/use_counter_t.html CQL documentation for counter columns
+      #
+      def increment(deltas, options = {})
+        incrementer(options) { increment(deltas) }.execute
       end
+      alias_method :incr, :increment
 
-      def decrement(data, options = {})
-        incrementer(options) { decrement(data) }.execute
+      #
+      # Decrement one or more counter columns
+      #
+      # @param deltas [Hash<Symbol,Integer>] map of counter column names to
+      #   amount by which to decrement each column
+      # @return [void]
+      #
+      # @see #increment
+      # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/../cql_using/use_counter_t.html CQL documentation for counter columns
+      # @since 0.5.0
+      #
+      def decrement(deltas, options = {})
+        incrementer(options) { decrement(deltas) }.execute
       end
       alias_method :decr, :decrement
 
       #
       # Prepend element(s) to a list in the row(s) matched by this data set.
       #
-      # @param [Symbol] column name of list column to prepend to
-      # @param [Object,Array] elements one element or an array of elements to prepend
-      # @param [Options] options options for persisting the column data
-      # @option (see #generate_upsert_options)
-      # @note If multiple elements are passed, they will appear in the list in reverse order.
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param column [Symbol] name of list column to prepend to
+      # @param elements [Object,Array] one element or an array of elements to
+      #   prepend
+      # @param options [Options] options for persisting the column data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.list_prepend(:categories, ['CQL', 'ORMs'])
+      #
+      # @note If multiple elements are passed, they will appear in the list in
+      #   reverse order.
+      # @note If a enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #list_append
+      # @see #update
       #
       def list_prepend(column, elements, options = {})
         updater(options) { list_prepend(column, elements) }.execute
@@ -86,11 +193,21 @@ module Cequel
       #
       # Append element(s) to a list in the row(s) matched by this data set.
       #
-      # @param [Symbol] column name of list column to append to
-      # @param [Object,Array] elements one element or an array of elements to append
-      # @param [Options] options options for persisting the column data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param column [Symbol] name of list column to append to
+      # @param elements [Object,Array] one element or an array of elements to
+      #   append
+      # @param options [Options] options for persisting the column data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.list_append(:categories, ['CQL', 'ORMs'])
+      #
+      # @note If a enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #list_append
+      # @see #update
+      # @since 1.0.0
       #
       def list_append(column, elements, options = {})
         updater(options) { list_append(column, elements) }.execute
@@ -99,12 +216,20 @@ module Cequel
       #
       # Replace a list element at a specified index with a new value
       #
-      # @param [Symbol] column name of list column
-      # @param [Integer] index which element to replace
-      # @param [Object] value new value at this index
-      # @param [Options] options options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param column [Symbol] name of list column
+      # @param index [Integer] which element to replace
+      # @param value [Object] new value at this index
+      # @param options [Options] options for persisting the data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.list_replace(:categories, 2, 'Object-Relational Mapper')
+      #
+      # @note if a enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #update
+      # @since 1.0.0
       #
       def list_replace(column, index, value, options = {})
         updater(options) { list_replace(column, index, value) }.execute
@@ -113,24 +238,43 @@ module Cequel
       #
       # Remove all occurrences of a given value from a list column
       #
-      # @param [Symbol] column name of list column
-      # @param [Object] value value to remove
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param column [Symbol] name of list column
+      # @param value [Object] value to remove
+      # @param options [Options] options for persisting the data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.list_remove(:categories, 'CQL3')
+      #
+      # @note If enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #list_remove_at
+      # @see #update
+      # @since 1.0.0
       #
       def list_remove(column, value, options = {})
         updater(options) { list_remove(column, value) }.execute
       end
 
       #
-      # Remove all occurrences of a given value from a list column
+      # @overload list_remove_at(column, *positions, options = {})
+      #   Remove the value from a given position or positions in a list column
+      #
+      #   @param column [Symbol] name of list column
+      #   @param positions [Integer] position(s) in list to remove value from
+      #   @param options [Options] options for persisting the data
+      #   @option (see Writer#initialize)
+      #   @return [void]
+      #
+      #   @example
+      #     posts.list_remove_at(:categories, 2)
       #
-      # @param [Symbol] column name of list column
-      # @param [Object] position position in list to remove value from
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      #   @note If enclosed in a Keyspace#batch block, this method will be
+      #     executed as part of the batch.
+      #   @see #list_remove
+      #   @see #update
+      #   @since 1.0.0
       #
       def list_remove_at(column, *positions)
         options = positions.extract_options!
@@ -138,13 +282,22 @@ module Cequel
       end
 
       #
-      # Remove a given key from a map column
+      # @overload map_remove(column, *keys, options = {})
+      #   Remove a given key from a map column
       #
-      # @param [Symbol] column name of map column
-      # @param [Object] key map key to remove
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      #   @param column [Symbol] name of map column
+      #   @param keys [Object] map key to remove
+      #   @param options [Options] options for persisting the data
+      #   @option (see Writer#initialize)
+      #   @return [void]
+      #
+      #   @example
+      #     posts.map_remove(:credits, 'editor')
+      #
+      #   @note If enclosed in a Keyspace#batch block, this method will be
+      #     executed as part of the batch.
+      #   @see #update
+      #   @since 1.0.0
       #
       def map_remove(column, *keys)
         options = keys.extract_options!
@@ -152,50 +305,112 @@ module Cequel
       end
 
       #
-      # Add one or more elements to a set
+      # Add one or more elements to a set column
+      #
+      # @param column [Symbol] name of set column
+      # @param values [Object,Set] value or values to add
+      # @param options [Options] options for persisting the data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.set_add(:tags, 'cql3')
       #
-      # @param [Symbol] column name of set column
-      # @param [Object,Set] value value or values to add
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @note If enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #update
+      # @since 1.0.0
       #
       def set_add(column, values, options = {})
         updater(options) { set_add(column, values) }.execute
       end
 
       #
-      # Remove one or more elements from a set
+      # Remove an element from a set
       #
-      # @param [Symbol] column name of set column
-      # @param [Object,Set] value value or values to add
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @param column [Symbol] name of set column
+      # @param value [Object] value to remove
+      # @param options [Options] options for persisting the data
+      # @option (see Writer#initialize)
+      # @return [void]
+      #
+      # @example
+      #   posts.set_remove(:tags, 'cql3')
+      #
+      # @note If enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #update
+      # @since 1.0.0
       #
       def set_remove(column, value, options = {})
         updater(options) { set_remove(column, value) }.execute
       end
 
       #
-      # Update one or more map elements
+      # Update one or more keys in a map column
+      #
+      # @param column [Symbol] name of set column
+      # @param updates [Hash] map of map keys to new values
+      # @param options [Options] options for persisting the data
+      # @option (see Writer#initialize)
+      # @return [void]
       #
-      # @param [Symbol] column name of set column
-      # @param [Hash] map updates
-      # @param [Options] options for persisting the data
-      # @option (see #generate_upsert_options)
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      # @example
+      #   posts.map_update(:credits, 'editor' => 34)
+      #
+      # @note If enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see #update
+      # @since 1.0.0
       #
       def map_update(column, updates, options = {})
         updater(options) { map_update(column, updates) }.execute
       end
 
       #
-      # Delete data from the column family
+      # @overload delete(options = {})
+      #   Delete one or more rows from the table
+      #
+      #   @param options [Options] options for persistence
+      #   @option (See Writer#initialize)
+      #
+      #   @example
+      #     posts.where(blog_subdomain: 'cassandra', permalink: 'cequel').
+      #       delete
+      #
+      # @overload delete(*columns, options = {})
+      #   Delete data from given columns in the specified rows. This is
+      #   equivalent to setting columns to `NULL` in an SQL database.
+      #
+      #   @param columns [Symbol] columns to remove
+      #   @param options [Options] options for persistence
+      #   @option (see Writer#initialize)
+      #
+      #   @example
+      #     posts.where(blog_subdomain: 'cassandra', permalink: 'cequel').
+      #       delete(:body)
+      #
+      # @overload delete(options = {}, &block)
+      #   Construct a `DELETE` statement with multiple operations (column
+      #   deletions, collection element removals, etc.)
       #
-      # @param columns zero or more columns to delete. Deletes the entire row if none specified.
-      # @param options persistence options
-      # @note if a enclosed in a Keyspace#batch block, this method will be executed as part of the batch.
+      #   @param options [Options] options for persistence
+      #   @option (see Writer#initialize)
+      #   @yield DSL context for construction delete statement
+      #
+      #   @example
+      #     posts.where(blog_subdomain: 'bigdata', permalink: 'cql').delete do
+      #       delete_columns :body
+      #       list_remove_at :categories, 2
+      #     end
+      #
+      #   @see Deleter
+      #
+      # @return [void]
+      #
+      # @note If enclosed in a Keyspace#batch block, this method will be
+      #   executed as part of the batch.
+      # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/delete_r.html CQL documentation for DELETE
       #
       def delete(*columns, &block)
         options = columns.extract_options!
@@ -211,7 +426,7 @@ module Cequel
       #
       # Select specified columns from this data set.
       #
-      # @param *columns [Symbol,Array] columns to select
+      # @param columns [Symbol] columns columns to select
       # @return [DataSet] new data set scoped to specified columns
       #
       def select(*columns)
@@ -223,9 +438,11 @@ module Cequel
       #
       # Return the remaining TTL for the specified columns from this data set.
       #
-      # @param *columns [Symbol,Array] columns to select
+      # @param columns [Symbol] columns to select
       # @return [DataSet] new data set scoped to specified columns
       #
+      # @since 1.0.0
+      #
       def select_ttl(*columns)
         clone.tap do |data_set|
           data_set.ttl_columns.concat(columns.flatten)
@@ -235,9 +452,11 @@ module Cequel
       #
       # Return the write time for the specified columns in the data set
       #
-      # @param *columns [Symbol,Array] columns to select
+      # @param columns [Symbol] columns to select
       # @return [DataSet] new data set scoped to specified columns
       #
+      # @since 1.0.0
+      #
       def select_writetime(*columns)
         clone.tap do |data_set|
           data_set.writetime_columns.concat(columns.flatten)
@@ -247,7 +466,7 @@ module Cequel
       #
       # Select specified columns from this data set, overriding chained scope.
       #
-      # @param *columns [Symbol,Array] columns to select
+      # @param columns [Symbol,Array] columns to select
       # @return [DataSet] new data set scoped to specified columns
       #
       def select!(*columns)
@@ -257,31 +476,40 @@ module Cequel
       end
 
       #
-      # Add a row_specification to this data set
+      # Filter this data set with a row specification
+      #
+      # @overload where(column_values)
+      #   @param column_values [Hash] Map of column name to values to match
       #
-      # @param row_specification [Hash, String] row_specification statement
-      # @param *bind_vars bind variables, only if using a CQL string row_specification
-      # @return [DataSet] new data set scoped to this row_specification
-      # @example Using a simple hash
-      #   DB[:posts].where(:title => 'Hey')
-      # @example Using a CQL string
-      #   DB[:posts].where("title = 'Hey'")
-      # @example Using a CQL string with bind variables
-      #   DB[:posts].where('title = ?', 'Hey')
-      # @example Use another data set as an input -- inner data set must return a single column per row!
-      #   DB[:blogs].where(:id => DB[:posts].select(:blog_id).where(:title => 'Hey'))
+      #   @example
+      #     database[:posts].where(title: 'Hey')
+      #
+      # @overload where(cql, *bind_vars)
+      #   @param cql [String] CQL fragment representing `WHERE` statement
+      #   @param bind_vars [Object] Bind variables for the CQL fragment
+      #
+      #   @example
+      #     DB[:posts].where('title = ?', 'Hey')
+      #
+      # @return [DataSet] New data set scoped to the row specification
       #
       def where(row_specification, *bind_vars)
         clone.tap do |data_set|
-          data_set.row_specifications.
-            concat(build_row_specifications(row_specification, bind_vars))
+          data_set.row_specifications
+            .concat(build_row_specifications(row_specification, bind_vars))
         end
       end
 
+      #
+      # Replace existing row specifications
+      #
+      # @see #where
+      # @return [DataSet] New data set with only row specifications given
+      #
       def where!(row_specification, *bind_vars)
         clone.tap do |data_set|
-          data_set.row_specifications.
-            replace(build_row_specifications(row_specification, bind_vars))
+          data_set.row_specifications
+            .replace(build_row_specifications(row_specification, bind_vars))
         end
       end
 
@@ -296,10 +524,13 @@ module Cequel
       end
 
       #
-      # Control how the result rows are sorted. Note that you can only sort by
-      # clustering keys, and in the case of multiple clustering keys you can only
-      # sort by the schema's clustering order or the reverse of the clustering
-      # order for all keys.
+      # Control how the result rows are sorted
+      #
+      # @param pairs [Hash] Map of column name to sort direction
+      # @return [DataSet] new data set with the specified ordering
+      #
+      # @note The only valid ordering column is the first clustering column
+      # @since 1.0.0
       #
       def order(pairs)
         clone.tap do |data_set|
@@ -311,89 +542,74 @@ module Cequel
       # Enumerate over rows in this data set. Along with #each, all other
       # Enumerable methods are implemented.
       #
-      # @yield [Hash] result rows
-      # @return [Enumerator] enumerator for rows, if no block given
+      # @overload each
+      #   @return [Enumerator] enumerator for rows, if no block given
+      #
+      # @overload each(&block)
+      #   @yield [Hash] result rows
+      #   @return [void]
+      #
+      # @return [Enumerator,void]
       #
       def each
-        if block_given?
-          begin
-            keyspace.execute(*cql).fetch do |row|
-              yield Row.from_result_row(row)
-            end
-          rescue EmptySubquery
-            # Noop -- yield no results
-          end
-        else
-          enum_for(:each)
-        end
+        return enum_for(:each) unless block_given?
+        execute_cql(*cql).fetch { |row| yield Row.from_result_row(row) }
       end
 
       #
       # @return [Hash] the first row in this data set
       #
       def first
-        row = keyspace.execute(*limit(1).cql).fetch_row
+        row = execute_cql(*limit(1).cql).fetch_row
         Row.from_result_row(row)
-      rescue EmptySubquery
-        nil
       end
 
       #
       # @return [Fixnum] the number of rows in this data set
       #
       def count
-        keyspace.execute(*count_cql).fetch_row['count']
-      rescue EmptySubquery
-        0
+        execute_cql(*count_cql).fetch_row['count']
       end
 
       #
-      # @return [String] CQL select statement encoding this data set's scope.
+      # @return [String] CQL `SELECT` statement encoding this data set's scope.
       #
       def cql
-        statement = Statement.new.
-          append(select_cql).
-          append(" FROM #{table_name}").
-          append(*row_specifications_cql).
-          append(sort_order_cql).
-          append(limit_cql).
-          args
+        statement = Statement.new
+          .append(select_cql)
+          .append(" FROM #{table_name}")
+          .append(*row_specifications_cql)
+          .append(sort_order_cql)
+          .append(limit_cql)
+          .args
       end
 
       #
       # @return [String] CQL statement to get count of rows in this data set
       #
       def count_cql
-        Statement.new.
-          append("SELECT COUNT(*) FROM #{table_name}").
-          append(*row_specifications_cql).
-          append(limit_cql).args
+        Statement.new
+          .append("SELECT COUNT(*) FROM #{table_name}")
+          .append(*row_specifications_cql)
+          .append(limit_cql).args
       end
 
+      #
+      # @return [String]
+      #
       def inspect
-        "#<#{self.class.name}: #{CassandraCQL::Statement.sanitize(cql.first, cql[1..-1])}>"
+        "#<#{self.class.name}: " \
+          "#{CassandraCQL::Statement.sanitize(cql.first, cql[1..-1])}>"
       end
 
+      #
+      # @return [Boolean]
+      #
       def ==(other)
         cql == other.cql
       end
 
-      def inserter(options = {}, &block)
-        Inserter.new(self, options, &block)
-      end
-
-      def updater(options = {}, &block)
-        Updater.new(self, options, &block)
-      end
-
-      def incrementer(options = {}, &block)
-        Incrementer.new(self, options, &block)
-      end
-
-      def deleter(options = {}, &block)
-        Deleter.new(self, options, &block)
-      end
-
+      # @private
       def row_specifications_cql
         if row_specifications.any?
           cql_fragments, bind_vars = [], []
@@ -407,11 +623,30 @@ module Cequel
         end
       end
 
+      # @private
+      def updater(options = {}, &block)
+        Updater.new(self, options, &block)
+      end
+
+      # @private
+      def deleter(options = {}, &block)
+        Deleter.new(self, options, &block)
+      end
+
       protected
+
       attr_writer :row_limit
 
       private
 
+      def inserter(options = {}, &block)
+        Inserter.new(self, options, &block)
+      end
+
+      def incrementer(options = {}, &block)
+        Incrementer.new(self, options, &block)
+      end
+
       def initialize_copy(source)
         super
         @select_columns = source.select_columns.clone
@@ -426,11 +661,11 @@ module Cequel
           ttl_columns.map { |column| "TTL(#{column})" } +
           writetime_columns.map { |column| "WRITETIME(#{column})" }
 
-          if all_columns.any?
-            "SELECT #{all_columns.join(',')}"
-          else
-            'SELECT *'
-          end
+        if all_columns.any?
+          "SELECT #{all_columns.join(',')}"
+        else
+          'SELECT *'
+        end
       end
 
       def limit_cql
@@ -439,23 +674,25 @@ module Cequel
 
       def sort_order_cql
         if sort_order.any?
-          order = sort_order.
-            map { |column, direction| "#{column} #{direction.to_s.upcase}" }.
-            join(', ')
+          order = sort_order
+            .map { |column, direction| "#{column} #{direction.to_s.upcase}" }
+            .join(', ')
           " ORDER BY #{order}"
         end
       end
 
       def build_row_specifications(row_specification, bind_vars)
         case row_specification
-        when Hash then RowSpecification.build(row_specification)
-        when String then CqlRowSpecification.build(row_specification, bind_vars)
-        else raise ArgumentError, "Invalid argument #{row_specification.inspect}; expected Hash or String"
+        when Hash
+          RowSpecification.build(row_specification)
+        when String
+          CqlRowSpecification.build(row_specification, bind_vars)
+        else
+          fail ArgumentError,
+               "Invalid argument #{row_specification.inspect}; " \
+               "expected Hash or String"
         end
       end
-
     end
-
   end
-
 end