Skip to content
Snippets Groups Projects
Commit eaf8f312 authored by Tom Lane's avatar Tom Lane
Browse files

Some editorial work on the documentation of the current-date/time 

functions.
parent aaf125f8
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 70 additions and 42 deletions
doc/src/sgml/func.sgml
+ 70
− 42
View file @ eaf8f312
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.322 2006/06/18 15:38:35 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.323 2006/06/19 16:13:01 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
......@@ -5357,7 +5357,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>current_date</function></literal></entry>
<entry><type>date</type></entry>
<entry>Today's date; see <xref linkend="functions-datetime-current">
<entry>Current date;
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5366,7 +5367,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>current_time</function></literal></entry>
<entry><type>time with time zone</type></entry>
<entry>Time of day; see <xref linkend="functions-datetime-current">
<entry>Current time of day;
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5375,7 +5377,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>current_timestamp</function></literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Date and time of start of current transaction; see <xref linkend="functions-datetime-current">
<entry>Current date and time (start of current transaction);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5384,8 +5387,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>date_part</function>(<type>text</type>, <type>timestamp</type>)</literal></entry>
<entry><type>double precision</type></entry>
<entry>Get subfield (equivalent to
<function>extract</function>); see <xref linkend="functions-datetime-extract">
<entry>Get subfield (equivalent to <function>extract</function>);
see <xref linkend="functions-datetime-extract">
</entry>
<entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
<entry><literal>20</literal></entry>
......@@ -5473,7 +5476,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>localtime</function></literal></entry>
<entry><type>time</type></entry>
<entry>Time of day; see <xref linkend="functions-datetime-current">
<entry>Current time of day;
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5482,7 +5486,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>localtimestamp</function></literal></entry>
<entry><type>timestamp</type></entry>
<entry>Date and time; see <xref linkend="functions-datetime-current">
<entry>Current date and time (start of current transaction);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5491,8 +5496,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>now</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Date and time of start of current transaction (equivalent to
<function>CURRENT_TIMESTAMP</function>); see <xref linkend="functions-datetime-current">
<entry>Current date and time (start of current transaction);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5501,8 +5506,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>transaction_timestamp</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Date and time of start of current transaction (equivalent to
<function>CURRENT_TIMESTAMP</function>); see <xref linkend="functions-datetime-current">
<entry>Current date and time (start of current transaction);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5511,7 +5516,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>statement_timestamp</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Date and time of start of current statement; see <xref linkend="functions-datetime-current">
<entry>Current date and time (start of current statement);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5520,7 +5526,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>clock_timestamp</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>Current date and time (changes during statement execution); see <xref linkend="functions-datetime-current">
<entry>Current date and time (changes during statement execution);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -5529,8 +5536,9 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>timeofday</function>()</literal></entry>
<entry><type>text</type></entry>
<entry>Current date and time (like <function>clock_timestamp</>), but as a Unix-style <type>text</> value;
see <xref linkend="functions-datetime-current">
<entry>Current date and time
(like <function>clock_timestamp</>, but as a <type>text</> string);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
......@@ -6118,7 +6126,7 @@ SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
</sect2>
<sect2 id="functions-datetime-current">
<title>Date/Time of Transaction Start</title>
<title>Current Date/Time</title>
<indexterm>
<primary>date</primary>
......@@ -6131,8 +6139,10 @@ SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
</indexterm>
<para>
The following functions are available to obtain the date and/or
time of the start of the current transaction:
<productname>PostgreSQL</productname> provides a number of functions
that return values related to the current date and time. These
SQL-standard functions all return values based on the start time of
the current transaction:
<synopsis>
CURRENT_DATE
CURRENT_TIME
......@@ -6185,43 +6195,61 @@ SELECT LOCALTIMESTAMP;
</para>
<para>
It is important to know that
<function>CURRENT_TIMESTAMP</function> and related functions return
the start time of the current transaction; their values do not
Since these functions return
the start time of the current transaction, their values do not
change during the transaction. This is considered a feature:
the intent is to allow a single transaction to have a consistent
notion of the <quote>current</quote> time, so that multiple
modifications within the same transaction bear the same
time stamp. Consider using <function>statement_timestamp</> or
<function>clock_timestamp</> if you need something that changes
more frequently.
time stamp.
</para>
<note>
<para>
Other database systems may advance these values more
frequently.
</para>
</note>
<para>
<function>CURRENT_TIMESTAMP</> might not be the
transaction start time on other database systems.
For this reason, and for completeness,
<function>transaction_timestamp</> is provided.
The function <function>now()</function> is the traditional
<productname>PostgreSQL</productname> equivalent to
the SQL-standard <function>CURRENT_TIMESTAMP</function>.
<productname>PostgreSQL</productname> also provides functions that
return the start time of the current statement, as well as the actual
current time at the instant the function is called. The complete list
of non-SQL-standard time functions is:
<synopsis>
now()
transaction_timestamp()
statement_timestamp()
clock_timestamp()
timeofday()
</synopsis>
</para>
<para>
<function>STATEMENT_TIMESTAMP</> is the time the statement
arrived at the server from the client. It is not the time
the command started execution. If multiple commands were
sent as a single query string to the server, each command
has the same <function>STATEMENT_TIMESTAMP</> because they
all arrived at the same time. Also, commands executed
by server-side functions have a <function>STATEMENT_TIMESTAMP</>
based on the time the client sent the query that triggered
the function, not the time the function was executed.
<function>now()</> is a traditional <productname>PostgreSQL</productname>
equivalent to <function>CURRENT_TIMESTAMP</function>.
<function>transaction_timestamp()</> is likewise equivalent to
<function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
what it returns.
<function>statement_timestamp()</> returns the start time of the current
statement (more specifically, the time of receipt of the latest command
message from the client).
<function>statement_timestamp()</> and <function>transaction_timestamp()</>
return the same value during the first command of a transaction, but may
differ during subsequent commands.
<function>clock_timestamp()</> returns the actual current time, and
therefore its value changes even within a single SQL command.
<function>timeofday()</> is a historical
<productname>PostgreSQL</productname> function. Like
<function>clock_timestamp()</>, it returns the actual current time,
but as a formatted <type>text</> string rather than a <type>timestamp
with time zone</> value.
</para>
<para>
All the date/time data types also accept the special literal value
<literal>now</literal> to specify the current date and time. Thus,
<literal>now</literal> to specify the current date and time (again,
interpreted as the transaction start time). Thus,
the following three all return the same result:
<programlisting>
SELECT CURRENT_TIMESTAMP;
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment