你当前正在访问 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.1234527Z2020-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.1234527Z2020-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.1234527Z2020-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
    }
]

后续步骤