> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/reference/actions/action-data-sources.md).

# Action data sources

An *action data source* is a collection of records, scoped to an action.It is the action-scoped counterpart to runtime-only [data sources](https://docs.appfarm.io/reference/apps/data.md#data-sources) in apps, and like an app data source it can be backed by an [object class](https://docs.appfarm.io/reference/data-model/object-classes.md), an [enumerated type](https://docs.appfarm.io/reference/data-model/enumerated-types.md), or a calendar.

An action data source exists only for the duration of the action run that declares it. Subsequent action nodes in the same run can read and write to it in the same way any data source in the platform is used, and it is discarded when the action completes.

Action data sources are always runtime-only. Changes to objects in an action data source are written to the database only when you run the [Persist objects](https://docs.appfarm.io/library/action-nodes/persist-objects.md) action node, and deleting an object only removes it from the data source.

Action data sources are useful for work that an action performs on a collection of object-class records — staging records before they are persisted, transforming records as they flow through an action, collecting results to return to the caller, or making enum values and time-period objects available to the action nodes that need them.

Action data sources are available in app actions and flow actions. Actions in services don't have action data sources.

## Creating an action data source

Action data sources are defined on their parent action, alongside action variables and action params. In both flows and apps, action data is configured on the **Action data** tab in the action editor.

Click **Add Data Source** and choose the backing:

* **Object class data source.** Select the object class and a cardinality — **One** for a single record, **Many** for a collection. The object class determines the properties on each record.
* **Calendar data source.** Set a **From** datetime, a **To** datetime, and a **Resolution**. The data source generates one object per time period in the range. Object Class is **Calendar** and Cardinality is **Many**. For the properties available on each calendar object, see [Calendar data sources](https://docs.appfarm.io/reference/apps/data/calendar-data-sources.md).
* **Enumerated type data source.** Select the enum. Cardinality is **Many**. The data source exposes the enum's values to the action.

## Using an action data source

**As the way to work with object classes from a flow.** Flows run on the server and do not have access to app-level data sources. A flow reads object class records into an action data source, works with them there, and persists them back to the database. To create, update, or delete records directly in the database instead, see [Working directly with the database in a flow](#working-directly-with-the-database-in-a-flow).

**As a persistence target.** Records on an action data source are written to the database with the [Persist Objects](https://docs.appfarm.io/library/action-nodes/persist-objects.md) action node.

**As intermediate collection state.** An action can read, filter, transform, and write against an action data source in the same way an app action would work with an app data source.

## Working directly with the database in a flow

In a flow, the [Create object](https://docs.appfarm.io/library/action-nodes/create-object.md), [Update object](https://docs.appfarm.io/library/action-nodes/update-object.md), and [Delete objects](https://docs.appfarm.io/library/action-nodes/delete-objects.md) action nodes can work directly against the database instead of an action data source. This works in the same way as a [data connector](https://docs.appfarm.io/reference/apps/data/data-sources.md#data-connectors) in apps, and is useful for bulk operations.

The **Data Source** picker on these action nodes has two tabs:

* **Create action data**, **Update action data**, or **Delete action data** lists the action's own data sources.
* **Create in database**, **Update in database**, or **Delete from database** lists the object classes in the data model. Select an object class to work directly against the database.

For example, to delete all `Order` objects with `Status` `Cancelled`, add a Delete objects action node, select **Delete from database** and `Order`, set **Selection** to `Filtered selection`, and add the filter `Order.Status EQUALS Cancelled`.

Selecting an object class adds a data connector for it to the action. A data connector never holds any objects, so it can't be used to read data.

The [Aggregate data](https://docs.appfarm.io/library/action-nodes/aggregate-data.md) action node reads from the database in the same way, from the **Aggregate from database** tab.

## Returning an action data source from an action

An action data source can be marked **return from action**, which makes it available to the caller as an output. When the caller — for example, a **Run Flow** or **Run Action** node — invokes the action, the returned data source is mapped into a data source in the calling context, either another action data source or an app data source. The mapping UI and its options are documented on the reference pages for [Run Flow](https://docs.appfarm.io/library/action-nodes/run-flow.md) and [Run Action](https://docs.appfarm.io/library/action-nodes/run-action.md).

On an API endpoint action, the option is named **Return from API Endpoint**, and it includes the data source in the response of the endpoint. A returned data source on an API endpoint action also has a **Node Name**, the identifier used for it in the response.

In a flow action of the type **Flow Action** (not an API endpoint or MCP tool), a returned action data source can additionally be marked **Streamable**. When the caller is the Run Flow action node, writes to the data source during the action's run are delivered to the caller's mapping as they occur, instead of only when the action completes. If the called action fails, any partial writes are reverted, so a failed run still writes nothing.

## Reference data sources

By default, a reference property on an action data source resolves only its display value. To bind into the properties of the referenced object (a deep-data binding), declare a reference data source for that property. The reference data source tells the platform which other data source on the action holds the referenced objects, so the reference can be resolved and its properties browsed and bound to, the same way as on an app data source.

A reference data source is declared per reference property, and its target must be an action data source on the same action, backed by the reference property's object class. Deep-data bindings on an action data source resolve in memory from data already loaded on the action, so a data source on a different action or at the app level cannot be used as the target.

{% hint style="info" %}
**Good to know**

If a declared reference data source cannot resolve, the binding shows a warning. This happens when the target data source has been deleted, its object class does not match the reference property, or it is not on the same action. In the last case, the reference still resolves its display value, but the deep-data binding does not.
{% endhint %}

## Properties

| Property               | Description                                                                                                                                                                                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**               | A descriptive name.                                                                                                                                                                                                                                                                                                      |
| **Node Name**          | *Returned data source on an API endpoint action.* The identifier of the data source in the response of the endpoint.                                                                                                                                                                                                     |
| **Object Class**       | The [object class](https://docs.appfarm.io/reference/data-model/object-classes.md) that backs the data source. Determines the properties available on each record. For calendar data sources, this is read-only and always `Calendar`.                                                                                   |
| **Enumerated Type**    | *Enumerated type data source.* The [enum](https://docs.appfarm.io/reference/data-model/enumerated-types.md) that backs the data source.                                                                                                                                                                                  |
| **Cardinality**        | Whether the data source holds a single record (**One**) or a collection of records (**Many**). For calendar and enumerated type data sources, **Many** is the only option.                                                                                                                                               |
| **From**               | *Calendar data source.* The start of the calendar period.                                                                                                                                                                                                                                                                |
| **To**                 | *Calendar data source.* The end of the calendar period.                                                                                                                                                                                                                                                                  |
| **Resolution**         | *Calendar data source.* The length of each time period generated — `Year`, `Quarter`, `Month`, `Week`, `Day`, or `Hour`.                                                                                                                                                                                                 |
| **Auto Create**        | *Object class data source with cardinality One.* Automatically create an object in the data source when the action starts, and again whenever the data source is emptied.                                                                                                                                                |
| **Runtime Properties** | Add runtime properties to the action data source. These are calculated or temporary properties that exist only at runtime, in the same way as runtime properties on app data sources.                                                                                                                                    |
| **Description**        | A longer description of the action data source. For your own reference.                                                                                                                                                                                                                                                  |
| **Return from Action** | *Object class data source.* Make the action data source available to the caller as an output. On an API endpoint action, this is named **Return from API Endpoint** and includes the data source in the response. See [Returning an action data source from an action](#returning-an-action-data-source-from-an-action). |
| **Streamable**         | *Available if Return from Action is enabled, in a flow action of the type Flow Action.* Deliver mid-action writes to the caller incrementally during the action run instead of only at the end. See [Returning an action data source from an action](#returning-an-action-data-source-from-an-action).                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appfarm.io/reference/actions/action-data-sources.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
