vertica 1.0.0.rc1 → 1.0.0.rc2

data/lib/vertica/data_type.rb

@@ -0,0 +1,146 @@
+# Class that represents a data type of a column.
+#
+# This gem is only able to handle registered types. Types are registered using {.register}.
+# If an unregistered type is encountered, the library will raise {Vertica::Error::UnknownTypeError}.
+#
+# @example Handling an unknown OID:
+#   Vertica::DataType.register 12345, 'fancy_type', lambda { |bytes| ... }
+#
+# @attr_reader oid [Integer] The object ID of the type.
+# @attr_reader name [String] The name of the type as it can be used in SQL.
+# @attr_reader size [Integer] The size of the type.
+# @attr_reader modifier [Integer] A modifier of the type.
+# @attr_reader format [Integer] The serialization format of this type.
+# @attr_reader deserializer [Proc] Proc that can deserialize values of this type coming from the database.
+#
+# @see Vertica::Column
+class Vertica::DataType
+
+  class << self
+    # @return [Hash<Integer, Hash>] The Vertica types that are registered with this library, indexed by OID.
+    # @see .register
+    attr_accessor :registered_types
+
+    # Registers a new type by OID.
+    #
+    # @param oid [Integer] The object ID of the type.
+    # @param name [String] The name of the type as it can be used in SQL.
+    # @param deserializer [Proc] Proc that can deserialize values of this type coming
+    #    from the database.
+    # @return [void]
+    def register(oid, name, deserializer = self.default_deserializer)
+      self.registered_types ||= {}
+      self.registered_types[oid] = { oid: oid, name: name, deserializer: TYPE_DESERIALIZERS.fetch(deserializer) }
+    end
+
+    # Builds a new type instance based on an OID.
+    # @param (see Vertica::DataType#initialize)
+    # @return [Vertica::DataType]
+    # @raise [Vertica::Error::UnknownTypeError] if the OID is not registered.
+    def build(oid: nil, **kwargs)
+      args = registered_types.fetch(oid) do |unknown_oid|
+        raise Vertica::Error::UnknownTypeError, "Unknown type OID: #{unknown_oid}"
+      end
+
+      new(args.merge(kwargs))
+    end
+
+    # The name of the default deserializer proc.
+    # @return [Symbol]
+    def default_deserializer
+      :generic
+    end
+  end
+
+  attr_reader :oid, :name, :size, :modifier, :format, :deserializer
+
+  # Instantiates a new DataType.
+  #
+  # @param oid [Integer] The object ID of the type.
+  # @param name [String] The name of the type as it can be used in SQL.
+  # @param size [Integer] The size of the type.
+  # @param modifier [Integer] A modifier of the type.
+  # @param format [Integer] The serialization format of this type.
+  # @param deserializer [Proc] Proc that can deserialize values of this type coming
+  #    from the database.
+  # @see .build
+  def initialize(oid: nil, name: nil, size: nil, modifier: nil, format: 0, deserializer: nil)
+    @oid, @name, @size, @modifier, @format, @deserializer = oid, name, size, modifier, format, deserializer
+  end
+
+  # @return [Integer] Returns a hash digtest of this object.
+  def hash
+    [oid, size, modifier, format].hash
+  end
+
+  # @return [Boolean] Returns true iff this record is equal to the other provided object
+  def eql?(other)
+    other.kind_of?(Vertica::DataType) && oid == other.oid && size == other.size &&
+      modifier == other.modifier && other.format == format
+  end
+
+  alias_method :==, :eql?
+
+  # Deserializes a value of this type as returned by the server.
+  # @param bytes [String, nil] The representation of the value returned by the server.
+  # @return [Object] The Ruby-value taht repesents the value returned from the DB.
+  # @see Vertica::Protocol::DataRow
+  def deserialize(bytes)
+    return nil if bytes.nil?
+    deserializer.call(bytes)
+  end
+
+  # @return [String] Returns a user-consumable string representation of this type.
+  def inspect
+    "#<#{self.class.name}:#{oid} #{sql.inspect}>"
+  end
+
+  # Returns a SQL representation of this type.
+  # @return [String]
+  # @todo Take size and modifier into account.
+  def sql
+    name
+  end
+
+  TYPE_DESERIALIZERS = {
+    generic: lambda { |bytes| bytes },
+    bool: lambda { |bytes|
+      case bytes
+        when 't'; true
+        when 'f'; false
+        else raise ArgumentError, "Cannot convert #{bytes.inspect} to a boolean value"
+      end
+    },
+    integer: lambda { |bytes| Integer(bytes) },
+    float: lambda { |bytes|
+      case bytes
+        when 'Infinity'; Float::INFINITY
+        when '-Infinity'; -Float::INFINITY
+        when 'NaN'; Float::NAN
+        else Float(bytes)
+      end
+    },
+    bigdecimal: lambda { |bytes| BigDecimal(bytes) },
+    unicode_string: lambda { |bytes| bytes.force_encoding(Encoding::UTF_8) },
+    binary_string: lambda { |bytes| bytes.gsub(/\\([0-3][0-7][0-7])/) { $1.to_i(8).chr }.force_encoding(Encoding::BINARY) },
+    date: lambda { |bytes| Date.parse(bytes) },
+    timestamp: lambda { |bytes| Time.parse(bytes) },
+  }.freeze
+
+  private_constant :TYPE_DESERIALIZERS
+end
+
+Vertica::DataType.register 5, 'bool', :bool
+Vertica::DataType.register 6, 'integer', :integer
+Vertica::DataType.register 7, 'float', :float
+Vertica::DataType.register 8, 'char', :unicode_string
+Vertica::DataType.register 9, 'varchar', :unicode_string
+Vertica::DataType.register 10, 'date', :date
+Vertica::DataType.register 11, 'time'
+Vertica::DataType.register 12, 'timestamp', :timestamp
+Vertica::DataType.register 13, 'timestamp_tz', :timestamp
+Vertica::DataType.register 14, 'time_tz'
+Vertica::DataType.register 15, 'interval'
+Vertica::DataType.register 16, 'numeric', :bigdecimal
+Vertica::DataType.register 17, 'bytes', :binary_string
+Vertica::DataType.register 115, 'long varchar', :unicode_string

