Metabase DatetimeSubtract 表达式完全指南语法、参数、实战案例与底层实现【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabasedatetimeSubtract是 Metabase 查询构建器Query Builder中处理时间序列数据的核心自定义表达式它从一个日期/时间值中减去指定数量的时间单位常用于计算会话、订阅等带开始/结束标记的数据。读完本文你将掌握datetimeSubtract的完整语法与参数约束、三种典型实战场景计算开始时间、判断当前时间是否落在区间内、时区换算并从源码层面理解它在 SQL 数据库与 MongoDB 中的真实执行原理。语法与基础行为datetimeSubtract的语法非常简洁只接收三个参数语法示例datetimeSubtract(column, amount, unit)datetimeSubtract(2021-03-25, 1, month)从日期/时间值中减去指定数量的时间单位结果2021-02-25从实现角度看这个表达式在 Metabase 的现代 MBQLMetabase Query Language层面对应:datetime-subtract子句。在 src/metabase/lib/schema/expression/temporal.cljc 中可以看到它与:datetime-add一起被定义为一个三元组子句三个位置参数分别约束为第一个参数expr必须是::expression/temporal即时间类型表达式第二个参数amount必须是整数:int第三个参数unit必须是::temporal-bucketing/unit.date-time.interval即合法的日期时间间隔单位。同时该子句的返回类型遵循:lib.type-of/type-is-temporal-type-of-first-arg规则——即返回类型与第一个时间参数的类型一致见 temporal.cljc 中的类型推断实现所以对日期列做减法返回日期、对带时间的列做减法返回带时间的值。三个参数详解column被减的时间值column可以是以下任意一种时间戳列timestamp column的名称一个返回 datetime 的自定义表达式一个符合YYYY-MM-DD或YYYY-MM-DDTHH:MM:SS格式的字符串如上方示例。值得注意的是源码中对该参数的类型推断做了特殊处理由于格式化的日期字符串在类型系统中可能同时被推断为:type/String与:type/DateTime的并集而这里做的是日期运算因此代码会在类型并集中取交集、只保留:type/Date与:type/DateTime中的时间类型见 temporal.cljc 的type-of-method实现保证字符串日期也能正确参与运算。unit时间单位unit可以是以下任一单位year年quarter季度month月day天hour小时minute分钟second秒millisecond毫秒在 src/metabase/lib/schema/temporal_bucketing.cljc 中这些单位由日期间隔单位集合date-interval-units包含:year、:quarter、:month、:week、:day与时间间隔单位集合time-interval-units包含:millisecond、:second、:minute、:hour取并集而来最终形成datetime-interval-units。前端的单位下拉列表正是按照这一套校验枚举来渲染的传入列表之外的单位会直接触发表达式校验错误。amount减去的数量amount有两条硬性约束必须是整数不能使用小数。例如你不能减去半年0.5。可以是负数datetimeSubtract(2021-03-25, -1, month)会返回2021-04-25——减去负数等价于加上正数这一特性使datetimeSubtract与datetimeAdd完全可以互换使用详见后文 datetimeAdd 一节。实战场景一计算开始时间假设你计划一个外出之夜已知每段行程需要 30 分钟需要反推每个预约点的出发时间活动到达时间Arrive By出发时间Depart At喝一杯2022 年 11 月 12 日 18:302022 年 11 月 12 日 18:00晚餐2022 年 11 月 12 日 20:002022 年 11 月 12 日 19:30跳舞2022 年 11 月 13 日 00:002022 年 11 月 12 日 23:30其中Depart At是一个自定义列表达式为datetimeSubtract([Arrive By], 30, minute)这就是用结束时间反推开始时间的典型场景在会话分析session与订阅周期subscription等带起止标记的时间序列数据中非常常见你往往只知道结束时间和持续时间用datetimeSubtract即可统一算出开始时间。实战场景二判断当前时间是否落在区间内承接上面的例子现在要判断当前时间是否处于出发与到达之间的路程区间。假设当前时间是 11 月 12 日 19:45活动到达时间Arrive By出发时间Depart At在路上On My Way喝一杯2022 年 11 月 12 日 18:302022 年 11 月 12 日 18:00否晚餐2022 年 11 月 12 日 20:002022 年 11 月 12 日 19:30是跳舞2022 年 11 月 13 日 00:002022 年 11 月 12 日 23:30否Depart At依然是自定义列datetimeSubtract([Arrive By], 30, minute)On My Way则借助 case 表达式结合 now当前时间与 between 区间判断检查当前时间是否落在Depart At与Arrive By之间case(between(now, [Depart At], [Arrive By]), Yes, No)这个组合datetimeSubtract产出区间下界、now提供当前时刻、between完成区间判定是 Metabase 中做实时窗口判断的通用范式可用于优惠券有效期内判断、告警窗口判断、运营活动进行中标记等需求。接受的数据类型数据类型是否支持datetimeSubtract字符串String❌数字Number❌时间戳Timestamp✅布尔值Boolean❌JSON❌Metabase 使用 timestamp 与 datetime 来泛指所有受支持的时序数据类型。关于 Metabase 中这些数据类型的更多信息可参考 时区文档。如果你的时间戳在数据库中以字符串或数字形式存储管理员可以在 表元数据页面 中将其转换为时间戳类型cast之后再参与datetimeSubtract运算。限制MongoDB 版本要求如果使用 MongoDBdatetimeSubtract仅支持5.0 及以上版本。这一限制的根源可以在 MongoDB 驱动源码中找到modules/drivers/mongo/src/metabase/driver/mongo/query_processor.clj 中的注释明确指出interval 在 MongoDB 中并不是一等公民无法独立翻译只能用于对日期表达式做加/减而带 interval 的日期运算$dateAdd/$dateSubtract直到 MongoDB 5.0 才首次引入。因此驱动在翻译这类表达式时会读取数据库版本号当主版本小于 5 时直接抛出 Date arithmetic not supported in versions before 5 异常而不是生成错误的查询。相关函数与跨工具等价实现本节覆盖与 MetabasedatetimeSubtract行为一致的其他函数与公式并说明如何为你的场景选择最合适的方案。datetimeAdddatetimeSubtract与 datetimeAdd 完全可以互换——因为amount允许为负数。在之前的活动示例中两者可以任选其一但应当尽量避免双重否定例如减去一个负数。下面两段表达式结果完全一致datetimeAdd([Arrive By], -30, minute)datetimeSubtract([Arrive By], 30, minute)这一等价关系也体现在 SQL 编译层在 src/metabase/driver/sql/query_processor.clj 中:datetime-add与:datetime-subtract两个子句的编译逻辑几乎相同唯一区别是后者把amount取负后再调用同一个add-interval-honeysql-form即减去 30 分钟在底层就是加上 -30 分钟。SQL当你使用查询构建器运行问题时Metabase 会把图形化的查询设置筛选、汇总等转换为 SQL 查询再发送给数据库执行。底层转换的核心逻辑就在 src/metabase/driver/sql/query_processor.clj 的-honeysql [:sql :datetime-subtract]方法中——它把datetimeSubtract(arg, amount, unit)编译为向时间值加上(- amount)个单位的 interval 形式。如果活动示例数据存放在 PostgreSQL 数据库中SELECT arrive_by - INTERVAL 30 minutes AS depart_at FROM events等价于 Metabase 的datetimeSubtract表达式datetimeSubtract([Arrive By], 30, minute)电子表格Spreadsheets假设活动示例数据位于电子表格中Arrive By 位于 A 列且为日期时间格式那么电子表格函数A:A - 30/(60*24)与下面的表达式产生相同结果datetimeSubtract([Arrive By], 30, minute)多数电子表格软件要求针对不同时间单位使用不同公式例如减天与减小时的算法完全不同。datetimeSubtract的价值正在于把所有这些零散算法统一成一种一致、可读的语法。Pythonpandas如果活动示例数据保存在名为df的 pandas 数据帧列中可以导入datetime模块并使用timedeltadf[Depart At] df[Arrive By] - datetime.timedelta(minutes30)这与下面的表达式等价datetimeSubtract([Arrive By], 30, minute)从源码看执行流程MBQL → 数据库查询综合前文源码证据一条datetimeSubtract表达式的完整生命周期可以概括为校验层temporal.cljc 中的 Malli schema 校验三个参数的类型——时间值、整数amount、合法的间隔单位类型推断层同一文件中的type-of-method确保返回类型与第一个时间参数一致即使传入的是格式化的字符串日期SQL 编译层对支持 SQL 的数据库query_processor.clj 将:datetime-subtract编译为add-interval-honeysql-form负的 amount interval 单位最终生成各数据库方言的- INTERVAL 30 minutes类语法MongoDB 特殊路径对 MongoDBquery_processor.clj 将 interval 翻译为$dateSubtract聚合操作符并在版本低于 5 时抛出明确异常。对应地仓库测试 test/metabase/query_processor/expressions_test.clj 中的temporal-arithmetic-test验证了所有支持表达式 日期运算特性的数据库驱动上[:- [:interval 31 :day]]即减去 31 天都能得到与[: [:interval -31 :day]]完全一致的预期结果——再次印证减法即加负数的统一语义。延伸阅读自定义表达式总览datetimeAdd 表达式now 表达式case 表达式时区与数据类型【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考