FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

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

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!