Docs
Kiwi Flow
Version Current

API reference

Kiwi Fabric activities

Federated queries, distributed transactions, data-source registration and file upload against Kiwi Fabric.

Flow Current 8 min read Updated

Federated queries, distributed transactions, data-source registration and file upload against Kiwi Fabric. This page covers 5 activity types.

kiwi_fabric_connection#

Kiwi Fabric Connection. Opens a connection to a Kiwi Fabric instance for later Kiwi Federated Query / Kiwi Distributed Transaction activities to reuse.

Input Type Required Description
baseUrl string Yes Kiwi Fabric API base URL, e.g. https://fabric.example.com
apiKey string Yes Kiwi Fabric API key (sent as Authorization: Bearer) Secret: stored encrypted.
Output Type Description
output.connection object The live client — pick this node in a Kiwi Federated Query / Kiwi Distributed Transaction activity's "Connection" field to reuse it

Config block example:

json
{}

kiwi_fabric_datasource#

Kiwi Fabric Data Source. Register a Kiwi Fabric data source and/or a queryable capability (table) on it — makes an uploaded file, or any other source, queryable by name.

Operations: registerDataSource, registerCapability. Set with the operation input.

Input Type Required Description
connection string No Reuse a Kiwi Fabric Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_fabric_connection node.
baseUrl string No Kiwi Fabric API base URL, e.g. https://fabric.example.com (only used when no Connection node is selected above)
apiKey string No Kiwi Fabric API key (only used when no Connection node is selected above) Secret: stored encrypted.
name string No Data source name to register (must be unique in Kiwi Fabric) Used when operation is registerDataSource.
type string No Data source category (default: File) Used when operation is registerDataSource. Allowed values: File, Rdbms, NoSql, Rest, Soap, Cloud, VectorDb. Default: File.
subType string No Sub-type within the category — for File: CSV, TSV, Json, Parquet, Excel, Avro, Delta, Iceberg (auto-detected from the extension if omitted) Used when operation is registerDataSource.
connectionStringTemplate string No For File sources: the file's storage path — use a Kiwi Fabric File upload's output.relativePath. For other types: the connection string. Used when operation is registerDataSource.
description string No Optional description
username string No Optional — only needed for credentialed source types Used when operation is registerDataSource.
password string No Optional — only needed for credentialed source types Used when operation is registerDataSource. Secret: stored encrypted.
dataSourceName string No The data source this capability belongs to (must already exist — see registerDataSource) Used when operation is registerCapability.
tableName string No The queryable table name — this is what you SELECT ... FROM in a Kiwi Federated Query Used when operation is registerCapability.
columns array No Column schema: [{"name": "...", "type": "string|int|long|float|double|decimal|bool|DateTime|Guid", "isNullable": true}] Used when operation is registerCapability.
identityColumn string No Identity/primary-key column name — optional for a read-only capability Used when operation is registerCapability.
predicateCapabilities string No How much filtering can be pushed down to the source (default: None) Used when operation is registerCapability. Allowed values: None, Partial, Full.
supportsProjection boolean No Whether column projection can be pushed down (default: true) Used when operation is registerCapability.
supportsPaging boolean No Whether paging can be pushed down (default: true) Used when operation is registerCapability.
kind string No Capability kind (default: Table) Used when operation is registerCapability. Allowed values: Table, StoredProcedure, SpRead, SpWrite. Default: Table.
Output Type Description
output.id string The registered data source's id (registerDataSource)
output.name string The registered data source's name (registerDataSource)
output.type string The registered data source's type (registerDataSource)
output.subType string The registered data source's sub-type (registerDataSource)
output.connectionStringTemplate string The registered data source's connection string/path (registerDataSource)
output.isActive boolean Whether the data source is active (registerDataSource)
output.dataSourceName string The capability's owning data source (registerCapability)
output.tableName string The registered, now-queryable table name (registerCapability)
output.columns array The capability's registered column schema (registerCapability)
output.predicateCapabilities string Pushdown level Kiwi Fabric recorded (registerCapability)
output.supportsProjection boolean Whether projection pushdown is enabled (registerCapability)
output.supportsPaging boolean Whether paging pushdown is enabled (registerCapability)

Config block example:

json
{
  "kiwi_fabric_datasource": {
    "operation": "registerCapability"
  },
  "inputs": [
    {
      "name": "dataSourceName",
      "value": "sales_upload"
    },
    {
      "name": "tableName",
      "value": "sales"
    },
    {
      "name": "columns",
      "value": [
        {
          "name": "productId",
          "type": "int"
        },
        {
          "name": "amount",
          "type": "decimal"
        }
      ]
    }
  ]
}

kiwi_fabric_file#

Kiwi Fabric File. Upload a file into Kiwi Fabric's managed storage, or list/delete previously uploaded files.

Operations: upload, list, delete. Set with the operation input.

