From bb305d42de6e314a6b99a0ddd6f980f6d9edec49 Mon Sep 17 00:00:00 2001
From: "Paul A. Jungwirth" <pj@illuminatedcomputing.com>
Date: Tue, 17 Jun 2025 23:23:23 -0700
Subject: [PATCH v57 03/11] Document temporal PERIODs

We don't support these yet, so we just explain the concept, say that we
use ranges and multiranges, and say that we plan to support PERIODs in
the future.

Author: Paul A. Jungwirth <pj@illuminatedcomputing.com>
---
 doc/src/sgml/temporal.sgml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/src/sgml/temporal.sgml b/doc/src/sgml/temporal.sgml
index 08c76991290..f54b0a6b284 100644
--- a/doc/src/sgml/temporal.sgml
+++ b/doc/src/sgml/temporal.sgml
@@ -15,6 +15,35 @@
    tables.
   </para>
 
+ <sect1 id="periods">
+  <title>Periods</title>
+
+  <indexterm zone="periods">
+   <primary>periods</primary>
+  </indexterm>
+
+  <para>
+   A <firstterm>period</firstterm> is metadata attached to a table
+   uniting two columns, a start time and end time, into one range-like
+   construct. Periods are used to represent <link
+   linkend="system-time">system time</link> and <link
+   linkend="application-time">application time</link>. A system-time
+   period must be named <literal>system_time</literal>, and an
+   application-time period can be named anything else. Their names must
+   not conflict with column names from the same table.
+  </para>
+
+  <para>
+   Application-time periods are referenced in several temporal operations described in
+   this chapter: temporal primary keys, unique constraints, foreign keys,
+   update commands, and delete commands.
+   <productname>PostgreSQL</productname> does not yet support periods.
+   Commands that accept periods instead accept columns with a
+   <link linkend="rangetypes-builtin">rangetype or multirangetype</link>.
+   Support for periods is planned for the future.
+  </para>
+ </sect1>
+
  <sect1 id="application-time">
   <title>Application Time</title>
 
-- 
2.39.5