google-cloud-bigtable 0.6.1 → 1.0.1

data/lib/google/cloud/bigtable/row.rb

@@ -18,24 +18,29 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # Row
       #
       # Row structure based on merged cells using read row state.
+      #
       class Row
+        ##
         # Cell
         #
         # Row cell built from data chunks.
+        #
         class Cell
           attr_reader :family, :qualifier, :value, :labels, :timestamp
 
+          ##
           # Creates a row cell instance.
           #
-          # @param family [String] Column family name
-          # @param qualifier [String] Column cell qualifier name
-          # @param timestamp [Integer] Timestamp in microseconds
-          # @param value [String] Cell value
-          # @param labels [Array<String>] List of label array
-
+          # @param family [String] Column family name.
+          # @param qualifier [String] Column cell qualifier name.
+          # @param timestamp [Integer] Timestamp in microseconds.
+          # @param value [String] Cell value.
+          # @param labels [Array<String>] List of label array.
+          #
           def initialize family, qualifier, timestamp, value, labels = []
             @family = family
             @qualifier = qualifier
@@ -44,30 +49,32 @@ module Google
             @labels = labels
           end
 
+          ##
           # Converts timestamp to Time instance.
           #
-          # @param granularity [Symbol] Optional
-          #   Valid granularity types are `:micros`, `millis`
-          #   Default granularity is a millis.
+          # @param granularity [Symbol] Optional.
+          #   Valid granularity types are `:micros`, `:millis`.
+          #   Default is `:millis`.
           # @return [Time | nil]
           #
           def to_time granularity = nil
             return nil if @timestamp.zero?
-            return Time.at(@timestamp / 100_0000.0) if granularity == :micros
-            Time.at(@timestamp / 1000.0)
+            return Time.at @timestamp / 1_000_000.0 if granularity == :micros
+            Time.at @timestamp / 1000.0
           end
 
+          ##
           # Converts a value to an integer.
           #
           # @return [Integer]
           #
           def to_i
-            @value.unpack("q>").first
+            @value.unpack1 "q>"
           end
 
           # @private
           #
-          # Cell object comparator
+          # Cell object comparator.
           #
           # @return [Boolean]
           #
@@ -80,22 +87,28 @@ module Google
           end
         end
 
-        # @return [String] Row key
+        ##
+        # @return [String] Row key.
+        #
         attr_accessor :key
 
-        # @return [Hash{String => Array<Google::Cloud::Bigtable::Row::Cell>}] Row cells
+        ##
+        # @return [Hash{String => Array<Google::Cloud::Bigtable::Row::Cell>}] Row cells.
+        #
         attr_accessor :cells
 
+        ##
         # Creates a flat row object.
         #
-        # @param key [String] Row key name
+        # @param key [String] Row key name.
         #
         def initialize key = nil
           @key = key
           @cells = Hash.new { |h, k| h[k] = [] }
         end
 
-        # List of column families names
+        ##
+        # List of column families names.
         #
         # @return [Array<String>]
         #
@@ -105,15 +118,13 @@ module Google
 
         # @private
         #
-        # FlatRow object comparator
+        # FlatRow object comparator.
         #
         # @return [Boolean]
         #
         def == other
           return false unless self.class == other.class
-          if key != other.key || column_families != other.column_families
-            return false
-          end
+          return false if key != other.key || column_families != other.column_families
 
           cells.all? do |family, list|
             list == other.cells[family]

data/lib/google/cloud/bigtable/row_filter.rb

@@ -26,6 +26,7 @@ require "google/cloud/bigtable/row_filter/condition_filter"
 module Google
   module Cloud
     module Bigtable
+      ##
       # # RowFilter
       #
       # Takes a row as input and produces an alternate view of the row based on
@@ -120,6 +121,7 @@ module Google
       # while the other does not.
       #
       # @example
+      #   require "google/cloud/bigtable"
       #
       #   # Pass filter
       #   Google::Cloud::Bigtable::RowFilter.pass
@@ -145,11 +147,12 @@ module Google
 
         private_constant :PASS, :BLOCK, :SINK, :STRIP_VALUE
 
+        ##
         # Creates a chain filter instance.
         #
         # A chain RowFilter that sends rows through several RowFilters in sequence.
         #
-        # See {Google::Cloud::Bigtable::RowFilter::ChainFilter}
+        # See {Google::Cloud::Bigtable::RowFilter::ChainFilter}.
         #
         # The elements of "filters" are chained together to process the input row:
         # in row -> f(0) -> intermediate row -> f(1) -> ... -> f(N) -> out row
@@ -158,6 +161,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::ChainFilter]
         #
         # @example Create chain filter with simple filter.
+        #   require "google/cloud/bigtable"
         #
         #   chain = Google::Cloud::Bigtable::RowFilter.chain
         #
@@ -166,9 +170,10 @@ module Google
         #   chain.strip_value
         #
         #   # OR
-        #   chain.key("user-*).strip_value
+        #   chain.key("user-*").strip_value
         #
         # @example Create complex chain filter.
