questdb 0.1.0-x64-mingw-ucrt

data/lib/questdb/direct_ingestion.rb

@@ -0,0 +1,440 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module QuestDB
+  module DirectIngestion
+    module_function
+
+    KIND_CODES = {
+      byte: 0, short: 1, int: 2, long: 3, float: 4, double: 5,
+      boolean: 6, uuid: 7, long256: 8, ipv4: 9, timestamp: 10,
+      timestamp_nanos: 11, date: 12, varchar: 13, binary: 14,
+      symbol: 15, char: 16, geohash: 17, decimal64: 18,
+      decimal128: 19, decimal256: 20, double_array: 21
+    }.freeze
+    AT_NOW = 0
+    AT_SCALAR_NANOS = 1
+    AT_MICROS = 2
+    AT_NANOS = 3
+    INTEGER_RANGES = {
+      byte: (-(1 << 7))..((1 << 7) - 1), short: (-(1 << 15))..((1 << 15) - 1),
+      int: (-(1 << 31))..((1 << 31) - 1), long: (-(1 << 63))..((1 << 63) - 1)
+    }.freeze
+    InferredVector = Struct.new(:kind, :values, :scale, :precision_bits, :shape)
+    private_constant :InferredVector
+
+    # Returns the compact, native-facing representation. It contains only
+    # private frozen strings, so mutating the caller's Arrays after this method
+    # returns cannot affect an in-flight write.
+    def prepare(table, columns:, symbols:, at:, max_rows_per_batch:, ack:)
+      table = utf8_string(table.is_a?(Symbol) ? table.to_s : table, "table name").freeze
+      raise ArgumentError, "table name must not be empty" if table.empty?
+      raise TypeError, "columns must be a Hash" unless columns.is_a?(Hash)
+      raise TypeError, "symbols must be a Hash" unless symbols.is_a?(Hash)
+      batch_size = Integer(max_rows_per_batch)
+      raise ArgumentError, "max_rows_per_batch must be positive" unless batch_size.positive?
+      ack_level = { ok: 0, durable: 1 }.fetch(ack.respond_to?(:to_sym) ? ack.to_sym : ack) do
+        raise ArgumentError, "ack must be :ok or :durable"
+      end
+
+      names = {}
+      vectors = []
+      row_count = nil
+      columns.each do |name, input|
+        normalized_name = column_name(name, names)
+        vector = input.is_a?(ColumnVector) ? input : infer(input, normalized_name)
+        row_count = establish_row_count(row_count, vector.values.length, normalized_name)
+        vectors << normalize_column(normalized_name, vector)
+      end
+      symbols.each do |name, input|
+        normalized_name = column_name(name, names)
+        values = input.is_a?(ColumnVector) ? input.values : array!(input, normalized_name)
+        if input.is_a?(ColumnVector) && input.kind != :varchar
+          raise ArgumentError, "symbol #{normalized_name.inspect} descriptor must use :varchar"
+        end
+        row_count = establish_row_count(row_count, values.length, normalized_name)
+        vectors << normalize_symbol(normalized_name, values)
+      end
+
+      row_count ||= 0
+      at_kind, at_data, at_count = normalize_at(at, row_count)
+      if row_count.zero?
+        if at_count && at_count.positive?
+          raise ArgumentError, "designated timestamp has #{at_count} rows but columns are empty"
+        end
+        return [table, [].freeze, AT_NOW, nil, 0, batch_size, ack_level].freeze
+      end
+      raise ArgumentError, "at vector has #{at_count} rows, expected #{row_count}" if at_count && at_count != row_count
+
+      [table, vectors.freeze, at_kind, at_data, row_count, batch_size, ack_level].freeze
+    end
+
+    def infer(input, name)
+      values = array!(input, name)
+      first = values.find { |value| !value.nil? }
+      if first.nil?
+        raise ArgumentError, "column #{name.inspect} is all nil; use QuestDB::ColumnVector with an explicit kind" unless values.empty?
+        return InferredVector.new(:long, values, nil, nil, nil)
+      end
+
+      kind = case first
+             when Integer then :long
+             when Float then :double
+             when TrueClass, FalseClass then :boolean
+             when String then :varchar
+             when Binary then :binary
+             when UUID then :uuid
+             when Long256 then :long256
+             when IPv4 then :ipv4
+             when TimestampNanos then :timestamp_nanos
+             when TimestampMicros then :timestamp
+             when DateMillis then :date
+             when Char then :char
+             when Geohash then :geohash
+             when DecimalValue then :decimal
+             when Float64Array then :double_array
+             else
+               raise TypeError, "cannot infer direct column type for #{name.inspect} from #{first.class}"
+             end
+      unless homogeneous_for_kind?(kind, values, first.class)
+        raise TypeError, "column #{name.inspect} is heterogeneous; use a homogeneous Array or explicit ColumnVector"
+      end
+      kind = decimal_kind(values) if kind == :decimal
+      metadata = case kind
+                 when :geohash
+                   bits = first.precision_bits
+                   raise ArgumentError, "all geohashes in #{name.inspect} must have the same precision" unless values.all? { |v| v.nil? || v.precision_bits == bits }
+                   { precision_bits: bits }
+                 when :decimal64, :decimal128, :decimal256
+                   scale = first.scale
+                   raise ArgumentError, "all decimals in #{name.inspect} must have the same non-negative scale" unless values.all? { |v| v.nil? || v.scale == scale }
+                   { scale: scale }
+                 when :double_array
+                   shape = first.shape
+                   raise ArgumentError, "all arrays in #{name.inspect} must have the same shape" unless values.all? { |v| v.nil? || v.shape == shape }
+                   { shape: shape }
+                 else {}
+                 end
+      InferredVector.new(kind, values, metadata[:scale], metadata[:precision_bits], metadata[:shape])
+    end
+
+    def normalize_column(name, vector)
+      kind = vector.kind
+      values = vector.values
+      if %i[byte short boolean char].include?(kind) && values.any?(&:nil?)
+        raise ArgumentError, "#{kind} cannot represent NULL in QuestDB; use :int, :varchar, or another nullable kind"
+      end
+      validity = validity_for(values)
+      data = case kind
+             when :byte, :short, :int, :long then pack_integers(values, kind)
+             when :float then pack_floats(values, "f")
+             when :double then pack_floats(values, "d")
+             when :boolean then pack_booleans(values)
+             when :varchar then pack_variable(values) { |v| utf8_string(v, "VARCHAR value", copy: false) }
+             when :binary then pack_variable(values) { |v| v.is_a?(Binary) ? v.bytes : String(v) }
+             when :uuid then values.map { |v| v.nil? ? ("\0" * 16) : (v.is_a?(UUID) ? v : UUID.new(v)).bytes }.join.b
+             when :long256 then values.map { |v| v.nil? ? ("\0" * 32) : (v.is_a?(Long256) ? v : Long256.new(v)).bytes }.join.b
+             when :ipv4 then values.map { |v| v.nil? ? 0 : (v.is_a?(IPv4) ? v : IPv4.new(v)).value }.pack("L*")
+             when :timestamp then values.map { |v| v.nil? ? 0 : timestamp_value(v, :micros) }.pack("q*")
+             when :timestamp_nanos then values.map { |v| v.nil? ? 0 : timestamp_value(v, :nanos) }.pack("q*")
+             when :date then values.map { |v| v.nil? ? 0 : date_value(v) }.pack("q*")
+             when :char then values.map { |v| v.nil? ? 0 : (v.is_a?(Char) ? v : Char.new(v)).value }.pack("S*")
+             when :geohash then pack_geohashes(values, vector.precision_bits)
+             when :decimal64, :decimal128, :decimal256 then pack_decimals(values, kind, vector.scale)
+             when :double_array then pack_double_arrays(values, vector.shape)
+             else raise ArgumentError, "unsupported direct column kind #{kind.inspect}"
+             end
+
+      descriptor = if %i[varchar binary].include?(kind)
+                     offsets, bytes = data
+                     [KIND_CODES.fetch(kind), name, offsets.freeze, validity, bytes.freeze, nil, 0, 0]
+                   elsif kind == :geohash
+                     [KIND_CODES.fetch(kind), name, data.freeze, validity, nil, nil, vector.precision_bits, 0]
+                   elsif %i[decimal64 decimal128 decimal256].include?(kind)
+                     [KIND_CODES.fetch(kind), name, data.freeze, validity, nil, nil, vector.scale, 0]
+                   elsif kind == :double_array
+                     shape = vector.shape.pack("L*").freeze
+                     [KIND_CODES.fetch(kind), name, data.freeze, validity, shape, nil, vector.shape.length, 0]
+                   else
+                     [KIND_CODES.fetch(kind), name, data.freeze, validity, nil, nil, 0, 0]
+                   end
+      descriptor.freeze
+    end
+
+    def normalize_symbol(name, values)
+      values = array!(values, name)
+      dictionary = {}
+      source_codes = {}
+      entries = []
+      codes = values.map do |value|
+        next 0 if value.nil?
+        source_codes.fetch(value) do
+          text = utf8_string(value, "SYMBOL value", copy: false)
+          index = dictionary.fetch(text) do
+            owned = text.dup.freeze
+            entries << owned
+            dictionary[owned] = entries.length - 1
+          end
+          source_codes[value] = index
+        end
+      end
+      offsets = [0]
+      bytes = +"".b
+      entries.each { |entry| bytes << entry; offsets << bytes.bytesize }
+      [KIND_CODES[:symbol], name, codes.pack("l*").freeze, validity_for(values), offsets.pack("l*").freeze,
+       bytes.force_encoding(Encoding::BINARY).freeze, 0, 0].freeze
+    end
+
+    def normalize_at(at, row_count)
+      return [AT_NOW, nil, nil] if at.equal?(SERVER_TIMESTAMP)
+      if at.is_a?(Array) || at.is_a?(ColumnVector)
+        vector = at.is_a?(ColumnVector) ? at : nil
+        values = vector ? vector.values : at
+        if values.any?(&:nil?)
+          raise ArgumentError, "designated timestamp vector cannot contain nil"
+        end
+        kind = if vector
+                 raise ArgumentError, "at ColumnVector must be :timestamp or :timestamp_nanos" unless %i[timestamp timestamp_nanos].include?(vector.kind)
+                 vector.kind
+               else
+                 nonempty = values.first
+                 case nonempty
+                 when TimestampNanos, Time then :timestamp_nanos
+                 when TimestampMicros then :timestamp
+                 when nil then :timestamp
+                 else raise TypeError, "at Array values must be TimestampNanos, TimestampMicros, or Time"
+                 end
+               end
+        expected = kind == :timestamp_nanos ? [TimestampNanos, Time] : [TimestampMicros]
+        unless values.all? { |value| expected.any? { |klass| value.is_a?(klass) } }
+          raise TypeError, "designated timestamp vector is heterogeneous"
+        end
+        unit = kind == :timestamp_nanos ? :nanos : :micros
+        packed = values.map { |value| non_negative_timestamp(timestamp_value(value, unit)) }.pack("q*").freeze
+        [kind == :timestamp_nanos ? AT_NANOS : AT_MICROS, packed, values.length]
+      else
+        nanos = case at
+                when TimestampNanos then at.value
+                when TimestampMicros then checked_multiply(at.value, 1_000, "designated timestamp")
+                when Time then time_nanos(at)
+                else raise TypeError, "at must be a timestamp vector, TimestampNanos, TimestampMicros, Time, or SERVER_TIMESTAMP"
+                end
+        [AT_SCALAR_NANOS, non_negative_timestamp(nanos), nil]
+      end
+    end
+
+    def validity_for(values)
+      return nil unless values.any?(&:nil?)
+      bits = Array.new((values.length + 7) / 8, 0)
+      values.each_with_index { |value, index| bits[index / 8] |= 1 << (index % 8) unless value.nil? }
+      bits.pack("C*").freeze
+    end
+
+    def pack_integers(values, kind)
+      range = INTEGER_RANGES.fetch(kind)
+      converted = values.map do |value|
+        next 0 if value.nil?
+        number = Integer(value)
+        raise RangeError, "#{kind} value #{number} is out of range" unless range.cover?(number)
+        if (kind == :int || kind == :long) && number == range.begin
+          raise RangeError, "#{kind} minimum value is reserved as QuestDB NULL"
+        end
+        number
+      end
+      converted.pack({ byte: "c*", short: "s*", int: "l*", long: "q*" }.fetch(kind))
+    end
+
+    def pack_floats(values, directive)
+      values.map do |value|
+        next 0.0 if value.nil?
+        raise TypeError, "floating-point columns accept only Numeric values" unless value.is_a?(Numeric)
+        number = Float(value)
+        raise RangeError, "NaN is reserved as QuestDB NULL" if number.nan?
+        if directive == "f" && number.finite? && number.abs > 3.4028234663852886e38
+          raise RangeError, "float value is outside IEEE-754 binary32 range"
+        end
+        number
+      end.pack("#{directive}*")
+    end
+
+    def pack_booleans(values)
+      bits = Array.new((values.length + 7) / 8, 0)
+      values.each_with_index do |value, index|
+        next if value.nil? || value == false
+        raise TypeError, "boolean columns accept only true, false, or nil" unless value == true
+        bits[index / 8] |= 1 << (index % 8)
+      end
+      bits.pack("C*")
+    end
+
+    def pack_variable(values)
+      offsets = [0]
+      bytes = +"".b
+      values.each do |value|
+        bytes << yield(value) unless value.nil?
+        raise RangeError, "variable-width column exceeds 2 GiB" if bytes.bytesize > 0x7fff_ffff
+        offsets << bytes.bytesize
+      end
+      [offsets.pack("l*"), bytes.force_encoding(Encoding::BINARY)]
+    end
+
+    def pack_geohashes(values, bits)
+      limit = (1 << bits) - 1
+      numbers = values.map do |value|
+        next 0 if value.nil?
+        geohash = value.is_a?(Geohash) ? value : Geohash.new(value, precision_bits: bits)
+        raise ArgumentError, "geohash precision mismatch" unless geohash.precision_bits == bits
+        raise RangeError, "geohash value exceeds precision" unless geohash.value.between?(0, limit)
+        geohash.value
+      end
+      numbers.pack(bits <= 8 ? "C*" : bits <= 16 ? "S*" : bits <= 32 ? "L*" : "Q*")
+    end
+
+    def pack_decimals(values, kind, scale)
+      width = { decimal64: 8, decimal128: 16, decimal256: 32 }.fetch(kind)
+      values.map do |value|
+        mantissa = if value.nil?
+                     0
+                   elsif value.is_a?(DecimalValue)
+                     raise ArgumentError, "decimal scale mismatch" unless value.scale == scale
+                     value.mantissa
+                   else Integer(value)
+                   end
+        min = -(1 << (width * 8 - 1)); max = (1 << (width * 8 - 1)) - 1
+        raise RangeError, "#{kind} mantissa is out of range" unless mantissa.between?(min, max)
+        twos_complement_bytes(mantissa, width)
+      end.join.b
+    end
+
+    def pack_double_arrays(values, shape)
+      size = shape.inject(1, :*)
+      values.map do |value|
+        next Array.new(size, 0.0).pack("d*") if value.nil?
+        array = value.is_a?(Float64Array) ? value : Float64Array.from_nested(value)
+        raise ArgumentError, "double_array shape mismatch" unless array.shape == shape
+        raise ArgumentError, "double_array value count mismatch" unless array.values.length == size
+        array.values.map { |item| Float(item) }.pack("d*")
+      end.join.b
+    end
+
+    def decimal_kind(values)
+      first = values.find { |value| !value.nil? }
+      scale = first.scale
+      raise RangeError, "decimal inference requires a non-negative scale" if scale.negative?
+      bits = values.reduce(0) do |maximum, value|
+        next maximum unless value
+        candidate = value.mantissa.bit_length + 1
+        candidate > maximum ? candidate : maximum
+      end
+      kind = bits <= 63 && scale <= 18 ? :decimal64 : bits <= 127 && scale <= 38 ? :decimal128 : :decimal256
+      cap = { decimal64: 18, decimal128: 38, decimal256: 76 }.fetch(kind)
+      raise RangeError, "decimal cannot fit a direct QuestDB decimal type" if bits > 255 || scale > cap
+      kind
+    end
+
+    def homogeneous_for_kind?(kind, values, expected_class)
+      case kind
+      when :boolean then values.all? { |value| value.nil? || value == true || value == false }
+      when :varchar then values.all? { |value| value.nil? || value.class == String }
+      else values.all? { |value| value.nil? || value.class == expected_class }
+      end
+    end
+
+    def timestamp_value(value, unit)
+      result = case value
+               when TimestampNanos
+                 unit == :nanos ? value.value : value.value.div(1_000)
+               when TimestampMicros
+                 unit == :micros ? value.value : checked_multiply(value.value, 1_000, "timestamp")
+               when Time
+                 unit == :nanos ? time_nanos(value) : time_nanos(value).div(1_000)
+               else Integer(value)
+               end
+      check_i64(result, "timestamp")
+    end
+
+    def date_value(value)
+      check_i64(value.is_a?(DateMillis) ? value.value : Integer(value), "date")
+    end
+
+    def time_nanos(time)
+      check_i64(time.to_i * 1_000_000_000 + time.nsec, "timestamp")
+    end
+
+    def non_negative_timestamp(value)
+      raise RangeError, "designated timestamp cannot be before the Unix epoch" if value.negative?
+      value
+    end
+
+    def checked_multiply(value, multiplier, label)
+      check_i64(Integer(value) * multiplier, label)
+    end
+
+    def check_i64(value, label)
+      raise RangeError, "#{label} is outside signed 64-bit range" unless value.between?(-(1 << 63), (1 << 63) - 1)
+      value
+    end
+
+    def twos_complement_bytes(value, width)
+      unsigned = value.negative? ? (1 << (width * 8)) + value : value
+      bytes = Array.new(width) { |index| (unsigned >> (index * 8)) & 0xff }
+      bytes.reverse! unless [1].pack("S") == "\x01\x00".b
+      bytes.pack("C*")
+    end
+
+    def establish_row_count(current, candidate, name)
+      return candidate if current.nil?
+      raise ArgumentError, "column #{name.inspect} has #{candidate} rows, expected #{current}" unless candidate == current
+      current
+    end
+
+    def column_name(name, names)
+      normalized = utf8_string(name.is_a?(Symbol) ? name.to_s : name, "column name").freeze
+      raise ArgumentError, "column name must not be empty" if normalized.empty?
+      raise ArgumentError, "duplicate column #{normalized.inspect}" if names.key?(normalized)
+      names[normalized] = true
+      normalized
+    end
+
+    def array!(value, name)
+      raise TypeError, "column #{name.inspect} must be an Array or ColumnVector" unless value.is_a?(Array)
+      value
+    end
+
+    def utf8_string(value, label, copy: true)
+      string = String(value)
+      if string.encoding == Encoding::UTF_8
+        raise EncodingError, "#{label} is not valid UTF-8" unless string.valid_encoding?
+        return copy ? string.dup : string
+      end
+      if string.ascii_only?
+        return string unless copy
+        return string.dup.force_encoding(Encoding::UTF_8)
+      end
+      string.encode(Encoding::UTF_8)
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError => error
+      raise EncodingError, "#{label} is not valid UTF-8: #{error.message}"
+    end
+  end
+end

