---
title: "flow_nodes"
description: "Workflow node table, describing node types, configurations, and link relationships."
---

# flow_nodes

## Field Descriptions

| Field Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| id | snowflakeId | No (System generated) | - | Primary key ID, generated by the system. |
| key | uid | Yes (Recommended) | - | Unique key for the node, remains unchanged when copied across versions, used for task result mapping (`jobs.nodeKey`). It is recommended to let the system generate it automatically; **do not** modify it in copied workflow versions. |
| title | string | No | - | Node title (for display). |
| workflow | belongsTo | Yes | - | Associated workflow (`workflows`), actual foreign key is `workflowId`; typically, a node must be associated with a workflow version when created. |
| upstream | belongsTo | No | - | Upstream node (`flow_nodes`), foreign key is `upstreamId`. The first node in the main chain is `null`. |
| branches | hasMany | No | - | Collection of branch nodes (`flow_nodes`), derived via `upstreamId` + `branchIndex`, used for queries only. |
| branchIndex | integer | No | - | Branch sequence number. `null` indicates the main chain; branch nodes use integer indices (e.g., `0/1` are common for condition nodes, the default branch for multi-conditions is `0`). See specific node type documentation for more details. |
| downstream | belongsTo | No | - | Downstream node (`flow_nodes`), foreign key is `downstreamId`; used for reconnecting to the main chain or at the end of a branch. |
| type | string | Yes | - | Node type (corresponding to the `instruction` name). |
| config | json | No | {} | Node configuration. Structure depends on `type`; specific node configurations are not detailed in this document. |

## Modeling Considerations

- Link Connectivity: When creating/deleting nodes, consistency of `upstreamId`/`downstreamId` and `branchIndex` must be maintained; using built-in actions handles insertion positions automatically.
- Executed versions cannot be modified: When a workflow version has already been executed (`versionStats.executed > 0`), adding/deleting nodes or modifying configurations is not allowed. Changes should be made in a new version.

## Example Values

```ts
const values = {
  key: '2kjfd91',
  title: 'Calculation',
  type: 'calculation',
  workflowId: 10001,
  upstreamId: 10000,
  branchIndex: null,
  config: {
    engine: 'formula.js',
    expression: '{{$context.data.a}}+1',
  },
};
```