data/lib/vertica/error.rb

@@ -8,6 +8,7 @@ class Vertica::Error < StandardError
   class EmptyQueryError < Vertica::Error; end
   class TimedOutError < ConnectionError; end
   class UnknownTypeError < Vertica::Error; end
+  class DuplicateColumnName < Vertica::Error; end
 
   class SynchronizeError < Vertica::Error
     attr_reader :running_job, :requested_job

data/lib/vertica/protocol/backend/command_complete.rb

@@ -3,19 +3,10 @@ module Vertica
     class CommandComplete < BackendMessage
       message_id 'C'
 
-      attr_reader :tag, :rows, :oid
+      attr_reader :tag
 
       def initialize(data)
-        case data = data.unpack('Z*').first
-          when /^INSERT /
-            @tag, oid, rows = data.split(' ', 3)
-            @oid, @rows = oid.to_i, rows.to_i
-          when /^DELETE /, /^UPDATE /, /^MOVE /, /^FETCH /, /^COPY /
-            @tag, @rows = data.split(' ', 2)
-            @rows = rows.to_i
-          else
-            @tag = data
-        end
+        @tag = data.unpack('Z*').first
       end
     end
   end

data/lib/vertica/protocol/backend/row_description.rb

@@ -18,7 +18,7 @@ module Vertica
             :data_type_oid      => field_info[3],
             :data_type_size     => field_info[4],
             :data_type_modifier => field_info[5],
-            :format_code        => field_info[6],
+            :data_format        => field_info[6],
           }
 
           pos += 19 + field_info[0].size

data/lib/vertica/query.rb

@@ -1,38 +1,56 @@
+# The Query class handles the state of the connection while a SQL query is being executed.
+# The connection should call {#run} and it will block until the query has been handled by
+# the connection, after which control will be given back to the {Connection} instance.
+#
+# @note This class is for internal use only, you should never interact with this class directly.
+#
+# @see Vertica::Connection#query
+# @see Vertica::Connection#copy
 class Vertica::Query
 
-  attr_reader :connection, :sql, :error, :result
-
+  # Instantiates a new query
+  # @param connection [Vertica::Connection] The connection to use for the query
+  # @param sql [String] The SQL statement to execute.
+  # @param row_handler [Proc, nil] Callback that will be called for every row that is returned.
+  #   If no handler is provided, all rows will be buffered so a {Vertica::Result} can be returned.
+  #
+  # @param copy_handler [Proc, nil] Callback that will be called when the connection is ready
+  #   to receive data for a `COPY ... FROM STDIN` statement.
   def initialize(connection, sql, row_handler: nil, copy_handler: nil)
     @connection, @sql = connection, sql
-    if row_handler.nil?
-      @buffer = []
-      @row_handler = lambda { |row| buffer_row(row) }
-    else
-      @row_handler = row_handler
-    end
+    @buffer = row_handler.nil? && copy_handler.nil? ? [] : nil
+    @row_handler = row_handler || lambda { |row| buffer_row(row) }
     @copy_handler = copy_handler
-    @error = nil
+    @row_description, @error = nil, nil
   end
 
+  # Sends the query to the server, and processes the results.
+  # @return [String] For an unbuffered query, the type of SQL command will be return as a string
+  #   (e.g. `"SELECT"` or `"COPY"`).
+  # @return [Vertica::Result] For a buffered query, this method will return a {Vertica::Result} instance
+  # @raise [Vertica::Error::ConnectionError] if the connection between client and
+  #   server fails.
+  # @raise [Vertica::Error::QueryError] if the server cannot evaluate the query.
   def run
-    @connection.write_message(Vertica::Protocol::Query.new(sql))
+    @connection.write_message(Vertica::Protocol::Query.new(@sql))
 
     begin
       process_message(message = @connection.read_message)
     end until message.kind_of?(Vertica::Protocol::ReadyForQuery)
 
-    raise error unless error.nil?
-    return result
+    raise @error unless @error.nil?
+    return @result
   end
 
-  def to_s
-    @sql
+  # @return [String] Returns a user-consumable string representation of this query instance.
+  def inspect
+    "#<Vertica::Query:#{object_id} sql=#{@sql.inspect}>"
   end
 
-  protected
+  private
 
   def buffer_rows?
-    !!@buffer
+    @buffer.is_a?(Array)
   end
 
   def process_message(message)
@@ -64,7 +82,7 @@ class Vertica::Query
 
   def handle_command_complete(message)
     if buffer_rows?
-      @result = Vertica::Result.build(row_description: @row_description, rows: @buffer, tag: message.tag)
+      @result = Vertica::Result.new(row_description: @row_description, rows: @buffer, tag: message.tag)
       @row_description, @buffer = nil, nil
     else
       @result = message.tag
@@ -76,7 +94,7 @@ class Vertica::Query
       @connection.write_message(Vertica::Protocol::CopyFail.new('no handler provided'))
     else
       begin
-        @copy_handler.call(CopyFromStdinWriter.new(connection))
+        @copy_handler.call(CopyFromStdinWriter.new(@connection))
         @connection.write_message(Vertica::Protocol::CopyDone.new)
       rescue => e
         @connection.write_message(Vertica::Protocol::CopyFail.new(e.message))

data/lib/vertica/result.rb

@@ -1,22 +1,62 @@
+# Class that represents a buffered resultset.
+#
+# This class implements the Enumerable interface for easy iteration through
+# the rows. You can also address specific values in the result using {#fetch}.
+# To leanr more about the shape of the result {#row_description} will give you
+# an ordered list of all the {Vertica::Column}s in this result.
+#
+# @example Iterating over the rows
+#    result = connection.query("SELECT name, id")
+#    result.each do |row|
+#      puts "#{row[:id]}: #{row[:name]}"
+#    end
+#
+# @example Fetching specific values in the result
+#    result = connection.query('SELECT id, name FROM people WHERE id = 1')
+#    name = result.fetch(0, 'name')
+#    id = result[0,0]
+#
+# @example Retrieving the only value in a result
+#    average_salery = connection.query("SELECT AVG(salery) FROM employees").the_value
+#
+# @attr_reader [Vertica::RowDescription] row_description The columns in the result.
+# @attr_reader [String] tag The kind of SQL command that produced this reuslt.
+#
+# @see Vertica::Connection#query
 class Vertica::Result
   include Enumerable
 
-  attr_reader :row_description
-  attr_reader :rows
-  attr_reader :tag
+  attr_reader :row_description, :tag
 
+  # Initializes a new Vertica::Result instance.
+  #
+  # The constructor assumes that the row description, and the list of rows match up.
+  # If you're unsure, use {Vertica::Result.build} which will assert this is the case.
+  #
+  # @param row_description [Vertica::RowDescription] The description of the rows
+  # @param rows [Array<Vertica::Row>] The array of rows
+  # @param tag [String] The kind of command that returned this result.
+  # @see Vertica::Result.build
   def initialize(row_description: nil, rows: nil, tag: nil)
     @row_description, @rows, @tag = row_description, rows, tag
   end
 
+  # Iterates through the resultset. This class also includes the `Enumerable`
+  # interface, which means you can use all the `Enumerable` methods like `map`
+  # and `inject`  as well.
+  # @yield The provided block will be called for every row in the resutset.
+  # @yieldparam row [Vertica::Row]
+  # @return [void]
   def each(&block)
     @rows.each(&block)
   end
 
+  # @return [Boolean] Returns `true` if the result has no rows.
   def empty?
     @rows.empty?
   end
 
+  # @return [Integer] The number of rows in this result
   def size
     @rows.length
   end
@@ -24,14 +64,31 @@ class Vertica::Result
   alias_method :count, :size
   alias_method :length, :size
 
