[CBRD-27040] Document that WITH FULLSCAN falls back to sampling above the heap page limit

en/admin/config.rst

@@ -407,6 +407,8 @@ On the below table, if "Applied" is "server parameter", that parameter affects t
 |                               | enable_memory_monitoring            | client/server parameter |         | bool     | no                             |                       |
 |                               +-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------------+
 |                               | flashback_timeout                   | client parameter        |         | int      | 300                            |                       |
+|                               +-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------------+
+|                               | stats_fullscan_max_pages            | client parameter        | O       | int      | 10,000                         | available             |
 +-------------------------------+-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------------+
 
 .. _lpg:
@@ -2270,6 +2272,8 @@ The following are other parameters. The type and value range for each parameter
 +-------------------------------------+--------+----------------+----------------+----------------+
 | flashback_timeout                   | int    | 300            | 0              | 3600           |
 +-------------------------------------+--------+----------------+----------------+----------------+
+| stats_fullscan_max_pages            | int    | 10,000         | 0              |                |
++-------------------------------------+--------+----------------+----------------+----------------+
 
 **access_ip_control**
 
@@ -2511,6 +2515,21 @@ The following are other parameters. The type and value range for each parameter
 
  It specifies the timeout for entering a transaction identifier in the flashback utility. If a transaction to be rewind is not entered within the specified timeout, an error message will be displayed, and the flashback utility will terminate. If there is no timeout, it may cause an issue where the archive log volumes required by the flashback utility are not deleted. Therefore, a method to remove the timeout is not provided. The default value is 300 seconds.
 
+.. _stats_fullscan_max_pages:
+
+**stats_fullscan_max_pages**
+
+    **stats_fullscan_max_pages** is a parameter that specifies the upper limit on the number of heap pages for which column statistics are collected with all the data of the table when **WITH FULLSCAN** is specified in the **UPDATE STATISTICS** statement. If the number of heap pages of the target table exceeds this value, the column statistics are collected with sampling data. The default value is **10,000** and the minimum value is **0**. This parameter is supported from version 11.4 Patch 6 of CUBRID.
+
+    If this parameter is set to **0**, the upper limit is not applied and **WITH FULLSCAN** always collects the column statistics with all the data of the table.
+
+    For more information, see :ref:`update-statistics`.
+
+    The following is an example of setting the parameter so that the upper limit is not applied. ::
+
+        stats_fullscan_max_pages=0
+
+
 .. _broker-configuration:
 
 Broker Configuration

en/sql/tuning.rst

@@ -4,6 +4,8 @@
 
 .. include:: join_method.inc
 
+.. _update-statistics:
+
 Updating Statistics
 ===================
 
@@ -26,7 +28,7 @@ The user can delete plan cache using the **PLANDUMP** utility. For more informat
 
     UPDATE STATISTICS ON CATALOG CLASSES [WITH FULLSCAN]; 
 
-*   **WITH FULLSCAN**: It updates the statistics with all the data in the specified table. If this is omitted, it updates the statistics with sampling data. The sampling data is 5000 pages regardless of total pages of table.
+*   **WITH FULLSCAN**: It updates the statistics with all the data in the specified table. If this is omitted, it updates the statistics with sampling data. The sampling data is 5000 pages regardless of total pages of table. From version 11.4 Patch 6 of CUBRID, if the number of heap pages of the table exceeds the value of the :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>` parameter, the column statistics are collected with sampling data even if **WITH FULLSCAN** is specified.
 
 *   **ALL CLASSES**: If the **ALL CLASSES** keyword is specified, the statistics on all the tables existing in the database are updated.
 
@@ -82,6 +84,23 @@ When starting and ending an update of statistics information, NOTIFICATION messa
 
     From version 11.4 of CUBRID,  **SELECT** authorization is required when executing **UPDATE STATISTICS** statement.
 
+.. note::
+
+    From version 11.4 Patch 6 of CUBRID, if the number of heap pages of the table exceeds the value of the :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>` parameter, the column statistics are collected with sampling data as if **WITH FULLSCAN** were omitted. This bounds the time to compute the *Number of Distinct Values* of each column by reading the entire target table. The *Number of Distinct Values* collected in this case is an estimate.
+
+    For a partitioned table, the heap pages of all partitions are summed for this decision. The column statistics are also collected with sampling data when the number of heap pages cannot be determined.
+
+    Index (B+tree) statistics are not affected by this change; they are collected with all the data of the table as specified by **WITH FULLSCAN**.
+
+    To collect the column statistics with all the data of the table, set :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>` to a value greater than the number of heap pages of the target table or to **0**, and then execute the **UPDATE STATISTICS** statement again.
+
+    When **WITH FULLSCAN** is changed to sampling, the following NOTIFICATION message is written on the client error log. You can check which table's column statistics were collected as estimates and the number of heap pages of that table by this message.
+
+    ::
+
+        Time: 09/04/26 11:33:46.772 - NOTIFICATION *** file ../../src/storage/statistics_cl.c, line 562  CODE = -1371, Tran = 1, EID = 3
+        WITH FULLSCAN is downgraded to sampling (class "dba.large_table", heap pages : 10965, stats_fullscan_max_pages : 10000).
+
 .. _info-stats:
 
 Checking Statistics Information

ko/admin/config.rst

@@ -407,6 +407,8 @@
 |                               | enable_memory_monitoring            | 클라이언트/서버         |         | bool     | no                             |                 |
 |                               +-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------+
 |                               | flashback_timeout                   | 클라이언트              |         | int      | 300                            |                 |
+|                               +-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------+
+|                               | stats_fullscan_max_pages            | 클라이언트              | O       | int      | 10,000                         | 가능            |
 +-------------------------------+-------------------------------------+-------------------------+---------+----------+--------------------------------+-----------------+
 
 .. _lpg:
@@ -834,7 +836,7 @@
 
 **double_write_buffer_size**
 
     **double_write_buffer_size** 는 이중 쓰기 버퍼 (Double Write Buffer, DWB)의 메모리와 디스크 공간을 설정할 수 있는 파라미터이다. 이 크기를 0으로 설정함으로써 Partial I/O를 방지하기 위한 DWB를 사용하지 않을 수 있다. 기본적으로 DWB는 활성화되어 있으며, 기본값은 **2M** 이다.  
     해당 값은 **바이트 단위(byte)**로 동작하므로, 최소 2,097,152 바이트에서 최대 33,554,432 바이트 사이의 값으로 설정해야 한다.
 
 **data_file_os_advise**
@@ -2245,6 +2247,8 @@
 +-------------------------------------+--------+----------------+----------------+----------------+
 | flashback_timeout                   | int    | 300            | 0              | 3600           |
 +-------------------------------------+--------+----------------+----------------+----------------+
+| stats_fullscan_max_pages            | int    | 10,000         | 0              |                |
++-------------------------------------+--------+----------------+----------------+----------------+
 
 **access_ip_control**
 
@@ -2486,6 +2490,21 @@
 
  flashback 유틸리티 실행 시, 사용자가 되돌릴 트랜잭션 식별자를 입력해야 하는 제한 시간을 설정한다. 설정된 제한 시간 이내에 트랜잭션 식별자를 입력하지 않으면 오류 메시지를 출력하고 flashback 유틸리티는 종료된다. 트랜잭션을 되돌리기 위해 보관 로그 볼륨을 계속 참조하기 때문에 제한 시간이 없다면 보관 로그 볼륨들이 삭제되지 못하고 쌓이는 문제가 발생할 수 있다. 따라서 무제한 대기를 위한 설정값은 제공하지 않으며 기본값은 300초이다.
 
+.. _stats_fullscan_max_pages:
+
+**stats_fullscan_max_pages**
+
+    **stats_fullscan_max_pages**\ 는 **UPDATE STATISTICS** 문에 **WITH FULLSCAN**\ 을 지정했을 때 테이블 전체 데이터로 칼럼 통계를 수집할 힙 페이지 개수의 상한을 지정하는 파라미터이다. 대상 테이블의 힙 페이지 개수가 이 값을 초과하면 칼럼 통계는 샘플링한 데이터로 수집된다. 기본값은 **10,000**\ 이며, 최소값은 **0**\ 이다. 이 파라미터는 CUBRID 11.4 Patch 6부터 지원한다.
+
+    이 파라미터가 **0**\ 으로 설정되면 상한을 적용하지 않으며, **WITH FULLSCAN**\ 은 항상 테이블 전체 데이터로 칼럼 통계를 수집한다.
+
+    자세한 내용은 :ref:`update-statistics`\ 를 참고한다.
+
+    다음은 상한을 적용하지 않도록 설정하는 예제이다. ::
+
+        stats_fullscan_max_pages=0
+
+
 .. _broker-configuration:
 
 브로커 설정

ko/sql/tuning.rst

@@ -3,6 +3,8 @@
 
 .. include:: join_method.inc
 
+.. _update-statistics:
+
 통계 정보 갱신
 ==============
 
@@ -25,7 +27,7 @@
 
     UPDATE STATISTICS ON CATALOG CLASSES [WITH FULLSCAN]; 
 
-*   **WITH FULLSCAN**: 지정된 테이블의 전체 데이터를 가지고 통계 정보를 업데이트한다. 생략 시 샘플링한 데이터를 가지고 통계 정보를 업데이트한다. 데이터 샘플은 테이블 전체 페이지 수와 상관없이 5000페이지이다.
+*   **WITH FULLSCAN**: 지정된 테이블의 전체 데이터를 가지고 통계 정보를 업데이트한다. 생략 시 샘플링한 데이터를 가지고 통계 정보를 업데이트한다. 데이터 샘플은 테이블 전체 페이지 수와 상관없이 5000페이지이다. CUBRID 11.4 Patch 6부터는 테이블의 힙 페이지 개수가 :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>` 파라미터의 값을 초과하면 **WITH FULLSCAN**\ 을 지정해도 칼럼 통계가 샘플링한 데이터로 수집된다.
 
 *   **ALL CLASSES**: 모든 테이블의 통계 정보를 업데이트한다. 
 
@@ -81,6 +83,23 @@
 
     CUBRID 11.4 부터는  **UPDATE STATISTICS** 문을 실행할 때 **SELECT** 권한이 필요하다.
 
+.. note::
+
+    CUBRID 11.4 Patch 6부터는 테이블의 힙 페이지 개수가 :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>` 파라미터의 값을 초과하면 **WITH FULLSCAN**\ 을 생략한 경우와 같이 샘플링한 데이터로 칼럼 통계를 수집한다. 칼럼의 *Number of Distinct Values*\ 를 대상 테이블 전체를 읽어 계산하는 데 걸리는 시간을 제한하기 위한 것이다. 이때 수집된 *Number of Distinct Values*\ 는 추정치이다.
+
+    파티션 테이블은 각 파티션의 힙 페이지 개수를 합산하여 판정한다. 힙 페이지 개수를 확인할 수 없는 경우에도 샘플링한 데이터로 수집한다.
+
+    인덱스(B+tree) 통계는 이 전환의 대상이 아니며, **WITH FULLSCAN**\ 을 지정한 대로 테이블 전체 데이터로 수집한다.
+
+    테이블 전체 데이터로 칼럼 통계를 수집해야 하는 경우에는 :ref:`stats_fullscan_max_pages <stats_fullscan_max_pages>`\ 의 값을 대상 테이블의 힙 페이지 개수보다 크게 설정하거나 **0**\ 으로 설정한 후 **UPDATE STATISTICS** 문을 다시 수행한다.
+
+    샘플링 방식으로 전환될 때 클라이언트 에러 로그에 다음과 같은 NOTIFICATION 메시지를 출력하며, 이를 통해 어떤 테이블의 칼럼 통계가 추정치로 수집되었는지와 그 테이블의 힙 페이지 개수를 확인할 수 있다.
+
+    ::
+
+        Time: 09/04/26 11:33:46.772 - NOTIFICATION *** file ../../src/storage/statistics_cl.c, line 562  CODE = -1371, Tran = 1, EID = 3
+        WITH FULLSCAN is downgraded to sampling (class "dba.large_table", heap pages : 10965, stats_fullscan_max_pages : 10000).
+
 .. _info-stats:
 
 통계 정보 확인