By default, a connector runs an initial snapshot operation only after it starts for the first time.
Following this initial snapshot, under normal circumstances, the connector does not repeat the snapshot process.
Any future change event data that the connector captures comes in through the streaming process only.

However, in some situations the data that the connector obtained during the initial snapshot might become stale, lost, or incomplete.
To provide a mechanism for recapturing {data-collection} data, {prodname} includes an option to perform ad hoc snapshots.
The following changes in a database might be cause for performing an ad hoc snapshot:

* The connector configuration is modified to capture a different set of {data-collection}s.
* Kafka topics are deleted and must be rebuilt.
* Data corruption occurs due to a configuration error or some other problem.

You can re-run a snapshot for a {data-collection} for which you previously captured a snapshot by initiating a so-called _ad-hoc snapshot_.
Ad hoc snapshots require the use of {link-prefix}:{link-signalling}#sending-signals-to-a-debezium-connector[signaling {data-collection}s].
You initiate an ad hoc snapshot by sending a signal request to the {prodname} signaling {data-collection}.

When you initiate an ad hoc snapshot of an existing {data-collection}, the connector appends content to the topic that already exists for the {data-collection}.
If a previously existing topic was removed, {prodname} can create a topic automatically if {link-prefix}:{link-topic-auto-creation}#customizing-debezium-automatically-created-topics[automatic topic creation] is enabled.

Ad hoc snapshot signals specify the {data-collection}s to include in the snapshot.
The snapshot can capture the entire contents of the database, or capture only a subset of the {data-collection}s in the database.
ifeval::['{context}' != 'mongodb']
Also, the snapshot can capture a subset of the contents of the {data-collection}(s) in the database.
endif::[]

You specify the {data-collection}s to capture by sending an `execute-snapshot` message to the signaling {data-collection}.
Set the type of the `execute-snapshot` signal to `incremental`, and provide the names of the {data-collection}s to include in the snapshot, as described in the following table:

.Example of an ad hoc `execute-snapshot` signal record
[cols="2,2,6",options="header"]
|===
|Field | Default | Value

|`type`
|`incremental`
| Specifies the type of snapshot that you want to run. +
Setting the type is optional.
Currently, you can request only `incremental` snapshots.


|`data-collections`
|_N/A_
| An array that contains regular expressions matching the fully-qualified names of the {data-collection} to be snapshotted. +
The format of the names is the same as for the `signal.data.collection` configuration option.

ifeval::['{context}' != 'mongodb']
|`additional-condition`
|_N/A_
| An optional string, which specifies a condition based on the column(s) of the {data-collection}(s), to capture a
subset of the contents of the {data-collection}(s).
endif::[]

ifeval::['{context}' != 'mongodb']
|`surrogate-key`
|_N/A_
| An optional string that specifies the column name that the connector uses as the primary key of a {data-collection} during the snapshot process.
endif::[]

|===

.Triggering an ad hoc snapshot

You initiate an ad hoc snapshot by adding an entry with the `execute-snapshot` signal type to the signaling {data-collection}.
After the connector processes the message, it begins the snapshot operation.
The snapshot process reads the first and last primary key values and uses those values as the start and end point for each {data-collection}.
Based on the number of entries in the {data-collection}, and the configured chunk size, {prodname} divides the {data-collection} into chunks, and proceeds to snapshot each chunk, in succession, one at a time.

Currently, the `execute-snapshot` action type triggers {link-prefix}:{link-signalling}#debezium-signaling-incremental-snapshots[incremental snapshots] only.
For more information, see xref:{context}-incremental-snapshots[Incremental snapshots].
////
.Prerequisites

* xref:{link-signalling}#debezium-signaling-enabling-source-signaling-channel[Signaling is enabled].

.Procedure

* Trigger a snapshot by submitting a SQL query to add a signal to the signaling {data-collection} that uses the following format:
+
[source,sql,subs="+attributes,+quotes"]
----
INSERT INTO _<signalingCollection>_ VALUES('_<signalName>_','_<signalType>_', '{"data-collections": ["_<dataCollection>_","_<dataCollectionN>_"]}')
----
+
For example:
+
[source,sql]
----
INSERT INTO myschema.debezium_signal VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.table1", "schema2.table2"]}')
----
////
