Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 4431758

Browse files
tglsfdctglsfdc
committed
Support ORDER BY ... NULLS FIRST/LAST, and add ASC/DESC/NULLS FIRST/NULLS LAST
per-column options for btree indexes. The planner's support for this is still pretty rudimentary; it does not yet know how to plan mergejoins with nondefault ordering options. The documentation is pretty rudimentary, too. I'll work on improving that stuff later. Note incompatible change from prior behavior: ORDER BY ... USING will now be rejected if the operator is not a less-than or greater-than member of some btree opclass. This prevents less-than-sane behavior if an operator that doesn't actually define a proper sort ordering is selected.
1 parent 3a32ba2 commit 4431758

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+1475
-592
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.140 2006/12/30 21:21:52 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.141 2007/01/09 02:14:09 tgl Exp $ -->
22
<!--
33
Documentation of the system catalogs, directed toward PostgreSQL developers
44
-->
@@ -369,7 +369,17 @@
369369
<entry><type>int2</type></entry>
370370
<entry></entry>
371371
<entry>Zero if the index offers no sort order, otherwise the strategy
372-
number of the strategy operator that describes the sort order</entry>
372+
number of the strategy operator that describes the default
373+
(<literal>ASC</>) sort order</entry>
374+
</row>
375+
376+
<row>
377+
<entry><structfield>amdescorder</structfield></entry>
378+
<entry><type>int2</type></entry>
379+
<entry></entry>
380+
<entry>Zero if the index offers no sort order, otherwise the strategy
381+
number of the strategy operator that describes the <literal>DESC</>
382+
sort order</entry>
373383
</row>
374384

375385
<row>
@@ -2453,8 +2463,8 @@
24532463
<entry><structfield>indisprimary</structfield></entry>
24542464
<entry><type>bool</type></entry>
24552465
<entry></entry>
2456-
<entry>If true, this index represents the primary key of the table.
2457-
(<structfield>indisunique</> should always be true when this is true.)</entry>
2466+
<entry>If true, this index represents the primary key of the table
2467+
(<structfield>indisunique</> should always be true when this is true)</entry>
24582468
</row>
24592469

24602470
<row>
@@ -2487,7 +2497,7 @@
24872497
of <literal>1 3</literal> would mean that the first and the third table
24882498
columns make up the index key. A zero in this array indicates that the
24892499
corresponding index attribute is an expression over the table columns,
2490-
rather than a simple column reference.
2500+
rather than a simple column reference
24912501
</entry>
24922502
</row>
24932503

@@ -2496,12 +2506,23 @@
24962506
<entry><type>oidvector</type></entry>
24972507
<entry><literal><link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link>.oid</literal></entry>
24982508
<entry>
2499-
For each column in the index key this contains the OID of
2509+
For each column in the index key, this contains the OID of
25002510
the operator class to use. See
25012511
<link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link> for details
25022512
</entry>
25032513
</row>
25042514

2515+
<row>
2516+
<entry><structfield>indoption</structfield></entry>
2517+
<entry><type>int2vector</type></entry>
2518+
<entry></entry>
2519+
<entry>
2520+
This is an array of <structfield>indnatts</structfield> values that
2521+
store per-column flag bits. The meaning of the bits is defined by
2522+
the index's access method
2523+
</entry>
2524+
</row>
2525+
25052526
<row>
25062527
<entry><structfield>indexprs</structfield></entry>
25072528
<entry><type>text</type></entry>

‎doc/src/sgml/queries.sgml

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.39 2006/10/24 02:24:27 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.40 2007/01/09 02:14:10 tgl Exp $ -->
22

33
<chapter id="queries">
44
<title>Queries</title>
@@ -1224,7 +1224,8 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
12241224
<synopsis>
12251225
SELECT <replaceable>select_list</replaceable>
12261226
FROM <replaceable>table_expression</replaceable>
1227-
ORDER BY <replaceable>sort_expression1</replaceable> <optional>ASC | DESC</optional> <optional>, <replaceable>sort_expression2</replaceable> <optional>ASC | DESC</optional> ...</optional>
1227+
ORDER BY <replaceable>sort_expression1</replaceable> <optional>ASC | DESC</optional> <optional>NULLS { FIRST | LAST }</optional>
1228+
<optional>, <replaceable>sort_expression2</replaceable> <optional>ASC | DESC</optional> <optional>NULLS { FIRST | LAST }</optional> ...</optional>
12281229
</synopsis>
12291230
The sort expression(s) can be any expression that would be valid in the
12301231
query's select list. An example is
@@ -1253,6 +1254,14 @@ SELECT a, b FROM table1 ORDER BY a + b, c;
12531254
</footnote>
12541255
</para>
12551256

