1 files changed, 71 insertions, 0 deletions
diff --git a/doc/src/sgml/tsm-system-time.sgml b/doc/src/sgml/tsm-system-time.sgml
new file mode 100644
index 0000000..df6e83a
--- /dev/null
+++ b/doc/src/sgml/tsm-system-time.sgml
@@ -0,0 +1,71 @@
+<!-- doc/src/sgml/tsm-system-time.sgml -->
+
+<sect1 id="tsm-system-time" xreflabel="tsm_system_time">
+ <title>tsm_system_time</title>
+
+ <indexterm zone="tsm-system-time">
+  <primary>tsm_system_time</primary>
+ </indexterm>
+
+ <para>
+  The <filename>tsm_system_time</filename> module provides the table sampling method
+  <literal>SYSTEM_TIME</literal>, which can be used in
+  the <literal>TABLESAMPLE</literal> clause of a <link linkend="sql-select"><command>SELECT</command></link>
+  command.
+ </para>
+
+ <para>
+  This table sampling method accepts a single floating-point argument that
+  is the maximum number of milliseconds to spend reading the table.  This
+  gives you direct control over how long the query takes, at the price that
+  the size of the sample becomes hard to predict.  The resulting sample will
+  contain as many rows as could be read in the specified time, unless the
+  whole table has been read first.
+ </para>
+
+ <para>
+  Like the built-in <literal>SYSTEM</literal> sampling
+  method, <literal>SYSTEM_TIME</literal> performs block-level sampling, so
+  that the sample is not completely random but may be subject to clustering
+  effects, especially if only a small number of rows are selected.
+ </para>
+
+ <para>
+  <literal>SYSTEM_TIME</literal> does not support
+  the <literal>REPEATABLE</literal> clause.
+ </para>
+
+ <para>
+  This module is considered <quote>trusted</quote>, that is, it can be
+  installed by non-superusers who have <literal>CREATE</literal> privilege
+  on the current database.
+ </para>
+
+ <sect2>
+  <title>Examples</title>
+
+  <para>
+   Here is an example of selecting a sample of a table with
+   <literal>SYSTEM_TIME</literal>.  First install the extension:
+  </para>
+
+<programlisting>
+CREATE EXTENSION tsm_system_time;
+</programlisting>
+
+  <para>
+   Then you can use it in a <command>SELECT</command> command, for instance:
+
+<programlisting>
+SELECT * FROM my_table TABLESAMPLE SYSTEM_TIME(1000);
+</programlisting>
+  </para>
+
+  <para>
+   This command will return as large a sample of <structname>my_table</structname> as
+   it can read in 1 second (1000 milliseconds).  Of course, if the whole
+   table can be read in under 1 second, all its rows will be returned.
+  </para>
+ </sect2>
+
+</sect1>