Input Type Required Description
connection string No Reuse a Kiwi Fabric Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_fabric_connection node.
baseUrl string No Kiwi Fabric API base URL, e.g. https://fabric.example.com (only used when no Connection node is selected above)
apiKey string No Kiwi Fabric API key (only used when no Connection node is selected above) Secret: stored encrypted.
storageId string No Use a governed Storage instead of a literal path/contentBase64 below — the physical location is configured by an administrator and never exposed to the workflow. Used when operation is upload.
areaId string No Storage Area within the Storage above — the RBAC boundary this operation is authorized against. Used when operation is upload.
relativePath string No Path relative to the Storage Area's root to upload Used when operation is upload.
path string No Local file path to upload. Either this or contentBase64 is required. Ignored when a Storage is picked above. Used when operation is upload.
contentBase64 string No File content as base64 — an alternative to path for uploading content produced earlier in the run without touching disk. Requires fileName. Ignored when a Storage is picked above. Used when operation is upload.
fileName string No File name to register with Kiwi Fabric (defaults to path's own file name when using path; required when using contentBase64) Used when operation is upload.
format string No Format hint — auto-detected from the file extension when omitted (required for formats with no reliable extension, e.g. Delta/Iceberg) Used when operation is upload. Allowed values: Csv, Tsv, Json, Parquet, Excel, Delta, Iceberg, Avro.
fileId string No The file's id (from a prior upload/list) to delete Used when operation is delete.
Output Type Description
output.fileId string The uploaded file's id (upload)
output.originalName string The uploaded file's original name (upload)
output.relativePath string Storage path/URI Kiwi Fabric registered the file under (upload) — pass as FilePath when separately registering a data source
output.sizeBytes number File size in bytes (upload)
output.format string The format Kiwi Fabric recorded for the file (upload)
output.uploadedAt string Upload timestamp (upload)
output.files array Previously uploaded files — each shaped like the upload outputs above (list)
output.message string Result message (delete)

Config block example:

json
{
  "kiwi_fabric_file": {
    "operation": "upload"
  },
  "inputs": [
    {
      "name": "path",
      "value": "C:/reports/sales.xlsx"
    },
    {
      "name": "format",
      "value": "Excel"
    }
  ]
}

kiwi_fabric_query#

Kiwi Federated Query. Run a SQL query that transparently federates across Kiwi Fabric's registered data sources.

Input Type Required Description
connection string No Reuse a Kiwi Fabric Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_fabric_connection node.
baseUrl string No Kiwi Fabric API base URL, e.g. https://fabric.example.com (only used when no Connection node is selected above)
apiKey string No Kiwi Fabric API key (only used when no Connection node is selected above) Secret: stored encrypted.
sql string Yes SQL to execute, e.g. SELECT * FROM orders o JOIN crm_customers c ON o.customer_id = c.id WHERE o.total > @minTotal
parameters object No Named parameters referenced in the SQL as @name, e.g. {"minTotal": 100}
Output Type Description
output.rows array Result rows, each a dictionary of column name to value
output.rowCount number Number of rows returned
output.originalSql string The SQL that was executed
output.totalMs number Total query execution time in milliseconds
output.sourceSummaries array One entry per underlying data source touched — rows fetched, timing, and predicate/projection pushdown flags

Config block example:

json
{
  "inputs": [
    {
      "name": "sql",
      "value": "SELECT * FROM orders WHERE total > @minTotal"
    },
    {
      "name": "parameters",
      "value": {
        "minTotal": 100
      }
    }
  ]
}

kiwi_fabric_saga#

Kiwi Distributed Transaction. Execute a multi-step distributed transaction (SAGA) via Kiwi Fabric, with automatic compensation on failure.

Input Type Required Description
connection string No Reuse a Kiwi Fabric Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_fabric_connection node.
baseUrl string No Kiwi Fabric API base URL, e.g. https://fabric.example.com (only used when no Connection node is selected above)
apiKey string No Kiwi Fabric API key (only used when no Connection node is selected above) Secret: stored encrypted.
sagaId string No Optional saga id (a GUID is generated if omitted)
steps array Yes Saga steps: [{id, table, operation: insert|update|delete|rawsql|restcall|execute, dependsOn, payload/setClauses+filter/actionSql+compensationSql/actionUrl+.../spParameters, ...}] — steps with the same dependsOn run in parallel; on any failure, already-completed steps are compensated automatically in reverse order.
parameters object No Saga-level named values, referenced from stored-procedure step parameter bindings
Output Type Description
output.sagaId string The executed saga's id
output.success boolean Whether every step completed (false if any step failed and was compensated)
output.durationMs number Total saga execution time in milliseconds
output.errorMessage string Failure reason, if any
output.steps array Per-step results — forward steps, then compensation steps (id suffixed ":compensation") if compensation ran
output.gaps array Steps with no compensation path that could not be reversed, if any

Config block example:

json
{
  "inputs": [
    {
      "name": "steps",
      "value": [
        {
          "id": "s1",
          "table": "orders",
          "operation": "insert",
          "payload": {
            "customerId": 42,
            "total": 199.99
          }
        }
      ]
    }
  ]
}