# JSON_INSERT

> Inserir novos valores em um documento JSON sem sobrescrever os dados existentes com SQL no StackQL.

Source: https://stackql.io/pt-br/language-spec/functions/json/json_insert

Insere novos valores em um documento JSON nos caminhos especificados, sem sobrescrever os valores existentes.

Veja também:  
[[`SELECT`]](/language-spec/select) [[` JSON_EXTRACT `]](/language-spec/functions/json/json_extract) [[` JSON_SET `]](/language-spec/functions/json/json_set) [[` JSON_REPLACE `]](/language-spec/functions/json/json_replace)

* * * 

## Sintaxe

```sql
SELECT JSON_INSERT(json_column, path, new_value) FROM <multipartIdentifier>;
```

## Argumentos

__*json_column*__  
A coluna ou expressão JSON a ser modificada.

__*path*__  
A expressão de caminho JSON em que o novo valor deve ser inserido. Se o caminho já existir, o valor original nesse caminho não é substituído.

__*new_value*__  
O valor a ser inserido no caminho especificado do documento JSON.

## Valor(es) retornado(s)
Retorna o documento JSON com o novo valor inserido se o caminho especificado ainda não existir; caso contrário, retorna o documento JSON sem alterações.

:::note Comportamento se uma chave existir

| Função                                                       | Sobrescreve se já existir? | Cria se não existir? |
|--------------------------------------------------------------|----------------------------|----------------------|
| [`json_insert()`](/language-spec/functions/json/json_insert) | Não                        | Sim                  |
| [`json_replace()`](/language-spec/functions/json/json_replace) | Sim                        | Não                  |
| [`json_set()`](/language-spec/functions/json/json_set)       | Sim                        | Sim                  |

:::

* * *

## Exemplos

### Inserir um novo par chave-valor em um objeto JSON

```sql
-- Example: Insert a new 'region' key with the value 'Europe' into a JSON object
SELECT JSON_INSERT(json_data, '$.region', 'Europe') as updated_object;

/* expected output...
|-----------------------------------------------------------|
|                      updated_object                       |
|-----------------------------------------------------------|
| {"name":"ResourceOne","type":"Storage","region":"Europe"} |
|-----------------------------------------------------------|
*/
```

Esta consulta insere uma nova chave chamada 'region' com o valor 'Europe' no documento JSON se a chave 'region' ainda não existir. Se 'region' já for uma chave do documento, a consulta retorna o documento original sem alterações.
