Docs
Kiwi Flow
Version Current

API reference

Database activities

Relational (SQL) and NoSQL (MongoDB, Cassandra, Couchbase, DynamoDB, DocumentDB, CosmosDB) connections and operations.

Flow Current 17 min read Updated

Relational (SQL) and NoSQL (MongoDB, Cassandra, Couchbase, DynamoDB, DocumentDB, CosmosDB) connections and operations. This page covers 14 activity types.

aws_documentdb#

AWS DocumentDB Operation. Find, insert, update, delete, upsert, or run an aggregation pipeline against an AWS DocumentDB collection (MongoDB-API-compatible).

Operations: find, insert, update, delete, upsert, aggregate. Set with the operation input.

Input Type Required Description
connection string No Reuse an AWS DocumentDB Connection node already on the canvas — its client and transaction (if any) apply automatically. Leave unset to configure a standalone connection below instead. Can reuse a aws_documentdb_connection node.
connectionString string No DocumentDB connection string, e.g. mongodb://user:pass@cluster-endpoint:27017/?tls=true&retryWrites=false (only used when no Connection node is selected above)
database string Yes Database name
collection string Yes Collection name
filter object No Query filter, e.g. {"status":"active"} (find: optional/matches all; update/delete/upsert: required) Used when operation is find, update, delete, upsert.
sort object No Sort spec, e.g. {"createdAt":-1} Used when operation is find.
limit number No Maximum number of documents to return Used when operation is find.
document object No Document to insert (single-document insert), or the full replacement document (upsert) Used when operation is insert, upsert.
documents string No Array of documents for a bulk insert, as JSON text — use instead of 'document' for inserting more than one Used when operation is insert.
update object Yes Fields to update, e.g. {"status":"shipped"} — auto-wrapped in $set unless it already uses $ operators Used when operation is update.
many boolean No Update/delete every matching document instead of just the first (default: false) Used when operation is update, delete.
pipeline string Yes Aggregation pipeline as JSON text — an array of stage objects, e.g. [{"$match":{...}},{"$group":{...}}] Used when operation is aggregate.
Output Type Description
output.rows array Matched documents (find/aggregate)
output.count number Number of documents returned (find/aggregate)
output.insertedId string Inserted document's _id (single insert)
output.insertedIds array Inserted documents' _ids (bulk insert)
output.insertedCount number Number of documents inserted
output.modifiedCount number Number of documents modified (update/upsert)
output.deletedCount number Number of documents deleted
output.matchedCount number Number of documents matched (upsert)
output.upsertedId string Newly inserted document's _id when upsert created a new document

Config block example:

json
{
  "aws_documentdb": {
    "operation": "find"
  }
}

aws_documentdb_connection#

AWS DocumentDB Connection. Opens an AWS DocumentDB client (with optional multi-document transaction and retry) for later AWS DocumentDB Operation activities to reuse.

Input Type Required Description
connectionString string Yes DocumentDB connection string, e.g. mongodb://user:pass@cluster-endpoint:27017/?tls=true&retryWrites=false Secret: stored encrypted.
useTransaction boolean No Start a multi-document transaction session on connect — commits automatically when the run succeeds, aborts automatically when it fails
retryAttempts number No Number of times to retry the initial connectivity ping if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live client/session — pick this node in an AWS DocumentDB Operation activity's "Connection" field to reuse it

Config block example:

json
{}

aws_dynamodb#

AWS DynamoDB Operation. Get, put, update, delete, query, or scan items in an AWS DynamoDB table.

Operations: getItem, putItem, updateItem, deleteItem, query, scan. Set with the operation input.

Input Type Required Description
connection string No Reuse an AWS DynamoDB Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a aws_dynamodb_connection node.
region string No AWS region, e.g. us-east-1 (only used when no Connection node is selected above)
accessKeyId string No AWS access key id (only used when no Connection node is selected above)
secretAccessKey string No AWS secret access key (only used when no Connection node is selected above)
serviceUrl string No Override endpoint URL, e.g. http://localhost:8000 for a local DynamoDB instance (only used when no Connection node is selected above)
table string Yes Table name
key object Yes Primary key attribute:value pairs, e.g. {"id": "123"} Used when operation is getItem, updateItem, deleteItem.
item object Yes Full item to write, including its primary key attribute(s) Used when operation is putItem.
updateExpression string Yes DynamoDB update expression, e.g. SET age = :age, #s = :status Used when operation is updateItem.
keyConditionExpression string Yes DynamoDB key condition expression, e.g. id = :id Used when operation is query.
filterExpression string No DynamoDB filter expression applied after the key condition (query) or over the whole table (scan) Used when operation is query, scan.
expressionAttributeValues object No Named parameter values bound to :name placeholders in updateExpression/keyConditionExpression/filterExpression Used when operation is updateItem, query, scan.
Output Type Description
output.item object Retrieved item (getItem)
output.found boolean Whether the item existed (getItem)
output.rows array Matched items (query/scan)
output.count number Number of items returned (query/scan)
output.success boolean Whether the operation completed successfully (putItem/updateItem/deleteItem)

