red_amber 0.3.0 → 0.4.1

data/lib/red_amber/data_frame_combinable.rb

@@ -1,17 +1,38 @@
 # frozen_string_literal: true
 
 module RedAmber
-  # mix-in for the class DataFrame
+  # Mix-in for the class DataFrame
   module DataFrameCombinable
     # Refinements for Arrow::Table
     using RefineArrowTable
 
-    # Concatenate other dataframe onto the bottom.
+    # Concatenate other dataframes or tables onto the bottom of self.
     #
+    # @note the `#types` must be same as `other#types`.
     # @param other [DataFrame, Arrow::Table, Array<DataFrame, Arrow::Table>]
-    #   DataFrame/Table to concatenate onto the bottom of self.
+    #   DataFrames or Tables to concatenate.
     # @return [DataFrame]
-    #   Concatenated dataframe.
+    #   concatenated dataframe.
+    # @example
+    #   df    = DataFrame.new(x: [1, 2], y: ['A', 'B'])
+    #   other = DataFrame.new(x: [3, 4], y: ['C', 'D'])
+    #   [df.types, other.types]
+    #
+    #   # =>
+    #   [[:uint8, :string], [:uint8, :string]]
+    #
+    #   df.concatenate(other)
+    #
+    #   # =>
+    #           x y
+    #     <uint8> <string>
+    #   0       1 A
+    #   1       2 B
+    #   2       3 C
+    #   3       4 D
+    #
+    # @since 0.2.3
+    #
     def concatenate(*other)
       case other
       in [] | [nil] | [[]]
@@ -39,14 +60,29 @@ module RedAmber
     alias_method :concat, :concatenate
     alias_method :bind_rows, :concatenate
 
-    # Merge other DataFrame or Table from other.
-    # - Self and other must have same size.
-    # - Self and other do not share the same key.
-    #   - If they share any keys, raise Error.
+    # Merge other DataFrames or Tables.
+    #
+    # @note the `#size` must be same as `other#size`.
+    # @note self and other must not share the same key.
     # @param other [DataFrame, Arrow::Table, Array<DataFrame, Arrow::Table>]
-    #   DataFrame/Table to concatenate.
+    #   DataFrames or Tables to merge.
+    # @raise [DataFrameArgumentError]
+    #   if size is not same or self and other shares the same key.
     # @return [DataFrame]
-    #   Merged dataframe.
+    #   merged dataframe.
+    # @example
+    #   df    = DataFrame.new(x: [1, 2], y: [3, 4])
+    #   other = DataFrame.new(a: ['A', 'B'], b: ['C', 'D'])
+    #   df.merge(other)
+    #
+    #   # =>
+    #           x       y a        b
+    #     <uint8> <uint8> <string> <string>
+    #   0       1       3 A        C
+    #   1       2       4 B        D
+    #
+    # @since 0.2.3
+    #
     def merge(*other)
       case other
       in [] | [nil] | [[]]
@@ -85,81 +121,225 @@ module RedAmber
 
     # Mutating joins (#inner_join, #full_join, #left_join, #right_join)
 
-    # Join another DataFrame or Table, leaving only the matching records.
-    # - Same as `#join` with `type: :inner`
-    # - A kind of mutating join.
-    #
     # @!macro join_before
     #   @param other [DataFrame, Arrow::Table]
     #     A DataFrame or a Table to be joined with self.
     #
+    # @!macro join_force_order
+    #   @param force_order [Boolean]
+    #     wheather force order of the output always same.
+    #     - This option is used in `:full_outer` and `:right_outer`.
+    #     - If this option is true (by default) it will append index to the source
+    #       and sort after joining. It will cause some degradation in performance.
+    #
     # @!macro join_after
     #   @param suffix [#succ]
     #     a suffix to rename keys when key names conflict as a result of join.
     #     `suffix` must be responsible to `#succ`.
     #   @return [DataFrame]
-    #     Joined dataframe.
+    #     joined dataframe.
     #
     # @!macro join_key_in_array
     #   @param join_keys [String, Symbol, Array<String, Symbol>]
-    #     A key or keys to match.
+    #     a key or keys to match.
     #
     # @!macro join_key_in_hash
     #   @param join_key_pairs [Hash]
-    #     Pairs of a key name or key names to match in left and right.
+    #     pairs of a key name or key names to match in left and right.
     #   @option join_key_pairs [String, Symbol, Array<String, Symbol>] :left
-    #     Join keys in `self`.
+    #     join keys in `self`.
     #   @option join_key_pairs [String, Symbol, Array<String, Symbol>] :right
-    #     Join keys in `other`.
+    #     join keys in `other`.
+    #
+    # @!macro join_common_example_1
+    #   @example
+    #     df = DataFrame.new(KEY: %w[A B C], X1: [1, 2, 3])
+    #
+    #     # =>
+    #       KEY           X1
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
+    #     2 C              3
+    #
+    #     other = DataFrame.new(KEY: %w[A B D], X2: [true, false, nil])
+    #
+    #     # =>
+    #       KEY      X2
+    #       <string> <boolean>
+    #     0 A        true
+    #     1 B        false
+    #     2 D        (nil)
+    #
+    # @!macro join_common_example_2
+    #   @example
+    #     df2 = DataFrame.new(KEY1: %w[A B C], X1: [1, 2, 3])
+    #
+    #     # =>
+    #       KEY1          X1
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
+    #     2 C              3
+    #
+    #     other2 = DataFrame.new(KEY2: %w[A B D], X2: [true, false, nil])
+    #
+    #     # =>
+    #       KEY2     X2
+    #       <string> <boolean>
+    #     0 A        true
+    #     1 B        false
+    #     2 D        (nil)
+    #
+    # @!macro join_common_example_3
+    #   @example
+    #     df3 = DataFrame.new(
+    #       KEY1: %w[A B C],
+    #       KEY2: [1, 2, 3]
+    #     )
+    #
+    #     # =>
+    #       KEY1        KEY2
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
+    #     2 C              3
+    #
+    #     other3 = DataFrame.new(
+    #       KEY1: %w[A B D],
+    #       KEY2: [1, 4, 5]
+    #     )
+    #
+    #     # =>
+    #       KEY1        KEY2
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              4
+    #     2 D              5
+
+    # Join another DataFrame or Table, leaving only the matching records.
+    # - Same as `#join` with `type: :inner`
+    # - A kind of mutating join.
     #
-    # @overload inner_join(other, suffix: '.1')
+    # @overload inner_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.inner_join(other)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
     #
-    # @overload inner_join(other, join_keys, suffix: '.1')
+    # @overload inner_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.inner_join(other, :KEY)
     #
-    # @overload inner_join(other, join_key_pairs, suffix: '.1')
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #
+    # @overload inner_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.inner_join(other2, { left: :KEY1, right: :KEY2 })
+    #
+    #     # =>
+    #       KEY1          X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
     #
-    def inner_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :inner, suffix: suffix)
+    # @since 0.2.3
+    #
+    def inner_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(other, join_keys, type: :inner, suffix: suffix, force_order: force_order)
     end
 
     # Join another DataFrame or Table, leaving all records.
     # - Same as `#join` with `type: :full_outer`
     # - A kind of mutating join.
     #
-    # @overload full_join(other, suffix: '.1')
+    # @overload full_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.full_join(other)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
+    #     3 D          (nil) (nil)
     #
-    # @overload full_join(other, join_keys, suffix: '.1')
+    # @overload full_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.full_join(other, :KEY)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
+    #     3 D          (nil) (nil)
     #
-    # @overload full_join(other, join_key_pairs, suffix: '.1')
+    # @overload full_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
-    #
-    def full_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :full_outer, suffix: suffix)
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.full_join(other2, { left: :KEY1, right: :KEY2 })
+    #
+    #     # =>
+    #       KEY1          X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
+    #     3 D          (nil) (nil)
+    #
+    # @since 0.2.3
+    #
+    def full_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(other, join_keys,
+           type: :full_outer, suffix: suffix, force_order: force_order)
     end
 
     alias_method :outer_join, :full_join
@@ -168,54 +348,130 @@ module RedAmber
     # - Same as `#join` with `type: :left_outer`
     # - A kind of mutating join.
     #
-    # @overload left_join(other, suffix: '.1')
+    # @overload left_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.left_join(other)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
     #
-    # @overload left_join(other, join_keys, suffix: '.1')
+    # @overload left_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.left_join(other, :KEY)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
     #
-    # @overload left_join(other, join_key_pairs, suffix: '.1')
+    # @overload left_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.left_join(other2, { left: :KEY1, right: :KEY2 })
     #
-    def left_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :left_outer, suffix: suffix)
+    #     # =>
+    #       KEY1          X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
+    #
+    # @since 0.2.3
+    #
+    def left_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(other, join_keys, type: :left_outer, suffix: suffix, force_order: force_order)
     end
 
     # Join matching values from self to other.
     # - Same as `#join` with `type: :right_outer`
     # - A kind of mutating join.
     #
-    # @overload right_join(other, suffix: '.1')
+    # @overload right_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.right_join(other)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 D          (nil) (nil)
     #
-    # @overload right_join(other, join_keys, suffix: '.1')
+    # @overload right_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.right_join(other, :KEY)
     #
-    # @overload right_join(other, join_key_pairs, suffix: '.1')
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 D          (nil) (nil)
+    #
+    # @overload right_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
-    #
-    def right_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :right_outer, suffix: suffix)
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.right_join(other2, { left: :KEY1, right: :KEY2 })
+    #
+    #     # =>
+    #       KEY1          X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 D          (nil) (nil)
+    #
+    # @since 0.2.3
+    #
+    def right_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(
+        other,
+        join_keys,
+        type: :right_outer,
+        suffix: suffix,
+        force_order: force_order
+      )
     end
 
     # Filtering joins (#semi_join, #anti_join)
@@ -224,54 +480,115 @@ module RedAmber
     # - Same as `#join` with `type: :left_semi`
     # - A kind of filtering join.
     #
-    # @overload semi_join(other, suffix: '.1')
+    # @overload semi_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.semi_join(other)
     #
-    # @overload semi_join(other, join_keys, suffix: '.1')
+    #     # =>
+    #       KEY           X1
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
+    #
+    # @overload semi_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.semi_join(other, :KEY)
+    #
+    #     # =>
+    #       KEY           X1
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
     #
-    # @overload semi_join(other, join_key_pairs, suffix: '.1')
+    # @overload semi_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.semi_join(other2, { left: :KEY1, right: :KEY2 })
+    #
+    #     # =>
+    #       KEY1          X1
+    #       <string> <uint8>
+    #     0 A              1
+    #     1 B              2
     #
-    def semi_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :left_semi, suffix: suffix)
+    # @since 0.2.3
+    #
+    def semi_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(other, join_keys, type: :left_semi, suffix: suffix, force_order: force_order)
     end
 
     # Return records of self that do not have a match in other.
     # - Same as `#join` with `type: :left_anti`
     # - A kind of filtering join.
     #
-    # @overload anti_join(other, suffix: '.1')
+    # @overload anti_join(other, suffix: '.1', force_order: true)
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
     #   @macro join_before
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example without key (use implicit common key)
+    #     df.anti_join(other)
+    #
+    #     # =>
+    #       KEY           X1
+    #       <string> <uint8>
+    #     0 C              3
     #
-    # @overload anti_join(other, join_keys, suffix: '.1')
+    # @overload anti_join(other, join_keys, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example with a key
+    #     df.anti_join(other, :KEY)
     #
-    # @overload anti_join(other, join_key_pairs, suffix: '.1')
+    #     # =>
+    #       KEY           X1
+    #       <string> <uint8>
+    #     0 C              3
+    #
+    # @overload anti_join(other, join_key_pairs, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_2
+    #   @example with key pairs
+    #     df2.anti_join(other2, { left: :KEY1, right: :KEY2 })
+    #
+    #     # =>
+    #       KEY1          X1
+    #       <string> <uint8>
+    #     0 C              3
+    #
+    # @since 0.2.3
     #
-    def anti_join(other, join_keys = nil, suffix: '.1')
-      join(other, join_keys, type: :left_anti, suffix: suffix)
+    def anti_join(other, join_keys = nil, suffix: '.1', force_order: true)
+      join(other, join_keys, type: :left_anti, suffix: suffix, force_order: force_order)
     end
 
     # Set operations (#intersect, #union, #difference, #set_operable?)
