Funções para trabalhar com datas e horas

A maioria das funções desta seção aceita um argumento opcional de fuso horário, por exemplo, Europe/Amsterdam. Nesse caso, é usado o fuso horário especificado em vez do fuso local (padrão).

Exemplo

SELECT
    toDateTime('2016-06-15 23:00:00') AS time,
    toDate(time) AS date_local,
    toDate(time, 'Asia/Yekaterinburg') AS date_yekat,
    toString(time, 'US/Samoa') AS time_samoa

┌────────────────time─┬─date_local─┬─date_yekat─┬─time_samoa──────────┐
│ 2016-06-15 23:00:00 │ 2016-06-15 │ 2016-06-16 │ 2016-06-15 09:00:00 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘

Introduzido na versão: v22.11.0

Retorna a data e a hora atuais no momento da análise da consulta. A função é uma expressão constante.

Esta função retorna o mesmo resultado que now('UTC'). Ela foi adicionada apenas para oferecer suporte ao MySQL. now é a forma de uso preferida.

Sintaxe

UTCTimestamp()

Aliases: UTC_timestamp

Argumentos

• Nenhum.

Valor retornado

Retorna a data e a hora atuais no momento da análise da consulta. DateTime

Exemplos

Obter o timestamp UTC atual

SELECT UTCTimestamp()

┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘

Introduzido em: v23.9.0

Converte um número que contém o ano, o mês e o dia em um Date. Esta função é o inverso da função toYYYYMMDD(). A saída é indefinida se a entrada não representar um valor de Date válido.

Sintaxe

YYYYMMDDToDate(YYYYMMDD)

Argumentos

• YYYYMMDD — Número contendo o ano, o mês e o dia. (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um valor Date com base nos argumentos fornecidos Date

Exemplos

Exemplo

SELECT YYYYMMDDToDate(20230911);

┌─YYYYMMDDToDate(20230911)─┐
│               2023-09-11 │
└──────────────────────────┘

Introduzido em: v23.9.0

Converte um número contendo o ano, o mês e o dia em um Date32. Esta função é o inverso da função toYYYYMMDD(). A saída é indefinida se a entrada não representar um valor Date32 válido.

Sintaxe

YYYYMMDDToDate32(YYYYMMDD)

Argumentos

• YYYYMMDD — Número que contém o ano, mês e dia. (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um valor Date32 a partir dos argumentos fornecidos Date32

Exemplos

Exemplo

SELECT YYYYMMDDToDate32(20000507);

┌─YYYYMMDDToDate32(20000507)─┐
│                 2000-05-07 │
└────────────────────────────┘

Introduzido em: v23.9.0

Converte um número que contém o ano, o mês, o dia, a hora, o minuto e o segundo em DateTime. Esta função é o oposto da função toYYYYMMDDhhmmss(). A saída é indefinida se a entrada não codificar um valor DateTime válido.

Sintaxe

YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])

Argumentos

• YYYYMMDDhhmmss — Número que contém o ano, mês, dia, hora, minuto e segundo. (U)Int* ou Float* ou Decimal
• timezone — Nome do fuso horário. String

Valor retornado

Retorna um valor DateTime a partir dos argumentos fornecidos DateTime

Exemplos

Exemplo

SELECT YYYYMMDDhhmmssToDateTime(20230911131415);

┌─YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│                      2023-09-11 13:14:15 │
└──────────────────────────────────────────┘

Introduzido em: v23.9.0

Converte um número com ano, mês, dia, hora, minuto e segundo em um DateTime64. Esta função é o oposto da função toYYYYMMDDhhmmss(). A saída é indefinida se a entrada não codificar um valor DateTime64 válido.

Sintaxe

YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])

Argumentos

• YYYYMMDDhhmmss — Número que contém o ano, mês, dia, hora, minuto e segundo. (U)Int* ou Float* ou Decimal
• precision — Precisão da parte fracionária (0-9). UInt8
• timezone — Nome do fuso horário. String

Valor retornado

Retorna um valor DateTime64 com base nos argumentos fornecidos DateTime64

Exemplos

Exemplo

SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');

┌─YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul')─┐
│                                        2023-09-11 13:14:15.000 │
└────────────────────────────────────────────────────────────────┘

Introduzido em: v23.9.0

Adiciona o intervalo de tempo à data, à data e hora ou à data ou data e hora codificada como string fornecida. Se a adição resultar em um valor fora dos limites do tipo de dado, o resultado será indefinido.

Sintaxe

addDate(datetime, interval)

Argumentos

• datetime — A data ou data e hora à qual interval é adicionado. Date ou Date32 ou DateTime ou DateTime64 ou String
• interval — Intervalo a ser adicionado. Interval

Valor retornado

Retorna a data ou data e hora obtida ao adicionar interval a datetime. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar intervalo a uma data

SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─addDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2021-01-01 │
└──────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de dias a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addDays(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual adicionar o número especificado de dias. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de dias a serem adicionados. (U)Int* ou Float*

Valor retornado

Retorna datetime com num dias adicionados. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar dias a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addDays(date, 5) AS add_days_with_date,
    addDays(date_time, 5) AS add_days_with_date_time,
    addDays(date_time_string, 5) AS add_days_with_date_time_string

┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│         2024-01-06 │     2024-01-06 00:00:00 │        2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘

Usando uma sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalDay(10))─┐
│                                          1998-06-26 │
└─────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de horas a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addHours(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de horas. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de horas a serem adicionadas. (U)Int* ou Float*

Valor retornado

Retorna datetime acrescido de num horas DateTime ou DateTime64(3)

Exemplos

Adicionar horas a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addHours(date, 12) AS add_hours_with_date,
    addHours(date_time, 12) AS add_hours_with_date_time,
    addHours(date_time_string, 12) AS add_hours_with_date_time_string

┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │      2024-01-01 12:00:00 │         2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalHour(10))─┐
│                                  1998-06-16 10:00:00 │
└──────────────────────────────────────────────────────┘

Introduzido em: v22.11.0

Adiciona um intervalo a outro intervalo ou a uma tupla de intervalos.

Sintaxe

addInterval(interval_1, interval_2)

Argumentos

• interval_1 — Primeiro intervalo ou tupla de intervalos. Interval ou Tuple(Interval)
• interval_2 — Segundo intervalo a ser somado. Interval

Valor retornado

Retorna uma tupla de intervalos Tuple(Interval)

Exemplos

Somar intervalos

SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)

┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1)                                             │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1)                                                                │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3)                                             │
└─────────────────────────────────────────────────┘

Introduzido em: v22.6.0

Adiciona um número especificado de microssegundos a uma data e hora ou a uma data e hora codificada como string.

Sintaxe

addMicroseconds(datetime, num)

Argumentos

• datetime — Data e hora à qual adicionar o número especificado de microssegundos. DateTime ou DateTime64 ou String
• num — Número de microssegundos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna date_time mais num microssegundos DateTime64

Exemplos

Adicionar microssegundos a diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
    addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string

┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│      2024-01-01 00:00:01.000000 │             2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─plus(CAST('1998-06-16', 'DateTime'), toIntervalMicrosecond(10))─┐
│                                      1998-06-16 00:00:00.000010 │
└─────────────────────────────────────────────────────────────────┘

Introduzido em: v22.6.0

Adiciona um número especificado de milissegundos a uma data e hora ou a uma data e hora codificada como string.

Sintaxe

addMilliseconds(datetime, num)

Argumentos

• datetime — Data e hora à qual será adicionado o número especificado de milissegundos. DateTime ou DateTime64 ou String
• num — Número de milissegundos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime mais num milissegundos DateTime64

Exemplos

Adicionar milissegundos a diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
    addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string

┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│         2024-01-01 00:00:01.000 │                2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘

Uso da sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─plus(CAST('1998-06-16', 'DateTime'), toIntervalMillisecond(10))─┐
│                                         1998-06-16 00:00:00.010 │
└─────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de minutos a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addMinutes(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de minutos. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de minutos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime acrescido de num minutos DateTime ou DateTime64(3)

Exemplos

Adicionar minutos a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMinutes(date, 20) AS add_minutes_with_date,
    addMinutes(date_time, 20) AS add_minutes_with_date_time,
    addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string

┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│   2024-01-01 00:20:00 │        2024-01-01 00:20:00 │           2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalMinute(10))─┐
│                                    1998-06-16 00:10:00 │
└────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de meses a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addMonths(datetime, num)

Argumentos

• datetime — Data ou data/hora à qual adicionar o número especificado de meses. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de meses a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime acrescido de num meses. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar meses a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMonths(date, 6) AS add_months_with_date,
    addMonths(date_time, 6) AS add_months_with_date_time,
    addMonths(date_time_string, 6) AS add_months_with_date_time_string

┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│           2024-07-01 │       2024-07-01 00:00:00 │          2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalMonth(10))─┐
│                                            1999-04-16 │
└───────────────────────────────────────────────────────┘

Introduzido em: v22.6.0

Adiciona um número especificado de nanossegundos a uma data e hora ou a uma data e hora codificada como string.

Sintaxe

addNanoseconds(datetime, num)

Argumentos

• datetime — Data e hora à qual será adicionado o número especificado de nanossegundos. DateTime ou DateTime64 ou String
• num — Número de nanossegundos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime mais num nanossegundos. DateTime64

Exemplos

Adicionar nanossegundos a diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
    addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string

┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│  2024-01-01 00:00:00.000001000 │         2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)

┌─plus(CAST('1998-06-16', 'DateTime'), toIntervalNanosecond(1000))─┐
│                                    1998-06-16 00:00:00.000001000 │
└──────────────────────────────────────────────────────────────────┘

Introduzido em: v20.1.0

Adiciona um número especificado de trimestres a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addQuarters(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de trimestres. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de trimestres a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime mais num trimestres Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar trimestres a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addQuarters(date, 1) AS add_quarters_with_date,
    addQuarters(date_time, 1) AS add_quarters_with_date_time,
    addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string

┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│             2024-04-01 │         2024-04-01 00:00:00 │            2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

Usando sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalQuarter(10))─┐
│                                              2000-12-16 │
└─────────────────────────────────────────────────────────┘

Introduzido na versão: v1.1.0

Adiciona um número especificado de segundos a uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

addSeconds(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de segundos. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de segundos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime mais num segundos DateTime ou DateTime64(3)

Exemplos

Adicionar segundos a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addSeconds(date, 30) AS add_seconds_with_date,
    addSeconds(date_time, 30) AS add_seconds_with_date_time,
    addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string

┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│   2024-01-01 00:00:30 │        2024-01-01 00:00:30 │           2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalSecond(10))─┐
│                                    1998-06-16 00:00:10 │
└────────────────────────────────────────────────────────┘

Introduzido em: v22.11.0

Adiciona consecutivamente uma tupla de intervalos a uma data ou a uma data e hora.

Sintaxe

addTupleOfIntervals(datetime, intervals)

Argumentos

• datetime — Data ou data e hora à qual serão adicionados intervalos. Date ou Date32 ou DateTime ou DateTime64
• intervals — Tuple de intervalos a ser adicionada a datetime. Tuple(Interval)

Valor retornado

Retorna date com intervals adicionados. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar Tuple de intervalos à data

WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))

┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│                                                                           2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de semanas a uma data, uma data e hora ou uma data ou data com hora codificada como string.

Sintaxe

addWeeks(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de semanas. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de semanas a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime mais num semanas. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar semanas a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addWeeks(date, 5) AS add_weeks_with_date,
    addWeeks(date_time, 5) AS add_weeks_with_date_time,
    addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string

┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│          2024-02-05 │      2024-02-05 00:00:00 │         2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalWeek(10))─┐
│                                           1998-08-25 │
└──────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Adiciona um número especificado de anos a uma data, uma data e hora ou uma data, ou data e hora, codificada como string.

Sintaxe

addYears(datetime, num)

Argumentos

• datetime — Data ou data e hora à qual será adicionado o número especificado de anos. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de anos a adicionar. (U)Int* ou Float*

Valor retornado

Retorna datetime acrescido de num anos Date ou Date32 ou DateTime ou DateTime64

Exemplos

Adicionar anos a diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addYears(date, 1) AS add_years_with_date,
    addYears(date_time, 1) AS add_years_with_date_time,
    addYears(date_time_string, 1) AS add_years_with_date_time_string

┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│          2025-01-01 │      2025-01-01 00:00:00 │         2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)

┌─plus(CAST('1998-06-16', 'Date'), toIntervalYear(10))─┐
│                                           2008-06-16 │
└──────────────────────────────────────────────────────┘

Introduzido em: v23.1.0

Retorna o componente da unidade da diferença entre startdate e enddate. A diferença é calculada com precisão de 1 nanossegundo.

Por exemplo, a diferença entre 2021-12-29 e 2022-01-01 é de 3 dias para a unidade de dia, 0 meses para a unidade de mês e 0 anos para a unidade de ano.

Para uma alternativa a age, consulte a função dateDiff.

Sintaxe

age('unit', startdate, enddate[, timezone])

Argumentos

• unit — O tipo de intervalo do resultado.

• startdate — O primeiro valor de data/hora a ser subtraído (o subtraendo). Date ou Date32 ou DateTime ou DateTime64
• enddate — O segundo valor de data/hora do qual será feita a subtração (o minuendo). Date ou Date32 ou DateTime ou DateTime64
• timezone — Opcional. Nome do fuso horário. Se especificado, ele é aplicado tanto a startdate quanto a enddate. Se não for especificado, serão usados os fusos horários de startdate e enddate. Se eles não forem iguais, o resultado será indefinido. String

Valor retornado

Retorna a diferença entre enddate e startdate expressa em unit. Int32

Exemplos

Calcular a idade em horas

SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))

┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│                                                                                24 │
└───────────────────────────────────────────────────────────────────────────────────┘

Calcular a idade em diferentes unidades

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    age('day', s, e) AS day_age,
    age('month', s, e) AS month_age,
    age('year', s, e) AS year_age

┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │       3 │         0 │        0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘

Introduzido em: v24.7.0

Altera o componente de dia de uma data ou data e hora.

Sintaxe

changeDay(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo que date_or_datetime, com o componente de dia modificado. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeDay('2024-01-31'::DateTime, 15)

2024-01-15 00:00:00

Introduzido em: v24.7.0

Altera o componente de hora de uma data ou de uma data e hora.

Sintaxe

changeHour(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo que date_or_datetime, com o componente de hora modificado. DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)

2024-01-01 05:00:00

Introduzido em: v24.7.0

Altera o componente de minuto de um date or date time.

Sintaxe

changeMinute(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo que date_or_datetime, com o componente de minuto alterado. DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)

2024-01-01 12:45:00

Introduzido em: v24.7.0

Altera o componente de mês de uma data ou data e hora.

Sintaxe

changeMonth(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo que date_or_datetime, com o componente de mês modificado. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeMonth('2024-01-01'::DateTime, 12)

2024-12-01 00:00:00

Introduzido em: v24.7.0

Altera o componente de segundo de uma data ou data e hora.

Sintaxe

changeSecond(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo de date_or_datetime, com o componente de segundos modificado. DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)

2024-01-01 12:30:15

Introduzido em: v24.7.0

Altera o componente de ano de uma data ou data e hora.

Sintaxe

changeYear(date_or_datetime, value)

Argumentos

• date_or_datetime — O valor a ser alterado. Date ou Date32 ou DateTime ou DateTime64
• value — O novo valor. (U)Int*

Valor retornado

Retorna um valor do mesmo tipo que date_or_datetime, com o componente de ano modificado. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Exemplo de uso

SELECT changeYear('2024-01-01'::DateTime, 2023)

2023-01-01 00:00:00

Introduzido em: v23.4.0

Retorna a quantidade de limites da unit especificada cruzados entre startdate e enddate. A diferença é calculada usando unidades relativas. Por exemplo, a diferença entre 2021-12-29 e 2022-01-01 é de 3 dias para a unidade day (consulte toRelativeDayNum), 1 mês para a unidade month (consulte toRelativeMonthNum) e 1 ano para a unidade year (consulte toRelativeYearNum).

Se a unidade week for especificada, dateDiff assume que as semanas começam na segunda-feira. Observe que esse comportamento é diferente do da função toWeek(), na qual as semanas começam por padrão no domingo.

Para ver uma alternativa a dateDiff, consulte a função age.

Sintaxe

dateDiff(unit, startdate, enddate[, timezone])

Aliases: timestampDiff, TIMESTAMP_DIFF, DATE_DIFF, date_diff, timestamp_diff

Argumentos

• unit — O tipo de intervalo do resultado.

• startdate — O primeiro valor de data/hora a ser subtraído (o subtraendo). Date ou Date32 ou DateTime ou DateTime64
• enddate — O segundo valor de data/hora do qual subtrair (o minuendo). Date ou Date32 ou DateTime ou DateTime64
• timezone — Opcional. Nome do fuso horário. Se especificado, ele será aplicado a startdate e enddate. Se não for especificado, serão usados os fusos horários de startdate e enddate. Se eles não forem iguais, o resultado será indefinido. String

Valor retornado

Retorna a diferença entre enddate e startdate, expressa em unit. Int64

Exemplos

Calcular a diferença entre datas em horas

SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌─res─┐
│  25 │
└─────┘

Calcular a diferença entre datas em unidades diferentes

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    dateDiff('day', s, e) AS day_diff,
    dateDiff('month', s, e) AS month_diff,
    dateDiff('year', s, e) AS year_diff

┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │        3 │          1 │         1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘

Introduzido em: v21.7.0

Retorna a parte da data especificada.

Valores possíveis:

• 'year'
• 'quarter'
• 'month'
• 'week'
• 'dayofyear'
• 'day'
• 'weekday'
• 'hour'
• 'minute'
• 'second'

Sintaxe

dateName(date_part, date[, timezone])

Argumentos

• date_part — A parte da data que você deseja extrair. String
• datetime — Um valor de data ou data e hora. Date ou Date32 ou DateTime ou DateTime64
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna a parte especificada da data. String

Exemplos

Extrair diferentes partes da data

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
    dateName('year', date_value),
    dateName('month', date_value),
    dateName('day', date_value)

┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ April                         │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

Introduzido em: v20.8.0

Trunca um valor de data e hora até a parte especificada da data.

Sintaxe

dateTrunc(unit, datetime[, timezone])

Aliases: DATE_TRUNC

Argumentos

• unit — O tipo de intervalo usado para truncar o resultado. Valores possíveis: nanosecond (somente DateTime64), microsecond (somente DateTime64), millisecond (somente DateTime64), second, minute, hour, day, week, month, quarter, year. String
• datetime — Data e hora. Date ou Date32 ou DateTime ou DateTime64
• timezone — Opcional. Nome do fuso horário do datetime retornado. Se não for especificado, a função usa o fuso horário do parâmetro datetime. String

Valor retornado

Retorna o valor de data e hora truncado.

Exemplos

Truncar sem fuso horário

SELECT now(), dateTrunc('hour', now());

┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │       2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘

Truncamento com fuso horário especificado

SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');

┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │                        2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘

Introduzido em: v1.1.0

Formata uma data ou data e hora de acordo com a string de formato fornecida. format é uma expressão constante, portanto, não é possível ter vários formatos para uma única coluna de resultado.

formatDateTime usa o estilo de formatação de data e hora do MySQL; consulte a documentação do MySQL.

A operação oposta desta função é parseDateTime.

Usando campos de substituição, você pode definir um padrão para a string resultante. A coluna de exemplo na tabela abaixo mostra o resultado da formatação para 2018-01-02 22:33:44.

Campos de substituição:

• Em versões do ClickHouse anteriores à v23.4, %f imprime um único zero (0) se o valor formatado for um Date, Date32 ou DateTime (que não têm segundos fracionários) ou um DateTime64 com precisão 0.
• Em versões do ClickHouse anteriores à v25.1, %f imprime tantos dígitos quantos forem especificados pela escala do DateTime64, em vez de 6 dígitos fixos.
• Em versões do ClickHouse anteriores à v23.4, %M imprime o minuto (00-59) em vez do nome completo do mês (January-December).

Sintaxe

formatDateTime(datetime, format[, timezone])

Aliases: DATE_FORMAT

Argumentos

• datetime — Uma data ou data e hora a ser formatada. Date ou Date32 ou DateTime ou DateTime64
• format — String de formato com campos de substituição. String
• timezone — Opcional. Nome do fuso horário para a data e hora formatadas. String

Valor retornado

Retorna valores de data e hora de acordo com o formato especificado. String

Exemplos

Formatar data com marcador de ano

SELECT formatDateTime(toDate('2010-01-04'), '%g')

┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10                                         │
└────────────────────────────────────────────┘

Formatar DateTime64 com frações de segundo

SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')

┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 123456                                                              │
└─────────────────────────────────────────────────────────────────────┘

Formato com fuso horário

SELECT
    now() AS ts,
    time_zone,
    formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam  │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Andorra    │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan  │ 23:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Athens     │ 22:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belfast    │ 20:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belgrade   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Berlin     │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Brussels   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bucharest  │ 22:13:40    │
└─────────────────────┴───────────────────┴─────────────┘

Introduzido em: v20.1.0

Semelhante a formatDateTime, mas formata data e hora no estilo Joda em vez do estilo MySQL. Consulte a documentação do Joda Time.

A operação oposta desta função é parseDateTimeInJodaSyntax.

Usando campos de substituição, você pode definir um padrão para a string resultante.

Campos de substituição:

Sintaxe

formatDateTimeInJodaSyntax(datetime, format[, timezone])

Argumentos

• datetime — Uma data ou data e hora a ser formatada. DateTime ou Date ou Date32 ou DateTime64
• format — String de formato com campos de substituição no estilo Joda. String
• timezone — Opcional. Nome do fuso horário para a hora formatada. String

Valor retornado

Retorna valores de data e hora de acordo com o formato especificado. String

Exemplos

Formatar datetime usando a sintaxe Joda

SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')

┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56                                                                  │
└──────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.11.0

Para um determinado número de dias transcorridos desde 1 January 0000, retorna a data correspondente no calendário gregoriano proléptico definido pela ISO 8601.

O cálculo é o mesmo da função FROM_DAYS() do MySQL. O resultado é indefinido se não puder ser representado dentro dos limites do tipo Date.

Sintaxe

fromDaysSinceYearZero(days)

Aliases: FROM_DAYS

Argumentos

• days — O número de dias transcorridos desde o ano zero. UInt32

Valor retornado

Retorna a data correspondente ao número de dias transcorridos desde o ano zero. Date

Exemplos

Converter dias transcorridos desde o ano zero em datas

SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

Introduzido em: v23.11.0

Para um determinado número de dias decorridos desde 1 de janeiro de 0000, retorna a data correspondente no calendário gregoriano proléptico definido pela ISO 8601. O cálculo é o mesmo da função FROM_DAYS() do MySQL. O resultado é indefinido se não puder ser representado nos limites do tipo Date32.

Sintaxe

fromDaysSinceYearZero32(days)

Argumentos

• days — O número de dias decorridos desde o ano zero. UInt32

Valor retornado

Retorna a data correspondente ao número de dias decorridos desde o ano zero. Date32

Exemplos

Converter dias desde o ano zero em datas

SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

Introduzido em: v21.1.0

Converte um número de Dia Juliano Modificado em uma data do calendário gregoriano proléptico, em formato de texto YYYY-MM-DD. Esta função oferece suporte a números de dia de -678941 a 2973483 (que representam 0000-01-01 e 9999-12-31, respectivamente). Ela gera uma exceção se o número do dia estiver fora do intervalo compatível.

Sintaxe

fromModifiedJulianDay(day)

Argumentos

• day — número do Dia Juliano Modificado. (U)Int*

Valor retornado

Retorna a data em formato de texto. String

Exemplos

Converter Dia Juliano Modificado em data

SELECT fromModifiedJulianDay(58849)

┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01                   │
└──────────────────────────────┘

Introduzido em: v21.1.0

Semelhante a fromModifiedJulianDay(), mas, em vez de lançar exceções, retorna NULL.

Sintaxe

fromModifiedJulianDayOrNull(day)

Argumentos

• day — número do Dia Juliano Modificado. (U)Int*

Valor retornado

Retorna a data em formato de texto para um argumento day válido; caso contrário, null. Nullable(String)

Exemplos

Converter Dia Juliano Modificado em data com tratamento de null

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- invalid argument, returns NULL

┌─fromModifiedJulianDayOrNull(58849)─┐
│ 2020-01-01                         │
└────────────────────────────────────┘
┌─fromModifiedJulianDayOrNull(60000000)─┐
│ ᴺᵁᴸᴸ                                  │
└───────────────────────────────────────┘

Introduzido em: v22.1.0

Converte um valor de data ou data com hora do fuso horário UTC em um valor de data ou data com hora no fuso horário especificado. Esta função é incluída principalmente para fins de compatibilidade com o Apache Spark e frameworks semelhantes.

Sintaxe

fromUTCTimestamp(datetime, time_zone)

Aliases: from_utc_timestamp

Argumentos

• datetime — Um valor constante de data ou data com hora, ou uma expressão. DateTime ou DateTime64
• time_zone — Um valor constante do tipo String ou uma expressão que representa o fuso horário. String

Valor retornado

Retorna um DateTime/DateTime64 no fuso horário especificado. DateTime ou DateTime64

Exemplos

Converta o fuso horário UTC para o fuso horário especificado

SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')

┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')─┐
│                                                   2023-03-16 18:00:00.000 │
└───────────────────────────────────────────────────────────────────────────┘

Introduzido em: v20.8.0

Esta função converte um timestamp Unix em uma data de calendário e uma hora do dia.

Ela pode ser chamada de duas maneiras:

• Quando recebe um único argumento do tipo Integer, retorna um valor do tipo DateTime, ou seja, comporta-se como toDateTime.
• Quando recebe dois ou três argumentos, em que o primeiro argumento é um valor do tipo Integer, Date, Date32, DateTime ou DateTime64, o segundo argumento é uma string de formato constante e o terceiro argumento é uma string constante de fuso horário opcional, a função retorna um valor do tipo String, ou seja, comporta-se como formatDateTime. Nesse caso, é usado o estilo de formatação de datetime do MySQL.

Sintaxe

fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])

Aliases: FROM_UNIXTIME

Argumentos

• timestamp — timestamp Unix ou valor de data/data com hora. (U)Int* ou Date ou Date32 ou DateTime ou DateTime64
• format — Opcional. String de formato constante para a formatação de saída. String
• timezone — Opcional. String constante de fuso horário. String

Valor retornado

Retorna DateTime a partir do timestamp quando chamada com um argumento, ou uma String quando chamada com dois ou três argumentos. DateTime ou String

Exemplos

Converte um timestamp Unix em DateTime

SELECT fromUnixTimestamp(423543535)

┌─fromUnixTimestamp(423543535)─┐
│          1983-06-04 02:58:55 │
└──────────────────────────────┘

Converta o timestamp Unix com formato

SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

Introduzido em: v23.1.0

Esta função converte um timestamp Unix em uma data de calendário e uma hora do dia.

Ela pode ser chamada de duas maneiras:

Quando recebe um único argumento do tipo Integer, retorna um valor do tipo DateTime, ou seja, comporta-se como toDateTime.

Quando recebe dois ou três argumentos, em que o primeiro é um valor do tipo Integer, Date, Date32, DateTime ou DateTime64, o segundo é uma string de formato constante e o terceiro é uma string constante opcional de fuso horário, a função retorna um valor do tipo String, ou seja, comporta-se como formatDateTimeInJodaSyntax. Nesse caso, é usado o estilo de formato de data e hora do Joda.

Sintaxe

fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])

Argumentos

• timestamp — timestamp Unix ou valor de data/hora. (U)Int* ou Date ou Date32 ou DateTime ou DateTime64
• format — Opcional. String de formato constante usando a sintaxe Joda para formatação de saída. String
• timezone — Opcional. String constante de fuso horário. String

Valor retornado

Retorna uma data com hora quando chamada com um argumento, ou uma String quando chamada com dois ou três argumentos.} DateTime ou String

Exemplos

Converter timestamp Unix com formato Joda

SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

Introduzido em: v26.7.0

Retorna a hora atual do dia no fuso horário do servidor (ou da sessão), no momento da análise da consulta. A função é uma expressão constante. É o LOCALTIME padrão do SQL/PostgreSQL e equivale a CAST(now() AS Time).

Sintaxe

localtime()

Argumentos

• Nenhum.

Valor retornado

Retorna a hora atual do dia. Time

Exemplos

Sintaxe SQL padrão sem parênteses

SELECT LOCALTIME

┌───────LOCALTIME─┐
│        07:42:09 │
└─────────────────┘

Introduzido na versão: v22.6.0

Cria um Date a partir de:

• ano, mês e dia
• ano e dia do ano

Sintaxe

makeDate(year, month, day)
makeDate(year, day_of_year)

Argumentos

• year — Número do ano. (U)Int* ou Float* ou Decimal
• month — Número do mês (1-12). (U)Int* ou Float* ou Decimal
• day — Dia do mês (1-31). (U)Int* ou Float* ou Decimal
• day_of_year — Dia do ano (1-365). (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um valor Date criado a partir dos argumentos fornecidos Date

Exemplos

Data a partir de ano, mês e dia

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

Data a partir do ano e do dia do ano

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

Introduzido na versão: v22.6.0

Cria um Date32 a partir de:

• ano, mês e dia
• ano e dia do ano

Sintaxe

makeDate32(year, month, day)
makeDate32(year, day_of_year)

Argumentos

• year — Número do ano. (U)Int* ou Float* ou Decimal
• month — Número do mês (1-12). (U)Int* ou Float* ou Decimal
• day — Dia do mês (1-31). (U)Int* ou Float* ou Decimal
• day_of_year — Dia do ano (1-365). (U)Int* ou Float* ou Decimal

Valor retornado

Retorna um valor Date32 construído com os argumentos fornecidos Date32

Exemplos

Date32 a partir de ano, mês e dia

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

Date32 com base no ano e no dia do ano

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

Introduzido em: v22.6.0

Cria um DateTime a partir do ano, mês, dia, hora, minuto e segundo, com timezone opcional.

Sintaxe

makeDateTime(year, month, day, hour, minute, second[, timezone])

Argumentos

• year — Número do ano. (U)Int* ou Float* ou Decimal
• month — Número do mês (1-12). (U)Int* ou Float* ou Decimal
• day — Dia do mês (1-31). (U)Int* ou Float* ou Decimal
• hour — Hora (0-23). (U)Int* ou Float* ou Decimal
• minute — Minuto (0-59). (U)Int* ou Float* ou Decimal
• second — Segundo (0-59). (U)Int* ou Float* ou Decimal
• timezone — Nome do fuso horário. String

Valor retornado

Retorna um valor DateTime construído a partir dos argumentos fornecidos DateTime

Exemplos

DateTime a partir de ano, mês, dia, hora, minuto e segundo

SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;

┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘

Introduzido em: v22.6.0

Cria um DateTime64 a partir de ano, mês, dia, hora, minuto e segundo, com fração, precisão e fuso horário opcionais.

Sintaxe

makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])

Argumentos

• year — Número do ano. (U)Int* ou Float* ou Decimal
• month — Número do mês (1-12). (U)Int* ou Float* ou Decimal
• day — Dia do mês (1-31). (U)Int* ou Float* ou Decimal
• hour — Hora (0-23). (U)Int* ou Float* ou Decimal
• minute — Minuto (0-59). (U)Int* ou Float* ou Decimal
• second — Segundo (0-59). (U)Int* ou Float* ou Decimal
• fraction — Parte fracionária do segundo. (U)Int* ou Float* ou Decimal
• precision — Precisão da parte fracionária (0-9). UInt8
• timezone — Nome do fuso horário. String

Valor retornado

Retorna um valor DateTime64 construído a partir dos argumentos fornecidos DateTime64

Exemplos

DateTime64 a partir de ano, mês, dia, hora, minuto e segundo

SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);

┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│                       2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘

Introduzido em: v22.1.0

Retorna o nome do mês como uma string a partir de um valor de data ou de data com hora.

Sintaxe

monthName(datetime)

Argumentos

• datetime — Data ou data e hora. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna o nome do mês. String

Exemplos

Obter o nome do mês a partir de uma data

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)

┌─monthName(date_value)─┐
│ April                 │
└───────────────────────┘

Introduzido em: v1.1.0

Retorna a data e hora atuais no momento da análise da consulta. A função é uma expressão constante.

Sintaxe

now([timezone])

Aliases: localtimestamp, current_timestamp

Argumentos

• timezone — Opcional. Nome do fuso horário do valor retornado. String

Valor retornado

Retorna a data e a hora atuais. DateTime

Exemplos

Consulta sem fuso horário

SELECT now()

┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘

Consulta com fuso horário especificado

SELECT now('Asia/Istanbul')

┌─now('Asia/Istanbul')─┐
│  2020-10-17 10:42:23 │
└──────────────────────┘

Sintaxe SQL padrão sem parênteses

SELECT NOW, CURRENT_TIMESTAMP

┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘

Introduzido em: v20.1.0

Retorna a data e a hora atuais com precisão inferior a segundos no momento da análise da consulta. A função é uma expressão constante.

Sintaxe

now64([scale[, timezone]])

Argumentos

• scale — Opcional. Tamanho do tick (precisão): 10^-precision segundos. Faixa válida: [0 : 9]. Em geral, usam-se 3 (padrão) (milissegundos), 6 (microssegundos) e 9 (nanossegundos). UInt8
• timezone — Opcional. Nome do fuso horário para o valor retornado. String

Valor retornado

Retorna a data e a hora atuais com precisão de subsegundos. DateTime64

Exemplos

Consulta com precisão padrão e personalizada

SELECT now64(), now64(9, 'Asia/Istanbul')

┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘

Introduzido em: v22.8.0

Retorna a data e a hora atuais no momento em que cada bloco de dados é processado. Ao contrário da função now, não é uma expressão constante, e o valor retornado será diferente entre os blocos em consultas de longa duração.

Faz sentido usar essa função para gerar a hora atual em consultas INSERT SELECT de longa duração.

Sintaxe

nowInBlock([timezone])

Argumentos

• timezone — Opcional. Nome do fuso horário do valor retornado. String

Valor retornado

Retorna a data e a hora atuais no momento em que cada bloco de dados é processado. DateTime

Exemplos

Diferença em relação à função now()

SELECT
    now(),
    nowInBlock(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │        0 │
└─────────────────────┴─────────────────────┴──────────┘

Introduzido em: v25.8.0

Retorna a data e a hora atuais no momento do processamento de cada bloco de dados, em milissegundos. Ao contrário da função now64, não é uma expressão constante, e o valor retornado será diferente entre blocos distintos em consultas de longa duração.

Faz sentido usar essa função para gerar a hora atual em consultas INSERT SELECT de longa duração.

Sintaxe

nowInBlock64([scale[, timezone]])

Argumentos

• scale — Opcional. Tamanho do tick (precisão): 10^-precision segundos. Intervalo válido: [0 : 9]. Normalmente, usam-se 3 (padrão) (milissegundos), 6 (microssegundos) e 9 (nanossegundos). UInt8
• timezone — Opcional. Nome do fuso horário do valor retornado. String

Valor retornado

Retorna a data e a hora atuais no momento em que cada bloco de dados é processado, com precisão de subsegundos. DateTime64

Exemplos

Diferença em relação à função now64()

SELECT
    now64(),
    nowInBlock64(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │        0 │
└─────────────────────────┴─────────────────────────┴──────────┘

Introduzido em: v23.6.0

Retorna o fuso horário do servidor, ou seja, o valor da configuração timezone. Se a função for executada no contexto de uma tabela distribuída, ela gerará uma coluna comum com valores correspondentes a cada shard. Caso contrário, produzirá um valor constante.

Sintaxe

serverTimezone()

Nomes alternativos: serverTimeZone

Argumentos

• Nenhum.

Valor retornado

Retorna o fuso horário do servidor como uma String

Exemplos

Exemplo de uso

SELECT serverTimeZone()

┌─serverTimeZone()─┐
│ Etc/UTC          │
└──────────────────┘

Introduzido em: v23.9.0

Subtrai o intervalo de tempo da data, data e hora ou data, ou data e hora codificada como string, fornecida. Se a subtração resultar em um valor fora dos limites do tipo de dado, o resultado será indefinido.

Sintaxe

subDate(datetime, interval)

Argumentos

• datetime — A data ou data e hora da qual interval é subtraído. Date ou Date32 ou DateTime ou DateTime64
• interval — Intervalo a ser subtraído. Interval

Valor retornado

Retorna a data ou data e hora obtida ao subtrair interval de datetime. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair intervalo de uma data

SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2015-01-01 │
└──────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de dias de uma data, uma data e hora ou uma data, ou data e hora, codificada como string.

Sintaxe

subtractDays(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual subtrair o número especificado de dias. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de dias a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime com num dias subtraídos Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair dias de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractDays(date, 31) AS subtract_days_with_date,
    subtractDays(date_time, 31) AS subtract_days_with_date_time,
    subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string

┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│              2023-12-01 │          2023-12-01 00:00:00 │             2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalDay(10))─┐
│                                           1998-06-06 │
└──────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de horas de uma data, de uma data e hora ou de uma data ou data e hora representada como string.

Sintaxe

subtractHours(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual será subtraído o número especificado de horas. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de horas a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num horas, DateTime ou DateTime64(3)

Exemplos

Subtrair horas de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractHours(date, 12) AS subtract_hours_with_date,
    subtractHours(date_time, 12) AS subtract_hours_with_date_time,
    subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string

┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│      2023-12-31 12:00:00 │           2023-12-31 12:00:00 │              2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalHour(10))─┐
│                                   1998-06-15 14:00:00 │
└───────────────────────────────────────────────────────┘

Introduzido em: v22.11.0

Adiciona um intervalo negativo a outro intervalo ou a uma tupla de intervalos.

Observação: intervalos do mesmo tipo serão combinados em um único intervalo. Por exemplo, se toIntervalDay(2) e toIntervalDay(1) forem informados, o resultado será (1) em vez de (2,1).

Sintaxe

subtractInterval(interval_1, interval_2)

Argumentos

• interval_1 — Primeiro intervalo ou tupla de intervalos. Interval ou Tuple(Interval)
• interval_2 — Segundo intervalo a ser negado. Interval

Valor retornado

Retorna uma tupla de intervalos Tuple(T)

Exemplos

Subtração de intervalos

SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);

┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1)                                                 │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1)                                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1)                                                  │
└──────────────────────────────────────────────────────┘

Introduzido em: v22.6.0

Subtrai um número especificado de microssegundos de uma data e hora ou de uma data e hora codificada como string.

Sintaxe

subtractMicroseconds(datetime, num)

Argumentos

• datetime — Data com hora da qual será subtraído o número especificado de microssegundos. DateTime ou DateTime64 ou String
• num — Número de microssegundos a serem subtraídos. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num microssegundos. DateTime64

Exemplos

Subtrair microssegundos de diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
    subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string

┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│           2023-12-31 23:59:59.000000 │                  2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─minus(CAST('1998-06-16', 'DateTime'), toIntervalMicrosecond(10))─┐
│                                       1998-06-15 23:59:59.999990 │
└──────────────────────────────────────────────────────────────────┘

Introduzido na versão: v22.6.0

Subtrai um número especificado de milissegundos de uma data e hora ou de uma data e hora codificada como string.

Sintaxe

subtractMilliseconds(datetime, num)

Argumentos

• datetime — Data e hora da qual será subtraído o número especificado de milissegundos. DateTime ou DateTime64 ou String
• num — Número de milissegundos a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num milissegundos DateTime64

Exemplos

Subtrair milissegundos de diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
    subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string

┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│              2023-12-31 23:59:59.000 │                     2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─minus(CAST('1998-06-16', 'DateTime'), toIntervalMillisecond(10))─┐
│                                          1998-06-15 23:59:59.990 │
└──────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de minutos de uma data, de uma data e hora ou de uma data ou data e hora representada como string.

Sintaxe

subtractMinutes(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual será subtraído o número especificado de minutos. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de minutos a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime com num minutos subtraídos. DateTime ou DateTime64(3)

Exemplos

Subtrair minutos de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMinutes(date, 30) AS subtract_minutes_with_date,
    subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
    subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string

┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│        2023-12-31 23:30:00 │             2023-12-31 23:30:00 │                2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

Usando a sintaxe alternativa do INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalMinute(10))─┐
│                                     1998-06-15 23:50:00 │
└─────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de meses de uma data, de uma data e hora ou de uma data/data e hora codificada como string.

Sintaxe

subtractMonths(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual será subtraído o número especificado de meses. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de meses a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num meses. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair meses de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMonths(date, 1) AS subtract_months_with_date,
    subtractMonths(date_time, 1) AS subtract_months_with_date_time,
    subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string

┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│                2023-12-01 │            2023-12-01 00:00:00 │               2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘

Uso da sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalMonth(10))─┐
│                                             1997-08-16 │
└────────────────────────────────────────────────────────┘

Introduzido na versão: v20.1.0

Subtrai um número especificado de nanossegundos de uma data e hora ou de uma data e hora codificada como string.

Sintaxe

subtractNanoseconds(datetime, num)

Argumentos

• datetime — Data e hora da qual será subtraído o número especificado de nanossegundos. DateTime ou DateTime64 ou String
• num — Número de nanossegundos a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num nanossegundos. DateTime64

Exemplos

Subtrair nanossegundos de diferentes tipos de data e hora

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
    subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string

┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│       2023-12-31 23:59:59.999999000 │              2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)

┌─minus(CAST('1998-06-16', 'DateTime'), toIntervalNanosecond(10))─┐
│                                   1998-06-15 23:59:59.999999990 │
└─────────────────────────────────────────────────────────────────┘

Introduzido em: v20.1.0

Subtrai um número especificado de trimestres de uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

subtractQuarters(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual o número especificado de trimestres será subtraído. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de trimestres a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime com num trimestres subtraídos Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair trimestres de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractQuarters(date, 1) AS subtract_quarters_with_date,
    subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
    subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string

┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│                  2023-10-01 │              2023-10-01 00:00:00 │                 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalQuarter(10))─┐
│                                               1995-12-16 │
└──────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de segundos de uma data, uma data e hora ou uma data, ou data e hora, codificada como string.

Sintaxe

subtractSeconds(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual será subtraído o número especificado de segundos. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de segundos a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num segundos. DateTime ou DateTime64(3)

Exemplos

Subtrair segundos de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractSeconds(date, 60) AS subtract_seconds_with_date,
    subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
    subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string

┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│        2023-12-31 23:59:00 │             2023-12-31 23:59:00 │                2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalSecond(10))─┐
│                                     1998-06-15 23:59:50 │
└─────────────────────────────────────────────────────────┘

Introduzido em: v22.11.0

Subtrai consecutivamente uma tupla de intervalos de uma data ou de uma data e hora.

Sintaxe

subtractTupleOfIntervals(datetime, intervals)

Argumentos

• datetime — Data ou data e hora da qual subtrair intervalos. Date ou Date32 ou DateTime ou DateTime64
• intervals — Tupla de intervalos a subtrair de datetime. Tuple(Interval)

Valor retornado

Retorna date com os intervals subtraídos. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair uma tupla de intervalos de uma data

WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))

┌─subtractTupleOfIntervals(date, (toIntervalDay(1), toIntervalYear(1)))─┐
│                                                            2016-12-31 │
└───────────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número especificado de semanas de uma data, uma data e hora ou uma data ou data e hora codificada como string.

Sintaxe

subtractWeeks(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual subtrair o número especificado de semanas. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de semanas a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num semanas Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtração de semanas em diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractWeeks(date, 1) AS subtract_weeks_with_date,
    subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
    subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string

┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│               2023-12-25 │           2023-12-25 00:00:00 │              2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Usando a sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalWeek(10))─┐
│                                            1998-04-07 │
└───────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Subtrai um número específico de anos de uma data, uma data e hora ou uma data, ou data e hora, codificada como string.

Sintaxe

subtractYears(datetime, num)

Argumentos

• datetime — Data ou data e hora da qual o número especificado de anos será subtraído. Date ou Date32 ou DateTime ou DateTime64 ou String
• num — Número de anos a subtrair. (U)Int* ou Float*

Valor retornado

Retorna datetime menos num anos. Date ou Date32 ou DateTime ou DateTime64

Exemplos

Subtrair anos de diferentes tipos de data

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractYears(date, 1) AS subtract_years_with_date,
    subtractYears(date_time, 1) AS subtract_years_with_date_time,
    subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string

┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│               2023-01-01 │           2023-01-01 00:00:00 │              2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Uso da sintaxe alternativa de INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)

┌─minus(CAST('1998-06-16', 'Date'), toIntervalYear(10))─┐
│                                            1988-06-16 │
└───────────────────────────────────────────────────────┘

Introduzido em: v23.4.0

Retorna a diferença, em segundos, entre duas datas ou entre duas datas com hora. A diferença é calculada como enddate - startdate.

Esta função é equivalente a dateDiff('second', startdate, enddate).

Para calcular diferenças de tempo em outras unidades (horas, dias, meses etc.), use a função dateDiff.

Sintaxe

timeDiff(startdate, enddate)

Argumentos

• startdate — O primeiro valor de tempo a ser subtraído (o subtraendo). Date ou Date32 ou DateTime ou DateTime64
• enddate — O segundo valor de tempo do qual será subtraído o primeiro (o minuendo). Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna a diferença entre enddate e startdate, expressa em segundos. Int64

Exemplos

Calcular a diferença de tempo em segundos

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌───res─┐
│ 90000 │
└───────┘

Calcular a diferença de tempo e converter em horas

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours

┌─hours─┐
│    25 │
└───────┘

Equivalente a dateDiff em segundos

SELECT
    timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
    dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result

┌─time_diff_result─┬─date_diff_result─┐
│           259200 │           259200 │
└──────────────────┴──────────────────┘

Introduzido em: v1.1.0

Arredonda a hora para o início de um intervalo de meia hora.

Sintaxe

timeSlot(time[, time_zone])

Argumentos

• time — Hora a ser arredondada para o início de um intervalo de meia hora. DateTime ou Date32 ou DateTime64
• time_zone — Opcional. Um valor constante do tipo String ou uma expressão que representa o fuso horário. String

Valor retornado

Retorna a hora arredondada para o início de um intervalo de meia hora. DateTime

Exemplos

Arredondar a hora para um intervalo de meia hora

SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))

┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│                                2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Para um intervalo de tempo que começa em StartTime e dura Duration segundos, retorna um Array de instantes, composto por pontos desse intervalo arredondados para baixo em múltiplos de Size segundos. Size é um parâmetro opcional cujo valor padrão é 1800 (30 minutos).

Isso é necessário, por exemplo, ao procurar visualizações de página na sessão correspondente.

Para DateTime64, a escala do valor retornado pode ser diferente da escala de StartTime. É usada a maior escala entre todos os argumentos fornecidos.

Sintaxe

timeSlots(StartTime, Duration[, Size])

Argumentos

• StartTime — Horário de início do intervalo. DateTime ou DateTime64
• Duration — Duração do intervalo em segundos. UInt32 ou DateTime64
• Size — Opcional. Tamanho dos intervalos de tempo em segundos. O padrão é 1800 (30 minutos). UInt32 ou DateTime64

Valor retornado

Retorna um array de DateTime/DateTime64 (o tipo de retorno corresponde ao tipo de StartTime). Para DateTime64, a escala do valor retornado pode ser diferente da escala de StartTime — é usada a maior escala entre todos os argumentos fornecidos. Array(DateTime) ou Array(DateTime64)

Exemplos

Gerar intervalos de tempo para um intervalo

SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))

┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00']               │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11']     │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000']                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Introduzido em: v23.9.0

Converte o primeiro argumento expr para o tipo DateTime64(6). Se um segundo argumento expr_time for informado, adiciona o horário especificado ao valor convertido.

Sintaxe

timestamp(expr[, expr_time])

Argumentos

• expr — Data ou data e hora. String
• expr_time — Opcional. Horário a ser adicionado ao valor convertido. String

Valor retornado

Retorna o valor convertido de expr ou expr com o horário adicionado DateTime64(6)

Exemplos

Converter string de data em DateTime64(6)

SELECT timestamp('2023-12-31') AS ts;

┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘

Adicionar horário à string de data

SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;

┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘

Introduzido em: v21.4.0

Retorna o nome do fuso horário da sessão atual ou converte um offset ou nome de fuso horário em um nome canônico de fuso horário.

Sintaxe

timezone()

Aliases: timeZone

Argumentos

• Nenhum.

Valor retornado

Retorna o nome canônico do fuso horário na forma de uma String

Exemplos

Exemplo de uso

SELECT timezone()

┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘

Introduzido na versão: v21.4.0

Retorna o nome do fuso horário de um valor DateTime ou DateTime64.

Sintaxe

timezoneOf(datetime)

Aliases: timeZoneOf

Argumentos

• datetime — Um valor do tipo DateTime ou DateTime64
• timezone — Opcional. Nome do fuso horário para o qual converter o valor datetime. String

Valor retornado

Retorna o nome do fuso horário do datetime String

Exemplos

Exemplo de uso

SELECT timezoneOf(now());

┌─timezoneOf(now())─┐
│ Etc/UTC           │
└───────────────────┘

Introduzido em: v21.6.0

Retorna o deslocamento do fuso horário em segundos em relação ao UTC. A função leva em conta o horário de verão e alterações históricas no fuso horário na data e hora especificadas.

Sintaxe

timezoneOffset(datetime)

Aliases: timeZoneOffset

Argumentos

• datetime — valor DateTime para obter o deslocamento do fuso horário. DateTime ou DateTime64

Valor retornado

Retorna o deslocamento em relação a UTC, em segundos Int32

Exemplos

Exemplo de uso

SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time,
toTypeName(Time) AS Type,
timezoneOffset(Time) AS Offset_in_seconds,
(Offset_in_seconds / 3600) AS Offset_in_hours;

┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │            -14400 │              -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘

Introduzido em: v1.1.0

Retorna o dia do mês (1-31) de um Date ou DateTime.

Sintaxe

toDayOfMonth(datetime)

Aliases: DAY, DAYOFMONTH

Argumentos

• datetime — Data ou data e hora da qual se obtém o dia do mês. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna o dia do mês da data/hora especificada UInt8

Exemplos

Exemplo de uso

SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                              21 │
└─────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Retorna o número do dia da semana correspondente a um valor Date ou DateTime.

A forma com dois argumentos de toDayOfWeek() permite especificar se a semana começa na segunda-feira ou no domingo e se o valor de retorno deve estar no intervalo de 0 a 6 ou de 1 a 7.

Sintaxe

toDayOfWeek(datetime[, mode[, timezone]])

Aliases: DAYOFWEEK

Argumentos

• datetime — Data ou data e hora da qual se obtém o dia da semana. Date ou Date32 ou DateTime ou DateTime64
• mode — Opcional. Inteiro que especifica o modo da semana (0–3). O padrão é 0 se for omitido. UInt8
• timezone — Opcional. Fuso horário a ser usado na conversão. String

Valor retornado

Retorna o dia da semana para o Date ou DateTime informado UInt8

Exemplos

Exemplo de uso

-- A data a seguir é 21 de abril de 2023, que foi uma sexta-feira:
SELECT
    toDayOfWeek(toDateTime('2023-04-21')),
    toDayOfWeek(toDateTime('2023-04-21'), 1)

┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│                                     5 │                                        4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘

Introduzido em: v18.4.0

Retorna o número do dia no ano (1-366) de um valor Date ou DateTime.

Sintaxe

toDayOfYear(datetime)

Aliases: DAYOFYEAR

Argumentos

• datetime — Data ou data e hora da qual será obtido o dia do ano. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna o dia do ano da Date ou DateTime especificada UInt16

Exemplos

Exemplo de uso

SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                            111 │
└────────────────────────────────────────────────┘

Introduzido na versão: v26.3.0

Retorna o número de dias do mês de um Date ou DateTime.

O valor retornado está no intervalo de 28 a 31.

Sintaxe

toDaysInMonth(datetime)

Argumentos

• datetime — Data ou data e hora a partir da qual obter o número de dias no mês. Date or Date32 or DateTime or DateTime64

Valor retornado

Retorna o número de dias no mês da data/hora informada. UInt8

Exemplos

Exemplo de uso

SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))

┌─toDaysInMonth(toDate('2023-02-01'))─┬─toDaysInMonth(toDate('2024-02-01'))─┬─toDaysInMonth(toDate('2023-01-01'))─┐
│                                  28 │                                  29 │                                  31 │
└─────────────────────────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘

Introduzido em: v23.9.0

Para uma determinada data, retorna o número de dias decorridos desde 1 de janeiro de 0000 no calendário gregoriano proléptico definido pela ISO 8601.

O cálculo é o mesmo da função TO_DAYS do MySQL.

Sintaxe

toDaysSinceYearZero(date[, time_zone])

Aliases: TO_DAYS

Argumentos

• date — A data ou data e hora para a qual calcular o número de dias desde o ano zero. Date ou Date32 ou DateTime ou DateTime64
• time_zone — Fuso horário. String

Valor retornado

Retorna o número de dias decorridos desde a data 0000-01-01. UInt32

Exemplos

Calcular os dias desde o ano zero

SELECT toDaysSinceYearZero(toDate('2023-09-08'))

┌─toDaysSinceYearZero(toDate('2023-09-08'))─┐
│                                    739136 │
└───────────────────────────────────────────┘

Introduzido em: v1.1.0

Retorna o componente hora (0–23) de um valor DateTime ou DateTime64.

Sintaxe

toHour(datetime)

Aliases: HOUR

Argumentos

• datetime — Data e hora da qual será extraída a hora. DateTime ou DateTime64

Valor retornado

Retorna a hora (0-23) de datetime. UInt8

Exemplos

Exemplo de uso

SELECT toHour(toDateTime('2023-04-21 10:20:30'))

┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│                                        10 │
└───────────────────────────────────────────┘

Introduzido em: v20.1.0

Retorna o número da semana ISO de uma data ou de uma data e hora.

Esta é uma função de compatibilidade equivalente a toWeek(date, 3). As semanas ISO começam na segunda-feira, e a primeira semana do ano contém o dia 4 de janeiro. De acordo com a ISO 8601, os números das semanas estão no intervalo de 1 a 53.

Observe que datas próximas ao início ou ao fim de um ano podem retornar um número de semana do ano anterior ou do ano seguinte. Por exemplo, 29 de dezembro de 2025 retorna a semana 1 porque cai na primeira semana que contém 4 de janeiro de 2026.

Sintaxe

toISOWeek(datetime[, timezone])

Argumentos

• datetime — Data ou data e hora a partir da qual obter o número da semana ISO. Date or DateTime or Date32 or DateTime64
• timezone — Opcional. Fuso horário. String

Valor retornado

Retorna o número da semana ISO de acordo com o padrão ISO 8601. Retorna um número entre 1 e 53. UInt8

Exemplos

Obter os números das semanas ISO

SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek

┌───────date─┬─isoWeek─┐
│ 2016-12-27 │      52 │
└────────────┴─────────┘

A semana ISO pode pertencer a um ano diferente

SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year

┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │       1 │ 2025 │
└────────────┴─────────┴──────┘

Introduzido em: v18.4.0

Converte uma data ou uma data e hora no número do ano ISO.

Sintaxe

toISOYear(datetime)

Argumentos

• datetime — O valor com data ou com data e hora. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna o valor de entrada convertido em um número de ano ISO. UInt16

Exemplos

Obter o ano ISO de valores de data

SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2

┌─year1─┬─year2─┐
│  2024 │  2024 │
└───────┴───────┘

Introduzido na versão: v1.1.0

Arredonda uma data ou data e hora para o último dia do mês.

Sintaxe

toLastDayOfMonth(value)

Aliases: LAST_DAY

Argumentos

• value — A data ou data e hora a ser arredondada para o último dia do mês. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna a data do último dia do mês para a data ou data e hora fornecida. Date

Exemplos

Arredondar para o último dia do mês

SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-30 │
└─────────────────────────────────────────────────────┘

Introduzido em: v23.5.0

Arredonda uma data ou data e hora para cima até o sábado ou domingo mais próximo.

Sintaxe

toLastDayOfWeek(datetime[, mode[, timezone]])

Argumentos

• datetime — Uma data ou data e hora para converter. Date ou DateTime ou Date32 ou DateTime64
• mode — Determina o primeiro dia da semana, conforme descrito na função toWeek(). O padrão é 0. UInt8
• timezone — Opcional. O fuso horário a ser usado na conversão. Se não for especificado, o fuso horário do servidor será usado. String

Valor retornado

Retorna a data do sábado ou domingo mais próximo, na data especificada ou após ela, dependendo do modo. Date ou Date32

Exemplos

Arredondar para cima até o sábado ou domingo mais próximo

SELECT
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* a Friday */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
    toLastDayOfWeek(toDate('2023-04-23')), /* a Sunday */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* a Sunday */
FORMAT Vertical

Row 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')):    2023-04-22
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-23
toLastDayOfWeek(toDate('2023-04-23')):                 2023-04-29
toLastDayOfWeek(toDate('2023-04-23'), 1):              2023-04-23

Introduzido em: v25.7.0

Retorna o componente de microssegundos (0-999999) de um valor DateTime64.

Sintaxe

toMicrosecond(datetime)

Aliases: MICROSECOND

Argumentos

• datetime — Data e hora da qual extrair o microssegundo. DateTime64

Valor retornado

Retorna o microssegundo do segundo (0 - 999999) de datetime. UInt32

Exemplos

Exemplo de uso

SELECT toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6));

┌─toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6))─┐
│                                                       456789 │
└──────────────────────────────────────────────────────────────┘

Introduzido em: v24.2.0

Retorna o componente de milissegundos (0–999) de um valor DateTime ou DateTime64.

Sintaxe

toMillisecond(datetime)

Aliases: MILLISECOND

Argumentos

• datetime — Data com hora da qual obter o milissegundo. DateTime ou DateTime64

Valor retornado

Retorna o milissegundo do minuto (0 - 59) em datetime. UInt16

Exemplos

Exemplo de uso

SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));

┌─toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│                                                       456 │
└───────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Retorna o componente de minutos (0-59) de um valor Date ou DateTime.

Sintaxe

toMinute(datetime)

Aliases: MINUTE

Argumentos

• datetime — Data e hora da qual obter o minuto. DateTime ou DateTime64

Valor retornado

Retorna o minuto da hora (0 - 59) de datetime. UInt8

Exemplos

Exemplo de uso

SELECT toMinute(toDateTime('2023-04-21 10:20:30'))

┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│                                          20 │
└─────────────────────────────────────────────┘

Introduzido em: v21.1.0

Converte uma data do calendário gregoriano proléptico em formato de texto YYYY-MM-DD em um número de Dia Juliano Modificado, no tipo Int32. Esta função é compatível com datas de 0000-01-01 a 9999-12-31. Ela gera uma exceção se o argumento não puder ser interpretado como uma data ou se a data for inválida.

Sintaxe

toModifiedJulianDay(date)

Argumentos

• date — A data em formato String. String ou FixedString

Valor retornado

Retorna o número do Dia Juliano Modificado. Int32

Exemplos

Converter data para Dia Juliano Modificado

SELECT toModifiedJulianDay('2020-01-01')

┌─toModifiedJulianDay('2020-01-01')─┐
│                             58849 │
└───────────────────────────────────┘

Introduzido em: v21.1.0

Semelhante a toModifiedJulianDay(), mas, em vez de lançar exceções, retorna NULL.

Sintaxe

toModifiedJulianDayOrNull(date)

Argumentos

• date — Data em formato de texto. String ou FixedString

Valor retornado

Retorna o número do Dia Juliano Modificado para date válido; caso contrário, null. Nullable(Int32)

Exemplos

Converter data para Dia Juliano Modificado com tratamento de null

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- invalid date, returns NULL

┌─toModifiedJulianDayOrNull('2020-01-01')─┐
│                                   58849 │
└─────────────────────────────────────────┘
┌─toModifiedJulianDayOrNull('0000-00-00')─┐
│                                    ᴺᵁᴸᴸ │
└─────────────────────────────────────────┘

Introduzido em: v1.1.0

Arredonda uma data ou uma data com hora para a segunda-feira da mesma semana. Retorna a data.

Sintaxe

toMonday(value)

Argumentos

• value — Data ou data com hora a ser arredondada para a segunda-feira da semana. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna a data da segunda-feira da mesma semana para a data ou data com hora fornecida. Date

Exemplos

Arredonde para a segunda-feira da semana

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- A Friday
toMonday(toDate('2023-04-24'));              -- Already a Monday

┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│                                  2023-04-17 │                     2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘

Introduzido em: v1.1.0

Retorna o mês (1-12) de um valor Date ou DateTime.

Sintaxe

toMonth(datetime)

Aliases: MONTH

Argumentos

• datetime — Data ou data com hora da qual obter o mês. Date ou Date32 ou DateTime ou DateTime64

Valor retornado

Retorna o mês da data/hora fornecida UInt8

Exemplos

Exemplo de uso

SELECT toMonth(toDateTime('2023-04-21 10:20:30'))

┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          4 │
└────────────────────────────────────────────┘

Introduzido em: v25.3.0

Retorna a quantidade de meses decorridos desde 1970

Sintaxe

toMonthNumSinceEpoch(date)

Argumentos

• date — Uma data ou data e hora. Date ou DateTime ou DateTime64

Valor retornado

Inteiro positivo

Exemplos

Exemplo

SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))

657

Introduzido em: v25.7.0

Retorna o componente de nanossegundos (0-999999999) de um valor DateTime64.

Sintaxe

toNanosecond(datetime)

Aliases: NANOSECOND

Argumentos

• datetime — Data e hora da qual extrair o nanossegundo. DateTime64

Valor retornado

Retorna o nanossegundo do segundo (0 - 999999999) de datetime. UInt32

Exemplos

Exemplo de uso

SELECT toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9));

┌─toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9))─┐
│                                                      123456789 │
└────────────────────────────────────────────────────────────────┘

Introduzido em: v1.1.0

Retorna o trimestre do ano (1 a 4) de um determinado valor Date ou DateTime.

Sintaxe