virgodb 0.1.0.dev.e373706-x86_64-linux-gnu → 0.1.1-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a75e70c710d3b2e1111368b0297640676376092f19e98fd6d69500bc5b715467
-  data.tar.gz: c71c7fdcba8387ccbbb0822cf3ba942cd2c8c4424c495fd1ee45932743342f06
+  metadata.gz: 4aad06a98bee583d89ff9cdc8cd0790caaa3d88f8168ebbecaf8808563797c50
+  data.tar.gz: 696c058c6f8fda74c10c7ad6bdbc8a9060fa230c430683d2ec7ce10ca243dd9f
 SHA512:
-  metadata.gz: 219e45185206a02d2b2720684de63b2a182cd1084090ad0a372c817c2b2a881c776c45c8d129edfcde503f071df096283c64856d08b7b7921dd0fae837d5d53f
-  data.tar.gz: eb881c951a994a503c3caa6a39a61dfea5bde6095f5313ef45f05b8a1a114236e307e50819a6e461db28b7c97ef97ea13fa2c222172c7d16c1ff924a5a61a889
+  metadata.gz: 2927c20cdfa1f9d5aa21e0dacf33d1db31df24347dd6296604c28d8f611c110944a53bc8bd3be479d7481773fa6a283372d9d5b910da6146b75d228860c16dcd
+  data.tar.gz: bbfa4a4bac7c6ad8f0b9b4cf0a6a661df1643e96ebc44c91fd8d9c5cf98366391c5f5be1f0d3ea1e2ef98cd26701162ec3cf4b2cd2293d7b92f53256a1078dcd

data/lib/virgodb/rows.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Virgodb
+  # Wraps virgodb's JSON rows (Array of string-keyed Hash) in a real Struct
+  # so callers can use either dot access (row.current_path) or bracket
+  # access (row["total_clicks"]). Struct instead of OpenStruct: shared
+  # method dispatch across instances, not one dynamically-defined accessor
+  # set per object.
+  module Rows
+    module_function
+
+    # The Struct CLASS is memoized by field-name shape, not rebuilt per row
+    # or per request -- a real caller only ever produces a small closed set
+    # of shapes (one per distinct SELECT alias list), so the cache
+    # converges to a couple dozen entries for the app's lifetime. Building
+    # a fresh anonymous Struct per row would pollute the method cache and
+    # grow the global class table.
+    #
+    # `fields` MUST be the caller's own known SELECT column list (its
+    # outer query's alias names, in order) -- NOT inferred from the actual
+    # JSON rows. virgodb's JSON serialization OMITS a key entirely when
+    # that row's value for it is NULL (e.g. sumIf(revenue, ...) on a path
+    # with zero conversions), rather than emitting `"total_revenue": null`.
+    # Deriving the shape from the union of every row's own keys would miss
+    # a column that's NULL across every row in a batch (e.g. a
+    # page-filtered query narrowed to a path with zero conversions) --
+    # only the caller's own SQL genuinely knows the full column list
+    # regardless of what any individual result happens to contain.
+    #
+    # `Struct#new(keyword_init: true)` already defaults any key ABSENT
+    # from a given row's hash to nil on its own, so a plain
+    # `row[field.to_s]` lookup (not a keys-actually-present transform)
+    # handles the all-NULL-column case correctly.
+    STRUCT_CACHE = {}
+    STRUCT_CACHE_MUTEX = Mutex.new
+    private_constant :STRUCT_CACHE, :STRUCT_CACHE_MUTEX
+
+    def to_structs(rows, fields)
+      klass = STRUCT_CACHE[fields] ||
+        STRUCT_CACHE_MUTEX.synchronize { STRUCT_CACHE[fields] ||= Struct.new(*fields, keyword_init: true) }
+
+      rows.map { |row| klass.new(**fields.to_h { |f| [ f, row[f.to_s] ] }) }
+    end
+  end
+end

data/lib/virgodb/table.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Virgodb
+  # A memoized Writer + its maintenance thread, both created lazily on first
+  # use -- not eagerly at process boot, since Writer.new and
+  # Virgodb.start_maintenance both raise if this table hasn't been migrated
+  # yet, and eager init would crash the whole process on that instead of
+  # just failing the first write attempt. Mutex-guarded so concurrent
+  # callers in one process can't race to double-initialize.
+  #
+  # This is the boilerplate every host app embedding virgodb needs around
+  # the raw Writer/start_maintenance/query FFI -- written once here instead
+  # of once per host app. Deliberately does NOT rescue write failures: a
+  # host app's own error-handling policy (swallow-and-log vs. raise, retry,
+  # ...) belongs to the host app, not this class -- a caller-side wrapper
+  # exposing both a safe and a raising write method is one reasonable
+  # shape for that policy.
+  class Table
+    def initialize(manifest_path:, data_dir:, sql_table_name:, key_column:, sort_by:, partition_column:, tier1_max_rows:, tier1_max_age_secs:, tuning:)
+      @manifest_path = manifest_path
+      @data_dir = data_dir
+      @sql_table_name = sql_table_name
+      @key_column = key_column
+      @sort_by = sort_by
+      @partition_column = partition_column
+      @tier1_max_rows = tier1_max_rows
+      @tier1_max_age_secs = tier1_max_age_secs
+      @tuning = tuning
+      @mutex = Mutex.new
+      @maintenance_started = false
+    end
+
+    attr_reader :manifest_path
+
+    def write_row(**attrs)
+      writer.write_row(**attrs)
+    end
+
+    # `tombstone` alone doesn't touch the Writer -- calling `writer` first
+    # ensures this table's maintenance thread (and therefore its physical
+    # tombstone-purge path) is actually running before a tombstone gets
+    # recorded for it to eventually act on.
+    def tombstone(column:, value:)
+      writer
+      Virgodb.tombstone(@manifest_path, @sql_table_name, column.to_s, value.to_s)
+    end
+
+    # Returns parsed JSON rows (Array of String-keyed Hash). `sql` must
+    # refer to the table by its real SQL name (the `sql_table_name` this
+    # instance was built with), not any shorthand a caller's own registry
+    # might use for it.
+    def query(sql, partition_keys: nil)
+      JSON.parse(Virgodb.query(@manifest_path, @sql_table_name, sql, partition_keys))
+    end
+
+    def flush!
+      writer.flush!
+    end
+
+    private
+
+    def writer
+      @writer || @mutex.synchronize { @writer ||= build_writer }
+    end
+
+    def build_writer
+      ensure_maintenance_started
+      Virgodb::Writer.new(@manifest_path, @sql_table_name, @tier1_max_rows, @tier1_max_age_secs)
+    end
+
+    def ensure_maintenance_started
+      return if @maintenance_started
+
+      FileUtils.mkdir_p(@data_dir)
+      Virgodb.start_maintenance(@manifest_path, @sql_table_name, @data_dir, @key_column, @sort_by, @tuning, @partition_column)
+      @maintenance_started = true
+    end
+  end
+end

data/lib/virgodb/time_helpers.rb

@@ -0,0 +1,45 @@
+require "time"
+
+module Virgodb
+  # Helpers matching virgodb's own wire format, not any host app's business
+  # logic -- every embedding app needs the exact same code, so it lives here
+  # once instead of being independently reimplemented (and independently
+  # mis-implemented) per host app.
+  module TimeHelpers
+    module_function
+
+    # `Virgodb.query` serializes Timestamp columns as zone-less ISO 8601
+    # strings (arrow-json, not raw epoch integers) -- any caller reading one
+    # back and needing epoch seconds again MUST parse it as UTC explicitly.
+    # A bare `Time.parse` interprets a zone-less string in the system's
+    # LOCAL timezone: on a non-UTC dev box, that silently shifts a written
+    # epoch by the local UTC offset on read-back (a real bug, caught by a
+    # host app running this on a non-UTC dev box before it shipped).
+    # Appending "Z" is what forces UTC interpretation -- verified directly
+    # under a non-UTC TZ before this shipped, same discipline as the bug
+    # this replaces. No ActiveSupport dependency (this gem doesn't require
+    # Rails): `Time.find_zone` isn't plain Ruby, this stdlib `time`-library
+    # trick is.
+    def parse_time(value)
+      return nil if value.nil? || value.empty?
+      Time.parse("#{value}Z").to_i
+    end
+
+    # ClickHouse's `toYYYYMM(time)`-equivalent: the month bucket (e.g.
+    # "202607") `time` falls in, matching exactly what
+    # crates/ingest::month_partition_key_from_timestamp writes into
+    # run_files.partition_key -- pure local computation, no DB round trip.
+    def month_partition_key(time)
+      time.strftime("%Y%m")
+    end
+
+    # A real time RANGE (e.g. a narrow lookup window) can straddle a month
+    # boundary even though any single instant can't -- every distinct month
+    # bucket `range` touches, so a range-bounded query can pass this
+    # straight to a table's partition-key pruning without silently missing
+    # a row that landed just across the boundary.
+    def month_partition_keys_for(range)
+      [ month_partition_key(range.begin), month_partition_key(range.end) ].uniq
+    end
+  end
+end

data/lib/virgodb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Virgodb
-  VERSION = "0.1.0.dev.e373706"
+  VERSION = "0.1.1"
 end

data/lib/virgodb.rb

@@ -2,3 +2,6 @@
 
 require "virgodb/version"
 require "virgodb/virgodb_ruby"
+require "virgodb/time_helpers"
+require "virgodb/rows"
+require "virgodb/table"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: virgodb
 version: !ruby/object:Gem::Version
-  version: 0.1.0.dev.e373706
+  version: 0.1.1
 platform: x86_64-linux-gnu
 authors:
 - virgodb
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   Embeds virgodb (an OLAP engine backed by Parquet + DataFusion) directly into a Ruby process
@@ -21,6 +21,9 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - lib/virgodb.rb
+- lib/virgodb/rows.rb
+- lib/virgodb/table.rb
+- lib/virgodb/time_helpers.rb
 - lib/virgodb/version.rb
 - lib/virgodb/virgodb_ruby.so
 homepage: