altertable-lakehouse 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dfae05324ea00439f1b6dba1529227cc10707bf59a1089b8342400f3a61407a
-  data.tar.gz: 0c336d73acd7751552a6806dba593b3c0590b19e84d999c2631c326f08385d8e
+  metadata.gz: 79141f78a6f427133d3eade8a3e78d697d7526eab2d767fbafa7d29d3d2954fb
+  data.tar.gz: 1fae0c3ce116fe23afbb8611ee272999273cd7fa5f4687cc9a4fdd32a14605f4
 SHA512:
-  metadata.gz: d7b17d9d68b20e4d6aed748ee3626fa6a89949a5e4311845f16181cfe9486ad23fdf915e21220f39b4f704122d9046102e3383fa150a958a195136016d877293
-  data.tar.gz: eddc49cf94b2d6fc1e14fb2b2326385e4c79013ab7d324eeaa9961b9732295ce492698b7b4f16ca03700a55eddf5d5c95a7a877b66ffe9b88fcb3781546ec774
+  metadata.gz: e2d5f5564023af9db4070e39af8b23f113ac8cf5b4dda09e4443e4a5cd343cefb3c26e30d5754e5576ccf72dace589a4bd412992e0b2499922f46b443ae54fd8
+  data.tar.gz: '0877c8558d85087f5678b1df8c48646b7f68684f331e649c8bd4b7d6c8b5a72657656d9e57d6eeef41c98b4e2d4d937c38953ed29f999ef2e9bf393e57f82d87'

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "0.8.0"
+    ".": "0.9.0"
 }

data/.rubocop.yml

@@ -1,7 +1,7 @@
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   Exclude:
     - 'vendor/**/*'
     - 'spec/**/*'

data/CHANGELOG.md

