# DBE_ILM
#### 接口介绍
服务于ILM策略实施，实现ILM策略的评估以及压缩Job的停用接口。DBE_ILM支持的接口请参见[表1]。
 表1DBE_ILM 
| 接口名称                                                                  | 描述                                       |
|:---|:---|
| [DBE_ILM.EXECUTE_ILM]    | 根据参数执行对指定的数据和ILM策略进行评估，评估通过则会生成对应的压缩Job。 |
| [DBE_ILM.STOP_ILM] | 根据参数停止正在执行的压缩Job。                        |
   
- DBE_ILM.EXECUTE_ILM
  根据参数执行对指定的数据和ILM策略进行评估，评估通过则会生成对应的压缩Job。
  DBE_ILM.EXECUTE_ILM原型为：
  ```
  DBE_ILM.EXECUTE_ILM(
  OWNER          IN VARCHAR2,
  OBJECT_NAME    IN VARCHAR2,
  TASK_ID        OUT NUMBER,
  SUBOBJECT_NAME IN VARCHAR2 DEFAULT NULL,
  POLICY_NAME    IN VARCHAR2 DEFAULT 'ALL POLICIES',
  EXECUTION_MODE IN NUMBER DEFAULT 2
  TURBO_FORCE    IN BOOLEAN DEFAULT FALSE, 
  TURBO_BLKSTART IN INTEGER DEFAULT -1, 
  TURBO_BLKEND   IN INTEGER DEFAULT -1)
  ```
  表2DBE_ILM.EXECUTE_ILM接口参数说明 
  | 参数 | 描述                                                                                                                                                            |
  |:---|:---|
  | OWNER                                        | 对象所属Schema。                                                                                                                                                   |
  | OBJECT_NAME                                  | 对象名称。                                                                                                                                                                                                   |
  | TASK_ID                                       | 输出生成ADO task的描述符id。                                                                                                                                                                                     |
  | SUBOBJECT_NAME                               | 数据子对象名称。                                                                                                                                                                                                  |
  | POLICY_NAME                                 | 策略名称，通过查询[GS_ADM_ILMOBJECTS](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/gaussdb-38-1317.html)视图可知，默认DBE_ILM.ILM_ALL_POLICIES代表该对象上所有策略。DBE_ILM.ILM_ALL_POLICIES默认值为'ALL POLICIES'，不支持小写。 |
  | EXECUTION_MODE                               | 执行模式，暂不涉及在线模式（ILM_EXECUTION_ONLINE）或离线模式（ILM_EXECUTION_OFFLINE）。                                                                                                                                         |
  | TURBO_FORCE                                   | 是否开启忽略冷热管理的强制压缩，仅对跨页透明压缩生效。TRUE表示开启，FALSE表示关闭。                                                                                                                                                           |
  | TURBO_BLKSTART                              | 强制压缩开始的block number，仅对跨页透明压缩生效。                                                                                                                                                                          |
  | TURBO_BLKEND                                  | 强制压缩结束的block number，仅对跨页透明压缩生效。                                                                                                                                                                          |
     
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  - DBE_ILM.EXECUTE_ILM依据当前数据库名及表名，生成类似"数据库名_表名_分区名_数字"格式的JOBNAME命名规则，然后通过DBE_SCHEDULER.Create_job创建对应名称的任务；当表名包含特殊字符时，调用该接口将报错：Invalid program name。
  
  - 当DBE_ILM.EXECUTE_ILM与DBE_ILM.STOP_ILM并发时，有较低概率会导致任务FAILED，gs_adm_ilmresults视图中comments字段内容显示"tuple concurrently updated"。
  
  - 业务进行压缩操作时（无论是自动调度还是手动调度），应尽可能避免对压缩中的相关表进行DDL操作。特别是在一段长事务中执行DDL，可能会引发死锁或锁等待问题。若确有必要进行DDL操作，建议使用DBE_ILM.STOP_ILM接口将相关表的压缩任务停止，确认停止后再进行DDL操作。
  
  - 执行DBE_ILM.EXECUTE_ILM需要拥有PUBLIC权限及CREATE JOB权限，可通过dbe_scheduler.grant_user_authorization进行赋权，非SYSADMIN用户执行需要表的owner权限。
  
  - 若要压缩二级分区，SUBOBJECT_NAME字段不可传入其一级分区名称，需传入具体的二级分区名称（或者传入NULL，即压缩所有子二级分区）。
  
  - 事务内调用此接口，需要等待事务结束、或者COMMIT后，压缩动作才能生效。多个不同事务内调用DBE_ILM.EXECUTE_ILM接口，先执行的事务若一直不提交，后执行的事务可能存在锁超时风险。
  
  - TURBO_FORCE参数的不同取值，对gs_adm_ilmresults视图有不同影响：
    - 当指定为FALSE时：由于gs_adm_ilmresults视图中的statistics字段统计内容本身对跨页透明压缩无意义，因此跨页透明压缩对象在该字段中显示为默认值。
    
    - 当指定为TRUE时：当前压缩任务独立于ILM原有的任务划分机制运行，不对该对象进行statistics统计，因此gs_adm_ilmresults视图中的statistics字段显示为空。
     
    
