Currently, the only way to initiate an incremental snapshot is to send an {link-prefix}:{link-signalling}#debezium-signaling-ad-hoc-snapshots[ad hoc snapshot signal] to the signaling {data-collection} on the source database.
tag::sql-based-snapshot[]
You submit a signal to the signaling {data-collection} as SQL `INSERT` queries.
end::sql-based-snapshot[]
tag::nosql-based-snapshot[]
You submit a signal to the signaling {data-collection} by using the MongoDB `insert()` method.
end::nosql-based-snapshot[]

After {prodname} detects the change in the signaling {data-collection}, it reads the signal, and runs the requested snapshot operation.

The query that you submit specifies the {data-collection}s to include in the snapshot, and, optionally, specifies the type of snapshot operation.
Currently, the only valid options for snapshots operations are `incremental` and `blocking`.

To specify the {data-collection}s to include in the snapshot, provide a `data-collections` array that lists the {data-collection}s or an array of regular expressions used to match {data-collection}s, for example,
tag::sql-based-snapshot[]
`{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}`
end::sql-based-snapshot[]
tag::nosql-based-snapshot[]
`{"data-collections": ["public.Collection1", "public.Collection2"]}`
end::nosql-based-snapshot[]

The `data-collections` array for an incremental snapshot signal has no default value.
If the `data-collections` array is empty, {prodname} detects that no action is required and does not perform a snapshot.

[NOTE]
====
If the name of a {data-collection} that you want to include in a snapshot contains a dot (`.`) in the name of the database, schema, or table, to add the {data-collection} to the `data-collections` array, you must escape each part of the name in double quotes.

tag::sql-based-snapshot[]
For example, to include a table that exists in the `*public*` schema and that has the name `*My.Table*`, use the following format: `*"public"."My.Table"*`.
end::sql-based-snapshot[]
tag::nosql-based-snapshot[]
For example, to include a data collection that exists in the `*public*` database, and that has the name `*MyCollection*`, use the following format: `*"public"."MyCollection"*`.
end::nosql-based-snapshot[]
====

.Prerequisites

* {link-prefix}:{link-signalling}#debezium-signaling-enabling-source-signaling-channel[Signaling is enabled].
** A signaling data collection exists on the source database.
** The signaling data collection is specified in the xref:{context}-property-signal-data-collection[`signal.data.collection`] property.

.Using a source signaling channel to trigger an incremental snapshot

tag::sql-based-snapshot[]

. Send a SQL query to add the ad hoc incremental snapshot request to the signaling {data-collection}:
+
[source,sql,indent=0,subs="+attributes,+quotes"]
----
INSERT INTO _<signalTable>_ (id, type, data) VALUES (_'<id>'_, _'<snapshotType>'_, '{"data-collections": ["_<tableName>_","_<tableName>_"],"type":"_<snapshotType>_","additional-conditions":[{"data-collection": "_<tableName>_", "filter": "_<additional-condition>_"}],"surrogate-key":"_<surrogate-key>_"}');
----
+
For example,
+
[source,sql,indent=0,subs="+attributes"]
----
INSERT INTO myschema.debezium_signal (id, type, data) // <1>
values ('ad-hoc-1',   // <2>
    'execute-snapshot',  // <3>
    '{"data-collections": ["schema1.table1", "schema2.table2"], // <4>
    "type":"incremental", // <5>
    "additional-conditions":[{"data-collection": "schema1.products", "filter": "color='blue'"}], // <6>
    "surrogate-key":"tenant-id"}'); // <7>
----
end::sql-based-snapshot[]

tag::nosql-based-snapshot[]

. Insert a snapshot signal document into the signaling {data-collection}:
+
[source,bash,indent=0,subs="+attributes,+quotes"]
----
_<signalDataCollection>_.insert({"_id" : _<idNumber>_,"type" : _<snapshotType>_, "data" : {"data-collections" ["_<collectionName>_", "_<collectionName>_"],"type": _<snapshotType>_}});
----
+
For example,
+
[source,bash,indent=0,subs="+attributes,+quotes"]
----
db.debeziumSignal.insert({ // <1>
"type" : "execute-snapshot", // <2> <3>
"data" : {
"data-collections" ["\"public\".\"Collection1\"", "\"public\".\"Collection2\""], // <4>
"type": "incremental"} // <5>
});
----
end::nosql-based-snapshot[]
+
The values of the `id`,`type`, and `data` parameters in the command correspond to the {link-prefix}:{link-signalling}#debezium-signaling-description-of-required-structure-of-a-signaling-data-collection[fields of the signaling {data-collection}].
+
The following table describes the parameters in the example:
+
tag::sql-based-snapshot[]

.Descriptions of fields in a SQL command for sending an incremental snapshot signal to the signaling {data-collection}
[cols="4%,11%,85%a",options="header"]
|===
|Item |Value |Description

|1
|`myschema.debezium_signal`
|Specifies the fully-qualified name of the signaling {data-collection} on the source database.

|2
|`ad-hoc-1`
| The `id` parameter specifies an arbitrary string that is assigned as the `id` identifier for the signal request.

Use this string to identify logging messages to entries in the signaling {data-collection}.
{prodname} does not use this string.
Rather, during the snapshot, {prodname} generates its own `id` string as a watermarking signal.

|3
|`execute-snapshot`
| Specifies `type` parameter specifies the operation that the signal is intended to trigger.

|4
|`data-collections`
|A required component of the `data` field of a signal that specifies an array of {data-collection} names or regular expressions to match {data-collection} names to include in the snapshot.

