From a37cc29483fbb881f6643a910e4c2e8b450a620f 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 v56 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 4c4febb94b4..aab8917ac0a 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>
+   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