yeartodate – função de script e gráfico

Esta função descobre se o carimbo de data e hora de entrada cai dentro de um ano da data em que o script foi carregado pela última vez, e retorna True se cair, False se não cair.

Sintaxe:

YearToDate(timestamp[ , yearoffset [ , firstmonth [ , todaydate] ] ])

Tipo de dados de retorno: Booleano

No Qlik Sense, o valor booleano “true” é representado por -1, e o valor falso é representado por 0.

Diagrama que exibe os valores de data para os quais a função yeartodate retornará um valor True ou False. — Exemplo de diagrama da função yeartodate()

Se nenhum dos parâmetros opcionais for usado, o acumulado no ano será qualquer data que ocorrer dentro de um ano civil, a partir de 1º de janeiro até a data da última execução do script, inclusive.

Em outras palavras, a função yeartodate(), quando acionada sem parâmetros adicionais, é usada para avaliar um carimbo de data/hora e retornar um resultado booleano com base no fato de a data ter ocorrido no ano civil até a data em que o carregamento ocorreu.

No entanto, também é possível substituir a data de início do ano usando o argumento firstmonth, bem como fazer comparações com anos anteriores ou seguintes usando o argumento yearoffset.

Finalmente, em casos de conjuntos de dados históricos, a função yeartodate() fornece um parâmetro a ser definido como todaydate, que comparará o carimbo de data/hora com o ano civil até e incluindo a data fornecida no argumento todaydate.

Argumentos
Argumento	Descrição
timestamp	O carimbo de data/hora a ser avaliado, por exemplo, "10/12/2012".
yearoffset	Ao especificar um yearoffset, yeartodate retorna True para o mesmo período em outro ano. Um yearoffset negativo indica um ano anterior e um offset positivo um ano futuro. O year-to-date mais recente é alcançado ao especificar yearoffset = -1. Se omitido, o valor 0 é assumido.
firstmonth	Ao especificar um firstmonth entre 1 e 12 (1, se omitido), o início do ano pode ser movido para o primeiro dia de qualquer mês. Por exemplo, se quiser trabalhar com um ano fiscal começando em 1º de maio, especifique firstmonth = 5. Um valor de 1 indicaria um ano fiscal começando em 1º de janeiro, e um valor de 12 indicaria um ano fiscal começando em 1º de dezembro.
todaydate	Ao especificar um todaydate (carimbo de data/hora da execução do último script, se omitido), é possível mover o dia usado como o limite superior do período.

Quando usar

A função yeartodate() retorna um resultado booleano. Normalmente, esse tipo de função será usado como uma condição em uma expressão If. Isso retornaria uma agregação ou cálculo dependendo se a data avaliada ocorreu no ano até e incluindo a data da última recarga do aplicativo.

Por exemplo, a função YearToDate() pode ser usada para identificar todos os equipamentos fabricados até o momento no ano atual.

Os exemplos a seguir presumem que o tempo do último carregamento é de 18/11/2011.

Exemplos de funções
Exemplo	Resultado
yeartodate( '11/18/2010')	retorna False
yeartodate( '02/01/2011')	retorna True
yeartodate( '11/18/2011')	retorna True
yeartodate( '11/19/2011')	retorna False
yeartodate( '11/19/2011', 0, 1, '12/31/2011')	retorna True
yeartodate( '11/18/2010', -1)	retorna True
yeartodate( '11/18/2011', -1)	retorna False
yeartodate( '04/30/2011', 0, 5)	retorna False
yeartodate( '05/01/2011', 0, 5)	retorna True

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. Para obter mais informações, consulte Modificando configurações regionais para aplicativos e scripts.

As configurações regionais padrão nos aplicativos são baseadas no perfil do usuário. Essas configurações de formato regional não estão relacionadas ao idioma exibido na interface do usuário do Qlik Cloud. O Qlik Cloud será exibido no mesmo idioma do navegador que você está usando.

Se você for um criador de aplicativos, poderá definir a região padrão para os aplicativos que criar. Para obter mais informações, consulte Definir suas configurações regionais preferidas para criar aplicativos e scripts no Qlik Cloud Analytics.

Exemplo 1: Exemplo básico

Visão geral

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

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 year_to_date, que determina quais transações ocorreram no ano civil até a data do último carregamento.

No momento em que este artigo foi escrito, a data é 26 de abril de 2022.

Script de carregamento

SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        yeartodate(date) as year_to_date
        ;
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
year_to_date

Tabela de resultados
date	year_to_date
01/10/2020	0
02/28/2020	0
04/09/2020	0
04/16/2020	0
05/21/2020	0
08/14/2020	0
10/07/2020	0
12/05/2020	0
01/22/2021	0
02/03/2021	0
03/17/2021	0
04/23/2021	0
05/04/2021	0
06/30/2021	0
07/26/2021	0
12/27/2021	0
02/02/2022	-1
02/26/2022	-1
03/07/2022	-1
03/11/2022	-1

O campo year_to_date é criado na instrução de carregamento anterior usando a função yeartodate() e transmitindo o campo date como o argumento da função.

Como nenhum outro parâmetro é informado para a função, a função yeartodate() identifica inicialmente a data de carregamento e, portanto, os limites do ano civil atual (a partir de 1º de janeiro) que retornará um resultado booleano de TRUE.

Portanto, qualquer transação que ocorra entre 1º de janeiro e 26 de abril, a data de carregamento, retornará um resultado booleano de TRUE. Qualquer transação que ocorra antes do início de 2022 retornará um resultado booleano de FALSE.

Exemplo 2: yearoffset

Visão geral

Abra o editor da carga 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.
A criação de um campo, two_years_prior, que determina quais transações ocorreram dois anos antes do ano civil até o momento.

Script de carregamento

SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        yeartodate(date,-2) as two_years_prior
        ;
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_years_prior

Tabela de resultados
date	two_years_prior
01/10/2020	-1
02/28/2020	-1
04/09/2020	-1
04/16/2020	-1
05/21/2020	0
08/14/2020	0
10/07/2020	0
12/05/2020	0
01/22/2021	0
02/03/2021	0
03/17/2021	0
04/23/2021	0
05/04/2021	0
06/30/2021	0
07/26/2021	0
12/27/2021	0
02/02/2022	0
02/26/2022	0
03/07/2022	0
03/11/2022	0

Ao usar -2 como argumento yearoffset na função yeartodate(), a função altera os limites do segmento comparador do ano civil em dois anos completos. Inicialmente, o segmento do ano equivale a entre 1º de janeiro e 26 de abril de 2022. O argumento yearoffset então compensa esse segmento com dois anos antes. Os limites de data cairão então entre 1º de janeiro e 26 de abril de 2020.

Portanto, qualquer transação que ocorra entre 1º de janeiro e 26 de abril de 2020 retornará um resultado booleano de TRUE. Todas as transações que aparecerem antes ou depois desse segmento retornarão FALSE.

Exemplo 3: firstmonth

Visão geral

Abra o editor da carga 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.
A criação de um campo year_to_date, que determina quais transações ocorreram no ano civil até a data do último carregamento.

Neste exemplo, definimos o início do ano fiscal como 1º de julho.

Script de carregamento

SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        yeartodate(date,0,7) as year_to_date
        ;
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
year_to_date

Tabela de resultados
date	year_to_date
01/10/2020	0
02/28/2020	0
04/09/2020	0
04/16/2020	0
05/21/2020	0
08/14/2020	0
10/07/2020	0
12/05/2020	0
01/22/2021	0
02/03/2021	0
03/17/2021	0
04/23/2021	0
05/04/2021	0
06/30/2021	0
07/26/2021	-1
12/27/2021	-1
02/02/2022	-1
02/26/2022	-1
03/07/2022	-1
03/11/2022	-1

Nesse caso, como o argumento firstmonth de 7 é usado na função yeartodate(), ele define o primeiro dia do ano como 1º de julho e o último dia do ano como 30 de junho.

Portanto, qualquer transação que ocorra entre 1º de julho de 2021 e 26 de abril de 2022, a data de carregamento, retornará um resultado booleano de TRUE. Qualquer transação que ocorra antes de 1º de julho de 2021 retornará um resultado booleano de FALSE.

Exemplo 4: todaydate

Visão geral

Abra o editor da carga 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.
A criação de um campo year_to_date, que determina quais transações ocorreram no ano civil até a data do último carregamento.

No entanto, neste exemplo, precisamos identificar todas as transações que ocorreram no ano civil até 1º de março de 2022, inclusive.

Script de carregamento

SET DateFormat='MM/DD/YYYY';

Transactions:
    Load
        *,
        yeartodate(date, 0, 1, '03/01/2022') as year_to_date
;
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
year_to_date

Tabela de resultados
date	year_to_date
01/10/2020	0
02/28/2020	0
04/09/2020	0
04/16/2020	0
05/21/2020	0
08/14/2020	0
10/07/2020	0
12/05/2020	0
01/22/2021	0
02/03/2021	0
03/17/2021	0
04/23/2021	0
05/04/2021	0
06/30/2021	0
07/26/2021	0
12/27/2021	0
02/02/2022	-1
02/26/2022	-1
03/07/2022	0
03/11/2022	0

Nesse caso, como o argumento todaydate de 03/01/2022 é usado na função yeartodate(), ele define o limite final do segmento do ano civil comparador como 1º de março de 2022. É fundamental fornecer o parâmetro firstmonth (entre 1 e 12); caso contrário, a função retornará resultados nulos.

Portanto, qualquer transação que ocorra entre 1º de janeiro de 2022 e 1º de março de 2022, o parâmetro todaydate, retornará um resultado booleano de TRUE. Qualquer transação que ocorra antes de 1º de janeiro de 2022 ou depois de 1º de março de 2022 retornará um resultado booleano de FALSE.

Exemplo 5: Exemplo de objeto 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 determina quais transações ocorreram no ano civil até a data do último carregamento é criado como uma medida em um objeto de gráfico do aplicativo.

Script de carregamento

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.

Adicione a seguinte medida:

=yeartodate(date)

Tabela de resultados
date	=yeartodate(date)
01/10/2020	0
02/28/2020	0
04/09/2020	0
04/16/2020	0
05/21/2020	0
08/14/2020	0
10/07/2020	0
12/05/2020	0
01/22/2021	0
02/03/2021	0
03/17/2021	0
04/23/2021	0
05/04/2021	0
06/30/2021	0
07/26/2021	0
12/27/2021	0
02/02/2022	-1
02/26/2022	-1
03/07/2022	-1
03/11/2022	-1

A medida year_to_date é criada no objeto de gráfico usando a função yeartodate() e transmitindo o campo date como o argumento da função.

Qualquer transação que ocorra entre 1º de janeiro e 26 de abril, a data de carregamento, retornará um resultado booleano de TRUE. Qualquer transação que ocorra antes do início de 2022 retornará um resultado booleano de FALSE.

Exemplo 6: cenário

Visão geral

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

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 chamada Transactions.
O campo de data fornecido no formato da variável de sistema DateFormat (MM/DD/AAAA).

O usuário final gostaria de um objeto de KPI que apresentasse o total de vendas para o período equivalente em 2021 como o ano atual até o momento do último carregamento.

No momento em que este artigo foi escrito, a data é 16 de junho de 2022.

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

Faça o seguinte:

Crie um objeto de KPI.
Crie a seguinte medida de agregação para calcular o total de vendas:

=sum(if(yeartodate(date,-1),amount,0))
Defina o Formato numérico da medida como Dinheiro.

Visualização de KPI representando dados de vendas de 2021, gerada usando a função yeartodate. — Gráfico de KPI yeartodate() para 2021

A função yeartodate() retorna um valor booleano ao avaliar as datas de cada ID de transação. Como o carregamento ocorreu em 16 de junho de 2022, a função yeartodate segmenta o período do ano entre 01/01/2022 e 16/06/2022. No entanto, como um valor period_no de -1 foi usado na função, esses limites são então transferidos para o ano anterior. Portanto, para qualquer transação que ocorra entre 01/01/2021 e 16/06/2021, a função yeartodate() retorna um valor booleano de TRUE e soma o valor.

Esta página ajudou?

Se você encontrar algum problema com esta página ou seu conteúdo - um erro de digitação, uma etapa ausente ou um erro técnico - informe-nos como podemos melhorar!

Deixe seu feedback aqui