---
title: "split | Speedscale Docs"
description: "Pick one segment of a delimited string with the split transform in Speedscale, let downstream transforms rewrite that segment, then re-join the segments with the same separator."
canonical: "https://docs.speedscale.com/guides/transformation/transforms/split/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/transforms/split/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/transforms/split/)

# split

The `split` transform divides a token into segments using a literal substring separator, exposes one segment to the rest of the chain, and on the way out re-joins the segments with the same separator — so the surrounding segments are preserved.

It's the simplest way to address one piece of a delimited string (CSV cell, path segment, header value list) without resorting to regex.

*   **Transform type name (config/API):** `split`
*   **Shorthand format:** `split(index=...,separator=...)`

<a id="quick-start"></a>

## Quick Start

Take the first comma-separated value:

```json
"type": "split",
"config": {
    "index": "0"
}
```

Take the third path segment of a slash-delimited URL field:

```text
res_body() → json_path(path="path") → split(index=2, separator="/")
```

<a id="how-it-works"></a>

## How It Works

The transform runs in two phases as a bookend around the rest of the chain.

1.  **First phase** — split the token into segments using `separator` as a literal substring. Return the segment at `index` to the downstream chain. The segment list is remembered.
2.  **Second phase** — replace the segment at `index` in the remembered list with whatever the downstream chain produced, then re-join the list with `separator`. The rebuilt string is the chain's output.

```text
input:    "shortest,straw"
          └─ 1st phase, separator=",", index=0:
                segments = ["shortest", "straw"]
                returns "shortest"
          └─ downstream produces "challenge"
          └─ 2nd phase: segments[0] = "challenge", rejoin
output:   "challenge,straw"
```

<a id="separator-is-a-single-literal-substring"></a>

### `separator` Is a Single Literal Substring

