# 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/May2026/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/May2026/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 onde 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 Qlik Sense interface do usuário. 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/May2026/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/May2026/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/May2026/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/May2026/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/May2026/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 |