syntax.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.85.2.3 2003/11/06 22:21:55 tgl Exp $
-->

<chapter id="sql-syntax">
 <title>SQL Syntax</title>

 <indexterm zone="sql-syntax">
  <primary>syntax</primary>
  <secondary>SQL</secondary>
 </indexterm>

 <para>
  This chapter describes the syntax of SQL.  It forms the foundation
  for understanding the following chapters which will go into detail
  about how the SQL commands are applied to define and modify data.
 </para>

 <para>
  We also advise users who are already familiar with SQL to read this
  chapter carefully because there are several rules and concepts that
  are implemented inconsistently among SQL databases or that are
  specific to <productname>PostgreSQL</productname>.
 </para>

 <sect1 id="sql-syntax-lexical">
  <title>Lexical Structure</title>

  <indexterm>
   <primary>token</primary>
  </indexterm>

  <para>
   SQL input consists of a sequence of
   <firstterm>commands</firstterm>.  A command is composed of a
   sequence of <firstterm>tokens</firstterm>, terminated by a
   semicolon (<quote>;</quote>).  The end of the input stream also
   terminates a command.  Which tokens are valid depends on the syntax
   of the particular command.
  </para>

  <para>
   A token can be a <firstterm>key word</firstterm>, an
   <firstterm>identifier</firstterm>, a <firstterm>quoted
   identifier</firstterm>, a <firstterm>literal</firstterm> (or
   constant), or a special character symbol.  Tokens are normally
   separated by whitespace (space, tab, newline), but need not be if
   there is no ambiguity (which is generally only the case if a
   special character is adjacent to some other token type).
  </para>

  <para>
   Additionally, <firstterm>comments</firstterm> can occur in SQL
   input.  They are not tokens, they are effectively equivalent to
   whitespace.
  </para>

   <para>
    For example, the following is (syntactically) valid SQL input:
<programlisting>
SELECT * FROM MY_TABLE;
UPDATE MY_TABLE SET A = 5;
INSERT INTO MY_TABLE VALUES (3, 'hi there');
</programlisting>
    This is a sequence of three commands, one per line (although this
    is not required; more than one command can be on a line, and
    commands can usefully be split across lines).
   </para>

  <para>
   The SQL syntax is not very consistent regarding what tokens
   identify commands and which are operands or parameters.  The first
   few tokens are generally the command name, so in the above example
   we would usually speak of a <quote>SELECT</quote>, an
   <quote>UPDATE</quote>, and an <quote>INSERT</quote> command.  But
   for instance the <command>UPDATE</command> command always requires
   a <token>SET</token> token to appear in a certain position, and
   this particular variation of <command>INSERT</command> also
   requires a <token>VALUES</token> in order to be complete.  The
   precise syntax rules for each command are described in <xref linkend="reference">.
  </para>

  <sect2 id="sql-syntax-identifiers">
   <title>Identifiers and Key Words</title>

   <indexterm zone="sql-syntax-identifiers">
    <primary>identifier</primary>
    <secondary>syntax of</secondary>
   </indexterm>

   <indexterm zone="sql-syntax-identifiers">
    <primary>name</primary>
    <secondary>syntax of</secondary>
   </indexterm>

   <indexterm zone="sql-syntax-identifiers">
    <primary>key word</primary>
    <secondary>syntax of</secondary>
   </indexterm>

   <para>
    Tokens such as <token>SELECT</token>, <token>UPDATE</token>, or
    <token>VALUES</token> in the example above are examples of
    <firstterm>key words</firstterm>, that is, words that have a fixed
    meaning in the SQL language.  The tokens <token>MY_TABLE</token>
    and <token>A</token> are examples of
    <firstterm>identifiers</firstterm>.  They identify names of
    tables, columns, or other database objects, depending on the
    command they are used in.  Therefore they are sometimes simply
    called <quote>names</quote>.  Key words and identifiers have the
    same lexical structure, meaning that one cannot know whether a
    token is an identifier or a key word without knowing the language.
    A complete list of key words can be found in <xref
    linkend="sql-keywords-appendix">.
   </para>

   <para>
    SQL identifiers and key words must begin with a letter
    (<literal>a</literal>-<literal>z</literal>, but also letters with
    diacritical marks and non-Latin letters) or an underscore
    (<literal>_</literal>).  Subsequent characters in an identifier or
    key word can be letters, underscores, digits
    (<literal>0</literal>-<literal>9</literal>), or dollar signs
    (<literal>$</>).  Note that dollar signs are not allowed in identifiers
    according to the letter of the SQL standard, so their use may render
    applications less portable.
    The SQL standard will not define a key word that contains
    digits or starts or ends with an underscore, so identifiers of this
    form are safe against possible conflict with future extensions of the
    standard.
   </para>

   <para>
    <indexterm><primary>identifier</primary><secondary>length</secondary></indexterm>
    The system uses no more than <symbol>NAMEDATALEN</symbol>-1
    characters of an identifier; longer names can be written in
    commands, but they will be truncated.  By default,
    <symbol>NAMEDATALEN</symbol> is 64 so the maximum identifier
    length is 63. If this limit is problematic, it can be raised by
    changing the <symbol>NAMEDATALEN</symbol> constant in
    <filename>src/include/postgres_ext.h</filename>.
   </para>

   <para>
    <indexterm>
     <primary>case sensitivity</primary>
     <secondary>of SQL commands</secondary>
    </indexterm>
    Identifier and key word names are case insensitive.  Therefore
