The Fauna service will be ending on May 30, 2025.

For more information on the service wind down, see our announcement and the Fauna Service End-of-Life FAQ.

TimeDiff

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
TimeDiff( start, finish, unit )
time_diff( start, finish, unit )
TimeDiff( start, finish, unit )
TimeDiff( start, finish, unit )
TimeDiff( start, finish, unit )
TimeDiff( start, finish, unit )

Description

The TimeDiff function returns the time difference between start and finish, expressed in unit units. The difference includes start but excludes finish.

Parameters

Parameter Type Definition and Requirements

start

Date or Timestamp

The starting Date or Timestamp. start must match the type of finish.

finish

Date or Timestamp

The ending Date or Timestamp. finish must match the type of start.

unit

String

The type of unit that the difference should be expressed in.

When start and finish are Dates, unit must be one of day or days.

When start and finish are Timestamps, unit must be one of:

  • day, or days

  • half day, or half days

  • hour, or hours

  • minute, or minutes

  • second, or seconds

  • millisecond, or milliseconds

  • microsecond, or microseconds

  • nanosecond, or nanoseconds

Returns

A Number which represents the count of unit units between start and finish.

Examples

The following query demonstrates several time differences:

client.query(
  q.Let(
    {
      start: q.Time('1970-01-01T00:00:00+00:00'),
      finish: q.Time('2020-07-06T12:34:56.789Z'),
    },
    [
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'days'),
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'half days'),
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'hours'),
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'minutes'),
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'seconds'),
      q.TimeDiff(q.Var('start'), q.Var('finish'), 'milliseconds'),
    ]
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
[ 18449, 36899, 442788, 26567314, 1594038896, 1594038896789 ]
result = client.query(
  q.let(
    {
      "start": q.time("1970-01-01T00:00:00+00:00"),
      "finish": q.time("2020-07-06T12:34:56.789Z"),
    },
    [
      q.time_diff(q.var("start"), q.var("finish"), "days"),
      q.time_diff(q.var("start"), q.var("finish"), "half days"),
      q.time_diff(q.var("start"), q.var("finish"), "hours"),
      q.time_diff(q.var("start"), q.var("finish"), "minutes"),
      q.time_diff(q.var("start"), q.var("finish"), "seconds"),
      q.time_diff(q.var("start"), q.var("finish"), "milliseconds"),
    ]
  )

)
print(result)
[18449, 36899, 442788, 26567314, 1594038896, 1594038896789]
result, err := client.Query(
	f.Let().Bind(
		"start", f.Time("1970-01-01T00:00:00+00:00")).Bind(
		"finish", f.Time("2020-07-06T12:34:56.789Z")).In(
		f.Arr{
			f.TimeDiff(f.Var("start"), f.Var("finish"), "days"),
			f.TimeDiff(f.Var("start"), f.Var("finish"), "half days"),
			f.TimeDiff(f.Var("start"), f.Var("finish"), "hours"),
			f.TimeDiff(f.Var("start"), f.Var("finish"), "minutes"),
			f.TimeDiff(f.Var("start"), f.Var("finish"), "seconds"),
			f.TimeDiff(f.Var("start"), f.Var("finish"), "milliseconds"),
		}))


if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
[18449 36899 442788 26567314 1594038896 1594038896789]
try
{
    Value result = await client.Query(
        Let(
            "start", Time("1970-01-01T00:00:00+00:00"),
            "finish", Time("2020-07-06T12:34:56.789Z")
        ).In(
            Arr(
                TimeDiff(Var("start"), Var("finish"), "days"),
                TimeDiff(Var("start"), Var("finish"), "half days"),
                TimeDiff(Var("start"), Var("finish"), "hours"),
                TimeDiff(Var("start"), Var("finish"), "minutes"),
                TimeDiff(Var("start"), Var("finish"), "seconds"),
                TimeDiff(Var("start"), Var("finish"), "milliseconds")
            )
        )
    );

    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
Arr(LongV(18449), LongV(36899), LongV(442788), LongV(26567314), LongV(1594038896), LongV(1594038896789))
System.out.println(
    client.query(
        Let(
            "start", Time("1970-01-01T00:00:00+00:00"),
            "finish", Time("2020-07-06T12:34:56.789Z")
        ).in(
            Arr(
                TimeDiff(Var("start"), Var("finish"), "days"),
                TimeDiff(Var("start"), Var("finish"), "half days"),
                TimeDiff(Var("start"), Var("finish"), "hours"),
                TimeDiff(Var("start"), Var("finish"), "minutes"),
                TimeDiff(Var("start"), Var("finish"), "seconds"),
                TimeDiff(Var("start"), Var("finish"), "milliseconds")
            )
        )
    ).get()
);
[18449, 36899, 442788, 26567314, 1594038896, 1594038896789]
Let(
  {
    'start': Time('1970-01-01T00:00:00+00:00'),
    'finish': Time('2020-07-06T12:34:56.789Z'),
  },
  [
    TimeDiff(Var('start'), Var('finish'), 'days'),
    TimeDiff(Var('start'), Var('finish'), 'half days'),
    TimeDiff(Var('start'), Var('finish'), 'hours'),
    TimeDiff(Var('start'), Var('finish'), 'minutes'),
    TimeDiff(Var('start'), Var('finish'), 'seconds'),
    TimeDiff(Var('start'), Var('finish'), 'milliseconds'),
  ]
)
[ 18449, 36899, 442788, 26567314, 1594038896, 1594038896789 ]
Query metrics:

  •    bytesIn: 544

  •   bytesOut:  67

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 5ms

  •    retries:   0

\