data/lib/questdb/event_inbox.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+require "thread"
+
+module QuestDB
+  # Internal bounded, drop-oldest queue used after native callbacks have been
+  # copied into Ruby-owned values. Callback dispatch never waits on consumers.
+  class EventInbox
+    def initialize(capacity)
+      @capacity = capacity.zero? ? 64 : capacity
+      @items = []
+      @mutex = Mutex.new
+      @delivered = 0
+      @dropped = 0
+    end
+
+    def push(value)
+      @mutex.synchronize do
+        if @items.length == @capacity
+          @items.shift
+          @dropped += 1
+        end
+        @items << value
+      end
+    end
+
+    def poll
+      @mutex.synchronize do
+        value = @items.shift
+        @delivered += 1 if value
+        value
+      end
+    end
+
+    def delivered = @mutex.synchronize { @delivered }
+    def dropped = @mutex.synchronize { @dropped }
+  end
+  private_constant :EventInbox
+end

data/lib/questdb/ingress/buffer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module QuestDB
+  module Ingress
+    class Buffer
+      MAX_PREALLOCATE_BYTES = 100 * 1024 * 1024
+      EMPTY_HASH = {}.freeze
+      private_constant :EMPTY_HASH
+
+      class << self
+        private
+
+        def from_native(native)
+          object = allocate
+          object.send(:initialize_native, native)
+          object
+        end
+
+        private :new
+      end
+
+      def row(table, symbols: EMPTY_HASH, columns: EMPTY_HASH, at:)
+        append(table, symbols, columns, at)
+        self
+      end
+
+      def row_count = @native.row_count
+      alias length row_count
+      def empty? = row_count.zero?
+
+      # QWP encodes at publication time. These values are only memory hints.
+      def bytesize = @native.bytesize
+      def capacity = @native.capacity
+
+      def reserve(additional)
+        additional = Integer(additional)
+        raise ArgumentError, "additional must be non-negative" if additional.negative?
+        raise RangeError, "buffer preallocation exceeds 100 MiB" if additional > MAX_PREALLOCATE_BYTES
+        @native.reserve(additional)
+        self
+      end
+
+      def clear = (@native.clear; self)
+      def initialize_copy(*) = raise(TypeError, "QuestDB buffers cannot be copied")
+
+      protected
+
+      attr_reader :native
+
+      private
+
+      def initialize_native(native)
+        @native = native
+      end
+
+      # Positional internal entry point avoids constructing a second keyword
+      # Hash when Sender delegates its ergonomic keyword API to the buffer.
+      def append(table, symbols, columns, at)
+        raise TypeError, "symbols must be a Hash" unless symbols.is_a?(Hash)
+        raise TypeError, "columns must be a Hash" unless columns.is_a?(Hash)
+        return false unless hash_has_value?(symbols) || hash_has_value?(columns)
+        @native.append_row(table, symbols, columns, normalize_at(at))
+      rescue EncodingError => error
+        raise IngressError.new(error.message, code: :invalid_utf8), cause: error
+      end
+
+      def hash_has_value?(hash)
+        hash.each_value { |value| return true unless value.nil? }
+        false
+      end
+
+      def normalize_at(value)
+        case value
+        when TimestampNanos, TimestampMicros, Time then value
+        else
+          return value if value.equal?(SERVER_TIMESTAMP)
+          raise IngressError.new("at must be TimestampNanos, TimestampMicros, Time, or SERVER_TIMESTAMP", code: :invalid_timestamp)
+        end
+      end
+    end
+  end
+end

data/lib/questdb/ingress/error.rb

@@ -0,0 +1,43 @@
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+module QuestDB
+  module Ingress
+    class IngressError < StandardError
+      attr_reader :code, :sender_error
+
+      def initialize(message, code: :invalid_api_call, in_doubt: false, sender_error: nil)
+        @code = code.to_sym
+        @in_doubt = !!in_doubt
+        @sender_error = if sender_error.is_a?(Array) && defined?(QuestDB::SenderError)
+                          QuestDB::SenderError.from_native(sender_error)
+                        else
+                          sender_error
+                        end
+        super(message)
+      end
+
+      def in_doubt? = @in_doubt
+    end
+
+    class ServerRejectionError < IngressError; end
+  end
+end