Entity versioning

Note: Partners who are still using the non-relational inventory schema can access the v1 versioning in batch feeds documentation in the archive section.

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.

Caution: If an entity is not modified with a new version for 14 days consecutively, it is garbage collected and removed from serving.

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.