Each entity that is sent to Google, whether through feeds or real-time updates,
has a version attached to it. This version comes in the form of a timestamp. In
feeds, the timestamp can be provided for each entity using the dateModified
attribute. If the attribute is not included the feed entities, the version is
set to the start time of feed ingestion. In real-time updates batchPush and
batchDelete, respectively, the fields generation_timestamp and delete_time
are used to set the version. If the field is not included, the version is set to
the time when the request was received. See the expected format of time
values
in the relational inventory schema.
Google only processes entities (for example: a restaurant, a menu, or a service) with a version equal to or newer than the last accepted version. Otherwise, the entity is not ingested and the Stale Entity error is recorded. When an entity is updated with a new version, the last modified timestamp is updated to the current time that it was updated.
Example
Suppose a feed is generated on June 16th at 01:10 UTC with the following example entity included.
{
"@type": "Restaurant",
"@id": "restaurant12345",
"dateModified": "2022-06-16T01:10:00.000Z",
...
}
The feed is not yet ingested by Google. Later that day at
2022-06-16T01:22:00.000Z, Google receives a
real-time update batchPush request with the following
entity.
{
"records": [
{
"data_record": "{\"@type\": \"Restaurant\",\"@id\": \"restaurant12345\" ...",
"generation_timestamp": "2022-06-16T01:20:00.000Z"
}
]
}
The version for the restaurant entity ID restaurant12345 is now
2022-06-16T01:20:00.000Z and the last modified timestamp of the entity is set
to 2022-06-16T01:22:00.000Z. In summary, the last modified time is the time
that the entity was updated in Google's inventory and the version is the
generation_timestamp value from the real-time update request or the
dateModified value from the feed.
Ingestion of the feed then starts on June 16th at 02:00 UTC. In this situation,
the entity received in the feed with version 2022-06-16T01:10:00.000Z is
considered stale and is not ingested. Google therefore continues to serve the
entity with version 2022-06-16T01:20:00.000Z from the
real-time update request.
Best practices:
- Implement a timestamp in feeds for each entity.
- Apply the real-time update changes to your next feed and set the dateModified timestamp in the feed entities to the current time when you created the feed.