> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentação das funções para trabalhar com datas e horas
# 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**
```sql theme={null}
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
```
```text theme={null}
┌────────────────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.
{/*AUTOGENERATED_START*/}
## 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`](#now) é a forma de uso preferida.
**Sintaxe**
```sql theme={null}
UTCTimestamp()
```
**Aliases**: `UTC_timestamp`
**Argumentos**
* Nenhum.
**Valor retornado**
Retorna a data e a hora atuais no momento da análise da consulta. [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Obter o timestamp UTC atual**
```sql title=Query theme={null}
SELECT UTCTimestamp()
```
```response title=Response theme={null}
┌──────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()`](/pt-BR/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
A saída é indefinida se a entrada não representar um valor de `Date` válido.
**Sintaxe**
```sql theme={null}
YYYYMMDDToDate(YYYYMMDD)
```
**Argumentos**
* `YYYYMMDD` — Número contendo o ano, o mês e o dia. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna um valor `Date` com base nos argumentos fornecidos [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate(20230911);
```
```response title=Response theme={null}
┌─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()`](/pt-BR/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
A saída é indefinida se a entrada não representar um valor `Date32` válido.
**Sintaxe**
```sql theme={null}
YYYYMMDDToDate32(YYYYMMDD)
```
**Argumentos**
* `YYYYMMDD` — Número que contém o ano, mês e dia. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna um valor `Date32` a partir dos argumentos fornecidos [`Date32`](/pt-BR/reference/data-types/date32)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate32(20000507);
```
```response title=Response theme={null}
┌─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()`](/pt-BR/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
A saída é indefinida se a entrada não codificar um valor `DateTime` válido.
**Sintaxe**
```sql theme={null}
YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])
```
**Argumentos**
* `YYYYMMDDhhmmss` — Número que contém o ano, mês, dia, hora, minuto e segundo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `timezone` — Nome do fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um valor `DateTime` a partir dos argumentos fornecidos [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT YYYYMMDDToDateTime(20230911131415);
```
```response title=Response theme={null}
┌──────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()`](/pt-BR/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
A saída é indefinida se a entrada não codificar um valor `DateTime64` válido.
**Sintaxe**
```sql theme={null}
YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])
```
**Argumentos**
* `YYYYMMDDhhmmss` — Número que contém o ano, mês, dia, hora, minuto e segundo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `precision` — Precisão da parte fracionária (0-9). [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `timezone` — Nome do fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um valor `DateTime64` com base nos argumentos fornecidos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addDate(datetime, interval)
```
**Argumentos**
* `datetime` — A data ou data e hora à qual `interval` é adicionado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `interval` — Intervalo a ser adicionado. [`Interval`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data ou data e hora obtida ao adicionar `interval` a `datetime`. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar intervalo a uma data**
```sql title=Query theme={null}
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addDays(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual adicionar o número especificado de dias. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de dias a serem adicionados. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` com `num` dias adicionados. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar dias a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addHours(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual será adicionado o número especificado de horas. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de horas a serem adicionadas. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` acrescido de `num` horas [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar horas a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addInterval(interval_1, interval_2)
```
**Argumentos**
* `interval_1` — Primeiro intervalo ou tupla de intervalos. [`Interval`](/pt-BR/reference/data-types/int-uint) ou [`Tuple(Interval)`](/pt-BR/reference/data-types/tuple)
* `interval_2` — Segundo intervalo a ser somado. [`Interval`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna uma tupla de intervalos [`Tuple(Interval)`](/pt-BR/reference/data-types/tuple)
**Exemplos**
**Somar intervalos**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql theme={null}
addMicroseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data e hora à qual adicionar o número especificado de microssegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de microssegundos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `date_time` mais `num` microssegundos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar microssegundos a diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addMilliseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data e hora à qual será adicionado o número especificado de milissegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de milissegundos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` mais `num` milissegundos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar milissegundos a diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addMinutes(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual será adicionado o número especificado de minutos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de minutos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` acrescido de `num` minutos [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar minutos a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addMonths(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data/hora à qual adicionar o número especificado de meses. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de meses a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` acrescido de `num` meses. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar meses a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addNanoseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data e hora à qual será adicionado o número especificado de nanossegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de nanossegundos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` mais `num` nanossegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar nanossegundos a diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addQuarters(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual será adicionado o número especificado de trimestres. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de trimestres a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` mais `num` trimestres [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar trimestres a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addSeconds(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual será adicionado o número especificado de segundos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de segundos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` mais `num` segundos [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar segundos a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addTupleOfIntervals(datetime, intervals)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual serão adicionados intervalos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `intervals` — Tuple de intervalos a ser adicionada a `datetime`. [`Tuple(Interval)`](/pt-BR/reference/data-types/tuple)
**Valor retornado**
Retorna `date` com `intervals` adicionados. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar Tuple de intervalos à data**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addWeeks(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora à qual será adicionado o número especificado de semanas. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de semanas a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` mais `num` semanas. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar semanas a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
addYears(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data com horário à qual será adicionado o número especificado de anos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de anos a adicionar. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` acrescido de `num` anos [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Adicionar anos a diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─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`](#dateDiff).
**Sintaxe**
```sql theme={null}
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`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `enddate` — O segundo valor de data/hora do qual será feita a subtração (o minuendo). [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a diferença entre enddate e startdate expressa em `unit`. [`Int32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Calcular a idade em horas**
```sql title=Query theme={null}
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
```
```response title=Response theme={null}
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 24 │
└───────────────────────────────────────────────────────────────────────────────────┘
```
**Calcular a idade em diferentes unidades**
```sql title=Query theme={null}
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 title=Response theme={null}
┌──────────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**
```sql theme={null}
changeDay(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo que `date_or_datetime`, com o componente de dia modificado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeDay('2024-01-31'::DateTime, 15)
```
```response title=Response theme={null}
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**
```sql theme={null}
changeHour(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo que `date_or_datetime`, com o componente de hora modificado. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
```
```response title=Response theme={null}
2024-01-01 05:00:00
```
## changeMinute
Introduzido em: v24.7.0
Altera o componente de minuto de um `date or date time`.
**Sintaxe**
```sql theme={null}
changeMinute(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo que `date_or_datetime`, com o componente de minuto alterado. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
```
```response title=Response theme={null}
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**
```sql theme={null}
changeMonth(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo que `date_or_datetime`, com o componente de mês modificado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeMonth('2024-01-01'::DateTime, 12)
```
```response title=Response theme={null}
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**
```sql theme={null}
changeSecond(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo de `date_or_datetime`, com o componente de segundos modificado. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
```
```response title=Response theme={null}
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**
```sql theme={null}
changeYear(date_or_datetime, value)
```
**Argumentos**
* `date_or_datetime` — O valor a ser alterado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `value` — O novo valor. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna um valor do mesmo tipo que `date_or_datetime`, com o componente de ano modificado. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT changeYear('2024-01-01'::DateTime, 2023)
```
```response title=Response theme={null}
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`](#toRelativeDayNum)), 1 mês para a unidade month (consulte [`toRelativeMonthNum`](#toRelativeMonthNum)) e 1 ano para a unidade year
(consulte [`toRelativeYearNum`](#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`](#age).
**Sintaxe**
```sql theme={null}
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`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `enddate` — O segundo valor de data/hora do qual subtrair (o minuendo). [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a diferença entre `enddate` e `startdate`, expressa em `unit`. [`Int64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Calcular a diferença entre datas em horas**
```sql title=Query theme={null}
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌─res─┐
│ 25 │
└─────┘
```
**Calcular a diferença entre datas em unidades diferentes**
```sql title=Query theme={null}
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 title=Response theme={null}
┌──────────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**
```sql theme={null}
dateName(date_part, date[, timezone])
```
**Argumentos**
* `date_part` — A parte da data que você deseja extrair. [`String`](/pt-BR/reference/data-types/string)
* `datetime` — Um valor de data ou data e hora. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a parte especificada da data. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Extrair diferentes partes da data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql theme={null}
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`](/pt-BR/reference/data-types/string)
* `datetime` — Data e hora. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/date32) ou [`Date`](/pt-BR/reference/data-types/date) |
| Day, Hour, Minute, Second | `Date32`, `DateTime64`, `Date` ou `DateTime` | [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`DateTime`](/pt-BR/reference/data-types/datetime) |
| Millisecond, Microsecond, | Qualquer | [`DateTime64`](/pt-BR/reference/data-types/datetime64) |
| Nanosecond | | com escala 3, 6 ou 9 |
**Exemplos**
**Truncar sem fuso horário**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now());
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
```
**Truncamento com fuso horário especificado**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
```
```response title=Response theme={null}
┌───────────────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](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
A operação oposta desta função é [`parseDateTime`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#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**
```sql theme={null}
formatDateTime(datetime, format[, timezone])
```
**Aliases**: `DATE_FORMAT`
**Argumentos**
* `datetime` — Uma data ou data e hora a ser formatada. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `format` — String de formato com campos de substituição. [`String`](/pt-BR/reference/data-types/string)
* `timezone` — Opcional. Nome do fuso horário para a data e hora formatadas. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna valores de data e hora de acordo com o formato especificado. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Formatar data com marcador de ano**
```sql title=Query theme={null}
SELECT formatDateTime(toDate('2010-01-04'), '%g')
```
```response title=Response theme={null}
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
```
**Formatar DateTime64 com frações de segundo**
```sql title=Query theme={null}
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
```
```response title=Response theme={null}
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560 │
└─────────────────────────────────────────────────────────────────────┘
```
**Formato com fuso horário**
```sql title=Query theme={null}
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 title=Response theme={null}
┌──────────────────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](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
A operação oposta desta função é [`parseDateTimeInJodaSyntax`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#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**
```sql theme={null}
formatDateTimeInJodaSyntax(datetime, format[, timezone])
```
**Argumentos**
* `datetime` — Uma data ou data e hora a ser formatada. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `format` — String de formato com campos de substituição no estilo Joda. [`String`](/pt-BR/reference/data-types/string)
* `timezone` — Opcional. Nome do fuso horário para a hora formatada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna valores de data e hora de acordo com o formato especificado. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Formatar `datetime` usando a sintaxe Joda**
```sql title=Query theme={null}
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─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](https://en.wikipedia.org/wiki/Year_zero), retorna a data correspondente no [calendário gregoriano proléptico definido pela ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
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](/pt-BR/reference/data-types/date).
**Sintaxe**
```sql theme={null}
fromDaysSinceYearZero(days)
```
**Aliases**: `FROM_DAYS`
**Argumentos**
* `days` — O número de dias transcorridos desde o ano zero. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data correspondente ao número de dias transcorridos desde o ano zero. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Converter dias transcorridos desde o ano zero em datas**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────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](https://en.wikipedia.org/wiki/Year_zero), retorna a data correspondente no [calendário gregoriano proléptico definido pela ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
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`](/pt-BR/reference/data-types/date32).
**Sintaxe**
```sql theme={null}
fromDaysSinceYearZero32(days)
```
**Argumentos**
* `days` — O número de dias decorridos desde o ano zero. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data correspondente ao número de dias decorridos desde o ano zero. [`Date32`](/pt-BR/reference/data-types/date32)
**Exemplos**
**Converter dias desde o ano zero em datas**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromModifiedJulianDay
Introduzido em: v21.1.0
Converte um número de [Dia Juliano Modificado](https://en.wikipedia.org/wiki/Julian_day#Variants) em uma data do [calendário gregoriano proléptico](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), 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**
```sql theme={null}
fromModifiedJulianDay(day)
```
**Argumentos**
* `day` — número do Dia Juliano Modificado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data em formato de texto. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Converter Dia Juliano Modificado em data**
```sql title=Query theme={null}
SELECT fromModifiedJulianDay(58849)
```
```response title=Response theme={null}
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
```
## fromModifiedJulianDayOrNull
Introduzido em: v21.1.0
Semelhante a [`fromModifiedJulianDay()`](#fromModifiedJulianDay), mas, em vez de lançar exceções, retorna `NULL`.
**Sintaxe**
```sql theme={null}
fromModifiedJulianDayOrNull(day)
```
**Argumentos**
* `day` — número do Dia Juliano Modificado. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data em formato de texto para um argumento `day` válido; caso contrário, `null`. [`Nullable(String)`](/pt-BR/reference/data-types/nullable)
**Exemplos**
**Converter Dia Juliano Modificado em data com tratamento de `null`**
```sql title=Query theme={null}
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- argumento inválido, retorna NULL
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
fromUTCTimestamp(datetime, time_zone)
```
**Aliases**: `from_utc_timestamp`
**Argumentos**
* `datetime` — Um valor constante de data ou data com hora, ou uma expressão. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `time_zone` — Um valor constante do tipo String ou uma expressão que representa o fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um DateTime/DateTime64 no fuso horário especificado. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Converta o fuso horário UTC para o fuso horário especificado**
```sql title=Query theme={null}
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/data-types/int-uint), retorna um valor do tipo [`DateTime`](/pt-BR/reference/data-types/datetime), ou seja, comporta-se como [`toDateTime`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#toDateTime).
* Quando recebe dois ou três argumentos, em que o primeiro argumento é um valor do tipo [`Integer`](/pt-BR/reference/data-types/int-uint), [`Date`](/pt-BR/reference/data-types/date), [`Date32`](/pt-BR/reference/data-types/date32), [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string), ou seja, comporta-se como [`formatDateTime`](#formatDateTime).
Nesse caso, é usado o [estilo de formatação de datetime do MySQL](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
**Sintaxe**
```sql theme={null}
fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])
```
**Aliases**: `FROM_UNIXTIME`
**Argumentos**
* `timestamp` — timestamp Unix ou valor de data/data com hora. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `format` — Opcional. String de formato constante para a formatação de saída. [`String`](/pt-BR/reference/data-types/string)
* `timezone` — Opcional. String constante de fuso horário. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/datetime) ou [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Converte um timestamp Unix em DateTime**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(423543535)
```
```response title=Response theme={null}
┌─fromUnixTimestamp(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────────┘
```
**Converta o timestamp Unix com formato**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/data-types/int-uint), retorna um valor do tipo [`DateTime`](/pt-BR/reference/data-types/datetime), ou seja, comporta-se como [`toDateTime`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#toDateTime).
Quando recebe dois ou três argumentos, em que o primeiro é um valor do tipo [`Integer`](/pt-BR/reference/data-types/int-uint), [`Date`](/pt-BR/reference/data-types/date), [`Date32`](/pt-BR/reference/data-types/date32), [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string), ou seja, comporta-se como [`formatDateTimeInJodaSyntax`](#formatDateTimeInJodaSyntax). Nesse caso, é usado o [estilo de formato de data e hora do Joda](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
**Sintaxe**
```sql theme={null}
fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])
```
**Argumentos**
* `timestamp` — timestamp Unix ou valor de data/hora. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `format` — Opcional. String de formato constante usando a sintaxe Joda para formatação de saída. [`String`](/pt-BR/reference/data-types/string)
* `timezone` — Opcional. String constante de fuso horário. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/datetime) ou [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Converter timestamp Unix com formato Joda**
```sql title=Query theme={null}
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘
```
## 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**
```sql theme={null}
makeDate(year, month, day)
makeDate(year, day_of_year)
```
**Argumentos**
* `year` — Número do ano. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `month` — Número do mês (1-12). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day` — Dia do mês (1-31). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day_of_year` — Dia do ano (1-365). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna um valor `Date` criado a partir dos argumentos fornecidos [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Data a partir de ano, mês e dia**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Data a partir do ano e do dia do ano**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────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**
```sql theme={null}
makeDate32(year, month, day)
makeDate32(year, day_of_year)
```
**Argumentos**
* `year` — Número do ano. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `month` — Número do mês (1-12). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day` — Dia do mês (1-31). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day_of_year` — Dia do ano (1-365). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
**Valor retornado**
Retorna um valor `Date32` construído com os argumentos fornecidos [`Date32`](/pt-BR/reference/data-types/date32)
**Exemplos**
**Date32 a partir de ano, mês e dia**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Date32 com base no ano e no dia do ano**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────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**
```sql theme={null}
makeDateTime(year, month, day, hour, minute, second[, timezone])
```
**Argumentos**
* `year` — Número do ano. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `month` — Número do mês (1-12). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day` — Dia do mês (1-31). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `hour` — Hora (0-23). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `minute` — Minuto (0-59). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `second` — Segundo (0-59). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `timezone` — Nome do fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um valor `DateTime` construído a partir dos argumentos fornecidos [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**DateTime a partir de ano, mês, dia, hora, minuto e segundo**
```sql title=Query theme={null}
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
```
```response title=Response theme={null}
┌────────────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**
```sql theme={null}
makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])
```
**Argumentos**
* `year` — Número do ano. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `month` — Número do mês (1-12). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `day` — Dia do mês (1-31). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `hour` — Hora (0-23). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `minute` — Minuto (0-59). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `second` — Segundo (0-59). [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `fraction` — Parte fracionária do segundo. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float) ou [`Decimal`](/pt-BR/reference/data-types/decimal)
* `precision` — Precisão da parte fracionária (0-9). [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `timezone` — Nome do fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um valor `DateTime64` construído a partir dos argumentos fornecidos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**DateTime64 a partir de ano, mês, dia, hora, minuto e segundo**
```sql title=Query theme={null}
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
monthName(datetime)
```
**Argumentos**
* `datetime` — Data ou data e hora. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o nome do mês. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Obter o nome do mês a partir de uma data**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
now([timezone])
```
**Aliases**: `current_timestamp`
**Argumentos**
* `timezone` — Opcional. Nome do fuso horário do valor retornado. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a data e a hora atuais. [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Consulta sem fuso horário**
```sql title=Query theme={null}
SELECT now()
```
```response title=Response theme={null}
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
```
**Consulta com fuso horário especificado**
```sql title=Query theme={null}
SELECT now('Asia/Istanbul')
```
```response title=Response theme={null}
┌─now('Asia/Istanbul')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
```
**Sintaxe padrão do SQL sem parênteses**
```sql title=Query theme={null}
SELECT NOW, CURRENT_TIMESTAMP
```
```response title=Response theme={null}
┌─────────────────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**
```sql theme={null}
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`](/pt-BR/reference/data-types/int-uint)
* `timezone` — Opcional. Nome do fuso horário para o valor retornado. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a data e a hora atuais com precisão de subsegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Consulta com precisão padrão e personalizada**
```sql title=Query theme={null}
SELECT now64(), now64(9, 'Asia/Istanbul')
```
```response title=Response theme={null}
┌─────────────────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`](#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**
```sql theme={null}
nowInBlock([timezone])
```
**Argumentos**
* `timezone` — Opcional. Nome do fuso horário do valor retornado. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a data e a hora atuais no momento em que cada bloco de dados é processado. [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Diferença em relação à função now()**
```sql title=Query theme={null}
SELECT
now(),
nowInBlock(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌───────────────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](#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**
```sql theme={null}
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`](/pt-BR/reference/data-types/int-uint)
* `timezone` — Opcional. Nome do fuso horário do valor retornado. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Diferença em relação à função now64()**
```sql title=Query theme={null}
SELECT
now64(),
nowInBlock64(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌─────────────────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`](/pt-BR/reference/settings/server-settings/settings#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**
```sql theme={null}
serverTimezone()
```
**Nomes alternativos**: `serverTimeZone`
**Argumentos**
* Nenhum.
**Valor retornado**
Retorna o fuso horário do servidor como uma [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT serverTimeZone()
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subDate(datetime, interval)
```
**Argumentos**
* `datetime` — A data ou data e hora da qual `interval` é subtraído. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `interval` — Intervalo a ser subtraído. [`Interval`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a data ou data e hora obtida ao subtrair `interval` de `datetime`. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair intervalo de uma data**
```sql title=Query theme={null}
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractDays(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual subtrair o número especificado de dias. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de dias a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` com `num` dias subtraídos [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair dias de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractHours(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual será subtraído o número especificado de horas. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de horas a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` horas, [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair horas de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractInterval(interval_1, interval_2)
```
**Argumentos**
* `interval_1` — Primeiro intervalo ou tupla de intervalos. [`Interval`](/pt-BR/reference/data-types/int-uint) ou [`Tuple(Interval)`](/pt-BR/reference/data-types/tuple)
* `interval_2` — Segundo intervalo a ser negado. [`Interval`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna uma tupla de intervalos [`Tuple(T)`](/pt-BR/reference/data-types/tuple)
**Exemplos**
**Subtração de intervalos**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql theme={null}
subtractMicroseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data com hora da qual será subtraído o número especificado de microssegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de microssegundos a serem subtraídos. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` microssegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair microssegundos de diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractMilliseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data e hora da qual será subtraído o número especificado de milissegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de milissegundos a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` milissegundos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair milissegundos de diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractMinutes(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual será subtraído o número especificado de minutos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de minutos a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` com `num` minutos subtraídos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair minutos de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractMonths(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual será subtraído o número especificado de meses. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de meses a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` meses. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair meses de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractNanoseconds(datetime, num)
```
**Argumentos**
* `datetime` — Data e hora da qual será subtraído o número especificado de nanossegundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de nanossegundos a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` nanossegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair nanossegundos de diferentes tipos de data e hora**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractQuarters(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual o número especificado de trimestres será subtraído. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de trimestres a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` com `num` trimestres subtraídos [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair trimestres de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractSeconds(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual será subtraído o número especificado de segundos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de segundos a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` segundos. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair segundos de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractTupleOfIntervals(datetime, intervals)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual subtrair intervalos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `intervals` — Tupla de intervalos a subtrair de `datetime`. [`Tuple(Interval)`](/pt-BR/reference/data-types/tuple)
**Valor retornado**
Retorna `date` com os `intervals` subtraídos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair uma tupla de intervalos de uma data**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractWeeks(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual subtrair o número especificado de semanas. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de semanas a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` semanas [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtração de semanas em diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
subtractYears(datetime, num)
```
**Argumentos**
* `datetime` — Data ou data e hora da qual o número especificado de anos será subtraído. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/string)
* `num` — Número de anos a subtrair. [`(U)Int*`](/pt-BR/reference/data-types/int-uint) ou [`Float*`](/pt-BR/reference/data-types/float)
**Valor retornado**
Retorna `datetime` menos `num` anos. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Subtrair anos de diferentes tipos de data**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─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`](#dateDiff).
**Sintaxe**
```sql theme={null}
timeDiff(startdate, enddate)
```
**Argumentos**
* `startdate` — O primeiro valor de tempo a ser subtraído (o subtraendo). [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `enddate` — O segundo valor de tempo do qual será subtraído o primeiro (o minuendo). [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a diferença entre `enddate` e `startdate`, expressa em segundos. [`Int64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Calcular a diferença de tempo em segundos**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌───res─┐
│ 90000 │
└───────┘
```
**Calcular a diferença de tempo e converter em horas**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
```
```response title=Response theme={null}
┌─hours─┐
│ 25 │
└───────┘
```
**Equivalente a dateDiff em segundos**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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**
```sql theme={null}
timeSlot(time[, time_zone])
```
**Argumentos**
* `time` — Hora a ser arredondada para o início de um intervalo de meia hora. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `time_zone` — Opcional. Um valor constante do tipo String ou uma expressão que representa o fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna a hora arredondada para o início de um intervalo de meia hora. [`DateTime`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Arredondar a hora para um intervalo de meia hora**
```sql title=Query theme={null}
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
timeSlots(StartTime, Duration[, Size])
```
**Argumentos**
* `StartTime` — Horário de início do intervalo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `Duration` — Duração do intervalo em segundos. [`UInt32`](/pt-BR/reference/data-types/int-uint) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `Size` — Opcional. Tamanho dos intervalos de tempo em segundos. O padrão é 1800 (30 minutos). [`UInt32`](/pt-BR/reference/data-types/int-uint) ou [`DateTime64`](/pt-BR/reference/data-types/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)`](/pt-BR/reference/data-types/array) ou [`Array(DateTime64)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Gerar intervalos de tempo para um intervalo**
```sql title=Query theme={null}
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 title=Response theme={null}
┌─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)`](/pt-BR/reference/data-types/datetime64).
Se um segundo argumento `expr_time` for informado, adiciona o horário especificado ao valor convertido.
**Sintaxe**
```sql theme={null}
timestamp(expr[, expr_time])
```
**Argumentos**
* `expr` — Data ou data e hora. [`String`](/pt-BR/reference/data-types/string)
* `expr_time` — Opcional. Horário a ser adicionado ao valor convertido. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o valor convertido de `expr` ou `expr` com o horário adicionado [`DateTime64(6)`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Converter string de data em DateTime64(6)**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
```
**Adicionar horário à string de data**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────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**
```sql theme={null}
timezone()
```
**Aliases**: `timeZone`
**Argumentos**
* Nenhum.
**Valor retornado**
Retorna o nome canônico do fuso horário na forma de uma [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT timezone()
```
```response title=Response theme={null}
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘
```
## timezoneOf
Introduzido na versão: v21.4.0
Retorna o nome do fuso horário de um valor [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64).
**Sintaxe**
```sql theme={null}
timezoneOf(datetime)
```
**Aliases**: `timeZoneOf`
**Argumentos**
* `datetime` — Um valor do tipo [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Nome do fuso horário para o qual converter o valor `datetime`. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o nome do fuso horário do `datetime` [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT timezoneOf(now());
```
```response title=Response theme={null}
┌─timezoneOf(now())─┐
│ Europe/Amsterdam │
└───────────────────┘
```
## timezoneOffset
Introduzido em: v21.6.0
Retorna o deslocamento do fuso horário em segundos em relação ao [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
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**
```sql theme={null}
timezoneOffset(datetime)
```
**Aliases**: `timeZoneOffset`
**Argumentos**
* `datetime` — valor `DateTime` para obter o deslocamento do fuso horário. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o deslocamento em relação a UTC, em segundos [`Int32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
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 title=Response theme={null}
┌────────────────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**
```sql theme={null}
toDayOfMonth(datetime)
```
**Aliases**: `DAY`, `DAYOFMONTH`
**Argumentos**
* `datetime` — Data ou data e hora da qual se obtém o dia do mês. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o dia do mês da data/hora especificada [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toDayOfWeek(datetime[, mode[, timezone]])
```
**Aliases**: `DAYOFWEEK`
**Argumentos**
* `datetime` — Data ou data e hora da qual se obtém o dia da semana. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `mode` — Opcional. Inteiro que especifica o modo da semana (0–3). O padrão é 0 se for omitido. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `timezone` — Opcional. Fuso horário a ser usado na conversão. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o dia da semana para o `Date` ou `DateTime` informado [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
-- 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 title=Response theme={null}
┌─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**
```sql theme={null}
toDayOfYear(datetime)
```
**Aliases**: `DAYOFYEAR`
**Argumentos**
* `datetime` — Data ou data e hora da qual será obtido o dia do ano. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o dia do ano da `Date` ou `DateTime` especificada [`UInt16`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toDaysInMonth(datetime)
```
**Argumentos**
* `datetime` — Data ou data e hora a partir da qual obter o número de dias no mês. [`Date`](/pt-BR/reference/data-types/date) or [`Date32`](/pt-BR/reference/data-types/date32) or [`DateTime`](/pt-BR/reference/data-types/datetime) or [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de dias no mês da data/hora informada. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─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](https://en.wikipedia.org/wiki/Year_zero) no
[calendário gregoriano proléptico definido pela ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
O cálculo é o mesmo da função [`TO_DAYS`](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_to-days) do MySQL.
**Sintaxe**
```sql theme={null}
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`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `time_zone` — Fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o número de dias decorridos desde a data `0000-01-01`. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Calcular os dias desde o ano zero**
```sql title=Query theme={null}
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toHour(datetime)
```
**Aliases**: `HOUR`
**Argumentos**
* `datetime` — Data e hora da qual será extraída a hora. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a hora (0-23) de `datetime`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toISOWeek(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data ou data e hora a partir da qual obter o número da semana ISO. [`Date`](/pt-BR/reference/data-types/date) or [`DateTime`](/pt-BR/reference/data-types/datetime) or [`Date32`](/pt-BR/reference/data-types/date32) or [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter os números das semanas ISO**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │ 52 │
└────────────┴─────────┘
```
**A semana ISO pode pertencer a um ano diferente**
```sql title=Query theme={null}
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
```
```response title=Response theme={null}
┌───────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**
```sql theme={null}
toISOYear(datetime)
```
**Argumentos**
* `datetime` — O valor com data ou com data e hora. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o valor de entrada convertido em um número de ano ISO. [`UInt16`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter o ano ISO de valores de data**
```sql title=Query theme={null}
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toLastDayOfMonth(value)
```
**Aliases**: `LAST_DAY`
**Argumentos**
* `value` — A data ou data e hora a ser arredondada para o último dia do mês. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data do último dia do mês para a data ou data e hora fornecida. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredondar para o último dia do mês**
```sql title=Query theme={null}
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toLastDayOfWeek(datetime[, mode[, timezone]])
```
**Argumentos**
* `datetime` — Uma data ou data com hora para converter. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `mode` — Determina o primeiro dia da semana, conforme descrito na função `toWeek()`. O padrão é `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32)
**Exemplos**
**Arredondar para cima até o sábado ou domingo mais próximo**
```sql title=Query theme={null}
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 title=Response theme={null}
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
```
## toMillisecond
Introduzido em: v24.2.0
Retorna o componente de milissegundos (0–999) de um valor `DateTime` ou `DateTime64`.
**Sintaxe**
```sql theme={null}
toMillisecond(datetime)
```
**Aliases**: `MILLISECOND`
**Argumentos**
* `datetime` — Data e hora da qual obter o milissegundo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o milissegundo do minuto (0 - 59) em `datetime`. [`UInt16`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
```
```response title=Response theme={null}
┌──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**
```sql theme={null}
toMinute(datetime)
```
**Aliases**: `MINUTE`
**Argumentos**
* `datetime` — Data e hora da qual obter o minuto. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o minuto da hora (0 - 59) de `datetime`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│ 20 │
└─────────────────────────────────────────────┘
```
## toModifiedJulianDay
Introduzido em: v21.1.0
Converte uma data do [calendário gregoriano proléptico](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) em formato de texto `YYYY-MM-DD` em um número de [Dia Juliano Modificado](https://en.wikipedia.org/wiki/Julian_day#Variants), 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**
```sql theme={null}
toModifiedJulianDay(date)
```
**Argumentos**
* `date` — A data em formato String. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
**Valor retornado**
Retorna o número do Dia Juliano Modificado. [`Int32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Converter data para Dia Juliano Modificado**
```sql title=Query theme={null}
SELECT toModifiedJulianDay('2020-01-01')
```
```response title=Response theme={null}
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
```
## toModifiedJulianDayOrNull
Introduzido em: v21.1.0
Semelhante a [`toModifiedJulianDay()`](#toModifiedJulianDay), mas, em vez de lançar exceções, retorna `NULL`.
**Sintaxe**
```sql theme={null}
toModifiedJulianDayOrNull(date)
```
**Argumentos**
* `date` — Data em formato de texto. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
**Valor retornado**
Retorna o número do Dia Juliano Modificado para `date` válido; caso contrário, `null`. [`Nullable(Int32)`](/pt-BR/reference/data-types/nullable)
**Exemplos**
**Converter data para Dia Juliano Modificado com tratamento de null**
```sql title=Query theme={null}
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- data inválida, retorna NULL
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toMonday(value)
```
**Argumentos**
* `value` — Data ou data com hora a ser arredondada para a segunda-feira da semana. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data da segunda-feira da mesma semana para a data ou data com hora fornecida. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredonde para a segunda-feira da semana**
```sql title=Query theme={null}
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Uma sexta-feira
toMonday(toDate('2023-04-24')); -- Já é uma segunda-feira
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toMonth(datetime)
```
**Aliases**: `MONTH`
**Argumentos**
* `datetime` — Data ou data com hora da qual obter o mês. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o mês da data/hora fornecida [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 4 │
└────────────────────────────────────────────┘
```
## toMonthNumSinceEpoch
Introduzido em: v25.3.0
Retorna a quantidade de meses decorridos desde 1970
**Sintaxe**
```sql theme={null}
toMonthNumSinceEpoch(date)
```
**Argumentos**
* `date` — Uma data ou data e hora. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Inteiro positivo
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
657
```
## toQuarter
Introduzido em: v1.1.0
Retorna o trimestre do ano (1 a 4) de um determinado valor `Date` ou `DateTime`.
**Sintaxe**
```sql theme={null}
toQuarter(datetime)
```
**Aliases**: `QUARTER`
**Argumentos**
* `datetime` — Data ou data com horário da qual obter o trimestre do ano. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o trimestre do ano da data/hora fornecida [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeDayNum(date)
```
**Argumentos**
* `date` — Data ou data com hora. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de dias desde um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos de dias**
```sql title=Query theme={null}
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeHourNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de horas a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos de hora**
```sql title=Query theme={null}
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeMinuteNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de minutos a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos de minutos**
```sql title=Query theme={null}
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeMonthNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de meses a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos do mês**
```sql title=Query theme={null}
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeQuarterNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de trimestres a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos de trimestre**
```sql title=Query theme={null}
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeSecondNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de segundos a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos de segundos**
```sql title=Query theme={null}
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeWeekNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de semanas a partir de um ponto de referência fixo no passado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números de semana relativos**
```sql title=Query theme={null}
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toRelativeYearNum(date)
```
**Argumentos**
* `date` — Data ou data com horário. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o número de anos a partir de um ponto de referência fixo no passado. [`UInt16`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obter números relativos do ano**
```sql title=Query theme={null}
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
```
```response title=Response theme={null}
┌─minus(toRela⋯ateTime')))─┐
│ 10 │
└──────────────────────────┘
```
## toSecond
Introduzido em: v1.1.0
Retorna o componente de segundos (0-59) de um valor `DateTime` ou `DateTime64`.
**Sintaxe**
```sql theme={null}
toSecond(datetime)
```
**Aliases**: `SECOND`
**Argumentos**
* `datetime` — Data e hora da qual obter o segundo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o segundo do minuto (0 - 59) de `datetime`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfDay(datetime)
```
**Argumentos**
* `datetime` — Uma data ou data com hora para arredondar. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime)
**Valor retornado**
Retorna a data com hora arredondada para baixo até o início do dia. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Arredondar para baixo até o início do dia**
```sql title=Query theme={null}
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfFifteenMinutes(datetime)
```
**Argumentos**
* `datetime` — Uma data ou data e hora para arredondar. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data e hora arredondada para o início do intervalo de quinze minutos mais próximo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
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 title=Response theme={null}
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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfFiveMinutes(datetime)
```
**Aliases**: `toStartOfFiveMinute`
**Argumentos**
* `datetime` — Uma data e hora para arredondar. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data e hora arredondada para o início do intervalo de cinco minutos mais próximo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
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 title=Response theme={null}
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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfHour(datetime)
```
**Argumentos**
* `datetime` — Uma data com hora a ser arredondada. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data com hora arredondada para baixo para o início da hora. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Arredondar para baixo para o início da hora**
```sql title=Query theme={null}
SELECT
toStartOfHour(toDateTime('2023-04-21 10:20:30'));
```
```response title=Response theme={null}
┌─────────────────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](https://en.wikipedia.org/wiki/ISO_week_date).
O tipo de retorno pode ser configurado pela configuração [`enable_extended_results_for_datetime_functions`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfISOYear(value)
```
**Argumentos**
* `value` — A data ou data com hora a ser arredondada para o primeiro dia do ano ISO. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o primeiro dia do ano ISO para a data ou data com hora informada. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredondar para o primeiro dia do ano ISO**
```sql title=Query theme={null}
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
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`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Arredondamento básico de intervalos**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
```
```response title=Response theme={null}
┌─toStartOfInt⋯alMonth(1))─┐
│ 2023-01-01 │
└──────────────────────────┘
```
**Usando o ponto de origem**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toStartOfMicrosecond(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data e hora. [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Valor de entrada com submicrossegundos [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Consulta sem fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
```
**Consulta com fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toStartOfMillisecond(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data e hora. [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Valor de entrada com frações de milissegundo. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Consulta sem fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
```
**Consulta com fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfMinute(datetime)
```
**Argumentos**
* `datetime` — Uma data com hora a ser arredondada. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data com hora arredondada para baixo, até o início do minuto. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Arredondar para baixo até o início do minuto**
```sql title=Query theme={null}
SELECT
toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
```
```response title=Response theme={null}
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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfMonth(value)
```
**Argumentos**
* `value` — A data ou data com hora a ser arredondada para baixo para o primeiro dia do mês. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o primeiro dia do mês para a data ou data com hora fornecida. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredondar para baixo para o primeiro dia do mês**
```sql title=Query theme={null}
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toStartOfNanosecond(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data e hora. [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Valor de entrada com precisão de nanossegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Consulta sem fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
```
```response title=Response theme={null}
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
```
**Consulta com fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfQuarter(value)
```
**Argumentos**
* `value` — A data ou data com hora a ser arredondada para baixo até o primeiro dia do trimestre. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o primeiro dia do trimestre da data ou data com hora fornecida. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredondar para baixo até o primeiro dia do trimestre**
```sql title=Query theme={null}
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toStartOfSecond(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data e hora das quais remover as frações de segundo. [`DateTime64`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o valor de entrada sem frações de segundo. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Consulta sem fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
```
```response title=Response theme={null}
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
```
**Consulta com fuso horário**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfTenMinutes(datetime)
```
**Argumentos**
* `datetime` — Uma data e hora. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna a data e hora arredondada para o início do intervalo de dez minutos mais próximo. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
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 title=Response theme={null}
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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfWeek(datetime[, mode[, timezone]])
```
**Argumentos**
* `datetime` — Uma data ou data com hora a ser convertida. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `mode` — Determina o primeiro dia da semana, conforme descrito na função `toWeek()`. O padrão é `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32)
**Exemplos**
**Arredondar para baixo para o domingo ou a segunda-feira mais próximos**
```sql title=Query theme={null}
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 title=Response theme={null}
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`](/pt-BR/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Sintaxe**
```sql theme={null}
toStartOfYear(value)
```
**Argumentos**
* `value` — A data ou data com hora a ser arredondada para baixo. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o primeiro dia do ano da data/hora fornecida [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Arredondar para baixo para o primeiro dia do ano**
```sql title=Query theme={null}
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toTimeWithFixedDate(date[, timezone])
```
**Argumentos**
* `date` — Data a ser convertida em hora. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário do valor retornado. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/datetime)
**Exemplos**
**Calcular a diferença de tempo entre duas datas**
```sql title=Query theme={null}
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toTimezone(datetime, timezone)
```
**Aliases**: `toTimeZone`
**Argumentos**
* `date` — O valor a ser convertido. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — O nome do fuso horário de destino. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o mesmo timestamp de entrada, mas com o fuso horário especificado [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
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 title=Response theme={null}
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**
```sql theme={null}
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`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `time_zone` — Um valor constante do tipo String ou uma expressão que representa o fuso horário. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna uma data ou data com hora no fuso horário UTC. [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Exemplos**
**Converter o fuso horário para UTC**
```sql title=Query theme={null}
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toUnixTimestamp(date[, timezone])
```
**Argumentos**
* `date` — Valor a ser convertido. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o timestamp Unix. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
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 title=Response theme={null}
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()`](#toWeek) é 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`](/pt-BR/reference/data-types/string) em um formato compatível com [`parseDateTime64BestEffort()`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#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**
```sql theme={null}
toWeek(datetime[, mode[, time_zone]])
```
**Aliases**: `week`
**Argumentos**
* `datetime` — Data ou data com hora da qual obter o número da semana. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o número da semana de acordo com o modo especificado. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obtenha números de semana com modos diferentes**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
```
```response title=Response theme={null}
┌───────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**
```sql theme={null}
toYYYYMM(datetime[, timezone])
```
**Argumentos**
* `datetime` — Uma data ou data com hora a ser convertida. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário para a conversão. Se informado, o fuso horário deve ser uma constante de string. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um número UInt32 com o ano e o número do mês (YYYY \* 100 + MM). [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Converte a data atual para o formato YYYYMM**
```sql title=Query theme={null}
SELECT toYYYYMM(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toYYYYMMDD(datetime[, timezone])
```
**Argumentos**
* `datetime` — Uma data ou uma data com hora a ser convertida. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário para a conversão. Se informado, o fuso horário deve ser uma constante de string. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Converter a data atual para o formato YYYYMMDD**
```sql title=Query theme={null}
SELECT toYYYYMMDD(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toYYYYMMDDhhmmss(datetime[, timezone])
```
**Argumentos**
* `datetime` — Data ou data com hora a ser convertida. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `timezone` — Opcional. Fuso horário da conversão. Se informado, o fuso horário deve ser uma constante de string. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Converter a data e hora atuais para o formato YYYYMMDDhhmmss**
```sql title=Query theme={null}
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│ 20230302112209 │
└───────────────────────────────────────┘
```
## toYear
Introduzido em: v1.1.0
Retorna o ano (d.C.) de um valor `Date` ou `DateTime`.
**Sintaxe**
```sql theme={null}
toYear(datetime)
```
**Aliases**: `YEAR`
**Argumentos**
* `datetime` — Data ou data com hora da qual extrair o ano. [`Date`](/pt-BR/reference/data-types/date) ou [`Date32`](/pt-BR/reference/data-types/date32) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Retorna o ano do valor [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) fornecido, como [`UInt16`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─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**
```sql theme={null}
toYearNumSinceEpoch(date)
```
**Argumentos**
* `date` — Uma data ou uma data com hora para converter. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`DateTime64`](/pt-BR/reference/data-types/datetime64)
**Valor retornado**
Inteiro positivo
**Exemplos**
**Exemplo**
```sql title=Query theme={null}
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
54
```
## 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()`](/pt-BR/reference/functions/regular-functions/date-time-functions#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`](/pt-BR/reference/data-types/string), em um formato compatível com [`parseDateTime64BestEffort()`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#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**
```sql theme={null}
toYearWeek(datetime[, mode[, timezone]])
```
**Aliases**: `yearweek`
**Argumentos**
* `datetime` — Data ou data com hora da qual obter o ano e a semana. [`Date`](/pt-BR/reference/data-types/date) ou [`DateTime`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o ano e o número da semana como um único valor inteiro. [`UInt32`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Obtenha combinações de ano-semana com diferentes modos**
```sql title=Query theme={null}
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 title=Response theme={null}
┌───────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**
```sql theme={null}
today()
```
**Aliases**: `curdate`, `current_date`
**Argumentos**
* Nenhum.
**Valor retornado**
Retorna a data atual [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ today ┃ curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │ 2025-03-03 │
└────────────┴────────────┴──────────────┘
```
**Sintaxe padrão do SQL sem parênteses**
```sql title=Query theme={null}
SELECT TODAY, CURDATE,CURRENT_DATE
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ 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**
```sql theme={null}
yesterday()
```
**Argumentos**
* Nenhum.
**Valor retornado**
Retorna a data de ontem. [`Date`](/pt-BR/reference/data-types/date)
**Exemplos**
**Obter a data de ontem**
```sql title=Query theme={null}
SELECT yesterday();
SELECT today() - 1;
```
```response title=Response theme={null}
┌─yesterday()─┐
│ 2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│ 2025-06-09 │
└───────────────────┘
```