GH-48435: [Ruby] Add support for reading sparse union array (#48439)

### Rationale for this change

It's a sparse variant of union array.

### What changes are included in this PR?

* Add `ArrowFormat::SparseUnionType`
* Add `ArrowFormat::SparseUnionArray`

### Are these changes tested?

Yes.

### Are there any user-facing changes?

Yes.
* GitHub Issue: #48435

Authored-by: Sutou Kouhei <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>

Author: kou

ruby/red-arrow-format/lib/arrow-format/array.rb

@@ -232,19 +232,23 @@ def to_a
   end
 
   class UnionArray < Array
+    def initialize(type, size, types_buffer, children)
+      super(type, size, nil)
+      @types_buffer = types_buffer
+      @children = children
+    end
+  end
+
+  class DenseUnionArray < UnionArray
     def initialize(type,
                    size,
                    types_buffer,
                    offsets_buffer,
                    children)
-      super(type, size, nil)
-      @types_buffer = types_buffer
+      super(type, size, types_buffer, children)
       @offsets_buffer = offsets_buffer
-      @children = children
     end
-  end
 
-  class DenseUnionArray < UnionArray
     def to_a
       children_values = @children.collect(&:to_a)
       types = @types_buffer.each(:S8, 0, @size)
@@ -256,6 +260,16 @@ def to_a
     end
   end
 
+  class SparseUnionArray < UnionArray
+    def to_a
+      children_values = @children.collect(&:to_a)
+      @types_buffer.each(:S8, 0, @size).with_index.collect do |(_, type), i|
+        index = @type.resolve_type_index(type)
+        children_values[index][i]
+      end
+    end
+  end
+
   class MapArray < VariableSizeListArray
     def to_a
       super.collect do |entries|

ruby/red-arrow-format/lib/arrow-format/file-reader.rb

@@ -184,6 +184,8 @@ def read_field(fb_field)
         case fb_type.mode
         when Org::Apache::Arrow::Flatbuf::UnionMode::DENSE
           type = DenseUnionType.new(children, type_ids)
+        when Org::Apache::Arrow::Flatbuf::UnionMode::SPARSE
+          type = SparseUnionType.new(children, type_ids)
         end
       when Org::Apache::Arrow::Flatbuf::Map
         type = MapType.new(read_field(fb_field.children[0]))
@@ -234,15 +236,22 @@ def read_column(field, nodes, buffers, body)
           read_column(child, nodes, buffers, body)
         end
         field.type.build_array(length, validity, children)
-      when UnionType
-        # union type doesn't have validity.
+      when DenseUnionType
+        # dense union type doesn't have validity.
         types = validity
         offsets_buffer = buffers.shift
         offsets = body.slice(offsets_buffer.offset, offsets_buffer.length)
         children = field.type.children.collect do |child|
           read_column(child, nodes, buffers, body)
         end
         field.type.build_array(length, types, offsets, children)
+      when SparseUnionType
+        # sparse union type doesn't have validity.
+        types = validity
+        children = field.type.children.collect do |child|
+          read_column(child, nodes, buffers, body)
+        end
+        field.type.build_array(length, types, children)
       when VariableSizeBinaryType
         offsets_buffer = buffers.shift
         values_buffer = buffers.shift

ruby/red-arrow-format/lib/arrow-format/type.rb

@@ -321,4 +321,14 @@ def build_array(size, types_buffer, offsets_buffer, children)
       DenseUnionArray.new(self, size, types_buffer, offsets_buffer, children)
     end
   end
+
+  class SparseUnionType < UnionType
+    def initialize(children, type_ids)
+      super("SparseUnion", children, type_ids)
+    end
+
+    def build_array(size, types_buffer, children)
+      SparseUnionArray.new(self, size, types_buffer, children)
+    end
+  end
 end

ruby/red-arrow-format/test/test-file-reader.rb

@@ -256,6 +256,28 @@ def test_read
     end
   end
 
+  sub_test_case("SparseUnion") do
+    def build_array
+      fields = [
+        Arrow::Field.new("number", :int8),
+        Arrow::Field.new("text", :string),
+      ]
+      type_ids = [11, 13]
+      data_type = Arrow::SparseUnionDataType.new(fields, type_ids)
+      types = Arrow::Int8Array.new([11, 13, 11, 13, 11])
+      children = [
+        Arrow::Int8Array.new([1, nil, nil, nil, 5]),
+        Arrow::StringArray.new([nil, "b", nil, "d", nil])
+      ]
+      Arrow::SparseUnionArray.new(data_type, types, children)
+    end
+
+    def test_read
+      assert_equal([{"value" => [1, "b", nil, "d", 5]}],
+                   read)
+    end
+  end
+
   sub_test_case("Map") do
     def build_array
       data_type = Arrow::MapDataType.new(:string, :int8)