feat(query): support bind parameters

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+### Added
+
+* Support named and positional bind values through `QueryRequest#params`.
+
 ## [0.7.0](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.6.0...altertable-lakehouse/v0.7.0) (2026-08-26)
 
 

README.md

@@ -40,7 +40,8 @@ client.append(
 
 # Query data
 result = client.query_all(
-  statement: "SELECT * FROM main.public.events LIMIT 10"
+  statement: "SELECT * FROM main.public.events WHERE age >= $min_age",
+  params: { "min_age" => 25 }
 )
 result[:rows].each { |row| puts row }
 ```

lib/altertable/lakehouse/models.rb

@@ -54,9 +54,9 @@ def self.from_h(h)
       end
 
       class QueryRequest < Request
-        attr_reader :statement, :catalog, :schema, :session_id, :compute_size, :sanitize, :limit, :offset, :timezone, :ephemeral, :visible, :requested_by, :query_id, :cache
+        attr_reader :statement, :catalog, :schema, :session_id, :compute_size, :sanitize, :limit, :offset, :timezone, :ephemeral, :visible, :requested_by, :query_id, :cache, :params
 
-        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, compute_size: nil, sanitize: nil, limit: nil, offset: nil, timezone: nil, ephemeral: nil, visible: nil, requested_by: nil, query_id: nil, cache: nil)
+        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, compute_size: nil, sanitize: nil, limit: nil, offset: nil, timezone: nil, ephemeral: nil, visible: nil, requested_by: nil, query_id: nil, cache: nil, params: nil)
           @statement = statement
           @catalog = catalog
           @schema = schema
@@ -71,6 +71,7 @@ def initialize(statement:, catalog: nil, schema: nil, session_id: nil, compute_s
           @requested_by = requested_by
           @query_id = query_id
           @cache = cache
+          @params = params
         end
 
         def to_h
@@ -88,6 +89,7 @@ def to_h
           h[:requested_by] = @requested_by if @requested_by
           h[:query_id] = @query_id if @query_id
           h[:cache] = @cache unless @cache.nil?
+          h[:params] = @params unless @params.nil?
           h
         end
       end

rbi/altertable/lakehouse.rbi

@@ -300,6 +300,9 @@ module Altertable
         sig { returns(T.nilable(T::Boolean)) }
         def cache; end
 
+        sig { returns(T.nilable(T.any(T::Hash[String, T.untyped], T::Array[T.untyped]))) }
+        def params; end
+
         sig do
           params(
             statement: String,
@@ -315,10 +318,11 @@ module Altertable
             visible: T.nilable(T::Boolean),
             requested_by: T.nilable(String),
             query_id: T.nilable(String),
-            cache: T.nilable(T::Boolean)
+            cache: T.nilable(T::Boolean),
+            params: T.nilable(T.any(T::Hash[String, T.untyped], T::Array[T.untyped]))
           ).void
         end
-        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, compute_size: nil, sanitize: nil, limit: nil, offset: nil, timezone: nil, ephemeral: nil, visible: nil, requested_by: nil, query_id: nil, cache: nil); end
+        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, compute_size: nil, sanitize: nil, limit: nil, offset: nil, timezone: nil, ephemeral: nil, visible: nil, requested_by: nil, query_id: nil, cache: nil, params: nil); end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
         def to_h; end

sig/altertable/lakehouse/models.rbs

@@ -45,6 +45,7 @@ module Altertable
         attr_reader requested_by: String?
         attr_reader query_id: String?
         attr_reader cache: bool?
+        attr_reader params: (::Hash[String, untyped] | ::Array[untyped])?
 
         def initialize: (
           statement: String,
@@ -60,7 +61,8 @@ module Altertable
           ?visible: bool?,
           ?requested_by: String?,
           ?query_id: String?,
-          ?cache: bool?
+          ?cache: bool?,
+          ?params: (::Hash[String, untyped] | ::Array[untyped])?
         ) -> void
 
         def to_h: () -> ::Hash[Symbol, untyped]

spec/altertable/lakehouse_spec.rb

@@ -201,6 +201,15 @@
 
       expect(result[:rows]).to eq([{ "cached_value" => 1 }])
     end
+
+    it "serializes named bind parameters" do
+      request = Altertable::Lakehouse::Models::QueryRequest.new(
+        statement: "SELECT $min_age",
+        params: { "min_age" => 25 }
+      )
+
+      expect(request.to_h).to include(params: { "min_age" => 25 })
+    end
   end
 
   # ── custom headers ───────────────────────────────────────────────────────────