From 598528744b9c103aa74f19c9d773f63dd1b7b49e 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 v52 03/10] 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 908fb6e0dab..ecaba2eed2f 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