Skip to content

Commit

Permalink
Merge pull request #3681 from cockroachdb/remove_timetz
Browse files Browse the repository at this point in the history
Removed content for timetz
  • Loading branch information
Amruta-Ranade authored Aug 30, 2018
2 parents 8bfae21 + 9e073fa commit 539c5c8
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 47 deletions.
1 change: 0 additions & 1 deletion v2.1/data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ Type | Description | Example
[`SERIAL`](serial.html) | A unique 64-bit signed integer. | `148591304110702593 `
[`STRING`](string.html) | A string of Unicode characters. | `'a1b2c3'`
[`TIME`](time.html) | A time of day in UTC. | `TIME '01:23:45.123456'`
[`TIMETZ`](time.html) | A time of day with a time zone offset from UTC. **Not recommended for use at this time. For details, see [`TIMETZ`](time.html#timetz-warning).** | `TIMETZ '01:23:45.123456-5:00'`
[`TIMESTAMP`](timestamp.html) | A date and time pairing in UTC. | `TIMESTAMP '2016-01-25 10:10:10'`
[`TIMESTAMPTZ`](timestamp.html) | A date and time pairing with a time zone offset from UTC. | `TIMESTAMPTZ '2016-01-25 10:10:10-05:00'`
[`UUID`](uuid.html) | A 128-bit hexadecimal value. | `7f9c24e8-3b12-4fef-91e0-56a2d5a246ec`
Expand Down
56 changes: 10 additions & 46 deletions v2.1/time.md
Original file line number Diff line number Diff line change
@@ -1,72 +1,36 @@
---
title: TIME
summary: The TIME data type stores a time of day in UTC, whereas TIMETZ stores a time of day with a time zone offset from UTC.
summary: The TIME data type stores a time of day in UTC.
toc: true
---
The `TIME` [data type](data-types.html) stores the time of day in UTC, whereas `TIMETZ` stores a time of day with a time zone offset from UTC.


## Variants

`TIME` has two variants:

- `TIME` presents all `TIME` values in UTC.

- `TIMETZ` converts `TIME` values from UTC to the client's session time zone (unless another time zone is specified for the value). However, it is conceptually important to note that `TIMETZ` **does not** store any time zone data.

<a name="timetz-warning"></a>

{{site.data.alerts.callout_danger}}
Use of `TIMETZ` is not recommended at this time. The current implementation is incomplete. The feature will be retracted or corrected in a future release. If corrected, the fix will be backwards-incompatible. For details, see [cockroachdb#25224](https://github.com/cockroachdb/cockroach/issues/25224).
{{site.data.alerts.end}}

{{site.data.alerts.callout_info}}
The default session time zone is UTC, which means that by default `TIMETZ` values display in UTC.
{{site.data.alerts.end}}

The difference between these two variants is that `TIMETZ` uses the client's session time zone, while `TIME` does not. This behavior extends to [functions like `now()` and `extract()`](functions-and-operators.html#date-and-time-functions) on `TIMETZ` values.

## Best practices

We recommend always using `TIME` because the `TIMETZ` variant can lead to unexpected behavior when:

- Comparing `TIMETZ` instances using [operators such as `>`](functions-and-operators.html#operators)
- [Ordering query results](query-order.html) which include `TIMETZ` values in time order, e.g., `SELECT * FROM table ORDER BY column_with_timetz_type`.

[Like Postgres](https://www.postgresql.org/docs/current/static/datatype-datetime.html), we implement the `TIMETZ` variant for [SQL standards compliance](sql-feature-support.html), and also because it is used by ORMs like [Hibernate](build-a-java-app-with-cockroachdb-hibernate.html).
The `TIME` [data type](data-types.html) stores the time of day in UTC.

## Aliases

The `TIME` data types are aliased as shown below.
In CockroachDB, the following are aliases:

Alias | Long Version
---------|-------------
`TIME` | `TIME WITHOUT TIME ZONE`
`TIMETZ` | `TIME WITH TIME ZONE`
`TIME WITHOUT TIME ZONE`

## Syntax

A constant value of type `TIME`/`TIMETZ` can be expressed using an
A constant value of type `TIME` can be expressed using an
[interpreted literal](sql-constants.html#interpreted-literals), or a
string literal
[annotated with](scalar-expressions.html#explicitly-typed-expressions)
type `TIME`/`TIMETZ` or
type `TIME` or
[coerced to](scalar-expressions.html#explicit-type-coercions) type
`TIME`/`TIMETZ`.
`TIME`.

The string format for time is `HH:MM:SS.SSSSSS`. For example: `TIME '05:40:00.000001'`.

To express a `TIMETZ` value (with time zone offset from UTC), use
the following format: `TIMETZ '10:10:10.555555-05:00'`

When it is unambiguous, a simple unannotated [string literal](sql-constants.html#string-literals) can also
be automatically interpreted as type `TIME` or `TIMETZ`.
be automatically interpreted as type `TIME`.

Note that the fractional portion of `TIME`/`TIMETZ` is optional and is rounded to microseconds (i.e., six digits after the decimal) for compatibility with the [PostgreSQL wire protocol](https://www.postgresql.org/docs/current/static/protocol.html).
Note that the fractional portion of `TIME` is optional and is rounded to microseconds (i.e., six digits after the decimal) for compatibility with the [PostgreSQL wire protocol](https://www.postgresql.org/docs/current/static/protocol.html).

## Size

A `TIME`/`TIMETZ` column supports values up to 8 bytes in width, but the total storage size is likely to be larger due to CockroachDB metadata.
A `TIME` column supports values up to 8 bytes in width, but the total storage size is likely to be larger due to CockroachDB metadata.

## Example

Expand Down

0 comments on commit 539c5c8

Please sign in to comment.