# replace

[Read this page in HTML](https://www.scopedb.io/docs/reference/functions/string/replace)

Replaces every occurrence of a substring.

## Syntax

```scopeql
replace(<string>, <pattern>, <replacement>)
```

## Arguments

| Argument        | Type     | Description                                                        |
| --------------- | -------- | ------------------------------------------------------------------ |
| `<string>`      | `string` | String to transform.                                               |
| `<pattern>`     | `string` | Substring to replace. An empty pattern leaves the input unchanged. |
| `<replacement>` | `string` | Replacement text. An empty string removes each match.              |

## Returns

Returns `string`. Returns NULL if any input is NULL.

## Examples

Replace every literal hyphen with an underscore before grouping event names from two producers.

```scopeql
VALUES ('payment-failed'), ('payment_failed'), ('checkout-started')
SELECT replace($0, '-', '_') AS event
GROUP BY event
AGGREGATE count() AS events
ORDER BY event
```

```text
+------------------+--------+
| event            | events |
+------------------+--------+
| checkout_started | 1      |
| payment_failed   | 2      |
+------------------+--------+
```

The replacement is literal. Use `regexp_replace` when the part to replace varies, such as a numeric ID.