<programlisting>
UPDATE MY_TABLE SET A = 5;
</programlisting>
    can equivalently be written as
<programlisting>
uPDaTE my_TabLE SeT a = 5;
</programlisting>
    A convention often used is to write key words in upper
    case and names in lower case, e.g.,
<programlisting>
UPDATE my_table SET a = 5;
</programlisting>
   </para>

   <para>
    <indexterm>
     <primary>quotation marks</primary>
     <secondary>and identifiers</secondary>
    </indexterm>
    There is a second kind of identifier:  the <firstterm>delimited
    identifier</firstterm> or <firstterm>quoted
    identifier</firstterm>.  It is formed by enclosing an arbitrary
    sequence of characters in double-quotes
    (<literal>"</literal>). <!-- " font-lock mania --> A delimited
    identifier is always an identifier, never a key word.  So
    <literal>"select"</literal> could be used to refer to a column or
    table named <quote>select</quote>, whereas an unquoted
    <literal>select</literal> would be taken as a key word and
    would therefore provoke a parse error when used where a table or
    column name is expected.  The example can be written with quoted
    identifiers like this:
<programlisting>
UPDATE "my_table" SET "a" = 5;
</programlisting>
   </para>

   <para>
    Quoted identifiers can contain any character other than a double
    quote itself.  (To include a double quote, write two double quotes.)
    This allows constructing table or column names that would
    otherwise not be possible, such as ones containing spaces or
    ampersands.  The length limitation still applies.
   </para>

   <para>
    Quoting an identifier also makes it case-sensitive, whereas
    unquoted names are always folded to lower case.  For example, the
    identifiers <literal>FOO</literal>, <literal>foo</literal>, and
    <literal>"foo"</literal> are considered the same by
    <productname>PostgreSQL</productname>, but
    <literal>"Foo"</literal> and <literal>"FOO"</literal> are
    different from these three and each other.  (The folding of
    unquoted names to lower case in <productname>PostgreSQL</> is
    incompatible with the SQL standard, which says that unquoted names
    should be folded to upper case.  Thus, <literal>foo</literal>
    should be equivalent to <literal>"FOO"</literal> not
    <literal>"foo"</literal> according to the standard.  If you want
    to write portable applications you are advised to always quote a
    particular name or never quote it.)
   </para>
  </sect2>


  <sect2 id="sql-syntax-constants">
   <title>Constants</title>

   <indexterm zone="sql-syntax-constants">
    <primary>constant</primary>
   </indexterm>

   <para>
    There are three kinds of <firstterm>implicitly-typed
    constants</firstterm> in <productname>PostgreSQL</productname>:
    strings, bit strings, and numbers.
    Constants can also be specified with explicit types, which can
    enable more accurate representation and more efficient handling by
    the system. The implicit constants are described below; explicit
    constants are discussed afterwards.
   </para>

   <sect3 id="sql-syntax-strings">
    <title>String Constants</title>

    <indexterm zone="sql-syntax-strings">
     <primary>character string</primary>
     <secondary>constant</secondary>
    </indexterm>

    <para>
     <indexterm>
      <primary>quotation marks</primary>
      <secondary>escaping</secondary>
     </indexterm>
     A string constant in SQL is an arbitrary sequence of characters
     bounded by single quotes (<literal>'</literal>), e.g., <literal>'This
     is a string'</literal>.  SQL allows single quotes to be embedded
     in strings by typing two adjacent single quotes, e.g.,
     <literal>'Dianne''s horse'</literal>.  In
     <productname>PostgreSQL</productname> single quotes may
     alternatively be escaped with a backslash (<literal>\</literal>),
     e.g., <literal>'Dianne\'s horse'</literal>.
    </para>

    <para>
     C-style backslash escapes are also available:
     <literal>\b</literal> is a backspace, <literal>\f</literal> is a
     form feed, <literal>\n</literal> is a newline,
     <literal>\r</literal> is a carriage return, <literal>\t</literal>
     is a tab, and <literal>\<replaceable>xxx</replaceable></literal>,
     where <replaceable>xxx</replaceable> is an octal number, is a
     byte with the corresponding code.  (It is your responsibility
     that the byte sequences you create are valid characters in the
     server character set encoding.)  Any other character following a
     backslash is taken literally.  Thus, to include a backslash in a
     string constant, type two backslashes.
    </para>

    <para>
     The character with the code zero cannot be in a string constant.
    </para>

    <para>
     Two string constants that are only separated by whitespace
     <emphasis>with at least one newline</emphasis> are concatenated
     and effectively treated as if the string had been written in one
     constant.  For example:
<programlisting>
SELECT 'foo'
'bar';
</programlisting>
     is equivalent to
<programlisting>
SELECT 'foobar';
</programlisting>
     but
<programlisting>
SELECT 'foo'      'bar';
</programlisting>
     is not valid syntax.  (This slightly bizarre behavior is specified
     by <acronym>SQL</acronym>; <productname>PostgreSQL</productname> is
     following the standard.)
    </para>
   </sect3>

   <sect3 id="sql-syntax-bit-strings">
    <title>Bit-String Constants</title>

    <indexterm zone="sql-syntax-bit-strings">
     <primary>bit string</primary>
     <secondary>constant</secondary>
    </indexterm>

    <para>
     Bit-string constants look like string constants with a
     <literal>B</literal> (upper or lower case) immediately before the
     opening quote (no intervening whitespace), e.g.,
     <literal>B'1001'</literal>.  The only characters allowed within
     bit-string constants are <literal>0</literal> and
     <literal>1</literal>.
    </para>

    <para>
     Alternatively, bit-string constants can be specified in hexadecimal
     notation, using a leading <literal>X</literal> (upper or lower case),
     e.g., <literal>X'1FF'</literal>.  This notation is equivalent to
     a bit-string constant with four binary digits for each hexadecimal digit.
    </para>

    <para>
     Both forms of bit-string constant can be continued
     across lines in the same way as regular string constants.
    </para>
   </sect3>

   <sect3>
    <title>Numeric Constants</title>

    <indexterm>
     <primary>number</primary>
     <secondary>constant</secondary>
    </indexterm>

    <para>
     Numeric constants are accepted in these general forms:
<synopsis>
<replaceable>digits</replaceable>
<replaceable>digits</replaceable>.<optional><replaceable>digits</replaceable></optional><optional>e<optional>+-</optional><replaceable>digits</replaceable></optional>
<optional><replaceable>digits</replaceable></optional>.<replaceable>digits</replaceable><optional>e<optional>+-</optional><replaceable>digits</replaceable></optional>
<replaceable>digits</replaceable>e<optional>+-</optional><replaceable>digits</replaceable>
</synopsis>
     where <replaceable>digits</replaceable> is one or more decimal
     digits (0 through 9).  At least one digit must be before or after the
     decimal point, if one is used.  At least one digit must follow the
     exponent marker (<literal>e</literal>), if one is present.
     There may not be any spaces or other characters embedded in the
     constant.  Note that any leading plus or minus sign is not actually
     considered part of the constant; it is an operator applied to the
     constant.
    </para>

    <para>
     These are some examples of valid numeric constants:
<literallayout>
42
3.5
4.
.001
5e2
1.925e-3
</literallayout>
    </para>

    <para>
     <indexterm><primary>integer</primary></indexterm>
     <indexterm><primary>bigint</primary></indexterm>
     <indexterm><primary>numeric</primary></indexterm>
     A numeric constant that contains neither a decimal point nor an
     exponent is initially presumed to be type <type>integer</> if its
     value fits in type <type>integer</> (32 bits); otherwise it is
     presumed to be type <type>bigint</> if its
     value fits in type <type>bigint</> (64 bits); otherwise it is
     taken to be type <type>numeric</>.  Constants that contain	decimal
     points and/or exponents are always initially presumed to be type
     <type>numeric</>.
    </para>