@@ -279,8 +596,13 @@ module RedAmber
     # Check if set operation with self and other is possible.
     #
     # @macro join_before
+    # @return [Boolean]
+    #   true if set operation is possible.
+    # @macro join_common_example_3
+    # @example
+    #   df3.set_operable?(other3) # => true
     #
-    # @return [Boolean] true if set operation is possible.
+    # @since 0.2.3
     #
     def set_operable?(other) # rubocop:disable Naming/AccessorMethodName
       keys == other.keys.map(&:to_sym)
@@ -291,8 +613,18 @@ module RedAmber
     # - A kind of set operations.
     #
     # @macro join_before
+    # @return [DataFrame]
+    #   joined dataframe.
+    # @macro join_common_example_3
+    # @example
+    #   df3.intersect(other3)
+    #
+    #   # =>
+    #     KEY1        KEY2
+    #     <string> <uint8>
+    #   0 A              1
     #
-    # @return [DataFrame] Joined dataframe.
+    # @since 0.2.3
     #
     def intersect(other)
       unless keys == other.keys.map(&:to_sym)
@@ -307,8 +639,22 @@ module RedAmber
     # - A kind of set operations.
     #
     # @macro join_before
-    #
-    # @return [DataFrame] Joined dataframe.
+    # @return [DataFrame]
+    #   joined dataframe.
+    # @macro join_common_example_3
+    # @example
+    #   df3.intersect(other3)
+    #
+    #   # =>
+    #     KEY1        KEY2
+    #     <string> <uint8>
+    #   0 A              1
+    #   1 B              2
+    #   2 C              3
+    #   3 B              4
+    #   4 D              5
+    #
+    # @since 0.2.3
     #
     def union(other)
       unless keys == other.keys.map(&:to_sym)
@@ -323,8 +669,27 @@ module RedAmber
     # - A kind of set operations.
     #
     # @macro join_before
+    # @return [DataFrame]
+    #   joined dataframe.
+    # @macro join_common_example_3
+    # @example
+    #   df3.intersect(other3)
+    #
+    #   # =>
+    #     KEY1        KEY2
+    #     <string> <uint8>
+    #   0 B              2
+    #   1 C              3
+    #
+    #   other.intersect(df)
+    #
+    #   # =>
+    #     KEY1        KEY2
+    #     <string> <uint8>
+    #   0 B              4
+    #   1 D              5
     #
-    # @return [DataFrame] Joined dataframe.
+    # @since 0.2.3
     #
     def difference(other)
       unless keys == other.keys.map(&:to_sym)
@@ -338,60 +703,167 @@ module RedAmber
 
     # Join another DataFrame or Table to self.
     #
-    # @overload join(other, type: :inner, suffix: '.1')
+    # @!macro join_common_type
+    #   @param type [:left_semi, :right_semi, :left_anti, :right_anti, :inner,
+    #                left_outer, :right_outer, :full_outer] type of join.
+    #
+    # @!macro join_common_example_4
+    #   @example
+    #     df4 = DataFrame.new(
+    #       X1: %w[A B C],
+    #       Y: %w[D E F]
+    #     )
+    #
+    #     # =>
+    #       X1       Y1
+    #       <string> <string>
+    #     0 A        D
+    #     1 B        E
+    #     2 C        F
+    #
+    #     other4 = DataFrame.new(
+    #       X2: %w[A B D],
+    #       Y:  %w[e E E]
+    #     )
+    #
+    #     # =>
+    #       X1       Y1
+    #       <string> <string>
+    #     0 A        D
+    #     1 B        E
+    #     2 C        F
+
+    # @note the order of joined results will be preserved by default.
+    #   This is enabled by appending index column to sort after joining but
+    #   it will cause some performance degradation. If you don't matter
+    #   the order of the result, set `force_order` option to `false`.
+    #
+    # @overload join(other, type: :inner, suffix: '.1', force_order: true)
     #
     #   If `join_key` is not specified, common keys in self and other are used
     #   (natural keys). Returns joined dataframe.
     #