@@ -7,6 +7,37 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 * Support named and positional bind values through `QueryRequest#params`.
+* `ColumnDescriptor` value objects (`Data`) for query columns, with `name` and `type` readers.
+
+### Changed
+
+* Require Ruby 3.2 or newer (`ColumnDescriptor` is a `Data` class). CI already only tested 3.2+.
+
+### Fixed
+
+* `QueryResult#columns` and `query_all[:columns]` return typed column descriptors again instead of bare names; rows stay keyed by column name.
+* A malformed `/query` column line (anything other than an array of `{ "name", "type" }` string objects) now raises `ParseError` instead of passing through untyped.
+
+## [0.9.0](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.8.2...altertable-lakehouse/v0.9.0) (2026-10-12)
+
+
+### Miscellaneous Chores
+
+* release 0.9.0 ([#58](https://github.com/altertable-ai/altertable-lakehouse-ruby/issues/58)) ([55fff71](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/55fff719c9e988d07cedd1a820752001aa4b53ea))
+
+## [0.8.2](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.8.1...altertable-lakehouse/v0.8.2) (2026-10-12)
+
+
+### Bug Fixes
+
+* **query:** restore typed column descriptors ([a16ea67](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/a16ea679f581bcedf665f1f7b487601b34f66432))
+
+## [0.8.1](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.8.0...altertable-lakehouse/v0.8.1) (2026-10-07)
+
+
+### Bug Fixes
+
+* **error:** implement proper query error parsing ([#54](https://github.com/altertable-ai/altertable-lakehouse-ruby/issues/54)) ([86f6512](https://github.com/altertable-ai/altertable-lakehouse-ruby/commit/86f6512cfc6c58822981d0ac4824b7479dd1f2f4))
 
 ## [0.8.0](https://github.com/altertable-ai/altertable-lakehouse-ruby/compare/altertable-lakehouse/v0.7.0...altertable-lakehouse/v0.8.0) (2026-10-07)
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    altertable-lakehouse (0.8.0)
+    altertable-lakehouse (0.9.0)
       base64
 
 GEM

data/README.md

@@ -124,7 +124,8 @@ result = client.query_all(
 )
 
 puts result[:metadata] # Hash
-puts result[:columns]  # Array of columns
+puts result[:columns]  # Array of ColumnDescriptor (#name, #type)
+puts result[:columns].first.type # e.g. "INTEGER"
 result[:rows].each do |row|
   puts row
 end

data/altertable-lakehouse.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   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.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/altertable-ai/altertable-lakehouse-ruby"

data/lib/altertable/lakehouse/adapters.rb

@@ -146,16 +146,16 @@ module Altertable
           @uri = URI.parse(@base_url)
         end
 
-        def get(path, body: nil, params: {}, headers: {}, &block) # rubocop:disable Lint/UnusedMethodArgument
-          request(Net::HTTP::Get, path, params: params, headers: headers, &block)
+        def get(path, body: nil, params: {}, headers: {}, &) # rubocop:disable Lint/UnusedMethodArgument
+          request(Net::HTTP::Get, path, params: params, headers: headers, &)
         end
 
-        def post(path, body: nil, params: {}, headers: {}, &block)
-          request(Net::HTTP::Post, path, body: body, params: params, headers: headers, &block)
+        def post(path, body: nil, params: {}, headers: {}, &)
+          request(Net::HTTP::Post, path, body: body, params: params, headers: headers, &)
         end
 
-        def delete(path, body: nil, params: {}, headers: {}, &block) # rubocop:disable Lint/UnusedMethodArgument
-          request(Net::HTTP::Delete, path, params: params, headers: headers, &block)
+        def delete(path, body: nil, params: {}, headers: {}, &) # rubocop:disable Lint/UnusedMethodArgument
+          request(Net::HTTP::Delete, path, params: params, headers: headers, &)
         end
 
         private

data/lib/altertable/lakehouse/client.rb

@@ -12,7 +12,7 @@ module Altertable
       DEFAULT_TIMEOUT = 10
       DEFAULT_OPEN_TIMEOUT = 5
 
-      def initialize(username: nil, password: nil, basic_auth_token: nil, base_url: nil, timeout: nil, open_timeout: nil, user_agent: nil, adapter: nil, headers: {}, **options)
+      def initialize(username: nil, password: nil, basic_auth_token: nil, base_url: nil, timeout: nil, open_timeout: nil, user_agent: nil, adapter: nil, headers: {}, **)
         # 1. Try passed basic_auth_token
         # 2. Try passed username/password
         # 3. Try ENV["ALTERTABLE_BASIC_AUTH_TOKEN"]
@@ -40,7 +40,7 @@ module Altertable
           "User-Agent" => @user_agent
         }
 
-        @adapter = select_adapter(adapter, base_url: @base_url, timeout: @timeout, open_timeout: @open_timeout, headers: default_headers.merge(headers), **options)
+        @adapter = select_adapter(adapter, base_url: @base_url, timeout: @timeout, open_timeout: @open_timeout, headers: default_headers.merge(headers), **)
       end
 
       # POST /append
@@ -59,8 +59,8 @@ module Altertable
       end
 
       # POST /query (streamed)
-      def query(statement:, headers: {}, **options)
-        req_body = Models::QueryRequest.new(statement: statement, **options).to_h.to_json
+      def query(statement:, headers: {}, **)
+        req_body = Models::QueryRequest.new(statement: statement, **).to_h.to_json
 
         enum = Enumerator.new do |yielder|
           buffer = ""
@@ -77,8 +77,8 @@ module Altertable
       end
 
       # POST /query (accumulated)
-      def query_all(statement:, headers: {}, **options)
-        result = query(statement: statement, headers: headers, **options)
+      def query_all(statement:, headers: {}, **)
+        result = query(statement: statement, headers: headers, **)
         rows = result.to_a # Accumulate
         {
           metadata: result.metadata,
@@ -278,36 +278,50 @@ module Altertable
       end
     end
 
+    ColumnDescriptor = Data.define(:name, :type)
+
     class QueryResult
       include Enumerable
 
       # metadata: the stream header object (first NDJSON line)
-      # columns:  array of column names or typed column descriptors (second NDJSON line)
+      # columns:  ColumnDescriptor array (second NDJSON line)
       attr_reader :metadata, :columns
 
       def initialize(enum)
         @enum = enum
         @metadata = nil
         @columns = nil
+        @column_names = nil
       end
 
       def each(&block)
-        # The real mock streams:
-        #   line 1: { "statement":…, "session_id":…, … }   (header object)
-        #   line 2: ["col1", "col2", …]                     (column names array)
-        #   line 3+: [val1, val2, …]                        (row value arrays)
-        # We zip each row array with the column names to produce a Hash.
+        # The mock streams NDJSON:
+        #   line 1: metadata object
+        #   line 2: column descriptors, or { "error": string }
+        #   line 3+: row arrays, or { "error": string }
+        # Row arrays are zipped with column names into hashes.
         line_index = 0
 
         @enum.each do |item|
+          if line_index.positive? && (message = stream_error_message(item))
+            raise QueryError.new(
+              message,
+              line_index: line_index,
+              operation: "query",
+              http_method: "POST",
+              http_path: "/query"
+            )
+          end
+
           case line_index
           when 0
             @metadata = item
           when 1
-            @columns = normalize_columns(item)
+            @columns = column_descriptors(item)
+            @column_names = @columns.map(&:name)
           else
-            if @columns.is_a?(Array) && item.is_a?(Array)
-              block.call(@columns.zip(item).to_h)
+            if item.is_a?(Array)
+              block.call(@column_names.zip(item).to_h)
             else
               block.call(item)
             end
@@ -318,16 +332,39 @@ module Altertable
 
       private
 
-      # The query service emits typed column descriptors, such as
-      # { "name" => "id", "type" => "INTEGER" }. Keep the public result
-      # shape stable by exposing names and using them as row keys.
-      def normalize_columns(columns)
-        return columns unless columns.is_a?(Array)
+      # A post-metadata JSON object with an `error` string is a stream failure,
+      # not column schema or a row.
+      def stream_error_message(item)
+        return unless item.is_a?(Hash)
+
+        message = item["error"]
+        message if message.is_a?(String)
+      end
+
+      def column_descriptors(columns)
+        unless columns.is_a?(Array)
+          raise column_parse_error("expected an array of column objects, got #{columns.inspect}")
+        end
 
         columns.map do |column|
-          column.is_a?(Hash) && column.key?("name") ? column["name"] : column
+          name = column["name"] if column.is_a?(Hash)
+          type = column["type"] if column.is_a?(Hash)
+          unless name.is_a?(String) && type.is_a?(String)
+            raise column_parse_error("expected a { \"name\", \"type\" } column object, got #{column.inspect}")
+          end
+
+          ColumnDescriptor.new(name: name, type: type)
         end
       end
+
+      def column_parse_error(message)
+        ParseError.new(
+          "Malformed /query column line: #{message}",
+          operation: "query",
+          http_method: "POST",
+          http_path: "/query"
+        )
+      end
     end
 
   end

data/lib/altertable/lakehouse/errors.rb

@@ -21,6 +21,27 @@ module Altertable
     class TimeoutError < Error; end
     class SerializationError < Error; end
     class ParseError < Error; end
+
+    # Backend-emitted `{ "error": string }` line in a /query NDJSON stream.
+    # `line_index` is the zero-based index of that line.
+    class QueryError < Error
+      attr_reader :line_index
+
+      def initialize(message, line_index:, operation: nil, http_method: nil, http_path: nil, status_code: nil, retriable: false, request_id: nil, cause: nil)
+        super(
+          message,
+          operation: operation,
+          http_method: http_method,
+          http_path: http_path,
+          status_code: status_code,
+          retriable: retriable,
+          request_id: request_id,
+          cause: cause
+        )
+        @line_index = line_index
+      end
+    end
+
     class ApiError < Error; end
     class ConfigurationError < Error; end
   end

data/lib/altertable/lakehouse/version.rb

@@ -1,5 +1,5 @@
 module Altertable
   module Lakehouse
-    VERSION = "0.8.0"
+    VERSION = "0.9.0"
   end
 end

data/rbi/altertable/lakehouse.rbi

@@ -47,6 +47,27 @@ module Altertable
     class TimeoutError < Error; end
     class SerializationError < Error; end
     class ParseError < Error; end
+
+    class QueryError < Error
+      sig { returns(Integer) }
+      def line_index; end
+
+      sig do
+        params(
+          message: String,
+          line_index: Integer,
+          operation: T.nilable(String),
+          http_method: T.nilable(String),
+          http_path: T.nilable(String),
+          status_code: T.nilable(Integer),
+          retriable: T::Boolean,
+          request_id: T.nilable(String),
+          cause: T.nilable(Exception)
+        ).void
+      end
+      def initialize(message, line_index:, operation: nil, http_method: nil, http_path: nil, status_code: nil, retriable: false, request_id: nil, cause: nil); end
+    end
+
     class ApiError < Error; end
     class ConfigurationError < Error; end
 
@@ -89,7 +110,7 @@ module Altertable
       sig { params(statement: String, headers: T::Hash[String, String], options: T.untyped).returns(::Altertable::Lakehouse::QueryResult) }
       def query(statement:, headers: {}, **options); end
 
-      sig { params(statement: String, headers: T::Hash[String, String], options: T.untyped).returns(T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      sig { params(statement: String, headers: T::Hash[String, String], options: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
       def query_all(statement:, headers: {}, **options); end
 
       sig do
@@ -183,13 +204,21 @@ module Altertable
       def handle_response(resp); end
     end
 
+    class ColumnDescriptor < Data
+      sig { returns(String) }
+      def name; end
+
+      sig { returns(String) }
+      def type; end
+    end
+
     class QueryResult
       include Enumerable
 
       sig { returns(T.untyped) }
       def metadata; end
 
-      sig { returns(T.untyped) }
+      sig { returns(T.nilable(T::Array[::Altertable::Lakehouse::ColumnDescriptor])) }
       def columns; end
 
       sig { params(enum: T.untyped).void }

data/sig/altertable/lakehouse/client.rbs

@@ -103,18 +103,34 @@ module Altertable
       def handle_response: (Adapters::Response resp) -> untyped
     end
 
+    class ColumnDescriptor < ::Data
+      attr_reader name: String
+      attr_reader type: String
+
+      def self.new: (name: String, type: String) -> instance
+                  | (String name, String type) -> instance
+      def to_h: () -> { name: String, type: String }
+    end
+
     class QueryResult
       include Enumerable
 
       @enum: Enumerator[untyped, untyped]
       @metadata: untyped
-      @columns: untyped
+      @columns: Array[ColumnDescriptor]?
+      @column_names: Array[String]?
 
       attr_reader metadata: untyped
-      attr_reader columns: untyped
+      attr_reader columns: Array[ColumnDescriptor]?
 
       def initialize: (Enumerator[untyped, untyped] enum) -> void
       def each: () { (untyped) -> void } -> void
+
+      private
+
+      def stream_error_message: (untyped item) -> String?
+      def column_descriptors: (untyped columns) -> Array[ColumnDescriptor]
+      def column_parse_error: (String message) -> ParseError
     end
   end
 end

data/sig/altertable/lakehouse/errors.rbs

@@ -39,6 +39,22 @@ module Altertable
     class ParseError < Error
     end
 
+    class QueryError < Error
+      attr_reader line_index: Integer
+
+      def initialize: (
+        String message,
+        line_index: Integer,
+        ?operation: String?,
+        ?http_method: String?,
+        ?http_path: String?,
+        ?status_code: Integer?,
+        ?retriable: bool,
+        ?request_id: String?,
+        ?cause: Exception?
+      ) -> void
+    end
+
     class ApiError < Error
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: altertable-lakehouse
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Altertable AI
@@ -249,7 +249,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="