调度日历配置完成后，在数据开发页面进行任务调度设置、临时查询、运维等操作时，即可按需选择相应的调度日历，来满足当前任务根据调度日历配置进行调度的需求。

在任务中使用日历 #

引用日历 #

打开某个离线计算任务，在右侧的调度设置面板中，用户可选择某个调度日历。详细说明可参见调度设置。

使用日历变量 #

引用此调度日历后，用户可在代码中使用 ${calendar_day} 、${calendar_month}的方式引用调度日历的日期。

支持天粒度、年粒度的二次计算，用户可通过加减的方式在调度日期、自然日中进行二次计算。

• ${calendar_day}、${calendar_month} 的取值逻辑：
  根据任务实例所在的定时时间，找到 Excel 中的第一列（date）所在的那一天，取第2列（schedule_date）的值。如上图：当任务的计划时间=2024年10月9日时，${calendar_day}的取值为2024年01月08日，${calendar_month}的取值为2024年10月。
• ${calendar_day} 的输出格式为 yyyyMMdd 格式、${calendar_month} 的输出格式为 yyyyMM 格式.
• ${calendar_day}、${calendar_month} 参数可应用于所有支持 ${date} 参数的地方，例如 SQL、Shell、数据集成等任务类型。

基于调度日历的加减 #

在默认情况下，直接使用 ${calendar_day}、${calendar_month} 参数取 Excel 中第2列的日期和月份应可以满足绝大多数需求。在特殊情况下，可能需要基于 ${calendar_day} 、${calendar_month} 做二次计算。${calendar_day}、${calendar_month} 的二次计算逻辑指的是对 ${calendar_day}、${calendar_month} 的二次偏移计算，例如${calendar_day-1+1d}、${calendar_month+1m} 等

• ${calendar_day}的二次计算逻辑：

  • -1 按有效的定时时间加减：是按定时时间的所在日，减一个**有效的定时时间**。如下表格是上传的日历文件中，摘取的部分时间，当计划时间 = 2024-12-16 时，减1个有效的定时时间应取值12月13日。即在第一列（定时时间）中向上，根据有效定时时间，向上走一位，有效无效，是根据第三列判断。

  • +1d 按定时时间加减：是指按定时时间所在日的下一个定时时间，即在第一列（定时时间）中向下走一位。

    定时时间	${calendar_day}取值	schedule
    2024/12/12(星期四)	2024/12/12	TRUE
    2024/12/13(星期五)	2024/12/13	TRUE
    2024/12/14(星期六)	none	FALSE
    2024/12/15(星期日)	none	FALSE
    2024/12/16(星期一)	2024/12/16	TRUE
    2024/12/17(星期二)	2024/12/17	TRUE
    2025/01/12(星期日)	none	FALSE
    2025/01/13(星期一)	2025/01/13	TRUE
    2025/01/14(星期二)	2025/01/14	TRUE
    2025/01/15(星期三)	2025/01/15	TRUE
    2025/01/16(星期四)	2025/01/16	TRUE
    2025/01/17(星期五)	2025/01/17	TRUE

  完成上述计算过程后，取第2列值（${calendar_day}取值）。${calendar_day-1+1d}只是示例，实际可使用其他值，例如执行 ${calendar_day-3+5d}。

• ${calendar_month} 的二次计算逻辑：

  • +1、+1d：遵循 ${calendar_day} 的加减逻辑。即 ${calendar_month+1}，是按定时时间的所在日，加一个**有效的定时时间​后，获取到对应${calendar_day}取值，并解析该取值所在月份；${calendar_month+1d}，是按定时时间所在日的下一个定时时间**。
    如以上表格是上传的日历文件中，摘取的部分时间，当计划时间 = 2024-01-13 时，${calendar_month+1} 取值为202412；${calendar_month+1d} 取值为none。
  • +1m: ${calendar_month} 的二次计算逻辑，是在解析到 ${calendar_day} 值的基础上，再加 1 个月。
    如以上表格是上传的日历文件中，摘取的部分时间，当计划时间 = 2024-12-12 时，${calendar_month+1m} 加一个月后为 2025/01/12，此时对应 ${calendar_day} 的最终取值为 none。
  • 混合计算+1+1m:先进行 day 加减，在进行 month 加减。
    如以上表格是上传的日历文件中，摘取的部分时间，当计划时间 = 2024-12-12 时，${calendar_month+1+1m} 表达式，加一个有效定时时间为 2024-12-13，加一个月后为 2025/01/13，此时对应 ${calendar_day} 的最终取值为 2025/01/13。

举例如下：

# 假设调度日历文件为：
# date schedule_date schedule
# 20240928 20240927 TRUE
# 20240929 20240928 TRUE
# 20240930 20240929 TRUE
# 20241001 20240930 FALSE
# 20241002 20241001 FALSE
# 20241003 20241002 FALSE
# 20241004 20241003 FALSE
# 20241005 20241004 FALSE
# 20241006 20241005 FALSE
# 20241007 20241006 FALSE
# 20241008 20241007 TRUE
# 20241009 20241008 TRUE

# 假设当前任务的计划时间为2024-09-30
# 基于调度日历进行增减
print('${calendar_day+1}')  #${calendar_day}取值=20240929，+1表示加一个有效的调度日，取20241007
print('${calendar_day-1}')  #取值20240928
print('${calendar_day+2}')  #按调度日历加2天，取10月8日，后2个调度日
print('${calendar_day-2}')  #按调度日历减2天，取9月27日，前2个调度日

# 假设当前计划时间为2024-09-30
# 基于自然日进行增减
print('${calendar_day+1d}')  #按自然日加1天，第一列向下走1位，取20240930
print('${calendar_day-1d}')  #按自然日减1天，第一列向上走1位，取20240928
print('${calendar_day+2d}')  #按自然日加2天，第一列向下走2位，取20241001
print('${calendar_day-2d}')  #按自然日减2天，第一列向下走2位，取20240927

# 假设当前计划时间为2024-09-30
# 基于叠加调度日历与自然日进行增减
print('${calendar_day+1-1d}')  #先按调度日历加1天（得到计划时间=10月8日对应的${calendar_day}取值=10月7日），再减一天自然日，得到10月6日

任务调试与运行 #

在进行代码调试时，SQL类代码不支持解析调度日历的参数，可通过运行Python脚本，或通过数据回溯的方式对调度日历参数进行测试。
当任务在周期调度、数据回溯时，处于非调度日历的日期（即对应业务日期设置为 FALSE），对应的实例直接设置为成功状态，不会实际运行。用户可在运行日志中查看是否实际运行。

• 非调度日历的时间，任务实例生成，但其状态置成功。
  可在实例运维页面，通过该任务的实例DAG按钮查看其详细日志，日志详情如下：
  
• 调度日历时间，任务实例正常运行，且按照调度日历文件对 ${calendar_day} 进行取值。
• 若当前时间已超出调度日历文件中的定时时间范围时，任务实例正常运行，且 ${calendar_day} 会自动解析成当前时间，即 ${calendar_day} 的取值与定时时间相等。
• 若用户取消使用调度日历（在调度设置中删除了日历），则 ${calendar_day} 的取值与 ${date} 相同。