> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação das funções de substituição de strings

# Funções de substituição de strings

[Funções gerais de strings](/pt-BR/reference/functions/regular-functions/string-functions) e [funções de pesquisa em strings](/pt-BR/reference/functions/regular-functions/string-search-functions) são descritas separadamente.

<Note>
  A documentação abaixo é gerada a partir da system table `system.functions`.
</Note>

{/*AUTOGENERATED_START*/}

<div id="format">
  ## format
</div>

Introduzido em: v20.1.0

Formata a string `pattern` com os valores (strings, inteiros etc.) listados nos argumentos, de modo semelhante à formatação em Python.
A string `pattern` pode conter campos de substituição entre chaves `{}`.
Tudo o que não estiver entre chaves é considerado texto literal e copiado literalmente para a saída.
Os caracteres de chave literais podem ser escapados com duas chaves: `{{` e `}}`.
Os nomes dos campos podem ser números (começando em zero) ou estar vazios (nesse caso, recebem implicitamente números crescentes).

**Sintaxe**

```sql theme={null}
format(pattern, s0[, s1, ...])
```

**Argumentos**

* `pattern` — A string de formato que contém placeholders. [`String`](/pt-BR/reference/data-types/string)
* `s0[, s1, ...]` — Um ou mais valores para substituir os placeholders no padrão. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna uma string formatada. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Placeholders numerados**

```sql title=Query theme={null}
SELECT format('{1} {0} {1}', 'World', 'Hello')
```

```response title=Response theme={null}
┌─format('{1} {0} {1}', 'World', 'Hello')─┐
│ Hello World Hello                       │
└─────────────────────────────────────────┘
```

**Numeração implícita**

```sql title=Query theme={null}
SELECT format('{} {}', 'Hello', 'World')
```

```response title=Response theme={null}
┌─format('{} {}', 'Hello', 'World')─┐
│ Hello World                       │
└───────────────────────────────────┘
```

<div id="overlay">
  ## overlay
</div>

Introduzido na versão: v24.9.0

Substitui parte da string `input` por outra string `replace`, começando no índice `offset`, baseado em 1.

**Sintaxe**

```sql theme={null}
overlay(s, replace, offset[, length])
```

**Argumentos**

* `s` — A string de entrada. [`String`](/pt-BR/reference/data-types/string)
* `replace` — A string de substituição. [`const String`](/pt-BR/reference/data-types/string)
* `offset` — Um inteiro do tipo `Int` (indexado a partir de 1). Se `offset` for negativo, ele será contado a partir do final da string `s`. [`Int`](/pt-BR/reference/data-types/int-uint)
* `length` — Opcional. Um inteiro do tipo `Int`. `length` especifica o comprimento do trecho dentro da string de entrada `s` que será substituído. Se `length` não for especificado, o número de bytes removidos de `s` será igual ao comprimento de `replace`; caso contrário, `length` bytes serão removidos. [`Int`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna uma string com o trecho substituído. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Substituição básica**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'mother', 4) AS res;
```

```response title=Response theme={null}
┌─res──────────────────────┐
│ My mother is from Mexico.│
└──────────────────────────┘
```

**Substituição com tamanho**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'dad', 4, 6) AS res;
```

```response title=Response theme={null}
┌─res───────────────────┐
│ My dad is from Mexico.│
└───────────────────────┘
```

<div id="overlayUTF8">
  ## overlayUTF8
</div>

Introduzido em: v24.9.0

Substitui parte da string `s` por outra string, `replace`, começando no índice `offset`, baseado em 1.
Pressupõe que a string contenha texto válido codificado em UTF-8.
Se essa suposição for violada, nenhuma exceção é lançada e o resultado é indefinido.

**Sintaxe**

```sql theme={null}
overlayUTF8(s, replace, offset[, length])
```

**Argumentos**

* `s` — A string de entrada. [`String`](/pt-BR/reference/data-types/string)
* `replace` — A string de substituição. [`const String`](/pt-BR/reference/data-types/string)
* `offset` — Um inteiro `Int` (baseado em 1). Se `offset` for negativo, ele é contado a partir do fim da string de entrada `s`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
* `length` — Opcional. Especifica o comprimento do trecho na string de entrada `s` que será substituído. Se `length` não for especificado, o número de caracteres removidos de `s` será igual ao comprimento de `replace`; caso contrário, serão removidos `length` caracteres. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna uma string com o conteúdo substituído. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Substituição UTF-8**

```sql title=Query theme={null}
SELECT overlayUTF8('Mein Vater ist aus Österreich.', 'der Türkei', 20) AS res;
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Mein Vater ist aus der Türkei.│
└───────────────────────────────┘
```

<div id="printf">
  ## printf
</div>

