你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

DateTimeDiff (Azure Cosmos DB)

  • 项目

适用于： SQL API

返回指定的 StartDate 和 EndDate 之间所跨的指定 DateTimePart 边界的计数（以带符号整数值的形式） 。

语法

DateTimeDiff (<DateTimePart> , <StartDate> , <EndDate>)

参数

DateTimePart
DateTimeAdd 向其添加整数的日期部分。 此表列出了所有有效的 DateTimePart 参数：

DateTimePart 缩写
Year "year", "yyyy", "yy"
Month "month", "mm", "m"
日期 "day", "dd", "d"
Hour "hour", "hh"
Minute "minute", "mi", "n"
秒 "second", "ss", "s"
Millisecond "millisecond", "ms"
Microsecond "microsecond", "mcs"
Nanosecond "nanosecond", "ns"

StartDate
YYYY-MM-DDThh:mm:ss.fffffffZ 格式的 UTC 日期和时间 ISO 8601 字符串值，其中：

格式 描述
YYYY 四位数的年份
MM 两位数的月份（01 = 1 月，依此类推。）
DD 两位数的月份日期（01 到 31）
T 时间元素开头的符号
hh 两位数的小时（00 到 23）
MM 两位数的分钟（00 到 59）
ss 两位数的秒（00 到 59）
.fffffff 七位数的小数秒
Z UTC（协调世界时）指示符

有关 ISO 8601 格式的详细信息，请参阅 ISO_8601

EndDate
YYYY-MM-DDThh:mm:ss.fffffffZ 格式的 UTC 日期和时间 ISO 8601 字符串值

返回类型

返回带符号整数值。

备注

DateTimeDiff 返回 undefined，原因如下：

  • 指定的 DateTimePart 值无效
  • StartDate 或 EndDate不是有效的 ISO 8601 DateTime

DateTimeDiff 始终返回带符号整数值，它度量跨越的 DateTimePart 边界数，而非时间间隔。

示例

以下示例计算 2020-01-01T01:02:03.1234527Z 和 2020-01-03T01:02:03.1234567Z 之间跨越的天的边界的数目。

SELECT DateTimeDiff("day", "2020-01-01T01:02:03.1234527Z", "2020-01-03T01:02:03.1234567Z") AS DifferenceInDays

[
    {
        "DifferenceInDays": 2
    }
]

以下示例计算 2028-01-01T01:02:03.1234527Z 和 2020-01-03T01:02:03.1234567Z 之间跨越的年份边界的数目。

SELECT DateTimeDiff("yyyy", "2028-01-01T01:02:03.1234527Z", "2020-01-03T01:02:03.1234567Z") AS DifferenceInYears

[
    {
        "DifferenceInYears": -8
    }
]

以下示例计算 2020-01-01T01:00:00.1234527Z 和 2020-01-01T01:59:59.1234567Z 之间跨越的小时边界的数目。 即使这些 DateTime 值之间相隔超过 0.99 小时，DateTimeDiff 仍将返回 0，因为没有超过小时边界。

SELECT DateTimeDiff("hh", "2020-01-01T01:00:00.1234527Z", "2020-01-01T01:59:59.1234567Z") AS DifferenceInHours

[
    {
        "DifferenceInHours": 0
    }
]

后续步骤