-    #   @!macro join_common_type
-    #     @param type [:left_semi, :right_semi, :left_anti, :right_anti, :inner,
-    #                  left_outer, :right_outer, :full_outer] type of join.
-    #
     #   @macro join_before
     #   @macro join_common_type
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_1
+    #   @example
+    #     df.join(other)
+    #
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #
+    #     df.join(other, type: :full_outer)
     #
-    # @overload join(other, join_keys, type: :inner, suffix: '.1')
+    #     # =>
+    #       KEY           X1 X2
+    #       <string> <uint8> <boolean>
+    #     0 A              1 true
+    #     1 B              2 false
+    #     2 C              3 (nil)
+    #     3 D          (nil) (nil)
+    #
+    # @overload join(other, join_keys, type: :inner, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_array
     #   @macro join_common_type
+    #   @macro join_force_order
     #   @macro join_after
+    #   @macro join_common_example_3
+    #   @example join keys in an Array
+    #     df3.join(other3, [:KEY1, :KEY2])
+    #
+    #     # =>
+    #       KEY1        KEY2
+    #       <string> <uint8>
+    #     0 A              1
     #
-    # @overload join(other, join_key_pairs, type: :inner, suffix: '.1')
+    #   @example partial join key and suffix
+    #     df3.join(other3, :KEY1, suffix: '.a')
+    #
+    #     # =>
+    #       KEY1        KEY2  KEY2.a
+    #       <string> <uint8> <uint8>
+    #     0 A              1       1
+    #     1 B              2       4
+    #
+    # @overload join(other, join_key_pairs, type: :inner, suffix: '.1', force_order: true)
     #
     #   @macro join_before
     #   @macro join_key_in_hash
     #   @macro join_common_type
+    #   @macro join_force_order
     #   @macro join_after
-    #
-    def join(other, join_keys = nil, type: :inner, suffix: '.1')
-      case other
-      when DataFrame
-        other = other.table
-      when Arrow::Table
-        # Nop
+    #   @macro join_common_example_4
+    #   @example without options
+    #     df4.join(other4)
+    #
+    #     # =>
+    #       X1       Y        X2
+    #       <string> <string> <string>
+    #     0 B        E        D
+    #     1 B        E        B
+    #
+    #   @example join by key pairs
+    #     df4.join(other4, { left: [:X1, :Y], right: [:X2, :Y] })
+    #
+    #     # =>
+    #       X1       Y
+    #       <string> <string>
+    #     0 B        E
+    #
+    #   @example join by key pairs, using renaming by suffix
+    #     df4.join(other4, { left: :X1, right: :X2 })
+    #
+    #     # =>
+    #       X1       Y        Y.1
+    #       <string> <string> <string>
+    #     0 A        D        e
+    #     1 B        E        E
+    #
+    # @since 0.2.3
+    #
+    def join(other, join_keys = nil, type: :inner, suffix: '.1', force_order: true)
+      right_table =
+        case other
+        when DataFrame
+          other.table
+        when Arrow::Table
+          other
+        else
+          raise DataFrameArgumentError, 'other must be a DataFrame or an Arrow::Table'
+        end
+
+      type = type.to_sym
+      left_index = :__LEFT_INDEX__
+      right_index = :__RIGHT_INDEX__
+      if force_order
+        left_table = assign(left_index) { indices }.table
+        other = DataFrame.create(other) if other.is_a?(Arrow::Table)
+        right_table = other.assign(right_index) { indices }.table
       else
-        raise DataFrameArgumentError, 'other must be a DataFrame or an Arrow::Table'
+        left_table = table
       end
 
-      table_keys = table.keys
-      other_keys = other.keys
-      type = type.to_sym
+      table_keys = left_table.keys
+      other_keys = right_table.keys
 
       # natural keys (implicit common keys)
       join_keys ||= table_keys.intersection(other_keys)
 
       # This is not necessary if additional procedure is contributed to Red Arrow.
       if join_keys.is_a?(Hash)
-        left_keys = join_keys[:left]
-        right_keys = join_keys[:right]
+        left_keys = ensure_keys(join_keys[:left])
+        right_keys = ensure_keys(join_keys[:right])
       else
