Gap Events

Salesforce sometimes sends gap events instead of change events to inform subscribers about errors, or if it’s not possible to generate change events. A gap event contains information about the change in the header, such as the change type and record ID. It doesn’t include details about the change, such as record fields.

The conditions that cause gap events include:

The change event size exceeds the maximum 1 MB message size.
Some field type conversions of custom fields. For more information, see Conversions That Generate a Gap Event.
When an internal error occurs in Salesforce preventing the change event from being generated.
Changes that occur outside the application server transaction and are applied directly in the database. For example, archiving of activities or a data cleanup job in the database. To not miss these operations, gap events are generated to notify you about those changes.

Gap events can have one of these changeType values in the event header.

GAP_CREATE
GAP_UPDATE
GAP_DELETE
GAP_UNDELETE

A changeType value of GAP_OVERFLOW means that the event is an overflow event. For more information, see Overflow Events.

Note

Upon receiving a gap event message, your application can retrieve the Salesforce record using the record ID value to get the current data for your system. For more information about handling gap events, see How to Handle a Gap Event in Transaction-Based Replication Steps.

The gap event’s transactionKey represents the internal database transaction ID if the change was applied at the database layer, outside an application server transaction. If the gap event was emitted due to other reasons, such as hitting the 1 MB event size limit or an internal error, the transactionKey holds the application server transaction ID.

If the same type of change occurs on the same Salesforce entity within the same transaction, sometimes multiple gap events are merged into a single gap event. The IDs of the changed records are included in the recordIds header field. For more information, see Merged Change Events.

Note

Example

This sample gap event is for an account creation and contains information about the change in the header. The change type is GAP_CREATE.

1{
2  "ChangeEventHeader": {
3    "entityName": "Account",
4    "recordIds": [
5      "001ZM000001n4n5YAA"
6    ],
7    "changeType": "GAP_CREATE",
8    "changeOrigin": "",
9    "transactionKey": "000a50de-05dd-07c4-22fb-44b7f9e72ab5",
10    "sequenceNumber": 19,
11    "commitTimestamp": 1714417112000,
12    "commitNumber": 72784468115,
13    "commitUser": "005ZM000000Q6ipYAC",
14    "nulledFields": [],
15    "diffFields": [],
16    "changedFields": []
17  },
18  "Name": null,
19  "Type": null,
20  "ParentId": null,
21  "BillingAddress": null,
22  "ShippingAddress": null,
23  "Phone": null,
24  "Fax": null,
25  "AccountNumber": null,
26  "Website": null,
27  "Sic": null,
28  "Industry": null,
29  "AnnualRevenue": null,
30  "NumberOfEmployees": null,
31  "Ownership": null,
32  "TickerSymbol": null,
33  "Description": null,
34  "Rating": null,
35  "Site": null,
36  "OwnerId": null,
37  "CreatedDate": null,
38  "CreatedById": null,
39  "LastModifiedDate": null,
40  "LastModifiedById": null,
41  "Jigsaw": null,
42  "JigsawCompanyId": null,
43  "AccountSource": null,
44  "SicDesc": null,
45  "External_Account_ID__c": null
46}

See Also