-  def fetch(row_index, col = nil)
-    row = rows.fetch(row_index)
+  # Retrieves a row or value from the result.
+  # @return [Vertica::Row, Object]
+  #
+  # @overload fetch(row)
+  #   Returns a row from the result.
+  #   @param row [Integer] The 0-indexed row number.
+  #   @raise [IndexError] if the row index is out of bounds.
+  #   @return [Vertica::Row]
+  # @overload fetch(row, column)
+  #   Returns a singular value from the result.
+  #   @param row [Integer] The 0-indexed row number.
+  #   @param col [Symbol, String, Integer] The name or index of the column.
+  #   @raise [IndexError] if the row index is out of bounds.
+  #   @raise [KeyError] if the requested column is not part of the result
+  #   @return The value at the given row and column in the result.
+  def fetch(row, col = nil)
+    row = @rows.fetch(row)
     return row if col.nil?
     row.fetch(col)
   end
 
   alias_method :[], :fetch
 
+  # Shorthand to return the value of a query that only returns a single value.
+  # @return The first value of the first row, i.e. `fetch(0, 0)`.
   def value
     fetch(0, 0)
   end
@@ -40,6 +97,13 @@ class Vertica::Result
 
   alias_method :columns, :row_description
 
+  # Builds a {Vertica::Result} from a row description and a list of compatible rows.
+  # @param row_description An object that can be built into a {Vertica::RowDescription}.
+  #   See {Vertica::RowDescription.build} for more info
+  # @param rows [Array] An array of objects that can be turned into a {Vertica::Row}.
+  #   See {Vertica::RowDescription#build_row} for more info
+  # @param tag [String] The type of SQL command that yielded the result.
+  # @return [Vertica::Result]
   def self.build(row_description: nil, rows: [], tag: nil)
     row_description = Vertica::RowDescription.build(row_description)
     rows = rows.map { |values| row_description.build_row(values) }

data/lib/vertica/row.rb

@@ -1,35 +1,86 @@
+# Class to represent a row returns by a query.
+#
+# Row instances can either be yielded to the block passed to {Vertica::Connection#query},
+# or be part of a buffered {Vertica::Result} returned by {Vertica::Connection#query}.
+#
+# @attr_reader row_description [Vertica::RowDescription] The ordered list of columns this
+#   row conforms to.
+#
+# @see Vertica::RowDescription#build_row
 class Vertica::Row
   include Enumerable
 
+  attr_reader :row_description
+
+  # Initializes a new row instance for a given row description and values. The
+  # number of values MUST match the number of columns in the row description.
+  # @param row_description [Vertica::RowDescription] The row description the
+  #   values will conform to.
+  # @param values [Array] The values for the columns in the row description
+  # @see Vertica::RowDescription#build_row
   def initialize(row_description, values)
     @row_description, @values = row_description, values
   end
 
+  # Iterates over the values in this row.
+  # @yield [value] The provided block will get called with the values in the order of
+  #   the columns in the row_description.
   def each(&block)
     @values.each(&block)
   end
 
+  # Fetches a value from this row.
+  # @param name_or_index [Symbol, String, Integer] The name of the column as string or symbol,
+  #   or the index of the column in the row description.
+  # @raise KeyError A KeyError is raised if the field connot be found.
   def fetch(name_or_index)
     @values.fetch(column_index(name_or_index))
   end
 
-  def inspect
-    "<Vertica::Row#{@values.inspect}>"
-  end
-
   alias_method :[], :fetch
 
+  # Returns an array representation of the row. The values will
+  # be ordered like the order of the fields in the {#row_description}.
+  # @return [Array]
   def to_a
-    @values.to_a
+    @values
   end
 
+  # Returns a hash representation of this rows, using the name of the
+  # fields as keys.
+  # @param symbolize_keys [true, false] Set to true to use symbols instead
+  #   of strings for the field names.
+  # @return [Hash]
+  # @raise [Vertica::Error::DuplicateColumnName] If the row contains multiple
+  #   columns with the same name
   def to_h(symbolize_keys: false)
     @row_description.inject({}) do |carry, column|
       key = symbolize_keys ? column.name.to_sym : column.name
-      carry.merge(key => fetch(column.name))
+      raise Vertica::Error::DuplicateColumnName, "Column with name #{key} occurs more than once in this row." if carry.key?(key)
+      carry[key] = fetch(column.name)
+      carry
     end
   end
 
+  # @return [Boolean] Returns true iff this record is equal to the other provided object
+  def eql?(other)
+    other.kind_of?(Vertica::Row) && other.row_description == row_description && other.to_a == to_a
+  end
+
+  alias_method :==, :eql?
+
+  # @return [Integer] Returns a hash digtest of this object.
+  def hash
+    [row_description, values].hash
+  end
+
+  # @return [String] Returns a user-consumable string representation of this row.
+  def inspect
+    "#<#{self.class.name}#{@values.inspect}>"
+  end
+
+  private
+
   def column(name_or_index)
     column_with_index(name_or_index).fetch(0)
   end