-        left_keys = join_keys
-        right_keys = join_keys
+        left_keys = ensure_keys(join_keys)
+        right_keys = left_keys
       end
-      left_keys = Array(left_keys).map(&:to_s)
-      right_keys = Array(right_keys).map(&:to_s)
 
       case type
       when :full_outer, :left_semi, :left_anti, :right_semi, :right_anti
@@ -407,43 +879,73 @@ module RedAmber
 
       # Should we rescue errors in Arrow::Table#join for usability ?
       joined_table =
-        table.join(other, join_keys,
-                   type: type,
-                   left_outputs: left_outputs,
-                   right_outputs: right_outputs)
+        left_table.join(
+          right_table,
+          join_keys,
+          type: type,
+          left_outputs: left_outputs,
+          right_outputs: right_outputs
+        )
 
       case type
       when :inner, :left_outer, :left_semi, :left_anti, :right_semi, :right_anti
-        if joined_table.keys.uniq!
-          DataFrame.create(rename_table(joined_table, n_keys, suffix))
-        else
-          DataFrame.create(joined_table)
-        end
+        dataframe =
+          if joined_table.keys.uniq!
+            DataFrame.create(rename_table(joined_table, n_keys, suffix))
+          else
+            DataFrame.create(joined_table)
+          end
+        sorter =
+          case type
+          when :inner, :left_outer
+            [left_index, right_index]
+          when :left_semi, :left_anti
+            [left_index]
+          when :right_semi, :right_anti
+            [right_index]
+          end
       when :full_outer
+        key_index_lr =
+          left_keys.map { left_table.keys.index(_1) }
+            .zip(right_keys.map { left_table.keys.size + right_table.keys.index(_1) })
         renamed_table = rename_table(joined_table, n_keys, suffix)
-        renamed_keys = renamed_table.keys
         dropper = []
-        DataFrame.create(renamed_table).assign do |df|
-          left_keys.map do |left_key|
-            i_left_key = renamed_keys.index(left_key)
-            right_key = renamed_keys[i_left_key + table_keys.size]
-            dropper << right_key
-            [left_key.to_sym, merge_array(df[left_key].data, df[right_key].data)]
+        dataframe =
+          DataFrame.create(renamed_table).assign do |df|
+            key_index_lr.map do |l, r|
+              dropper << df.keys[r]
+              [df.keys[l], merge_array(df.vectors[l].data, df.vectors[r].data)]
+            end
           end
-        end.drop(dropper)
+        dataframe = dataframe.drop(dropper)
+        sorter = [left_index, right_index]
       when :right_outer
-        if joined_table.keys.uniq!
-          DataFrame.create(rename_table(joined_table, left_outputs.size, suffix))
-        else
-          DataFrame.create(joined_table)
-        end.pick do
-          [right_keys, keys.map(&:to_s) - right_keys]
-        end
+        dataframe =
+          if joined_table.keys.uniq!
+            DataFrame.create(rename_table(joined_table, left_outputs.size, suffix))
+          else
+            DataFrame.create(joined_table)
+          end
+        dataframe = dataframe.pick(right_keys, dataframe.keys - right_keys)
+        sorter = [left_index, right_index]
+      end
+
+      if force_order
+        dataframe
+          .sort(sorter)
+          .drop(sorter)
+      else
+        dataframe
       end
     end
 
     private
 
+    # To ensure Array of Symbols
+    def ensure_keys(keys)
+      Array(keys).map(&:to_sym)
+    end
+
     # Rename duplicate keys by suffix
     def rename_table(joined_table, n_keys, suffix)
       joined_keys = joined_table.keys
@@ -453,17 +955,9 @@ module RedAmber
       renamed_right_keys =
         other_keys.map do |key|
           if dup_keys.include?(key)
-            new_key = nil
-            loop do
-              new_key = "#{key}#{suffix}"
-              break unless joined_keys.include?(new_key)
-
-              s = suffix.succ
-              raise DataFrameArgumentError, "suffix #{suffix} is invalid" if s == suffix
-
-              suffix = s
-            end
-            new_key
+            suffixed = "#{key}#{suffix}".to_sym
+            # Find a key from suffixed.succ
+            (suffixed..).find { !joined_keys.include?(_1) }
           else
             key
           end