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 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘

Para manter a compatibilidade com o padrão SQL, as seguintes funções, NOW, CURRENT_TIMESTAMP, LOCALTIME, LOCALTIMESTAMP, TODAY e CURRENT_DATE, podem ser usadas sem parênteses.

UTCTimestamp

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

Query

SELECT UTCTimestamp()

Response

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

YYYYMMDDToDate

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

Query

SELECT YYYYMMDDToDate(20230911);

Response

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

YYYYMMDDToDate32

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

Query

SELECT YYYYMMDDToDate32(20000507);

Response

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

YYYYMMDDhhmmssToDateTime

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

Query

SELECT YYYYMMDDToDateTime(20230911131415);

Response

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

YYYYMMDDhhmmssToDateTime64

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

Query

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

Response

┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│  2023-09-11 13:14:15.000 │
└──────────────────────────┘

addDate

Introduzido em: v23.9.0 Adiciona o intervalo de tempo à data, à data e hora ou à data ou data e hora codificadas como string fornecidas. 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

Query

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

Response

┌─addDate(toDa⋯valYear(3))─┐
│               2021-01-01 │
└──────────────────────────┘

addDays

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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯valDay(10))─┐
│               1998-06-26 │
└──────────────────────────┘

addHours

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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯alHour(10))─┐
│      1998-06-16 10:00:00 │
└──────────────────────────┘

addInterval

Introduzido em: v22.11.0 Adiciona um intervalo a outro intervalo ou a uma tupla de intervalos.

Intervalos do mesmo tipo serão combinados em um único intervalo. Por exemplo, se toIntervalDay(1) e toIntervalDay(2) forem passados, o resultado será (3) em vez de (1,1).

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

Query

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)

Response

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

addMicroseconds

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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘

addMilliseconds

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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯second(10))─┐
│  1998-06-16 00:00:00.010 │
└──────────────────────────┘

addMinutes

Introduzido em: v1.1.0 Adiciona um número especificado de minutos a uma data, uma data e hora ou uma data codificada como string, com ou sem hora. 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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯Minute(10))─┐
│      1998-06-16 00:10:00 │
└──────────────────────────┘

addMonths

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, representada 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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯lMonth(10))─┐
│               1999-04-16 │
└──────────────────────────┘

addNanoseconds

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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘

addQuarters

Introduzido em: v20.1.0 Adiciona um número especificado de trimestres a uma data, uma data e hora ou uma data, ou data com hora, codificada em 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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯uarter(10))─┐
│               2000-12-16 │
└──────────────────────────┘

addSeconds

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 com 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

Query

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

Response

┌─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

Query

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

Response

┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│                             1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘

addTupleOfIntervals

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

Query

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

Response

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

addWeeks

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 representada 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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯alWeek(10))─┐
│               1998-08-25 │
└──────────────────────────┘

addYears

Introduzido em: v1.1.0 Adiciona um número especificado de anos a uma data, uma data e hora ou uma data, ou data com hora, codificada em string. Sintaxe

addYears(datetime, num)

Argumentos

datetime — Data ou data com horário à 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

Query

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

Response

┌─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

Query

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

Response

┌─plus(CAST('1⋯alYear(10))─┐
│               2008-06-16 │
└──────────────────────────┘

age

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.

Unidade	Valores possíveis
nanosecond	`nanosecond`, `nanoseconds`, `ns`
microsecond	`microsecond`, `microseconds`, `us`, `u`
millisecond	`millisecond`, `milliseconds`, `ms`
second	`second`, `seconds`, `ss`, `s`
minute	`minute`, `minutes`, `mi`, `n`
hour	`hour`, `hours`, `hh`, `h`
day	`day`, `days`, `dd`, `d`
week	`week`, `weeks`, `wk`, `ww`
month	`month`, `months`, `mm`, `m`
quarter	`quarter`, `quarters`, `qq`, `q`
year	`year`, `years`, `yyyy`, `yy`

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

Query

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

Response

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

Calcular a idade em diferentes unidades

Query

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

Response

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

changeDay

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

Query

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

Response

2024-01-15 00:00:00

changeHour

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

Query

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

Response

2024-01-01 05:00:00

changeMinute

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

Query

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

Response

2024-01-01 12:45:00

changeMonth

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

Query

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

Response

2024-12-01 00:00:00

changeSecond

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

Query

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

Response

2024-01-01 12:30:15

changeYear

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

Query

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

Response

2023-01-01 00:00:00

dateDiff

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.

Unidade	Valores possíveis
nanossegundo	`nanosecond`, `nanoseconds`, `ns`
microssegundo	`microsecond`, `microseconds`, `us`, `u`
milissegundo	`millisecond`, `milliseconds`, `ms`
segundo	`second`, `seconds`, `ss`, `s`
minuto	`minute`, `minutes`, `mi`, `n`
hora	`hour`, `hours`, `hh`, `h`
dia	`day`, `days`, `dd`, `d`
semana	`week`, `weeks`, `wk`, `ww`
mês	`month`, `months`, `mm`, `m`
trimestre	`quarter`, `quarters`, `qq`, `q`
ano	`year`, `years`, `yyyy`, `yy`

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

Query

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

Response

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

Calcular a diferença entre datas em unidades diferentes

Query

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

Response

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

dateName

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

Query

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

Response

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

dateTrunc

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.

Argumento `unit`	Argumento `datetime`	Tipo de retorno
Year, Quarter, Month, Week	`Date32` ou `DateTime64` ou `Date` ou `DateTime`	`Date32` ou `Date`
Day, Hour, Minute, Second	`Date32`, `DateTime64`, `Date` ou `DateTime`	`DateTime64` ou `DateTime`
Millisecond, Microsecond,	Qualquer	`DateTime64`
Nanosecond		com escala 3, 6 ou 9

Exemplos Truncar sem fuso horário

Query

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

Response

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

Truncamento com fuso horário especificado

Query

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

Response

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

formatDateTime

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:

Placeholder	Description	Example
%a	nome abreviado do dia da semana (Mon-Sun)	Mon
%b	nome abreviado do mês (Jan-Dec)	Jan
%c	mês como número inteiro (01-12)	01
%C	ano dividido por 100 e truncado para inteiro (00-99)	20
%d	dia do mês, preenchido com zero à esquerda (01-31)	02
%D	data curta no formato MM/DD/YY, equivalente a %m/%d/%y	01/02/18
%e	dia do mês, preenchido com espaço (1-31)	2
%f	segundos fracionários	123456
%F	data curta no formato YYYY-MM-DD, equivalente a %Y-%m-%d	2018-01-02
%g	formato de ano com dois dígitos, alinhado ao ISO 8601	18
%G	formato de ano com quatro dígitos para o número da semana ISO	2018
%h	hora no formato de 12 horas (01-12)	09
%H	hora no formato de 24 horas (00-23)	22
%i	minuto (00-59)	33
%I	hora no formato de 12 horas (01-12)	10
%j	dia do ano (001-366)	002
%k	hora no formato de 24 horas (00-23)	14
%l	hora no formato de 12 horas (01-12)	09
%m	mês como número inteiro (01-12)	01
%M	nome completo do mês (January-December)	January
%n	caractere de nova linha
%p	indicador AM ou PM	PM
%Q	trimestre (1-4)	1
%r	hora no formato HH:MM AM/PM de 12 horas, equivalente a %h:%i %p	10:30 PM
%R	hora no formato HH:MM de 24 horas, equivalente a %H:%i	22:33
%s	segundo (00-59)	44
%S	segundo (00-59)	44
%t	caractere de tabulação horizontal
%T	formato de hora ISO 8601 (HH:MM:SS), equivalente a %H:%i:%S	22:33:44
%u	dia da semana ISO 8601 como número, com segunda-feira como 1 (1-7)	2
%V	número da semana ISO 8601 (01-53)	01
%w	dia da semana como número inteiro, com domingo como 0 (0-6)	2
%W	nome completo do dia da semana (Monday-Sunday)	Monday
%y	ano, dois últimos dígitos (00-99)	18
%Y	ano	2018
%z	deslocamento em relação ao UTC como +HHMM ou -HHMM	-0500
%%	um sinal de %	%

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

Query

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

Response

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

Formatar DateTime64 com frações de segundo

Query

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

Response

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

Formato com fuso horário

Query

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

Response

┌──────────────────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    │
└─────────────────────┴───────────────────┴─────────────┘

formatDateTimeInJodaSyntax

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:

Marcador	Descrição	Apresentação	Exemplos
G	era	texto	AD
C	século da era (>=0)	número	20
Y	ano da era (>=0)	ano	1996
x	ano da semana (ainda sem suporte)	ano	1996
w	semana do ano da semana (ainda sem suporte)	número	27
e	dia da semana	número	2
E	dia da semana	texto	Tuesday; Tue
y	ano	ano	1996
D	dia do ano	número	189
M	mês do ano	mês	July; Jul; 07
d	dia do mês	número	10
a	período do dia	texto	PM
K	hora no período do dia (0~11)	número	0
h	hora do relógio no período do dia (1~12)	número	12
H	hora do dia (0~23)	número	0
k	hora do relógio do dia (1~24)	número	24
m	minuto da hora	número	30
s	segundo do minuto	número	55
S	fração de segundo	número	978
z	fuso horário	texto	Eastern Standard Time; EST
Z	deslocamento do fuso horário	zona	-0800; -0812
’	escape de texto	delimitador
”	aspa simples	literal	’

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

Query

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

Response

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

fromDaysSinceYearZero

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

Query

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

Response

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

fromDaysSinceYearZero32

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

Query

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

Response

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

fromModifiedJulianDay

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

Query

SELECT fromModifiedJulianDay(58849)

Response

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

fromModifiedJulianDayOrNull

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

Query

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- argumento inválido, retorna NULL

Response

┌─fromModified⋯Null(58849)─┐
│ 2020-01-01               │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ                     │
└──────────────────────────┘

fromUTCTimestamp

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

Query

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

Response

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

fromUnixTimestamp

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

Query

SELECT fromUnixTimestamp(423543535)

Response

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

Converta o timestamp Unix com formato

Query

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

Response

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

fromUnixTimestampInJodaSyntax

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

Query

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

Response

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

localtime

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

Query

SELECT LOCALTIME

Response

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

makeDate

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

Query

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

Response

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

Data a partir do ano e do dia do ano

Query

SELECT makeDate(2023, 42) AS date;

Response

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

makeDate32

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

Query

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

Response

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

Date32 com base no ano e no dia do ano

Query

SELECT makeDate(2023, 42) AS date;

Response

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

makeDateTime

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

Query

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

Response

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

makeDateTime64

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

Query

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

Response

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

monthName

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

Query

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

Response

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

now

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

Query

SELECT now()

Response

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

Consulta com fuso horário especificado

Query

SELECT now('Asia/Istanbul')

Response

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

Sintaxe SQL padrão sem parênteses

Query

SELECT NOW, CURRENT_TIMESTAMP

Response

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

now64

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

Query

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

Response

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

nowInBlock

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()

Query

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

Response

┌───────────────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 │
└─────────────────────┴─────────────────────┴──────────┘

nowInBlock64

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()

Query

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

Response

┌─────────────────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 │
└─────────────────────────┴─────────────────────────┴──────────┘

serverTimezone

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

Query

SELECT serverTimeZone()

Response

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

subDate

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

Query

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

Response

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

subtractDays

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯valDay(10))─┐
│               1998-06-06 │
└──────────────────────────┘

subtractHours

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯alHour(10))─┐
│      1998-06-15 14:00:00 │
└──────────────────────────┘

subtractInterval

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

Query

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);

Response

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

subtractMicroseconds

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘

subtractMilliseconds

Introduzido na versão: v22.6.0 Subtrai um número especificado de milissegundos de uma data com hora ou de uma data com hora representada 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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯second(10))─┐
│  1998-06-15 23:59:59.990 │
└──────────────────────────┘

subtractMinutes

Introduzido em: v1.1.0 Subtrai um número especificado de minutos de uma data, de uma data com hora ou de uma data ou data com 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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯Minute(10))─┐
│      1998-06-15 23:50:00 │
└──────────────────────────┘

subtractMonths

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯lMonth(10))─┐
│               1997-08-16 │
└──────────────────────────┘

subtractNanoseconds

Introduzido na versão: v20.1.0 Subtrai um número especificado de nanossegundos de uma data com hora ou de uma data com hora representada 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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘

subtractQuarters

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 em 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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('1⋯Quarter(10))─┐
│                1996-09-16 │
└───────────────────────────┘

subtractSeconds

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯Second(10))─┐
│      1998-06-15 23:59:50 │
└──────────────────────────┘

subtractTupleOfIntervals

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

Query

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

Response

┌─subtractTupl⋯alYear(1)))─┐
│               2016-12-31 │
└──────────────────────────┘

subtractWeeks

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯alWeek(10))─┐
│               1998-04-07 │
└──────────────────────────┘

subtractYears

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

Query

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

Response

┌─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

Query

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

Response

┌─minus(CAST('⋯alYear(10))─┐
│               1988-06-16 │
└──────────────────────────┘

timeDiff

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

Query

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

Response

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

Calcular a diferença de tempo e converter em horas

Query

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

Response

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

Equivalente a dateDiff em segundos

Query

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

Response

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

timeSlot

Introduzido em: v1.1.0 Arredonda a hora para o início de um intervalo de meia hora.

Embora esta função possa receber como argumento valores dos tipos estendidos Date32 e DateTime64, passá-la uma data/hora fora do intervalo normal (anos de 1970 a 2149 para Date / 2106 para DateTime) produzirá resultados incorretos.

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

Query

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

Response

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

timeSlots

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

Query

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))

Response

┌─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']                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

timestamp

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)

Query

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

Response

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

Adicionar horário à string de data

Query

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

Response

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

timezone

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

Query

SELECT timezone()

Response

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

timezoneOf

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

Query

SELECT timezoneOf(now());

Response

┌─timezoneOf(now())─┐
│ Europe/Amsterdam  │
└───────────────────┘

timezoneOffset

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

Query

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;

Response

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

toDayOfMonth

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

Query

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

Response

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

toDayOfWeek

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.

Modo	Primeiro dia da semana	Intervalo
0	Segunda-feira	1-7: segunda-feira = 1, terça-feira = 2, …, domingo = 7
1	Segunda-feira	0-6: segunda-feira = 0, terça-feira = 1, …, domingo = 6
2	Domingo	0-6: domingo = 0, segunda-feira = 1, …, sábado = 6
3	Domingo	1-7: domingo = 1, segunda-feira = 2, …, sábado = 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

Query

-- 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)

Response

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

toDayOfYear

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

Query

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

Response

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

toDaysInMonth

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

Query

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

Response

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

toDaysSinceYearZero

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

Query

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

Response

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

toHour

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

Query

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

Response

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

toISOWeek

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

Query

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

Response

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

A semana ISO pode pertencer a um ano diferente

Query

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

Response

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

toISOYear

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

Query

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

Response

┌─week1─┬─week2─┐
│    40 │    40 │
└───────┴───────┘

toLastDayOfMonth

Introduzido na versão: v1.1.0 Arredonda uma data ou data com hora para o último dia do mês.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

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

Query

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

Response

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

toLastDayOfWeek

Introduzido em: v23.5.0 Arredonda uma data ou data com hora para cima até o sábado ou domingo mais próximo.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

Sintaxe

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

Argumentos

datetime — Uma data ou data com 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

Query

SELECT
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* uma sexta-feira */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* uma sexta-feira */
    toLastDayOfWeek(toDate('2023-04-23')), /* um domingo */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* um domingo */
FORMAT Vertical

Response

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

toMicrosecond

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

Query

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

Response

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

toMillisecond

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 e 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

Query

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

Response

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

toMinute

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

Query

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

Response

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

toModifiedJulianDay

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

Query

SELECT toModifiedJulianDay('2020-01-01')

Response

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

toModifiedJulianDayOrNull

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

Query

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- data inválida, retorna NULL

Response

┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

toMonday

Introduzido em: v1.1.0 Arredonda uma data ou uma data com hora para a segunda-feira da mesma semana. Retorna a data.

O tipo de retorno pode ser configurado pela definição de enable_extended_results_for_datetime_functions.

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

Query

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Uma sexta-feira
toMonday(toDate('2023-04-24'));              -- Já é uma segunda-feira

Response

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

toMonth

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

Query

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

Response

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

toMonthNumSinceEpoch

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

Query

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

Response

toNanosecond

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

Query

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

Response

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

toQuarter

Introduzido em: v1.1.0 Retorna o trimestre do ano (1 a 4) de um determinado valor Date ou DateTime. Sintaxe

toQuarter(datetime)

Aliases: QUARTER Argumentos

datetime — Data ou data com horário da qual obter o trimestre do ano. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o trimestre do ano da data/hora fornecida UInt8 Exemplos Exemplo de uso

Query

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

Response

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

toRelativeDayNum

Introduzido na versão: v1.1.0 Converte uma data ou uma data com hora no número de dias decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada isoladamente. O principal objetivo da função é calcular a diferença em dias entre duas datas ou duas datas com hora, por exemplo, toRelativeDayNum(dt1) - toRelativeDayNum(dt2). Sintaxe

toRelativeDayNum(date)

Argumentos

date — Data ou data com hora. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de dias desde um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos de dias

Query

SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))

Response

┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

toRelativeHourNum

Introduzido em: v1.1.0 Converte uma data ou data com hora em um número de horas decorridas desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada isoladamente. O principal objetivo da função é calcular a diferença em horas entre duas datas ou datas com hora, por exemplo, toRelativeHourNum(dt1) - toRelativeHourNum(dt2). Sintaxe

toRelativeHourNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de horas a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos de hora

Query

SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference

Response

┌─hours_difference─┐
│               12 │
└──────────────────┘

toRelativeMinuteNum

Introduzido em: v1.1.0 Converte uma data ou uma data com hora em um número de minutos decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada de forma independente. O principal objetivo da função é calcular a diferença em minutos entre duas datas ou datas com hora, por exemplo, toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2). Sintaxe

toRelativeMinuteNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de minutos a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos de minutos

Query

SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference

Response

┌─minutes_difference─┐
│                 30 │
└────────────────────┘

toRelativeMonthNum

Introduzido em: v1.1.0 Converte uma data ou data com hora em um número de meses decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não foi projetada para ser usada de forma isolada. O principal objetivo da função é calcular a diferença em meses entre duas datas ou datas com hora, por exemplo, toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2). Sintaxe

toRelativeMonthNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de meses a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos do mês

Query

SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference

Response

┌─months_difference─┐
│                 3 │
└───────────────────┘

toRelativeQuarterNum

Introduzido em: v1.1.0 Converte uma data ou data e hora no número de trimestres decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada isoladamente. O principal objetivo da função é calcular a diferença em trimestres entre duas datas ou valores de data e hora, por exemplo, toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2). Sintaxe

toRelativeQuarterNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de trimestres a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos de trimestre

Query

SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference

Response

┌─quarters_difference─┐
│                   1 │
└─────────────────────┘

toRelativeSecondNum

Introduzido na versão: v1.1.0 Converte uma data ou data com hora em um número de segundos decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada de forma independente. O principal objetivo da função é calcular a diferença em segundos entre duas datas ou datas com hora, por exemplo, toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2). Sintaxe

toRelativeSecondNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de segundos a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números relativos de segundos

Query

SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference

Response

┌─seconds_difference─┐
│                 60 │
└────────────────────┘

toRelativeWeekNum

Introduzido em: v1.1.0 Converte uma data ou data e hora em um número de semanas decorridas desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não se destina ao uso independente. O principal objetivo da função é calcular a diferença em semanas entre duas datas ou valores de data e hora, por exemplo, toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2). Sintaxe

toRelativeWeekNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de semanas a partir de um ponto de referência fixo no passado. UInt32 Exemplos Obter números de semana relativos

Query

SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference

Response

┌─weeks_difference─┐
│                1 │
└──────────────────┘

toRelativeYearNum

Introduzido na versão: v1.1.0 Converte uma data ou data com hora em um número de anos decorridos desde um determinado ponto fixo no passado. O ponto exato no tempo é um detalhe de implementação e, portanto, esta função não deve ser usada de forma independente. O principal objetivo da função é calcular a diferença em anos entre duas datas ou datas com hora, por exemplo, toRelativeYearNum(dt1) - toRelativeYearNum(dt2). Sintaxe

toRelativeYearNum(date)

Argumentos

date — Data ou data com horário. Date ou DateTime ou DateTime64

Valor retornado Retorna o número de anos a partir de um ponto de referência fixo no passado. UInt16 Exemplos Obter números relativos do ano

Query

SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)

Response

┌─minus(toRela⋯ateTime')))─┐
│                       10 │
└──────────────────────────┘

toSecond

Introduzido em: v1.1.0 Retorna o componente de segundos (0-59) de um valor DateTime ou DateTime64. Sintaxe

toSecond(datetime)

Aliases: SECOND Argumentos

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

Valor retornado Retorna o segundo do minuto (0 - 59) de datetime. UInt8 Exemplos Exemplo de uso

Query

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

Response

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

toStartOfDay

Introduzido em: v1.1.0 Arredonda para baixo uma data e hora até o início do dia.

O tipo de retorno pode ser configurado por meio da configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfDay(datetime)

Argumentos

datetime — Uma data ou data com hora para arredondar. Date ou DateTime

Valor retornado Retorna a data com hora arredondada para baixo até o início do dia. DateTime ou DateTime64 Exemplos Arredondar para baixo até o início do dia

Query

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

Response

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

toStartOfFifteenMinutes

Introduzido em: v1.1.0 Arredonda a data com hora para baixo até o início do intervalo de quinze minutos.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfFifteenMinutes(datetime)

Argumentos

datetime — Uma data ou data e hora para arredondar. DateTime ou DateTime64

Valor retornado Retorna a data e hora arredondada para o início do intervalo de quinze minutos mais próximo. DateTime ou DateTime64 Exemplos Exemplo

Query

SELECT
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Response

Linha 1:
──────
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:15:00

toStartOfFiveMinutes

Introduzido em: v22.6.0 Arredonda uma data com hora para baixo até o início do intervalo de cinco minutos mais próximo.

O tipo de retorno pode ser configurado definindo enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfFiveMinutes(datetime)

Aliases: toStartOfFiveMinute Argumentos

datetime — Uma data e hora para arredondar. DateTime ou DateTime64

Valor retornado Retorna a data e hora arredondada para o início do intervalo de cinco minutos mais próximo. DateTime ou DateTime64 Exemplos Exemplo

Query

SELECT
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Response

Linha 1:
──────
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfHour

Introduzido em: v1.1.0 Arredonda uma data com hora para baixo até o início da hora.

O tipo de retorno pode ser configurado por meio da definição de enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfHour(datetime)

Argumentos

datetime — Uma data com hora a ser arredondada. DateTime ou DateTime64

Valor retornado Retorna a data com hora arredondada para baixo para o início da hora. DateTime ou DateTime64 Exemplos Arredondar para baixo para o início da hora

Query

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

Response

┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime        │
└─────────────────────┴─────────────────┘

toStartOfISOYear

Introduzido em: v1.1.0 Arredonda uma data ou data com hora para o primeiro dia do ano ISO, que pode ser diferente do ano civil. Veja ISO week date.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfISOYear(value)

Argumentos

value — A data ou data com hora a ser arredondada para o primeiro dia do ano ISO. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o primeiro dia do ano ISO para a data ou data com hora informada. Date Exemplos Arredondar para o primeiro dia do ano ISO

Query

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

Response

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

toStartOfInterval

Introduzido em: v20.1.0 Esta função generaliza outras funções toStartOf*() usando a sintaxe toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone]). Por exemplo,

toStartOfInterval(t, INTERVAL 1 YEAR) retorna o mesmo que toStartOfYear(t),
toStartOfInterval(t, INTERVAL 1 MONTH) retorna o mesmo que toStartOfMonth(t),
toStartOfInterval(t, INTERVAL 1 DAY) retorna o mesmo que toStartOfDay(t),
toStartOfInterval(t, INTERVAL 15 MINUTE) retorna o mesmo que toStartOfFifteenMinutes(t).

O cálculo é feito em relação a pontos específicos no tempo:

Intervalo	Início
YEAR	ano 0
QUARTER	1900 Q1
MONTH	janeiro de 1900
WEEK	1970, 1ª semana (01-05)
DAY	1970-01-01
HOUR	(*)
MINUTE	1970-01-01 00:00:00
SECOND	1970-01-01 00:00:00
MILLISECOND	1970-01-01 00:00:00
MICROSECOND	1970-01-01 00:00:00
NANOSECOND	1970-01-01 00:00:00
(*) os intervalos de hora são especiais: o cálculo é sempre feito em relação a 00:00:00 (meia-noite) do dia atual. Como resultado, apenas
valores de hora entre 1 e 23 são úteis.

Se a unidade WEEK for especificada, toStartOfInterval assume que as semanas começam na segunda-feira. Observe que esse comportamento é diferente do da função toStartOfWeek, na qual as semanas começam por padrão no domingo. A segunda sobrecarga emula a função time_bucket() do TimescaleDB e a função date_bin() do PostgreSQL, respectivamente. Sintaxe

toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])

Aliases: time_bucket, date_bin Argumentos

value — Valor de data ou data/hora a ser arredondado para baixo. Date ou DateTime ou DateTime64
x — Número que representa o comprimento do intervalo. - unit — Unidade do intervalo: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND. - time_zone — Opcional. Nome do fuso horário como string. - origin — Opcional. Ponto de origem para o cálculo (apenas na segunda sobrecarga).

Valor retornado Retorna o início do intervalo que contém o valor informado. DateTime Exemplos Arredondamento básico de intervalos

Query

SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)

Response

┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘

Usando o ponto de origem

Query

SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))

Response

┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

toStartOfMicrosecond

Introduzido em: v22.6.0 Arredonda para baixo uma data com hora até o início do microssegundo. Sintaxe

toStartOfMicrosecond(datetime[, timezone])

Argumentos

datetime — Data e hora. DateTime64
timezone — Opcional. Fuso horário do valor retornado. Se não for especificado, a função usa o fuso horário do parâmetro value. String

Valor retornado Valor de entrada com submicrossegundos DateTime64 Exemplos Consulta sem fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);

Response

┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘

Consulta com fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');

Response

┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

toStartOfMillisecond

Introduzido em: v22.6.0 Arredonda para baixo uma data com hora até o início do milissegundo. Sintaxe

toStartOfMillisecond(datetime[, timezone])

Argumentos

datetime — Data e hora. DateTime64
timezone — Opcional. Fuso horário do valor retornado. Se não for especificado, a função usa o fuso horário do parâmetro value. String

Valor retornado Valor de entrada com frações de milissegundo. DateTime64 Exemplos Consulta sem fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);

Response

┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘

Consulta com fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');

Response

┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

toStartOfMinute

Introduzido em: v1.1.0 Arredonda uma data com hora para o início do minuto.

O tipo de retorno pode ser configurado com a definição de enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfMinute(datetime)

Argumentos

datetime — Uma data com hora a ser arredondada. DateTime ou DateTime64

Valor retornado Retorna a data com hora arredondada para baixo, até o início do minuto. DateTime ou DateTime64 Exemplos Arredondar para baixo até o início do minuto

Query

SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical

Response

Linha 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')):           2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00

toStartOfMonth

Introduzido em: v1.1.0 Arredonda uma data ou data com hora para baixo, até o primeiro dia do mês.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfMonth(value)

Argumentos

value — A data ou data com hora a ser arredondada para baixo para o primeiro dia do mês. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o primeiro dia do mês para a data ou data com hora fornecida. Date Exemplos Arredondar para baixo para o primeiro dia do mês

Query

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

Response

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

toStartOfNanosecond

Introduzido em: v22.6.0 Arredonda para baixo uma data e hora para o início do nanossegundo. Sintaxe

toStartOfNanosecond(datetime[, timezone])

Argumentos

datetime — Data e hora. DateTime64
timezone — Opcional. Fuso horário do valor retornado. Se não for especificado, a função usa o fuso horário do parâmetro value. String

Valor retornado Valor de entrada com precisão de nanossegundos. DateTime64 Exemplos Consulta sem fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);

Response

┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘

Consulta com fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');

Response

┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│              2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘

toStartOfQuarter

Introduzido em: v1.1.0 Arredonda uma data ou data com hora para o primeiro dia do trimestre. O primeiro dia do trimestre é 1º de janeiro, 1º de abril, 1º de julho ou 1º de outubro.

O tipo de retorno pode ser configurado por meio da configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfQuarter(value)

Argumentos

value — A data ou data com hora a ser arredondada para baixo até o primeiro dia do trimestre. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o primeiro dia do trimestre da data ou data com hora fornecida. Date Exemplos Arredondar para baixo até o primeiro dia do trimestre

Query

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

Response

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

toStartOfSecond

Introduzido em: v20.5.0 Arredonda para baixo uma data com hora até o início do segundo. Sintaxe

toStartOfSecond(datetime[, timezone])

Argumentos

datetime — Data e hora das quais remover as frações de segundo. DateTime64
timezone — Opcional. Fuso horário do valor retornado. Se não for especificado, a função usa o fuso horário do parâmetro value. String

Valor retornado Retorna o valor de entrada sem frações de segundo. DateTime64 Exemplos Consulta sem fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);

Response

┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘

Consulta com fuso horário

Query

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');

Response

┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

toStartOfTenMinutes

Introduzido em: v20.1.0 Arredonda uma data com hora para baixo até o início do intervalo de dez minutos mais próximo.

O tipo de retorno pode ser configurado pela configuração enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfTenMinutes(datetime)

Argumentos

datetime — Uma data e hora. DateTime ou DateTime64

Valor retornado Retorna a data e hora arredondada para o início do intervalo de dez minutos mais próximo. DateTime ou DateTime64 Exemplos Exemplo

Query

SELECT
    toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Response

linha 1:
──────
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:10:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfWeek

Introduzido na versão: v20.1.0 Arredonda uma data ou data com hora para o domingo ou a segunda-feira anteriores mais próximos.

O tipo de retorno pode ser configurado com a definição de enable_extended_results_for_datetime_functions.

Sintaxe

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

Argumentos

datetime — Uma data ou data com hora a ser convertida. 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 — O fuso horário a ser usado na conversão. Se não for especificado, será usado o fuso horário do servidor. String

Valor retornado Retorna a data do domingo ou da segunda-feira mais próximos, na data informada ou antes dela, dependendo do modo. Date ou Date32 Exemplos Arredondar para baixo para o domingo ou a segunda-feira mais próximos

Query

SELECT
        toStartOfWeek(toDateTime('2023-04-21 10:20:30')), /* uma sexta-feira */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* uma sexta-feira */
        toStartOfWeek(toDate('2023-04-24')), /* uma segunda-feira */
        toStartOfWeek(toDate('2023-04-24'), 1) /* uma segunda-feira */
    FORMAT Vertical

Response

Linha 1:
    ──────
    toStartOfWeek(toDateTime('2023-04-21 10:20:30')):      2023-04-17
    toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1):   2023-04-17
    toStartOfWeek(toDate('2023-04-24')):                   2023-04-24
    toStartOfWeek(toDate('2023-04-24'), 1):                2023-04-24

toStartOfYear

Introduzido na versão: v1.1.0 Arredonda uma data ou data com hora para o primeiro dia do ano. Retorna a data como um objeto Date.

O tipo de retorno pode ser configurado pela definição de enable_extended_results_for_datetime_functions.

Sintaxe

toStartOfYear(value)

Argumentos

value — A data ou data com hora a ser arredondada para baixo. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o primeiro dia do ano da data/hora fornecida Date Exemplos Arredondar para baixo para o primeiro dia do ano

Query

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

Response

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

toTimeWithFixedDate

Introduzido em: v1.1.0 Extrai o componente de hora de uma data ou data com hora. O resultado retornado é um deslocamento em relação a um ponto fixo no tempo, atualmente 1970-01-02, mas o ponto exato no tempo é um detalhe de implementação que pode mudar no futuro. Portanto, toTime não deve ser usado isoladamente. O principal objetivo da função é calcular a diferença de tempo entre duas datas ou datas com hora, por exemplo, toTime(dt1) - toTime(dt2). Sintaxe

toTimeWithFixedDate(date[, timezone])

Argumentos

date — Data a ser convertida em hora. Date ou DateTime ou DateTime64
timezone — Opcional. Fuso horário do valor retornado. String

Valor retornado Retorna o componente de hora de uma data ou de uma data com hora na forma de um deslocamento em relação a um ponto fixo no tempo (atualmente, 1970-01-02). DateTime Exemplos Calcular a diferença de tempo entre duas datas

Query

SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)

Response

┌─result─┬─toTypeName(result)─┐
│   3600 │ Int32              │
└────────┴────────────────────┘

toTimezone

Introduzido em: v1.1.0 Converte um DateTime ou DateTime64 para o fuso horário especificado. O valor interno (número de segundos Unix) do dado não muda. Apenas o atributo de fuso horário do valor e sua representação textual mudam. Sintaxe

toTimezone(datetime, timezone)

Aliases: toTimeZone Argumentos

date — O valor a ser convertido. DateTime ou DateTime64
timezone — O nome do fuso horário de destino. String

Valor retornado Retorna o mesmo timestamp de entrada, mas com o fuso horário especificado DateTime ou DateTime64 Exemplos Exemplo de uso

Query

SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
toTypeName(time_utc) AS type_utc,
toInt32(time_utc) AS int32utc,
toTimezone(time_utc, 'Asia/Yekaterinburg') AS time_yekat,
toTypeName(time_yekat) AS type_yekat,
toInt32(time_yekat) AS int32yekat,
toTimezone(time_utc, 'US/Samoa') AS time_samoa,
toTypeName(time_samoa) AS type_samoa,
toInt32(time_samoa) AS int32samoa
FORMAT Vertical;

Response

Linha 1:
──────
time_utc:   2019-01-01 00:00:00
type_utc:   DateTime('UTC')
int32utc:   1546300800
time_yekat: 2019-01-01 05:00:00
type_yekat: DateTime('Asia/Yekaterinburg')
int32yekat: 1546300800
time_samoa: 2018-12-31 13:00:00
type_samoa: DateTime('US/Samoa')
int32samoa: 1546300800

toUTCTimestamp

Introduzido na versão: v23.8.0 Converte um valor de data ou data com hora de um fuso horário para um timestamp em UTC. Esta função é incluída principalmente para compatibilidade com o Apache Spark e frameworks semelhantes. Sintaxe

toUTCTimestamp(datetime, time_zone)

Aliases: to_utc_timestamp Argumentos

datetime — Um valor constante do tipo 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 uma data ou data com hora no fuso horário UTC. DateTime ou DateTime64 Exemplos Converter o fuso horário para UTC

Query

SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')

Response

┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│                                     2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘

toUnixTimestamp

Introduzido na versão: v1.1.0 Converte uma String, Date ou DateTime em um timestamp Unix (segundos desde 1970-01-01 00:00:00 UTC) para UInt32. Sintaxe

toUnixTimestamp(date[, timezone])

Argumentos

date — Valor a ser convertido. Date ou Date32 ou DateTime ou DateTime64 ou String
timezone — Opcional. 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 o timestamp Unix. UInt32 Exemplos Exemplo de uso

Query

SELECT
'2017-11-05 08:07:47' AS dt_str,
toUnixTimestamp(dt_str) AS from_str,
toUnixTimestamp(dt_str, 'Asia/Tokyo') AS from_str_tokyo,
toUnixTimestamp(toDateTime(dt_str)) AS from_datetime,
toUnixTimestamp(toDateTime64(dt_str, 0)) AS from_datetime64,
toUnixTimestamp(toDate(dt_str)) AS from_date,
toUnixTimestamp(toDate32(dt_str)) AS from_date32
FORMAT Vertical;

Response

Linha 1:
──────
dt_str:          2017-11-05 08:07:47
from_str:        1509869267
from_str_tokyo:  1509836867
from_datetime:   1509869267
from_datetime64: 1509869267
from_date:       1509840000
from_date32:     1509840000

toWeek

Introduzido em: v20.1.0 Esta função retorna o número da semana para uma data ou datetime. A forma com dois argumentos de toWeek() permite especificar se a semana começa no domingo ou na segunda-feira e se o valor retornado deve ficar no intervalo de 0 a 53 ou de 1 a 53. toISOWeek() é uma função de compatibilidade equivalente a toWeek(date,3). A tabela a seguir descreve como o argumento mode funciona.

Mode	Primeiro dia da semana	Intervalo	A semana 1 é a primeira semana …
0	Domingo	0-53	com um domingo neste ano
1	Segunda-feira	0-53	com 4 ou mais dias neste ano
2	Domingo	1-53	com um domingo neste ano
3	Segunda-feira	1-53	com 4 ou mais dias neste ano
4	Domingo	0-53	com 4 ou mais dias neste ano
5	Segunda-feira	0-53	com uma segunda-feira neste ano
6	Domingo	1-53	com 4 ou mais dias neste ano
7	Segunda-feira	1-53	com uma segunda-feira neste ano
8	Domingo	1-53	contém 1º de janeiro
9	Segunda-feira	1-53	contém 1º de janeiro

Para valores de mode com o significado de “com 4 ou mais dias neste ano”, as semanas são numeradas de acordo com a ISO 8601:1988:

Se a semana que contém 1º de janeiro tiver 4 ou mais dias no novo ano, ela será a semana 1.
Caso contrário, será a última semana do ano anterior, e a próxima semana será a semana 1.

Para valores de mode com o significado de “contém 1º de janeiro”, a semana que contém 1º de janeiro é a semana 1. Não importa quantos dias do novo ano a semana contenha, mesmo que contenha apenas um dia. Ou seja, se a última semana de dezembro contiver 1º de janeiro do ano seguinte, ela será a semana 1 do ano seguinte. O primeiro argumento também pode ser especificado como String em um formato compatível com parseDateTime64BestEffort(). O suporte a argumentos string existe apenas por motivos de compatibilidade com o MySQL, como esperado por algumas ferramentas de terceiros. Como o suporte a argumentos string pode, no futuro, passar a depender de novas configurações de compatibilidade com MySQL e como o parsing de strings geralmente é lento, recomenda-se não usá-lo. Sintaxe

toWeek(datetime[, mode[, time_zone]])

Aliases: week Argumentos

datetime — Data ou data com hora da qual obter o número da semana. Date ou DateTime
mode — Opcional. Um modo de 0 a 9 determina o primeiro dia da semana e o intervalo do número da semana. O padrão é 0. - time_zone — Opcional. Fuso horário. String

Valor retornado Retorna o número da semana de acordo com o modo especificado. UInt32 Exemplos Obtenha números de semana com modos diferentes

Query

SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9

Response

┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │    52 │    52 │     1 │
└────────────┴───────┴───────┴───────┘

toYYYYMM

Introduzido em: v1.1.0 Converte uma data ou data e hora em um número UInt32 contendo o ano e o número do mês (YYYY * 100 + MM). Aceita um segundo argumento opcional de fuso horário. Se fornecido, o fuso horário deve ser uma constante de string. Esta função é o oposto da função YYYYMMDDToDate(). Sintaxe

toYYYYMM(datetime[, timezone])

Argumentos

datetime — Uma data ou data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64
timezone — Opcional. Fuso horário para a conversão. Se informado, o fuso horário deve ser uma constante de string. String

Valor retornado Retorna um número UInt32 com o ano e o número do mês (YYYY * 100 + MM). UInt32 Exemplos Converte a data atual para o formato YYYYMM

Query

SELECT toYYYYMM(now(), 'US/Eastern')

Response

┌─toYYYYMM(now(), 'US/Eastern')─┐
│                        202303 │
└───────────────────────────────┘

toYYYYMMDD

Introduzido em: v1.1.0 Converte uma data ou uma data com hora em um número UInt32 que contém o ano, o mês e o dia (YYYY * 10000 + MM * 100 + DD). Aceita um segundo argumento opcional de fuso horário. Se fornecido, o fuso horário deve ser uma constante de string. Sintaxe

toYYYYMMDD(datetime[, timezone])

Argumentos

datetime — Uma data ou uma data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64
timezone — Opcional. Fuso horário para a conversão. Se informado, o fuso horário deve ser uma constante de string. String

Valor retornado Retorna um número UInt32 que contém o ano, o mês e o dia (YYYY * 10000 + MM * 100 + DD). UInt32 Exemplos Converter a data atual para o formato YYYYMMDD

Query

SELECT toYYYYMMDD(now(), 'US/Eastern')

Response

┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│                        20230302 │
└─────────────────────────────────┘

toYYYYMMDDhhmmss

Introduzido em: v1.1.0 Converte uma data ou data com hora em um número UInt64 contendo ano, mês, dia, hora, minuto e segundo (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss). Aceita um segundo argumento opcional de fuso horário. Se fornecido, o fuso horário deve ser uma constante de string. Sintaxe

toYYYYMMDDhhmmss(datetime[, timezone])

Argumentos

datetime — Data ou data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64
timezone — Opcional. Fuso horário da conversão. Se informado, o fuso horário deve ser uma constante de string. String

Valor retornado Retorna um número UInt64 contendo o ano, mês, dia, hora, minuto e segundo (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss). UInt64 Exemplos Converter a data e hora atuais para o formato YYYYMMDDhhmmss

Query

SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')

Response

┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│                        20230302112209 │
└───────────────────────────────────────┘

toYear

Introduzido em: v1.1.0 Retorna o ano (d.C.) de um valor Date ou DateTime. Sintaxe

toYear(datetime)

Aliases: YEAR Argumentos

datetime — Data ou data com hora da qual extrair o ano. Date ou Date32 ou DateTime ou DateTime64

Valor retornado Retorna o ano do valor Date ou DateTime fornecido, como UInt16 Exemplos Exemplo de uso

Query

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

Response

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

toYearNumSinceEpoch

Introduzido em: v25.3.0 Retorna o número de anos decorridos desde 1970 Sintaxe

toYearNumSinceEpoch(date)

Argumentos

date — Uma data ou uma data com hora para converter. Date ou DateTime ou DateTime64

Valor retornado Inteiro positivo Exemplos Exemplo

Query

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

Response

toYearWeek

Introduzido em: v20.1.0 Retorna o ano e a semana de uma data. O ano no resultado pode ser diferente do ano no argumento de data na primeira e na última semana do ano. O argumento mode funciona como o argumento mode de toWeek(). Aviso: O número da semana retornado por toYearWeek() pode ser diferente do que toWeek() retorna. toWeek() sempre retorna o número da semana no contexto do ano informado e, se toWeek() retornar 0, toYearWeek() retornará o valor correspondente à última semana do ano anterior. Veja prev_yearWeek no exemplo abaixo. O primeiro argumento também pode ser especificado como String, em um formato compatível com parseDateTime64BestEffort(). O suporte a argumentos do tipo string existe apenas por motivos de compatibilidade com o MySQL, esperado por certas ferramentas de terceiros. Como esse suporte pode, no futuro, passar a depender de novas configurações de compatibilidade com MySQL e como o parsing de strings geralmente é lento, recomenda-se não usá-lo. Sintaxe

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

Aliases: yearweek Argumentos

datetime — Data ou data com hora da qual obter o ano e a semana. Date ou DateTime
mode — Opcional. Um valor de 0 a 9 determina o primeiro dia da semana e o intervalo do número da semana. O padrão é 0. - timezone — Opcional. Fuso horário. String

Valor retornado Retorna o ano e o número da semana como um único valor inteiro. UInt32 Exemplos Obtenha combinações de ano-semana com diferentes modos

Query

SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9, toYearWeek(toDate('2022-01-01')) AS prev_yearWeek

Response

┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │    201652 │    201652 │    201701 │        202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘

today

Introduzido em: v1.1.0 Retorna a data atual no momento da análise da consulta. O mesmo que toDate(now()). Sintaxe

today()

Aliases: curdate, current_date Argumentos

Nenhum.

Valor retornado Retorna a data atual Date Exemplos Exemplo de uso

Query

SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty

Response

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │   2025-03-03 │
└────────────┴────────────┴──────────────┘

Sintaxe padrão do SQL sem parênteses

Query

SELECT TODAY, CURDATE,CURRENT_DATE

Response

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      TODAY ┃    CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │   2025-03-04 │
└────────────┴────────────┴──────────────┘

yesterday

Introduzido em: v1.1.0 Aceita zero argumentos e retorna a data de ontem em um dos estágios da análise da consulta. Sintaxe

yesterday()

Argumentos

Nenhum.

Valor retornado Retorna a data de ontem. Date Exemplos Obter a data de ontem

Query

SELECT yesterday();
SELECT today() - 1;

Response

┌─yesterday()─┐
│  2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2025-06-09 │
└───────────────────┘

Última modificação em 25 de junho de 2026

DistânciaDocumentação das funções de distância

​UTCTimestamp

​YYYYMMDDToDate

​YYYYMMDDToDate32

​YYYYMMDDhhmmssToDateTime

​YYYYMMDDhhmmssToDateTime64

​addDate

​addDays

​addHours

​addInterval

​addMicroseconds

​addMilliseconds

​addMinutes

​addMonths

​addNanoseconds

​addQuarters

​addSeconds

​addTupleOfIntervals

​addWeeks

​addYears

​age

​changeDay

​changeHour

​changeMinute

​changeMonth

​changeSecond

​changeYear

​dateDiff

​dateName

​dateTrunc

​formatDateTime

​formatDateTimeInJodaSyntax

​fromDaysSinceYearZero

​fromDaysSinceYearZero32

​fromModifiedJulianDay

​fromModifiedJulianDayOrNull

​fromUTCTimestamp

​fromUnixTimestamp

​fromUnixTimestampInJodaSyntax

​localtime

​makeDate

​makeDate32

​makeDateTime

​makeDateTime64

​monthName

​now

​now64

​nowInBlock

​nowInBlock64

​serverTimezone

​subDate

​subtractDays

​subtractHours

​subtractInterval

​subtractMicroseconds

​subtractMilliseconds

​subtractMinutes

​subtractMonths

​subtractNanoseconds

​subtractQuarters

​subtractSeconds

​subtractTupleOfIntervals

​subtractWeeks

​subtractYears

​timeDiff

​timeSlot

​timeSlots

​timestamp

​timezone

​timezoneOf

​timezoneOffset

​toDayOfMonth

​toDayOfWeek

​toDayOfYear

​toDaysInMonth

​toDaysSinceYearZero

​toHour

​toISOWeek

​toISOYear

​toLastDayOfMonth

​toLastDayOfWeek

UTCTimestamp

YYYYMMDDToDate

YYYYMMDDToDate32

YYYYMMDDhhmmssToDateTime

YYYYMMDDhhmmssToDateTime64

addDate

addDays

addHours

addInterval

addMicroseconds

addMilliseconds

addMinutes

addMonths

addNanoseconds

addQuarters

addSeconds

addTupleOfIntervals

addWeeks

addYears

age

changeDay

changeHour

changeMinute

changeMonth

changeSecond

changeYear

dateDiff

dateName

dateTrunc

formatDateTime

formatDateTimeInJodaSyntax

fromDaysSinceYearZero

fromDaysSinceYearZero32

fromModifiedJulianDay

fromModifiedJulianDayOrNull

fromUTCTimestamp

fromUnixTimestamp

fromUnixTimestampInJodaSyntax

localtime

makeDate

makeDate32

makeDateTime

makeDateTime64

monthName

now

now64

nowInBlock

nowInBlock64

serverTimezone

subDate

subtractDays

subtractHours

subtractInterval

subtractMicroseconds

subtractMilliseconds

subtractMinutes

subtractMonths

subtractNanoseconds

subtractQuarters

subtractSeconds

subtractTupleOfIntervals

subtractWeeks

subtractYears

timeDiff

timeSlot

timeSlots

timestamp

timezone

timezoneOf

timezoneOffset

toDayOfMonth

toDayOfWeek

toDayOfYear

toDaysInMonth

toDaysSinceYearZero

toHour

toISOWeek

toISOYear

toLastDayOfMonth

toLastDayOfWeek