The array lists regular expressions which match {data-collection}s by their fully-qualified names, using the same format as you use to specify the name of the connector's signaling {data-collection} in the xref:{context}-property-signal-data-collection[`signal.data.collection`] configuration property.
Collection names are case-sensitive.

|5
|`incremental`
|An optional `type` component of the `data` field of a signal that specifies the type of snapshot operation to run.

Currently supports the `incremental` and `blocking` types.
If you do not specify a value, the connector runs an incremental snapshot.

|6
|`additional-conditions`
| An optional array that specifies a set of additional conditions that the connector evaluates to determine the subset of records to include in a snapshot.
Each element in the `additional-conditions` array is an object that includes the following keys:

`data-collection`:: The fully-qualified name of the data collection for which the filter will be applied.
Collection names are case-sensitive.
`filter`:: Specifies the column values that must be present in a data collection record for the snapshot to include it, for example, `"color='blue'"`.
|7
|`surrogate-key`
|An optional string that specifies the column name that the connector uses as the primary key for snapshots.
|===

[id="{context}-incremental-snapshots-additional-conditions"]
.Ad hoc incremental snapshots with `additional-conditions`

If you want a snapshot to include only a subset of the content in a {data-collection}, you can modify the signal request by appending an `additional-conditions` parameter to the snapshot signal.

The SQL query for a typical snapshot takes the following form:

[source,sql,subs="+attributes,+quotes"]
----
SELECT * FROM _<tableName>_ ....
----

By adding an `additional-conditions` parameter, you append a `WHERE` condition to the SQL query, as in the following example:

[source,sql,subs="+attributes,+quotes"]
----
SELECT * FROM _<data-collection>_ WHERE _<filter>_ ....
----

The following example shows a SQL query to send an ad hoc incremental snapshot request with an additional condition to the signaling {data-collection}:
[source,sql,indent=0,subs="+attributes,+quotes"]
----
INSERT INTO _<signalTable>_ (id, type, data) VALUES (_'<id>'_, _'<snapshotType>'_, '{"data-collections": ["_<tableName>_","_<tableName>_"],"type":"_<snapshotType>_","additional-conditions":[{"data-collection": "_<tableName>_", "filter": "_<additional-condition>_"}]}');
----

For example, suppose you have a `products` {data-collection} that contains the following columns:

* `id` (primary key)
* `color`
* `quantity`

If you want an incremental snapshot of the `products` {data-collection} to include only the data items where `color='blue'`, you can use the following SQL statement to trigger the snapshot:

[source,sql,indent=0,subs="+attributes"]
----
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", [{"data-collection": "schema1.products", "filter": "color='blue'"}]}');
----

The `additional-conditions` parameter also enables you to pass conditions that are based on more than on column.
For example, using the `products` {data-collection} from the previous example, you can submit a query that triggers an incremental snapshot that includes the data of only those items for which `color='blue'` and `quantity>10`:

[source,sql,indent=0,subs="+attributes"]
----
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", [{"data-collection": "schema1.products", "filter": "color='blue' AND quantity>10"}]}');
----

end::sql-based-snapshot[]

tag::nosql-based-snapshot[]

+
.Descriptions of fields in a MongoDB insert() command for sending an incremental snapshot signal to the signaling {data-collection}
[cols="4%,11%,85a%",options="header"]
|===
|Item |Value |Description

|1
|`db.debeziumSignal`
|Specifies the fully-qualified name of the signaling {data-collection} on the source database.

|2
|null
| The `_id` parameter specifies an arbitrary string that is assigned as the `id` identifier for the signal request.

The insert method in the preceding example omits use of the optional `_id` parameter.
Because the document does not explicitly assign a value for the parameter, the arbitrary id that MongoDB automatically assigns to the document becomes the `id` identifier for the signal request.

Use this string to identify logging messages to entries in the signaling {data-collection}.
{prodname} does not use this identifier string.
Rather, during the snapshot, {prodname} generates its own `id` string as a watermarking signal.

|3
|`execute-snapshot`
| Specifies `type` parameter specifies the operation that the signal is intended to trigger.

|4
|`data-collections`
|A required component of the `data` field of a signal that specifies an array of {data-collection} names or regular expressions to match {data-collection} names to include in the snapshot.

The array lists regular expressions which match {data-collection}s by their fully-qualified names, using the same format as you use to specify the name of the connector's signaling {data-collection} in the xref:{context}-property-signal-data-collection[`signal.data.collection`] configuration property.
Collection names are case-sensitive.

|`incremental`
|An optional `type` component of the `data` field of a signal that specifies the type of snapshot operation to run.

Currently supports the `incremental` and `blocking` types.

If you do not specify a value, the connector runs an incremental snapshot.
|===

end::nosql-based-snapshot[]

The following example, shows the JSON for an incremental snapshot event that is captured by a connector.

.Example: Incremental snapshot event message
[source,json,index=0]
----
{
    "before":null,
    "after": {
        "pk":"1",
        "value":"New data"
    },
    "source": {
        ...
        "snapshot":"incremental" <1>
    },
    "op":"r", <2>
    "ts_ms":"1620393591654",
    "ts_us":"1620393591654014",
    "ts_ns":"1620393591654014325",
    "transaction":null
}
----
[cols="1,1,4a",options="header"]
|===
|Item |Field name |Description
|1
|`snapshot`
|Specifies the type of snapshot operation to run.

Currently, the only valid options are `blocking` and `incremental`.

Specifying a `type` value in the SQL query that you submit to the signaling {data-collection} is optional.
If you do not specify a value, the connector runs an incremental snapshot.

|2
|`op`
|Specifies the event type.

The value for snapshot events is `r`, signifying a `READ` operation.

|===