Config block example:

json
{
  "aws_dynamodb": {
    "operation": "getItem"
  }
}

aws_dynamodb_connection#

AWS DynamoDB Connection. Opens an AWS DynamoDB client (with optional retry) for later AWS DynamoDB Operation activities to reuse.

Input Type Required Description
region string Yes AWS region, e.g. us-east-1
accessKeyId string Yes AWS access key id
secretAccessKey string Yes AWS secret access key Secret: stored encrypted.
serviceUrl string No Override endpoint URL, e.g. http://localhost:8000 for a local DynamoDB instance
retryAttempts number No Number of times to retry the initial connectivity check if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live client — pick this node in an AWS DynamoDB Operation activity's "Connection" field to reuse it

Config block example:

json
{}

azure_cosmosdb#

Azure CosmosDB Operation. Read, insert, upsert, update, delete, or query items in an Azure CosmosDB container (Core SQL API).

Operations: readItem, insert, upsert, update, delete, query. Set with the operation input.

Input Type Required Description
connection string No Reuse an Azure CosmosDB Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a azure_cosmosdb_connection node.
connectionString string No Cosmos account connection string, e.g. AccountEndpoint=https://...;AccountKey=...; (only used when no Connection node is selected above)
database string Yes Database name
container string Yes Container name
id string Yes Item id Used when operation is readItem, update, delete.
partitionKey string No Partition key value — required for readItem/insert/upsert/update/delete; optional for query (a single-partition query when set, cross-partition otherwise) Used when operation is readItem, insert, upsert, update, delete, query.
document object Yes Document body — must include an "id" property (Cosmos requires every item to have one) Used when operation is insert, upsert, update.
query string Yes Cosmos SQL API query, e.g. SELECT * FROM c WHERE c.status = @status Used when operation is query.
parameters object No Named parameter values bound to @param placeholders in the query Used when operation is query.
Output Type Description
output.document object Retrieved document (readItem)
output.found boolean Whether the item existed (readItem)
output.rows array Matched items (query)
output.count number Number of items returned (query)
output.success boolean Whether the operation completed successfully (insert/upsert/update/delete)

Config block example:

json
{
  "azure_cosmosdb": {
    "operation": "readItem"
  }
}

azure_cosmosdb_connection#

Azure CosmosDB Connection. Opens an Azure CosmosDB client (with optional retry) for later Azure CosmosDB Operation activities to reuse.

Input Type Required Description
connectionString string Yes Cosmos account connection string, e.g. AccountEndpoint=https://...;AccountKey=...; Secret: stored encrypted.
retryAttempts number No Number of times to retry the initial connectivity check if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live client — pick this node in an Azure CosmosDB Operation activity's "Connection" field to reuse it

Config block example:

json
{}

cassandra#

Cassandra Operation. Select, insert, update, delete, or execute raw CQL against an Apache Cassandra keyspace.

Operations: select, insert, update, delete, execute_cql. Set with the operation input.

Input Type Required Description
connection string No Reuse a Cassandra Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a cassandra_connection node.
contactPoints string No Comma-separated list of contact-point hosts, e.g. 10.0.0.1,10.0.0.2 (only used when no Connection node is selected above)
port number No CQL native transport port (default: 9042)
keyspace string No Keyspace name (only used when no Connection node is selected above)
username string No Username, if authentication is enabled
password string No Password, if authentication is enabled
table string Yes Table name Used when operation is select, insert, update, delete.
columns string No Comma-separated column list to select (default: *) Used when operation is select.
where string No WHERE clause fragment with ? placeholders, e.g. "id = ?" (select: optional; update/delete: required) Used when operation is select, update, delete.
values object Yes Column:value pairs to insert — Cassandra's INSERT already upserts by primary key, so there is no separate upsert operation Used when operation is insert.
set object Yes Column:value pairs to update Used when operation is update.
cql string Yes Raw CQL statement with ? placeholders Used when operation is execute_cql.
parameters string No Ordered array of values bound to the ? placeholders in where/cql, as JSON text, e.g. [42, "active"] Used when operation is select, update, delete, execute_cql.
Output Type Description
output.rows array Matched rows (select / execute_cql when the statement is a SELECT)
output.count number Number of rows returned
output.success boolean Whether the statement executed successfully (insert/update/delete/execute_cql non-query)

Config block example:

json
{
  "cassandra": {
    "operation": "select"
  }
}

cassandra_connection#

Cassandra Connection. Opens an Apache Cassandra session (with optional retry) for later Cassandra Operation activities to reuse.

