diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 15bfda8d2c8..596f91f818a 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -62,7 +62,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.27 2000/12/16 18:22:53 tgl - Any string can be specified as an identifier if surrounded by + Any string can be used as an identifier if surrounded by double quotes (like this!). Some care is required since such an identifier will be case sensitive and will retain embedded whitespace and most other special characters. @@ -361,7 +361,7 @@ UNCOMMITTED UNNAMED where the comment begins with "/*" and extends - to the first occurrence of "*/". These block + to the matching occurrence of "*/". These block comments nest, as specified in SQL99, so that one can comment out larger blocks of code which may contain existing block comments. @@ -381,7 +381,7 @@ UNCOMMITTED UNNAMED truncated. By default, NAMEDATALEN is 32 so the maximum name length is 31 (but at the time the system is built, NAMEDATALEN can be changed in - src/include/postgres_ext.h). + src/include/postgres_ext.h). @@ -408,8 +408,8 @@ UNCOMMITTED UNNAMED Constants - There are three implicitly typed constants - for use in Postgres: strings, integers, + There are three kinds of implicitly typed constants + in Postgres: strings, integers, and floating point numbers. Constants can also be specified with explicit types, which can enable more accurate representation and more efficient handling by the @@ -442,20 +442,10 @@ UNCOMMITTED UNNAMED Integer constants - in SQL are collection of ASCII digits with no decimal point. Legal - values range from -2147483648 to +2147483647. This will vary - depending on the operating system and host machine. - - - - Note that larger integers can be specified for int8 - by using SQL92 string notation or - Postgres type notation: - - -int8 '4000000000' -- string style -'4000000000'::int8 -- Postgres (historical) style - + in SQL are sequences of ASCII digits with no decimal point. + The range of legal values depends on which integer datatype is + used, but the plain integer type accepts values + ranging from -2147483648 to +2147483647. @@ -512,6 +502,28 @@ CAST ( 'string' AS type ) if there is no ambiguity as to the type the constant must be, in which case it is automatically coerced. + + + It is also possible to specify a type coercion using a function-like + syntax: + + +typename ( value ) + + + although this only works for types whose names are also valid as + function names. (For example, double precision + can't be used this way --- but the equivalent float8 + can.) + + + + The ::, CAST(), and function-call + syntaxes can also be used to specify run-time type conversions. But + the form type + 'string' can only be used to specify the + type of a literal constant. + @@ -519,18 +531,20 @@ CAST ( 'string' AS type ) Array constants - are arrays of any Postgres type, including other arrays, string - constants, etc. The general format of an array constant is the - following: + are n-dimensional arrays of any Postgres datatype. + The general format of an array constant is the following: -{val1delimval2delim} +{ val1 delim val2 delim ... } where delim - is the delimiter for the type stored in the pg_type class. - (For built-in types, this is the comma character (","). An - example of an array constant is + is the delimiter character for the type, as recorded in its + pg_type class entry. + (For all built-in types, this is the comma character ",".) + Each val is either a constant + of the array element type, or a sub-array. + An example of an array constant is {{1,2,3},{4,5,6},{7,8,9}} @@ -541,9 +555,12 @@ CAST ( 'string' AS type ) - Individual array elements can and should be placed between quotation - marks whenever possible to avoid ambiguity problems with respect to - leading white space. + Individual array elements can be placed between single-quote + marks to avoid ambiguity problems with respect to leading white space. + Without quote marks, the array-value parser will skip white space. + Note that to write a quote mark inside a string literal that is to + become an array value, you must double the quote mark as described + previously. @@ -556,7 +573,8 @@ CAST ( 'string' AS type ) A field - is either an attribute of a given class or one of the following: + is either a user-defined attribute of a given class or one of the + following system-defined attributes: @@ -564,8 +582,8 @@ CAST ( 'string' AS type ) stands for the unique identifier of an instance which is added by - Postgres to all instances automatically. Oids are not reused and are 32 - bit quantities. + Postgres to all instances automatically. OIDs are not reused and are + 32-bit quantities. @@ -592,7 +610,7 @@ CAST ( 'string' AS type ) cmin - The command identifier within the transaction. + The command identifier within the inserting transaction. @@ -601,7 +619,7 @@ CAST ( 'string' AS type ) cmax - The identity of the deleting command. + The command identifier within the deleting transaction. @@ -609,12 +627,9 @@ CAST ( 'string' AS type ) - For further information on these fields consult + For further information on the system attributes consult . - Times are represented internally as instances of the - abstime - data type. Transaction and command identifiers are 32 bit quantities. - Transactions are assigned sequentially starting at 512. + Transaction and command identifiers are 32 bit quantities. @@ -625,27 +640,29 @@ CAST ( 'string' AS type ) A column is a construct of the form: -instance{.composite_field}.field `['number`]' +instance{.composite_field}.field `['subscript`]' instance identifies a particular class and can be thought of as standing for the instances of that class. An instance variable is either a class - name, a surrogate for a class defined by means of a FROM clause, - or the keyword NEW or CURRENT. - NEW and CURRENT can only appear in the action portion of a rule, while - other instance variables can be used in any SQL statement. + name, an alias for a class defined by means of a FROM clause, + or the keyword NEW or OLD. + (NEW and OLD can only appear in the action portion of a rule, while + other instance variables can be used in any SQL statement.) The + instance name can be omitted if the first field name is unique + across all the classes being used in the current query. composite_field is a field of of one of the Postgres composite types, - while successive composite fields address attributes in the + while successive composite fields select attributes in the class(s) to which the composite field evaluates. Lastly, field is a normal (base type) field in the class(s) last addressed. If field - is of type array, - then the optional number - designator indicates a specific element in the array. If no number is - indicated, then all array elements are returned. + is of an array type, + then the optional subscript + selects a specific element in the array. If no subscript is + provided, then the whole array is selected. @@ -654,9 +671,8 @@ CAST ( 'string' AS type ) Operators - Any built-in system, or user-defined operator may be used in SQL. - For the list of built-in and system operators consult - . + Any built-in or user-defined operator may be used in SQL. + For the list of built-in operators consult . For a list of user-defined operators consult your system administrator or run a query on the pg_operator class. Parentheses may be used for arbitrary grouping of operators in expressions. @@ -676,12 +692,12 @@ CAST ( 'string' AS type ) An expression is one of the following: - ( a_expr ) constant - attribute - a_expr binary_operator a_expr - a_expr right_unary_operator - left_unary_operator a_expr + column + expression binary_operator expression + expression right_unary_operator + left_unary_operator expression + ( expression ) parameter functional expression aggregate expression @@ -689,7 +705,7 @@ CAST ( 'string' AS type ) - We have already discussed constants and attributes. The three kinds of + We have already discussed constants and columns. The three kinds of operator expressions indicate respectively binary (infix), right-unary (suffix) and left-unary (prefix) operators. The following sections discuss the remaining options. @@ -701,7 +717,7 @@ CAST ( 'string' AS type ) A parameter is used to indicate a parameter in a SQL function. Typically this - is used in SQL function definition statement. The form of a + is used in SQL function definition statements. The form of a parameter is: @@ -716,8 +732,7 @@ $number CREATE FUNCTION dept (name) RETURNS dept - AS 'select * from - dept where name=$1' + AS 'select * from dept where name = $1' LANGUAGE 'sql'; @@ -732,7 +747,7 @@ CREATE FUNCTION dept (name) enclosed in parentheses: -function (a_expr [, a_expr ... ] ) +function (expression [, expression ... ] ) @@ -795,15 +810,15 @@ sqrt(emp.salary) of which must be of the form: -a_expr [ AS result_attname ] +expression [ AS result_attname ] where result_attname is the name to be assigned to the created column. If result_attname is not present, then Postgres selects a - default name based on the contents of a_expr. - If a_expr is a simple attribute reference + default name based on the contents of expression. + If expression is a simple attribute reference then the default name will be the same as that attribute's name, but otherwise the implementation is free to assign any default name. @@ -822,7 +837,7 @@ sqrt(emp.salary) OR - A clause is an a_expr + A clause is an expression that evaluates to a boolean over a set of instances. @@ -832,29 +847,54 @@ sqrt(emp.salary) The from list - is a comma-separated list of from expressions. - Each "from expression" is of the form: + is a comma-separated list of from-expressions. + The simplest possibility for a from-expression is: -[ class_reference ] instance_variable - {, [ class_ref ] instance_variable... } +class_reference [ [ AS ] alias ] - where class_reference - is of the form + where class_reference is of the form -class_name [ * ] +[ ONLY ] table_name [ * ] - The "from expression" - defines one or more instance variables to range over the class - indicated in class_reference. - One can also request - the instance variable to range over only the specific class - and not those that are beneath the - indicated class in the inheritance hierarchy by specifying ONLY before - before the classname. + The from-expression defines an instance variable that ranges over the + rows of the specified table. The instance variable's name is either + the table name, or the alias if one is given. + Ordinarily, if the table has child tables then the instance variable + will range over all rows in the inheritance hierarchy starting with + the specified table. If ONLY is specified then + child tables are not included. A trailing asterisk * + can be written to specifically indicate that child tables are included + (ONLY and * are mutually + exclusive). + + + + A from-expression can also be a sub-query: + + +( select-statement ) [ AS ] alias + + + Here, the effect is as though the SELECT were executed and its results + stored in a temporary table, which then becomes available as an instance + variable under the given alias. + + + + Finally, a from-expression can be built up from simpler from-expressions + using JOIN clauses: + + +from_expression [ NATURAL ] join_type from_expression + [ ON join_condition | USING ( join_column_list ) ] + + + This syntax allows specification of outer joins. + For details see the reference page for SELECT. @@ -868,7 +908,7 @@ sqrt(emp.salary) left-associative. This may lead to non-intuitive behavior; for example the boolean operators "<" and ">" have a different precedence than the boolean operators "<=" and ">=". Also, - you will sometimes need to add parenthesis when using combinations + you will sometimes need to add parentheses when using combinations of binary and unary operators. For instance SELECT 5 & ~ 6; @@ -1020,8 +1060,8 @@ SELECT (5 &) ~ 6; Note that the operator precedence rules also apply to user-defined - operators that look like the built-in operators - with special treatment. For example, if you define a + operators that have the same names as the built-in operators + mentioned above. For example, if you define a + operator for some custom data type it will have the same precedence as the built-in + operator, no matter what yours does.