Suporte de duração no Power Query M

Uma duração no Power Query M representa a diferença entre dois pontos no tempo, expressos em dias, horas, minutos e segundos. Se você estiver calculando o tempo entre interações do cliente, filtrando registros com base no tempo decorrido ou criando lógica dinâmica baseada em tempo, as durações são essenciais para criar modelos de dados robustos e inteligentes.

Este artigo explora a estrutura, a criação e a manipulação de durações no Power Query M. Ele inclui exemplos práticos e dicas de compartilhamento para ajudá-lo a usar durações efetivamente em seus próprios fluxos de trabalho de dados.

Criar uma duração

Uma duração é definida pela #duration(<days>, <hours>, <minutes>, <seconds>) função. Por exemplo, #duration(2, 3, 0, 0) representa uma duração de 2 dias e 3 horas. O Power Query M fornece várias maneiras de criar uma duração, dependendo do contexto e do nível de precisão necessários.

Use a função #duration.

A maneira mais direta de criar uma duração é com a #duration(<days>, <hours>, <minutes>, <seconds>) sintaxe. Cada argumento deve ser um número e o resultado é um valor de duração.

#duration(2, 5, 30, 0) // 2 days, 5 hours, 30 minutes

Essa função também dá suporte a segundos fracionários:

#duration(0, 0, 0, 1.75) // 1.75 seconds

Criar durações a partir de valores de data e hora

As durações também podem ser criadas subtraindo um valor de data e hora de outro. O resultado é uma duração que representa o período de tempo entre os dois.

let
    Source =
    {
        #date(2025, 7, 24) - #date(2025, 7, 23),
        // Result: #duration(1, 0, 0, 0)
        #time(12, 0, 0) - #time(11, 30, 30),
        // Result: #duration(0, 0, 29, 30)
        #datetime(2025, 7, 24, 12, 0, 0) - #datetime(2025, 7, 23, 12, 0, 0),
        // Result: #duration(1, 0, 0, 0)
        #datetimezone(2025, 7, 24, 12, 0, 0, 7, 0) - #datetimezone(2025, 7, 23, 10, 30, 0, 4, 0),
        // Result: #duration(0, 22, 30, 0)
        #datetime(2025, 7, 24, 12, 0, 0) - DateTime.From(#date(2025, 7, 23))
        // Result: #duration(1, 12, 0, 0)
    }
in
    Source

Observação

Subtrair um tipo de data e hora de um tipo de data e hora diferente (por exemplo, subtrair um date valor de um datetime valor) resulta em um erro. Se você precisar usar diferentes tipos de data e hora para determinar uma duração, use as Date.Fromfunções , DateTime.Fromou DateTimeZone.FromTime.From funções para alterar explicitamente um dos tipos de data e hora.

Converter de valores compatíveis

A Duration.From função pode converter valores compatíveis em durações. Para obter mais informações, vá para Duration.From(valor).

Trabalhar com durações

Depois que uma duração é criada no Power Query M, ela pode ser manipulada usando várias operações e funções. Esses recursos tornam as durações altamente versáteis para lógica e cálculos baseados em tempo.

Operações aritméticas

As durações dão suporte a operações aritméticas padrão:

  • Adição e subtração: adicione ou subtraia durações entre si ou de valores de data e hora.

    let
    Source = {
        #duration(1, 2, 0, 0) + #duration(0, 3, 30, 0),
        // Result: #duration(1, 5, 30, 0)
        #duration(1, 2, 0, 0) - #duration(0, 3, 30, 0),
        // Result: #duration(0, 22, 30, 0)
        #datetime(2025, 7, 24, 12, 0, 0) + #duration(0, 2, 0, 0),
        // Result: #datetime(2025, 7, 24, 14, 0, 0)
        #datetime(2025, 7, 24, 12, 0, 0) - #duration(0, 2, 0, 0),
        // Result: #datetime(2025, 7, 24, 10, 0, 0)
        #time(12, 0, 0) - #duration(0, 3, 30, 0)
        // Result: #time(8, 30, 0)
    }
in
    Source

  • Negação: uma duração pode ser negada para reverter sua direção.

    let
    Source = {
        #datetime(2025, 7, 24, 12, 0, 0) + -#duration(0, 2, 0, 0),
        // Result (subtracts two hours): #datetime(2025, 7, 24, 10, 0, 0)
        #datetime(2025, 7, 23, 12, 0, 0) - #datetime(2025, 7, 24, 12, 0, 0)
        // Result: -#duration(1, 0, 0, 0)
    }
in
    Source

Multiplicação e divisão

As durações podem ser multiplicadas ou divididas por valores numéricos:

let
    Source = {
        #duration(0, 2, 0, 0) * 2,
        // Result (4 hours): #duration(0, 4, 0, 0)
        #duration(1, 0, 0, 0) / 2
        // Result (12 hours): #duration(0, 12, 0, 0)
    }
in
    Source

Esse cálculo é útil para dimensionar durações ou intervalos de tempo médios.

Comparações

As durações podem ser comparadas usando operadores de comparação padrão:

let
    Source = #duration(1, 0, 0, 0) > #duration(0, 23, 59, 59)
        // Result: true
in
    Source

Esse cálculo permite que as durações sejam usadas na lógica condicional, como filtrar linhas com base no tempo decorrido.

Compatibilidade de tipo

As durações são compatíveis com valores de data e hora em expressões aritméticas, mas não intercambiáveis com elas. Por exemplo, subtrair dois valores de data e hora gera um duration, mas a adição de dois valores de data e hora é inválida.

let
    Source =
    {
        #datetime(2025, 7, 24, 12, 0, 0) - #datetime(2025, 7, 23, 12, 0, 0),
        // Result: #duration(1, 0, 0, 0)
        #datetime(2025, 7, 24, 12, 0, 0) + #datetime(2025, 7, 23, 12, 0, 0)
        // Result: Error
    }
in
    Source

Funções de duração em M

O Power Query M inclui um conjunto de funções internas para trabalhar com durações. Essas funções permitem conversão, extração de componentes e agregação de valores de duração, tornando-as ferramentas essenciais para transformações baseadas em tempo.

Duration.From(valor)

A Duration.From função converte um valor compatível em uma duração. Os valores compatíveis consistem em um número interpretado como uma fração de um dia ou uma representação textual de uma duração. Acesse para obter Duration.FromText informações sobre os formatos de representação textual.

let
    Source =
    {
        Duration.From(1.5),
        // Result: 1.5 days = #duration(1, 12, 0, 0)
        Duration.From("2.05:55:20.242")
        // Result: #duration(2, 5, 55, 20.242)
    }
in
    Source

Acessadores de componentes

Essas funções extraem partes específicas de uma duração:

  • Duration.Days(<duration>)

    Retorna o número de dias inteiros na duração.

  • Duration.Hours(<duration>)

    Retorna o número de horas além dos dias inteiros.

  • Duration.Minutes(<duration>)

    Retorna o número de minutos além das horas inteiras.

  • Duration.Seconds(<duration>)

    Retorna o número de segundos além dos minutos inteiros.

let
    Source = #duration(2, 5, 30, 45),
    TextFormat = Text.Format(
        "Duration = #{0} days, #{1} hours, #{2} minutes, and #{3} seconds.",
        {
            Duration.Days(Source),
            Duration.Hours(Source),
            Duration.Minutes(Source),
            Duration.Seconds(Source)
        }
    )
    // Results: "Duration = 2 days, 5 hours, 30 minutes, and 45 seconds."
in
    TextFormat

Funções de valor total

Essas funções retornam o valor total de uma duração em uma única unidade, incluindo partes fracionárias:

  • Duration.TotalDays(<duration>)
  • Duration.TotalHours(<duration>)
  • Duration.TotalMinutes(<duration>)
  • Duration.TotalSeconds(<duration>)
let
    Source =
    {
        Duration.TotalDays(#duration(1, 12, 0, 0)),    // 1.5 days
        Duration.TotalHours(#duration(1, 12, 0, 0)),   // 36 hours
        Duration.TotalMinutes(#duration(1, 12, 0, 0)), // 2160 minutes
        Duration.TotalSeconds(#duration(1, 12, 0, 0))  // 129600 seconds
    }
in
    Source

Normalização de duração

Na maioria dos casos, a duração é composta de dias, horas (máximo de 23 horas), minutos (máximo de 59 minutos) e segundos (máximo de 59,9999999 segundos). No entanto, em alguns casos, você pode exceder os valores máximos nos parâmetros de duração. Nesse caso, o Power Query M normaliza automaticamente esses valores:

  • Segundos transbordam em minutos
  • Minutos transbordam em horas
  • Horas transbordam em dias

Por exemplo, suponha que você tenha uma coluna que forneça a data e a hora de início de um processo em execução. Além disso, você tem uma coluna que mostra quanto tempo levou para o processo ser concluído, em segundos. Você deseja criar uma terceira coluna que mostre a data e a hora em que o processo é concluído.

let
    Source = #table(type table[StartTime = datetime, Seconds = Int64.Type],
    {
        {#datetime(2025, 7, 25, 8, 0, 0), 5400},
        {#datetime(2025, 7, 25, 13, 15, 0), 86400},
        {#datetime(2025, 7, 24, 22, 30, 0), 172800}
    }),
    AddSeconds = Table.AddColumn(
        Source,
        "EndTime",
        each [StartTime] + #duration(0, 0, 0, [Seconds]),
        type datetime
    )
in
    AddSeconds

A tabela a seguir é o resultado desses cálculos.

Captura de tela da tabela que contém a coluna de data e hora de término derivada da hora de início e da duração em segundos.

Portanto, mesmo que você tenha tido apenas o número de segundos em que um processo ocorreu, o Power Query M acumula esse valor de duração em minutos, horas e dias em que o resultado é avaliado.

Representar semanas, meses e anos

Como as durações são baseadas em unidades fixas (dias, horas, minutos, segundos), não há nenhum conceito nativo de semanas, meses ou anos, que variam de comprimento. Um duration tipo no Power Query M é uma estrutura fixa que não conta para regras de calendário. Para períodos de duração precisos ao longo de meses ou anos, subtraia uma data e hora de outra em vez de usar durações fixas. Essa abordagem lida corretamente com anos bissextos, intervalos de meses variados e DST (horário de verão). No entanto, observe também que algum comportamento de data e hora pode ser diferente dependendo se a consulta é executada localmente (no Power Query Desktop) ou online (no Power Query Online). Para obter detalhes, vá para as variantes Local, Fixa e UTC da data e hora atuais. Em geral, evite depender de durações fixas para cálculos de longo prazo.

  • Last updated on