EXTRACT(field FROM source)

The <function>extract</function> function retrieves subfields such as year or hour from date/time values. <replaceable>source</replaceable> must be a value expression of type <type>timestamp</type>, <type>date</type>, <type>time</type>, or <type>interval</type>. (Timestamps and times can be with or without time zone.) <replaceable>field</replaceable> is an identifier or string that selects what field to extract from the source value. Not all fields are valid for every input data type; for example, fields smaller than a day cannot be extracted from a <type>date</type>, while fields of a day or more cannot be extracted from a <type>time</type>. The <function>extract</function> function returns values of type <type>numeric</type>. extract関数は、日付/時刻の値から年や時などの部分フィールドを抽出します。 sourceはtimestamp、date、time、interval型の値式でなければなりません。 （timestampとtimeは、タイムゾーンの有無に関わらず指定できます。） fieldはsourceの値からどのフィールドを抽出するかを選択する識別子もしくは文字列です。 すべての入力データ型に対してすべてのフィールドが有効であるとは限りません。 たとえば、1日より小さいフィールドはdateから抽出できませんし、1日以上のフィールドはtimeから抽出できません。 extract関数はnumeric型の値を返します。

The following are valid field names: 以下は有効なフィールド名です。 alphabetical

When processing an <type>interval</type> value, the <function>extract</function> function produces field values that match the interpretation used by the interval output function. This can produce surprising results if one starts with a non-normalized interval representation, for example: interval値を処理する場合、extract関数は、interval出力関数で使用される解釈と一致するフィールド値を生成します。 これは、非正規化されたINTERVALでの表示から始めた場合、驚くべき結果を生じる可能性があります。 例えば次のようになります。

SELECT INTERVAL '80 minutes';
Result: 01:20:00
SELECT EXTRACT(MINUTES FROM INTERVAL '80 minutes');
Result: 20

The <function>extract</function> function is primarily intended for computational processing. For formatting date/time values for display, see <xref linkend="functions-formatting"/>. extract関数は主に演算処理を意図しています。 日付/時刻の値を表示する目的での書式については9.8を参照してください。

The <function>date_part</function> function is modeled on the traditional <productname>Ingres</productname> equivalent to the <acronym>SQL</acronym>-standard function <function>extract</function>: date_part関数は伝統的なIngres上で設計されたもので、標準SQLのextract関数と等価です。

date_part('field', source)

Note that here the <replaceable>field</replaceable> parameter needs to be a string value, not a name. The valid field names for <function>date_part</function> are the same as for <function>extract</function>. For historical reasons, the <function>date_part</function> function returns values of type <type>double precision</type>. This can result in a loss of precision in certain uses. Using <function>extract</function> is recommended instead. ここでfieldパラメータが名前ではなく文字列値である必要があることに注意してください。 date_partで有効なフィールド名はextractと同じです。 歴史的な理由により、date_part関数はdouble precision型の結果を返します。 場合によってはこれによって精度が失われることがあります。 extractを代わりに使うことをお勧めします。

SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
Result: 4

The function <function>date_trunc</function> is conceptually similar to the <function>trunc</function> function for numbers. date_trunc関数は概念的に数値に対するtrunc関数と類似しています。

date_trunc(field, source [, time_zone ])

<replaceable>source</replaceable> is a value expression of type <type>timestamp</type>, <type>timestamp with time zone</type>, or <type>interval</type>. (Values of type <type>date</type> and <type>time</type> are cast automatically to <type>timestamp</type> or <type>interval</type>, respectively.) <replaceable>field</replaceable> selects to which precision to truncate the input value. The return value is likewise of type <type>timestamp</type>, <type>timestamp with time zone</type>, or <type>interval</type>, and it has all fields that are less significant than the selected one set to zero (or one, for day and month). sourceは、データ型timestamp、timestamp with time zoneもしくはintervalの値式です。 （date型とtime型の値はそれぞれ自動的にtimestampもしくはintervalにキャストされます。） fieldは、入力値の値をどの精度で切り捨てるかを選択します。 同様に戻り値はtimestamp、timestamp with time zoneもしくはinterval型で、指定した精度より下のすべてのフィールドがゼロに設定（日と月については1に設定）されます。

Valid values for <replaceable>field</replaceable> are: fieldの有効値には次のものがあります。