Input Type Required Description
contactPoints string Yes Comma-separated list of contact-point hosts, e.g. 10.0.0.1,10.0.0.2
port number No CQL native transport port (default: 9042)
keyspace string Yes Keyspace name
username string No Username, if authentication is enabled
password string No Password, if authentication is enabled Secret: stored encrypted.
retryAttempts number No Number of times to retry the initial connection if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live session — pick this node in a Cassandra Operation activity's "Connection" field to reuse it

Config block example:

json
{}

couchbase#

Couchbase Operation. Get, insert, upsert, replace, remove, or query documents in a Couchbase bucket.

Operations: get, insert, upsert, replace, remove, query. Set with the operation input.

Input Type Required Description
connection string No Reuse a Couchbase Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a couchbase_connection node.
connectionString string No Cluster connection string, e.g. couchbase://localhost or couchbases://host for TLS (only used when no Connection node is selected above)
username string No Username (only used when no Connection node is selected above)
password string No Password (only used when no Connection node is selected above)
bucket string Yes Bucket name
scope string No Scope name (default: _default)
collection string No Collection name (default: _default)
key string Yes Document key Used when operation is get, insert, upsert, replace, remove.
document object Yes Document body Used when operation is insert, upsert, replace.
statement string Yes N1QL query statement, with $name placeholders bound from parameters Used when operation is query.
parameters object No Named parameter values bound to $name placeholders in the N1QL statement Used when operation is query.
Output Type Description
output.document object Retrieved document (get)
output.found boolean Whether the document existed (get)
output.rows array Matched rows (query)
output.count number Number of rows returned (query)
output.success boolean Whether the operation completed successfully (insert/upsert/replace/remove)

Config block example:

json
{
  "couchbase": {
    "operation": "get"
  }
}

couchbase_connection#

Couchbase Connection. Opens a Couchbase cluster connection (with optional retry) for later Couchbase Operation activities to reuse.

Input Type Required Description
connectionString string Yes Cluster connection string, e.g. couchbase://localhost or couchbases://host for TLS
username string Yes Username
password string Yes Password Secret: stored encrypted.
retryAttempts number No Number of times to retry the initial connection if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live cluster connection — pick this node in a Couchbase Operation activity's "Connection" field to reuse it

Config block example:

json
{}

mongodb#

MongoDB Operation. Find, insert, update, delete, upsert, or run an aggregation pipeline against a MongoDB collection.

Operations: find, insert, update, delete, upsert, aggregate. Set with the operation input.

Input Type Required Description
connection string No Reuse a MongoDB Connection node already on the canvas — its client and transaction (if any) apply automatically. Leave unset to configure a standalone connection below instead. Can reuse a mongodb_connection node.
connectionString string No MongoDB connection string, e.g. mongodb://user:pass@host:27017 (only used when no Connection node is selected above)
database string Yes Database name
collection string Yes Collection name
filter object No Query filter, e.g. {"status":"active"} (find: optional/matches all; update/delete/upsert: required) Used when operation is find, update, delete, upsert.
sort object No Sort spec, e.g. {"createdAt":-1} Used when operation is find.
limit number No Maximum number of documents to return Used when operation is find.
document object No Document to insert (single-document insert), or the full replacement document (upsert) Used when operation is insert, upsert.
documents string No Array of documents for a bulk insert, as JSON text — use instead of 'document' for inserting more than one Used when operation is insert.
update object Yes Fields to update, e.g. {"status":"shipped"} — auto-wrapped in $set unless it already uses $ operators Used when operation is update.
many boolean No Update/delete every matching document instead of just the first (default: false) Used when operation is update, delete.
pipeline string Yes Aggregation pipeline as JSON text — an array of stage objects, e.g. [{"$match":{...}},{"$group":{...}}] Used when operation is aggregate.
Output Type Description
output.rows array Matched documents (find/aggregate)
output.count number Number of documents returned (find/aggregate)
output.insertedId string Inserted document's _id (single insert)
output.insertedIds array Inserted documents' _ids (bulk insert)
output.insertedCount number Number of documents inserted
output.modifiedCount number Number of documents modified (update/upsert)
output.deletedCount number Number of documents deleted
output.matchedCount number Number of documents matched (upsert)
output.upsertedId string Newly inserted document's _id when upsert created a new document

Config block example:

json
{
  "mongodb": {
    "operation": "find"
  }
}

mongodb_connection#

MongoDB Connection. Opens a MongoDB client (with optional multi-document transaction and retry) for later MongoDB Operation activities to reuse.

Input Type Required Description
connectionString string Yes MongoDB connection string, e.g. mongodb://user:pass@host:27017 Secret: stored encrypted.
useTransaction boolean No Start a multi-document transaction session on connect (requires a replica set/sharded cluster) — commits automatically when the run succeeds, aborts automatically when it fails
retryAttempts number No Number of times to retry the initial connectivity ping if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
Output Type Description
output.connection object The live client/session — pick this node in a MongoDB Operation activity's "Connection" field to reuse it

Config block example:

json
{}

sql_database#

SQL Operation. Select, insert, update, delete, upsert, or execute raw SQL against a relational database — SQL Server, PostgreSQL, MySQL, MariaDB, SQLite, Oracle, Firebird, DB2, SAP HANA, Informix, or MS Access.

Operations: select, insert, update, delete, upsert, execute_sql, execute_kmql. Set with the operation input.

Input Type Required Description
connection string No Reuse a SQL Connection node already on the canvas — its connection, transaction, and default schema apply automatically. Leave unset to configure a standalone connection below instead. Can reuse a sql_database_connection node.
engine string No Database engine (only used when no Connection node is selected above) Allowed values: sqlserver, postgresql, mysql, mariadb, sqlite, oracle, firebird, db2, saphana, informix, msaccess.
connectionString string No Database connection string (only used when no Connection node is selected above) — use the "Build…" button to construct it from server/port/database/credentials for the selected engine
table string Yes Table name Used when operation is select, insert, update, delete, upsert.
columns string No Comma-separated column list to select (default: *) Used when operation is select.
where string No WHERE clause fragment, e.g. "Id = @id" (select); required for update/delete Used when operation is select, update, delete.
orderBy string No ORDER BY clause fragment Used when operation is select.
limit number No Maximum number of rows to return Used when operation is select.
values object Yes Column:value pairs to write Used when operation is insert, upsert.
set object Yes Column:value pairs to update Used when operation is update.
keyColumns string Yes Comma-separated column(s) identifying the row to match on Used when operation is upsert.
sql string Yes Raw SQL statement to execute — plain SQL for whichever engine this connection targets (Kiwi Flow's own {{...}} template syntax is reserved for referencing workflow/activity values, so it is not available here for Kiwi ORM's cross-engine markup) Used when operation is execute_sql.
kmql string Yes Kiwi ORM markup query (KMQL) — e.g. {{T: orders}}, {{C: colA, colB}}, {{UPSERT: table, keyCols}}...{{/UPSERT}}. Use @param_name (not {{...}}) for value placeholders, bound via the parameters field below — Kiwi Flow's own {{...}} interpolation does not run on this field, so KMQL markup is never misread as a workflow reference. Used when operation is execute_kmql.
parameters object No Named parameter values for @param placeholders referenced in where/sql/kmql Used when operation is select, update, delete, execute_sql, execute_kmql.
Output Type Description
output.rows array Matched rows (select / execute_sql / execute_kmql when the statement is a query)
output.count number Number of rows returned (select / execute_sql / execute_kmql query)
output.rowsAffected number Rows affected (insert/update/delete/upsert/execute_sql/execute_kmql non-query)

Config block example:

json
{
  "sql_database": {
    "operation": "select"
  }
}

sql_database_connection#

SQL Connection. Opens a relational database connection (with optional transaction, isolation level, retry, and session settings) for later SQL Operation activities to reuse.

Input Type Required Description
engine string Yes Database engine Allowed values: sqlserver, postgresql, mysql, mariadb, sqlite, oracle, firebird, db2, saphana, informix, msaccess.
connectionString string Yes Database connection string — use the "Build…" button to construct it from server/port/database/credentials for the selected engine Secret: stored encrypted.
useTransaction boolean No Begin a transaction on connect — commits automatically when the run succeeds, rolls back automatically when it fails (no separate commit/rollback node needed)
isolationLevel string No Transaction isolation level (only used when 'Use transaction' is on; default: driver default) Allowed values: ReadUncommitted, ReadCommitted, RepeatableRead, Serializable, Snapshot.
commandTimeoutSeconds number No Command timeout in seconds for statements run through this connection
defaultSchema string No Default schema — bare table names in referencing SQL Database activities are automatically qualified with this schema
sessionVariables string No One raw SQL statement per line, run in order immediately after connecting (e.g. SET DATEFORMAT ymd;) — engine-specific syntax is your responsibility
retryAttempts number No Number of times to retry the initial connection if it fails (default: 0)
retryDelaySeconds number No Delay between connection retry attempts, in seconds (default: 2)
connectionLifetime string No "run" (default): every referencing SQL Operation activity shares this one connection/transaction. "perActivity": each referencing activity opens and closes its own connection using these same settings. Allowed values: run, perActivity. Default: run.
batchSize number No Batch size for future bulk-operation activities to consume (reserved — no current operation uses this yet)
Output Type Description
output.connection object The live connection/session — pick this node in a SQL Operation activity's "Connection" field to reuse it
output.engine string The database engine this connection targets

Config block example:

json
{}