altertable-lakehouse 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f2f1d437eff964062288c5b189001c85a1954e7b95e1a91646f792d6886d0d1
-  data.tar.gz: 68037c1a228479878bb023f0532b4f91e8f005a065ac8473c42d62ba3ce4f8f5
+  metadata.gz: d635646f7f35014bb92fadccf1f9366de1881a9b8340a785f2acfe767073ccd1
+  data.tar.gz: ec0735c51c64be58de7e18720e8b97113287324f47317afd34ba5af2193d5439
 SHA512:
-  metadata.gz: 48c13e24a29727a0dd957053558b7e47d74eefcd651fe12a8b81c8cd912073c75c7f42c00c1a29d8e7ed231665541ea602ff2cb9a86affef3b40825d775d0f91
-  data.tar.gz: 3f3f3e6b41468ed309266855c88f60e729022dbd2bb638c8c9c88b8f7baf861dc84b3fdd886dd8a098b3000d9cb339d1ffd9c8cec7fe82103da52a3fedc496fd
+  metadata.gz: 41343b469a2ccc2b24baa8342ae06ae51160c91470e7946e3e54fd931f9b504a5724be67c30a11da27d81f64dff5c9754ac0f5033ca0ba2a9db1b0bac5c82def
+  data.tar.gz: 3e4657c5f172e33d5e2c2e1b67fec4fd04d68ec3f415c6589d63b10d542ee294759eaf3f3a5067414acb58a91ce47cc39c7687a8321747badd4111f634ac5550

data/.github/workflows/ci.yml

@@ -3,9 +3,7 @@ name: CI
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
-
+  pull_request: {}
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -52,3 +50,18 @@ jobs:
           bundler-cache: true
       - name: Run RuboCop
         run: bundle exec rubocop
+
+  typing:
+    name: "Typing"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Validate RBS
+        run: bundle exec rbs validate
+      - name: Typecheck with Sorbet
+        run: bundle exec srb tc

data/.github/workflows/semantic-pull-request.yml

