Dates and Timestamps

Dates in KG are typically given as an epoch timestamp, representing the number of seconds or milliseconds since 00:00:00 UTC on January 1, 1970. Such a date field will contain the following fields:

Field NameExample ValueField Description
strd2018-10-04T08:11:28A string representation of the given timestamp
precision4The arithmetic precision of the given timestamp. 1 indicates that we only know the year of the event (e.g. 1900-XX-XX), 2 means we know up to the month (e.g. 1966-10-XX), 3 means we know up to the day, 4 means we know the full date and time.
timestamp1538640688000The number of milliseconds since 00:00:00 UTC on January 1, 1970.

Here's an example in JSON:

"from": {
  "str": "d2018-10-04T08:11:28",
  "precision": 4,
  "timestamp": 1538640688000

Crawl Timestamps

Each entity in the KG also includes a field crawlTimestamp that represents the last time that any of that entity’s origins were crawled and extracted. This field therefore represents the maximum possible freshness of any individual data point.

Note that all crawlTimestamp are represented in seconds.

Querying for Dates

Date Field Expansion

When referring to any date/timestamp field (not including crawlTimestamp) in a query, if the timestamp field is omitted from the query, the field in the query will be expanded to include the timestamp field. For example, these two queries are equivalent, with the first being automatically expanded to the second:

Epoch vs. Date Literal

You can represent a timestamp in a query using an Epoch timestamp, in either milliseconds or seconds, given as an integer.

Example (these 2 queries are equivalent):

Timestamps can also be represented as a literal date string (a "Date Literal") with one of the following formats:

  • MM-dd-yyyy (ex. "08-01-2015")
  • MM/dd/yyyy (ex. "08/01/2015")
  • yyyy-MM-dd (ex. "2015-08-01")
  • yyyy/MM/dd (ex. "2015/08/01")

For example, to view all organizations that were founded on New Years Day in the year 2000, we could query:
type:Organization foundingDate:"01/01/2000"

Note that equivalent min/max and greater/less than expressions can be used interchangeably, whether we are using an epoch timestamp or a Date Literal to represent the timestamp in our query. For example, these 4 queries are all equivalent:

Special Time Period Literals

For a Crawl Timestamp, or for the date field of an Article entity, we can use a Time Period Literal to represent some length of time. A Time Period Literal consists of a numeric value and a unit specifier. For example, the Time Period Literal "4h" represents 4 hours. These are the time units that are supported:

  • s: seconds
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • y: 365 days

Example: To find all Articles that were published at least 4 hours ago:

type:Article date>=4h

Example: To find all Articles for which any origin was crawled within the last 4 hours:

type:Article lastCrawlTime<=4h

Example: To find all Organizations for which any origin was crawled within the last 365 days:

type:Organization crawlTimestamp<=1y

Special handling for Article date field

Every Article entity has a date field representing the publication date of the article. We can reference this field as either date or date.str in our DQL query.

For example, to find articles published after March 1, 2022:

type:Article date>"2022-03-01"