MDEV-36761: Put NULL-aware cardinality estimation under new_mode flag

Olernov · Olernov · commit aa70eeac2cff · 2025-10-31T19:47:30.000+07:00
The NULL-aware index statistics fix is now controlled by the
FIX_INDEX_STATS_FOR_ALL_NULLS flag and disabled by default
for preserving execution plan stability in stable versions.

To enable:
  SET @@new_mode = 'FIX_INDEX_STATS_FOR_ALL_NULLS';

Or via command line:
  --new-mode=FIX_INDEX_STATS_FOR_ALL_NULLS

Or in configuration file:
  [mysqld]
  new_mode=FIX_INDEX_STATS_FOR_ALL_NULLS

`all_nulls_key_parts` bitmap is now calculated at set_statistics_for_table()
diff --git a/mysql-test/main/mysqld--help.result b/mysql-test/main/mysqld--help.result
@@ -743,7 +743,9 @@ The following specify which files/extra groups are read (specified before remain
  Number of seconds to wait for a block to be written to a
  connection before aborting the write
  --new-mode=name     Used to introduce new behavior to existing MariaDB
- versions. No currently supported values.
+ versions. Any combination of: 
+ FIX_INDEX_STATS_FOR_ALL_NULLS
+ Use 'ALL' to set all combinations.
  --note-verbosity=name 
  Verbosity level for note-warnings given to the user. See
  also @@sql_notes.. Any combination of: basic, 
diff --git a/mysql-test/main/null_aware_cardinality.result b/mysql-test/main/null_aware_cardinality.result
@@ -1,3 +1,4 @@
+SET @session_start_value = @@new_mode;
 # Small driving table
 CREATE TABLE t1 (a INT, b INT);
 INSERT INTO t1 VALUES (1, 1), (2, 2000),(3,300);
@@ -13,6 +14,7 @@ ANALYZE TABLE t2 PERSISTENT FOR ALL;
 Table	Op	Msg_type	Msg_text
 test.t2	analyze	status	Engine-independent statistics collected
 test.t2	analyze	status	Table is already up to date
+SET @@new_mode = "FIX_INDEX_STATS_FOR_ALL_NULLS";
 # NULL-rejecting equality t1.b = t2.b will not return any matches
 # because all values of t2.b are NULL. So "rows" = 1 for t2 where 1 is
 # a special value meaning "very few" rows
@@ -30,10 +32,6 @@ id	select_type	table	type	possible_keys	key	key_len	ref	rows	filtered	Extra
 1	SIMPLE	t2	ref	key_b	key_b	5	test.t1.b	11	100.00	Using index condition; Using where
 Warnings:
 Note	1003	select `test`.`t1`.`a` AS `a`,`test`.`t1`.`b` AS `b`,`test`.`t2`.`a` AS `a`,`test`.`t2`.`b` AS `b` from `test`.`t1` join `test`.`t2` where `test`.`t2`.`a` = `test`.`t1`.`a` and `test`.`t1`.`b` <=> `test`.`t2`.`b`
-ANALYZE SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b <=> t2.b;
-id	select_type	table	type	possible_keys	key	key_len	ref	rows	r_rows	filtered	r_filtered	Extra
-1	SIMPLE	t1	ALL	NULL	NULL	NULL	NULL	3	3.00	100.00	100.00	
-1	SIMPLE	t2	ref	key_b	key_b	5	test.t1.b	11	0.00	100.00	100.00	Using index condition; Using where
 # Insert some non-NULL values and re-collect the stats
 INSERT INTO t2 SELECT 1, 1 FROM seq_1_to_100;
 ANALYZE TABLE t2 PERSISTENT FOR COLUMNS (b) INDEXES (key_b);
@@ -82,12 +80,21 @@ id	select_type	table	type	possible_keys	key	key_len	ref	rows	filtered	Extra
 1	SIMPLE	t3	ref	key_ab	key_ab	10	test.t1.a,const	11	100.00	Using where; Using index
 Warnings:
 Note	1003	select `test`.`t1`.`a` AS `a`,`test`.`t1`.`b` AS `b`,`test`.`t3`.`a` AS `a`,`test`.`t3`.`b` AS `b` from `test`.`t1` join `test`.`t3` where `test`.`t3`.`a` = `test`.`t1`.`a` and `test`.`t3`.`b` is null
+# In the old mode (null-aware estimation is not enabled), "rows" > 1
+SET @@new_mode = "";
+EXPLAIN EXTENDED SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b = t2.b;
+id	select_type	table	type	possible_keys	key	key_len	ref	rows	filtered	Extra
+1	SIMPLE	t1	ALL	NULL	NULL	NULL	NULL	3	100.00	Using where
+1	SIMPLE	t2	ref	key_b	key_b	5	test.t1.b	100	100.00	Using where
+Warnings:
+Note	1003	select `test`.`t1`.`a` AS `a`,`test`.`t1`.`b` AS `b`,`test`.`t2`.`a` AS `a`,`test`.`t2`.`b` AS `b` from `test`.`t1` join `test`.`t2` where `test`.`t2`.`a` = `test`.`t1`.`a` and `test`.`t2`.`b` = `test`.`t1`.`b`
 # Insert some non-NULL values and re-collect the stats
 INSERT INTO t3 SELECT 1, 1 FROM seq_1_to_100;
 ANALYZE TABLE t3 PERSISTENT FOR COLUMNS (b) INDEXES (key_ab);
 Table	Op	Msg_type	Msg_text
 test.t3	analyze	status	Engine-independent statistics collected
 test.t3	analyze	status	OK
+SET @@new_mode = "FIX_INDEX_STATS_FOR_ALL_NULLS";
 EXPLAIN EXTENDED SELECT * FROM t1 JOIN t3 ON t1.a = t3.a AND t1.b = t3.b;
 id	select_type	table	type	possible_keys	key	key_len	ref	rows	filtered	Extra
 1	SIMPLE	t1	ALL	NULL	NULL	NULL	NULL	3	100.00	Using where
@@ -147,4 +154,5 @@ EXPLAIN SELECT * FROM t1, t2 WHERE t2.a=t1.a AND t2.b=t1.a;
 id	select_type	table	type	possible_keys	key	key_len	ref	rows	Extra
 1	SIMPLE	t1	ALL	NULL	NULL	NULL	NULL	10	Using where
 1	SIMPLE	t2	ref	i1	i1	21	test.t1.a,test.t1.a	1	Using where
+SET @@new_mode = @session_start_value;
 DROP TABLE t1, t2;
diff --git a/mysql-test/main/null_aware_cardinality.test b/mysql-test/main/null_aware_cardinality.test
@@ -1,5 +1,7 @@
 --source include/have_sequence.inc
 
+SET @session_start_value = @@new_mode;
+
 --echo # Small driving table
 CREATE TABLE t1 (a INT, b INT);
 INSERT INTO t1 VALUES (1, 1), (2, 2000),(3,300);
@@ -13,6 +15,8 @@ INSERT INTO t2 SELECT seq/100,  NULL FROM seq_1_to_1000;
 
 ANALYZE TABLE t2 PERSISTENT FOR ALL;
 
+SET @@new_mode = "FIX_INDEX_STATS_FOR_ALL_NULLS";
+
 --echo # NULL-rejecting equality t1.b = t2.b will not return any matches
 --echo # because all values of t2.b are NULL. So "rows" = 1 for t2 where 1 is
 --echo # a special value meaning "very few" rows
@@ -22,8 +26,6 @@ EXPLAIN EXTENDED SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b = t2.b;
 --echo # must not be affected ("rows" > 1 is expected)
 EXPLAIN EXTENDED SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b <=> t2.b;
 
-ANALYZE SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b <=> t2.b;
-
 --echo # Insert some non-NULL values and re-collect the stats
 INSERT INTO t2 SELECT 1, 1 FROM seq_1_to_100;
 
@@ -50,11 +52,16 @@ EXPLAIN EXTENDED SELECT * FROM t1 JOIN t3 ON t1.a = t3.a AND t1.b <=> t3.b;
 
 EXPLAIN EXTENDED SELECT * FROM t1 JOIN t3 ON t1.a = t3.a AND t3.b is NULL;
 
+--echo # In the old mode (null-aware estimation is not enabled), "rows" > 1
+SET @@new_mode = "";
+EXPLAIN EXTENDED SELECT * FROM t1 JOIN t2 ON t1.a = t2.a AND t1.b = t2.b;
+
 --echo # Insert some non-NULL values and re-collect the stats
 INSERT INTO t3 SELECT 1, 1 FROM seq_1_to_100;
 
 ANALYZE TABLE t3 PERSISTENT FOR COLUMNS (b) INDEXES (key_ab);
 
+SET @@new_mode = "FIX_INDEX_STATS_FOR_ALL_NULLS";
 EXPLAIN EXTENDED SELECT * FROM t1 JOIN t3 ON t1.a = t3.a AND t1.b = t3.b;
 
 --echo # Test composite index for 3 columns. Key prefix is used for access
@@ -92,4 +99,5 @@ ANALYZE TABLE t2 PERSISTENT FOR COLUMNS (b) INDEXES (i1);
 
 EXPLAIN SELECT * FROM t1, t2 WHERE t2.a=t1.a AND t2.b=t1.a;
 
+SET @@new_mode = @session_start_value;
 DROP TABLE t1, t2;
diff --git a/mysql-test/suite/sys_vars/r/new_mode.result b/mysql-test/suite/sys_vars/r/new_mode.result
@@ -25,7 +25,7 @@ ERROR 42000: Variable 'new_mode' can't be set to the value of 'TEST_WARNING3'
 SET @@session.new_mode = "ALL";
 select @@session.new_mode;
 @@session.new_mode
-
+FIX_INDEX_STATS_FOR_ALL_NULLS
 SET @@global.new_mode = NULL;
 ERROR 42000: Variable 'new_mode' can't be set to the value of 'NULL'
 SET @@global.new_mode = '';
diff --git a/mysql-test/suite/sys_vars/r/sysvars_server_embedded.result b/mysql-test/suite/sys_vars/r/sysvars_server_embedded.result
@@ -2319,7 +2319,7 @@ VARIABLE_COMMENT	Used to introduce new behavior to existing MariaDB versions
 NUMERIC_MIN_VALUE	NULL
 NUMERIC_MAX_VALUE	NULL
 NUMERIC_BLOCK_SIZE	NULL
-ENUM_VALUE_LIST	
+ENUM_VALUE_LIST	FIX_INDEX_STATS_FOR_ALL_NULLS
 READ_ONLY	NO
 COMMAND_LINE_ARGUMENT	REQUIRED
 VARIABLE_NAME	NOTE_VERBOSITY
diff --git a/mysql-test/suite/sys_vars/r/sysvars_server_notembedded.result b/mysql-test/suite/sys_vars/r/sysvars_server_notembedded.result
@@ -2529,7 +2529,7 @@ VARIABLE_COMMENT	Used to introduce new behavior to existing MariaDB versions
 NUMERIC_MIN_VALUE	NULL
 NUMERIC_MAX_VALUE	NULL
 NUMERIC_BLOCK_SIZE	NULL
-ENUM_VALUE_LIST	
+ENUM_VALUE_LIST	FIX_INDEX_STATS_FOR_ALL_NULLS
 READ_ONLY	NO
 COMMAND_LINE_ARGUMENT	REQUIRED
 VARIABLE_NAME	NOTE_VERBOSITY
diff --git a/sql/sql_class.h b/sql/sql_class.h
@@ -219,7 +219,8 @@ void old_mode_deprecated_warnings(THD *thd, ulonglong v);
   See sys_vars.cc /new_mode_all_names
 */
 
-#define NEW_MODE_MAX                                                         0
+#define NEW_MODE_FIX_INDEX_STATS_FOR_ALL_NULLS                      (1ULL << 0)
+#define NEW_MODE_MAX                                                         1
 
 /* Definitions above that have transitioned from new behaviour to default */
 
diff --git a/sql/sql_select.cc b/sql/sql_select.cc
@@ -13450,6 +13450,7 @@ static bool create_hj_key_for_table(JOIN *join, JOIN_TAB *join_tab,
   keyinfo->algorithm= HA_KEY_ALG_UNDEF;
   keyinfo->flags= HA_GENERATED_KEY;
   keyinfo->is_statistics_from_stat_tables= FALSE;
+  keyinfo->all_nulls_key_parts= 0;
   keyinfo->name.str= "$hj";
   keyinfo->name.length= 3;
   keyinfo->rec_per_key= (ulong*) thd->calloc(sizeof(ulong)*key_parts);
@@ -22432,6 +22433,7 @@ bool Create_tmp_table::finalize(THD *thd,
     keyinfo->collected_stats= NULL;
     keyinfo->algorithm= HA_KEY_ALG_UNDEF;
     keyinfo->is_statistics_from_stat_tables= FALSE;
+    keyinfo->all_nulls_key_parts= 0;
     keyinfo->name= group_key;
     keyinfo->comment.str= 0;
     ORDER *cur_group= m_group;
@@ -22553,6 +22555,7 @@ bool Create_tmp_table::finalize(THD *thd,
     keyinfo->name= distinct_key;
     keyinfo->algorithm= HA_KEY_ALG_UNDEF;
     keyinfo->is_statistics_from_stat_tables= FALSE;
+    keyinfo->all_nulls_key_parts= 0;
     keyinfo->read_stats= NULL;
     keyinfo->collected_stats= NULL;
 
diff --git a/sql/sql_statistics.cc b/sql/sql_statistics.cc
@@ -4156,11 +4156,35 @@ void set_statistics_for_table(THD *thd, TABLE *table)
   for (key_info= table->key_info, key_info_end= key_info+table->s->keys;
        key_info < key_info_end; key_info++)
   {
+    key_info->all_nulls_key_parts= 0;
     key_info->is_statistics_from_stat_tables=
-      (check_eits_preferred(thd) &&
-       table->stats_is_read &&
-       key_info->read_stats->avg_frequency_is_inited() &&
-       key_info->read_stats->has_stats());
+        (check_eits_preferred(thd) &&
+         table->stats_is_read &&
+         key_info->read_stats->avg_frequency_is_inited() &&
+         key_info->read_stats->has_stats(thd));
+
+    // Fill out `all_nulls_key_parts` bitmap
+    if (TEST_NEW_MODE_FLAG(thd, NEW_MODE_FIX_INDEX_STATS_FOR_ALL_NULLS) &&
+        key_info->is_statistics_from_stat_tables)
+    {
+      for (uint part_idx= 0; part_idx < key_info->usable_key_parts; part_idx++)
+      {
+        Field *field=
+            table->field[key_info->key_part[part_idx].field->field_index];
+        if (!field->read_stats)
+        {
+          // No column statistics available
+          continue;
+        }
+
+        // Check if all values in this column are NULL according to statistics
+        double nulls_ratio= field->read_stats->get_nulls_ratio();
+        if (nulls_ratio == 1.0)
+        {
+          key_info->all_nulls_key_parts |= (1 << part_idx);
+        }
+      }
+    }
   }
 }
 
diff --git a/sql/sql_statistics.h b/sql/sql_statistics.h
@@ -606,7 +606,6 @@ class Index_statistics
   bool stats_were_read;
 
 public:
-
   void init_avg_frequency(ulonglong *ptr)
   {
     avg_frequency= ptr;
@@ -615,7 +614,13 @@ class Index_statistics
 
   void mark_stats_as_read() { stats_were_read= true; }
 
-  bool has_stats() const { return stats_were_read; }
+  bool has_stats(THD *thd) const
+  {
+    if (TEST_NEW_MODE_FLAG(thd, NEW_MODE_FIX_INDEX_STATS_FOR_ALL_NULLS))
+      return stats_were_read;
+    else
+      return get_avg_frequency(0) > 0.5;
+  }
 
   bool avg_frequency_is_inited() { return avg_frequency != NULL; }
 
diff --git a/sql/structs.h b/sql/structs.h
@@ -171,6 +171,14 @@ typedef struct st_key {
   engine_option_value *option_list;
   ha_index_option_struct *option_struct;                  /* structure with parsed options */
 
+  /*
+    Bitmap of key parts where all values are NULL (nulls_ratio == 1.0).
+    Bit N set means key part N has all NULLs in the corresponding column.
+    Used for NULL-aware cardinality estimation.
+    It is computed based on EITS data, otherwise it is 0.
+  */
+  key_part_map all_nulls_key_parts;
+
   double actual_rec_per_key(uint last_key_part_in_prefix) const;
   double rec_per_key_null_aware(uint last_key_part_in_prefix,
                                 key_part_map notnull_part) const;
diff --git a/sql/sys_vars.cc b/sql/sys_vars.cc
@@ -4055,15 +4055,16 @@ static Sys_var_set Sys_old_behavior(
 */
 static const char *new_mode_all_names[]=
 {
+  "FIX_INDEX_STATS_FOR_ALL_NULLS",
   "TEST_WARNING1",                       // Default from here, See NEW_MODE_MAX
   "TEST_WARNING2",
   0
 };
 
 static int new_mode_hidden_names[] =
 {
-  0,  // TEST_WARNING1
-  1,  // TEST_WARNING2
+  1,  // TEST_WARNING1
+  2,  // TEST_WARNING2
   -1  // End of list
 };
 
diff --git a/sql/table.cc b/sql/table.cc
@@ -8642,6 +8642,7 @@ bool TABLE::add_tmp_key(uint key, uint key_parts,
   bzero(keyinfo->rec_per_key, sizeof(ulong)*key_parts);
   keyinfo->read_stats= NULL;
   keyinfo->collected_stats= NULL;
+  keyinfo->all_nulls_key_parts= 0;
 
   for (i= 0; i < key_parts; i++)
   {
@@ -10304,7 +10305,8 @@ uint TABLE_SHARE::actual_n_key_parts(THD *thd)
   Prefers engine-independent statistics (EITS) if available and falls back
   to engine-dependent statistics otherwise.
 
-  @param max_key_part  Index of the last key part in the prefix (0-based)
+  @param last_key_part_in_prefix  Index of the last key part
+                                  in the prefix (0-based)
 
   @return  Estimated records per key value:
            - 0.0 if no statistics available
@@ -10331,7 +10333,8 @@ double KEY::actual_rec_per_key(uint last_key_part_in_prefix) const
   the query uses NULL-rejecting conditions (e.g., =), returns 1.0 to indicate
   high selectivity since NULL = NULL never matches.
 
-  @param max_key_part  Index of the last key part in the prefix (0-based)
+  @param last_key_part_in_prefix  Index of the last key part
+                                  in the prefix (0-based)
   @param notnull_part  Bitmap indicating which key parts have NULL-rejecting
                        conditions (bit N set means key part N uses =, not <=>)
 
@@ -10344,60 +10347,19 @@ double KEY::actual_rec_per_key(uint last_key_part_in_prefix) const
 double KEY::rec_per_key_null_aware(uint last_key_part_in_prefix,
                                    key_part_map notnull_part) const
 {
-  if (!is_statistics_from_stat_tables)
+  if (notnull_part & all_nulls_key_parts)
   {
-    // Fall back to engine-dependent statistics if EITS is not available
-    return rec_per_key ? (double) rec_per_key[last_key_part_in_prefix] : 0.0;
+    /*
+      For NULL-rejecting conditions like `t1.key_col = t2.col`, we know
+      there will be no matches (since NULL = NULL is never true).
+      If at least one NULL-rejecting condition is present, and all
+      corresponding key part values are NULL, return number of records 1.0
+      (highly selective), indicating no expected matches.
+    */
+    return 1.0;
   }
 
-  // Use engine-independent statistics (EITS)
-  double records= read_stats->get_avg_frequency(last_key_part_in_prefix);
-  if (records != 0.0)
-    return records;
-
-  /*
-    The index statistics show avg_frequency == 0 for this index prefix.
-    This typically means all values in the indexed columns are NULL.
-
-    For NULL-rejecting conditions like `t1.key_col = t2.col`, we know
-    there will be no matches (since NULL = NULL is never true).
-    However, for non-NULL-rejecting conditions like `t1.key_col <=> t2.col`,
-    matches are possible.
-
-    Check each key part in the prefix: if any key part has a NULL-rejecting
-    condition (indicated by bit set in `notnull_part`) and the statistics
-    confirm all values are NULL (nulls_ratio == 1.0), we can return 1.0
-    (highly selective estimate) instead of 0.0 (unknown), indicating
-    no expected matches.
-  */
-  for (int bit= last_key_part_in_prefix; bit >= 0; bit--)
-  {
-    key_part_map mask = (key_part_map)1 << bit;
-    if ((notnull_part & mask) == 0)
-    {
-      // Non-NULL-rejecting condition for the key part
-      continue;
-    }
-
-    Field *field= table->field[key_part[bit].field->field_index];
-    if (!field->read_stats)
-    {
-      // No column statistics available
-      continue;
-    }
-
-    // Check if all values in this column are NULL according to statistics
-    double nulls_ratio= field->read_stats->get_nulls_ratio();
-    if (nulls_ratio == 1.0)
-    {
-      /*
-        All values are NULL and the condition is NULL-rejecting.
-        Return 1.0 (highly selective), indicating no expected matches.
-      */
-      return 1.0;
-    }
-  }
-  return records;
+  return actual_rec_per_key(last_key_part_in_prefix);
 }
 
 /*