+        #   require "google/cloud/bigtable"
         #
         #   chain = Google::Cloud::Bigtable::RowFilter.chain
         #
@@ -176,12 +181,13 @@ module Google
         #   chain_1.label("users").qualifier("name").cells_per_row(5)
         #
         #   # Add to main chain filter
-        #   chain.chain(chain_1).value("xyz*).key("user-*")
+        #   chain.chain(chain_1).value("xyz*").key("user-*")
         #
         def self.chain
           ChainFilter.new
         end
 
+        ##
         # Creates an interleave filter.
         #
         # A RowFilter that sends each row to each of several component
@@ -216,6 +222,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::InterleaveFilter]
         #
         # @example Create an interleave filter with simple filter.
+        #   require "google/cloud/bigtable"
         #
         #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
         #
@@ -224,9 +231,10 @@ module Google
         #   interleave.sink
         #
         #   # OR
-        #   interleave.key("user-*).sink
+        #   interleave.key("user-*").sink
         #
         # @example Create complex interleave filter.
+        #   require "google/cloud/bigtable"
         #
         #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
         #
@@ -234,12 +242,13 @@ module Google
         #   chain_1.label("users").qualifier("name").cells_per_row(5)
         #
         #   # Add to main chain filter
-        #   interleave.chain(chain_1).value("xyz*).key("user-*")
+        #   interleave.chain(chain_1).value("xyz*").key("user-*")
         #
         def self.interleave
           InterleaveFilter.new
         end
 
+        ##
         # Creates a condition filter instance.
         #
         # A RowFilter that evaluates one of two possible RowFilters, depending on
@@ -250,12 +259,13 @@ module Google
         # results. Additionally, condition filters have poor performance, especially
         # when filters are set for the false condition.
         #
-        # Cannot be used within the `predicate_filter`, `true_filter`, or `false_filter`
+        # Cannot be used within the `predicate_filter`, `true_filter`, or `false_filter`.
         #
         # @param predicate [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
         # @return [Google::Cloud::Bigtable::RowFilter::ConditionFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   predicate = Google::Cloud::Bigtable::RowFilter.key("user-*")
         #   condition = Google::Cloud::Bigtable::RowFilter.condition(predicate)
@@ -267,9 +277,10 @@ module Google
         #   condition.on_match(label).otherwise(strip_value)
         #
         def self.condition predicate
-          ConditionFilter.new(predicate)
+          ConditionFilter.new predicate
         end
 
+        ##
         # Creates a pass filter instance.
         #
         # Matches all cells, regardless of input. Functionally equivalent to
@@ -278,6 +289,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.pass
         #
@@ -285,6 +297,7 @@ module Google
           PASS
         end
 
+        ##
         # Creates a block-all filter instance.
         #
         # Does not match any cells, regardless of input. Useful for temporarily
@@ -293,6 +306,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.block
         #
@@ -300,14 +314,16 @@ module Google
           BLOCK
         end
 
+        ##
         # Creates a sink filter instance.
         #
         # Outputs all cells directly to the output of the read rather than to any
-        # parent filter
+        # parent filter.
         #
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.sink
         #
@@ -315,6 +331,7 @@ module Google
           SINK
         end
 
+        ##
         # Creates a strip value filter instance.
         #
         # Replaces each cell's value with an empty string.
@@ -322,6 +339,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.strip_value
         #
@@ -329,6 +347,7 @@ module Google
           STRIP_VALUE
         end
 
+        ##
         # Creates a key filter instance to match a row key using a regular expression.
         #
         # Matches only cells from rows whose row keys satisfy the given RE2 regex. In
@@ -339,37 +358,40 @@ module Google
         # will not match the new line character `\n`, which may be present in a
         # binary key.
         #
-        # For Regex syntax:
-        # @see https://github.com/google/re2/wiki/Syntax
+        # @see https://github.com/google/re2/wiki/Syntax Regex syntax
         #
         # @param regex [String] Regex to match row keys.
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.key("user-.*")
         #
         def self.key regex
-          SimpleFilter.new.key(regex)
+          SimpleFilter.new.key regex
         end
 
+        ##
         # Creates a sample probability filter instance.
         #
         # Matches all cells from a row with probability p, and matches no cells
         # from the row with probability 1-p.
         #
-        # @param probability [Float] Probability value
-        #   Probability must be greather then 0 and less then 1.0
+        # @param probability [Float] Probability value.
+        #   Probability must be greater than 0 and less than 1.0.
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.sample(0.5)
         #
         def self.sample probability
-          SimpleFilter.new.sample(probability)
+          SimpleFilter.new.sample probability
         end
 
+        ##
         # Creates a family name match filter using a regular expression.
         #
         # Matches only cells from columns whose families satisfy the given RE2
@@ -379,20 +401,21 @@ module Google
         # `\n`, it is sufficient to use `.` as a full wildcard when matching
         # column family names.
         #
-        # For Regex syntax:
-        # @see https://github.com/google/re2/wiki/Syntax
+        # @see https://github.com/google/re2/wiki/Syntax Regex syntax
         #
         # @param regex [String] Regex to match family name.
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.family("cf-.*")
         #
         def self.family regex