When the input value is of type <type>timestamp with time zone</type>, the truncation is performed with respect to a particular time zone; for example, truncation to <literal>day</literal> produces a value that is midnight in that zone. By default, truncation is done with respect to the current <xref linkend="guc-timezone"/> setting, but the optional <replaceable>time_zone</replaceable> argument can be provided to specify a different time zone. The time zone name can be specified in any of the ways described in <xref linkend="datatype-timezones"/>. 入力値がtimestamp with time zone型の値なら、特定の時間帯を考慮して切り捨てが行われます。たとえば、日を切り捨てると値はその時間帯での真夜中になります。 デフォルトでは切り捨ては現在のTimeZoneの設定に従いますが、別の時間帯を指定することができるようにオプションのtime_zone引数が提供されています。 時間帯名は8.5.3に記述されている方法で指定できます。

A time zone cannot be specified when processing <type>timestamp without time zone</type> or <type>interval</type> inputs. These are always taken at face value. timestamp without time zoneあるいはintervalの入力を処理している間は時間帯は指定できません。 これらは額面通りの値で扱われます。

Examples (assuming the local time zone is <literal>America/New_York</literal>): 例（現地タイムゾーンはAmerica/New_Yorkと仮定します）：

SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-02-16 20:00:00
SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-01-01 00:00:00
SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00');
Result: 2001-02-16 00:00:00-05
SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/Sydney');
Result: 2001-02-16 08:00:00-05
SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
Result: 3 days 02:00:00

The function <function>date_bin</function> <quote>bins</quote> the input timestamp into the specified interval (the <firstterm>stride</firstterm>) aligned with a specified origin. 関数date_binは、指定した原点に揃えて入力のタイムスタンプを指定した時間間隔(stride)に「分類」します。

date_bin(stride, source, origin)

<replaceable>source</replaceable> is a value expression of type <type>timestamp</type> or <type>timestamp with time zone</type>. (Values of type <type>date</type> are cast automatically to <type>timestamp</type>.) <replaceable>stride</replaceable> is a value expression of type <type>interval</type>. The return value is likewise of type <type>timestamp</type> or <type>timestamp with time zone</type>, and it marks the beginning of the bin into which the <replaceable>source</replaceable> is placed. sourceはtimestampあるいはtimestamp with time zone型の値式です。 （date型の値はtimestampに自動キャストされます。） strideはinterval型の値式です。 戻り値は同様に、timestampあるいはtimestamp with time zone型で、sourceが置かれた箱の開始位置に印を付けています。

Examples: 例を示します。

SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01');
Result: 2020-02-11 15:30:00
SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00:02:30');
Result: 2020-02-11 15:32:30

In the case of full units (1 minute, 1 hour, etc.), it gives the same result as the analogous <function>date_trunc</function> call, but the difference is that <function>date_bin</function> can truncate to an arbitrary interval. 完全な単位(1分、1時間など)の場合は、これは類似のdate_truncの呼び出しと同じ結果を与えます。 違いは、date_binは任意の間隔へと切り捨てられることです。

The <parameter>stride</parameter> interval must be greater than zero and cannot contain units of month or larger. stride間隔はゼロより大きくなければならず、かつ月単位あるいはそれよりも大きくてはいけません。

The <literal>AT TIME ZONE</literal> operator converts time stamp <emphasis>without</emphasis> time zone to/from time stamp <emphasis>with</emphasis> time zone, and <type>time with time zone</type> values to different time zones. <xref linkend="functions-datetime-zoneconvert-table"/> shows its variants. AT TIME ZONE構文を使用することにより、time stamp without time zoneからtime stamp with time zoneへ、あるいはtime with time zoneの値を異なる時間帯に変換することができます。 表 9.34にその種類を示します。

In these expressions, the desired time zone <replaceable>zone</replaceable> can be specified either as a text value (e.g., <literal>'America/Los_Angeles'</literal>) or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>). In the text case, a time zone name can be specified in any of the ways described in <xref linkend="datatype-timezones"/>. The interval case is only useful for zones that have fixed offsets from UTC, so it is not very common in practice. これらの式では、設定する時間帯zoneは、（'America/Los_Angeles'のような）テキスト値、または（INTERVAL '-08:00'のような）時間間隔で指定することができます。 テキストの場合、8.5.3に示した方法で時間帯名称を指定することができます。 時間間隔を使うのはUTCからの固定のオフセットを持つ時間帯でのみ有用なので、一般的に非常に有用であるとは言えません。

