Project: YugabyteDB (App Definition and Development / Database)
File: toc.md

title: Date-time types ToC [YSQL] headerTitle: Table of contents for the date-time data types section linkTitle: Section contents description: Overview and content map of the date-time types section. menu: v2.18: identifier: toc parent: api-ysql-datatypes-datetime weight: 31 type: docs This section is the top of the entire date-time documentation subtree. Its siblings are the top-of-subtree pages for other data types like and . It presents a table that summarizes the properties of the date-time data types, and that links to the dedicated sections for each of these. It recommends avoiding the timetz datatype and states that it will not, therefore, be treated in the data-time major section. For completeness, it presents a table of the special date-time manifest constants and recommends that you avoid using all of these except for 'infinity' and '-infinity'. Finally, it lists the date-time subsections that cover just those topics that you will need to understand if your purpose is only to write brand-new application code. This section explains the background for the accounts of the date-time data types. In particular, it explains the notions that underly the sensitivity to the reigning timezone of these operations: . . This section explains: the purpose and significance of the set timezone SQL statement; the at time zone operator for plain timestamp and timestamptz expressions; the various other ways that, ultimately, the intended UTC offset is specified; and which operations are sensitive to the specified UTC offset. It has these child pages: - - - - It's resolved case-insensitively. It's never resolved in pgtimezonenames.abbrev. It's never resolved in pgtimezoneabbrevs.abbrev as the argument of set timezone but is resolved there as the argument of at time zone (and, equivalently, in timezone()) and as the argument of maketimestamptz() (and equivalently within a text literal for a timestamptz_ value). It's is resolved first in pgtimezoneabbrevs.abbrev and, only if this fails, then in pgtimezonenames.name. This applies only in those syntax contexts where pgtimezoneabbrevs.abbrev is a candidate for the resolutionso not for set timezone, which looks only in pgtimezonenames.name. Many of the code examples rely on typecastingespecially from/to text values to/from plain timestamp and timestamptz values. It's unlikely that you'll use such typecasting in actual application

(Rather, you'll use dedicated built-in functions for the conversions.) But you'll rely heavily on typecasting for ad hoc tests while you develop such code. This section defines the semantics of the date data type, the time data type, the plain timestamp and timestamptz data types, and the interval data type. Interval arithmetic is rather tricky. This explains the size of the subsection that's devoted to this data type. The section has these child pages: - - - - - - - This section presents the five-by-five matrix of all possible conversions between values of the date-time datatypes. Many of the cells are empty because they correspond to operations that aren't supported (or, because the cell is on the diagonal representing the conversion between values of the same data type, it's tautologically uninteresting). This still leaves twenty typecasts whose semantics you need to understand. However, many can be understood as combinations of others, and this leaves only a few that demand careful study. The critical conversions are between plain timestamp and timestamptz values in each direction. This section describes the date-time operators and presents tests for them grouped as follows: This section describes the general-purpose date-time functions in the following groups: This section describes: The use of the tochar() built-in function for converting a date-time value to a text_ value. The use of the todate() and totimestamp() built-in functions for converting a text value to a date-time value. The conversions, in each direction, are controlled by a so-called template. A template, in turn, is made up of a mixture of pre-defined so-called template patterns and free text in a user-defined order. See the section . These template patterns, again in turn, can be modified. See the section . This shows you how to implement a SQL stopwatch that allows you to start it with a procedure call before starting what you want to time and to read it with a select statement when what you want to time finishes. This reading goes to the spool file along with all other select results. Using a SQL stopwatch brings many advantages over using \\timing on. This short page gives the instructions for downloading and installing all of the reusable code that's defined within this date-time data types major section.