Warehouse syncs mAPI reference
Complete reference documentation for the Warehouse syncs resource.
Warehouse syncs
#A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
You can list, retrieve, upsert, and validate syncs, change their schedule, run them, and list their recent runs. Upserting a sync saves a draft. Pass commit=true to publish it. Syncs are identified by their key and belong to one environment. They aren't promoted between environments, and they aren't available in branch environments.
Endpoints
Run a warehouse sync
#Starts a run of the published warehouse sync now, instead of waiting for its schedule. Refused while a run is in progress.
Endpoint
Path parameters
The key of the warehouse sync to run.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
Wraps the WarehouseSync response under the warehouse_sync key.
A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
Update a warehouse sync's settings
#Pauses or resumes a warehouse sync, or changes how often it runs. Settings take effect right away and don't need a publish.
Endpoint
Path parameters
The key of the warehouse sync to update.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Request body
Whether the sync runs on its schedule.
How often the sync runs, in minutes.
Returns
Wraps the WarehouseSync response under the warehouse_sync key.
A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
List warehouse syncs
#Returns a paginated list of warehouse syncs for the given environment.
Endpoint
Query parameters
The environment slug. When omitted, the account's default environment is used.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A paginated list of WarehouseSync. Contains a list of entries and page information.
A list of entries.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
List warehouse sync runs
#Returns the most recent runs of a warehouse sync, newest first.
Endpoint
Path parameters
The key of the warehouse sync.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
A paginated list of WarehouseSyncRun. Contains a list of entries and page information.
A list of entries.
When the run ended.
Why the run failed.
What went wrong.
Where the run failed.
The ID of the run.
The ID of the delivery of rows to Knock. Null when the run hasn't sent rows yet, failed before sending them, or found no changes.
How many rows failed before reaching Knock.
How many changed rows were read from the warehouse.
How many rows were applied in Knock.
How many rows failed to apply in Knock.
When the run started.
The status of the run.
When the run was queued.
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
Validate a warehouse sync
#Checks a warehouse sync payload the way an upsert would, without saving it. Returns the payload as sent.
Endpoint
Path parameters
The key of the warehouse sync to validate.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Request body
A warehouse sync payload for upsert or validate. Fields left out keep their current values. warehouse_key, target_type, and target are required to create a sync and can't change after. Change enabled and frequency_minutes with the settings endpoint.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
An optional description of the sync. Maximum of 280 characters allowed.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
The version_id of the sync you last read. When it isn't the current version, someone saved since, and the request is refused.
The key of the warehouse the sync reads from. Can't change after creation.
Returns
Wraps the WarehouseSyncRequest response under the warehouse_sync key.
A warehouse sync payload for upsert or validate. Fields left out keep their current values. warehouse_key, target_type, and target are required to create a sync and can't change after. Change enabled and frequency_minutes with the settings endpoint.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
An optional description of the sync. Maximum of 280 characters allowed.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
The version_id of the sync you last read. When it isn't the current version, someone saved since, and the request is refused.
The key of the warehouse the sync reads from. Can't change after creation.
Get a warehouse sync
#Retrieve a warehouse sync by its key in a given environment.
Endpoint
Path parameters
The key of the warehouse sync to retrieve.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
Upsert a warehouse sync
#Creates a warehouse sync, or saves a new draft of it if it exists. Fields left out keep their current values. Pass commit=true to publish the draft. A draft that fails to publish stays saved.
Endpoint
Path parameters
The key of the warehouse sync to upsert.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Whether to commit the resource at the same time as modifying it.
The message to commit the resource with, only used if commit is true.
Request body
A warehouse sync payload for upsert or validate. Fields left out keep their current values. warehouse_key, target_type, and target are required to create a sync and can't change after. Change enabled and frequency_minutes with the settings endpoint.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
An optional description of the sync. Maximum of 280 characters allowed.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
The version_id of the sync you last read. When it isn't the current version, someone saved since, and the request is refused.
The key of the warehouse the sync reads from. Can't change after creation.
Returns
Wraps the WarehouseSync response under the warehouse_sync key.
A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
WarehouseSync
#A warehouse sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.
Attributes
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
When the sync was created. (read-only).
An optional description of the sync. Maximum of 280 characters allowed.
Whether the sync runs on its schedule.
The slug of the environment the sync belongs to. (read-only).
How often the sync runs, in minutes.
Whether the sync has a draft that hasn't been published.
The unique key of the sync in its environment.
The last run failure, cleared when a run succeeds.
What went wrong.
Where the run failed: reading the warehouse (extract), sending rows to Knock (load), or applying them (apply).
When the sync was last published.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
Why the last publish didn't go live, when it failed.
The SHA hash of the sync's definition. (read-only).
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The status of the sync.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
When the returned version was saved. (read-only).
The ID of the version returned. Send it back when saving to make sure nobody saved since.
The key of the warehouse the sync reads from. Can't change after creation.
WarehouseSyncTarget
#The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
Attributes
The key of the static audience the rows become members of.
The object collection the rows are written to.
WarehouseSyncRequest
#A warehouse sync payload for upsert or validate. Fields left out keep their current values. warehouse_key, target_type, and target are required to create a sync and can't change after. Change enabled and frequency_minutes with the settings endpoint.
Attributes
How the sync detects changed and deleted rows.
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
An optional description of the sync. Maximum of 280 characters allowed.
How columns map to Knock fields.
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
The name of the sync. Must be at minimum 1 character and at maximum 255 characters in length.
The column that uniquely identifies each row.
The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.
The collection or audience the sync writes to. object and subscription syncs set collection, and static_audience_membership syncs set audience_key. Null for user and tenant syncs.
The key of the static audience the rows become members of.
The object collection the rows are written to.
What each row becomes in Knock. Can't change after creation.
The version_id of the sync you last read. When it isn't the current version, someone saved since, and the request is refused.
The key of the warehouse the sync reads from. Can't change after creation.
WarehouseSyncMapping
#Maps one column from the warehouse to one field in Knock.
Attributes
What to do when the column is NULL. set_null clears the Knock field, and preserve keeps its current value.
The column to read. Can be a dotted path into an object column, such as PROPERTIES.plan.
The Knock field to write the value to.
WarehouseSyncChangeTracking
#How the sync detects changed and deleted rows.
Attributes
A boolean column that marks a row as deleted. Requires last_modified_column.
A timestamp column that changes whenever a row changes. With it, each run reads only rows changed since the last run.
WarehouseSyncSource
#The rows a warehouse sync reads: a table or view (relation), or the result of a SQL query (sql).
Attributes
Whether the sync reads a table or view, or a SQL query.
The name of the table or view. Required when mode is relation.
The SQL query to read. Required when mode is sql.
The schema of the table or view. Required when mode is relation.