questdb 0.1.0-aarch64-linux-gnu

data/examples/callbacks.rb

@@ -0,0 +1,46 @@
+# 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 "questdb"
+
+client = nil
+client = QuestDB.connect(
+  ENV.fetch("QDB_CLIENT_CONF", "ws::addr=localhost:9000;"),
+  connection_listener: lambda { |event|
+    warn "connection=#{event.kind} endpoint=#{event.host}:#{event.port}"
+  },
+  error_handler: lambda { |error|
+    warn "rejection=#{error.category} policy=#{error.applied_policy} fsn=#{error.from_fsn}-#{error.to_fsn}: #{error.message}"
+  }
+)
+
+begin
+  client.sender do |sender|
+    sender.row("ruby_callback_example", columns: { value: 1 }, at: QuestDB::SERVER_TIMESTAMP)
+    sender.flush(wait: true)
+  end
+ensure
+  # A handler closure that captures client keeps it alive; always close explicitly.
+  client.close
+end

data/examples/columnar.rb

@@ -0,0 +1,41 @@
+# 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 "questdb"
+
+conf = ENV.fetch("QDB_CLIENT_CONF", "ws::addr=localhost:9000;")
+QuestDB.connect(conf) do |client|
+  now = QuestDB::TimestampNanos.now.value
+  client.ingest_columns(
+    "ruby_columnar_example",
+    columns: {
+      price: [2615.54, 2616.10, nil],
+      quantity: QuestDB::ColumnVector.int([3, 5, 8]),
+      venue_code: QuestDB::ColumnVector.varchar(["LDN", "NYC", "SGP"])
+    },
+    symbols: { symbol: ["ETH-USD", "BTC-USD", "ETH-USD"] },
+    at: 3.times.map { |index| QuestDB::TimestampNanos.new(now + index) },
+    max_rows_per_batch: 16_384,
+    ack: :ok
+  )
+end

data/examples/independent_buffer.rb

@@ -0,0 +1,39 @@
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   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 "questdb"
+
+QuestDB.connect("ws::addr=localhost:9000;sender_pool_max=4;") do |client|
+  workers = 2.times.map do |index|
+    Thread.new do
+      client.sender do |sender|
+        100.times do |row|
+          sender.row("parallel_metrics",
+                     symbols: { worker: index.to_s },
+                     columns: { value: row },
+                     at: QuestDB::TimestampNanos.now)
+        end
+        sender.flush(wait: true)
+      end
+    end
+  end
+  workers.each(&:join)
+end

data/examples/query.rb

@@ -0,0 +1,28 @@
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   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 "questdb"
+
+QuestDB.connect(ENV.fetch("QDB_CLIENT_CONF", "ws::addr=localhost:9000;")) do |client|
+  client.query("SELECT table_name FROM tables() LIMIT $1", binds: [10]) do |result|
+    result.each { |row| puts row["table_name"] }
+  end
+end

data/examples/standalone.rb

@@ -0,0 +1,33 @@
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   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 "questdb"
+
+conf = ENV.fetch("QDB_CLIENT_CONF", "ws::addr=localhost:9000;auto_flush=off;")
+QuestDB::Sender.from_conf(conf).open do |sender|
+  sender.row(
+    "ruby_standalone_example",
+    symbols: { source: "ruby" },
+    columns: { value: 42 },
+    at: QuestDB::TimestampNanos.now
+  )
+  sender.flush(wait: true)
+end

data/examples/tls_auth.rb

@@ -0,0 +1,33 @@
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   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 "questdb"
+
+conf = "wss::addr=#{ENV.fetch('QDB_HOST')}:#{ENV.fetch('QDB_PORT', '9000')};" \
+       "token=#{ENV.fetch('QDB_TOKEN')};" \
+       "tls_roots=#{ENV.fetch('QDB_TLS_ROOTS')};"
+
+QuestDB.connect(conf) do |client|
+  client.sender do |sender|
+    sender.row("secure_metrics", columns: { value: 1 }, at: QuestDB::TimestampNanos.now)
+    sender.flush(wait: true)
+  end
+end

data/lib/questdb/arrow.rb

