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.
timestamp1538640688000The number of seconds or milliseconds since 00:00:00 UTC on January 1, 1970. Which unit is used can be determined by examining the precision field. A value of 4 would indicate that the timestamp is in milliseconds, while a precision of 1 would indicate seconds

Here's an example in JSON:

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

Crawl Timestamps

Each entity in the KG also includes a field 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.

The name of the crawl timestamp field varies depending on the entity type. The table below explains which field name is associated with each entity type:

Entity TypeCrawl Timestamp Field Name
AdministrativeAreacrawlTimestamp
ArticlelastCrawlTime
DegreeEntitycrawlTimestamp
DiscussionlastCrawlTime
EventcrawlTimestamp
ImagelastCrawlTime
OrganizationcrawlTimestamp
PersoncrawlTimestamp
PostlastCrawlTime
ProductlastCrawlTime
SkillcrawlTimestamp
VideolastCrawlTime

Note that all crawl timestamps are represented in seconds.

Querying for Dates

Date Field Expansion

When referring to any date/timestamp field (not including crawl timestamps) in a query, if the timestamp subfield is omitted from the field specification, the field in the query will be expanded to include the timestamp subfield. 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"


Did this page help you?