# Create a stream out

> Choose the Salesforce object, how each record is found and the sanda value for every field, then preview what the first run would send.

A stream out is four choices: the object it writes to, how it finds each record, which sanda value goes in each field, and when it runs. Saving sends nothing. The stream opens with a preview of what its first run would write.

## Before you start

- **A connected Salesforce org.** See [connect Salesforce](https://docs.sanda-os.com.au/streams/connect-salesforce).
- **The values on your semantic fluid.** A stream out sends metrics, dimensions and columns of the tables on your [semantic map](https://docs.sanda-os.com.au/semantic-fluid/the-map).
- **A way to match rows to records.** Usually that is the Salesforce Id, which a Salesforce sync lands in your warehouse beside every record. See [Salesforce](https://docs.sanda-os.com.au/connectors/salesforce).

## Create the stream out

:::steps
1. **Open the editor.** Go to **Data · Streams**, open the **Streams out** tab, and press **New stream out**.
2. **Name it.** Type a **Name**, such as "account revenue". The **Description** is optional.
3. **Choose where it writes.** Pick the **Salesforce org** and the **Object**. The list holds the objects the Salesforce user can edit, the most used first.
4. **Choose how each record is found.** Under **How each record is found**, pick the **Salesforce field**: the record Id, or a field marked External ID in Salesforce. Then pick the **sanda value that holds it**, a column or a dimension. When you match on the Id and your Salesforce connection landed an Id column for the object, sanda fills it in and marks it as a suggestion.
5. **Map the fields.** Under **What it writes**, pick a Salesforce field on the left and the sanda value for it on the right. Press **Add a field** for each one more.
6. **Narrow the rows, if you need to.** Under **Which rows**, press **add a condition**. Leave it empty to send a value for every record.
7. **Choose when it runs.** Under **When it runs**, pick a connection in **Run after a sync**, a stream in under **Run after a stream in lands** if you have any, a schedule under **On a schedule**, or more than one. See [when it runs](#when-it-runs).
8. **Save.** Press **Save stream**. Until everything the stream needs is chosen, the button is unavailable and the line beside it says what is missing. The stream opens with **Preview the next run** already read, and nothing has been sent.
:::

Read the preview, then press **Run now** to send the first run. See [preview and run](#preview-and-run).

## Matching on the Id or an External ID

| Match on | What a run does | Use it when |
|---|---|---|
| The record Id | Updates records that already exist, and never creates one. A row whose value is not an Id of that object is refused before anything is sent. | The numbers are about records that came from Salesforce, which is the usual case. |
| An External ID field | Updates the record with that value, and creates a record when none has it. | The records belong to another system, and Salesforce keeps that system's key in an External ID field. |

A stream out that can create records needs every field Salesforce requires to create one. The editor names any it is missing under **What it writes**. If every record already exists, you can leave them out, but a row with no matching record is then refused.

The sanda value that finds a record is a column or a dimension, never a metric: a metric is worked out over many rows and can't say which one record a row is about. If two rows of a stream out match one record, neither is sent, because sending both would let whichever came last win. That happens when a column you send has more than one value for a record, such as an invoice date on an Account. Send a metric for it instead, such as the latest invoice date, so each record has one row.

## Which fields it can write

The **Salesforce field** lists hold the fields the Salesforce user can edit. sanda writes text and picklist fields, checkboxes, numbers, currency and percent fields, dates, dates with times, times, and lookups (as an Id). Each value is formatted for its field before it is sent:

- A number is rounded to the field's decimal places. The hint under the field says how many.
- Text longer than the field holds is refused for that record, and the run says which.
- A checkbox takes true or false. Yes and no, and 1 and 0, also work.
- A date is sent as the day, and a date and time as an exact moment.
- An empty value clears the field in Salesforce.

Under **What it writes**, the fields sanda can't write are listed with the reason: formula fields, auto-numbered fields, fields the Salesforce user can't edit, address and location fields (map their parts instead, such as the street and the city), and fields that hold a file.

One stream out writes at most 100 fields and reads at most 50,000 records.

:::caution Check a percent field in the preview
Salesforce stores 12.5 in a percent field to mean 12.5 per cent. A sanda metric that holds the fraction (0.125) is sent as it stands and shows as 0.125 per cent. Look at a percent field in the preview before the first run.
:::

## Which rows

**Which rows** narrows the records a stream out sends values for, with the same conditions you use elsewhere in sanda. A named period such as `last_30_days` stays a period, so the window moves with each run. sanda works it out in UTC each time the stream runs. See [filters and date ranges](https://docs.sanda-os.com.au/reference/filters).

A record that stops matching a stream's conditions keeps the value the stream last wrote. The stream stops sending to it, and does not clear the field.

## When it runs

- **Run after a sync.** The stream runs whenever the connection you pick lands new rows, which is when sanda's numbers can have changed. This is usually all a stream out needs.
- **Run after a stream in lands.** The same, for a [stream in](https://docs.sanda-os.com.au/streams/in): it runs whenever that stream lands new or changed rows. When the numbers it sends are built by a task from what the stream in lands, add both to a [stream graph](https://docs.sanda-os.com.au/streams/graphs) instead, so the stream out waits for the task to finish.
- **On a schedule.** **Every few minutes** (as often as your edition allows: every 15 minutes on Standard), **Daily** or **Weekly**. A stream keeps its own clock, so it isn't tied to the grid other schedules run on. A daily or weekly time stays at the same local time when the clocks change.
- **By hand only.** Choose **Manual** and leave the two after-runs empty. The stream runs when someone presses **Run now**.
- **Pause itself after.** How many failed runs in a row before the stream pauses itself. 0 never pauses. See [when runs fail](https://docs.sanda-os.com.au/streams/runs#when-runs-fail).

## Preview and run

Open a stream out and press **Preview** under **Preview the next run**. sanda reads the stream's rows from your warehouse, formats them for their fields and compares them with what Salesforce last accepted, without sending anything. You see:

- how many rows were read, how many records a run would send, and how many are unchanged;
- the first twenty records it would send, each marked **first send** or **changed**;
- the rows that can't be sent as they stand, with the reason.

Anyone who can open the console can preview, read-only members included. When it looks right, press **Run now**.

## Change a stream out

Open the stream and press **Edit**, change what you need, and press **Save changes**.

- Renaming a stream, or changing its conditions or when it runs, asks nothing of Salesforce.
- Changing the org, the object or the field that finds a record starts the stream over: the next run sends every record, because what the stream remembers belongs to its old target. The editor says so before you save.
- Changing the fields it writes means the next run sends the records whose values changed, which after a new field is usually every one.