1257+
<para>
1258+
The <literal>NULLS FIRST</> and <literal>NULLS LAST</> options can be
1259+
used to determine whether nulls appear before or after non-null values
1260+
in the sort ordering. By default, null values sort as if larger than any
1261+
non-null value; that is, <literal>NULLS FIRST</> is the default for
1262+
<literal>DESC</> order, and <literal>NULLS LAST</> otherwise.
1263+
</para>
1264+
12561265
<para>
12571266
For backwards compatibility with the SQL92 version of the standard,
12581267
a <replaceable>sort_expression</> can instead be the name or number
@@ -1301,7 +1310,7 @@ SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong
13011310
<synopsis>
13021311
SELECT <replaceable>select_list</replaceable>
13031312
FROM <replaceable>table_expression</replaceable>
1304-
<optional> ORDER BY <replaceable>sort_expression1</replaceable> <optional>ASC | DESC</optional> <optional>, <replaceable>sort_expression2</replaceable> <optional>ASC | DESC</optional> ...</optional> </optional>
1313+
<optional> ORDER BY ... </optional>
13051314
<optional> LIMIT { <replaceable>number</replaceable> | ALL } </optional> <optional> OFFSET <replaceable>number</replaceable> </optional>
13061315
</synopsis>
13071316
</para>

‎doc/src/sgml/ref/create_index.sgml

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.58 2006/09/16 00:30:17 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.59 2007/01/09 02:14:10 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -21,7 +21,7 @@ PostgreSQL documentation
2121
<refsynopsisdiv>
2222
<synopsis>
2323
CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
24-
( { <replaceable class="parameter">column</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] )
24+
( { <replaceable class="parameter">column</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] )
2525
[ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ]
2626
[ TABLESPACE <replaceable class="parameter">tablespace</replaceable> ]
2727
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
@@ -187,6 +187,44 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</re
187187
</listitem>
188188
</varlistentry>
189189

190+
<varlistentry>
191+
<term><literal>ASC</></term>
192+
<listitem>
193+
<para>
194+
Specifies ascending sort order (which is the default).
195+
</para>
196+
</listitem>
197+
</varlistentry>
198+
199+
<varlistentry>
200+
<term><literal>DESC</></term>
201+
<listitem>
202+
<para>
203+
Specifies descending sort order.
204+
</para>
205+
</listitem>
206+
</varlistentry>
207+
208+
<varlistentry>
209+
<term><literal>NULLS FIRST</></term>
210+
<listitem>
211+
<para>
212+
Specifies that nulls sort before non-nulls. This is the default
213+
when <literal>DESC</> is specified.
214+
</para>
215+
</listitem>
216+
</varlistentry>
217+
218+
<varlistentry>
219+
<term><literal>NULLS LAST</></term>
220+
<listitem>
221+
<para>
222+
Specifies that nulls sort after non-nulls. This is the default
223+
when <literal>DESC</> is not specified.
224+
</para>
225+
</listitem>
226+
</varlistentry>
227+
190228
<varlistentry>
191229
<term><replaceable class="parameter">storage_parameter</replaceable></term>
192230
<listitem>
@@ -363,6 +401,21 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</re
363401
linkend="xindex">.
364402
</para>
365403

404+
<para>
405+
For index methods that support ordered scans (currently, only B-tree),
406+
the optional clauses <literal>ASC</>, <literal>DESC</>, <literal>NULLS
407+
FIRST</>, and/or <literal>NULLS LAST</> can be specified to reverse
408+
the normal sort direction of the index. Since an ordered index can be
409+
scanned either forward or backward, it is not normally useful to create a
410+
single-column <literal>DESC</> index &mdash; that sort ordering is already
411+
available with a regular index. The value of these options is that
412+
multicolumn indexes can be created that match the sort ordering requested
413+
by a mixed-ordering query, such as <literal>SELECT ... ORDER BY x ASC, y
414+
DESC</>. The <literal>NULLS</> options are useful if you need to support
415+
<quote>nulls sort low</> behavior, rather than the default <quote>nulls
416+
sort high</>, in queries that depend on indexes to avoid sorting steps.
417+
</para>
418+
366419
<para>
367420
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
368421
to remove an index.
@@ -403,6 +456,13 @@ CREATE INDEX lower_title_idx ON films ((lower(title)));
403456
</programlisting>
404457
</para>
405458

