ClickHouse icon

ClickHouse

Query, insert, update, delete, and manage ClickHouse tables. Supports AI agent tool use with schema discovery, auto-pagination for large results, and parameterized queries.

Actions11

Upsert

AI-generated

Summary

Upsert rows into a ClickHouse table, inserting new records and updating existing ones based on key columns.

Inputs

  • table (required) — The target ClickHouse table to upsert into; can be a name or an expression.
  • keyColumns (required) — Comma-separated list of columns that form the unique key for upsert; must match the table's ORDER BY columns for ReplacingMergeTree.
  • options — Configuration group containing chunk size, column mapping, and other settings for the upsert operation.
  • database — Optional override for the database name or ID; can be an expression.
  • forceInsert — If true, bypasses engine detection and always uses INSERT mode.
  • onlyMapped — If true, only explicitly mapped columns are included; unmapped fields are ignored.
  • versionColumn — Column used to determine row version for ReplacingMergeTree; defaults to the last inserted row.

Output shape

a single JSON object describing the upsert result, containing success, operation, upsertedRows, table, keyColumns, engineType, and mode; may also include an error field when continueOnFail is enabled

When continueOnFail is disabled, errors are thrown; otherwise a successful run returns the metadata object and failures are reported via the error field.

Examples

Example 1: Upsert user records

operation: upsert, table: users, keyColumns: id, user_id, chunkSize: 1000, columnMapping: {sourceField: username, targetColumn: user_name}

Example 2: Bulk upsert with forceInsert enabled

operation: upsert, table: orders, keyColumns: order_id, forceInsert: true, versionColumn: updated_at

Links

Discussion