utPLSQL · jgebal · May 25, 2018 · Apr 23, 2018 · Apr 24, 2018 · May 1, 2018
diff --git a/docs/userguide/advanced_data_comparison.md b/docs/userguide/advanced_data_comparison.md
@@ -7,7 +7,7 @@ utPLSQL expectations incorporates advanced data comparison options when comparin
 - nested table and varray  
 
 Advanced data-comparison options are available for the [`equal`](expectations.md#equal) matcher.
- 
+
 ## Syntax
 
 ```
@@ -23,6 +23,9 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
  - `exclude(a_items varchar2)` - item or comma separated list of items to exclude
  - `include(a_items ut_varchar2_list)` - table of items to include 
  - `exclude(a_items ut_varchar2_list)` - table of items to exclude
+ - `unordered` - perform compare on unordered set of data, return only missing or actual
+ - `join_by(a_columns varchar2)` - columns or comma seperated list of columns to join two cursors by
+ - `join_by(a_columns ut_varchar2_list)` - table of columns to join two cursors by
 
 Each item in the comma separated list can be:
 - a column name of cursor to be compared
@@ -55,7 +58,7 @@ Columns 'ignore_me' and "ADate" will get excluded from cursor comparison.
 The cursor data is equal, when those columns are excluded.
 
 This option is useful in scenarios, when you need to exclude incomparable/unpredictable column data like CREATE_DATE of a record that is maintained by default value on a table column.
- 
+
 ## Selecting columns for data comparison
 
 Consider the following example
@@ -92,6 +95,86 @@ Only the columns 'RN', "A_Column" will be compared. Column 'SOME_COL' is exclude
 
 This option can be useful in scenarios where you need to narrow-down the scope of test so that the test is only focused on very specific data.  
 
+##Unordered
+
+Unordered option allows for quick comparison of two cursors without need of ordering them in any way.
+
+Result of such comparison will be limited to only information about row existing or not existing in given set without actual information about exact differences.
+
+
+
+```sql
+procedure unordered_tst is
+    l_actual   sys_refcursor;
+    l_expected sys_refcursor;
+begin
+    open l_expected for select username, user_id from all_users
+    union all
+    select 'TEST' username, -600 user_id from dual
+    order by 1 desc;
+    open l_actual   for select username, user_id from all_users
+    union all
+    select 'TEST' username, -610 user_id from dual
+    order by 1 asc;
+    ut.expect( l_actual ).to_equal( l_expected ).unordered;
+end;
+```
+
+
+
+Above test will result in two differences of one row extra and one row missing. 
+
+
+
+```sql
+      Diff:
+      Rows: [ 2 differences ]
+      Missing:  <ROW><USERNAME>TEST</USERNAME><USER_ID>-600</USER_ID></ROW>
+      Extra:    <ROW><USERNAME>TEST</USERNAME><USER_ID>-610</USER_ID></ROW>
+```
+
+
+
+
+
+## Join By option
+
+You can now join two cursors by defining a primary key or composite key that will be used to uniquely identify and compare rows. This option allows us to exactly show which rows are missing, extra and which are different without ordering clause. In the situation where the join key is not unique, join will partition set over rows with a same key and join on row number as well as given join key. The extra rows or missing will be presented to user as well as not matching rows. 
+
+Join by option can be used in conjunction with include or exclude options. However if any of the join keys is part of exclude set, comparison will fail and report to user that sets could not be joined on specific key  (excluded).
+
+Join by options currently doesn't support nested table inside cursor.
+
+```sql
+procedure join_by_username is
+    l_actual   sys_refcursor;
+    l_expected sys_refcursor;
+begin
+    open l_expected for select username, user_id from all_users
+    union all
+    select 'TEST' username, -600 user_id from dual
+    order by 1 desc;
+    open l_actual   for select username, user_id from all_users
+    union all
+    select 'TEST' username, -610 user_id from dual
+    order by 1 asc;
+    ut.expect( l_actual ).to_equal( l_expected ).join_by('USERNAME');
+end;
+```
+This will show you difference in row 'TEST' regardless of order.
+
+```sql
+      Rows: [ 1 differences ]
+        PK <USERNAME>TEST</USERNAME> - Expected: <USER_ID>-600</USER_ID>
+        PK <USERNAME>TEST</USERNAME> - Actual:   <USER_ID>-610</USER_ID>
+```
+
+Assumption is that join by is made by column name so that what will be displayed as part of results.
+
+
+
+**Please note that .join_by option will take longer to process due to need of parsing via primary keys.**
+
 ## Defining item as XPath
 When using XPath expression, keep in mind the following:
 
@@ -109,4 +192,4 @@ begin
     open l_actual   for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 4;
     ut.expect( l_actual ).to_equal( l_expected ).include( '/ROW/RN|/ROW/A_Column|/ROW/SOME_COL' );
 end;
-```   
+```
diff --git a/source/core/types/ut_key_value_pair.tps b/source/core/types/ut_key_value_pair.tps
@@ -1,4 +1,4 @@
-create or replace type ut_key_value_pair as object(
+create or replace type ut_key_value_pair force as object(
   /*
   utPLSQL - Version 3
   Copyright 2016 - 2017 utPLSQL Project

diff --git a/source/create_synonyms_and_grants_for_public.sql b/source/create_synonyms_and_grants_for_public.sql
@@ -142,8 +142,6 @@ create public synonym ut_file_mapping for &&ut3_owner..ut_file_mapping;
 create public synonym ut_file_mapper for &&ut3_owner..ut_file_mapper;
 create public synonym ut_key_value_pairs for &&ut3_owner..ut_key_value_pairs;
 create public synonym ut_key_value_pair for &&ut3_owner..ut_key_value_pair;
-create public synonym ut_compound_data_tmp for &&ut3_owner..ut_compound_data_tmp;
-create public synonym ut_compound_data_diff_tmp for &&ut3_owner..ut_compound_data_diff_tmp;
 create public synonym ut_sonar_test_reporter for &&ut3_owner..ut_sonar_test_reporter;
 begin
   $if dbms_db_version.version = 12 and dbms_db_version.release >= 2 or dbms_db_version.version > 12 $then

diff --git a/source/create_user_synonyms.sql b/source/create_user_synonyms.sql
@@ -95,7 +95,6 @@ create or replace synonym &ut3_user..ut_file_mapper for &&ut3_owner..ut_file_map
 create or replace synonym &ut3_user..ut_key_value_pairs for &&ut3_owner..ut_key_value_pairs;
 create or replace synonym &ut3_user..ut_key_value_pair for &&ut3_owner..ut_key_value_pair;
 create or replace synonym &ut3_user..ut_compound_data_tmp for &&ut3_owner..ut_cursor_data;
-create or replace synonym &ut3_user..ut_compound_data_diff_tmp for &&ut3_owner..ut_compound_data_diff_tmp;
 create or replace synonym &ut3_user..ut_sonar_test_reporter for &&ut3_owner..ut_sonar_test_reporter;
 begin
   $if dbms_db_version.version = 12 and dbms_db_version.release >= 2 or dbms_db_version.version > 12 $then

diff --git a/source/expectations/data_values/ut_compound_data_diff_tmp.sql b/source/expectations/data_values/ut_compound_data_diff_tmp.sql
@@ -14,5 +14,13 @@ create global temporary table ut_compound_data_diff_tmp(
   */
   diff_id    raw(128),
   item_no    integer,
-  constraint ut_compound_data_diff_tmp_pk primary key(diff_id,item_no)
+  pk_hash    raw(128),
+  item_hash  raw(128),
+  duplicate_no integer,
+  constraint ut_compound_data_diff_tmp_uk1 unique (diff_id,duplicate_no,item_no,item_hash, pk_hash),
+  constraint ut_compound_data_diff_tmp_chk check(
+   item_no is not null and pk_hash is null and duplicate_no is null
+   or item_no is null and item_hash is not null and duplicate_no is not null
+   or item_no is null and pk_hash is not null and duplicate_no is not null
+   )
 ) on commit preserve rows;