# addmonths – função de script e gráfico

Esta função retorna a data que ocorre n meses após a startdate ou, se n for negativo, a data que ocorre n meses antes da startdate.

Sintaxe:

AddMonths(startdate, n , [ , mode])

Tipo de dados de retorno: dual

A função `addmonths()` adiciona ou subtrai um número definido de meses `n`, de uma `startdate` e retorna a data resultante.

O argumento `mode` afetará os valores de `startdate` no dia 28 do mês ou depois dele. Ao definir o argumento `mode` como 1, a função `addmonths()` retorna uma data que é igual em distância relativa ao final do mês que `startdate`.

Exemplo de diagrama da função `addmonths()`

Exemplo de diagrama da função `addmonths()`

Exemplo de diagrama da função `addmonths()`addmonths() ![Diagrama de exemplo mostrando como os vários componentes da função addmonths se unem para produzir uma data de saída.](https://help.qlik.com/pt-BR/sense/May2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-addmonths-overview.png)

Por exemplo, 28 de fevereiro é o último dia do mês. Se a função `addmonths()`, com uma `mode` de 1, for usada para retornar a data dois meses depois, a função retornará a última data de abril, 30 de abril.

Exemplo de diagrama da função `addmonths()`, com `mode=1`

Exemplo de diagrama da função `addmonths()`, com `mode=1`

Exemplo de diagrama da função `addmonths()`addmonths(), com `mode=1`mode=1 ![Diagrama de exemplo mostrando como o argumento "mode" pode ser mudado para alterar a data de saída da função addmonths.](https://help.qlik.com/pt-BR/sense/May2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-addmonths-overview-n-mode-arguments.png)

Argumentos

| Argumento | Descrição |
| --- | --- |
| startdate | A data de início como um carimbo de data/hora, como “12/10/2012”. |
| n | Número de meses como um número inteiro positivo ou negativo. |
| mode | Especifica se o mês é adicionado em relação ao início ou ao final do mês. O modo padrão é 0 para adições relativas ao início do mês. Defina o modo como 1 para adições relativas ao final do mês. Quando o modo está definido como 1 e a data de entrada é 28 ou acima, a função verifica quantos dias faltam para chegar ao final do mês na data de início. O mesmo número de dias para chegar ao final do mês é definido na data retornada. |

## Quando usar

A função `addmonths()` normalmente será usada em uma expressão para encontrar uma data em um determinado número de meses antes ou depois de um período.

Por exemplo, a função `addmonths()` pode ser usada para identificar a data de término dos contratos de telefonia móvel.

Exemplos de funções

| Exemplo | Resultado |
| --- | --- |
| `addmonths ('01/29/2003' ,3)` | Retorna "04/29/2003". |
| `addmonths ('01/29/2003',3,0)` | Retorna "04/29/2003". |
| `addmonths ('01/29/2003',3,1)` | Retorna "04/28/2003". |
| `addmonths ('01/29/2003',1,0)` | Retorna "02/28/2003". |
| `addmonths ('01/29/2003',1,1)` | Retorna "02/26/2003". |
| `addmonths ('02/28/2003',1,0)` | Retorna "03/28/2003". |
| `addmonths ('02/28/2003',1,1)` | Retorna "03/31/2003". |
| `addmonths ('01/29/2003',-3)` | Retorna "10/29/2002". |

## Configurações regionais

A menos que especificado de outra forma, os exemplos neste tópico usam o seguinte formato de data: MM/DD/AAAA. O formato de data é especificado na instrução `SET DateFormat` no seu script de carregamento de dados. A formatação de data padrão pode ser diferente no seu sistema devido às suas configurações regionais e outros fatores. Você pode alterar os formatos nos exemplos abaixo para atender às suas necessidades. Ou pode alterar os formatos no seu script de carregamento para corresponder a esses exemplos.

As configurações regionais padrão nos aplicativos são baseadas nas configurações regionais do sistema do computador ou servidor em que o Qlik Sense está instalado. Se o servidor Qlik Sense que você está acessando estiver definido como Suécia, o Editor de carregamento de dados usará as configurações regionais suecas para datas, horas e moedas. Essas configurações de formato regional não estão relacionadas ao idioma exibido na interface do usuário do Qlik Sense. O Qlik Sense será exibido no mesmo idioma do navegador que você está usando.

## Exemplo 1: Sem argumentos adicionais

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/addmonths.htm)

#### Script de carregamento e resultados

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

* Um conjunto de dados contendo um conjunto de transações entre 2020 e 2022, que é carregado em uma tabela denominada `Transactions`.

* O campo de data fornecido no formato da `variável` de sistema DateFormat (MM/DD/AAAA).

* A criação de um campo, `two_months_later`, que retorna a data de dois meses após a transação ter ocorrido.

Script de carregamento

```
SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        addmonths(date,2) as two_months_later
        ;
Load
*
Inline 
[
id,date,amount
8188,'01/10/2020',37.23
8189,'02/28/2020',17.17
8190,'04/09/2020',88.27
8191,'04/16/2020',57.42
8192,'05/21/2020',53.80
8193,'08/14/2020',82.06
8194,'10/07/2020',40.39
8195,'12/05/2020',87.21
8196,'01/22/2021',95.93
8197,'02/03/2021',45.89
8198,'03/17/2021',36.23
8199,'04/23/2021',25.66
8200,'05/04/2021',82.77
8201,'06/30/2021',69.98
8202,'07/26/2021',76.11
8203,'12/27/2021',25.12
8204,'02/02/2022',46.23
8205,'02/26/2022',84.21
8206,'03/07/2022',96.24
8207,'03/11/2022',67.67
];
```

Resultados

Carregue os dados e abra uma pasta. Crie uma nova tabela e adicione esses campos como dimensões:

* `date`

* `two_months_later`

Tabela de resultados

| data | two\_months\_later |
| --- | --- |
| 01/10/2020 | 03/10/2020 |
| 02/28/2020 | 04/28/2020 |
| 04/09/2020 | 06/09/2020 |
| 04/16/2020 | 06/16/2020 |
| 05/21/2020 | 07/21/2020 |
| 08/14/2020 | 10/14/2020 |
| 10/07/2020 | 12/07/2020 |
| 12/05/2020 | 02/05/2021 |
| 01/22/2021 | 03/22/2021 |
| 02/03/2021 | 04/03/2021 |
| 03/17/2021 | 05/17/2021 |
| 04/23/2021 | 06/23/2021 |
| 05/04/2021 | 07/04/2021 |
| 06/30/2021 | 08/30/2021 |
| 07/26/2021 | 09/26/2021 |
| 12/27/2021 | 02/27/2022 |
| 02/02/2022 | 04/02/2022 |
| 02/26/2022 | 04/26/2022 |
| 03/07/2022 | 05/07/2022 |
| 03/11/2022 | 05/11/2022 |

O campo `two_months_later` é criado na instrução de carregamento anterior usando a função `addmonths()`. O primeiro argumento fornecido identifica qual data está sendo avaliada. O segundo argumento é o número de meses para adicionar a ou subtrair de `startdate`. Nesse caso, o valor de 2 é fornecido.

Diagrama da função `addmonths()`, exemplo sem argumentos adicionais

Diagrama da função `addmonths()`, exemplo sem argumentos adicionais

Diagrama da função `addmonths()`addmonths(), exemplo sem argumentos adicionais![Diagrama da função addmonths mostrando como a Transação 8193 do script de carregamento é convertida de uma data de entrada em uma data de saída resultante.](https://help.qlik.com/pt-BR/sense/May2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-addmonths-examples-no-add-arg.png)

A transação 8193 ocorreu em 14 de agosto. Portanto, a função `addmonths()` retorna 14 de outubro de 2020 para o campo `two_months_later`.

## Exemplo 2: Final relativo do mês

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/addmonths.htm)

#### Script de carregamento e resultados

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

* Um conjunto de dados contendo um conjunto de transações de fim de mês em 2022, que é carregado em uma tabela denominada `Transactions`.

* O campo de data fornecido no formato da variável de sistema `DateFormat` (MM/DD/AAAA).

* A criação de um campo, `relative_two_months_prior`, que retorna a data relativa de término do mês de dois meses antes da transação.

Script de carregamento

```
SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        addmonths(date,-2,1) as relative_two_months_prior
        ;
Load
*
Inline 
[
id,date,amount
8188,'01/28/2022',37.23
8189,'01/31/2022',57.54
8190,'02/28/2022',17.17
8191,'04/29/2022',88.27
8192,'04/30/2022',57.42
8193,'05/31/2022',53.80
8194,'08/14/2022',82.06
8195,'10/07/2022',40.39
];
```

Resultados

Carregue os dados e abra uma pasta. Crie uma nova tabela e adicione esses campos como dimensões:

* `date`

* `relative_two_months_prior`

Tabela de resultados

| data | relative\_two\_months\_prior |
| --- | --- |
| 01/28/2022 | 11/27/2021 |
| 01/31/2022 | 11/30/2021 |
| 02/28/2022 | 12/31/2021 |
| 04/29/2022 | 02/27/2022 |
| 04/30/2022 | 02/28/2022 |
| 05/31/2022 | 03/31/2022 |
| 08/14/2022 | 06/14/2022 |
| 10/07/2022 | 08/07/2022 |

O campo `relative_two_months_prior` é criado na instrução de carregamento anterior usando a função `addmonths()`. O primeiro argumento fornecido identifica qual data está sendo avaliada. O segundo argumento é o número de meses para adicionar a ou subtrair de `startdate`. Nesse caso, o valor de -2 é fornecido. O argumento final é o modo, com um valor de 1, que força a função a calcular a data relativa de fim de mês para todas as datas maiores que ou iguais a 28.

Diagrama da função `addmonths()`, exemplo com `  n=-2 `

Diagrama da função `addmonths()`, exemplo com `  n=-2 `

Diagrama da função `addmonths()`addmonths(), exemplo com `  n=-2 ` n=-2![Diagrama da função addmonths mostrando como a Transação 8191 do script de carregamento é convertida de uma data de entrada em uma data de saída resultante.](https://help.qlik.com/pt-BR/sense/May2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-addmonths-examples-rel-mth-end.png)

A transação 8191 ocorre em 29 de abril de 2022. Inicialmente, dois meses antes definiria o mês como fevereiro. Então, como o terceiro argumento da função define o modo como 1 e o valor do dia é posterior ao dia 27, a função calcula o valor relativo do final do mês. A função identifica que 29 é o penúltimo dia de abril e, portanto, retorna o penúltimo dia de fevereiro, 27.

## Exemplo 3: Exemplo de objeto de gráfico

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/addmonths.htm)

#### Script de carregamento e expressão de gráfico

Visão geral

Abra o editor de carregamento de dados e adicione o script de carregamento abaixo em uma nova guia.

O script de carregamento contém o mesmo conjunto de dados e cenário do primeiro exemplo.

No entanto, neste exemplo, o conjunto de dados inalterado é carregado no aplicativo. O cálculo que retorna a data de dois meses após a transação ter ocorrido é criado como uma medida em um objeto de gráfico.

Script de carregamento

```
SET DateFormat='MM/DD/YYYY';

Transactions:
Load
*
Inline 
[
id,date,amount
8188,'01/10/2020',37.23
8189,'02/28/2020',17.17
8190,'04/09/2020',88.27
8191,'04/16/2020',57.42
8192,'05/21/2020',53.80
8193,'08/14/2020',82.06
8194,'10/07/2020',40.39
8195,'12/05/2020',87.21
8196,'01/22/2021',95.93
8197,'02/03/2021',45.89
8198,'03/17/2021',36.23
8199,'04/23/2021',25.66
8200,'05/04/2021',82.77
8201,'06/30/2021',69.98
8202,'07/26/2021',76.11
8203,'12/27/2021',25.12
8204,'02/02/2022',46.23
8205,'02/26/2022',84.21
8206,'03/07/2022',96.24
8207,'03/11/2022',67.67
];
```

Resultados

Carregue os dados e abra uma pasta. Crie uma nova tabela e adicione esse campo como uma dimensão: `date`.

Crie a seguinte medida:

`=addmonths(date,2)`

Tabela de resultados

| data | =addmonths(date,2) |
| --- | --- |
| 01/10/2020 | 03/10/2020 |
| 02/28/2020 | 04/28/2020 |
| 04/09/2020 | 06/09/2020 |
| 04/16/2020 | 06/16/2020 |
| 05/21/2020 | 07/21/2020 |
| 08/14/2020 | 10/14/2020 |
| 10/07/2020 | 12/07/2020 |
| 12/05/2020 | 02/05/2021 |
| 01/22/2021 | 03/22/2021 |
| 02/03/2021 | 04/03/2021 |
| 03/17/2021 | 05/17/2021 |
| 04/23/2021 | 06/23/2021 |
| 05/04/2021 | 07/04/2021 |
| 06/30/2021 | 08/30/2021 |
| 07/26/2021 | 09/26/2021 |
| 12/27/2021 | 02/27/2022 |
| 02/02/2022 | 04/02/2022 |
| 02/26/2022 | 04/26/2022 |
| 03/07/2022 | 05/07/2022 |
| 03/11/2022 | 05/11/2022 |

A medida `two_months_later` é criada no objeto de gráfico usando a função `addmonths()`. O primeiro argumento fornecido identifica qual data está sendo avaliada. O segundo argumento é o número de meses para adicionar a ou subtrair de `startdate`. Nesse caso, o valor de 2 é fornecido.

Diagrama da função `addmonths()`, exemplo de objeto de gráfico

Diagrama da função `addmonths()`, exemplo de objeto de gráfico

Diagrama da função `addmonths()`addmonths(), exemplo de objeto de gráfico![Diagrama da função addmonths mostrando como a Transação 8193 do script de carregamento é convertida de uma data de entrada em uma data de saída resultante.](https://help.qlik.com/pt-BR/sense/May2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-addmonths-examples-chart-object.png)

A transação 8193 ocorreu em 14 de agosto. Portanto, a função `addmonths()` retorna 14 de outubro de 2020 para o campo `two_months_later`.

## Exemplo 4: Cenário

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/addmonths.htm)

#### Script de carregamento e expressão de gráfico

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

* Um conjunto de dados que é carregado em uma tabela denominada Mobile\_Plans.

* Informações com o ID do contrato, a data de início, a duração do contrato e a mensalidade.

O usuário final deseja um objeto de gráfico que mostre, por ID de contrato, a data de rescisão de cada contrato telefônico.

Script de carregamento

```
Mobile_Plans:
Load
*
Inline 
[
contract_id,start_date,contract_length,monthly_fee
8188,'01/13/2020',18,37.23
8189,'02/26/2020',24,17.17
8190,'03/27/2020',36,88.27
8191,'04/16/2020',24,57.42
8192,'05/21/2020',24,53.80
8193,'08/14/2020',12,82.06
8194,'10/07/2020',18,40.39
8195,'12/05/2020',12,87.21
8196,'01/22/2021',12,95.93
8197,'02/03/2021',18,45.89
8198,'03/17/2021',24,36.23
8199,'04/23/2021',24,25.66
8200,'05/04/2021',12,82.77
8201,'06/30/2021',12,69.98
8202,'07/26/2021',12,76.11
8203,'12/27/2021',36,25.12
8204,'06/06/2022',24,46.23
8205,'07/18/2022',12,84.21
8206,'11/14/2022',12,96.24
8207,'12/12/2022',18,67.67
];
```

Resultados

Carregue os dados e abra uma pasta. Crie uma nova tabela e adicione esses campos como dimensões:

* contract\_id

* start\_date

* contract\_length

Crie a medida a seguir para calcular a data de término de cada contrato:

=addmonths(start\_date,contract\_length, 0)

Tabela de resultados

| contract\_id | start\_date | contract\_length | =addmonths(start\_date,contract\_length,0) |
| --- | --- | --- | --- |
| 8188 | 01/13/2020 | 18 | 07/13/2021 |
| 8189 | 02/26/2020 | 24 | 02/26/2022 |
| 8190 | 03/27/2020 | 36 | 03/27/2023 |
| 8191 | 04/16/2020 | 24 | 04/16/2022 |
| 8192 | 05/21/2020 | 24 | 05/21/2022 |
| 8193 | 08/14/2020 | 12 | 08/14/2021 |
| 8194 | 10/07/2020 | 18 | 04/07/2022 |
| 8195 | 12/05/2020 | 12 | 12/05/2021 |
| 8196 | 01/22/2021 | 12 | 01/22/2022 |
| 8197 | 02/03/2021 | 18 | 08/03/2022 |
| 8198 | 03/17/2021 | 24 | 03/17/2023 |
| 8199 | 04/23/2021 | 24 | 04/23/2023 |
| 8200 | 05/04/2021 | 12 | 05/04/2022 |
| 8201 | 06/30/2021 | 12 | 06/30/2022 |
| 8202 | 07/26/2021 | 12 | 07/26/2022 |
| 8203 | 12/27/2021 | 36 | 12/27/2024 |
| 8204 | 06/06/2022 | 24 | 06/06/2024 |
| 8205 | 07/18/2022 | 12 | 07/18/2023 |
| 8206 | 11/14/2022 | 12 | 11/14/2023 |
| 8207 | 12/12/2022 | 18 | 06/12/2024 |