Introduzido em: v24.8.0

A função `printf` formata a string fornecida com os valores (strings, inteiros, números de ponto flutuante etc.) listados nos argumentos, de maneira semelhante à função `printf` em C++.
A string de formato pode conter especificadores de formato iniciados pelo caractere `%`.
Tudo o que não estiver contido em `%` e no especificador de formato seguinte é considerado texto literal e copiado literalmente para a saída.
O caractere `%` literal pode ser escapado com `%%`.
A string de formato pode ser uma constante ou uma expressão de coluna, permitindo diferentes padrões de formato por linha.

**Sintaxe**

```sql theme={null}
printf(format[, sub1, sub2, ...])
```

**Argumentos**

* `format` — A string de formato com especificadores `%`. [`String`](/pt-BR/reference/data-types/string)
* `sub1, sub2, ...` — Opcional. Zero ou mais valores a serem substituídos na string de formato. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna uma string formatada. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Formatação no estilo C++**

```sql title=Query theme={null}
SELECT printf('%%%s %s %d', 'Hello', 'World', 2024);
```

```response title=Response theme={null}
┌─printf('%%%s %s %d', 'Hello', 'World', 2024)─┐
│ %Hello World 2024                            │
└──────────────────────────────────────────────┘
```

<div id="regexpQuoteMeta">
  ## regexpQuoteMeta
</div>

Introduzido em: v20.1.0

Adiciona uma barra invertida antes destes caracteres com significado especial em expressões regulares: `\0`, `\\`, `|`, `(`, `)`, `^`, `$`, `.`, `[`, `]`, `?`, `*`, `+`, `{`, `:`, `-`.
Esta implementação difere ligeiramente de re2::RE2::QuoteMeta.
Ela escapa o byte zero como `\0` em vez de `\x00` e escapa apenas os caracteres necessários.

**Sintaxe**

```sql theme={null}
regexpQuoteMeta(s)
```

**Argumentos**

* `s` — A string de entrada que contém caracteres que devem ser escapados em regex. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com os caracteres especiais de regex escapados. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Escapar caracteres especiais de regex**

```sql title=Query theme={null}
SELECT regexpQuoteMeta('Hello. [World]? (Yes)*') AS res
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Hello\. \[World\]\? \(Yes\)\* │
└───────────────────────────────┘
```

<div id="replaceAll">
  ## replaceAll
</div>

Introduzido em: v1.1.0

Substitui todas as ocorrências da substring `pattern` em `haystack` pela string `replacement`.

**Sintaxe**

```sql theme={null}
replaceAll(haystack, pattern, replacement)
```

**Aliases**: `replace`

**Argumentos**

* `haystack` — A string de entrada na qual buscar. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — A substring a ser encontrada e substituída. [`const String`](/pt-BR/reference/data-types/string)
* `replacement` — A string que substituirá o padrão. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com todas as ocorrências do padrão substituídas. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Substituir todas as ocorrências**

```sql title=Query theme={null}
SELECT replaceAll('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res──────────┐
│ Hi, Hi world │
└──────────────┘
```

<div id="replaceOne">
  ## replaceOne
</div>

Introduzido em: v1.1.0

Substitui a primeira ocorrência da substring `pattern` em `haystack` pela string `replacement`.

**Sintaxe**

```sql theme={null}
replaceOne(haystack, pattern, replacement)
```

**Argumentos**

* `haystack` — A string de entrada na qual a busca será feita. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — A substring a ser encontrada e substituída. [`const String`](/pt-BR/reference/data-types/string)
* `replacement` — A string usada para substituir a substring. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com a primeira ocorrência da substring substituída. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Substituir a primeira ocorrência**

```sql title=Query theme={null}
SELECT replaceOne('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res─────────────┐
│ Hi, Hello world │
└─────────────────┘
```

<div id="replaceRegexpAll">
  ## replaceRegexpAll
</div>

Introduzido em: v1.1.0

Semelhante a `replaceRegexpOne`, mas substitui todas as ocorrências do padrão.
Como exceção, se uma expressão regular corresponder a uma substring vazia, a substituição não será feita mais de uma vez.

**Sintaxe**

```sql theme={null}
replaceRegexpAll(haystack, pattern, replacement)
```

**Aliases**: `REGEXP_REPLACE`

**Argumentos**

* `haystack` — A string de entrada na qual a busca será feita. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — O padrão de expressão regular a ser encontrado. [`const String`](/pt-BR/reference/data-types/string)
* `replacement` — A string que substituirá o padrão; pode conter substituições. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com todas as correspondências da expressão regular substituídas. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Substituir todos os caracteres pela versão duplicada**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello123', '.', '\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res──────────────────┐
│ HHeelllloo112233     │
└──────────────────────┘
```

**Exemplo de substituição de substring vazia**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello, World!', '^', 'here: ') AS res
```

```response title=Response theme={null}
┌─res─────────────────┐
│ here: Hello, World! │
└─────────────────────┘
```

<div id="replaceRegexpOne">
  ## replaceRegexpOne
</div>

Introduzido em: v1.1.0

Substitui a primeira ocorrência da substring que corresponde à expressão regular `pattern` (na sintaxe do re2) em `haystack` pela string `replacement`.
`replacement` pode conter substituições `\0-\9`.
As substituições `\1-\9` correspondem aos grupos de captura de 1 a 9 (submatches), e a substituição `\0` corresponde à correspondência inteira.
Para usar o caractere literal `\` nas strings `pattern` ou `replacement`, escape-o com `\`.
Lembre-se também de que literais de string exigem escape adicional.

**Sintaxe**

```sql theme={null}
replaceRegexpOne(haystack, pattern, replacement)
```

**Argumentos**

* `haystack` — A string de entrada na qual será feita a pesquisa. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — O padrão de expressão regular a ser encontrado. [`const String`](/pt-BR/reference/data-types/string)
* `replacement` — A string que substituirá o padrão; pode conter substituições. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com a primeira correspondência da expressão regular substituída. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Convertendo datas ISO para o formato americano**

```sql title=Query theme={null}
SELECT DISTINCT
    EventDate,
    replaceRegexpOne(toString(EventDate), '(\\d{4})-(\\d{2})-(\\d{2})', '\\2/\\3/\\1') AS res
FROM test.hits
LIMIT 7
FORMAT TabSeparated
```

```response title=Response theme={null}
2014-03-17      03/17/2014
2014-03-18      03/18/2014
2014-03-19      03/19/2014
2014-03-20      03/20/2014
2014-03-21      03/21/2014
2014-03-22      03/22/2014
2014-03-23      03/23/2014
```

**Copiando uma string dez vezes**

```sql title=Query theme={null}
SELECT replaceRegexpOne('Hello, World!', '.*', '\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World! │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="translate">
  ## translate
</div>

Introduzido na versão: v22.7.0

Substitui caracteres na string `s` usando um mapeamento de caracteres um para um definido pelas strings `from` e `to`.
`from` e `to` devem ser strings ASCII constantes.
Se `from` e `to` tiverem o mesmo tamanho, cada ocorrência do primeiro caractere de `from` em `s` será substituída pelo primeiro caractere de `to`, a segunda ocorrência de `from` em `s` será substituída pelo segundo caractere de `to` e assim por diante.
Se `from` contiver mais caracteres do que `to`, todas as ocorrências dos caracteres no final de `from` que não tiverem caractere correspondente em `to` serão removidas de `s`.
Caracteres não ASCII em `s` não são modificados pela função.

**Sintaxe**

```sql theme={null}
translate(s, from, to)
```

**Argumentos**

* `s` — A string de entrada a ser convertida. [`String`](/pt-BR/reference/data-types/string)
* `from` — Uma string ASCII constante que contém os caracteres a serem substituídos. [`const String`](/pt-BR/reference/data-types/string)
* `to` — Uma string ASCII constante que contém os caracteres de substituição. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna uma string com as substituições de caracteres aplicadas. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Mapeamento de caracteres**

```sql title=Query theme={null}
SELECT translate('Hello, World!', 'delor', 'DELOR') AS res
```

```response title=Response theme={null}
┌─res───────────┐
│ HELLO, WORLD! │
└───────────────┘
```

**Comprimentos distintos**

```sql title=Query theme={null}
SELECT translate('clickhouse', 'clickhouse', 'CLICK') AS res
```

```response title=Response theme={null}
┌─res───┐
│ CLICK │
└───────┘
```

<div id="translateUTF8">
  ## translateUTF8
</div>

Introduzido em: v22.7.0

Como [`translate`](#translate), mas pressupõe que `s`, `from` e `to` sejam strings codificadas em UTF-8.

**Sintaxe**

```sql theme={null}
translateUTF8(s, from, to)
```

**Argumentos**

* `s` — string UTF-8 de entrada a ser convertida. [`String`](/pt-BR/reference/data-types/string)
* `from` — uma string UTF-8 constante que contém os caracteres a serem substituídos. [`const String`](/pt-BR/reference/data-types/string)
* `to` — uma string UTF-8 constante que contém os caracteres de substituição. [`const String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna um valor do tipo de dado `String`. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Conversão de caracteres UTF-8**

```sql title=Query theme={null}
SELECT translateUTF8('Münchener Straße', 'üß', 'us') AS res;
```

```response title=Response theme={null}
┌─res──────────────┐
│ Munchener Strase │
└──────────────────┘
```