# replace

> Documentation index: http://docs.tenzir.com/llms.txt

Replaces literal substrings within a string.

```tql
replace(x:string, pattern:string, replacement:string, [max=int], [ignore_case=bool]) -> string
```

## Description

The `replace` function returns a new string where occurrences of `pattern` in `x` are replaced with `replacement`, up to `max` times. If `max` is omitted, all occurrences are replaced.

Set `ignore_case=true` to match using full Unicode case folding instead of case-sensitive matching.

### `x: string`

The subject to replace the action on.

### `pattern: string`

The pattern to replace in `x`.

### `replacement: string`

The replacement value for `pattern`.

### `max = int (optional)`

The maximum number of replacements to perform.

If the option is not set, all occurrences are replaced.

### `ignore_case: bool` (optional)

If `true`, matches the literal `pattern` using full Unicode case folding.

Defaults to `false`.

## Examples

### Replace all occurrences of a character

```tql
from {x: "hello".replace("l", "r")}
```

```tql
{x: "herro"}
```

### Replace a limited number of occurrences

```tql
from {x: "hello".replace("l", "r", max=1)}
```

```tql
{x: "herlo"}
```

### Replace case-insensitively

```tql
from {
  ascii: "Connection ERROR".replace("error", "warning", ignore_case=true),
  unicode: "Fußstraße".replace("STRASSE", "weg", ignore_case=true),
}
```

```tql
{
  ascii: "Connection warning",
  unicode: "Fußweg",
}
```

## See Also

* [`replace_regex`](http://docs.tenzir.com/reference/functions/replace_regex.md)
* [`replace`](http://docs.tenzir.com/reference/operators/replace.md)
* [Manipulate strings](http://docs.tenzir.com/guides/transformation/manipulate-strings.md)