`separator` is a single literal string, **not** a character class and **not** a list of alternative delimiters. `separator=",;"` splits on the two-character substring `,;`, not on either `,` or `;`. Use [`regex`](https://docs.speedscale.com/guides/transformation/transforms/regex/) when you need character-class or alternation behavior.

The separator can be any length:

| Input | Separator | Segments |
| --- | --- | --- |
| `a,b,c` | `,` | `["a", "b", "c"]` |
| \`a |  | b |
| `riding{asdf}{}{}through` | `{asdf}{}{}` | `["riding", "through"]` |

<a id="index-out-of-range"></a>

### Index Out of Range

If `index` is greater than or equal to the number of segments, both phases are no-ops:

*   The first phase returns the original token unchanged.
*   The downstream chain runs on the original token.
*   The second phase re-joins the original segments (no edit), returning the un-modified string.

This is intentional — a chain configured against optional segments doesn't crash on payloads that lack them. It also means **you cannot use `split` to append a new segment** when the index is past the end. Use [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) or construct the value upstream if you need to grow the field.

<a id="empty-token"></a>

### Empty Token

An empty input string yields `[""]` (a single empty segment). With the default `index=0`, the first phase returns the empty string and the downstream chain operates on it. The re-join is also the original empty string.

<a id="configuration"></a>

## Configuration

```json
"type": "split",
"config": {
    "index": "<non-negative integer>",
    "separator": "<literal substring>"
}
```

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `index` | No | `0` | Zero-based index of the segment to extract. Negative values fail chain initialization. |
| `separator` | No | `,` | Literal substring used as the delimiter. Treated as a single string, not as a list of alternatives. |

<a id="examples"></a>

## Examples

<a id="example-1--first-tag-from-a-comma-separated-list"></a>

### Example 1 — First tag from a comma-separated list

```text
req_body() → json_path(path="tags") → split(index=0)
```

*   Input field: `javascript,react,frontend,typescript`
*   After `split`: `javascript`
*   If the downstream chain rewrites that segment to `vue`, the field becomes `vue,react,frontend,typescript`.

<a id="example-2--pick-a-path-segment"></a>

### Example 2 — Pick a path segment

```text
res_body() → json_path(path="path") → split(index=2, separator="/")
```

*   Input field: `/api/v1/users/profile`
*   Segments: `["", "api", "v1", "users", "profile"]`
*   After `split`: `v1` — note the leading empty segment from the leading `/`.

If the downstream chain rewrites `v1` to `v2`, the field becomes `/api/v2/users/profile`.

<a id="example-3--take-the-primary-language"></a>

### Example 3 — Take the primary language

```text
http_req_header(header="Accept-Language") → split(index=0, separator=",")
```

*   Input: `en-US,en;q=0.9,fr;q=0.8`
*   After `split`: `en-US`.

To strip the optional weight (e.g. `en;q=0.9` → `en`), follow with another `split(index=0, separator=";")`.

<a id="example-4--multi-character-separator"></a>

### Example 4 — Multi-character separator

```text
req_body() → json_path(path="message") → split(index=3, separator="{asdf}{}{}")
```

*   Input field: `riding{asdf}{}{}through{asdf}{}{}shortest{asdf}{}{}straw{asdf}{}{}has{asdf}{}{}been`
*   After `split`: `straw` (index 3).

<a id="example-5--out-of-range-index-passes-through-unchanged"></a>

### Example 5 — Out-of-range index passes through unchanged

```text
split(index=500, separator=",")
```

*   Input: `shortest,straw`
*   Output of both phases: `shortest,straw`. No transformation, no error.

<a id="common-misconceptions"></a>

## Common Misconceptions

1.  **"`separator` is a list of delimiters."** No. It's a single literal substring. `separator=",;"` splits on the two-character substring `,;`, not on either `,` or `;`. For alternation, use [`regex`](https://docs.speedscale.com/guides/transformation/transforms/regex/).
    
2.  **"It's a character class like `strings.Trim`."** No. Each character of `separator` is part of one literal delimiter.
    
3.  **"Index `-1` means the last segment."** No. Negative indices are rejected at chain initialization.
    
4.  **"An out-of-range index is an error."** No. The first phase returns the input unchanged, the downstream chain runs on the original token, and the second phase re-joins the original segments. The field passes through.
    
5.  **"`split` works on bytes."** It works on the UTF-8 string form of the token. Multi-byte separators (e.g. unicode characters) split correctly.
    
6.  **"You can extend a field by writing to an index past its length."** No. Out-of-range writes are dropped. Build the new field upstream with `constant`/`replace` instead.
    

<a id="troubleshooting"></a>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Chain init: `index not parsable as an integer (or a negative number)` | `index` is non-numeric or negative | Use a non-negative integer |
| Field passes through unchanged | `index` is past the end of the segment list, or the separator never matches | Verify the separator literally appears in the token; check the segment count |
| Wrong segment extracted from a path with a leading delimiter | Leading delimiters produce an empty first segment | Account for the empty `""` at index 0, e.g. use `index=N+1` |
| `;`\-separated values not splitting on `,` and `;` together | `separator` is a single literal substring | Use [`regex`](https://docs.speedscale.com/guides/transformation/transforms/regex/) for alternation, or chain two `split` transforms |
| Output is unchanged after a downstream `constant` | The downstream output went to an out-of-range index | Lower `index` to point at a real segment |

<a id="related-transforms"></a>

## Related Transforms

*   [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) — whole-string literal replacement when you don't need segment indexing.
*   [`regex`](https://docs.speedscale.com/guides/transformation/transforms/regex/) — pattern-based extraction with alternation, capture groups, and character classes.
*   [`json_path`](https://docs.speedscale.com/guides/transformation/transforms/json_path/) — for JSON-aware extraction before splitting.
*   [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/) — pair with `split` to propagate a segment's new value across the entire RRPair.

<a id="advanced-notes"></a>

## Advanced Notes

*   The transform does not require recorded response data.
*   The segment list is held on the transform instance, so concurrent invocations on the same instance are not supported. (Each transform-chain construction yields its own instance — this only matters for very unusual configurations.)
*   Re-joining uses the configured `separator` verbatim. If `separator` is empty, the join produces the concatenation of the segments.
