# yearname - Função de script e de gráfico

Esta função retorna um ano com quatro dígitos como valor de exibição com um valor numérico subjacente que corresponde a um carimbo de data/hora com o primeiro milissegundo do primeiro dia do ano que contém date.

Diagrama do intervalo de tempo da função `yearname()`.

Diagrama do intervalo de tempo da função `yearname()`.

Diagrama do intervalo de tempo da função `yearname()`yearname(). ![Diagrama que mostra o intervalo de tempo no qual a função yearname retornará um resultado.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-diagram1.png)

A função `yearname()` é diferente da função `year()`, pois permite deslocar a data que você deseja avaliar e permite definir o primeiro mês do ano.

Se o primeiro mês do ano não for janeiro, a função retornará os dois anos de quatro dígitos durante o período de doze meses que contêm a data. Por exemplo, se o início do ano for abril e a data avaliada for 30/06/2020, o resultado retornado será `2020-2021`.

Diagrama da função `yearname()` com abril definido como o primeiro mês do ano.

Diagrama da função `yearname()` com abril definido como o primeiro mês do ano.

Diagrama da função `yearname()`yearname() com abril definido como o primeiro mês do ano. ![Diagrama que mostra que a função yearname pode identificar datas dentro de um período de doze meses e que seu retorno pode depender de qual mês está definido como o primeiro do ano.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-diagram2.png)

Sintaxe:

YearName(date[, period\_no[, first\_month\_of\_year]] )

Tipo de dados de retorno: dual

| Argumento | Descrição |
| --- | --- |
| date | A data ou o carimbo de data/hora a ser avaliado. |
| period\_no | period\_no é um inteiro, em que o valor 0 indica o ano que contém a date. Valores negativos em period\_no indicam anos precedentes e valores positivos indicam anos sucessivos. |
| first\_month\_of\_year | Se desejar trabalhar com anos (fiscais) que não comecem em janeiro, indique um valor entre 2 e 12 em first\_month\_of\_year. O valor de exibição serão caracteres que mostram dois anos. |

Você pode usar os seguintes valores para definir o primeiro mês do ano no argumento `first_month_of_year`:

Valores first\_month\_of\_year

| Mês | Valor |
| --- | --- |
| Fevereiro | 2 |
| Março | 3 |
| Abril | 4 |
| Maio | 5 |
| Junho | 6 |
| Julho | 7 |
| Agosto | 8 |
| Setembro | 9 |
| Outubro | 10 |
| Novembro | 11 |
| Dezembro | 12 |

Quando usar

A função `yearname()` é útil para comparar agregações por ano. Por exemplo, se você quiser ver o total de vendas de produtos por ano.

Essas dimensões podem ser criadas no script de carregamento usando a função para criar um campo em uma tabela de Calendário mestre. Elas também podem ser criadas em um gráfico como dimensões calculadas

## 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.

Exemplos de funções

| Exemplo | Resultado |
| --- | --- |
| `yearname('10/19/2001')` | Retorna "2001". |
| `yearname('10/19/2001',-1)` | Retorna "2000". |
| `yearname('10/19/2001',0,4)` | Retorna "2001-2002". |

Tópicos relacionados

| Tópico | Descrição |
| --- | --- |
| [year - Função de script e de gráfico](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/year.htm) | Essa função retorna um número inteiro que representa o ano em que a expressão é interpretada como uma data, de acordo com a interpretação de número padrão. |

## Exemplo 1: Sem argumentos adicionais

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/yearname.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 é carregado em uma tabela chamada "`Transactions`".

* A `variável` de sistema DateFormat que é definida como "`MM/DD/YYYY`".

* Um carregamento anterior que usa o `yearname()` e que está definido como o campo `year_name`.

Script de carregamento

```
SET DateFormat='MM/DD/YYYY'; 
						
Transactions: 
    Load 
      *, 
      yearname(date) as year_name 
      ; 
Load 
* 
Inline  
[ 
id,date,amount 
8188,'01/13/2020',37.23 
8189,'02/26/2020',17.17 
8190,'03/27/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,'06/06/2022',46.23 
8205,'07/18/2022',84.21 
8206,'11/14/2022',96.24 
8207,'12/12/2022',67.67 
]; 
```

Resultados

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

* `date`
* `year_name`

Tabela de resultados

| data | year\_name |
| --- | --- |
| 01/13/2020 | 2020 |
| 02/26/2020 | 2020 |
| 03/27/2020 | 2020 |
| 04/16/2020 | 2020 |
| 05/21/2020 | 2020 |
| 08/14/2020 | 2020 |
| 10/07/2020 | 2020 |
| 12/05/2020 | 2020 |
| 01/22/2021 | 2021 |
| 02/03/2021 | 2021 |
| 03/17/2021 | 2021 |
| 04/23/2021 | 2021 |
| 05/04/2021 | 2021 |
| 06/30/2021 | 2021 |
| 07/26/2021 | 2021 |
| 12/27/2021 | 2021 |
| 06/06/2022 | 2022 |
| 07/18/2022 | 2022 |
| 11/14/2022 | 2022 |
| 12/12/2022 | 2022 |