-          SimpleFilter.new.family(regex)
+          SimpleFilter.new.family regex
         end
 
+        ##
         # Creates a column qualifier match filter using a regular expression.
         #
         # Matches only cells from columns whose qualifiers satisfy the given RE2
@@ -402,20 +425,21 @@ module Google
         # character will not match the new line character `\n`, which may be
         # present in a binary qualifier.
         #
-        # For Regex syntax:
-        # @see https://github.com/google/re2/wiki/Syntax
+        # @see https://github.com/google/re2/wiki/Syntax Regex syntax
         #
         # @param regex [String] Regex to match column qualifier name.
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.qualifier("user-name.*")
         #
         def self.qualifier regex
-          SimpleFilter.new.qualifier(regex)
+          SimpleFilter.new.qualifier regex
         end
 
+        ##
         # Creates a value match filter using a regular expression.
         #
         # Matches only cells with values that satisfy the given regular expression.
@@ -424,20 +448,21 @@ module Google
         # will not match the new line character `\n`, which may be present in a
         # binary value.
         #
-        # For Regex syntax:
-        # @see https://github.com/google/re2/wiki/Syntax
+        # @see https://github.com/google/re2/wiki/Syntax Regex syntax
         #
         # @param regex [String] Regex to match cell value.
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.value("abc.*")
         #
         def self.value regex
-          SimpleFilter.new.value(regex)
+          SimpleFilter.new.value regex
         end
 
+        ##
         # Creates a label filter instance to apply a label based on the result of
         # read rows.
         #
@@ -458,13 +483,15 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.label("user-detail")
         #
         def self.label value
-          SimpleFilter.new.label(value)
+          SimpleFilter.new.label value
         end
 
+        ##
         # Creates a cell-per-row-offset filter instance to skip first N cells.
         #
         # Skips the first N cells of each row, matching all subsequent cells.
@@ -475,13 +502,15 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_row_offset(3)
         #
         def self.cells_per_row_offset offset
-          SimpleFilter.new.cells_per_row_offset(offset)
+          SimpleFilter.new.cells_per_row_offset offset
         end
 
+        ##
         # Create a cells-per-row limit filter instance.
         #
         # Matches only the first N cells of each row.
@@ -492,13 +521,15 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_row(5)
         #
         def self.cells_per_row limit
-          SimpleFilter.new.cells_per_row(limit)
+          SimpleFilter.new.cells_per_row limit
         end
 
+        ##
         # Creates cells-per-column filter instance.
         #
         # Matches only the most recent N cells within each column.
@@ -509,13 +540,15 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_column(5)
         #
         def self.cells_per_column limit
-          SimpleFilter.new.cells_per_column(limit)
+          SimpleFilter.new.cells_per_column limit
         end
 
+        ##
         # Creates a timestamp-range filter instance.
         #
         # Matches only cells with timestamps within the given range.
@@ -526,6 +559,7 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   timestamp_micros = (Time.now.to_f * 1000000).round(-3)
         #   from = timestamp_micros - 300000000
@@ -540,9 +574,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.timestamp_range(to: to)
         #
         def self.timestamp_range from: nil, to: nil
-          SimpleFilter.new.timestamp_range(from, to)
+          SimpleFilter.new.timestamp_range from, to
         end
 
+        ##
         # Creates a value-range filter instance.
         #
         # Matches only cells with values that fall within the given range.
@@ -558,20 +593,29 @@ module Google
         # @param range [Google::Cloud::Bigtable::ValueRange]
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
-        # @example Start to end range
+        # @example Start to end range.
+        #   require "google/cloud/bigtable"
         #
-        #   range = Google::Cloud::Bigtable::ValueRange.from("abc").to("xyz")
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_value_range.from("value-001", inclusive: false)
         #   filter = Google::Cloud::Bigtable::RowFilter.value_range(range)
         #
-        # @example Start exlusive to infinite end range
+        # @example Start exclusive to infinite end range.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
         #
-        #   range = Google::Cloud::Bigtable::ValueRange.from("abc", inclusive: false)
+        #   range = table.new_value_range.from("value-001", inclusive: false)
         #   filter = Google::Cloud::Bigtable::RowFilter.value_range(range)
         #
         def self.value_range range
-          SimpleFilter.new.value_range(range)
+          SimpleFilter.new.value_range range
         end
 
+        ##
         # Creates a column-range filter instance.
         #
         # Matches only cells from columns within the given range.
@@ -580,13 +624,14 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
-        #   range = Google::Cloud::Bigtable::ColumnRange.new(cf).from("field0").to("field5")
+        #   range = Google::Cloud::Bigtable::ColumnRange.new("cf").from("field0").to("field5")
         #
         #   filter = Google::Cloud::Bigtable::RowFilter.column_range(range)
         #
         def self.column_range range
-          SimpleFilter.new.column_range(range)
+          SimpleFilter.new.column_range range
         end
       end
     end