The syntax <literal>AT LOCAL</literal> may be used as shorthand for <literal>AT TIME ZONE <replaceable>local</replaceable></literal>, where <replaceable>local</replaceable> is the session's <varname>TimeZone</varname> value. 構文AT LOCALは、AT TIME ZONE localの省略形として使用できます。 ここで、localはセッションのTimeZone値です。

Examples (assuming the current <xref linkend="guc-timezone"/> setting is <literal>America/Los_Angeles</literal>): 以下に例を示します（現在の時間帯（TimeZone）をAmerica/Los_Angelesと想定しています）。

SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
Result: 2001-02-16 19:38:40-08
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
Result: 2001-02-16 18:38:40
SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
Result: 2001-02-16 05:38:40
SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
Result: 2001-02-16 17:38:40
SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
Result: 17:38:40

The first example adds a time zone to a value that lacks it, and displays the value using the current <varname>TimeZone</varname> setting. The second example shifts the time stamp with time zone value to the specified time zone, and returns the value without a time zone. This allows storage and display of values different from the current <varname>TimeZone</varname> setting. The third example converts Tokyo time to Chicago time. The fourth example shifts the time stamp with time zone value to the time zone currently specified by the <varname>TimeZone</varname> setting and returns the value without a time zone. 最初の例は、時間帯のない値に時間帯を追加し、現在のTimeZone設定を使ってその値を表示します。 2番目の例は、time stamp with time zone値を指定した時間帯に変換し、その値をwithout a time zoneで返しています。 これは、TimeZone設定とは異なる値の格納と表示を可能にします。 3番目の例は、東京時間をシカゴ時間に変換します。 4番目の例は、タイムスタンプをTimeZone設定で指定された現在のタイムゾーンにシフトし、タイムゾーンなしで値を返します。

The fifth example is a cautionary tale. Due to the fact that there is no date associated with the input value, the conversion is made using the current date of the session. Therefore, this static example may show a wrong result depending on the time of the year it is viewed because <literal>'America/Los_Angeles'</literal> observes Daylight Savings Time. 第5の例は警告を含みます。 入力値に日付が関連付けられていないため、変換はセッションの現在の日付を使用して行われます。 したがって、この静的な例は、'America/Los_Angeles'がサマータイムを使用しているため、表示される年の時期によっては誤った結果を示す可能性があります。