O campo "`year_name`" é criado na instrução de carregamento anterior usando a função `yearname()` e transmitindo o campo de data como o argumento da função.

A função `yearname()` identifica em qual ano o valor de data cai e o retorna como um valor de ano de quatro dígitos.

Diagrama da função `yearname()` que mostra 2021 como o valor do ano.

Diagrama da função `yearname()` que mostra 2021 como o valor do ano.

Diagrama da função `yearname()`yearname() que mostra 2021 como o valor do ano.![O diagrama que mostra a função yearname() retorna 2021 para a data de 17 de março de 2021.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-example1-diagram.png)

## Exemplo 2 – period\_no

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/yearname.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 é carregado em uma tabela chamada "Transactions".

* A variável de sistema DateFormat , que está definida como "`MM/DD/YYYY`".

* Um carregamento anterior que usa `yearname()` e que está definido como o campo `year_name`.

Script de carregamento

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

Transactions: 
    Load 
      *, 
      yearname(date,-1) as prior_year_name 
      ; 
Load 
* 
Inline  
[ 
id,date,amount 
8188,'01/13/2020',37.23 
8189,'02/26/2020',17.17 
8190,'03/27/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,'06/06/2022',46.23 
8205,'07/18/2022',84.21 
8206,'11/14/2022',96.24 
8207,'12/12/2022',67.67 
];  
```

Resultados

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

* `date`
* `prior_year_name`

Tabela de resultados

| data | prior\_year\_name |
| --- | --- |
| 01/13/2020 | 2019 |
| 02/26/2020 | 2019 |
| 03/27/2020 | 2019 |
| 04/16/2020 | 2019 |
| 05/21/2020 | 2019 |
| 08/14/2020 | 2019 |
| 10/07/2020 | 2019 |
| 12/05/2020 | 2019 |
| 01/22/2021 | 2020 |
| 02/03/2021 | 2020 |
| 03/17/2021 | 2020 |
| 04/23/2021 | 2020 |
| 05/04/2021 | 2020 |
| 06/30/2021 | 2020 |
| 07/26/2021 | 2020 |
| 12/27/2021 | 2020 |
| 06/06/2022 | 2021 |
| 07/18/2022 | 2021 |
| 11/14/2022 | 2021 |
| 12/12/2022 | 2021 |

Como um `period_no` de `-1` foi usado como o argumento de deslocamento na função `yearname()`, a função primeiro identifica o ano em que as transações ocorrem. Em seguida, a função muda para um ano antes e retorna o ano resultante.

Diagrama da função `yearname()` com `period_no` definido como `-1`.

Diagrama da função `yearname()` com `period_no` definido como `-1`.

Diagrama da função `yearname()`yearname() com `period_no`period\_no definido como `-1`-1.![Diagrama que mostra como um period_no como negativo altera os intervalos de tempo que a função yearname() identifica.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-example2-diagram.png)

## Exemplo 3: first\_month\_of\_year

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/yearname.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:

* O mesmo conjunto de dados do primeiro exemplo.

* A variável de sistema `DateFormat` que está definida como "`MM/DD/YYYY`".

* Um carregamento anterior que usa `yearname()` e que está definido como o campo `year_name`.

Script de carregamento

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

Transactions: 
    Load 
      *, 
      yearname(date,0,4) as year_name 
      ; 
Load 
* 
Inline  
[ 
id,date,amount 
8188,'01/13/2020',37.23 
8189,'02/26/2020',17.17 
8190,'03/27/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,'06/06/2022',46.23 
8205,'07/18/2022',84.21 
8206,'11/14/2022',96.24 
8207,'12/12/2022',67.67 
];
```

Resultados

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

* `id`
* `date`
* `year_name`

Tabela de resultados

| data | year\_name |
| --- | --- |
| 01/13/2020 | 2019-2020 |
| 02/26/2020 | 2019-2020 |
| 03/27/2020 | 2019-2020 |
| 04/16/2020 | 2020-2021 |
| 05/21/2020 | 2020-2021 |
| 08/14/2020 | 2020-2021 |
| 10/07/2020 | 2020-2021 |
| 12/05/2020 | 2020-2021 |
| 01/22/2021 | 2020-2021 |
| 02/03/2021 | 2020-2021 |
| 03/17/2021 | 2020-2021 |
| 04/23/2021 | 2021-2022 |
| 05/04/2021 | 2021-2022 |
| 06/30/2021 | 2021-2022 |
| 07/26/2021 | 2021-2022 |
| 12/27/2021 | 2021-2022 |
| 06/06/2022 | 2022-2023 |
| 07/18/2022 | 2022-2023 |
| 11/14/2022 | 2022-2023 |
| 12/12/2022 | 2022-2023 |

Como o argumento `first_month_of_year` de `4` é usado na função `yearname()`, o começo do ano passa de 1º de janeiro para 1º de abril. Portanto, cada período de doze meses cruza dois anos civis, e a função `yearname()` retorna os dois anos de quatro dígitos para as datas avaliadas.

A transação 8198 ocorre em 17 de março de 2021. A função `yearname()` define o início do ano em 1º de abril e o final em 30 de março. Portanto, a transação 8198 ocorreu no período do ano de 1º de abril de 2020 e 30 de março de 2021. Como resultado, a função `yearname()` retorna o valor 2020-2021.

Diagrama da função `yearname()` com março definido como o primeiro mês do ano.

Diagrama da função `yearname()` com março definido como o primeiro mês do ano.

Diagrama da função `yearname()`yearname() com março definido como o primeiro mês do ano.![Diagrama mostrando o intervalo de tempo identificado pela função yearname() quando o primeiro mês do ano é definido como março.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-example3-diagram.png)

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

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/yearname.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:

* O mesmo conjunto de dados do primeiro exemplo.

* A variável de sistema `DateFormat` que está definida como "`MM/DD/YYYY`".

No entanto, o campo que retorna o ano em que a transação ocorreu é 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/13/2020',37.23 
8189,'02/26/2020',17.17 
8190,'03/27/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,'06/06/2022',46.23 
8205,'07/18/2022',84.21 
8206,'11/14/2022',96.24 
8207,'12/12/2022',67.67 
];	
```

Resultados

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

`date`

Para calcular o campo "`year_name`", crie esta medida:

`=yearname(date)`

Tabela de resultados

| data | =yearname(date) |
| --- | --- |
| 01/13/2020 | 2020 |
| 02/26/2020 | 2020 |
| 03/27/2020 | 2020 |
| 04/16/2020 | 2020 |
| 05/21/2020 | 2020 |
| 08/14/2020 | 2020 |
| 10/07/2020 | 2020 |
| 12/05/2020 | 2020 |
| 01/22/2021 | 2021 |
| 02/03/2021 | 2021 |
| 03/17/2021 | 2021 |
| 04/23/2021 | 2021 |
| 05/04/2021 | 2021 |
| 06/30/2021 | 2021 |
| 07/26/2021 | 2021 |
| 12/27/2021 | 2021 |
| 06/06/2022 | 2022 |
| 07/18/2022 | 2022 |
| 11/14/2022 | 2022 |
| 12/12/2022 | 2022 |

A medida "`year_name`" é criada no objeto de gráfico usando a função `yearname()` e transmitindo o campo de data como argumento da função.

A função `yearname()` identifica em qual ano o valor de data cai e o retorna como um valor de ano de quatro dígitos.

Diagrama da função `yearname()` com 2021 como o valor do ano.

Diagrama da função `yearname()` com 2021 como o valor do ano.

Diagrama da função `yearname()`yearname() com 2021 como o valor do ano.![Diagrama que mostra a função yearname() e retorna 2021 como o valor do ano.](https://help.qlik.com/pt-BR/sense/November2025/Subsystems/Hub/Content/Resources/Images/scripting-functions-yearname-example4-diagram.png)

## Exemplo 5: Cenário

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/DateAndTimeFunctions/yearname.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:

* O mesmo conjunto de dados do primeiro exemplo.

* A variável de sistema DateFormat que está definida como "MM/DD/YYYY".

O usuário final gostaria de um gráfico que apresentasse o total de vendas por trimestre para as transações. Use a função yearname() como uma dimensão calculada para criar esse gráfico quando a dimensão yearname() não estiver disponível no modelo de dados.

Script de carregamento

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

Transactions: 
Load 
* 
Inline  
[ 
id,date,amount 
8188,'01/13/2020',37.23 
8189,'02/26/2020',17.17 
8190,'03/27/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,'06/06/2022',46.23 
8205,'07/18/2022',84.21 
8206,'11/14/2022',96.24 
8207,'12/12/2022',67.67 
];
```

Resultados

Carregue os dados e abra uma pasta. Crie uma nova tabela.

Para comparar agregações por ano, crie esta dimensão calculada:

=yearname(date)

Crie esta medida:

=sum(amount)

Defina o Formato numérico da medida como Dinheiro.

Tabela de resultados

| yearname(date) | =sum(amount) |
| --- | --- |
| 2020 | $463.55 |
| 2021 | $457.69 |
| 2022 | $294.35 |