@@ -0,0 +1,250 @@
+# 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 "questdb"
+
+module QuestDB
+  # Optional Apache Arrow C Stream interoperability. Requiring this file adds
+  # adapters without loading red-arrow, nanoarrow, or polars-df.
+  module Arrow
+    ACK_LEVELS = { ok: 0, durable: 1 }.freeze
+    OVERRIDE_KINDS = {
+      symbol: 0,
+      ipv4: 1,
+      char: 2,
+      geohash: 3,
+      varchar: 4
+    }.freeze
+    private_constant :ACK_LEVELS, :OVERRIDE_KINDS
+
+    class PointerCapsule
+      attr_reader :name
+
+      def initialize(pointer, name: "arrow_array_stream")
+        @pointer = Integer(pointer)
+        @name = name.freeze
+      end
+
+      def to_i = @pointer
+    end
+    private_constant :PointerCapsule
+
+    module_function
+
+    def with_stream(source)
+      if source.respond_to?(:arrow_c_stream)
+        capsule = source.arrow_c_stream
+        validate_capsule!(capsule)
+        return yield capsule
+      end
+
+      reader = red_arrow_reader(source)
+      unless reader
+        raise TypeError,
+              "Arrow source must respond to #arrow_c_stream or be an Arrow::Table, Arrow::RecordBatch, or Arrow::RecordBatchReader"
+      end
+
+      pointer = reader.export
+      capsule = PointerCapsule.new(pointer)
+      begin
+        yield capsule
+      ensure
+        # Red Arrow allocates only the ArrowArrayStream struct shell here.
+        # Native ingestion consumes/releases its contents; the shell remains
+        # the exporter's responsibility.
+        GLib.free(pointer)
+      end
+    end
+
+    def validate_capsule!(capsule)
+      raise TypeError, "arrow_c_stream must return an object responding to #to_i" unless capsule.respond_to?(:to_i)
+      if capsule.respond_to?(:name) && capsule.name != "arrow_array_stream"
+        raise TypeError, "arrow_c_stream returned #{capsule.name.inspect}, expected \"arrow_array_stream\""
+      end
+      capsule
+    end
+
+    def red_arrow_reader(source)
+      return nil unless defined?(::Arrow::RecordBatchReader)
+      return source if source.is_a?(::Arrow::RecordBatchReader)
+      if defined?(::Arrow::Table) && source.is_a?(::Arrow::Table)
+        return ::Arrow::TableBatchReader.new(source)
+      end
+      if defined?(::Arrow::RecordBatch) && source.is_a?(::Arrow::RecordBatch)
+        return ::Arrow::RecordBatchReader.new([source])
+      end
+      nil
+    end
+
+    def normalize_ack(value)
+      value = value.to_sym if value.respond_to?(:to_sym)
+      ACK_LEVELS.fetch(value) { raise ArgumentError, "ack must be :ok or :durable" }
+    end
+
+    def normalize_at(value)
+      case value
+      when String, Symbol
+        [2, value]
+      when TimestampNanos
+        [1, non_negative_i64(value.value, "designated timestamp")]
+      when TimestampMicros
+        [1, non_negative_i64(value.value * 1_000, "designated timestamp")]
+      when Time
+        [1, non_negative_i64(value.to_i * 1_000_000_000 + value.nsec, "designated timestamp")]
+      else
+        return [0, nil] if value.equal?(SERVER_TIMESTAMP)
+        raise TypeError, "at must be a timestamp column name, TimestampNanos, TimestampMicros, Time, or SERVER_TIMESTAMP"
+      end
+    end
+
+    def normalize_overrides(symbols, overrides)
+      raise TypeError, "schema_overrides must be a Hash" unless overrides.is_a?(Hash)
+      descriptors = {}
+      case symbols
+      when :auto, nil
+      when Array
+        symbols.each { |name| descriptors[name.to_s] = [name, OVERRIDE_KINDS[:symbol], 0] }
+      else
+        raise ArgumentError, "symbols must be :auto or an Array of column names"
+      end
+
+      overrides.each do |name, specification|
+        kind, argument = if specification.is_a?(Array)
+                           raise ArgumentError, "override arrays must contain [kind, argument]" unless specification.length == 2
+                           specification
+                         else
+                           [specification, 0]
+                         end
+        kind = kind.to_sym if kind.respond_to?(:to_sym)
+        code = OVERRIDE_KINDS.fetch(kind) do
+          raise ArgumentError, "unsupported Arrow schema override #{kind.inspect}"
+        end
+        argument = Integer(argument)
+        if kind == :geohash
+          raise RangeError, "geohash precision must be between 1 and 60 bits" unless argument.between?(1, 60)
+        elsif argument != 0
+          raise ArgumentError, "only a geohash override accepts an argument"
+        end
+        key = name.to_s
+        raise ArgumentError, "duplicate Arrow override for #{key.inspect}" if descriptors.key?(key)
+        descriptors[key] = [name, code, argument]
+      end
+      descriptors.values.freeze
+    end
+
+    def non_negative_i64(value, label)
+      value = Integer(value)
+      raise RangeError, "#{label} cannot be before the Unix epoch" if value.negative?
+      raise RangeError, "#{label} is outside signed 64-bit range" if value > (1 << 63) - 1
+      value
+    end
+  end
+
+  class Client
+    def ingest_arrow(table, source, at:, symbols: :auto, schema_overrides: {}, ack: :ok,
+                     checkpoint_batches: 100)
+      at_kind, at_value = Arrow.normalize_at(at)
+      overrides = Arrow.normalize_overrides(symbols, schema_overrides)
+      ack_level = Arrow.normalize_ack(ack)
+      checkpoint_batches = Integer(checkpoint_batches)
+      raise ArgumentError, "checkpoint_batches must be positive" unless checkpoint_batches.positive?
+      @mutex.synchronize { ensure_open! }
+      Arrow.with_stream(source) do |capsule|
+        @native.ingest_arrow(
+          capsule, table, at_kind, at_value, overrides, ack_level, checkpoint_batches
+        )
+      end
+      self
+    end
+  end
+
+  class PooledSender
+    def ingest_arrow(table, source, at:, symbols: :auto, schema_overrides: {}, ack: :ok,
+                     checkpoint_batches: 100)
+      ensure_open!
+      @client.ingest_arrow(
+        table, source, at: at, symbols: symbols,
+        schema_overrides: schema_overrides, ack: ack,
+        checkpoint_batches: checkpoint_batches
+      )
+      self
+    end
+  end
+
+  class Sender
+    def ingest_arrow(table, source, at:, symbols: :auto, schema_overrides: {}, ack: :ok,
+                     checkpoint_batches: 100)
+      at_kind, at_value = Arrow.normalize_at(at)
+      overrides = Arrow.normalize_overrides(symbols, schema_overrides)
+      ack_level = Arrow.normalize_ack(ack)
+      checkpoint_batches = Integer(checkpoint_batches)
+      raise ArgumentError, "checkpoint_batches must be positive" unless checkpoint_batches.positive?
+      ensure_ws!
+      Arrow.with_stream(source) do |capsule|
+        @native.ingest_arrow(
+          @configuration, capsule, table, at_kind, at_value,
+          overrides, ack_level, checkpoint_batches
+        )
+      end
+      self
+    end
+  end
+
+  class QueryResult
+    # Return a one-shot Arrow C Stream capsule. The native query is fully
+    # materialized into Arrow-owned batches before this method returns, then
+    # the reader lease is closed. Consumers may retain the capsule independently.
+    def arrow_c_stream
+      start_consumption!
+      capsule = nil
+      begin
+        capsule = @native.materialize_arrow_stream
+      ensure
+        close_preserving_primary_error
+      end
+      capsule
+    end
+
+    def to_nanoarrow
+      require "nanoarrow"
+      Nanoarrow::Array.new(self)
+    end
+
+    def to_polars
+      require "polars-df"
+      Polars::DataFrame.new(self)
+    end
+
+    def to_red_arrow_table
+      require "arrow"
+      capsule = arrow_c_stream
+      reader = ::Arrow::RecordBatchReader.import(capsule.to_i)
+      begin
+        reader.read_all
+      ensure
+        reader.unref
+      end
+    end
+  end
+end