The function <literal><function>timezone</function>(<replaceable>zone</replaceable>, <replaceable>timestamp</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>timestamp</replaceable> AT TIME ZONE <replaceable>zone</replaceable></literal>. 関数timezone(zone, timestamp)は、SQL準拠の構文timestamp AT TIME ZONE zoneと等価です。

The function <literal><function>timezone</function>(<replaceable>zone</replaceable>, <replaceable>time</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>time</replaceable> AT TIME ZONE <replaceable>zone</replaceable></literal>. 関数timezone(zone, time)は、SQL準拠の構文time AT TIME ZONE zoneと等価です。

The function <literal><function>timezone</function>(<replaceable>timestamp</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>timestamp</replaceable> AT LOCAL</literal>. 関数timezone(timestamp)は、SQL準拠の構文timestamp AT LOCALと等価です。

The function <literal><function>timezone</function>(<replaceable>time</replaceable>)</literal> is equivalent to the SQL-conforming construct <literal><replaceable>time</replaceable> AT LOCAL</literal>. 関数timezone(time)は、SQL準拠の構文time AT LOCALと等価です。

<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: PostgreSQLは、現在の日付時刻に関した値を返す多くの関数を提供します。 これらの標準SQL関数はすべて、現在のトランザクションの開始時刻に基づいた値を返します。

CURRENT_DATE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_TIME(precision)
CURRENT_TIMESTAMP(precision)
LOCALTIME
LOCALTIMESTAMP
LOCALTIME(precision)
LOCALTIMESTAMP(precision)

<function>CURRENT_TIME</function> and <function>CURRENT_TIMESTAMP</function> deliver values with time zone; <function>LOCALTIME</function> and <function>LOCALTIMESTAMP</function> deliver values without time zone. CURRENT_TIMEおよびCURRENT_TIMESTAMP関数では、時間帯を伴う値を扱います。一方、LOCALTIMEおよびLOCALTIMESTAMP関数では、時間帯を伴わない値を扱います。

<function>CURRENT_TIME</function>, <function>CURRENT_TIMESTAMP</function>, <function>LOCALTIME</function>, and <function>LOCALTIMESTAMP</function> can optionally take a precision parameter, which causes the result to be rounded to that many fractional digits in the seconds field. Without a precision parameter, the result is given to the full available precision. CURRENT_TIME、CURRENT_TIMESTAMP、LOCALTIME、およびLOCALTIMESTAMP関数では、精度のパラメータをオプションで取ることができ、それに合わせて秒フィールドの端数桁を丸める結果をもたらします。 精度のパラメータがない場合、結果は使用可能な最大精度で出力されます。

Some examples: 例を示します。

SELECT CURRENT_TIME;
Result: 14:39:53.662522-05
SELECT CURRENT_DATE;
Result: 2019-12-23
SELECT CURRENT_TIMESTAMP;
Result: 2019-12-23 14:39:53.662522-05
SELECT CURRENT_TIMESTAMP(2);
Result: 2019-12-23 14:39:53.66-05
SELECT LOCALTIMESTAMP;
Result: 2019-12-23 14:39:53.662522

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. これらの関数は現在のトランザクションの開始時刻を返すため、その値はトランザクションが実行されている間は変化しません。 これは仕様であると考えられており、その意図は、単一のトランザクションが一貫性のある「現在」時刻の概念を持ち、同一トランザクション内の複数の変更が同一のタイムスタンプを持つようにすることにあります。

<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: PostgreSQLはまた、関数を呼び出した時の実際の現在時刻や現在の文の開始時刻を返す関数も提供します。 非標準SQLの時間関数の全一覧を以下に示します。

transaction_timestamp()
statement_timestamp()
clock_timestamp()
timeofday()
now()

<function>transaction_timestamp()</function> is equivalent to <function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect what it returns. <function>statement_timestamp()</function> 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()</function> and <function>transaction_timestamp()</function> return the same value during the first command of a transaction, but might differ during subsequent commands. <function>clock_timestamp()</function> returns the actual current time, and therefore its value changes even within a single SQL command. <function>timeofday()</function> is a historical <productname>PostgreSQL</productname> function. Like <function>clock_timestamp()</function>, it returns the actual current time, but as a formatted <type>text</type> string rather than a <type>timestamp with time zone</type> value. <function>now()</function> is a traditional <productname>PostgreSQL</productname> equivalent to <function>transaction_timestamp()</function>. transaction_timestamp()はCURRENT_TIMESTAMPと等価ですが、明確に何を返すかを反映する名前になっています。 statement_timestamp()は現在の文の実行開始時刻を返すものです（より具体的にいうと、直前のコマンドメッセージをクライアントから受け取った時刻です）。 statement_timestamp()およびtransaction_timestamp()はトランザクションの最初のコマンドでは同じ値を返しますが、その後に引き続くコマンドでは異なる可能性があります。 clock_timestamp()は実際の現在時刻を返しますので、その値は単一のSQLコマンドであっても異なります。 timeofday()はPostgreSQLの歴史的な関数です。 clock_timestamp()同様、実際の現在時刻を返しますが、timestamp with time zone型の値ではなく、整形されたtext文字列を返します。now()はtransaction_timestamp()と同じもので、伝統的なPostgreSQL関数です。

All the date/time data types also accept the special literal value <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: すべての日付/時刻型はまた、特殊なリテラル値 nowを受け付け、これは現在の日付と時刻（ここでも、トランザクションの開始時刻として解釈されます）を表します。 したがって、下記の３つの実行結果は全て同じものとなります。

SELECT CURRENT_TIMESTAMP;
SELECT now();
SELECT TIMESTAMP 'now';  -- but see tip below

The following functions are available to delay execution of the server process: 以下の関数は、サーバプロセスの実行を遅延させるために使用可能です。

pg_sleep ( double precision )
pg_sleep_for ( interval )
pg_sleep_until ( timestamp with time zone )

<function>pg_sleep</function> makes the current session's process sleep until the given number of seconds have elapsed. Fractional-second delays can be specified. <function>pg_sleep_for</function> is a convenience function to allow the sleep time to be specified as an <type>interval</type>. <function>pg_sleep_until</function> is a convenience function for when a specific wake-up time is desired. For example: pg_sleepは、指定された秒数が経過するまで、現在のセッションのプロセスを休止させます。 小数秒の遅延を指定することができます。 pg_sleep_forはintervalでより長い休止時間を指定する便利な関数です。 pg_sleep_untilは特定の起床時刻が望まれる場合に便利な関数です。 以下に例を示します。

SELECT pg_sleep(1.5);
SELECT pg_sleep_for('5 minutes');
SELECT pg_sleep_until('tomorrow 03:00');