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, TODAY e CURRENT_DATE, podem ser usadas sem parênteses.
now('UTC'). Ela foi adicionada apenas para oferecer suporte ao MySQL. now é a forma de uso preferida.
Sintaxe
Aliases: UTC_timestamp
Argumentos
Valor retornado
Retorna a data e a hora atuais no momento da análise da consulta. DateTime
Exemplos
Obter o timestamp UTC atual
┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘
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
Argumentos
Valor retornado
Retorna um valor Date com base nos argumentos fornecidos Date
Exemplos
Exemplo
SELECT YYYYMMDDToDate(20230911);
┌─toYYYYMMDD(20230911)─┐
│ 2023-09-11 │
└──────────────────────┘
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)
Date32 a partir dos argumentos fornecidos Date32
Exemplos
Exemplo
SELECT YYYYMMDDToDate32(20000507);
┌─YYYYMMDDToDate32(20000507)─┐
│ 2000-05-07 │
└────────────────────────────┘
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])
YYYYMMDDhhmmss — Número que contém o ano, mês, dia, hora, minuto e segundo. (U)Int* ou Float* ou Decimaltimezone — Nome do fuso horário. String
Valor retornado
Retorna um valor DateTime a partir dos argumentos fornecidos DateTime
Exemplos
Exemplo
SELECT YYYYMMDDToDateTime(20230911131415);
┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│ 2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘
YYYYMMDDhhmmssToDateTime64
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]])
YYYYMMDDhhmmss — Número que contém o ano, mês, dia, hora, minuto e segundo. (U)Int* ou Float* ou Decimalprecision — Precisão da parte fracionária (0-9). UInt8timezone — Nome do fuso horário. String
Valor retornado
Retorna um valor DateTime64 com base nos argumentos fornecidos DateTime64
Exemplos
Exemplo
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│ 2023-09-11 13:14:15.000 │
└──────────────────────────┘
addDate(datetime, interval)
interval a datetime. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar intervalo a uma data
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
┌─addDate(toDa⋯valYear(3))─┐
│ 2021-01-01 │
└──────────────────────────┘
datetime com num dias adicionados. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar dias a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addDays(date, 5) AS add_days_with_date,
addDays(date_time, 5) AS add_days_with_date_time,
addDays(date_time_string, 5) AS add_days_with_date_time_string
┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│ 2024-01-06 │ 2024-01-06 00:00:00 │ 2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
┌─plus(CAST('1⋯valDay(10))─┐
│ 1998-06-26 │
└──────────────────────────┘
datetime acrescido de num horas DateTime ou DateTime64(3)
Exemplos
Adicionar horas a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addHours(date, 12) AS add_hours_with_date,
addHours(date_time, 12) AS add_hours_with_date_time,
addHours(date_time_string, 12) AS add_hours_with_date_time_string
┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
┌─plus(CAST('1⋯alHour(10))─┐
│ 1998-06-16 10:00:00 │
└──────────────────────────┘
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).
addInterval(interval_1, interval_2)
Tuple(Interval)
Exemplos
Somar intervalos
SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)
┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1) │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1) │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3) │
└─────────────────────────────────────────────────┘
addMicroseconds(datetime, num)
date_time mais num microssegundos DateTime64
Exemplos
Adicionar microssegundos a diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string
┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000000 │ 2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘
addMilliseconds(datetime, num)
datetime mais num milissegundos DateTime64
Exemplos
Adicionar milissegundos a diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string
┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000 │ 2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
┌─plus(CAST('1⋯second(10))─┐
│ 1998-06-16 00:00:00.010 │
└──────────────────────────┘
addMinutes(datetime, num)
datetime acrescido de num minutos DateTime ou DateTime64(3)
Exemplos
Adicionar minutos a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMinutes(date, 20) AS add_minutes_with_date,
addMinutes(date_time, 20) AS add_minutes_with_date_time,
addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string
┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
┌─plus(CAST('1⋯Minute(10))─┐
│ 1998-06-16 00:10:00 │
└──────────────────────────┘
datetime acrescido de num meses. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar meses a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMonths(date, 6) AS add_months_with_date,
addMonths(date_time, 6) AS add_months_with_date_time,
addMonths(date_time_string, 6) AS add_months_with_date_time_string
┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│ 2024-07-01 │ 2024-07-01 00:00:00 │ 2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
┌─plus(CAST('1⋯lMonth(10))─┐
│ 1999-04-16 │
└──────────────────────────┘
addNanoseconds(datetime, num)
datetime mais num nanossegundos. DateTime64
Exemplos
Adicionar nanossegundos a diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string
┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│ 2024-01-01 00:00:00.000001000 │ 2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘
addQuarters(datetime, num)
datetime mais num trimestres Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar trimestres a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addQuarters(date, 1) AS add_quarters_with_date,
addQuarters(date_time, 1) AS add_quarters_with_date_time,
addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string
┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│ 2024-04-01 │ 2024-04-01 00:00:00 │ 2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
┌─plus(CAST('1⋯uarter(10))─┐
│ 2000-12-16 │
└──────────────────────────┘
addSeconds(datetime, num)
datetime mais num segundos DateTime ou DateTime64(3)
Exemplos
Adicionar segundos a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addSeconds(date, 30) AS add_seconds_with_date,
addSeconds(date_time, 30) AS add_seconds_with_date_time,
addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string
┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│ 1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘
addTupleOfIntervals(datetime, intervals)
date com intervals adicionados. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar Tuple de intervalos à data
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│ 2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘
datetime mais num semanas. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar semanas a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addWeeks(date, 5) AS add_weeks_with_date,
addWeeks(date_time, 5) AS add_weeks_with_date_time,
addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string
┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│ 2024-02-05 │ 2024-02-05 00:00:00 │ 2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
┌─plus(CAST('1⋯alWeek(10))─┐
│ 1998-08-25 │
└──────────────────────────┘
datetime acrescido de num anos Date ou Date32 ou DateTime ou DateTime64
Exemplos
Adicionar anos a diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addYears(date, 1) AS add_years_with_date,
addYears(date_time, 1) AS add_years_with_date_time,
addYears(date_time_string, 1) AS add_years_with_date_time_string
┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│ 2025-01-01 │ 2025-01-01 00:00:00 │ 2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
┌─plus(CAST('1⋯alYear(10))─┐
│ 2008-06-16 │
└──────────────────────────┘
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])
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 DateTime64enddate — O segundo valor de data/hora do qual será feita a subtração (o minuendo). Date ou Date32 ou DateTime ou DateTime64timezone — Opcional. Nome do fuso horário. Se especificado, ele é aplicado tanto a startdate quanto a enddate. Se não for especificado, serão usados os fusos horários de startdate e enddate. Se eles não forem iguais, o resultado será indefinido. String
Valor retornado
Retorna a diferença entre enddate e startdate expressa em unit. Int32
Exemplos
Calcular a idade em horas
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 24 │
└───────────────────────────────────────────────────────────────────────────────────┘
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
age('day', s, e) AS day_age,
age('month', s, e) AS month_age,
age('year', s, e) AS year_age
┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 0 │ 0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘
changeDay(date_or_datetime, value)
date_or_datetime, com o componente de dia modificado. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeDay('2024-01-31'::DateTime, 15)
changeHour(date_or_datetime, value)
date_or_datetime, com o componente de hora modificado. DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
date or date time.
Sintaxe
changeMinute(date_or_datetime, value)
date_or_datetime, com o componente de minuto alterado. DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
changeMonth(date_or_datetime, value)
date_or_datetime, com o componente de mês modificado. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeMonth('2024-01-01'::DateTime, 12)
changeSecond(date_or_datetime, value)
date_or_datetime, com o componente de segundos modificado. DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
changeYear(date_or_datetime, value)
date_or_datetime, com o componente de ano modificado. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Exemplo de uso
SELECT changeYear('2024-01-01'::DateTime, 2023)
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])
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 DateTime64enddate — O segundo valor de data/hora do qual subtrair (o minuendo). Date ou Date32 ou DateTime ou DateTime64timezone — Opcional. Nome do fuso horário. Se especificado, ele será aplicado a startdate e enddate. Se não for especificado, serão usados os fusos horários de startdate e enddate. Se eles não forem iguais, o resultado será indefinido. String
Valor retornado
Retorna a diferença entre enddate e startdate, expressa em unit. Int64
Exemplos
Calcular a diferença entre datas em horas
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
dateDiff('day', s, e) AS day_diff,
dateDiff('month', s, e) AS month_diff,
dateDiff('year', s, e) AS year_diff
┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 1 │ 1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘
- ‘year’
- ‘quarter’
- ‘month’
- ‘week’
- ‘dayofyear’
- ‘day’
- ‘weekday’
- ‘hour’
- ‘minute’
- ‘second’
Sintaxe
dateName(date_part, date[, timezone])
String
Exemplos
Extrair diferentes partes da data
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
dateName('year', date_value),
dateName('month', date_value),
dateName('day', date_value)
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021 │ April │ 14 │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘
dateTrunc(unit, datetime[, timezone])
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.
Stringdatetime — Data e hora. Date ou Date32 ou DateTime ou DateTime64timezone — 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 |
SELECT now(), dateTrunc('hour', now());
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │ 2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘
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])
DATE_FORMAT
Argumentos
datetime — Uma data ou data e hora a ser formatada. Date ou Date32 ou DateTime ou DateTime64format — String de formato com campos de substituição. Stringtimezone — Opcional. Nome do fuso horário para a data e hora formatadas. String
Valor retornado
Retorna valores de data e hora de acordo com o formato especificado. String
Exemplos
Formatar data com marcador de ano
SELECT formatDateTime(toDate('2010-01-04'), '%g')
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560 │
└─────────────────────────────────────────────────────────────────────┘
SELECT
now() AS ts,
time_zone,
formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Andorra │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan │ 23:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Athens │ 22:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belfast │ 20:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belgrade │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Berlin │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Brussels │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bucharest │ 22:13:40 │
└─────────────────────┴───────────────────┴─────────────┘
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 | ’ |
formatDateTimeInJodaSyntax(datetime, format[, timezone])
datetime — Uma data ou data e hora a ser formatada. DateTime ou Date ou Date32 ou DateTime64format — String de formato com campos de substituição no estilo Joda. Stringtimezone — Opcional. Nome do fuso horário para a hora formatada. String
Valor retornado
Retorna valores de data e hora de acordo com o formato especificado. String
Exemplos
Formatar datetime usando a sintaxe Joda
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
FROM_DAYS() do MySQL. O resultado é indefinido se não puder ser representado dentro dos limites do tipo Date.
Sintaxe
fromDaysSinceYearZero(days)
FROM_DAYS
Argumentos
days — O número de dias transcorridos desde o ano zero. UInt32
Valor retornado
Retorna a data correspondente ao número de dias transcorridos desde o ano zero. Date
Exemplos
Converter dias transcorridos desde o ano zero em datas
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
FROM_DAYS() do MySQL. O resultado é indefinido se não puder ser representado nos limites do tipo Date32.
Sintaxe
fromDaysSinceYearZero32(days)
days — O número de dias decorridos desde o ano zero. UInt32
Valor retornado
Retorna a data correspondente ao número de dias decorridos desde o ano zero. Date32
Exemplos
Converter dias desde o ano zero em datas
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
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)
day — número do Dia Juliano Modificado. (U)Int*
Valor retornado
Retorna a data em formato de texto. String
Exemplos
Converter Dia Juliano Modificado em data
SELECT fromModifiedJulianDay(58849)
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
fromModifiedJulianDayOrNull
fromModifiedJulianDay(), mas, em vez de lançar exceções, retorna NULL.
Sintaxe
fromModifiedJulianDayOrNull(day)
day — número do Dia Juliano Modificado. (U)Int*
Valor retornado
Retorna a data em formato de texto para um argumento day válido; caso contrário, null. Nullable(String)
Exemplos
Converter Dia Juliano Modificado em data com tratamento de null
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- argumento inválido, retorna NULL
┌─fromModified⋯Null(58849)─┐
│ 2020-01-01 │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
fromUTCTimestamp(datetime, time_zone)
from_utc_timestamp
Argumentos
datetime — Um valor constante de data ou data com hora, ou uma expressão. DateTime ou DateTime64time_zone — Um valor constante do tipo String ou uma expressão que representa o fuso horário. String
Valor retornado
Retorna um DateTime/DateTime64 no fuso horário especificado. DateTime ou DateTime64
Exemplos
Converta o fuso horário UTC para o fuso horário especificado
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│ 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘
- 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]])
FROM_UNIXTIME
Argumentos
timestamp — timestamp Unix ou valor de data/data com hora. (U)Int* ou Date ou Date32 ou DateTime ou DateTime64format — Opcional. String de formato constante para a formatação de saída. Stringtimezone — Opcional. String constante de fuso horário. String
Valor retornado
Retorna DateTime a partir do timestamp quando chamada com um argumento, ou uma String quando chamada com dois ou três argumentos. DateTime ou String
Exemplos
Converte um timestamp Unix em DateTime
SELECT fromUnixTimestamp(423543535)
┌─fromUnixTimestamp(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────────┘
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘
fromUnixTimestampInJodaSyntax
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])
timestamp — timestamp Unix ou valor de data/hora. (U)Int* ou Date ou Date32 ou DateTime ou DateTime64format — Opcional. String de formato constante usando a sintaxe Joda para formatação de saída. Stringtimezone — Opcional. String constante de fuso horário. String
Valor retornado
Retorna uma data com hora quando chamada com um argumento, ou uma String quando chamada com dois ou três argumentos.} DateTime ou String
Exemplos
Converter timestamp Unix com formato Joda
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘
Date a partir de:
- ano, mês e dia
- ano e dia do ano
Sintaxe
makeDate(year, month, day)
makeDate(year, day_of_year)
Date criado a partir dos argumentos fornecidos Date
Exemplos
Data a partir de ano, mês e dia
SELECT makeDate(2023, 2, 28) AS date;
┌───────date─┐
│ 2023-02-28 │
└────────────┘
SELECT makeDate(2023, 42) AS date;
┌───────date─┐
│ 2023-02-11 │
└────────────┘
Date32 a partir de:
- ano, mês e dia
- ano e dia do ano
Sintaxe
makeDate32(year, month, day)
makeDate32(year, day_of_year)
Date32 construído com os argumentos fornecidos Date32
Exemplos
Date32 a partir de ano, mês e dia
SELECT makeDate(2023, 2, 28) AS date;
┌───────date─┐
│ 2023-02-28 │
└────────────┘
SELECT makeDate(2023, 42) AS date;
┌───────date─┐
│ 2023-02-11 │
└────────────┘
DateTime a partir do ano, mês, dia, hora, minuto e segundo, com timezone opcional.
Sintaxe
makeDateTime(year, month, day, hour, minute, second[, timezone])
DateTime construído a partir dos argumentos fornecidos DateTime
Exemplos
DateTime a partir de ano, mês, dia, hora, minuto e segundo
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘
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]]])
DateTime64 construído a partir dos argumentos fornecidos DateTime64
Exemplos
DateTime64 a partir de ano, mês, dia, hora, minuto e segundo
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│ 2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘
String
Exemplos
Obter o nome do mês a partir de uma data
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
┌─monthName(date_value)─┐
│ April │
└───────────────────────┘
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
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
SELECT now('Asia/Istanbul')
┌─now('Asia/Istanbul')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
SELECT NOW, CURRENT_TIMESTAMP
┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘
now64([scale[, timezone]])
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). UInt8timezone — Opcional. Nome do fuso horário para o valor retornado. String
Valor retornado
Retorna a data e a hora atuais com precisão de subsegundos. DateTime64
Exemplos
Consulta com precisão padrão e personalizada
SELECT now64(), now64(9, 'Asia/Istanbul')
┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘
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
Argumentos
timezone — Opcional. Nome do fuso horário do valor retornado. String
Valor retornado
Retorna a data e a hora atuais no momento em que cada bloco de dados é processado. DateTime
Exemplos
Diferença em relação à função now()
SELECT
now(),
nowInBlock(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │ 0 │
└─────────────────────┴─────────────────────┴──────────┘
INSERT SELECT de longa duração.
Sintaxe
nowInBlock64([scale[, timezone]])
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). UInt8timezone — Opcional. Nome do fuso horário do valor retornado. String
Valor retornado
Retorna a data e a hora atuais no momento em que cada bloco de dados é processado, com precisão de subsegundos. DateTime64
Exemplos
Diferença em relação à função now64()
SELECT
now64(),
nowInBlock64(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │ 0 │
└─────────────────────────┴─────────────────────────┴──────────┘
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
Nomes alternativos: serverTimeZone
Argumentos
Valor retornado
Retorna o fuso horário do servidor como uma String
Exemplos
Exemplo de uso
┌─serverTimeZone()─┐
│ UTC │
└──────────────────┘
subDate(datetime, interval)
interval de datetime. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair intervalo de uma data
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2015-01-01 │
└──────────────────────────────────────────────────┘
subtractDays(datetime, num)
datetime com num dias subtraídos Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair dias de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractDays(date, 31) AS subtract_days_with_date,
subtractDays(date_time, 31) AS subtract_days_with_date_time,
subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string
┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
┌─minus(CAST('⋯valDay(10))─┐
│ 1998-06-06 │
└──────────────────────────┘
subtractHours(datetime, num)
datetime menos num horas, DateTime ou DateTime64(3)
Exemplos
Subtrair horas de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractHours(date, 12) AS subtract_hours_with_date,
subtractHours(date_time, 12) AS subtract_hours_with_date_time,
subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string
┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
┌─minus(CAST('⋯alHour(10))─┐
│ 1998-06-15 14:00:00 │
└──────────────────────────┘
toIntervalDay(2) e toIntervalDay(1) forem
informados, o resultado será (1) em vez de (2,1).
Sintaxe
subtractInterval(interval_1, interval_2)
Tuple(T)
Exemplos
Subtração de intervalos
SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);
┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1) │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1) │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1) │
└──────────────────────────────────────────────────────┘
subtractMicroseconds(datetime, num)
datetime — Data com hora da qual será subtraído o número especificado de microssegundos. DateTime ou DateTime64 ou Stringnum — Número de microssegundos a serem subtraídos. (U)Int* ou Float*
Valor retornado
Retorna datetime menos num microssegundos. DateTime64
Exemplos
Subtrair microssegundos de diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string
┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000000 │ 2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘
subtractMilliseconds(datetime, num)
datetime menos num milissegundos DateTime64
Exemplos
Subtrair milissegundos de diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string
┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000 │ 2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
┌─minus(CAST('⋯second(10))─┐
│ 1998-06-15 23:59:59.990 │
└──────────────────────────┘
subtractMinutes(datetime, num)
datetime com num minutos subtraídos. DateTime ou DateTime64(3)
Exemplos
Subtrair minutos de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMinutes(date, 30) AS subtract_minutes_with_date,
subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string
┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
┌─minus(CAST('⋯Minute(10))─┐
│ 1998-06-15 23:50:00 │
└──────────────────────────┘
subtractMonths(datetime, num)
datetime menos num meses. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair meses de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMonths(date, 1) AS subtract_months_with_date,
subtractMonths(date_time, 1) AS subtract_months_with_date_time,
subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string
┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
┌─minus(CAST('⋯lMonth(10))─┐
│ 1997-08-16 │
└──────────────────────────┘
subtractNanoseconds(datetime, num)
datetime menos num nanossegundos. DateTime64
Exemplos
Subtrair nanossegundos de diferentes tipos de data e hora
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string
┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.999999000 │ 2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘
subtractQuarters(datetime, num)
datetime com num trimestres subtraídos Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair trimestres de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractQuarters(date, 1) AS subtract_quarters_with_date,
subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string
┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│ 2023-10-01 │ 2023-10-01 00:00:00 │ 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
┌─minus(CAST('1⋯Quarter(10))─┐
│ 1996-09-16 │
└───────────────────────────┘
subtractSeconds(datetime, num)
datetime menos num segundos. DateTime ou DateTime64(3)
Exemplos
Subtrair segundos de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractSeconds(date, 60) AS subtract_seconds_with_date,
subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string
┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
┌─minus(CAST('⋯Second(10))─┐
│ 1998-06-15 23:59:50 │
└──────────────────────────┘
subtractTupleOfIntervals(datetime, intervals)
date com os intervals subtraídos. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair uma tupla de intervalos de uma data
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
┌─subtractTupl⋯alYear(1)))─┐
│ 2016-12-31 │
└──────────────────────────┘
subtractWeeks(datetime, num)
datetime menos num semanas Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtração de semanas em diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractWeeks(date, 1) AS subtract_weeks_with_date,
subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string
┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│ 2023-12-25 │ 2023-12-25 00:00:00 │ 2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
┌─minus(CAST('⋯alWeek(10))─┐
│ 1998-04-07 │
└──────────────────────────┘
subtractYears(datetime, num)
datetime menos num anos. Date ou Date32 ou DateTime ou DateTime64
Exemplos
Subtrair anos de diferentes tipos de data
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractYears(date, 1) AS subtract_years_with_date,
subtractYears(date_time, 1) AS subtract_years_with_date_time,
subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string
┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│ 2023-01-01 │ 2023-01-01 00:00:00 │ 2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
┌─minus(CAST('⋯alYear(10))─┐
│ 1988-06-16 │
└──────────────────────────┘
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)
enddate e startdate, expressa em segundos. Int64
Exemplos
Calcular a diferença de tempo em segundos
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
┌───res─┐
│ 90000 │
└───────┘
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
┌─hours─┐
│ 25 │
└───────┘
SELECT
timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result
┌─time_diff_result─┬─date_diff_result─┐
│ 259200 │ 259200 │
└──────────────────┴──────────────────┘
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.
timeSlot(time[, time_zone])
time — Hora a ser arredondada para o início de um intervalo de meia hora. DateTime ou Date32 ou DateTime64time_zone — Opcional. Um valor constante do tipo String ou uma expressão que representa o fuso horário. String
Valor retornado
Retorna a hora arredondada para o início de um intervalo de meia hora. DateTime
Exemplos
Arredondar a hora para um intervalo de meia hora
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│ 2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘
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])
StartTime). Para DateTime64, a escala do valor retornado pode ser diferente da escala de StartTime — é usada a maior escala entre todos os argumentos fornecidos. Array(DateTime) ou Array(DateTime64)
Exemplos
Gerar intervalos de tempo para um intervalo
SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))
┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00'] │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11'] │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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])
expr — Data ou data e hora. Stringexpr_time — Opcional. Horário a ser adicionado ao valor convertido. String
Valor retornado
Retorna o valor convertido de expr ou expr com o horário adicionado DateTime64(6)
Exemplos
Converter string de data em DateTime64(6)
SELECT timestamp('2023-12-31') AS ts;
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘
timeZone
Argumentos
Valor retornado
Retorna o nome canônico do fuso horário na forma de uma String
Exemplos
Exemplo de uso
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘
DateTime ou DateTime64.
Sintaxe
Aliases: timeZoneOf
Argumentos
datetime — Um valor do tipo DateTime ou DateTime64timezone — Opcional. Nome do fuso horário para o qual converter o valor datetime. String
Valor retornado
Retorna o nome do fuso horário do datetime String
Exemplos
Exemplo de uso
SELECT timezoneOf(now());
┌─timezoneOf(now())─┐
│ Europe/Amsterdam │
└───────────────────┘
timeZoneOffset
Argumentos
datetime — valor DateTime para obter o deslocamento do fuso horário. DateTime ou DateTime64
Valor retornado
Retorna o deslocamento em relação a UTC, em segundos Int32
Exemplos
Exemplo de uso
SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time,
toTypeName(Time) AS Type,
timezoneOffset(Time) AS Offset_in_seconds,
(Offset_in_seconds / 3600) AS Offset_in_hours;
┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │ -14400 │ -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘
Date ou DateTime.
Sintaxe
Aliases: DAY, DAYOFMONTH
Argumentos
Valor retornado
Retorna o dia do mês da data/hora especificada UInt8
Exemplos
Exemplo de uso
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 21 │
└─────────────────────────────────────────────────┘
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 |
toDayOfWeek(datetime[, mode[, timezone]])
DAYOFWEEK
Argumentos
datetime — Data ou data e hora da qual se obtém o dia da semana. Date ou Date32 ou DateTime ou DateTime64mode — Opcional. Inteiro que especifica o modo da semana (0–3). O padrão é 0 se for omitido. UInt8timezone — Opcional. Fuso horário a ser usado na conversão. String
Valor retornado
Retorna o dia da semana para o Date ou DateTime informado UInt8
Exemplos
Exemplo de uso
-- A data a seguir é 21 de abril de 2023, que foi uma sexta-feira:
SELECT
toDayOfWeek(toDateTime('2023-04-21')),
toDayOfWeek(toDateTime('2023-04-21'), 1)
┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│ 5 │ 4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘
Date ou DateTime.
Sintaxe
Aliases: DAYOFYEAR
Argumentos
Valor retornado
Retorna o dia do ano da Date ou DateTime especificada UInt16
Exemplos
Exemplo de uso
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 111 │
└────────────────────────────────────────────────┘
Date ou DateTime.
O valor retornado está no intervalo de 28 a 31.
Sintaxe
Argumentos
Valor retornado
Retorna o número de dias no mês da data/hora informada. UInt8
Exemplos
Exemplo de uso
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
┌─toDaysInMonth(toDate('2023-02-01'))─┬─toDaysInMonth(toDate('2024-02-01'))─┬─toDaysInMonth(toDate('2023-01-01'))─┐
│ 28 │ 29 │ 31 │
└─────────────────────────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
TO_DAYS do MySQL.
Sintaxe
toDaysSinceYearZero(date[, time_zone])
TO_DAYS
Argumentos
Valor retornado
Retorna o número de dias decorridos desde a data 0000-01-01. UInt32
Exemplos
Calcular os dias desde o ano zero
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│ 713569 │
└────────────────────────────────────────────┘
DateTime ou DateTime64.
Sintaxe
Aliases: HOUR
Argumentos
Valor retornado
Retorna a hora (0-23) de datetime. UInt8
Exemplos
Exemplo de uso
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│ 10 │
└───────────────────────────────────────────┘
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])
UInt8
Exemplos
Obter os números das semanas ISO
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │ 52 │
└────────────┴─────────┘
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │ 1 │ 2025 │
└────────────┴─────────┴──────┘
UInt16
Exemplos
Obter o ano ISO de valores de data
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
┌─week1─┬─week2─┐
│ 40 │ 40 │
└───────┴───────┘
LAST_DAY
Argumentos
Valor retornado
Retorna a data do último dia do mês para a data ou data e hora fornecida. Date
Exemplos
Arredondar para o último dia do mês
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-30 │
└─────────────────────────────────────────────────────┘
toLastDayOfWeek(datetime[, mode[, timezone]])
datetime — Uma data ou data com hora para converter. Date ou DateTime ou Date32 ou DateTime64mode — Determina o primeiro dia da semana, conforme descrito na função toWeek(). O padrão é 0. UInt8timezone — Opcional. O fuso horário a ser usado na conversão. Se não for especificado, o fuso horário do servidor será usado. String
Valor retornado
Retorna a data do sábado ou domingo mais próximo, na data especificada ou após ela, dependendo do modo. Date ou Date32
Exemplos
Arredondar para cima até o sábado ou domingo mais próximo
SELECT
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* 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
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
DateTime ou DateTime64.
Sintaxe
Aliases: MILLISECOND
Argumentos
Valor retornado
Retorna o milissegundo do minuto (0 - 59) em datetime. UInt16
Exemplos
Exemplo de uso
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│ 456 │
└────────────────────────────────────────────────────────────┘
Date ou DateTime.
Sintaxe
Aliases: MINUTE
Argumentos
Valor retornado
Retorna o minuto da hora (0 - 59) de datetime. UInt8
Exemplos
Exemplo de uso
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│ 20 │
└─────────────────────────────────────────────┘
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)
Int32
Exemplos
Converter data para Dia Juliano Modificado
SELECT toModifiedJulianDay('2020-01-01')
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
toModifiedJulianDayOrNull
toModifiedJulianDay(), mas, em vez de lançar exceções, retorna NULL.
Sintaxe
toModifiedJulianDayOrNull(date)
date válido; caso contrário, null. Nullable(Int32)
Exemplos
Converter data para Dia Juliano Modificado com tratamento de null
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- data inválida, retorna NULL
┌─toModifiedJu⋯020-01-01')─┐
│ 58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
Date
Exemplos
Arredonde para a segunda-feira da semana
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Uma sexta-feira
toMonday(toDate('2023-04-24')); -- Já é uma segunda-feira
┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│ 2023-04-17 │ 2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘
Date ou DateTime.
Sintaxe
Aliases: MONTH
Argumentos
Valor retornado
Retorna o mês da data/hora fornecida UInt8
Exemplos
Exemplo de uso
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 4 │
└────────────────────────────────────────────┘
toMonthNumSinceEpoch(date)
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
Date ou DateTime.
Sintaxe
Aliases: QUARTER
Argumentos
Valor retornado
Retorna o trimestre do ano da data/hora fornecida UInt8
Exemplos
Exemplo de uso
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2 │
└──────────────────────────────────────────────┘
toRelativeDayNum(dt1) - toRelativeDayNum(dt2).
Sintaxe
Argumentos
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
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
┌─minus(toRela⋯3-01-01')))─┐
│ 90 │
└──────────────────────────┘
toRelativeHourNum(dt1) - toRelativeHourNum(dt2).
Sintaxe
Argumentos
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
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
┌─hours_difference─┐
│ 12 │
└──────────────────┘
toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2).
Sintaxe
toRelativeMinuteNum(date)
UInt32
Exemplos
Obter números relativos de minutos
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
┌─minutes_difference─┐
│ 30 │
└────────────────────┘
toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2).
Sintaxe
Argumentos
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
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
┌─months_difference─┐
│ 3 │
└───────────────────┘
toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2).
Sintaxe
toRelativeQuarterNum(date)
UInt32
Exemplos
Obter números relativos de trimestre
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
┌─quarters_difference─┐
│ 1 │
└─────────────────────┘
toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2).
Sintaxe
toRelativeSecondNum(date)
UInt32
Exemplos
Obter números relativos de segundos
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
┌─seconds_difference─┐
│ 60 │
└────────────────────┘
toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2).
Sintaxe
Argumentos
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
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
┌─weeks_difference─┐
│ 1 │
└──────────────────┘
toRelativeYearNum(dt1) - toRelativeYearNum(dt2).
Sintaxe
Argumentos
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
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
┌─minus(toRela⋯ateTime')))─┐
│ 10 │
└──────────────────────────┘
DateTime ou DateTime64.
Sintaxe
Aliases: SECOND
Argumentos
Valor retornado
Retorna o segundo do minuto (0 - 59) de datetime. UInt8
Exemplos
Exemplo de uso
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│ 30 │
└─────────────────────────────────────────────┘
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
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘
toStartOfFifteenMinutes(datetime)
DateTime ou DateTime64
Exemplos
Exemplo
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
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(datetime)
toStartOfFiveMinute
Argumentos
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
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
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
DateTime ou DateTime64
Exemplos
Arredondar para baixo para o início da hora
SELECT
toStartOfHour(toDateTime('2023-04-21 10:20:30'));
┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime │
└─────────────────────┴─────────────────┘
Date
Exemplos
Arredondar para o primeiro dia do ano ISO
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-02 │
└─────────────────────────────────────────────────────┘
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. | |
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]])
time_bucket, date_bin
Argumentos
value — Valor de data ou data/hora a ser arredondado para baixo. Date ou DateTime ou DateTime64x — 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
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
┌─toStartOfInt⋯alMonth(1))─┐
│ 2023-01-01 │
└──────────────────────────┘
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
┌─toStartOfInt⋯14:35:30'))─┐
│ 2023-01-01 14:44:30 │
└──────────────────────────┘
toStartOfMicrosecond(datetime[, timezone])
datetime — Data e hora. DateTime64timezone — 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
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘
toStartOfMillisecond(datetime[, timezone])
datetime — Data e hora. DateTime64timezone — 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
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘
toStartOfMinute(datetime)
DateTime ou DateTime64
Exemplos
Arredondar para baixo até o início do minuto
SELECT
toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
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
Date
Exemplos
Arredondar para baixo para o primeiro dia do mês
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└───────────────────────────────────────────────────┘
toStartOfNanosecond(datetime[, timezone])
datetime — Data e hora. DateTime64timezone — 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
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘
Date
Exemplos
Arredondar para baixo até o primeiro dia do trimestre
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└─────────────────────────────────────────────────────┘
toStartOfSecond(datetime[, timezone])
datetime — Data e hora das quais remover as frações de segundo. DateTime64timezone — 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
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘
toStartOfTenMinutes(datetime)
DateTime ou DateTime64
Exemplos
Exemplo
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
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(datetime[, mode[, timezone]])
datetime — Uma data ou data com hora a ser convertida. Date ou DateTime ou Date32 ou DateTime64mode — Determina o primeiro dia da semana, conforme descrito na função toWeek(). O padrão é 0. UInt8timezone — 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
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
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
Date.
Sintaxe
Argumentos
Valor retornado
Retorna o primeiro dia do ano da data/hora fornecida Date
Exemplos
Arredondar para baixo para o primeiro dia do ano
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-01 │
└──────────────────────────────────────────────────┘
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])
DateTime
Exemplos
Calcular a diferença de tempo entre duas datas
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
┌─result─┬─toTypeName(result)─┐
│ 3600 │ Int32 │
└────────┴────────────────────┘
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)
toTimeZone
Argumentos
Valor retornado
Retorna o mesmo timestamp de entrada, mas com o fuso horário especificado DateTime ou DateTime64
Exemplos
Exemplo de uso
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;
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(datetime, time_zone)
to_utc_timestamp
Argumentos
datetime — Um valor constante do tipo data ou data com hora, ou uma expressão. DateTime ou DateTime64time_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
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│ 2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘
String, Date ou DateTime em um timestamp Unix (segundos desde 1970-01-01 00:00:00 UTC) para UInt32.
Sintaxe
toUnixTimestamp(date[, timezone])
date — Valor a ser convertido. Date ou Date32 ou DateTime ou DateTime64 ou Stringtimezone — 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
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;
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() 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 |
- 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]])
week
Argumentos
datetime — Data ou data com hora da qual obter o número da semana. Date ou DateTimemode — 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
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │ 52 │ 52 │ 1 │
└────────────┴───────┴───────┴───────┘
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])
datetime — Uma data ou data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64timezone — 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
SELECT toYYYYMM(now(), 'US/Eastern')
┌─toYYYYMM(now(), 'US/Eastern')─┐
│ 202303 │
└───────────────────────────────┘
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])
datetime — Uma data ou uma data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64timezone — 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
SELECT toYYYYMMDD(now(), 'US/Eastern')
┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│ 20230302 │
└─────────────────────────────────┘
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])
datetime — Data ou data com hora a ser convertida. Date ou Date32 ou DateTime ou DateTime64timezone — 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
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│ 20230302112209 │
└───────────────────────────────────────┘
Date ou DateTime.
Sintaxe
Aliases: YEAR
Argumentos
Valor retornado
Retorna o ano do valor Date ou DateTime fornecido, como UInt16
Exemplos
Exemplo de uso
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023 │
└───────────────────────────────────────────┘
toYearNumSinceEpoch(date)
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
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]])
yearweek
Argumentos
datetime — Data ou data com hora da qual obter o ano e a semana. Date ou DateTimemode — 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
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
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │ 201652 │ 201652 │ 201701 │ 202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘
toDate(now()).
Sintaxe
Aliases: curdate, current_date
Argumentos
Valor retornado
Retorna a data atual Date
Exemplos
Exemplo de uso
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ today ┃ curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │ 2025-03-03 │
└────────────┴────────────┴──────────────┘
SELECT TODAY, CURDATE,CURRENT_DATE
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ TODAY ┃ CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │ 2025-03-04 │
└────────────┴────────────┴──────────────┘
Date
Exemplos
Obter a data de ontem
SELECT yesterday();
SELECT today() - 1;
┌─yesterday()─┐
│ 2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│ 2025-06-09 │
└───────────────────┘