459+
<para>
460+
To create an index with non-default sort ordering of nulls:
461+
<programlisting>
462+
CREATE INDEX title_idx_nulls_low ON films (title NULLS FIRST);
463+
</programlisting>
464+
</para>
465+
406466
<para>
407467
To create an index with non-default fill factor:
408468
<programlisting>

‎doc/src/sgml/ref/select.sgml

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.94 2006/12/01 20:49:53 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.95 2007/01/09 02:14:10 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -27,7 +27,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
2727
[ GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] ]
2828
[ HAVING <replaceable class="parameter">condition</replaceable> [, ...] ]
2929
[ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="parameter">select</replaceable> ]
30-
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...] ]
30+
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
3131
[ LIMIT { <replaceable class="parameter">count</replaceable> | ALL } ]
3232
[ OFFSET <replaceable class="parameter">start</replaceable> ]
3333
[ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ] [...] ]
@@ -642,7 +642,7 @@ HAVING <replaceable class="parameter">condition</replaceable>
642642
<para>
643643
The optional <literal>ORDER BY</literal> clause has this general form:
644644
<synopsis>
645-
ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...]
645+
ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...]
646646
</synopsis>
647647
<replaceable class="parameter">expression</replaceable> can be the
648648
name or ordinal number of an output column
@@ -652,8 +652,8 @@ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC |
652652

