Warehouse syncs

Warehouse sync commands enable you to manage syncs from the CLI. A sync reads rows from a warehouse on a schedule and writes them to Knock as users, tenants, objects, audience members, or subscriptions.

A push saves a draft of the sync. Pass --commit to publish it. Syncs aren't part of the commit and promote flow: you push a sync into the environment it syncs into, including Production. To copy a sync into another environment, pull it from one environment and push it to the other.

knock pull and knock push don't include warehouse syncs. Use knock warehouse-sync pull and knock warehouse-sync push. Syncs aren't available in branch environments.

When syncs are pulled from Knock, they are stored in directories named by their sync key. Each sync directory contains a warehouse_sync.json file. The sync key is the directory name.

warehouse-syncs/
└── users/
  └── warehouse_sync.json

warehouse_sync.json has these fields you can edit:

• name. The name of the sync.
• description. Optional context about what the sync does.
• warehouse_key. The warehouse the sync reads from. Can't change after the sync is created.
• target_type. What each row becomes in Knock: user, tenant, object, static_audience_membership, or subscription. Can't change after the sync is created.
• target. The object collection (collection) for object and subscription syncs, or the static audience (audience_key) for static_audience_membership syncs. Null for user and tenant syncs. Can't change after the sync is created.
• source. The rows to read. Set mode to relation with a schema and name to read a table or view, or to sql with a query.
• primary_key_column. The column that uniquely identifies each row.
• change_tracking. The last_modified_column and is_deleted_column the sync uses to detect changed and deleted rows. See create a sync and deleted rows.
• mappings. How columns map to Knock fields. Each mapping has a source_column, a target_field, and an on_null of set_null or preserve.

Pulled files also include a __readonly object with the sync's status, schedule, and other fields that a push doesn't change. A push never changes the sync's schedule. Pause a sync or change how often it runs from its Settings tab in the dashboard, or with the Management API. A sync that a push creates starts on the default schedule.

A field set to null is cleared on the next push. A field left out of the file keeps its current value.

Display all warehouse syncs for an environment, with their warehouse, target, and status.

Flags

Display a single warehouse sync from an environment, including its status and setup.

Flags

Pull one or more warehouse syncs from an environment into a local file system. Knock CLI will create a new sync directory or update the existing sync directory in the local file system.

By default this command will resolve to the warehouse syncs resource directory via your knock.json file. When not set, will use the current working directory as the default. In the case of the --all flag, the target directory path will be resolved via your knock.json file or the --warehouse-syncs-dir flag.

Note: if pulling the target sync for the first time (or all syncs), Knock CLI will ask to confirm before writing to the local file system.

See the Warehouse sync file structure section for details on how sync files are organized.

Flags

Push one or more warehouse syncs from a local file system to Knock. Knock saves a new draft of an existing sync with the matching key, or creates the sync if it doesn't exist yet. Pass --commit to publish the draft too. A draft that fails to publish stays saved.

A push doesn't change the sync's schedule, and a sync that a push creates starts on the default schedule.

By default this command will resolve to the warehouse syncs resource directory via your knock.json file. When not set, will use the current working directory as the default. In the case of the --all flag, the target directory path will be resolved via your knock.json file or the --warehouse-syncs-dir flag.

Note: you must be directly above the target sync directory when running the warehouse-sync push command, so the CLI can locate the warehouse_sync.json file.

Flags

Validate one or more warehouse syncs from a local file system. Knock checks the sync the same way as the warehouse-sync push command, except without saving it.

Flags

Run a published warehouse sync now, instead of waiting for its schedule. Knock doesn't start another run while one is in progress. See the run's progress with knock warehouse-sync runs.

Flags

Display the most recent runs of a warehouse sync, newest first, with their status and how many rows were applied or failed. See run history.

Flags

Open a warehouse sync in the Knock dashboard. This command opens the sync's page in your default browser.

Flags