From 107783a5a2659baa28c3541782c634b9528a2f3f 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 v55 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