diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 933178ff1dd..fbd14373647 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -250,8 +250,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.129 2003/11/04 09:55:38 p varchar, date, double precision, integer, interval, numeric, decimal, real, - smallint, time, timestamp - (both with or without time zone). + smallint, time (with or without time zone), + timestamp (with or without time zone). diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 5f40d81e0a8..94eddbc200f 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -1,5 +1,5 @@ @@ -995,7 +995,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.36 2003/09/20 20:12:04 tg The Julian Date was invented by the French scholar Joseph Justus Scaliger (1540-1609) - and probably takes its name from the Scaliger's father, + and probably takes its name from Scaliger's father, the Italian scholar Julius Caesar Scaliger (1484-1558). Astronomers have used the Julian period to assign a unique number to every day since 1 January 4713 BC. This is the so-called Julian Date @@ -1007,7 +1007,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.36 2003/09/20 20:12:04 tg The Julian Date is different from the Julian Calendar. The Julian calendar was introduced by Julius Caesar in 45 BC. It was in common use - until the 1582, when countries started changing to the Gregorian + until the year 1582, when countries started changing to the Gregorian calendar. In the Julian calendar, the tropical year is approximated as 365 1/4 days = 365.25 days. This gives an error of about 1 day in 128 years. @@ -1042,7 +1042,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.36 2003/09/20 20:12:04 tg So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600, 2000, and 2400 are leap years. - By contrast, in the older Julian calendar only years divisible by 4 are leap years. + By contrast, in the older Julian calendar all years divisible by 4 are leap + years. diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index c4d60ae24f9..47eff6ed141 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -1,4 +1,4 @@ - + Indexes @@ -77,7 +77,7 @@ CREATE INDEX test1_id_index ON test1 (id); than a sequential table scan. But you may have to run the ANALYZE command regularly to update statistics to allow the query planner to make educated decisions. - Also read for information about + See for information about how to find out whether an index is used and when and why the planner may choose not to use an index. @@ -106,8 +106,8 @@ CREATE INDEX test1_id_index ON test1 (id); PostgreSQL provides several index types: - B-tree, R-tree, GiST, and Hash. Each index type is more appropriate for - a particular query type because of the algorithm it uses. + B-tree, R-tree, GiST, and Hash. Each index type uses a different + algorithm that is best suited to different types of queries. index B-tree @@ -116,9 +116,10 @@ CREATE INDEX test1_id_index ON test1 (id); B-tree index - By - default, the CREATE INDEX command will create a - B-tree index, which fits the most common situations. In + By default, the CREATE INDEX command will create a + B-tree index, which fits the most common situations. B-trees can + handle equality and range queries on data that can be sorted into + some ordering. In particular, the PostgreSQL query planner will consider using a B-tree index whenever an indexed column is involved in a comparison using one of these operators: @@ -154,7 +155,7 @@ CREATE INDEX test1_id_index ON test1 (id); R-tree index - R-tree indexes are especially suited for spatial data. To create + R-tree indexes are suited for queries on spatial data. To create an R-tree index, use a command of the form CREATE INDEX name ON table USING RTREE (column); @@ -185,6 +186,7 @@ CREATE INDEX name ON table hash index + Hash indexes can only handle simple equality comparisons. The query planner will consider using a hash index whenever an indexed column is involved in a comparison using the = operator. The following command is used to @@ -195,19 +197,18 @@ CREATE INDEX name ON table Testing has shown PostgreSQL's hash - indexes to be similar or slower than B-tree indexes, and the - index size and build time for hash indexes is much worse. Hash - indexes also suffer poor performance under high concurrency. For + indexes to perform no better than B-tree indexes, and the + index size and build time for hash indexes is much worse. For these reasons, hash index use is presently discouraged. - The B-tree index is an implementation of Lehman-Yao + The B-tree index method is an implementation of Lehman-Yao high-concurrency B-trees. The R-tree index method implements standard R-trees using Guttman's quadratic split algorithm. The - hash index is an implementation of Litwin's linear hashing. We + hash index method is an implementation of Litwin's linear hashing. We mention the algorithms used solely to indicate that all of these index methods are fully dynamic and do not have to be optimized periodically (as is the case with, for example, static hash methods). @@ -233,7 +234,7 @@ CREATE TABLE test2 ( name varchar ); - (Say, you keep your /dev + (say, you keep your /dev directory in a database...) and you frequently make queries like SELECT name FROM test2 WHERE major = constant AND minor = constant; @@ -263,8 +264,8 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor); a and b, or in queries involving only a, but not in other combinations. (In a query involving a and c - the planner might choose to use the index for - a only and treat c like an + the planner could choose to use the index for + a, while treating c like an ordinary unindexed column.) Of course, each column must be used with operators appropriate to the index type; clauses that involve other operators will not be considered. @@ -310,16 +311,16 @@ CREATE UNIQUE INDEX name ON table When an index is declared unique, multiple table rows with equal indexed values will not be allowed. Null values are not considered - equal. + equal. A multicolumn unique index will only reject cases where all + of the indexed columns are equal in two rows. - PostgreSQL automatically creates unique - indexes when a table is declared with a unique constraint or a - primary key, on the columns that make up the primary key or unique - columns (a multicolumn index, if appropriate), to enforce that - constraint. A unique index can be added to a table at any later - time, to add a unique constraint. + PostgreSQL automatically creates a unique + index when a unique constraint or a primary key is defined for a table. + The index covers the columns that make up the primary key or unique + columns (a multicolumn index, if appropriate), and is the mechanism + that enforces the constraint. @@ -328,6 +329,9 @@ CREATE UNIQUE INDEX name ON tableALTER TABLE ... ADD CONSTRAINT. The use of indexes to enforce unique constraints could be considered an implementation detail that should not be accessed directly. + One should, however, be aware that there's no need to manually + create indexes on unique columns; doing so would just duplicate + the automatically-created index. @@ -362,6 +366,14 @@ CREATE INDEX test1_lower_col1_idx ON test1 (lower(col1)); + + If we were to declare this index UNIQUE, it would prevent + creation of rows whose col1 values differ only in case, + as well as rows whose col1 values are actually identical. + Thus, indexes on expressions can be used to enforce constraints that + are not definable as simple unique constraints. + + As another example, if one often does queries like this: @@ -409,7 +421,7 @@ CREATE INDEX name ON table In practice the default operator class for the column's data type is usually sufficient. The main point of having operator classes is that for some data types, there could be more than one meaningful - ordering. For example, we might want to sort a complex-number data + index behavior. For example, we might want to sort a complex-number data type either by absolute value or by real part. We could do this by defining two operator classes for the data type and then selecting the proper class when making an index. @@ -419,20 +431,6 @@ CREATE INDEX name ON table There are also some built-in operator classes besides the default ones: - - - The operator classes box_ops and - bigbox_ops both support R-tree indexes on the - box data type. The difference between them is - that bigbox_ops scales box coordinates down, - to avoid floating-point exceptions from doing multiplication, - addition, and subtraction on very large floating-point - coordinates. If the field on which your rectangles lie is about - 20 000 square units or larger, you should use - bigbox_ops. - - - The operator classes text_pattern_ops, @@ -644,7 +642,8 @@ SELECT * FROM orders WHERE order_nr = 3501; create, it would probably be too slow to be of any real use.) The system can recognize simple inequality implications, for example x < 1 implies x < 2; otherwise - the predicate condition must exactly match the query's WHERE condition + the predicate condition must exactly match part of the query's + WHERE condition or the index will not be recognized to be usable. @@ -723,7 +722,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) maintenance and tuning, it is still important to check which indexes are actually used by the real-life query workload. Examining index usage for an individual query is done with the - EXPLAIN command; its application for this purpose is + + command; its application for this purpose is illustrated in . It is also possible to gather overall statistics about index usage in a running server, as described in . @@ -740,7 +740,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) - Always run ANALYZE first. This command + Always run + first. This command collects statistics about the distribution of the values in the table. This information is required to guess the number of rows returned by a query, which is needed by the planner to assign @@ -813,8 +814,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) run-time parameters (described in ). An inaccurate selectivity estimate is due to insufficient statistics. It may be possible to help this by - tuning the statistics-gathering parameters (see ALTER - TABLE reference). + tuning the statistics-gathering parameters (see + ). diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 8a6e5fa9c2e..437d7330b21 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,4 +1,4 @@ - + Queries @@ -44,7 +44,7 @@ SELECT * FROM table1; client application. For example, the psql program will display an ASCII-art table on the screen, while client libraries will offer functions to - retrieve individual rows and columns.) The select list + extract individual values from the query result.) The select list specification * means all columns that the table expression happens to provide. A select list can also select a subset of the available columns or make calculations using the diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index b780fce083b..23bf492d094 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -205,7 +205,7 @@ UPDATE "my_table" SET "a" = 5; should be equivalent to "FOO" not "foo" according to the standard. If you want to write portable applications you are advised to always quote a - particular name or never quote it. + particular name or never quote it.) @@ -241,13 +241,13 @@ UPDATE "my_table" SET "a" = 5; escaping A string constant in SQL is an arbitrary sequence of characters - bounded by single quotes ('), e.g., 'This + bounded by single quotes ('), e.g., 'This is a string'. SQL allows single quotes to be embedded - in strings by typing two adjacent single quotes (e.g., - 'Dianne''s horse'). In + in strings by typing two adjacent single quotes, e.g., + 'Dianne''s horse'. In PostgreSQL single quotes may - alternatively be escaped with a backslash (\, - e.g., 'Dianne\'s horse'). + alternatively be escaped with a backslash (\), + e.g., 'Dianne\'s horse'. @@ -838,7 +838,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; - A constant or literal value; see . + A constant or literal value.