@@ -0,0 +1,29 @@
+name: Semantic Pull Request
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            style
+            chore
+            refactor
+            test
+            build
+            ci

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "0.3.0"
+    ".": "0.4.0"
 }

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.3.0...altertable-lakehouse/v0.4.0) (2026-05-27)
+
+
+### Features
+
+* add v0.11.0 lakehouse operations ([#27](https://github.com/altertable-ai/altertable-lakehouse-ruby/issues/27)) ([cc52dbb](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/cc52dbb4ef995b027697f6fa68164f6704e02058))
+* **explain:** add /explain support ([#31](https://github.com/altertable-ai/altertable-lakehouse-ruby/issues/31)) ([b326e94](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/b326e949742f9f4c89e5ea2aeb67028513e8a118))
+* **typings:** add RBI & RBS typings ([#29](https://github.com/altertable-ai/altertable-lakehouse-ruby/issues/29)) ([c569e6d](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/c569e6d58c1c36af2f51a329591eebd2e0677d17))
+
 ## [0.3.0](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse-v0.2.0...altertable-lakehouse/v0.3.0) (2026-03-08)
 
 

data/Gemfile

@@ -5,3 +5,5 @@ gemspec
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 gem "faraday-net_http"
+
+gem "tapioca", require: false, group: %i[development test]

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    altertable-lakehouse (0.3.0)
+    altertable-lakehouse (0.4.0)
       base64
 
 GEM
@@ -11,11 +11,13 @@ GEM
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
+    benchmark (0.5.0)
     bigdecimal (4.0.1)
     diff-lcs (1.6.2)
     docker-api (2.4.0)
       excon (>= 0.64.0)
       multi_json
+    erubi (1.13.1)
     excon (1.4.0)
       logger
     faraday (2.14.1)
@@ -41,6 +43,7 @@ GEM
     multi_json (1.19.1)
     net-http (0.9.1)
       uri (>= 0.11.1)
+    netrc (0.11.0)
     parallel (1.27.0)
     parser (3.3.10.2)
       ast (~> 2.4.1)
@@ -50,7 +53,16 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
+    rbi (0.3.9)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
     regexp_parser (2.11.3)
+    require-hooks (0.2.2)
+    rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -80,18 +92,49 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
+    sorbet (0.6.12997)
+      sorbet-static (= 0.6.12997)
+    sorbet-runtime (0.6.12997)
+    sorbet-static (0.6.12997-universal-darwin)
+    sorbet-static-and-runtime (0.6.12997)
+      sorbet (= 0.6.12997)
+      sorbet-runtime (= 0.6.12997)
+    spoom (1.7.8)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.3.3)
+      rbs (>= 4.0.0.dev.4)
+      rexml (>= 3.2.6)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.17.7)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (>= 0.3.1)
+      require-hooks (>= 0.2.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.7.0)
+      thor (>= 1.2.0)
+      yard-sorbet
     testcontainers (0.2.0)
       testcontainers-core (= 0.2.0)
     testcontainers-core (0.2.0)
       docker-api (~> 2.2)
+    thor (1.5.0)
+    tsort (0.2.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri (1.1.1)
+    yard (0.9.43)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
 
 PLATFORMS
   arm64-darwin-25
-  ruby
   x86_64-linux
 
 DEPENDENCIES
@@ -101,8 +144,12 @@ DEPENDENCIES
   faraday-retry (~> 2.0)
   httpx
   rake (~> 13.0)
+  rbs
   rspec (~> 3.0)
   rubocop (~> 1.50)
+  sorbet
+  sorbet-runtime
+  tapioca
   testcontainers
 
 BUNDLED WITH

data/README.md

@@ -34,7 +34,8 @@ client.append(
   catalog: "main",
   schema: "public",
   table: "events",
-  payload: { user_id: 123, event: "signup", timestamp: Time.now.iso8601 }
+  payload: { user_id: 123, event: "signup", timestamp: Time.now.iso8601 },
+  sync: true
 )
 
 # Query data
@@ -94,15 +95,19 @@ client.append(
   ]
 )
 
-# Override credentials per-request
-client.append(
+# Asynchronous append with task polling
+resp = client.append(
   catalog: "main",
   schema: "public",
   table: "events",
   payload: { user_id: 789 },
-  username: "other_user",
-  password: "other_password"
+  sync: false
 )
+
+if resp.task_id
+  task = client.get_task(resp.task_id)
+  puts task.status
+end
 ```
 
 ### `query_all`
@@ -111,7 +116,8 @@ Executes a SQL query and returns all rows in memory (accumulated).
 
 ```ruby
 result = client.query_all(
-  statement: "SELECT * FROM main.public.events LIMIT 10"
+  statement: "SELECT * FROM main.public.events LIMIT 10",
+  cache: true
 )
 
 puts result[:metadata] # Hash
@@ -180,6 +186,45 @@ puts resp.valid # => false
 puts resp.error
 ```
 
+### `get_task`
+
+Retrieves the status of an asynchronous append task.
+
+```ruby
+task = client.get_task("task-uuid")
+puts task.status # "pending" or "completed"
+```
+
+### `explain`
+
+Returns scan estimates for a SQL statement without executing it.
+
+```ruby
+resp = client.explain(
+  statement: "SELECT * FROM users WHERE age > 25",
+  include_plan: true
+)
+
+resp.tables.each do |table|
+  puts "#{table.table_name}: ~#{table.estimated_rows} rows"
+end
+```
+
+### `autocomplete`
+
+Returns SQL autocomplete suggestions.
+
+```ruby
+resp = client.autocomplete(
+  statement: "SEL",
+  max_suggestions: 5
+)
+
+resp.suggestions.each do |suggestion|
+  puts suggestion.suggestion
+end
+```
+
 ## Configuration
 
 | Option | Type | Default | Description |

data/altertable-lakehouse.gemspec

@@ -0,0 +1,41 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "altertable/lakehouse/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "altertable-lakehouse"
+  spec.version = Altertable::Lakehouse::VERSION
+  spec.authors = ["Altertable AI"]
+  spec.email = ["support@altertable.ai"]
+
+  spec.summary = "Official Ruby client for Altertable Lakehouse"
+  spec.description = "Official Ruby client for Altertable Lakehouse API."
+  spec.homepage = "https://github.com/altertable-ai/altertable-lakehouse-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/altertable-ai/altertable-lakehouse-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/altertable-ai/altertable-lakehouse-ruby/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|sorbet)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base64"
+
+  spec.add_development_dependency "faraday", "~> 2.12"
+  spec.add_development_dependency "faraday-retry", "~> 2.0"
+  spec.add_development_dependency "faraday-net_http"
+  spec.add_development_dependency "httpx" # For testing optional support
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "testcontainers"
+  spec.add_development_dependency "rbs"
+  spec.add_development_dependency "sorbet"
+  spec.add_development_dependency "sorbet-runtime"
+end

data/lib/altertable/lakehouse/client.rb

@@ -43,13 +43,20 @@ module Altertable
       end
 
       # POST /append
-      def append(catalog:, schema:, table:, payload:)
+      def append(catalog:, schema:, table:, payload:, sync: nil)
         params = { catalog: catalog, schema: schema, table: table }
+        params[:sync] = sync unless sync.nil?
         req = Models::AppendRequest.new(payload)
         resp = request(:post, "/append", body: req.to_h, query: params)
         Models::AppendResponse.from_h(resp)
       end
 
+      # GET /tasks/:task_id
+      def get_task(task_id)
+        resp = request(:get, "/tasks/#{task_id}")
+        Models::TaskResponse.from_h(resp)
+      end
+
       # POST /query (streamed)
       def query(statement:, **options)
         req_body = Models::QueryRequest.new(statement: statement, **options).to_h.to_json
@@ -109,12 +116,43 @@ module Altertable
       end
 
       # POST /validate
-      def validate(statement:)
-        req = Models::ValidateRequest.new(statement: statement)
+      def validate(statement:, catalog: nil, schema: nil, session_id: nil)
+        req = Models::ValidateRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id
+        )
         resp = request(:post, "/validate", body: req.to_h)
         Models::ValidateResponse.from_h(resp)
       end
 
+      # POST /autocomplete
+      def autocomplete(statement:, catalog: nil, schema: nil, session_id: nil, max_suggestions: nil)
+        req = Models::AutocompleteRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id,
+          max_suggestions: max_suggestions
+        )
+        resp = request(:post, "/autocomplete", body: req.to_h)
+        Models::AutocompleteResponse.from_h(resp)
+      end
+
+      # POST /explain
+      def explain(statement:, catalog: nil, schema: nil, session_id: nil, include_plan: nil)
+        req = Models::ExplainRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id,
+          include_plan: include_plan
+        )
+        resp = request(:post, "/explain", body: req.to_h)
+        Models::ExplainResponse.from_h(resp)
+      end
+
       private
 
       def select_adapter(name, options)

data/lib/altertable/lakehouse/models.rb

@@ -21,22 +21,42 @@ module Altertable
       end
 
       class AppendResponse < Request
-        attr_reader :ok, :error_code
+        attr_reader :ok, :error_code, :error_message, :task_id
 
-        def initialize(ok:, error_code: nil)
+        def initialize(ok:, error_code: nil, error_message: nil, task_id: nil)
           @ok = ok
           @error_code = error_code
+          @error_message = error_message
+          @task_id = task_id
         end
 
         def self.from_h(h)
-          new(ok: h["ok"], error_code: h["error_code"])
+          new(
+            ok: h["ok"],
+            error_code: h["error_code"],
+            error_message: h["error_message"],
+            task_id: h["task_id"]
+          )
+        end
+      end
+
+      class TaskResponse < Request
+        attr_reader :task_id, :status
+
+        def initialize(task_id:, status:)
+          @task_id = task_id
+          @status = status
+        end
+
+        def self.from_h(h)
+          new(task_id: h["task_id"], status: h["status"])
         end
       end
 
       class QueryRequest < Request
-        attr_reader :statement, :catalog, :schema, :session_id, :compute_size, :sanitize, :limit, :offset, :timezone, :ephemeral, :visible, :requested_by, :query_id
+        attr_reader :statement, :catalog, :schema, :session_id, :compute_size, :sanitize, :limit, :offset, :timezone, :ephemeral, :visible, :requested_by, :query_id, :cache
 
-        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)
+        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)
           @statement = statement
           @catalog = catalog
           @schema = schema
@@ -50,6 +70,7 @@ module Altertable
           @visible = visible
           @requested_by = requested_by
           @query_id = query_id
+          @cache = cache
         end
 
         def to_h
@@ -66,19 +87,27 @@ module Altertable
           h[:visible] = @visible unless @visible.nil?
           h[:requested_by] = @requested_by if @requested_by
           h[:query_id] = @query_id if @query_id
+          h[:cache] = @cache unless @cache.nil?
           h
         end
       end
 
       class ValidateRequest < Request
-        attr_reader :statement
+        attr_reader :statement, :catalog, :schema, :session_id
 
-        def initialize(statement:)
+        def initialize(statement:, catalog: nil, schema: nil, session_id: nil)
           @statement = statement
+          @catalog = catalog
+          @schema = schema
+          @session_id = session_id
         end
 
         def to_h
-          { statement: @statement }
+          h = { statement: @statement }
+          h[:catalog] = @catalog if @catalog
+          h[:schema] = @schema if @schema
+          h[:session_id] = @session_id if @session_id
+          h
         end
       end
 
@@ -152,6 +181,149 @@ module Altertable
           new(cancelled: h["cancelled"], message: h["message"])
         end
       end
+
+      class AutocompleteRequest < Request
+        attr_reader :statement, :catalog, :schema, :session_id, :max_suggestions
+
+        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, max_suggestions: nil)
+          @statement = statement
+          @catalog = catalog
+          @schema = schema
+          @session_id = session_id
+          @max_suggestions = max_suggestions
+        end
+
+        def to_h
+          h = { statement: @statement }
+          h[:catalog] = @catalog if @catalog
+          h[:schema] = @schema if @schema
+          h[:session_id] = @session_id if @session_id
+          h[:max_suggestions] = @max_suggestions if @max_suggestions
+          h
+        end
+      end
+
+      class AutocompleteSuggestion < Request
+        attr_reader :suggestion, :suggestion_start, :suggestion_type, :suggestion_score, :extra_char
+
+        def initialize(suggestion:, suggestion_start:, suggestion_type:, suggestion_score:, extra_char: nil)
+          @suggestion = suggestion
+          @suggestion_start = suggestion_start
+          @suggestion_type = suggestion_type
+          @suggestion_score = suggestion_score
+          @extra_char = extra_char
+        end
+
+        def self.from_h(h)
+          new(
+            suggestion: h["suggestion"],
+            suggestion_start: h["suggestion_start"],
+            suggestion_type: h["suggestion_type"],
+            suggestion_score: h["suggestion_score"],
+            extra_char: h["extra_char"]
+          )
+        end
+      end
+
+      class AutocompleteResponse < Request
+        attr_reader :suggestions, :statement, :connections_errors
+
+        def initialize(suggestions:, statement:, connections_errors:)
+          @suggestions = suggestions
+          @statement = statement
+          @connections_errors = connections_errors
+        end
+
+        def self.from_h(h)
+          new(
+            suggestions: Array(h["suggestions"]).map { |suggestion| AutocompleteSuggestion.from_h(suggestion) },
+            statement: h["statement"],
+            connections_errors: h["connections_errors"] || {}
+          )
+        end
+      end
+
+      class ExplainRequest < Request
+        attr_reader :statement, :catalog, :schema, :session_id, :include_plan
+
+        def initialize(statement:, catalog: nil, schema: nil, session_id: nil, include_plan: nil)
+          @statement = statement
+          @catalog = catalog
+          @schema = schema
+          @session_id = session_id
+          @include_plan = include_plan
+        end
+
+        def to_h
+          h = { statement: @statement }
+          h[:catalog] = @catalog if @catalog
+          h[:schema] = @schema if @schema
+          h[:session_id] = @session_id if @session_id
+          h[:include_plan] = @include_plan unless @include_plan.nil?
+          h
+        end
+      end
+
+      class TableScanEstimate < Request
+        attr_reader :table_name, :estimated_rows, :filters, :scanned_bytes_estimate,
+                    :scanned_files_estimate, :total_bytes, :total_files
+
+        def initialize(table_name:, estimated_rows:, filters: nil, scanned_bytes_estimate: nil,
+                       scanned_files_estimate: nil, total_bytes: nil, total_files: nil)
+          @table_name = table_name
+          @estimated_rows = estimated_rows
+          @filters = filters
+          @scanned_bytes_estimate = scanned_bytes_estimate
+          @scanned_files_estimate = scanned_files_estimate
+          @total_bytes = total_bytes
+          @total_files = total_files
+        end
+
+        def self.from_h(h)
+          new(
+            table_name: h["table_name"],
+            estimated_rows: h["estimated_rows"],
+            filters: h["filters"],
+            scanned_bytes_estimate: h["scanned_bytes_estimate"],
+            scanned_files_estimate: h["scanned_files_estimate"],
+            total_bytes: h["total_bytes"],
+            total_files: h["total_files"]
+          )
+        end
+      end
+
+      class ExplainResponse < Request
+        attr_reader :tables, :statement, :connections_errors, :error, :plan,
+                    :scanned_bytes_estimate, :scanned_files_estimate, :total_bytes, :total_files
+
+        def initialize(tables:, statement:, connections_errors:, error: nil, plan: nil,
+                       scanned_bytes_estimate: nil, scanned_files_estimate: nil,
+                       total_bytes: nil, total_files: nil)
+          @tables = tables
+          @statement = statement
+          @connections_errors = connections_errors
+          @error = error
+          @plan = plan
+          @scanned_bytes_estimate = scanned_bytes_estimate
+          @scanned_files_estimate = scanned_files_estimate
+          @total_bytes = total_bytes
+          @total_files = total_files
+        end
+
+        def self.from_h(h)
+          new(
+            tables: Array(h["tables"]).map { |table| TableScanEstimate.from_h(table) },
+            statement: h["statement"],
+            connections_errors: h["connections_errors"] || {},
+            error: h["error"],
+            plan: h["plan"],
+            scanned_bytes_estimate: h["scanned_bytes_estimate"],
+            scanned_files_estimate: h["scanned_files_estimate"],
+            total_bytes: h["total_bytes"],
+            total_files: h["total_files"]
+          )
+        end
+      end
     end
   end
 end

data/lib/altertable/lakehouse/version.rb

@@ -1,5 +1,5 @@
 module Altertable
   module Lakehouse
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end