Adding upstream version 15.4.upstream/15.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 90 insertions, 0 deletions

diff --git a/doc/src/sgml/keywords.sgml b/doc/src/sgml/keywords.sgml
new file mode 100644
index 0000000..a7bf30c
--- /dev/null
+++ b/doc/src/sgml/keywords.sgml
@@ -0,0 +1,90 @@
+<!-- doc/src/sgml/keywords.sgml -->
+
+<appendix id="sql-keywords-appendix">
+ <title><acronym>SQL</acronym> Key Words</title>
+
+ <indexterm zone="sql-keywords-appendix">
+  <primary>key word</primary>
+  <secondary>list of</secondary>
+ </indexterm>
+
+ <para>
+  <xref linkend="keywords-table"/> lists all tokens that are key words
+  in the SQL standard and in <productname>PostgreSQL</productname>
+  &version;.  Background information can be found in <xref
+  linkend="sql-syntax-identifiers"/>.
+  (For space reasons, only the latest two versions of the SQL standard, and
+  SQL-92 for historical comparison, are included.  The differences between
+  those and the other intermediate standard versions are small.)
+ </para>
+
+ <para>
+  SQL distinguishes between <firstterm>reserved</firstterm> and
+  <firstterm>non-reserved</firstterm> key words.  According to the standard,
+  reserved key words
+  are the only real key words; they are never allowed as identifiers.
+  Non-reserved key words only have a special meaning in particular
+  contexts and can be used as identifiers in other contexts.  Most
+  non-reserved key words are actually the names of built-in tables
+  and functions specified by SQL.  The concept of non-reserved key
+  words essentially only exists to declare that some predefined meaning
+  is attached to a word in some contexts.
+ </para>
+
+ <para>
+  In the <productname>PostgreSQL</productname> parser, life is a bit
+  more complicated. There are several different classes of tokens
+  ranging from those that can never be used as an identifier to those
+  that have absolutely no special status in the parser, but are considered
+  ordinary identifiers.  (The latter is usually the case for
+  functions specified by SQL.)  Even reserved key words are not
+  completely reserved in <productname>PostgreSQL</productname>, but
+  can be used as column labels (for example, <literal>SELECT 55 AS
+  CHECK</literal>, even though <token>CHECK</token> is a reserved key
+  word).
+ </para>
+
+ <para>
+  In <xref linkend="keywords-table"/> in the column for
+  <productname>PostgreSQL</productname> we classify as
+  <quote>non-reserved</quote> those key words that are explicitly
+  known to the parser but are allowed as column or table names.
+  Some key words that are otherwise
+  non-reserved cannot be used as function or data type names and are
+  marked accordingly.  (Most of these words represent built-in
+  functions or data types with special syntax.  The function or type
+  is still available but it cannot be redefined by the user.)  Labeled
+  <quote>reserved</quote> are those tokens that are not allowed as
+  column or table names.  Some reserved key words are
+  allowable as names for functions or data types; this is also shown in the
+  table.  If not so marked, a reserved key word is only allowed as a
+  column label.
+  A blank entry in this column means that the word is treated as an
+  ordinary identifier by <productname>PostgreSQL</productname>.
+ </para>
+
+ <para>
+  Furthermore, while most key words can be used as <quote>bare</quote>
+  column labels without writing <literal>AS</literal> before them (as
+  described in <xref linkend="queries-column-labels"/>), there are a few
+  that require a leading <literal>AS</literal> to avoid ambiguity.  These
+  are marked in the table as <quote>requires <literal>AS</literal></quote>.
+ </para>
+
+ <para>
+  As a general rule, if you get spurious parser errors for commands
+  that use any of the listed key words as an identifier, you should
+  try quoting the identifier to see if the problem goes away.
+ </para>
+
+ <para>
+  It is important to understand before studying <xref
+  linkend="keywords-table"/> that the fact that a key word is not
+  reserved in <productname>PostgreSQL</productname> does not mean that
+  the feature related to the word is not implemented.  Conversely, the
+  presence of a key word does not indicate the existence of a feature.
+ </para>
+
+ &keywords-table;
+
+</appendix>