653653
<para>
654654
The <literal>ORDER BY</literal> clause causes the result rows to
655-
be sorted according to the specified expressions. If two rows are
656-
equal according to the leftmost expression, the are compared
655+
be sorted according to the specified expression(s). If two rows are
656+
equal according to the leftmost expression, they are compared
657657
according to the next expression and so on. If they are equal
658658
according to all specified expressions, they are returned in
659659
an implementation-dependent order.
@@ -697,6 +697,8 @@ SELECT name FROM distributors ORDER BY code;
697697
<literal>ORDER BY</> clause. If not specified, <literal>ASC</> is
698698
assumed by default. Alternatively, a specific ordering operator
699699
name may be specified in the <literal>USING</> clause.
700+
An ordering operator must be a less-than or greater-than
701+
member of some btree operator family.
700702
<literal>ASC</> is usually equivalent to <literal>USING &lt;</> and
701703
<literal>DESC</> is usually equivalent to <literal>USING &gt;</>.
702704
(But the creator of a user-defined data type can define exactly what the
@@ -705,9 +707,14 @@ SELECT name FROM distributors ORDER BY code;
705707
</para>
706708

707709
<para>
708-
The null value sorts higher than any other value. In other words,
709-
with ascending sort order, null values sort at the end, and with
710-
descending sort order, null values sort at the beginning.
710+
If <literal>NULLS LAST</> is specified, null values sort after all
711+
non-null values; if <literal>NULLS FIRST</> is specified, null values
712+
sort before all non-null values. If neither is specified, the default
713+
behavior is <literal>NULLS LAST</> when <literal>ASC</> is specified
714+
or implied, and <literal>NULLS FIRST</> when <literal>DESC</> is specified
715+
(thus, the default is to act as though nulls are larger than non-nulls).
716+
When <literal>USING</> is specified, the default nulls ordering depends
717+
on whether the operator is a less-than or greater-than operator.
711718
</para>
712719

713720
<para>

‎doc/src/sgml/ref/select_into.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.38 2006/09/16 00:30:20 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.39 2007/01/09 02:14:10 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -28,7 +28,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
2828
[ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
2929
[ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
3030
[ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ]
31-
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
31+
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
3232
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
3333
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
3434
[ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ] [...] ]

‎doc/src/sgml/sql.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/sql.sgml,v 1.42 2006/09/16 00:30:15 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/sql.sgml,v 1.43 2007/01/09 02:14:10 tgl Exp $ -->
22

33
<chapter id="sql-intro">
44
<title>SQL</title>
@@ -860,7 +860,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
860860
[ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
861861
[ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
862862
[ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ]
863-
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
863+
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
864864
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
865865
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
866866
[ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ] [...] ]

‎doc/src/sgml/xindex.sgml

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.53 2006/12/01 23:46:46 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/xindex.sgml,v 1.54 2007/01/09 02:14:10 tgl Exp $ -->
22

33
<sect1 id="xindex">
44
<title>Interfacing Extensions To Indexes</title>
@@ -289,13 +289,17 @@
289289
</para>
290290

291291
<para>
292-
By the way, the <structfield>amorderstrategy</structfield> column
293-
in <classname>pg_am</> tells whether
294-
the index method supports ordered scans. Zero means it doesn't; if it
295-
does, <structfield>amorderstrategy</structfield> is the strategy
296-
number that corresponds to the ordering operator. For example, B-tree
297-
has <structfield>amorderstrategy</structfield> = 1, which is its
298-
<quote>less than</quote> strategy number.
292+
By the way, the <structfield>amorderstrategy</structfield> and
293+
<structfield>amdescorder</structfield> columns in <classname>pg_am</> tell
294+
whether the index method supports ordered scans. Zeroes mean it doesn't;
295+
if it does, <structfield>amorderstrategy</structfield> is the strategy
296+
number that corresponds to the default ordering operator, and
297+
<structfield>amdescorder</structfield> is the strategy number for the
298+
ordering operator of an index column that has the <literal>DESC</> option.
299+
For example, B-tree has <structfield>amorderstrategy</structfield> = 1,
300+
which is its <quote>less than</quote> strategy number, and
301+
<structfield>amdescorder</structfield> = 5, which is its
302+
<quote>greater than</quote> strategy number.
299303
</para>
300304
</sect2>
301305

‎src/backend/access/nbtree/README

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
$PostgreSQL: pgsql/src/backend/access/nbtree/README,v 1.15 2006/12/28 23:16:39 tgl Exp $
1+
$PostgreSQL: pgsql/src/backend/access/nbtree/README,v 1.16 2007/01/09 02:14:10 tgl Exp $
22

33
This directory contains a correct implementation of Lehman and Yao's
44
high-concurrency B-tree management algorithm (P. Lehman and S. Yao,
@@ -483,5 +483,6 @@ Notes to operator class implementors
483483
With this implementation, we require each supported combination of
484484
datatypes to supply us with a comparison procedure via pg_amproc.
485485
This procedure must take two nonnull values A and B and return an int32 < 0,
486-
0, or > 0 if A < B, A = B, or A > B, respectively. See nbtcompare.c for
487-
examples.
486+
0, or > 0 if A < B, A = B, or A > B, respectively. The procedure must
487+
not return INT_MIN for "A < B", since the value may be negated before
488+
being tested for sign. See nbtcompare.c for examples.

‎src/backend/access/nbtree/nbtcompare.c

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
*
99
*
1010
* IDENTIFICATION
11-
* $PostgreSQL: pgsql/src/backend/access/nbtree/nbtcompare.c,v 1.53 2007/01/05 22:19:23 momjian Exp $
11+
* $PostgreSQL: pgsql/src/backend/access/nbtree/nbtcompare.c,v 1.54 2007/01/09 02:14:10 tgl Exp $
1212
*
1313
* NOTES
1414
*
@@ -22,10 +22,10 @@
2222
*
2323
* The result is always an int32 regardless of the input datatype.
2424
*
25-
* NOTE: although any negative int32 is acceptable for reporting "<",
26-
* and any positive int32 is acceptable for reporting ">", routines
25+
* Although any negative int32 (except INT_MIN) is acceptable for reporting
26+
* "<", and any positive int32 is acceptable for reporting ">", routines
2727
* that work on 32-bit or wider datatypes can't just return "a - b".
28-
* That could overflow and give the wrong answer. Also, one should not
28+
* That could overflow and give the wrong answer. Also, one must not
2929
* return INT_MIN to report "<", since some callers will negate the result.
3030
*
3131
* NOTE: it is critical that the comparison function impose a total order

0 commit comments

Comments
 (0)