- DBE_ILM.STOP_ILM
  根据参数停止正在执行的ILM策略。
  DBE_ILM.STOP_ILM原型为：
  ```
  DBE_ILM.STOP_ILM(
  TASK_ID             IN NUMBER DEFAULT -1,
  P_DROP_RUNNING_JOBS IN BOOLEAN DEFAULT FALSE,
  P_JOBNAME           IN VARCHAR2 DEFAULT NULL)
  ```
  表3DBE_ILM.STOP_ILM接口参数说明 
  | 参数                   | 描述                                                                                                                                     |
  |:---|:---|
  | TASK_ID             | 指定待停止ADO task的描述符id。                                                                                                                   |
  | P_DROP_RUNNING_JOBS | 是否停止正在执行中的任务，true为强制停止，false为不停止正在执行的任务。                                                                                                 |
  | P_JOBNAME          | 标识待停止的特定JobName，通过[GS_MY_ILMEVALUATIONDETAILS](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/gaussdb-38-1323.html)视图可以查询。 |
     
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  当并发量较大时，执行DBE_ILM.STOP_ILM可能会提示资源繁忙，稍后重试即可。提示内容为"Resources are busy, please try again later"。
  
 
#### 示例
```
gaussdb=# ALTER DATABASE set ilm = on;
gaussdb=# CREATE Schema ILM_DATA;
gaussdb=# SET current_schema=ILM_DATA;
BEGIN
    DBE_ILM_ADMIN.DISABLE_ILM();
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(1, 15);
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(2, 30);
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(11, 1);
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(12, 10);
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(13, 1024);
    DBE_ILM_ADMIN.CUSTOMIZE_ILM(14, 240);
    DBE_ILM_ADMIN.ENABLE_ILM();
END;
/
-- 1.1.2 prepare test data
gaussdb=# CREATE SEQUENCE ILM_DATA.ORDER_TABLE_SE_ORDER_ID MINVALUE 1;
gaussdb=# CREATE OR REPLACE PROCEDURE ILM_DATA.ORDER_TABLE_CREATE_DATA(NUM INTEGER) IS
BEGIN
    FOR X IN 1..NUM
        LOOP
            INSERT INTO ORDER_TABLE VALUES(ORDER_TABLE_SE_ORDER_ID.nextval, '零食大礼包A', NOW());
        END LOOP;
    COMMIT;
END;
/
-- 1.1.3 normal procedure
-- 1.1.3.1 evaluate successed - all policy
gaussdb=# CREATE TABLE ILM_DATA.ORDER_TABLE (ORDER_ID INT, GOODS_NAME TEXT, CREATE_TIME TIMESTAMP)
    WITH (STORAGE_TYPE=ASTORE) ILM ADD POLICY ROW STORE COMPRESS ADVANCED ROW AFTER 1 DAYS OF NO MODIFICATION;
BEGIN
    ILM_DATA.ORDER_TABLE_CREATE_DATA(5);
    PERFORM PG_SLEEP(2);
END;
/
gaussdb=# SELECT ORDER_ID, DBE_COMPRESSION.GET_COMPRESSION_TYPE('ilm_data', 'order_table', ctid::text, NULL) FROM ILM_DATA.ORDER_TABLE;
 order_id | get_compression_type 
----------+----------------------
        1 |                    1
        2 |                    1
        3 |                    1
        4 |                    1
        5 |                    1
(5 rows)
gaussdb=# SELECT ORDER_ID, DBE_HEAT_MAP.ROW_HEAT_MAP('ilm_data','order_table', NULL, ctid::text) FROM ILM_DATA.ORDER_TABLE;
 order_id |                 row_heat_map                  
----------+-----------------------------------------------
        1 | (ilm_data,order_table,,,16799,16799,"(0,1)",)
        2 | (ilm_data,order_table,,,16799,16799,"(0,2)",)
        3 | (ilm_data,order_table,,,16799,16799,"(0,3)",)
        4 | (ilm_data,order_table,,,16799,16799,"(0,4)",)
        5 | (ilm_data,order_table,,,16799,16799,"(0,5)",)
(5 rows)
DECLARE
    v_taskid number;
BEGIN
    DBE_ILM.EXECUTE_ILM(OWNER        => 'ilm_data',
                        OBJECT_NAME    => 'order_table',
                        TASK_ID        => v_taskid,
                        SUBOBJECT_NAME => NULL,
                        POLICY_NAME    => 'ALL POLICIES',
                        EXECUTION_MODE => 2);
    RAISE INFO 'Task ID is:%', v_taskid;
END;
/
INFO:  Task ID is:1
gaussdb=# SELECT ORDER_ID, DBE_COMPRESSION.GET_COMPRESSION_TYPE('ilm_data', 'order_table', ctid::text, NULL) FROM ILM_DATA.ORDER_TABLE;
 order_id | get_compression_type 
----------+----------------------
        1 |                    1
        2 |                    1
        3 |                    1
        4 |                    1
        5 |                    1
(5 rows)
gaussdb=# CALL DBE_ILM.STOP_ILM(-1, true, NULL);
 stop_ilm 
----------
(1 row)
```
