head	1.132;
access;
symbols
	REL9_0_0:1.131
	REL9_1_ALPHA1:1.132
	REL9_0_RC1:1.131
	REL9_0_BETA4:1.131
	REL9_0_STABLE:1.131.0.2
	REL9_0_BETA3:1.131
	REL9_0_BETA2:1.130
	REL7_4_29:1.71.2.2
	REL8_0_25:1.80.4.3
	REL8_1_21:1.90.2.1
	REL8_2_17:1.94
	REL8_3_11:1.102.2.1
	REL8_4_4:1.122.2.2
	REL9_0_BETA1:1.130
	REL9_0_ALPHA5_BRANCH:1.129.0.4
	REL9_0_ALPHA5:1.129
	REL7_4_28:1.71.2.2
	REL8_0_24:1.80.4.3
	REL8_1_20:1.90.2.1
	REL8_2_16:1.94
	REL8_3_10:1.102.2.1
	REL8_4_3:1.122.2.2
	REL9_0_ALPHA4:1.129
	REL9_0_ALPHA4_BRANCH:1.129.0.2
	REL8_5_ALPHA3:1.128
	REL8_5_ALPHA3_BRANCH:1.128.0.2
	REL7_4_27:1.71.2.2
	REL8_0_23:1.80.4.3
	REL8_1_19:1.90.2.1
	REL8_2_15:1.94
	REL8_3_9:1.102.2.1
	REL8_4_2:1.122.2.2
	REL8_5_ALPHA2:1.125
	REL8_5_ALPHA2_BRANCH:1.125.0.2
	REL7_4_26:1.71.2.2
	REL8_0_22:1.80.4.3
	REL8_1_18:1.90.2.1
	REL8_2_14:1.94
	REL8_3_8:1.102.2.1
	REL8_4_1:1.122.2.1
	REL8_5_ALPHA1:1.123
	REL8_5_ALPHA1_BRANCH:1.123.0.2
	REL8_4_STABLE:1.122.0.2
	REL8_4_0:1.122
	REL8_4_RC2:1.122
	REL8_4_RC1:1.122
	REL8_4_BETA2:1.122
	REL8_4_BETA1:1.120
	REL7_4_25:1.71.2.2
	REL8_0_21:1.80.4.3
	REL8_1_17:1.90.2.1
	REL8_2_13:1.94
	REL8_3_7:1.102.2.1
	REL7_4_24:1.71.2.2
	REL8_0_20:1.80.4.3
	REL8_1_16:1.90.2.1
	REL8_2_12:1.94
	REL8_3_6:1.102.2.1
	REL7_4_23:1.71.2.2
	REL8_0_19:1.80.4.3
	REL8_1_15:1.90.2.1
	REL8_2_11:1.94
	REL8_3_5:1.102
	REL7_4_22:1.71.2.2
	REL8_0_18:1.80.4.3
	REL8_1_14:1.90.2.1
	REL8_2_10:1.94
	REL8_3_4:1.102
	REL7_4_21:1.71.2.2
	REL8_0_17:1.80.4.3
	REL8_1_13:1.90.2.1
	REL8_2_9:1.94
	REL8_3_3:1.102
	REL7_4_20:1.71.2.2
	REL8_0_16:1.80.4.3
	REL8_1_12:1.90.2.1
	REL8_2_8:1.94
	REL8_3_2:1.102
	REL8_2_7:1.94
	REL8_3_1:1.102
	REL8_3_STABLE:1.102.0.2
	REL8_3_0:1.102
	REL8_3_RC2:1.102
	REL7_3_21:1.63
	REL7_4_19:1.71.2.2
	REL8_0_15:1.80.4.3
	REL8_1_11:1.90.2.1
	REL8_2_6:1.94
	REL8_3_RC1:1.102
	REL8_3_BETA4:1.102
	REL8_3_BETA3:1.101
	REL8_3_BETA2:1.101
	REL8_3_BETA1:1.101
	REL7_3_20:1.63
	REL7_4_18:1.71.2.2
	REL8_0_14:1.80.4.3
	REL8_1_10:1.90.2.1
	REL8_2_5:1.94
	REL7_3_19:1.63
	REL7_4_17:1.71.2.2
	REL8_0_13:1.80.4.3
	REL8_1_9:1.90.2.1
	REL8_2_4:1.94
	REL8_0_12:1.80.4.3
	REL8_1_8:1.90.2.1
	REL8_2_3:1.94
	REL7_3_18:1.63
	REL7_4_16:1.71.2.2
	REL8_0_11:1.80.4.3
	REL8_1_7:1.90.2.1
	REL8_2_2:1.94
	REL8_0_10:1.80.4.3
	REL8_1_6:1.90.2.1
	REL8_2_1:1.94
	REL7_4_15:1.71.2.2
	REL7_3_17:1.63
	REL8_2_STABLE:1.94.0.2
	REL8_2_0:1.94
	REL8_2_RC1:1.93
	REL8_2_BETA3:1.93
	REL8_2_BETA2:1.93
	REL8_1_5:1.90
	REL8_0_9:1.80.4.2
	REL7_4_14:1.71.2.2
	REL7_3_16:1.63
	REL8_2_BETA1:1.93
	REL7_3_15:1.63
	REL7_4_13:1.71.2.2
	REL8_0_8:1.80.4.2
	REL8_1_4:1.90
	REL7_3_14:1.63
	REL7_4_12:1.71.2.2
	REL8_0_7:1.80.4.2
	REL8_1_3:1.90
	REL7_3_13:1.63
	REL7_4_11:1.71.2.2
	REL8_0_6:1.80.4.2
	REL8_1_2:1.90
	REL7_3_12:1.63
	REL7_4_10:1.71.2.2
	REL8_0_5:1.80.4.2
	REL8_1_1:1.90
	REL8_1_STABLE:1.90.0.2
	REL8_1_0:1.90
	REL8_1_0RC1:1.89
	REL8_1_0BETA4:1.89
	REL8_1_0BETA3:1.89
	REL7_3_11:1.63
	REL7_4_9:1.71.2.2
	REL8_0_4:1.80.4.2
	REL8_1_0BETA2:1.89
	REL8_1_0BETA1:1.89
	REL7_2_8:1.51
	REL7_3_10:1.63
	REL7_4_8:1.71.2.2
	REL8_0_3:1.80.4.2
	REL8_0_2:1.80.4.1
	REL7_2_7:1.51
	REL7_3_9:1.63
	REL7_4_7:1.71.2.2
	REL8_0_1:1.80.4.1
	REL8_0_STABLE:1.80.0.4
	REL8_0_0:1.80.0.2
	REL8_0_0RC5:1.80
	REL8_0_0RC4:1.80
	REL8_0_0RC3:1.78
	REL8_0_0RC2:1.78
	REL8_0_0RC1:1.78
	REL8_0_0BETA5:1.77
	REL8_0_0BETA4:1.77
	REL7_4_6:1.71.2.2
	REL7_3_8:1.63
	REL7_2_6:1.51
	REL8_0_0BETA3:1.77
	REL8_0_0BETA2:1.77
	REL7_2_5:1.51
	REL7_4_5:1.71.2.1
	REL7_3_7:1.63
	REL7_4_4:1.71.2.1
	REL8_0_0BETA1:1.77
	REL7_4_3:1.71.2.1
	REL7_4_2:1.71.2.1
	REL7_3_6:1.63
	REL7_4_1:1.71.2.1
	REL7_3_5:1.63
	REL7_4:1.71.2.1
	REL7_4_RC2:1.71.2.1
	REL7_4_STABLE:1.71.0.2
	REL7_4_RC1:1.71
	REL7_4_BETA5:1.70
	REL7_4_BETA4:1.70
	REL7_4_BETA3:1.70
	REL7_4_BETA2:1.68
	WIN32_DEV:1.67.0.2
	REL7_4_BETA1:1.67
	REL7_3_4:1.63
	REL7_3_2:1.63
	REL7_2_4:1.51
	REL7_3_STABLE:1.63.0.2
	REL7_2_3:1.51
	REL7_2_STABLE:1.51.0.2
	REL7_2:1.51
	REL7_2_RC2:1.51
	REL7_2_RC1:1.51
	REL7_2_BETA5:1.51
	REL7_2_BETA4:1.51
	REL7_2_BETA3:1.50
	REL7_2_BETA2:1.50
	REL7_2_BETA1:1.49
	REL7_1_2:1.40
	REL7_1_STABLE:1.40.0.2
	REL7_1_BETA:1.33
	REL7_1_BETA3:1.36
	REL7_1_BETA2:1.35
	REL7_1:1.40
	REL7_0_PATCHES:1.28.0.2
	REL7_0:1.28
	REL6_5_PATCHES:1.17.0.2
	REL6_5:1.17
	REL6_4:1.7.0.2;
locks; strict;
comment	@# @;


1.132
date	2010.08.07.02.44.05;	author tgl;	state Exp;
branches;
next	1.131;

1.131
date	2010.06.15.20.04.53;	author momjian;	state Exp;
branches;
next	1.130;

1.130
date	2010.04.03.07.23.02;	author petere;	state Exp;
branches;
next	1.129;

1.129
date	2010.02.12.17.33.19;	author tgl;	state Exp;
branches;
next	1.128;

1.128
date	2009.10.28.14.55.37;	author tgl;	state Exp;
branches;
next	1.127;

1.127
date	2009.10.27.17.11.18;	author tgl;	state Exp;
branches;
next	1.126;

1.126
date	2009.10.21.20.22.38;	author tgl;	state Exp;
branches;
next	1.125;

1.125
date	2009.09.18.05.00.42;	author petere;	state Exp;
branches;
next	1.124;

1.124
date	2009.08.27.20.08.02;	author tgl;	state Exp;
branches;
next	1.123;

1.123
date	2009.08.18.23.40.20;	author tgl;	state Exp;
branches;
next	1.122;

1.122
date	2009.05.03.20.45.43;	author tgl;	state Exp;
branches
	1.122.2.1;
next	1.121;

1.121
date	2009.04.15.22.42.50;	author momjian;	state Exp;
branches;
next	1.120;

1.120
date	2009.02.02.20.42.57;	author tgl;	state Exp;
branches;
next	1.119;

1.119
date	2009.01.23.14.05.28;	author momjian;	state Exp;
branches;
next	1.118;

1.118
date	2009.01.22.20.15.59;	author tgl;	state Exp;
branches;
next	1.117;

1.117
date	2009.01.12.14.06.20;	author petere;	state Exp;
branches;
next	1.116;

1.116
date	2008.12.31.23.42.56;	author tgl;	state Exp;
branches;
next	1.115;

1.115
date	2008.12.31.00.08.35;	author tgl;	state Exp;
branches;
next	1.114;

1.114
date	2008.12.29.18.23.53;	author tgl;	state Exp;
branches;
next	1.113;

1.113
date	2008.12.28.18.53.54;	author tgl;	state Exp;
branches;
next	1.112;

1.112
date	2008.12.01.09.38.08;	author petere;	state Exp;
branches;
next	1.111;

1.111
date	2008.11.21.11.47.55;	author petere;	state Exp;
branches;
next	1.110;

1.110
date	2008.11.20.14.04.45;	author petere;	state Exp;
branches;
next	1.109;

1.109
date	2008.11.19.12.21.57;	author petere;	state Exp;
branches;
next	1.108;

1.108
date	2008.11.14.10.22.47;	author petere;	state Exp;
branches;
next	1.107;

1.107
date	2008.10.22.11.00.33;	author petere;	state Exp;
branches;
next	1.106;

1.106
date	2008.10.07.19.27.04;	author tgl;	state Exp;
branches;
next	1.105;

1.105
date	2008.10.04.21.56.52;	author tgl;	state Exp;
branches;
next	1.104;

1.104
date	2008.09.23.09.20.35;	author heikki;	state Exp;
branches;
next	1.103;

1.103
date	2008.02.15.22.17.06;	author tgl;	state Exp;
branches;
next	1.102;

1.102
date	2007.11.28.15.42.31;	author petere;	state Exp;
branches
	1.102.2.1;
next	1.101;

1.101
date	2007.06.08.20.26.18;	author tgl;	state Exp;
branches;
next	1.100;

1.100
date	2007.05.15.19.13.55;	author neilc;	state Exp;
branches;
next	1.99;

1.99
date	2007.02.01.19.10.25;	author momjian;	state Exp;
branches;
next	1.98;

1.98
date	2007.02.01.00.28.19;	author momjian;	state Exp;
branches;
next	1.97;

1.97
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.96;

1.96
date	2007.01.09.16.59.20;	author tgl;	state Exp;
branches;
next	1.95;

1.95
date	2007.01.09.02.14.10;	author tgl;	state Exp;
branches;
next	1.94;

1.94
date	2006.12.01.20.49.53;	author tgl;	state Exp;
branches;
next	1.93;

1.93
date	2006.09.18.19.54.01;	author tgl;	state Exp;
branches;
next	1.92;

1.92
date	2006.09.16.00.30.20;	author momjian;	state Exp;
branches;
next	1.91;

1.91
date	2006.04.30.18.30.38;	author tgl;	state Exp;
branches;
next	1.90;

1.90
date	2005.11.01.21.09.51;	author tgl;	state Exp;
branches
	1.90.2.1;
next	1.89;

1.89
date	2005.08.01.20.31.04;	author tgl;	state Exp;
branches;
next	1.88;

1.88
date	2005.07.14.06.17.36;	author neilc;	state Exp;
branches;
next	1.87;

1.87
date	2005.05.08.03.08.05;	author momjian;	state Exp;
branches;
next	1.86;

1.86
date	2005.04.28.21.47.10;	author tgl;	state Exp;
branches;
next	1.85;

1.85
date	2005.04.22.15.32.58;	author momjian;	state Exp;
branches;
next	1.84;

1.84
date	2005.04.22.04.20.44;	author momjian;	state Exp;
branches;
next	1.83;

1.83
date	2005.04.08.00.59.58;	author neilc;	state Exp;
branches;
next	1.82;

1.82
date	2005.03.10.23.21.20;	author tgl;	state Exp;
branches;
next	1.81;

1.81
date	2005.01.22.23.22.19;	author momjian;	state Exp;
branches;
next	1.80;

1.80
date	2005.01.04.08.59.45;	author tgl;	state Exp;
branches
	1.80.4.1;
next	1.79;

1.79
date	2005.01.04.03.58.16;	author tgl;	state Exp;
branches;
next	1.78;

1.78
date	2004.11.27.21.27.07;	author petere;	state Exp;
branches;
next	1.77;

1.77
date	2004.05.16.23.22.08;	author neilc;	state Exp;
branches;
next	1.76;

1.76
date	2004.03.09.16.57.47;	author neilc;	state Exp;
branches;
next	1.75;

1.75
date	2004.03.03.22.22.24;	author neilc;	state Exp;
branches;
next	1.74;

1.74
date	2003.12.14.00.15.03;	author neilc;	state Exp;
branches;
next	1.73;

1.73
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.72;

1.72
date	2003.11.04.00.34.45;	author tgl;	state Exp;
branches;
next	1.71;

1.71
date	2003.11.01.01.56.29;	author petere;	state Exp;
branches
	1.71.2.1;
next	1.70;

1.70
date	2003.09.11.21.42.20;	author momjian;	state Exp;
branches;
next	1.69;

1.69
date	2003.08.31.17.32.24;	author petere;	state Exp;
branches;
next	1.68;

1.68
date	2003.08.17.22.09.00;	author tgl;	state Exp;
branches;
next	1.67;

1.67
date	2003.05.04.02.23.16;	author petere;	state Exp;
branches
	1.67.2.1;
next	1.66;

1.66
date	2003.03.25.16.15.44;	author petere;	state Exp;
branches;
next	1.65;

1.65
date	2003.03.20.19.00.01;	author momjian;	state Exp;
branches;
next	1.64;

1.64
date	2003.01.19.00.13.31;	author momjian;	state Exp;
branches;
next	1.63;

1.63
date	2002.10.24.21.19.15;	author tgl;	state Exp;
branches;
next	1.62;

1.62
date	2002.10.18.18.26.22;	author tgl;	state Exp;
branches;
next	1.61;

1.61
date	2002.09.21.18.32.54;	author petere;	state Exp;
branches;
next	1.60;

1.60
date	2002.08.30.16.00.41;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	2002.08.30.03.18.23;	author momjian;	state Exp;
branches;
next	1.58;

1.58
date	2002.08.29.00.17.01;	author tgl;	state Exp;
branches;
next	1.57;

1.57
date	2002.08.28.14.35.37;	author momjian;	state Exp;
branches;
next	1.56;

1.56
date	2002.08.15.02.59.18;	author momjian;	state Exp;
branches;
next	1.55;

1.55
date	2002.08.04.19.48.09;	author momjian;	state Exp;
branches;
next	1.54;

1.54
date	2002.04.23.02.07.16;	author tgl;	state Exp;
branches;
next	1.53;

1.53
date	2002.03.27.19.19.23;	author petere;	state Exp;
branches;
next	1.52;

1.52
date	2002.03.22.19.20.45;	author petere;	state Exp;
branches;
next	1.51;

1.51
date	2001.12.08.03.24.39;	author thomas;	state Exp;
branches;
next	1.50;

1.50
date	2001.10.31.04.50.52;	author momjian;	state Exp;
branches;
next	1.49;

1.49
date	2001.10.23.16.42.36;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	2001.10.20.02.55.38;	author momjian;	state Exp;
branches;
next	1.47;

1.47
date	2001.09.23.03.39.01;	author momjian;	state Exp;
branches;
next	1.46;

1.46
date	2001.09.14.10.28.09;	author ishii;	state Exp;
branches;
next	1.45;

1.45
date	2001.09.13.15.55.24;	author petere;	state Exp;
branches;
next	1.44;

1.44
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.43;

1.43
date	2001.06.10.03.46.31;	author momjian;	state Exp;
branches;
next	1.42;

1.42
date	2001.05.30.04.32.30;	author tgl;	state Exp;
branches;
next	1.41;

1.41
date	2001.05.27.09.59.28;	author petere;	state Exp;
branches;
next	1.40;

1.40
date	2001.03.24.23.03.26;	author petere;	state Exp;
branches;
next	1.39;

1.39
date	2001.03.20.20.54.41;	author tgl;	state Exp;
branches;
next	1.38;

1.38
date	2001.02.04.12.18.08;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2001.01.13.23.58.55;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2001.01.08.21.30.37;	author tgl;	state Exp;
branches;
next	1.35;

1.35
date	2000.12.12.05.07.59;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2000.12.08.20.11.11;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2000.07.22.04.30.27;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2000.07.21.18.51.24;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	2000.06.22.22.31.16;	author petere;	state Exp;
branches;
next	1.29;

1.29
date	2000.06.09.01.44.00;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	2000.03.27.17.14.43;	author thomas;	state Exp;
branches;
next	1.27;

1.27
date	2000.03.26.18.32.27;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2000.03.15.23.31.19;	author tgl;	state Exp;
branches;
next	1.25;

1.25
date	2000.02.21.01.13.52;	author tgl;	state Exp;
branches;
next	1.24;

1.24
date	2000.01.27.18.11.25;	author tgl;	state Exp;
branches;
next	1.23;

1.23
date	99.12.13.17.39.38;	author tgl;	state Exp;
branches;
next	1.22;

1.22
date	99.08.06.13.50.31;	author thomas;	state Exp;
branches;
next	1.21;

1.21
date	99.07.22.15.09.14;	author thomas;	state Exp;
branches;
next	1.20;

1.20
date	99.07.16.14.32.06;	author thomas;	state Exp;
branches;
next	1.19;

1.19
date	99.07.15.15.49.18;	author thomas;	state Exp;
branches;
next	1.18;

1.18
date	99.07.14.20.32.58;	author thomas;	state Exp;
branches;
next	1.17;

1.17
date	99.06.14.07.37.05;	author thomas;	state Exp;
branches;
next	1.16;

1.16
date	99.06.03.19.52.08;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	99.05.12.07.34.02;	author thomas;	state Exp;
branches;
next	1.14;

1.14
date	99.05.10.18.22.48;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	99.04.06.15.41.20;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	99.03.19.02.41.36;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	99.02.13.03.32.43;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	99.02.02.03.43.56;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	98.12.29.02.24.46;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	98.12.18.16.22.31;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	98.10.30.19.34.35;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.10.15.05.47.04;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	98.09.30.05.38.56;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.09.25.13.42.42;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.07.15.54.08;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.09.01.15.53.08;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.05.13.05.34.00;	author thomas;	state Exp;
branches;
next	;

1.67.2.1
date	2003.09.07.04.36.46;	author momjian;	state Exp;
branches;
next	;

1.71.2.1
date	2003.11.04.00.34.50;	author tgl;	state Exp;
branches;
next	1.71.2.2;

1.71.2.2
date	2004.09.13.01.59.35;	author neilc;	state Exp;
branches;
next	;

1.80.4.1
date	2005.01.22.23.23.53;	author momjian;	state Exp;
branches;
next	1.80.4.2;

1.80.4.2
date	2005.04.22.15.53.27;	author momjian;	state Exp;
branches;
next	1.80.4.3;

1.80.4.3
date	2006.12.01.20.50.06;	author tgl;	state Exp;
branches;
next	;

1.90.2.1
date	2006.12.01.20.49.59;	author tgl;	state Exp;
branches;
next	;

1.102.2.1
date	2009.01.22.22.56.54;	author momjian;	state Exp;
branches;
next	;

1.122.2.1
date	2009.08.27.20.08.12;	author tgl;	state Exp;
branches;
next	1.122.2.2;

1.122.2.2
date	2009.10.27.17.11.30;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.132
log
@Recognize functional dependency on primary keys.  This allows a table's
other columns to be referenced without listing them in GROUP BY, so long as
the primary key column(s) are listed in GROUP BY.

Eventually we should also allow functional dependency on a UNIQUE constraint
when the columns are marked NOT NULL, but that has to wait until NOT NULL
constraints are represented in pg_constraint, because we need to have
pg_constraint OIDs for all the conditions needed to ensure functional
dependency.

Peter Eisentraut, reviewed by Alex Hunsaker and Tom Lane
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.131 2010/06/15 20:04:53 momjian Exp $
PostgreSQL documentation
-->

<refentry id="SQL-SELECT">
 <refmeta>
  <refentrytitle>SELECT</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>SELECT</refname>
  <refname>TABLE</refname>
  <refname>WITH</refname>
  <refpurpose>retrieve rows from a table or view</refpurpose>
 </refnamediv>

 <indexterm zone="sql-select">
  <primary>SELECT</primary>
 </indexterm>

 <indexterm zone="sql-select">
  <primary>TABLE command</primary>
 </indexterm>

 <indexterm zone="sql-select">
  <primary>WITH</primary>
  <secondary>in SELECT</secondary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replaceable> [, ...] ) ] ]
    * | <replaceable class="parameter">expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...]
    [ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
    [ WHERE <replaceable class="parameter">condition</replaceable> ]
    [ GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] ]
    [ HAVING <replaceable class="parameter">condition</replaceable> [, ...] ]
    [ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] ]
    [ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="parameter">select</replaceable> ]
    [ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
    [ LIMIT { <replaceable class="parameter">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="parameter">start</replaceable> [ ROW | ROWS ] ]
    [ FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { ROW | ROWS } ONLY ]
    [ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ] [...] ]

<phrase>where <replaceable class="parameter">from_item</replaceable> can be one of:</phrase>

    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ] ]
    ( <replaceable class="parameter">select</replaceable> ) [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ]
    <replaceable class="parameter">with_query_name</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ] ]
    <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] | <replaceable class="parameter">column_definition</replaceable> [, ...] ) ]
    <replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) AS ( <replaceable class="parameter">column_definition</replaceable> [, ...] )
    <replaceable class="parameter">from_item</replaceable> [ NATURAL ] <replaceable class="parameter">join_type</replaceable> <replaceable class="parameter">from_item</replaceable> [ ON <replaceable class="parameter">join_condition</replaceable> | USING ( <replaceable class="parameter">join_column</replaceable> [, ...] ) ]

<phrase>and <replaceable class="parameter">with_query</replaceable> is:</phrase>

    <replaceable class="parameter">with_query_name</replaceable> [ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) ] AS ( <replaceable class="parameter">select</replaceable> )

TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] | <replaceable class="parameter">with_query_name</replaceable> }
</synopsis>

 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>SELECT</command> retrieves rows from zero or more tables.
   The general processing of <command>SELECT</command> is as follows:

   <orderedlist>
    <listitem>
     <para>
      All queries in the <literal>WITH</literal> list are computed.
      These effectively serve as temporary tables that can be referenced
      in the <literal>FROM</literal> list.  A <literal>WITH</literal> query
      that is referenced more than once in <literal>FROM</literal> is
      computed only once.
      (See <xref linkend="sql-with" endterm="sql-with-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      All elements in the <literal>FROM</literal> list are computed.
      (Each element in the <literal>FROM</literal> list is a real or
      virtual table.)  If more than one element is specified in the
      <literal>FROM</literal> list, they are cross-joined together.
      (See <xref linkend="sql-from" endterm="sql-from-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      If the <literal>WHERE</literal> clause is specified, all rows
      that do not satisfy the condition are eliminated from the
      output.  (See <xref linkend="sql-where"
      endterm="sql-where-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      If the <literal>GROUP BY</literal> clause is specified, the
      output is divided into groups of rows that match on one or more
      values.  If the <literal>HAVING</literal> clause is present, it
      eliminates groups that do not satisfy the given condition.  (See
      <xref linkend="sql-groupby" endterm="sql-groupby-title"> and
      <xref linkend="sql-having" endterm="sql-having-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      The actual output rows are computed using the
      <command>SELECT</command> output expressions for each selected
      row.  (See
      <xref linkend="sql-select-list" endterm="sql-select-list-title">
      below.)
     </para>
    </listitem>

    <listitem>
     <para>
      Using the operators <literal>UNION</literal>,
      <literal>INTERSECT</literal>, and <literal>EXCEPT</literal>, the
      output of more than one <command>SELECT</command> statement can
      be combined to form a single result set.  The
      <literal>UNION</literal> operator returns all rows that are in
      one or both of the result sets.  The
      <literal>INTERSECT</literal> operator returns all rows that are
      strictly in both result sets.  The <literal>EXCEPT</literal>
      operator returns the rows that are in the first result set but
      not in the second.  In all three cases, duplicate rows are
      eliminated unless <literal>ALL</literal> is specified. (See
      <xref linkend="sql-union" endterm="sql-union-title">, <xref
      linkend="sql-intersect" endterm="sql-intersect-title">, and
      <xref linkend="sql-except" endterm="sql-except-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      If the <literal>ORDER BY</literal> clause is specified, the
      returned rows are sorted in the specified order.  If
      <literal>ORDER BY</literal> is not given, the rows are returned
      in whatever order the system finds fastest to produce.  (See
      <xref linkend="sql-orderby" endterm="sql-orderby-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      <literal>DISTINCT</literal> eliminates duplicate rows from the
      result.  <literal>DISTINCT ON</literal> eliminates rows that
      match on all the specified expressions.  <literal>ALL</literal>
      (the default) will return all candidate rows, including
      duplicates.  (See <xref linkend="sql-distinct"
      endterm="sql-distinct-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      If the <literal>LIMIT</literal> (or <literal>FETCH FIRST</literal>) or <literal>OFFSET</literal>
      clause is specified, the <command>SELECT</command> statement
      only returns a subset of the result rows. (See <xref
      linkend="sql-limit" endterm="sql-limit-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
      If <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
      is specified, the
      <command>SELECT</command> statement locks the selected rows
      against concurrent updates.  (See <xref linkend="sql-for-update-share"
      endterm="sql-for-update-share-title"> below.)
     </para>
    </listitem>
   </orderedlist>
  </para>

  <para>
   You must have <literal>SELECT</literal> privilege on each column used
   in a <command>SELECT</> command.  The use of <literal>FOR UPDATE</literal>
   or <literal>FOR SHARE</literal> requires
   <literal>UPDATE</literal> privilege as well (for at least one column
   of each table so selected).
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <refsect2 id="SQL-WITH">
   <title id="sql-with-title"><literal>WITH</literal> Clause</title>

   <para>
    The <literal>WITH</literal> clause allows you to specify one or more
    subqueries that can be referenced by name in the primary query.
    The subqueries effectively act as temporary tables or views
    for the duration of the primary query.
   </para>

   <para>
    A name (without schema qualification) must be specified for each
    <literal>WITH</literal> query.  Optionally, a list of column names
    can be specified; if this is omitted,
    the column names are inferred from the subquery.
   </para>

   <para>
    If <literal>RECURSIVE</literal> is specified, it allows a
    subquery to reference itself by name.  Such a subquery must have
    the form
<synopsis>
<replaceable class="parameter">non_recursive_term</replaceable> UNION [ ALL ] <replaceable class="parameter">recursive_term</replaceable>
</synopsis>
    where the recursive self-reference must appear on the right-hand
    side of the <literal>UNION</>.  Only one recursive self-reference
    is permitted per query.
   </para>

   <para>
    Another effect of <literal>RECURSIVE</literal> is that
    <literal>WITH</literal> queries need not be ordered: a query
    can reference another one that is later in the list.  (However,
    circular references, or mutual recursion, are not implemented.)
    Without <literal>RECURSIVE</literal>, <literal>WITH</literal> queries
    can only reference sibling <literal>WITH</literal> queries
    that are earlier in the <literal>WITH</literal> list.
   </para>

   <para>
    A useful property of <literal>WITH</literal> queries is that they
    are evaluated only once per execution of the primary query,
    even if the primary query refers to them more than once.
   </para>

   <para>
    See <xref linkend="queries-with"> for additional information.
   </para>
  </refsect2>

  <refsect2 id="SQL-FROM">
   <title id="sql-from-title"><literal>FROM</literal> Clause</title>

   <para>
    The <literal>FROM</literal> clause specifies one or more source
    tables for the <command>SELECT</command>.  If multiple sources are
    specified, the result is the Cartesian product (cross join) of all
    the sources.  But usually qualification conditions
    are added to restrict the returned rows to a small subset of the
    Cartesian product.
   </para>

   <para>
    The <literal>FROM</literal> clause can contain the following
    elements:

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">table_name</replaceable></term>
      <listitem>
       <para>
        The name (optionally schema-qualified) of an existing table or
        view.  If <literal>ONLY</> is specified, only that table is
        scanned.  If <literal>ONLY</> is not specified, the table and
        any descendant tables are scanned.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">alias</replaceable></term>
      <listitem>
       <para>
        A substitute name for the <literal>FROM</> item containing the
        alias.  An alias is used for brevity or to eliminate ambiguity
        for self-joins (where the same table is scanned multiple
        times).  When an alias is provided, it completely hides the
        actual name of the table or function; for example given
        <literal>FROM foo AS f</>, the remainder of the
        <command>SELECT</command> must refer to this <literal>FROM</>
        item as <literal>f</> not <literal>foo</>.  If an alias is
        written, a column alias list can also be written to provide
        substitute names for one or more columns of the table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">select</replaceable></term>
      <listitem>
       <para>
        A sub-<command>SELECT</command> can appear in the
        <literal>FROM</literal> clause.  This acts as though its
        output were created as a temporary table for the duration of
        this single <command>SELECT</command> command.  Note that the
        sub-<command>SELECT</command> must be surrounded by
        parentheses, and an alias <emphasis>must</emphasis> be
        provided for it.  A
        <xref linkend="sql-values"> command
        can also be used here.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">with_query_name</replaceable></term>
      <listitem>
       <para>
        A <literal>WITH</> query is referenced by writing its name,
        just as though the query's name were a table name.  (In fact,
        the <literal>WITH</> query hides any real table of the same name
        for the purposes of the primary query.  If necessary, you can
        refer to a real table of the same name by schema-qualifying
        the table's name.)
        An alias can be provided in the same way as for a table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">function_name</replaceable></term>
      <listitem>
       <para>
        Function calls can appear in the <literal>FROM</literal>
        clause.  (This is especially useful for functions that return
        result sets, but any function can be used.)  This acts as
        though its output were created as a temporary table for the
        duration of this single <command>SELECT</command> command. An
        alias can also be used. If an alias is written, a column alias
        list can also be written to provide substitute names for one
        or more attributes of the function's composite return type. If
        the function has been defined as returning the <type>record</>
        data type, then an alias or the key word <literal>AS</> must
        be present, followed by a column definition list in the form
        <literal>( <replaceable
        class="parameter">column_name</replaceable> <replaceable
        class="parameter">data_type</replaceable> <optional>, ... </>
        )</literal>.  The column definition list must match the actual
        number and types of columns returned by the function.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">join_type</replaceable></term>
      <listitem>
       <para>
        One of
        <itemizedlist>
         <listitem>
          <para><literal>[ INNER ] JOIN</literal></para>
         </listitem>
         <listitem>
          <para><literal>LEFT [ OUTER ] JOIN</literal></para>
         </listitem>
         <listitem>
          <para><literal>RIGHT [ OUTER ] JOIN</literal></para>
         </listitem>
         <listitem>
          <para><literal>FULL [ OUTER ] JOIN</literal></para>
         </listitem>
         <listitem>
          <para><literal>CROSS JOIN</literal></para>
         </listitem>
        </itemizedlist>

        For the <literal>INNER</> and <literal>OUTER</> join types, a
        join condition must be specified, namely exactly one of
        <literal>NATURAL</>, <literal>ON <replaceable
        class="parameter">join_condition</replaceable></literal>, or
        <literal>USING (<replaceable
        class="parameter">join_column</replaceable> [, ...])</literal>.
        See below for the meaning.  For <literal>CROSS JOIN</literal>,
        none of these clauses can appear.
       </para>

       <para>
        A <literal>JOIN</literal> clause combines two
        <literal>FROM</> items.  Use parentheses if necessary to
        determine the order of nesting.  In the absence of parentheses,
        <literal>JOIN</literal>s nest left-to-right.  In any case
        <literal>JOIN</literal> binds more tightly than the commas
        separating <literal>FROM</> items.
       </para>

       <para>
        <literal>CROSS JOIN</> and <literal>INNER JOIN</literal>
        produce a simple Cartesian product, the same result as you get from
        listing the two items at the top level of <literal>FROM</>,
        but restricted by the join condition (if any).
        <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON
        (TRUE)</>, that is, no rows are removed by qualification.
        These join types are just a notational convenience, since they
        do nothing you couldn't do with plain <literal>FROM</> and
        <literal>WHERE</>.
       </para>

       <para>
        <literal>LEFT OUTER JOIN</> returns all rows in the qualified
        Cartesian product (i.e., all combined rows that pass its join
        condition), plus one copy of each row in the left-hand table
        for which there was no right-hand row that passed the join
        condition.  This left-hand row is extended to the full width
        of the joined table by inserting null values for the
        right-hand columns.  Note that only the <literal>JOIN</>
        clause's own condition is considered while deciding which rows
        have matches.  Outer conditions are applied afterwards.
       </para>

       <para>
        Conversely, <literal>RIGHT OUTER JOIN</> returns all the
        joined rows, plus one row for each unmatched right-hand row
        (extended with nulls on the left).  This is just a notational
        convenience, since you could convert it to a <literal>LEFT
        OUTER JOIN</> by switching the left and right inputs.
       </para>

       <para>
        <literal>FULL OUTER JOIN</> returns all the joined rows, plus
        one row for each unmatched left-hand row (extended with nulls
        on the right), plus one row for each unmatched right-hand row
        (extended with nulls on the left).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ON <replaceable class="parameter">join_condition</replaceable></literal></term>
      <listitem>
       <para>
        <replaceable class="parameter">join_condition</replaceable> is
        an expression resulting in a value of type
        <type>boolean</type> (similar to a <literal>WHERE</literal>
        clause) that specifies which rows in a join are considered to
        match.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>USING ( <replaceable class="parameter">join_column</replaceable> [, ...] )</literal></term>
      <listitem>
       <para>
        A clause of the form <literal>USING ( a, b, ... )</literal> is
        shorthand for <literal>ON left_table.a = right_table.a AND
        left_table.b = right_table.b ...</literal>.  Also,
        <literal>USING</> implies that only one of each pair of
        equivalent columns will be included in the join output, not
        both.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NATURAL</literal></term>
      <listitem>
       <para>
        <literal>NATURAL</literal> is shorthand for a
        <literal>USING</> list that mentions all columns in the two
        tables that have the same names.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="SQL-WHERE">
   <title id="sql-where-title"><literal>WHERE</literal> Clause</title>

   <para>
    The optional <literal>WHERE</literal> clause has the general form
<synopsis>
WHERE <replaceable class="parameter">condition</replaceable>
</synopsis>
    where <replaceable class="parameter">condition</replaceable> is
    any expression that evaluates to a result of type
    <type>boolean</type>.  Any row that does not satisfy this
    condition will be eliminated from the output.  A row satisfies the
    condition if it returns true when the actual row values are
    substituted for any variable references.
   </para>
  </refsect2>

  <refsect2 id="SQL-GROUPBY">
   <title id="sql-groupby-title"><literal>GROUP BY</literal> Clause</title>

   <para>
    The optional <literal>GROUP BY</literal> clause has the general form
<synopsis>
GROUP BY <replaceable class="parameter">expression</replaceable> [, ...]
</synopsis>
   </para>

   <para>
    <literal>GROUP BY</literal> will condense into a single row all
    selected rows that share the same values for the grouped
    expressions.  <replaceable
    class="parameter">expression</replaceable> can be an input column
    name, or the name or ordinal number of an output column
    (<command>SELECT</command> list item), or an arbitrary
    expression formed from input-column values.  In case of ambiguity,
    a <literal>GROUP BY</literal> name will be interpreted as an
    input-column name rather than an output column name.
   </para>

   <para>
    Aggregate functions, if any are used, are computed across all rows
    making up each group, producing a separate value for each group
    (whereas without <literal>GROUP BY</literal>, an aggregate
    produces a single value computed across all the selected rows).
    When <literal>GROUP BY</literal> is present, it is not valid for
    the <command>SELECT</command> list expressions to refer to
    ungrouped columns except within aggregate functions or if the
    ungrouped column is functionally dependent on the grouped columns,
    since there would otherwise be more than one possible value to
    return for an ungrouped column.  A functional dependency exists if
    the grouped columns (or a subset thereof) are the primary key of
    the table containing the ungrouped column.
   </para>
  </refsect2>

  <refsect2 id="SQL-HAVING">
   <title id="sql-having-title"><literal>HAVING</literal> Clause</title>

   <para>
    The optional <literal>HAVING</literal> clause has the general form
<synopsis>
HAVING <replaceable class="parameter">condition</replaceable>
</synopsis>
    where <replaceable class="parameter">condition</replaceable> is
    the same as specified for the <literal>WHERE</literal> clause.
   </para>

   <para>
    <literal>HAVING</literal> eliminates group rows that do not
    satisfy the condition.  <literal>HAVING</literal> is different
    from <literal>WHERE</literal>: <literal>WHERE</literal> filters
    individual rows before the application of <literal>GROUP
    BY</literal>, while <literal>HAVING</literal> filters group rows
    created by <literal>GROUP BY</literal>.  Each column referenced in
    <replaceable class="parameter">condition</replaceable> must
    unambiguously reference a grouping column, unless the reference
    appears within an aggregate function.
   </para>

   <para>
    The presence of <literal>HAVING</literal> turns a query into a grouped
    query even if there is no <literal>GROUP BY</> clause.  This is the
    same as what happens when the query contains aggregate functions but
    no <literal>GROUP BY</> clause.  All the selected rows are considered to
    form a single group, and the <command>SELECT</command> list and
    <literal>HAVING</literal> clause can only reference table columns from
    within aggregate functions.  Such a query will emit a single row if the
    <literal>HAVING</literal> condition is true, zero rows if it is not true.
   </para>
  </refsect2>

  <refsect2 id="SQL-WINDOW">
   <title id="sql-window-title"><literal>WINDOW</literal> Clause</title>

   <para>
    The optional <literal>WINDOW</literal> clause has the general form
<synopsis>
WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...]
</synopsis>
    where <replaceable class="parameter">window_name</replaceable> is
    a name that can be referenced from subsequent window definitions or
    <literal>OVER</> clauses, and
    <replaceable class="parameter">window_definition</replaceable> is
<synopsis>
[ <replaceable class="parameter">existing_window_name</replaceable> ]
[ PARTITION BY <replaceable class="parameter">expression</replaceable> [, ...] ]
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
[ <replaceable class="parameter">frame_clause</replaceable> ]
</synopsis>
   </para>

   <para>
    If an <replaceable class="parameter">existing_window_name</replaceable>
    is specified it must refer to an earlier entry in the <literal>WINDOW</>
    list; the new window copies its partitioning clause from that entry,
    as well as its ordering clause if any.  In this case the new window cannot
    specify its own <literal>PARTITION BY</> clause, and it can specify
    <literal>ORDER BY</> only if the copied window does not have one.
    The new window always uses its own frame clause; the copied window
    must not specify a frame clause.
   </para>

   <para>
    The elements of the <literal>PARTITION BY</> list are interpreted in
    much the same fashion as elements of a
    <xref linkend="sql-groupby" endterm="sql-groupby-title">, except that
    they are always simple expressions and never the name or number of an
    output column.
    Another difference is that these expressions can contain aggregate
    function calls, which are not allowed in a regular <literal>GROUP BY</>
    clause.  They are allowed here because windowing occurs after grouping
    and aggregation.
   </para>

   <para>
    Similarly, the elements of the <literal>ORDER BY</> list are interpreted
    in much the same fashion as elements of an
    <xref linkend="sql-orderby" endterm="sql-orderby-title">, except that
    the expressions are always taken as simple expressions and never the name
    or number of an output column.
   </para>

   <para>
    The optional <replaceable class="parameter">frame_clause</> defines
    the <firstterm>window frame</> for window functions that depend on the
    frame (not all do).  The window frame is a set of related rows for
    each row of the query (called the <firstterm>current row</>).
    The <replaceable class="parameter">frame_clause</> can be one of

<synopsis>
[ RANGE | ROWS ] <replaceable>frame_start</>
[ RANGE | ROWS ] BETWEEN <replaceable>frame_start</> AND <replaceable>frame_end</>
</synopsis>

    where <replaceable>frame_start</> and <replaceable>frame_end</> can be
    one of

<synopsis>
UNBOUNDED PRECEDING
<replaceable>value</replaceable> PRECEDING
CURRENT ROW
<replaceable>value</replaceable> FOLLOWING
UNBOUNDED FOLLOWING
</synopsis>

    If <replaceable>frame_end</> is omitted it defaults to <literal>CURRENT
    ROW</>.  Restrictions are that
    <replaceable>frame_start</> cannot be <literal>UNBOUNDED FOLLOWING</>,
    <replaceable>frame_end</> cannot be <literal>UNBOUNDED PRECEDING</>,
    and the <replaceable>frame_end</> choice cannot appear earlier in the
    above list than the <replaceable>frame_start</> choice &mdash; for example
    <literal>RANGE BETWEEN CURRENT ROW AND <replaceable>value</>
    PRECEDING</literal> is not allowed.
   </para>

   <para>
    The default framing option is <literal>RANGE UNBOUNDED PRECEDING</>,
    which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND
    CURRENT ROW</>; it sets the frame to be all rows from the partition start
    up through the current row's last peer in the <literal>ORDER BY</>
    ordering (which means all rows if there is no <literal>ORDER BY</>).
    In general, <literal>UNBOUNDED PRECEDING</> means that the frame
    starts with the first row of the partition, and similarly
    <literal>UNBOUNDED FOLLOWING</> means that the frame ends with the last
    row of the partition (regardless of <literal>RANGE</> or <literal>ROWS</>
    mode).  In <literal>ROWS</> mode, <literal>CURRENT ROW</>
    means that the frame starts or ends with the current row; but in
    <literal>RANGE</> mode it means that the frame starts or ends with
    the current row's first or last peer in the <literal>ORDER BY</> ordering.
    The <replaceable>value</> <literal>PRECEDING</> and
    <replaceable>value</> <literal>FOLLOWING</> cases are currently only
    allowed in <literal>ROWS</> mode.  They indicate that the frame starts
    or ends with the row that many rows before or after the current row.
    <replaceable>value</replaceable> must be an integer expression not
    containing any variables, aggregate functions, or window functions.
    The value must not be null or negative; but it can be zero, which
    selects the current row itself.
   </para>

   <para>
    Beware that the <literal>ROWS</> options can produce unpredictable
    results if the <literal>ORDER BY</> ordering does not order the rows
    uniquely.  The <literal>RANGE</> options are designed to ensure that
    rows that are peers in the <literal>ORDER BY</> ordering are treated
    alike; any two peer rows will be both in or both not in the frame.
   </para>

   <para>
    The purpose of a <literal>WINDOW</literal> clause is to specify the
    behavior of <firstterm>window functions</> appearing in the query's
    <xref linkend="sql-select-list" endterm="sql-select-list-title"> or
    <xref linkend="sql-orderby" endterm="sql-orderby-title">.  These functions
    can reference the <literal>WINDOW</literal> clause entries by name
    in their <literal>OVER</> clauses.  A <literal>WINDOW</literal> clause
    entry does not have to be referenced anywhere, however; if it is not
    used in the query it is simply ignored.  It is possible to use window
    functions without any <literal>WINDOW</literal> clause at all, since
    a window function call can specify its window definition directly in
    its <literal>OVER</> clause.  However, the <literal>WINDOW</literal>
    clause saves typing when the same window definition is needed for more
    than one window function.
   </para>

   <para>
    Window functions are described in detail in
    <xref linkend="tutorial-window">,
    <xref linkend="syntax-window-functions">, and
    <xref linkend="queries-window">.
   </para>
  </refsect2>

  <refsect2 id="sql-select-list">
   <title id="sql-select-list-title"><command>SELECT</command> List</title>

   <para>
    The <command>SELECT</command> list (between the key words
    <literal>SELECT</> and <literal>FROM</>) specifies expressions
    that form the output rows of the <command>SELECT</command>
    statement.  The expressions can (and usually do) refer to columns
    computed in the <literal>FROM</> clause.
   </para>

   <para>
    Just as in a table, every output column of a <command>SELECT</command>
    has a name.  In a simple <command>SELECT</command> this name is just
    used to label the column for display, but when the <command>SELECT</>
    is a sub-query of a larger query, the name is seen by the larger query
    as the column name of the virtual table produced by the sub-query.
    To specify the name to use for an output column, write
    <literal>AS</> <replaceable class="parameter">output_name</replaceable>
    after the column's expression.  (You can omit <literal>AS</literal>,
    but only if the desired output name does not match any
    <productname>PostgreSQL</productname> keyword (see <xref
    linkend="sql-keywords-appendix">).  For protection against possible
    future keyword additions, it is recommended that you always either
    write <literal>AS</literal> or double-quote the output name.)
    If you do not specify a column name, a name is chosen automatically
    by <productname>PostgreSQL</productname>.  If the column's expression
    is a simple column reference then the chosen name is the same as that
    column's name; in more complex cases a generated name looking like
    <literal>?column<replaceable>N</>?</literal> is usually chosen.
   </para>

   <para>
    An output column's name can be used to refer to the column's value in
    <literal>ORDER BY</> and <literal>GROUP BY</> clauses, but not in the
    <literal>WHERE</> or <literal>HAVING</> clauses; there you must write
    out the expression instead.
   </para>

   <para>
    Instead of an expression, <literal>*</literal> can be written in
    the output list as a shorthand for all the columns of the selected
    rows.  Also, you can write <literal><replaceable
    class="parameter">table_name</replaceable>.*</literal> as a
    shorthand for the columns coming from just that table.  In these
    cases it is not possible to specify new names with <literal>AS</>;
    the output column names will be the same as the table columns' names.
   </para>
  </refsect2>

  <refsect2 id="SQL-UNION">
   <title id="sql-union-title"><literal>UNION</literal> Clause</title>

   <para>
    The <literal>UNION</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> UNION [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
    <replaceable class="parameter">select_statement</replaceable> is
    any <command>SELECT</command> statement without an <literal>ORDER
    BY</>, <literal>LIMIT</>, <literal>FOR UPDATE</literal>, or
    <literal>FOR SHARE</literal> clause.
    (<literal>ORDER BY</> and <literal>LIMIT</> can be attached to a
    subexpression if it is enclosed in parentheses.  Without
    parentheses, these clauses will be taken to apply to the result of
    the <literal>UNION</literal>, not to its right-hand input
    expression.)
   </para>

   <para>
    The <literal>UNION</literal> operator computes the set union of
    the rows returned by the involved <command>SELECT</command>
    statements.  A row is in the set union of two result sets if it
    appears in at least one of the result sets.  The two
    <command>SELECT</command> statements that represent the direct
    operands of the <literal>UNION</literal> must produce the same
    number of columns, and corresponding columns must be of compatible
    data types.
   </para>

   <para>
    The result of <literal>UNION</> does not contain any duplicate
    rows unless the <literal>ALL</> option is specified.
    <literal>ALL</> prevents elimination of duplicates.  (Therefore,
    <literal>UNION ALL</> is usually significantly quicker than
    <literal>UNION</>; use <literal>ALL</> when you can.)
   </para>

   <para>
    Multiple <literal>UNION</> operators in the same
    <command>SELECT</command> statement are evaluated left to right,
    unless otherwise indicated by parentheses.
   </para>

   <para>
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> cannot be
    specified either for a <literal>UNION</> result or for any input of a
    <literal>UNION</>.
   </para>
  </refsect2>

  <refsect2 id="SQL-INTERSECT">
   <title id="sql-intersect-title"><literal>INTERSECT</literal> Clause</title>

   <para>
    The <literal>INTERSECT</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> INTERSECT [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
    <replaceable class="parameter">select_statement</replaceable> is
    any <command>SELECT</command> statement without an <literal>ORDER
    BY</>, <literal>LIMIT</>, <literal>FOR UPDATE</literal>, or
    <literal>FOR SHARE</literal> clause.
   </para>

   <para>
    The <literal>INTERSECT</literal> operator computes the set
    intersection of the rows returned by the involved
    <command>SELECT</command> statements.  A row is in the
    intersection of two result sets if it appears in both result sets.
   </para>

   <para>
    The result of <literal>INTERSECT</literal> does not contain any
    duplicate rows unless the <literal>ALL</> option is specified.
    With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the
    left table and <replaceable>n</> duplicates in the right table will appear
    min(<replaceable>m</>,<replaceable>n</>) times in the result set.
   </para>

   <para>
    Multiple <literal>INTERSECT</literal> operators in the same
    <command>SELECT</command> statement are evaluated left to right,
    unless parentheses dictate otherwise.
    <literal>INTERSECT</literal> binds more tightly than
    <literal>UNION</literal>.  That is, <literal>A UNION B INTERSECT
    C</literal> will be read as <literal>A UNION (B INTERSECT
    C)</literal>.
   </para>

   <para>
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> cannot be
    specified either for an <literal>INTERSECT</> result or for any input of
    an <literal>INTERSECT</>.
   </para>
  </refsect2>

  <refsect2 id="SQL-EXCEPT">
   <title id="sql-except-title"><literal>EXCEPT</literal> Clause</title>

   <para>
    The <literal>EXCEPT</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> EXCEPT [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
    <replaceable class="parameter">select_statement</replaceable> is
    any <command>SELECT</command> statement without an <literal>ORDER
    BY</>, <literal>LIMIT</>, <literal>FOR UPDATE</literal>, or
    <literal>FOR SHARE</literal> clause.
   </para>

   <para>
    The <literal>EXCEPT</literal> operator computes the set of rows
    that are in the result of the left <command>SELECT</command>
    statement but not in the result of the right one.
   </para>

   <para>
    The result of <literal>EXCEPT</literal> does not contain any
    duplicate rows unless the <literal>ALL</> option is specified.
    With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the
    left table and <replaceable>n</> duplicates in the right table will appear
    max(<replaceable>m</>-<replaceable>n</>,0) times in the result set.
   </para>

   <para>
    Multiple <literal>EXCEPT</literal> operators in the same
    <command>SELECT</command> statement are evaluated left to right,
    unless parentheses dictate otherwise.  <literal>EXCEPT</> binds at
    the same level as <literal>UNION</>.
   </para>

   <para>
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> cannot be
    specified either for an <literal>EXCEPT</> result or for any input of
    an <literal>EXCEPT</>.
   </para>
  </refsect2>

  <refsect2 id="SQL-ORDERBY">
   <title id="sql-orderby-title"><literal>ORDER BY</literal> Clause</title>

   <para>
    The optional <literal>ORDER BY</literal> clause has this general form:
<synopsis>
ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...]
</synopsis>
    The <literal>ORDER BY</literal> clause causes the result rows to
    be sorted according to the specified expression(s).  If two rows are
    equal according to the leftmost expression, they are compared
    according to the next expression and so on.  If they are equal
    according to all specified expressions, they are returned in
    an implementation-dependent order.
   </para>

   <para>
    Each <replaceable class="parameter">expression</replaceable> can be the
    name or ordinal number of an output column
    (<command>SELECT</command> list item), or it can be an arbitrary
    expression formed from input-column values.
   </para>

   <para>
    The ordinal number refers to the ordinal (left-to-right) position
    of the output column. This feature makes it possible to define an
    ordering on the basis of a column that does not have a unique
    name.  This is never absolutely necessary because it is always
    possible to assign a name to an output column using the
    <literal>AS</> clause.
   </para>

   <para>
    It is also possible to use arbitrary expressions in the
    <literal>ORDER BY</literal> clause, including columns that do not
    appear in the <command>SELECT</command> output list.  Thus the
    following statement is valid:
<programlisting>
SELECT name FROM distributors ORDER BY code;
</programlisting>
    A limitation of this feature is that an <literal>ORDER BY</>
    clause applying to the result of a <literal>UNION</>,
    <literal>INTERSECT</>, or <literal>EXCEPT</> clause can only
    specify an output column name or number, not an expression.
   </para>

   <para>
    If an <literal>ORDER BY</> expression is a simple name that
    matches both an output column name and an input column name,
    <literal>ORDER BY</> will interpret it as the output column name.
    This is the opposite of the choice that <literal>GROUP BY</> will
    make in the same situation.  This inconsistency is made to be
    compatible with the SQL standard.
   </para>

   <para>
    Optionally one can add the key word <literal>ASC</> (ascending) or
    <literal>DESC</> (descending) after any expression in the
    <literal>ORDER BY</> clause.  If not specified, <literal>ASC</> is
    assumed by default.  Alternatively, a specific ordering operator
    name can be specified in the <literal>USING</> clause.
    An ordering operator must be a less-than or greater-than
    member of some B-tree operator family.
    <literal>ASC</> is usually equivalent to <literal>USING &lt;</> and
    <literal>DESC</> is usually equivalent to <literal>USING &gt;</>.
    (But the creator of a user-defined data type can define exactly what the
    default sort ordering is, and it might correspond to operators with other
    names.)
   </para>

   <para>
    If <literal>NULLS LAST</> is specified, null values sort after all
    non-null values; if <literal>NULLS FIRST</> is specified, null values
    sort before all non-null values.  If neither is specified, the default
    behavior is <literal>NULLS LAST</> when <literal>ASC</> is specified
    or implied, and <literal>NULLS FIRST</> when <literal>DESC</> is specified
    (thus, the default is to act as though nulls are larger than non-nulls).
    When <literal>USING</> is specified, the default nulls ordering depends
    on whether the operator is a less-than or greater-than operator.
   </para>

   <para>
    Note that ordering options apply only to the expression they follow;
    for example <literal>ORDER BY x, y DESC</> does not mean
    the same thing as <literal>ORDER BY x DESC, y DESC</>.
   </para>

   <para>
    Character-string data is sorted according to the locale-specific
    collation order that was established when the database was created.
   </para>
  </refsect2>

  <refsect2 id="sql-distinct">
   <title id="sql-distinct-title"><literal>DISTINCT</literal> Clause</title>

   <para>
    If <literal>DISTINCT</> is specified, all duplicate rows are
    removed from the result set (one row is kept from each group of
    duplicates).  <literal>ALL</> specifies the opposite: all rows are
    kept; that is the default.
   </para>

   <para>
    <literal>DISTINCT ON ( <replaceable
    class="parameter">expression</replaceable> [, ...] )</literal>
    keeps only the first row of each set of rows where the given
    expressions evaluate to equal.  The <literal>DISTINCT ON</literal>
    expressions are interpreted using the same rules as for
    <literal>ORDER BY</> (see above).  Note that the <quote>first
    row</quote> of each set is unpredictable unless <literal>ORDER
    BY</> is used to ensure that the desired row appears first.  For
    example:
<programlisting>
SELECT DISTINCT ON (location) location, time, report
    FROM weather_reports
    ORDER BY location, time DESC;
</programlisting>
    retrieves the most recent weather report for each location.  But
    if we had not used <literal>ORDER BY</> to force descending order
    of time values for each location, we'd have gotten a report from
    an unpredictable time for each location.
   </para>

   <para>
    The <literal>DISTINCT ON</> expression(s) must match the leftmost
    <literal>ORDER BY</> expression(s).  The <literal>ORDER BY</> clause
    will normally contain additional expression(s) that determine the
    desired precedence of rows within each <literal>DISTINCT ON</> group.
   </para>
  </refsect2>

  <refsect2 id="SQL-LIMIT">
   <title id="sql-limit-title"><literal>LIMIT</literal> Clause</title>

   <para>
    The <literal>LIMIT</literal> clause consists of two independent
    sub-clauses:
<synopsis>
LIMIT { <replaceable class="parameter">count</replaceable> | ALL }
OFFSET <replaceable class="parameter">start</replaceable>
</synopsis>
    <replaceable class="parameter">count</replaceable> specifies the
    maximum number of rows to return, while <replaceable
    class="parameter">start</replaceable> specifies the number of rows
    to skip before starting to return rows.  When both are specified,
    <replaceable class="parameter">start</replaceable> rows are skipped
    before starting to count the <replaceable
    class="parameter">count</replaceable> rows to be returned.
   </para>

   <para>
    If the <replaceable class="parameter">count</replaceable> expression
    evaluates to NULL, it is treated as <literal>LIMIT ALL</>, i.e., no
    limit.  If <replaceable class="parameter">start</replaceable> evaluates
    to NULL, it is treated the same as <literal>OFFSET 0</>.
   </para>

   <para>
    SQL:2008 introduced a different syntax to achieve the same thing,
    which <productname>PostgreSQL</> also supports.  It is:
<synopsis>
OFFSET <replaceable class="parameter">start</replaceable> { ROW | ROWS }
FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { ROW | ROWS } ONLY
</synopsis>
    According to the standard, the <literal>OFFSET</literal> clause must come
    before the <literal>FETCH</literal> clause if both are present; but
    <productname>PostgreSQL</> is laxer and allows either order.
    <literal>ROW</literal>
    and <literal>ROWS</literal> as well as <literal>FIRST</literal>
    and <literal>NEXT</literal> are noise words that don't influence
    the effects of these clauses.  In this syntax, when using expressions
    other than simple constants for <replaceable class="parameter">start</>
    or <replaceable class="parameter">count</replaceable>, parentheses will be
    necessary in most cases.  If <replaceable class="parameter">count</> is
    omitted in <literal>FETCH</>, it defaults to 1.
   </para>

   <para>
    When using <literal>LIMIT</>, it is a good idea to use an
    <literal>ORDER BY</> clause that constrains the result rows into a
    unique order.  Otherwise you will get an unpredictable subset of
    the query's rows &mdash; you might be asking for the tenth through
    twentieth rows, but tenth through twentieth in what ordering?  You
    don't know what ordering unless you specify <literal>ORDER BY</>.
   </para>

   <para>
    The query planner takes <literal>LIMIT</> into account when
    generating a query plan, so you are very likely to get different
    plans (yielding different row orders) depending on what you use
    for <literal>LIMIT</> and <literal>OFFSET</>.  Thus, using
    different <literal>LIMIT</>/<literal>OFFSET</> values to select
    different subsets of a query result <emphasis>will give
    inconsistent results</emphasis> unless you enforce a predictable
    result ordering with <literal>ORDER BY</>.  This is not a bug; it
    is an inherent consequence of the fact that SQL does not promise
    to deliver the results of a query in any particular order unless
    <literal>ORDER BY</> is used to constrain the order.
   </para>

   <para>
    It is even possible for repeated executions of the same <literal>LIMIT</>
    query to return different subsets of the rows of a table, if there
    is not an <literal>ORDER BY</> to enforce selection of a deterministic
    subset.  Again, this is not a bug; determinism of the results is
    simply not guaranteed in such a case.
   </para>
  </refsect2>

  <refsect2 id="SQL-FOR-UPDATE-SHARE">
   <title id="sql-for-update-share-title"><literal>FOR UPDATE</literal>/<literal>FOR SHARE</literal> Clause</title>

   <para>
    The <literal>FOR UPDATE</literal> clause has this form:
<synopsis>
FOR UPDATE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ]
</synopsis>
   </para>

   <para>
    The closely related <literal>FOR SHARE</literal> clause has this form:
<synopsis>
FOR SHARE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ]
</synopsis>
   </para>

   <para>
    <literal>FOR UPDATE</literal> causes the rows retrieved by the
    <command>SELECT</command> statement to be locked as though for
    update.  This prevents them from being modified or deleted by
    other transactions until the current transaction ends.  That is,
    other transactions that attempt <command>UPDATE</command>,
    <command>DELETE</command>, or <command>SELECT FOR UPDATE</command>
    of these rows will be blocked until the current transaction ends.
    Also, if an <command>UPDATE</command>, <command>DELETE</command>,
    or <command>SELECT FOR UPDATE</command> from another transaction
    has already locked a selected row or rows, <command>SELECT FOR
    UPDATE</command> will wait for the other transaction to complete,
    and will then lock and return the updated row (or no row, if the
    row was deleted).  Within a <literal>SERIALIZABLE</> transaction,
    however, an error will be thrown if a row to be locked has changed
    since the transaction started.  For further discussion see <xref
    linkend="mvcc">.
   </para>

   <para>
    <literal>FOR SHARE</literal> behaves similarly, except that it
    acquires a shared rather than exclusive lock on each retrieved
    row.  A shared lock blocks other transactions from performing
    <command>UPDATE</command>, <command>DELETE</command>, or <command>SELECT
    FOR UPDATE</command> on these rows, but it does not prevent them
    from performing <command>SELECT FOR SHARE</command>.
   </para>

   <para>
    To prevent the operation from waiting for other transactions to commit,
    use the <literal>NOWAIT</> option.  With <literal>NOWAIT</>, the statement
    reports an error, rather than waiting, if a selected row
    cannot be locked immediately.  Note that <literal>NOWAIT</> applies only
    to the row-level lock(s) &mdash; the required <literal>ROW SHARE</literal>
    table-level lock is still taken in the ordinary way (see
    <xref linkend="mvcc">).  You can use
    <xref linkend="sql-lock">
    with the <literal>NOWAIT</> option first,
    if you need to acquire the table-level lock without waiting.
   </para>

   <para>
    If specific tables are named in <literal>FOR UPDATE</literal>
    or <literal>FOR SHARE</literal>,
    then only rows coming from those tables are locked; any other
    tables used in the <command>SELECT</command> are simply read as
    usual.  A <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
    clause without a table list affects all tables used in the statement.
    If <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal> is
    applied to a view or sub-query, it affects all tables used in
    the view or sub-query.
    However, <literal>FOR UPDATE</literal>/<literal>FOR SHARE</literal>
    do not apply to <literal>WITH</> queries referenced by the primary query.
    If you want row locking to occur within a <literal>WITH</> query, specify
    <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal> within the
    <literal>WITH</> query.
   </para>

   <para>
    Multiple <literal>FOR UPDATE</literal> and <literal>FOR SHARE</literal>
    clauses can be written if it is necessary to specify different locking
    behavior for different tables.  If the same table is mentioned (or
    implicitly affected) by both <literal>FOR UPDATE</literal> and
    <literal>FOR SHARE</literal> clauses, then it is processed as
    <literal>FOR UPDATE</literal>.  Similarly, a table is processed
    as <literal>NOWAIT</> if that is specified in any of the clauses
    affecting it.
   </para>

   <para>
    <literal>FOR UPDATE</literal> and <literal>FOR SHARE</literal> cannot be
    used in contexts where returned rows cannot be clearly identified with
    individual table rows; for example they cannot be used with aggregation.
   </para>

   <para>
    When <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
    appears at the top level of a <command>SELECT</> query, the rows that
    are locked are exactly those that are returned by the query; in the
    case of a join query, the rows locked are those that contribute to
    returned join rows.  In addition, rows that satisfied the query
    conditions as of the query snapshot will be locked, although they
    will not be returned if they were updated after the snapshot
    and no longer satisfy the query conditions.  If a
    <literal>LIMIT</> is used, locking stops
    once enough rows have been returned to satisfy the limit (but note that
    rows skipped over by <literal>OFFSET</> will get locked).  Similarly,
    if <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
    is used in a cursor's query, only rows actually fetched or stepped past
    by the cursor will be locked.
   </para>

   <para>
    When <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
    appears in a sub-<command>SELECT</>, the rows locked are those
    returned to the outer query by the sub-query.  This might involve
    fewer rows than inspection of the sub-query alone would suggest,
    since conditions from the outer query might be used to optimize
    execution of the sub-query.  For example,
<programlisting>
SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss WHERE col1 = 5;
</programlisting>
    will lock only rows having <literal>col1 = 5</>, even though that
    condition is not textually within the sub-query.
   </para>

  <caution>
   <para>
    Avoid locking a row and then modifying it within a later savepoint or
    <application>PL/pgSQL</application> exception block.  A subsequent
    rollback would cause the lock to be lost.  For example:
<programlisting>
BEGIN;
SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
SAVEPOINT s;
UPDATE mytable SET ... WHERE key = 1;
ROLLBACK TO s;
</programlisting>
    After the <command>ROLLBACK</>, the row is effectively unlocked, rather
    than returned to its pre-savepoint state of being locked but not modified.
    This hazard occurs if a row locked in the current transaction is updated
    or deleted, or if a shared lock is upgraded to exclusive: in all these
    cases, the former lock state is forgotten.  If the transaction is then
    rolled back to a state between the original locking command and the
    subsequent change, the row will appear not to be locked at all.  This is
    an implementation deficiency which will be addressed in a future release
    of <productname>PostgreSQL</productname>.
   </para>
  </caution>

  <caution>
   <para>
    It is possible for a <command>SELECT</> command using <literal>ORDER
    BY</literal> and <literal>FOR UPDATE/SHARE</literal> to return rows out of
    order.  This is because <literal>ORDER BY</> is applied first.
    The command sorts the result, but might then block trying to obtain a lock
    on one or more of the rows.  Once the <literal>SELECT</> unblocks, some
    of the ordering column values might have been modified, leading to those
    rows appearing to be out of order (though they are in order in terms
    of the original column values).  This can be worked around at need by
    placing the <literal>FOR UPDATE/SHARE</literal> clause in a sub-query,
    for example
<programlisting>
SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss ORDER BY column1;
</programlisting>
    Note that this will result in locking all rows of <structname>mytable</>,
    whereas <literal>FOR UPDATE</> at the top level would lock only the
    actually returned rows.  This can make for a significant performance
    difference, particularly if the <literal>ORDER BY</> is combined with
    <literal>LIMIT</> or other restrictions.  So this technique is recommended
    only if concurrent updates of the ordering columns are expected and a
    strictly sorted result is required.
   </para>
  </caution>
  </refsect2>

  <refsect2 id="SQL-TABLE">
   <title><literal>TABLE</literal> Command</title>

   <para>
    The command
<programlisting>
TABLE <replaceable class="parameter">name</replaceable>
</programlisting>
    is completely equivalent to
<programlisting>
SELECT * FROM <replaceable class="parameter">name</replaceable>
</programlisting>
    It can be used as a top-level command or as a space-saving syntax
    variant in parts of complex queries.
   </para>
  </refsect2>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To join the table <literal>films</literal> with the table
   <literal>distributors</literal>:

<programlisting>
SELECT f.title, f.did, d.name, f.date_prod, f.kind
    FROM distributors d, films f
    WHERE f.did = d.did

       title       | did |     name     | date_prod  |   kind
-------------------+-----+--------------+------------+----------
 The Third Man     | 101 | British Lion | 1949-12-23 | Drama
 The African Queen | 101 | British Lion | 1951-08-11 | Romantic
 ...
</programlisting>
  </para>

  <para>
   To sum the column <literal>len</literal> of all films and group
   the results by <literal>kind</literal>:

<programlisting>
SELECT kind, sum(len) AS total FROM films GROUP BY kind;

   kind   | total
----------+-------
 Action   | 07:34
 Comedy   | 02:58
 Drama    | 14:28
 Musical  | 06:42
 Romantic | 04:38
</programlisting>
  </para>

  <para>
   To sum the column <literal>len</literal> of all films, group
   the results by <literal>kind</literal> and show those group totals
   that are less than 5 hours:

<programlisting>
SELECT kind, sum(len) AS total
    FROM films
    GROUP BY kind
    HAVING sum(len) &lt; interval '5 hours';

   kind   | total
----------+-------
 Comedy   | 02:58
 Romantic | 04:38
</programlisting>
  </para>

  <para>
   The following two examples are identical ways of sorting the individual
   results according to the contents of the second column
   (<literal>name</literal>):

<programlisting>
SELECT * FROM distributors ORDER BY name;
SELECT * FROM distributors ORDER BY 2;

 did |       name
-----+------------------
 109 | 20th Century Fox
 110 | Bavaria Atelier
 101 | British Lion
 107 | Columbia
 102 | Jean Luc Godard
 113 | Luso films
 104 | Mosfilm
 103 | Paramount
 106 | Toho
 105 | United Artists
 111 | Walt Disney
 112 | Warner Bros.
 108 | Westward
</programlisting>
  </para>

  <para>
   The next example shows how to obtain the union of the tables
   <literal>distributors</literal> and
   <literal>actors</literal>, restricting the results to those that begin
   with the letter W in each table.  Only distinct rows are wanted, so the
   key word <literal>ALL</literal> is omitted.

<programlisting>
distributors:               actors:
 did |     name              id |     name
-----+--------------        ----+----------------
 108 | Westward               1 | Woody Allen
 111 | Walt Disney            2 | Warren Beatty
 112 | Warner Bros.           3 | Walter Matthau
 ...                         ...

SELECT distributors.name
    FROM distributors
    WHERE distributors.name LIKE 'W%'
UNION
SELECT actors.name
    FROM actors
    WHERE actors.name LIKE 'W%';

      name
----------------
 Walt Disney
 Walter Matthau
 Warner Bros.
 Warren Beatty
 Westward
 Woody Allen
</programlisting>
  </para>

  <para>
   This example shows how to use a function in the <literal>FROM</>
   clause, both with and without a column definition list:

<programlisting>
CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS $$
    SELECT * FROM distributors WHERE did = $1;
$$ LANGUAGE SQL;

SELECT * FROM distributors(111);
 did |    name
-----+-------------
 111 | Walt Disney

CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS $$
    SELECT * FROM distributors WHERE did = $1;
$$ LANGUAGE SQL;

SELECT * FROM distributors_2(111) AS (f1 int, f2 text);
 f1  |     f2
-----+-------------
 111 | Walt Disney
</programlisting>
  </para>

  <para>
   This example shows how to use a simple <literal>WITH</> clause:

<programlisting>
WITH t AS (
    SELECT random() as x FROM generate_series(1, 3)
  )
SELECT * FROM t
UNION ALL
SELECT * FROM t

         x          
--------------------
  0.534150459803641
  0.520092216785997
 0.0735620250925422
  0.534150459803641
  0.520092216785997
 0.0735620250925422
</programlisting>

   Notice that the <literal>WITH</> query was evaluated only once,
   so that we got two sets of the same three random values.
  </para>

  <para>
   This example uses <literal>WITH RECURSIVE</literal> to find all
   subordinates (direct or indirect) of the employee Mary, and their
   level of indirectness, from a table that shows only direct
   subordinates:

<programlisting>
WITH RECURSIVE employee_recursive(distance, employee_name, manager_name) AS (
    SELECT 1, employee_name, manager_name
    FROM employee
    WHERE manager_name = 'Mary'
  UNION ALL
    SELECT er.distance + 1, e.employee_name, e.manager_name
    FROM employee_recursive er, employee e
    WHERE er.employee_name = e.manager_name
  )
SELECT distance, employee_name FROM employee_recursive;
</programlisting>

   Notice the typical form of recursive queries:
   an initial condition, followed by <literal>UNION</literal>,
   followed by the recursive part of the query. Be sure that the
   recursive part of the query will eventually return no tuples, or
   else the query will loop indefinitely.  (See <xref linkend="queries-with">
   for more examples.)
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   Of course, the <command>SELECT</command> statement is compatible
   with the SQL standard.  But there are some extensions and some
   missing features.
  </para>

  <refsect2>
   <title>Omitted <literal>FROM</literal> Clauses</title>

   <para>
    <productname>PostgreSQL</productname> allows one to omit the
    <literal>FROM</literal> clause.  It has a straightforward use to
    compute the results of simple expressions:
<programlisting>
SELECT 2+2;

 ?column?
----------
        4
</programlisting>
    Some other <acronym>SQL</acronym> databases cannot do this except
    by introducing a dummy one-row table from which to do the
    <command>SELECT</command>.
   </para>

   <para>
    Note that if a <literal>FROM</literal> clause is not specified,
    the query cannot reference any database tables. For example, the
    following query is invalid:
<programlisting>
SELECT distributors.* WHERE distributors.name = 'Westward';
</programlisting>
    <productname>PostgreSQL</productname> releases prior to
    8.1 would accept queries of this form, and add an implicit entry
    to the query's <literal>FROM</literal> clause for each table
    referenced by the query. This is no longer allowed.
   </para>
  </refsect2>

  <refsect2>
   <title>Omitting the <literal>AS</literal> Key Word</title>

   <para>
    In the SQL standard, the optional key word <literal>AS</> can be
    omitted before an output column name whenever the new column name
    is a valid column name (that is, not the same as any reserved
    keyword).  <productname>PostgreSQL</productname> is slightly more
    restrictive: <literal>AS</> is required if the new column name
    matches any keyword at all, reserved or not.  Recommended practice is
    to use <literal>AS</> or double-quote output column names, to prevent
    any possible conflict against future keyword additions.
   </para>

   <para>
    In <literal>FROM</literal> items, both the standard and
    <productname>PostgreSQL</productname> allow <literal>AS</> to
    be omitted before an alias that is an unreserved keyword.  But
    this is impractical for output column names, because of syntactic
    ambiguities.
   </para>
  </refsect2>

  <refsect2>
   <title><literal>ONLY</literal> and Parentheses</title>

   <para>
    The SQL standard requires parentheses around the table name
    after <literal>ONLY</literal>, as in <literal>SELECT * FROM ONLY
    (tab1), ONLY (tab2) WHERE ...</literal>.  PostgreSQL supports that
    as well, but the parentheses are optional.  (This point applies
    equally to all SQL commands supporting the <literal>ONLY</literal>
    option.)
   </para>
  </refsect2>

  <refsect2>
   <title>Namespace Available to <literal>GROUP BY</literal> and <literal>ORDER BY</literal></title>

   <para>
    In the SQL-92 standard, an <literal>ORDER BY</literal> clause can
    only use output column names or numbers, while a <literal>GROUP
    BY</literal> clause can only use expressions based on input column
    names.  <productname>PostgreSQL</productname> extends each of
    these clauses to allow the other choice as well (but it uses the
    standard's interpretation if there is ambiguity).
    <productname>PostgreSQL</productname> also allows both clauses to
    specify arbitrary expressions.  Note that names appearing in an
    expression will always be taken as input-column names, not as
    output-column names.
   </para>

   <para>
    SQL:1999 and later use a slightly different definition which is not
    entirely upward compatible with SQL-92.
    In most cases, however, <productname>PostgreSQL</productname>
    will interpret an <literal>ORDER BY</literal> or <literal>GROUP
    BY</literal> expression the same way SQL:1999 does.
   </para>
  </refsect2>

  <refsect2>
   <title>Functional Dependencies</title>

   <para>
    <productname>PostgreSQL</productname> recognizes functional dependency
    (allowing columns to be omitted from <literal>GROUP BY</>) only when
    a table's primary key is included in the <literal>GROUP BY</> list.
    The SQL standard specifies additional conditions that should be
    recognized.
   </para>
  </refsect2>

  <refsect2>
   <title><literal>WINDOW</literal> Clause Restrictions</title>

   <para>
    The SQL standard provides additional options for the window
    <replaceable class="parameter">frame_clause</>.
    <productname>PostgreSQL</productname> currently supports only the
    options listed above.
   </para>
  </refsect2>

  <refsect2>
   <title><literal>LIMIT</literal> and <literal>OFFSET</literal></title>

   <para>
    The clauses <literal>LIMIT</literal> and <literal>OFFSET</literal>
    are <productname>PostgreSQL</productname>-specific syntax, also
    used by <productname>MySQL</productname>.  The SQL:2008 standard
    has introduced the clauses <literal>OFFSET ... FETCH {FIRST|NEXT}
    ...</literal> for the same functionality, as shown above
    in <xref linkend="sql-limit" endterm="sql-limit-title">.  This
    syntax is also used by <productname>IBM DB2</productname>.
    (Applications written for <productname>Oracle</productname>
    frequently use a workaround involving the automatically
    generated <literal>rownum</literal> column, which is not available in
    PostgreSQL, to implement the effects of these clauses.)
   </para>
  </refsect2>

  <refsect2>
   <title><literal>FOR UPDATE</> and <literal>FOR SHARE</></title>

   <para>
    Although <literal>FOR UPDATE</> appears in the SQL standard, the
    standard allows it only as an option of <command>DECLARE CURSOR</>.
    <productname>PostgreSQL</productname> allows it in any <command>SELECT</>
    query as well as in sub-<command>SELECT</>s, but this is an extension.
    The <literal>FOR SHARE</> variant, and the <literal>NOWAIT</> option,
    do not appear in the standard.
   </para>
  </refsect2>

  <refsect2>
   <title>Nonstandard Clauses</title>

   <para>
    The clause <literal>DISTINCT ON</literal> is not defined in the
    SQL standard.
   </para>
  </refsect2>
 </refsect1>
</refentry>
@


1.131
log
@Clarify SELECT FOR UPDATE behavior in docs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.130 2010/04/03 07:23:02 petere Exp $
d523 6
a528 3
    ungrouped columns except within aggregate functions, since there
    would be more than one possible value to return for an ungrouped
    column.
d1597 12
@


1.130
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.129 2010/02/12 17:33:19 tgl Exp $
d1203 3
a1205 2
    will not be returned if they have since been updated to not satisfy
    the query conditions.  If a <literal>LIMIT</> is used, locking stops
@


1.129
log
@Extend the set of frame options supported for window functions.

This patch allows the frame to start from CURRENT ROW (in either RANGE or
ROWS mode), and it also adds support for ROWS n PRECEDING and ROWS n FOLLOWING
start and end points.  (RANGE value PRECEDING/FOLLOWING isn't there yet ---
the grammar works, but that's all.)

Hitoshi Harada, reviewed by Pavel Stehule
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.128 2009/10/28 14:55:37 tgl Exp $
d8 1
a8 1
  <refentrytitle id="sql-select-title">SELECT</refentrytitle>
d308 1
a308 1
        <xref linkend="sql-values" endterm="sql-values-title"> command
d1157 1
a1157 1
    <xref linkend="sql-lock" endterm="sql-lock-title">
@


1.128
log
@When FOR UPDATE/SHARE is used with LIMIT, put the LockRows plan node
underneath the Limit node, not atop it.  This fixes the old problem that such
a query might unexpectedly return fewer rows than the LIMIT says, due to
LockRows discarding updated rows.

There is a related problem that LockRows might destroy the sort ordering
produced by earlier steps; but fixing that by pushing LockRows below Sort
would create serious performance problems that are unjustified in many
real-world applications, as well as potential deadlock problems from locking
many more rows than expected.  Instead, keep the present semantics of applying
FOR UPDATE after ORDER BY within a single query level; but allow the user to
specify the other way by writing FOR UPDATE in a sub-select.  To make that
work, track whether FOR UPDATE appeared explicitly in sub-selects or got
pushed down from the parent, and don't flatten a sub-select that contained an
explicit FOR UPDATE.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.127 2009/10/27 17:11:18 tgl Exp $
d619 12
a630 1
    frame (not all do).  It can be one of
d632 5
a636 6
RANGE UNBOUNDED PRECEDING
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
ROWS UNBOUNDED PRECEDING
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
d638 41
a678 12
    The first two are equivalent and are also the default: they set the
    frame to be all rows from the partition start up through the current row's
    last peer in the <literal>ORDER BY</> ordering (which means all rows if
    there is no <literal>ORDER BY</>).  The options
    <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</> and
    <literal>ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</>
    are also equivalent: they always select all rows in the partition.
    Lastly, <literal>ROWS UNBOUNDED PRECEDING</> or its verbose equivalent
    <literal>ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW</> select
    all rows up through the current row (regardless of duplicates).
    Beware that this option can produce implementation-dependent results
    if the <literal>ORDER BY</> ordering does not order the rows uniquely.
@


1.127
log
@Make FOR UPDATE/SHARE in the primary query not propagate into WITH queries;
for example in
  WITH w AS (SELECT * FROM foo) SELECT * FROM w, bar ... FOR UPDATE
the FOR UPDATE will now affect bar but not foo.  This is more useful and
consistent than the original 8.4 behavior, which tried to propagate FOR UPDATE
into the WITH query but always failed due to assorted implementation
restrictions.  Even though we are in process of removing those restrictions,
it seems correct on philosophical grounds to not let the outer query's
FOR UPDATE affect the WITH query.

In passing, fix isLockedRel which frequently got things wrong in
nested-subquery cases: "FOR UPDATE OF foo" applies to an alias foo in the
current query level, not subqueries.  This has been broken for a long time,
but it doesn't seem worth back-patching further than 8.4 because the actual
consequences are minimal.  At worst the parser would sometimes get
RowShareLock on a relation when it should be AccessShareLock or vice versa.
That would only make a difference if someone were using ExclusiveLock
concurrently, which no standard operation does, and anyway FOR UPDATE
doesn't result in visible changes so it's not clear that the someone would
notice any problem.  Between that and the fact that FOR UPDATE barely works
with subqueries at all in existing releases, I'm not excited about worrying
about it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.126 2009/10/21 20:22:38 tgl Exp $
d1095 3
a1097 1
    row was deleted).  For further discussion see <xref
d1102 9
d1112 2
a1113 2
    use the <literal>NOWAIT</> option.  <command>SELECT FOR UPDATE
    NOWAIT</command> reports an error, rather than waiting, if a selected row
d1117 1
a1117 1
    <xref linkend="mvcc">).  You can use the <literal>NOWAIT</> option of
d1119 1
a1123 9
    <literal>FOR SHARE</literal> behaves similarly, except that it
    acquires a shared rather than exclusive lock on each retrieved
    row.  A shared lock blocks other transactions from performing
    <command>UPDATE</command>, <command>DELETE</command>, or <command>SELECT
    FOR UPDATE</command> on these rows, but it does not prevent them
    from performing <command>SELECT FOR SHARE</command>.
   </para>

   <para>
d1129 1
a1129 1
    clause without a table list affects all tables used in the command.
d1157 30
d1213 20
a1232 24
    It is possible for a <command>SELECT</> command using both
    <literal>LIMIT</literal> and <literal>FOR UPDATE/SHARE</literal>
    clauses to return fewer rows than specified by <literal>LIMIT</literal>.
    This is because <literal>LIMIT</> is applied first.  The command
    selects the specified number of rows,
    but might then block trying to obtain a lock on one or more of them.
    Once the <literal>SELECT</> unblocks, the row might have been deleted
    or updated so that it does not meet the query <literal>WHERE</> condition
    anymore, in which case it will not be returned.
   </para>
  </caution>

  <caution>
   <para>
    Similarly, it is possible for a <command>SELECT</> command
    using <literal>ORDER BY</literal> and <literal>FOR
    UPDATE/SHARE</literal> to return rows out of order.  This is
    because <literal>ORDER BY</> is applied first.  The command
    orders the result, but might then block trying to obtain a lock
    on one or more of the rows.  Once the <literal>SELECT</>
    unblocks, one of the ordered columns might have been modified
    and be returned out of order.  A workaround is to perform
    <command>SELECT ... FOR UPDATE/SHARE</> and then <command>SELECT
    ... ORDER BY</>.
d1573 1
a1573 1
    in <xref linkend="sql-limit" endterm="sql-limit-title">, and this
d1577 1
a1577 1
    generated <literal>rownum</literal> column, not available in
d1583 13
@


1.126
log
@Remove add_missing_from GUC and associated parser support for "implicit RTEs".
Per recent discussion, add_missing_from has been deprecated for long enough to
consider removing, and it's getting in the way of planned parser refactoring.
The system now always behaves as though add_missing_from were OFF.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.125 2009/09/18 05:00:42 petere Exp $
d1130 5
@


1.125
log
@Easier to translate psql help

Instead of requiring translators to translate the entire SQL command
synopses, change create_help.pl to only require them to translate the
placeholders, and paste those into the synopsis using a printf mechanism.
Make some small updates to the markup to make it easier to parse.

Note: This causes msgmerge of gettext 0.17 to segfault.  You will need
the patch from https://savannah.gnu.org/bugs/?27474 to make it work.
msgmerge usually only runs on babel.postgresql.org, however.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.124 2009/08/27 20:08:02 tgl Exp $
d1454 1
a1454 6
    referenced by the query. This is no longer the default behavior,
    because it does not comply with the SQL standard, and is
    considered by many to be error-prone. For compatibility with
    applications that rely on this behavior the <xref
    linkend="guc-add-missing-from"> configuration variable can be
    enabled.
@


1.124
log
@Modify the definition of window-function PARTITION BY and ORDER BY clauses
so that their elements are always taken as simple expressions over the
query's input columns.  It originally seemed like a good idea to make them
act exactly like GROUP BY and ORDER BY, right down to the SQL92-era behavior
of accepting output column names or numbers.  However, that was not such a
great idea, for two reasons:

1. It permits circular references, as exhibited in bug #5018: the output
column could be the one containing the window function itself.  (We actually
had a regression test case illustrating this, but nobody thought twice about
how confusing that would be.)

2. It doesn't seem like a good idea for, eg, "lead(foo) OVER (ORDER BY foo)"
to potentially use two completely different meanings for "foo".

Accordingly, narrow down the behavior of window clauses to use only the
SQL99-compliant interpretation that the expressions are simple expressions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.123 2009/08/18 23:40:20 tgl Exp $
d50 1
a50 1
where <replaceable class="parameter">from_item</replaceable> can be one of:
d59 1
a59 1
and <replaceable class="parameter">with_query</replaceable> is:
@


1.123
log
@Allow mixing of traditional and SQL:2008 LIMIT/OFFSET syntax.  Being rigid
about it doesn't simplify the grammar at all, and it does invite confusion
among those who only read the SELECT syntax summary and not the full details.
Per gripe from Jaime Casanova.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.122 2009/05/03 20:45:43 tgl Exp $
d598 5
a602 6
    the same fashion as elements of a
    <xref linkend="sql-groupby" endterm="sql-groupby-title">, and
    the elements of the <literal>ORDER BY</> list are interpreted in the
    same fashion as elements of an
    <xref linkend="sql-orderby" endterm="sql-orderby-title">.
    The only difference is that these expressions can contain aggregate
d609 8
@


1.122
log
@Fix unintelligible description created by removing only part of
a parenthetical remark.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.121 2009/04/15 22:42:50 momjian Exp $
d1008 1
a1008 1
    which PostgreSQL also supports.  It is:
d1013 4
a1016 3
    Both clauses are optional, but if present
    the <literal>OFFSET</literal> clause must come before
    the <literal>FETCH</literal> clause.  <literal>ROW</literal>
@


1.122.2.1
log
@Modify the definition of window-function PARTITION BY and ORDER BY clauses
so that their elements are always taken as simple expressions over the
query's input columns.  It originally seemed like a good idea to make them
act exactly like GROUP BY and ORDER BY, right down to the SQL92-era behavior
of accepting output column names or numbers.  However, that was not such a
great idea, for two reasons:

1. It permits circular references, as exhibited in bug #5018: the output
column could be the one containing the window function itself.  (We actually
had a regression test case illustrating this, but nobody thought twice about
how confusing that would be.)

2. It doesn't seem like a good idea for, eg, "lead(foo) OVER (ORDER BY foo)"
to potentially use two completely different meanings for "foo".

Accordingly, narrow down the behavior of window clauses to use only the
SQL99-compliant interpretation that the expressions are simple expressions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.122 2009/05/03 20:45:43 tgl Exp $
d598 6
a603 5
    much the same fashion as elements of a
    <xref linkend="sql-groupby" endterm="sql-groupby-title">, except that
    they are always simple expressions and never the name or number of an
    output column.
    Another difference is that these expressions can contain aggregate
a609 8
    Similarly, the elements of the <literal>ORDER BY</> list are interpreted
    in much the same fashion as elements of an
    <xref linkend="sql-orderby" endterm="sql-orderby-title">, except that
    the expressions are always taken as simple expressions and never the name
    or number of an output column.
   </para>

   <para>
@


1.122.2.2
log
@Make FOR UPDATE/SHARE in the primary query not propagate into WITH queries;
for example in
  WITH w AS (SELECT * FROM foo) SELECT * FROM w, bar ... FOR UPDATE
the FOR UPDATE will now affect bar but not foo.  This is more useful and
consistent than the original 8.4 behavior, which tried to propagate FOR UPDATE
into the WITH query but always failed due to assorted implementation
restrictions.  Even though we are in process of removing those restrictions,
it seems correct on philosophical grounds to not let the outer query's
FOR UPDATE affect the WITH query.

In passing, fix isLockedRel which frequently got things wrong in
nested-subquery cases: "FOR UPDATE OF foo" applies to an alias foo in the
current query level, not subqueries.  This has been broken for a long time,
but it doesn't seem worth back-patching further than 8.4 because the actual
consequences are minimal.  At worst the parser would sometimes get
RowShareLock on a relation when it should be AccessShareLock or vice versa.
That would only make a difference if someone were using ExclusiveLock
concurrently, which no standard operation does, and anyway FOR UPDATE
doesn't result in visible changes so it's not clear that the someone would
notice any problem.  Between that and the fact that FOR UPDATE barely works
with subqueries at all in existing releases, I'm not excited about worrying
about it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.122.2.1 2009/08/27 20:08:12 tgl Exp $
a1128 5
    However, <literal>FOR UPDATE</literal>/<literal>FOR SHARE</literal>
    do not apply to <literal>WITH</> queries referenced by the primary query.
    If you want row locking to occur within a <literal>WITH</> query, specify
    <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal> within the
    <literal>WITH</> query.
@


1.121
log
@Remove mention of pre-7.1 inheritance behavior from /ref pages;  keep
mentions in main documentation.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.120 2009/02/02 20:42:57 tgl Exp $
d274 1
a274 3
        any descendant tables are scanned.  The default
        behavior can be changed using the <xref
        linkend="guc-sql-inheritance"> configuration option.
@


1.120
log
@Document the longstanding behavior of LIMIT NULL and OFFSET NULL,
per gripe from David Wheeler that this was mentioned nowhere.
In passing, editorialize a bit on the description of the SQL:2008
equivalent syntax.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.119 2009/01/23 14:05:28 momjian Exp $
d274 2
a275 6
        all its descendant tables (if any) are scanned.  <literal>*</>
        can be appended to the table name to indicate that descendant
        tables are to be scanned, but in the current version, this is
        the default behavior.  (In releases before 7.1,
        <literal>ONLY</> was the default behavior.)  The default
        behavior can be modified by changing the <xref
@


1.119
log
@Document that SELECT ... ORDER BY .. FOR UPDATE/SHARE might return
results out of order because of locking, per bug report 4593
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.118 2009/01/22 20:15:59 tgl Exp $
d1006 7
d1024 5
a1028 4
    the effects of these clauses.  When using expressions other than
    constants for the offset or fetch count, parentheses will be
    necessary in most cases.  If the fetch count is omitted, it
    defaults to 1.
@


1.118
log
@Support column-level privileges, as required by SQL standard.

Stephen Frost, with help from KaiGai Kohei and others
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.117 2009/01/12 14:06:20 petere Exp $
d1166 1
a1166 1
    <literal>LIMIT</literal> and  <literal>FOR UPDATE/SHARE</literal>
d1170 1
a1170 1
    but might then block trying to obtain lock on one or more of them.
d1176 15
@


1.117
log
@Add some minimal documentation that the SQL standard requires parentheses
after ONLY.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.116 2008/12/31 23:42:56 tgl Exp $
d189 5
a193 4
   You must have <literal>SELECT</literal> privilege on a table to
   read its values.  The use of <literal>FOR UPDATE</literal> or
   <literal>FOR SHARE</literal> requires
   <literal>UPDATE</literal> privilege as well.
@


1.116
log
@Throw error if a <window definition> references a window that already has a
frame clause, as appears to be required by the fine print in the SQL spec.
Per discussion with Pavel, not doing so risks user confusion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.115 2008/12/31 00:08:35 tgl Exp $
d1461 13
@


1.115
log
@Add some basic support for window frame clauses to the window-functions
patch.  This includes the ability to force the frame to cover the whole
partition, and the ability to make the frame end exactly on the current row
rather than its last ORDER BY peer.  Supporting any more of the full SQL
frame-clause syntax will require nontrivial hacking on the window aggregate
code, so it'll have to wait for 8.5 or beyond.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.114 2008/12/29 18:23:53 tgl Exp $
d586 1
a586 1
[ <replaceable class="parameter">framing_clause</replaceable> ]
d597 2
a598 1
    The framing clause is never copied from the existing window.
d615 1
a615 1
    The optional <replaceable class="parameter">framing_clause</> defines
d1490 1
a1490 1
    <replaceable class="parameter">framing_clause</>.
@


1.114
log
@Fix thinko in documentation of default window frame behavior,
per Hitoshi Harada.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.113 2008/12/28 18:53:54 tgl Exp $
d586 1
d588 13
d614 23
a636 6
    If an <replaceable class="parameter">existing_window_name</replaceable>
    is specified it must refer to an earlier entry in the <literal>WINDOW</>
    list; the new window copies its partitioning clause from that entry,
    as well as its ordering clause if any.  In this case the new window cannot
    specify its own <literal>PARTITION BY</> clause, and it can specify
    <literal>ORDER BY</> only if the copied window does not have one.
d657 3
a659 2
    <xref linkend="tutorial-window"> and
    <xref linkend="syntax-window-functions">.
d1488 4
a1491 6
    The SQL standard provides for an optional <quote>framing clause</>,
    introduced by the key word <literal>RANGE</> or <literal>ROWS</>,
    in window definitions.  <productname>PostgreSQL</productname> does
    not yet implement framing clauses, and always follows the
    default framing behavior, which is equivalent to the framing clause
    <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW</>.
@


1.113
log
@Support window functions a la SQL:2008.

Hitoshi Harada, with some kibitzing from Heikki and Tom.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.112 2008/12/01 09:38:08 petere Exp $
d1461 1
a1461 1
    <literal>ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW</>.
@


1.112
log
@Add braces to clarify syntax synopsis
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.111 2008/11/21 11:47:55 petere Exp $
d42 1
d570 61
d987 1
a987 1
   </para>    
d1453 13
@


1.111
log
@Use relation_expr for TABLE command, requested by Tom.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.110 2008/11/20 14:04:45 petere Exp $
d62 1
a62 1
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] | <replaceable class="parameter">with_query_name</replaceable>
@


1.110
log
@TABLE command
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.109 2008/11/19 12:21:57 petere Exp $
d62 1
a62 1
TABLE <replaceable class="parameter">table_name</replaceable> | <replaceable class="parameter">with_query_name</replaceable>
@


1.109
log
@Add WITH as a refname to the SELECT reference page.

Now "\help WITH" works and there will be a separate WITH(7) man page.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.108 2008/11/14 10:22:47 petere Exp $
d15 1
d25 4
d61 2
d1081 17
@


1.108
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.107 2008/10/22 11:00:33 petere Exp $
d15 1
d23 5
@


1.107
log
@SQL:2008 alternative syntax for LIMIT/OFFSET:
OFFSET num {ROW|ROWS} FETCH {FIRST|NEXT} [num] {ROW|ROWS} ONLY
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.106 2008/10/07 19:27:04 tgl Exp $
d9 1
@


1.106
log
@Extend CTE patch to support recursive UNION (ie, without ALL).  The
implementation uses an in-memory hash table, so it will poop out for very
large recursive results ... but the performance characteristics of a
sort-based implementation would be pretty unpleasant too.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.105 2008/10/04 21:56:52 tgl Exp $
d33 2
a34 1
    [ OFFSET <replaceable class="parameter">start</replaceable> ]
d154 1
a154 1
      If the <literal>LIMIT</literal> or <literal>OFFSET</literal>
d896 18
d1360 18
d1381 2
a1382 3
    The clauses <literal>DISTINCT ON</literal>,
    <literal>LIMIT</literal>, and <literal>OFFSET</literal> are not
    defined in the SQL standard.
@


1.105
log
@Implement SQL-standard WITH clauses, including WITH RECURSIVE.

There are some unimplemented aspects: recursive queries must use UNION ALL
(should allow UNION too), and we don't have SEARCH or CYCLE clauses.
These might or might not get done for 8.4, but even without them it's a
pretty useful feature.

There are also a couple of small loose ends and definitional quibbles,
which I'll send a memo about to pgsql-hackers shortly.  But let's land
the patch now so we can get on with other development.

Yoshiyuki Asaba, with lots of help from Tatsuo Ishii and Tom Lane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.104 2008/09/23 09:20:35 heikki Exp $
d205 1
a205 1
<replaceable class="parameter">non_recursive_term</replaceable> UNION ALL <replaceable class="parameter">recursive_term</replaceable>
d208 1
a208 1
    side of <literal>UNION ALL</>.  Only one recursive self-reference
d1237 1
a1237 1
   an initial condition, followed by <literal>UNION ALL</literal>,
@


1.104
log
@Make LC_COLLATE and LC_CTYPE database-level settings. Collation and
ctype are now more like encoding, stored in new datcollate and datctype
columns in pg_database.

This is a stripped-down version of Radek Strnad's patch, with further
changes by me.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.103 2008/02/15 22:17:06 tgl Exp $
d23 1
d40 1
d44 4
d62 11
d183 50
d267 1
a267 1
     
d285 1
a285 1
     
d304 15
d341 1
a341 1
     
d424 1
a424 1
     
d437 1
a437 1
     
d465 1
a465 1
   
d482 1
a482 1
  
d529 1
a529 1
    
d541 1
a541 1
    
d603 1
a603 1
  
d622 1
a622 1
    
d633 1
a633 1
    
d641 1
a641 1
    
d647 1
a647 1
    
d675 1
a675 1
    
d683 1
a683 1
    
d693 1
a693 1
    
d720 1
a720 1
    
d728 1
a728 1
    
d735 1
a735 1
    
d774 1
a774 1
    
d797 1
a797 1
    
d874 1
a874 1
  
d1191 52
d1244 1
a1244 1
 
d1253 1
a1253 1
  
d1333 1
a1333 1
    entirely upward compatible with SQL-92.  
@


1.103
log
@Allow AS to be omitted when specifying an output column name in SELECT
(or RETURNING), but only when the output name is not any SQL keyword.
This seems as close as we can get to the standard's syntax without a
great deal of thrashing.  Original patch by Hiroshi Saito, amended by me.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.102 2007/11/28 15:42:31 petere Exp $
d750 1
a750 2
    collation order that was established when the database cluster
    was initialized.
@


1.102
log
@spell checker run
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.101 2007/06/08 20:26:18 tgl Exp $
d24 1
a24 1
    * | <replaceable class="parameter">expression</replaceable> [ AS <replaceable class="parameter">output_name</replaceable> ] [, ...]
d480 29
a508 9
    computed in the <literal>FROM</> clause.  Using the clause
    <literal>AS <replaceable
    class="parameter">output_name</replaceable></literal>, another
    name can be specified for an output column.  This name is
    primarily used to label the column for display.  It can also be
    used to refer to the column's value in <literal>ORDER BY</> and
    <literal>GROUP BY</> clauses, but not in the <literal>WHERE</> or
    <literal>HAVING</> clauses; there you must write out the
    expression instead.
d514 1
a514 1
    rows.  Also, one can write <literal><replaceable
d516 3
a518 1
    shorthand for the columns coming from just that table.
d686 1
a686 1
    of the result column. This feature makes it possible to define an
d689 1
a689 1
    possible to assign a name to a result column using the
d696 1
a696 1
    appear in the <command>SELECT</command> result list.  Thus the
d709 2
a710 2
    matches both a result column name and an input column name,
    <literal>ORDER BY</> will interpret it as the result column name.
d1160 12
a1171 1
   <title>The <literal>AS</literal> Key Word</title>
d1174 5
a1178 7
    In the SQL standard, the optional key word <literal>AS</> is just
    noise and can be omitted without affecting the meaning.  The
    <productname>PostgreSQL</productname> parser requires this key
    word when renaming output columns because the type extensibility
    features lead to parsing ambiguities without it.
    <literal>AS</literal> is optional in <literal>FROM</literal>
    items, however.
d1187 1
a1187 1
    only use result column names or numbers, while a <literal>GROUP
d1195 1
a1195 1
    result-column names.
@


1.102.2.1
log
@Document that SELECT FOR UPDATE/SHARE with ORDER BY might return results
in the incorrect order, per bug 4593.  Backpatch to 8.3.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.102 2007/11/28 15:42:31 petere Exp $
a943 16

  <caution>
   <para>
    Similarly, it is possible for a <command>SELECT</> command
    using <literal>ORDER BY</literal> and <literal>FOR
    UPDATE/SHARE</literal> to return rows out of order.  This is
    because <literal>ORDER BY</> is applied first.  The command
    orders the result, but might then block trying to obtain a lock
    on one or more of the rows.  Once the <literal>SELECT</>
    unblocks, one of the ordered columns might have been modified
    and be returned out of order.  A workaround is to perform
    <command>SELECT ... FOR UPDATE/SHARE</> and then <command>SELECT
    ... ORDER BY</>.
   </para>
  </caution>

@


1.101
log
@Add note that LIMIT without ORDER BY can produce outright nondeterministic
results.  Necessary due to introduction of syncscan patch.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.100 2007/05/15 19:13:55 neilc Exp $
d701 1
a701 1
    member of some btree operator family.
@


1.100
log
@Various fixes for the SGML docs. Consistently use spaces before/after
parentheses in syntax descriptions. Consistently use the present tense
when describing the basic purpose of each "DROP" command. Add a few
more hyperlinks.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.99 2007/02/01 19:10:25 momjian Exp $
d813 8
@


1.99
log
@Wording cleanup for error messages.  Also change can't -> cannot.

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.98 2007/02/01 00:28:19 momjian Exp $
d357 1
a357 1
      <term><literal>USING (<replaceable class="parameter">join_column</replaceable> [, ...])</literal></term>
@


1.98
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.97 2007/01/31 23:26:04 momjian Exp $
d895 2
a896 2
    used in contexts where returned rows can't be clearly identified with
    individual table rows; for example they can't be used with aggregation.
@


1.97
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.96 2007/01/09 16:59:20 tgl Exp $
d752 1
a752 1
    example,
d903 1
a903 1
    rollback would cause the lock to be lost.  For example,
@


1.96
log
@Marginal tweaks in the documentation for ORDER BY; in particular point
out the common error that ORDER BY x, y DESC does not mean the same as
ORDER BY x DESC, y DESC.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.95 2007/01/09 02:14:10 tgl Exp $
d245 1
a245 1
        alias may also be used. If an alias is written, a column alias
d290 1
a290 1
        none of these clauses may appear.
d545 1
a545 1
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> may not be
d591 1
a591 1
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> may not be
d633 1
a633 1
    Currently, <literal>FOR UPDATE</> and <literal>FOR SHARE</> may not be
d681 1
a681 1
    <literal>INTERSECT</>, or <literal>EXCEPT</> clause may only
d695 1
a695 1
    Optionally one may add the key word <literal>ASC</> (ascending) or
d699 1
a699 1
    name may be specified in the <literal>USING</> clause.
d795 1
a795 1
    the query's rows &mdash; you may be asking for the tenth through
d1147 1
a1147 1
    In the SQL-92 standard, an <literal>ORDER BY</literal> clause may
d1149 1
a1149 1
    BY</literal> clause may only use expressions based on input column
@


1.95
log
@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.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.94 2006/12/01 20:49:53 tgl Exp $
a646 7
    <replaceable class="parameter">expression</replaceable> can be the
    name or ordinal number of an output column
    (<command>SELECT</command> list item), or it can be an arbitrary
    expression formed from input-column values.
   </para>

   <para>
d656 7
d721 6
@


1.94
log
@Document the recently-understood hazard that a rollback can release row-level
locks that logically should not be released, because when a subtransaction
overwrites XMAX all knowledge of the previous lock state is lost.  It seems
unlikely that we will be able to fix this before 8.3...
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.93 2006/09/18 19:54:01 tgl Exp $
d30 1
a30 1
    [ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...] ]
d645 1
a645 1
ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...]
d655 2
a656 2
    be sorted according to the specified expressions.  If two rows are
    equal according to the leftmost expression, the are compared
d700 2
d710 8
a717 3
    The null value sorts higher than any other value. In other words,
    with ascending sort order, null values sort at the end, and with
    descending sort order, null values sort at the beginning.
@


1.93
log
@Documentation for VALUES lists.  Joe Conway and Tom Lane
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.92 2006/09/16 00:30:20 momjian Exp $
d886 25
d922 1
@


1.92
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.91 2006/04/30 18:30:38 tgl Exp $
d229 3
a231 1
        provided for it.
@


1.91
log
@Improve the representation of FOR UPDATE/FOR SHARE so that we can
support both FOR UPDATE and FOR SHARE in one command, as well as both
NOWAIT and normal WAIT behavior.  The more general code is actually
simpler and cleaner.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.90 2005/11/01 21:09:51 tgl Exp $
a1137 17

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
@


1.90
log
@Make an editorial pass over the reference pages.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.89 2005/08/01 20:31:04 tgl Exp $
d33 1
a33 1
    [ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT ] ]
d145 2
a146 2
      If the <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>
      clause is specified, the
a855 7
    It is currently not allowed for a single <command>SELECT</command>
    statement to include both <literal>FOR UPDATE</literal> and
    <literal>FOR SHARE</literal>, nor can different parts of the statement use
    both <literal>NOWAIT</> and normal waiting mode.
   </para>

   <para>
d860 16
a875 1
    usual.
@


1.90.2.1
log
@Document the recently-understood hazard that a rollback can release row-level
locks that logically should not be released, because when a subtransaction
overwrites XMAX all knowledge of the previous lock state is lost.  It seems
unlikely that we will be able to fix this before 8.3...
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.90 2005/11/01 21:09:51 tgl Exp $
a875 25
  <caution>
   <para>
    Avoid locking a row and then modifying it within a later savepoint or
    <application>PL/pgSQL</application> exception block.  A subsequent
    rollback would cause the lock to be lost.  For example,
<programlisting>
BEGIN;
SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
SAVEPOINT s;
UPDATE mytable SET ... WHERE key = 1;
ROLLBACK TO s;
</programlisting>
    After the <command>ROLLBACK</>, the row is effectively unlocked, rather
    than returned to its pre-savepoint state of being locked but not modified.
    This hazard occurs if a row locked in the current transaction is updated
    or deleted, or if a shared lock is upgraded to exclusive: in all these
    cases, the former lock state is forgotten.  If the transaction is then
    rolled back to a state between the original locking command and the
    subsequent change, the row will appear not to be locked at all.  This is
    an implementation deficiency which will be addressed in a future release
    of <productname>PostgreSQL</productname>.
   </para>
  </caution>

  <caution>
a886 1
  </caution>
@


1.89
log
@Add NOWAIT option to SELECT FOR UPDATE/SHARE.
Original patch by Hans-Juergen Schoenig, revisions by Karel Zak
and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.88 2005/07/14 06:17:36 neilc Exp $
d1098 1
a1098 1
    In the SQL:2003 standard, an <literal>ORDER BY</literal> clause may
d1111 2
a1112 2
    SQL:2003 uses a slightly different definition which is not entirely upward
    compatible with SQL-92.  
d1115 1
a1115 1
    BY</literal> expression the same way SQL:2003 does.
@


1.88
log
@This doc patch replaces all inappropriate references to SQL:1999 when it
is used as if it were the latest (and/or still valid) SQL standard.
SQL:2003 is used in its place. Patch from Simon Riggs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.87 2005/05/08 03:08:05 momjian Exp $
d33 1
a33 1
    [ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] ]
d154 1
a154 1
   
d509 1
a509 1
    <literal>FOR SHARE</literal> clause. 
d806 1
a806 1
FOR UPDATE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ]
d813 1
a813 1
FOR SHARE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ]
d835 12
d858 2
a859 1
    <literal>FOR SHARE</literal>.
d877 2
a878 2
    It is possible for a <command>SELECT</> command using both 
    <literal>LIMIT</literal> and  <literal>FOR UPDATE/SHARE</literal> 
@


1.87
log
@Documentation adjustments.

Vladimir Chukharev
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.86 2005/04/28 21:47:10 tgl Exp $
d1085 1
a1085 1
    In the SQL-92 standard, an <literal>ORDER BY</literal> clause may
d1098 3
a1100 3
    SQL:1999 uses a slightly different definition which is not entirely upward
    compatible 
    with SQL-92.  In most cases, however, <productname>PostgreSQL</productname>
d1102 1
a1102 1
    BY</literal> expression the same way SQL:1999 does.
@


1.86
log
@Implement sharable row-level locks, and use them for foreign key references
to eliminate unnecessary deadlocks.  This commit adds SELECT ... FOR SHARE
paralleling SELECT ... FOR UPDATE.  The implementation uses a new SLRU
data structure (managed much like pg_subtrans) to represent multiple-
transaction-ID sets.  When more than one transaction is holding a shared
lock on a particular row, we create a MultiXactId representing that set
of transactions and store its ID in the row's XMAX.  This scheme allows
an effectively unlimited number of row locks, just as we did before,
while not costing any extra overhead except when a shared lock actually
has to be shared.   Still TODO: use the regular lock manager to control
the grant order when multiple backends are waiting for a row lock.

Alvaro Herrera and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.85 2005/04/22 15:32:58 momjian Exp $
d50 1
a50 1
   <command>SELECT</command> retrieves rows from one or more tables.
@


1.85
log
@Typo fix.  Alvaro.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.84 2005/04/22 04:20:44 momjian Exp $
d33 1
a33 1
    [ FOR UPDATE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] ]
d145 5
a149 4
      The <literal>FOR UPDATE</literal> clause causes the
      <command>SELECT</command> statement to lock the selected rows
      against concurrent updates.  (See <xref linkend="sql-for-update"
      endterm="sql-for-update-title"> below.)
d157 2
a158 1
   read its values.  The use of <literal>FOR UPDATE</literal> requires
d508 2
a509 1
    BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
d543 3
a545 2
    Currently, <literal>FOR UPDATE</> may not be specified either for
    a <literal>UNION</> result or for any input of a <literal>UNION</>.
d559 2
a560 1
    BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
d589 3
a591 2
    Currently, <literal>FOR UPDATE</> may not be specified either for
    an <literal>INTERSECT</> result or for any input of an <literal>INTERSECT</>.
d605 2
a606 1
    BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
d631 3
a633 2
    Currently, <literal>FOR UPDATE</> may not be specified either for
    an <literal>EXCEPT</> result or for any input of an <literal>EXCEPT</>.
d800 2
a801 2
  <refsect2 id="SQL-FOR-UPDATE">
   <title id="sql-for-update-title"><literal>FOR UPDATE</literal> Clause</title>
d811 7
d835 17
a851 1
    If specific tables are named in <literal>FOR UPDATE</literal>,
d858 3
a860 3
    <literal>FOR UPDATE</literal> cannot be used in contexts where
    returned rows can't be clearly identified with individual table
    rows; for example it can't be used with aggregation.
d865 1
a865 1
    <literal>LIMIT</literal> and  <literal>FOR UPDATE</literal> 
d867 6
a872 4
    This is because <literal>LIMIT</> selects a number of rows,
    but might then block requesting a <literal>FOR UPDATE</literal> lock.
    Once the <literal>SELECT</> unblocks, the query qualification might not
    be met and the row not be returned by <literal>SELECT</>.
@


1.84
log
@Remove pre-7.3 mention that FOR UPDATE can be before LIMIT.

Document that FOR UPDATE and LIMIT together can return fewer rows that
LIMIT specifies, and why.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.83 2005/04/08 00:59:58 neilc Exp $
d838 1
a838 1
    Once the <literal>SELECT</> unblocks, the query qualifiation might not
@


1.83
log
@Change the default setting of "add_missing_from" to false. This has been
the long-term plan for this behavior for quite some time, but it is only
possible now that DELETE has a USING clause so that the user can join
other tables in a DELETE statement without relying on this behavior.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.82 2005/03/10 23:21:20 tgl Exp $
d833 7
a839 5
    <literal>FOR UPDATE</literal> may appear before
    <literal>LIMIT</literal> for compatibility with
    <productname>PostgreSQL</productname> versions before 7.3.  It
    effectively executes after <literal>LIMIT</literal>, however, and
    so that is the recommended place to write it.
@


1.82
log
@Make the behavior of HAVING without GROUP BY conform to the SQL spec.
Formerly, if such a clause contained no aggregate functions we mistakenly
treated it as equivalent to WHERE.  Per spec it must cause the query to
be treated as a grouped query of a single group, the same as appearance
of aggregate functions would do.  Also, the HAVING filter must execute
after aggregate function computation even if it itself contains no
aggregate functions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.81 2005/01/22 23:22:19 momjian Exp $
d1014 3
a1016 2
    A less obvious use is to abbreviate a normal
    <command>SELECT</command> from tables:
a1018 24

 did |   name
-----+----------
 108 | Westward
</programlisting>
    This works because an implicit <literal>FROM</literal> item is
    added for each table that is referenced in other parts of the
    <command>SELECT</command> statement but not mentioned in
    <literal>FROM</literal>.
   </para>

   <para>
    While this is a convenient shorthand, it's easy to misuse.  For
    example, the command
<programlisting>
SELECT distributors.* FROM distributors d;
</programlisting>
    is probably a mistake; most likely the user meant
<programlisting>
SELECT d.* FROM distributors d;
</programlisting>
    rather than the unconstrained join
<programlisting>
SELECT distributors.* FROM distributors d, distributors distributors;
d1020 9
a1028 7
    that he will actually get.  To help detect this sort of mistake,
    <productname>PostgreSQL</productname> will warn if the
    implicit-<literal>FROM</literal> feature is used in a
    <command>SELECT</command> statement that also contains an explicit
    <literal>FROM</literal> clause.  Also, it is possible to disable
    the implicit-<literal>FROM</literal> feature by setting the
    <xref linkend="guc-add-missing-from"> parameter to false.
@


1.81
log
@More < and > changes to ampersands.

8.0.X and HEAD.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.80 2005/01/04 08:59:45 tgl Exp $
d455 11
@


1.80
log
@Fix subsection ordering (DISTINCT should be described before LIMIT).
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.79 2005/01/04 03:58:16 tgl Exp $
d877 1
a877 1
    HAVING sum(len) < interval '5 hours';
@


1.80.4.1
log
@More < and > changes to ampersands.

8.0.X and HEAD.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.80 2005/01/04 08:59:45 tgl Exp $
d877 1
a877 1
    HAVING sum(len) &lt; interval '5 hours';
@


1.80.4.2
log
@Backpatch of LIMIT / FOR UPDATE behavior, but keep pre-7.3 mention in 8.0.X.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.80.4.1 2005/01/22 23:23:53 momjian Exp $
a821 10
    It is possible for a <command>SELECT</> command using both 
    <literal>LIMIT</literal> and  <literal>FOR UPDATE</literal> 
    clauses to return fewer rows than specified by <literal>LIMIT</literal>.
    This is because <literal>LIMIT</> selects a number of rows,
    but might then block requesting a <literal>FOR UPDATE</literal> lock.
    Once the <literal>SELECT</> unblocks, the query qualification might not
    be met and the row not be returned by <literal>SELECT</>.
   </para>

   <para>
@


1.80.4.3
log
@Document the recently-understood hazard that a rollback can release row-level
locks that logically should not be released, because when a subtransaction
overwrites XMAX all knowledge of the previous lock state is lost.  It seems
unlikely that we will be able to fix this before 8.3...
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.80.4.2 2005/04/22 15:53:27 momjian Exp $
a821 32
    <literal>FOR UPDATE</literal> may appear before
    <literal>LIMIT</literal> for compatibility with
    <productname>PostgreSQL</productname> versions before 7.3.  It
    effectively executes after <literal>LIMIT</literal>, however, and
    so that is the recommended place to write it.
   </para>

  <caution>
   <para>
    Avoid locking a row and then modifying it within a later savepoint or
    <application>PL/pgSQL</application> exception block.  A subsequent
    rollback would cause the lock to be lost.  For example,
<programlisting>
BEGIN;
SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
SAVEPOINT s;
UPDATE mytable SET ... WHERE key = 1;
ROLLBACK TO s;
</programlisting>
    After the <command>ROLLBACK</>, the row is effectively unlocked, rather
    than returned to its pre-savepoint state of being locked but not modified.
    This hazard occurs if a row locked in the current transaction is updated
    or deleted: the former lock state is forgotten.  If the transaction is then
    rolled back to a state between the original locking command and the
    subsequent change, the row will appear not to be locked at all.  This is
    an implementation deficiency which will be addressed in a future release
    of <productname>PostgreSQL</productname>.
   </para>
  </caution>

  <caution>
   <para>
d830 8
a837 1
  </caution>
@


1.79
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.78 2004/11/27 21:27:07 petere Exp $
d698 39
a780 39
  <refsect2 id="sql-distinct">
   <title id="sql-distinct-title"><literal>DISTINCT</literal> Clause</title>

   <para>
    If <literal>DISTINCT</> is specified, all duplicate rows are
    removed from the result set (one row is kept from each group of
    duplicates).  <literal>ALL</> specifies the opposite: all rows are
    kept; that is the default.
   </para>

   <para>
    <literal>DISTINCT ON ( <replaceable
    class="parameter">expression</replaceable> [, ...] )</literal>
    keeps only the first row of each set of rows where the given
    expressions evaluate to equal.  The <literal>DISTINCT ON</literal>
    expressions are interpreted using the same rules as for
    <literal>ORDER BY</> (see above).  Note that the <quote>first
    row</quote> of each set is unpredictable unless <literal>ORDER
    BY</> is used to ensure that the desired row appears first.  For
    example,
<programlisting>
SELECT DISTINCT ON (location) location, time, report
    FROM weather_reports
    ORDER BY location, time DESC;
</programlisting>
    retrieves the most recent weather report for each location.  But
    if we had not used <literal>ORDER BY</> to force descending order
    of time values for each location, we'd have gotten a report from
    an unpredictable time for each location.
   </para>

   <para>
    The <literal>DISTINCT ON</> expression(s) must match the leftmost
    <literal>ORDER BY</> expression(s).  The <literal>ORDER BY</> clause
    will normally contain additional expression(s) that determine the
    desired precedence of rows within each <literal>DISTINCT ON</> group.
   </para>
  </refsect2>

@


1.78
log
@Update of conformance information to SQL:2003
by Troels Arvin, Simon Riggs, Elein Mustain

Make spelling of SQL standard names uniform.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.77 2004/05/16 23:22:08 neilc Exp $
d86 10
a114 10
      The actual output rows are computed using the
      <command>SELECT</command> output expressions for each selected
      row.  (See
      <xref linkend="sql-select-list" endterm="sql-select-list-title">
      below.)
     </para>
    </listitem>

    <listitem>
     <para>
d456 28
d517 3
a519 1
    <literal>ALL</> prevents elimination of duplicates.
d557 3
a559 3
    With <literal>ALL</>, a row that has m duplicates in the left
    table and n duplicates in the right table will appear min(m,n)
    times in the result set.
d571 5
d600 3
a602 3
    With <literal>ALL</>, a row that has m duplicates in the left
    table and n duplicates in the right table will appear max(m-n,0)
    times in the result set.
d611 1
a611 5
  </refsect2>

  <refsect2 id="sql-select-list">
   <title id="sql-select-list-title"><command>SELECT</command> List</title>

d613 2
a614 21
    The <command>SELECT</command> list (between the key words
    <literal>SELECT</> and <literal>FROM</>) specifies expressions
    that form the output rows of the <command>SELECT</command>
    statement.  The expressions can (and usually do) refer to columns
    computed in the <literal>FROM</> clause.  Using the clause
    <literal>AS <replaceable
    class="parameter">output_name</replaceable></literal>, another
    name can be specified for an output column.  This name is
    primarily used to label the column for display.  It can also be
    used to refer to the column's value in <literal>ORDER BY</> and
    <literal>GROUP BY</> clauses, but not in the <literal>WHERE</> or
    <literal>HAVING</> clauses; there you must write out the
    expression instead.
   </para>

   <para>
    Instead of an expression, <literal>*</literal> can be written in
    the output list as a shorthand for all the columns of the selected
    rows.  Also, one can write <literal><replaceable
    class="parameter">table_name</replaceable>.*</literal> as a
    shorthand for the columns coming from just that table.
d722 1
a722 1
    the query's rows---you may be asking for the tenth through
@


1.77
log
@Add documentation for the new "dollar quoting" feature, and update existing
examples to use dollar quoting when appropriate. Original patch from David
Fetter, additional work and editorializing by Neil Conway.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/select.sgml,v 1.76 2004/03/09 16:57:47 neilc Exp $
d1048 1
a1048 1
    In the SQL92 standard, an <literal>ORDER BY</literal> clause may
d1061 1
a1061 1
    SQL99 uses a slightly different definition which is not entirely upward
d1063 1
a1063 1
    with SQL92.  In most cases, however, <productname>PostgreSQL</productname>
d1065 1
a1065 1
    BY</literal> expression the same way SQL99 does.
@


1.76
log
@Refer to GUC variables using <xref> tags rather than <varname> tags,
where appropriate. Add "id" and "xreflabel" tags to the descriptions
of the GUC variables to facilitate this. Also make a few minor docs
cleanups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/select.sgml,v 1.75 2004/03/03 22:22:24 neilc Exp $
d941 1
a941 1
CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS '
d943 1
a943 1
' LANGUAGE SQL;
d950 1
a950 1
CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS '
d952 1
a952 1
' LANGUAGE SQL;
@


1.75
log
@Add a few more cross-references where appropriate, add more text about
the FROM clause and an example to the UPDATE reference page, and make
a few other SGML tweaks.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/select.sgml,v 1.74 2003/12/14 00:15:03 neilc Exp $
d193 2
a194 2
        behavior can be modified by changing the
        <varname>sql_interitance</varname> configuration option.
d1026 1
a1026 1
    <varname>add_missing_from</> parameter to false.
@


1.74
log
@This patch fixes a few more uppercase GUC vars. I also removed an
example from the RESET reference page because it seemed completely
redundant.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/select.sgml,v 1.73 2003/11/29 19:51:39 pgsql Exp $
d177 2
a178 1
    <literal>FROM</literal>-clause elements can contain:
d293 3
a295 3
	<literal>JOIN</literal>s nest left-to-right.  In any case
	<literal>JOIN</literal> binds more tightly than the commas
	separating <literal>FROM</> items.
d302 1
a302 1
	but restricted by the join condition (if any).
d651 1
a651 1
    
@


1.73
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.72 2003/11/04 00:34:45 tgl Exp $
d1025 1
a1025 1
    <varname>ADD_MISSING_FROM</> parameter to false.
@


1.72
log
@Copy-editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.71 2003/11/01 01:56:29 petere Exp $
@


1.71
log
@Spell checking, consistent terminology.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.70 2003/09/11 21:42:20 momjian Exp $
a43 5
<comment>FIXME: This last syntax is incorrect if the join type is an
INNER or OUTER join (in which case one of NATURAL, ON ..., or USING
... is mandatory, not optional). What's the best way to fix
this?</comment>

d105 1
a105 1
      The actual output rows are computed the
a124 9
      If the <literal>LIMIT</literal> or <literal>OFFSET</literal>
      clause is specified, the <command>SELECT</command> statement
      only returns a subset of the result rows. (See <xref
      linkend="sql-limit" endterm="sql-limit-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
d136 9
d289 6
a294 3
        A <literal>JOIN</literal> clause, combines two
        <literal>FROM</> items.  (Use parentheses if necessary to
        determine the order of nesting.)
d299 3
a301 2
        produce a simple Cartesian product, the same as you get from
        listing the two items at the top level of <literal>FROM</>.
d303 1
a303 1
        (true)</>, that is, no rows are removed by qualification.
d317 1
a317 1
        clauses own condition is considered while deciding which rows
d412 1
a412 1
    (<command>SELECT</command> list), or it can be an arbitrary
d499 1
a499 1
    a <literal>UNION</> result or for the inputs of <literal>UNION</>.
d615 1
a615 1
    (<command>SELECT</command> list), or it can be an arbitrary
d625 1
a625 1
    random order.
d662 1
a662 1
    <literal>DESC</> (descending) after each expression in the
d691 1
a691 1
    clauses:
d697 1
a697 1
    maximum number of rows to return, and <replaceable
d699 4
a702 1
    to skip before starting to return rows.
d759 7
d901 1
a901 1
   This example shows how to obtain the union of the tables
d904 1
a904 1
   with letter W in each table.  Only distinct rows are wanted, so the
d937 1
a937 1
   clause, both with and without a column definition list.
d1060 2
a1061 1
    SQL99 uses a slightly different definition which is not upward compatible
@


1.71.2.1
log
@Copy-editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.71 2003/11/01 01:56:29 petere Exp $
d44 5
d110 1
a110 1
      The actual output rows are computed using the
d130 9
a149 9
      If the <literal>LIMIT</literal> or <literal>OFFSET</literal>
      clause is specified, the <command>SELECT</command> statement
      only returns a subset of the result rows. (See <xref
      linkend="sql-limit" endterm="sql-limit-title"> below.)
     </para>
    </listitem>

    <listitem>
     <para>
d294 3
a296 6
        A <literal>JOIN</literal> clause combines two
        <literal>FROM</> items.  Use parentheses if necessary to
        determine the order of nesting.  In the absence of parentheses,
	<literal>JOIN</literal>s nest left-to-right.  In any case
	<literal>JOIN</literal> binds more tightly than the commas
	separating <literal>FROM</> items.
d301 2
a302 3
        produce a simple Cartesian product, the same result as you get from
        listing the two items at the top level of <literal>FROM</>,
	but restricted by the join condition (if any).
d304 1
a304 1
        (TRUE)</>, that is, no rows are removed by qualification.
d318 1
a318 1
        clause's own condition is considered while deciding which rows
d413 1
a413 1
    (<command>SELECT</command> list item), or an arbitrary
d500 1
a500 1
    a <literal>UNION</> result or for any input of a <literal>UNION</>.
d616 1
a616 1
    (<command>SELECT</command> list item), or it can be an arbitrary
d626 1
a626 1
    an implementation-dependent order.
d663 1
a663 1
    <literal>DESC</> (descending) after any expression in the
d692 1
a692 1
    sub-clauses:
d698 1
a698 1
    maximum number of rows to return, while <replaceable
d700 1
a700 4
    to skip before starting to return rows.  When both are specified,
    <replaceable class="parameter">start</replaceable> rows are skipped
    before starting to count the <replaceable
    class="parameter">count</replaceable> rows to be returned.
a756 7

   <para>
    The <literal>DISTINCT ON</> expression(s) must match the leftmost
    <literal>ORDER BY</> expression(s).  The <literal>ORDER BY</> clause
    will normally contain additional expression(s) that determine the
    desired precedence of rows within each <literal>DISTINCT ON</> group.
   </para>
d892 1
a892 1
   The next example shows how to obtain the union of the tables
d895 1
a895 1
   with the letter W in each table.  Only distinct rows are wanted, so the
d928 1
a928 1
   clause, both with and without a column definition list:
d1051 1
a1051 2
    SQL99 uses a slightly different definition which is not entirely upward
    compatible 
@


1.71.2.2
log
@Due to popular domand, backport fix for a typo in the SELECT reference
page, per Thomas F. O'Connell.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.71.2.1 2003/11/04 00:34:50 tgl Exp $
d193 1
a193 1
        <varname>sql_inheritance</varname> configuration option.
@


1.70
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.69 2003/08/31 17:32:24 petere Exp $
d669 1
a669 1
    (But the creator of a user-defined datatype can define exactly what the
@


1.69
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.68 2003/08/17 22:09:00 tgl Exp $
d801 4
a804 4
    <literal>LIMIT</literal> for compatibility with PostgreSQL
    versions before 7.3.  It effectively executes after
    <literal>LIMIT</literal>, however, and so that is the recommended
    place to write it.
d1011 6
a1016 5
    PostgreSQL will warn if the implicit-<literal>FROM</literal>
    feature is used in a <command>SELECT</command> statement that also
    contains an explicit <literal>FROM</literal> clause.  Also, it is
    possible to disable the implicit-<literal>FROM</literal> feature
    by setting the <varname>ADD_MISSING_FROM</> parameter to false.
@


1.68
log
@Update documentation to reflect the fact that ORDER BY, GROUP BY, etc
are now driven by the default btree opclass, rather than assuming that
particular operator names have the needed semantics.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.67 2003/05/04 02:23:16 petere Exp $
d16 4
@


1.67
log
@Last round of reference page editing.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.66 2003/03/25 16:15:44 petere Exp $
d663 5
a667 2
    <literal>ASC</> is equivalent to <literal>USING &lt;</> and
    <literal>DESC</> is equivalent to <literal>USING &gt;</>.
d677 1
a677 1
    Data of character types is sorted according to the locale-specific
d1009 3
a1011 1
    contains an explicit <literal>FROM</literal> clause.
d1023 1
a1023 1
    features lead to parsing ambiguities in this context.
d1033 1
a1033 1
    In the SQL standard, an <literal>ORDER BY</literal> clause may
d1043 7
@


1.67.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.69 2003/08/31 17:32:24 petere Exp $
a16 4
 <indexterm zone="sql-select">
  <primary>SELECT</primary>
 </indexterm>

d663 2
a664 5
    <literal>ASC</> is usually equivalent to <literal>USING &lt;</> and
    <literal>DESC</> is usually equivalent to <literal>USING &gt;</>.
    (But the creator of a user-defined datatype can define exactly what the
    default sort ordering is, and it might correspond to operators with other
    names.)
d674 1
a674 1
    Character-string data is sorted according to the locale-specific
d1006 1
a1006 3
    contains an explicit <literal>FROM</literal> clause.  Also, it is
    possible to disable the implicit-<literal>FROM</literal> feature
    by setting the <varname>ADD_MISSING_FROM</> parameter to false.
d1018 1
a1018 1
    features lead to parsing ambiguities without it.
d1028 1
a1028 1
    In the SQL92 standard, an <literal>ORDER BY</literal> clause may
a1037 7
   </para>

   <para>
    SQL99 uses a slightly different definition which is not upward compatible
    with SQL92.  In most cases, however, <productname>PostgreSQL</productname>
    will interpret an <literal>ORDER BY</literal> or <literal>GROUP
    BY</literal> expression the same way SQL99 does.
@


1.66
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.65 2003/03/20 19:00:01 momjian Exp $
d11 1
d13 4
a16 6
  <refname>
   SELECT
  </refname>
  <refpurpose>
   retrieve rows from a table or view
  </refpurpose></refnamediv>
d18 158
a175 46
  <refsynopsisdivinfo>
   <date>2000-12-11</date>
  </refsynopsisdivinfo>
  <synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
    * | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</replaceable> ] [, ...]
    [ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ]
    [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
    [ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
    [ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
    [ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ]
    [ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
    [ FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] ]

where <replaceable class="PARAMETER">from_item</replaceable> can be:

[ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ]
    [ [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ] ]
|
( <replaceable class="PARAMETER">select</replaceable> )
    [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ]
|
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] )
    [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> | <replaceable class="PARAMETER">column_definition_list</replaceable> ) ]
|
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] )
    AS ( <replaceable class="PARAMETER">column_definition_list</replaceable> )
|
<!-- 
   FIXME: this syntax is incorrect if the join type is an INNER or
   OUTER join (in which case one of NATURAL, ON ..., or USING ... is
   mandatory, not optional). What's the best way to fix this?
-->
<replaceable class="PARAMETER">from_item</replaceable> [ NATURAL ] <replaceable class="PARAMETER">join_type</replaceable> <replaceable class="PARAMETER">from_item</replaceable>
    [ ON <replaceable class="PARAMETER">join_condition</replaceable> | USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ) ]
  </synopsis>
  
  <refsect2 id="R2-SQL-SELECT-1">
   <refsect2info>
    <date>2000-12-11</date>
   </refsect2info>
   <title>
    Inputs
   </title>
d178 2
d182 1
a182 1
      <term><replaceable class="PARAMETER">expression</replaceable></term>
d185 10
a194 1
	The name of a table's column or an expression.
d200 1
a200 1
      <term><replaceable class="PARAMETER">output_name</replaceable></term>
d203 10
a212 7
	Specifies another name for an output column using
	the AS clause.  This name is primarily used to label the column
	for display.  It can also be used to refer to the column's value in
	ORDER BY and GROUP BY clauses.  But the
	<replaceable class="PARAMETER">output_name</replaceable>
	cannot be used in the WHERE or HAVING clauses; write out the
	expression instead.
d218 1
a218 1
      <term><replaceable class="PARAMETER">from_item</replaceable></term>
d221 7
a227 1
        A table reference, sub-SELECT, table function, or JOIN clause.  See below for details.
d231 1
a231 1
     
d233 1
a233 1
      <term><replaceable class="PARAMETER">condition</replaceable></term>
d236 16
a251 2
	A Boolean expression giving a result of true or false.
	See the WHERE and HAVING clause descriptions below.
d257 1
a257 1
      <term><replaceable class="PARAMETER">select</replaceable></term>
d260 27
a286 3
	A select statement with all features except the ORDER BY, 
	LIMIT/OFFSET, and FOR UPDATE clauses (even those can be used when the 
	select is parenthesized).
a287 5
      </listitem>
     </varlistentry>
     
    </variablelist>
   </para>
a288 7
   <para>
    FROM items can contain:
    <variablelist>
     
     <varlistentry>
      <term><replaceable class="PARAMETER">table_name</replaceable></term>
      <listitem>
d290 3
a292 9
	The name (optionally schema-qualified) of an existing table or view.
	If <literal>ONLY</> is specified, only that table is scanned.  If
	<literal>ONLY</> is not specified, the table and all its descendant
	tables (if any) are scanned.  <literal>*</> can be appended to the
	table name to indicate that descendant tables are to be scanned, but
	in the current version, this is the default behavior.  (In releases
	before 7.1, <literal>ONLY</> was the default behavior.)  The
	default behavior can be modified by changing the
	<option>SQL_INHERITANCE</option> configuration option.
d294 1
a294 6
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><replaceable class="PARAMETER">alias</replaceable></term>
      <listitem>
d296 8
a303 10
	A substitute name for the FROM item containing the alias.
	An alias is used for brevity or to eliminate ambiguity for self-joins
	(where the same table is scanned multiple times).  When an alias
	is provided, it completely hides the actual name of the table or
	table function; for example given <literal>FROM foo AS f</>, the
	remainder of the SELECT must refer to this FROM item as <literal>f</>
	not <literal>foo</>.
	If an alias is
	written, a column alias list can also be written to provide
	substitute names for one or more columns of the table.
d305 1
a305 6
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><replaceable class="PARAMETER">select</replaceable></term>
      <listitem>
d307 9
a315 5
	A sub-SELECT can appear in the FROM clause.  This acts as though
	its output were created as a temporary table for the duration of
	this single SELECT command.  Note that the sub-SELECT must be
	surrounded by parentheses, and an alias <emphasis>must</emphasis>
	be provided for it.
a316 2
      </listitem>
     </varlistentry>
a317 3
     <varlistentry>
      <term><replaceable class="PARAMETER">table function</replaceable></term>
      <listitem>
d319 5
a323 12
	A table function can appear in the FROM clause.  This acts as though
	its output were created as a temporary table for the duration of
	this single SELECT command. An alias may also be used. If an alias is
	written, a column alias list can also be written to provide substitute
	names for one or more columns of the table function. If the table
	function has been defined as returning the <type>record</> data type,
	an alias, or the keyword <literal>AS</>, must be present, followed by
	a column definition list in the form ( <replaceable
	class="PARAMETER">column_name</replaceable> <replaceable
	class="PARAMETER">data_type</replaceable> [, ... ] ).
	The column definition list must match the actual number and types
	of columns returned by the function.
d325 1
a325 6
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><replaceable class="PARAMETER">join_type</replaceable></term>
      <listitem>
d327 4
a330 10
       One of
       <command>[ INNER ] JOIN</command>,
       <command>LEFT [ OUTER ] JOIN</command>,
       <command>RIGHT [ OUTER ] JOIN</command>,
       <command>FULL [ OUTER ] JOIN</command>, or
       <command>CROSS JOIN</command>.
       For INNER and OUTER join types, exactly one of NATURAL,
       ON <replaceable class="PARAMETER">join_condition</replaceable>, or
       USING ( <replaceable class="PARAMETER">join_column_list</replaceable> )
       must appear.  For CROSS JOIN, none of these items may appear.
d336 1
a336 1
      <term><replaceable class="PARAMETER">join_condition</replaceable></term>
d339 5
a343 3
       A qualification condition.  This is similar to the WHERE condition
       except that it only applies to the two from_items being joined in
       this JOIN clause.
d349 1
a349 25
      <term><replaceable class="PARAMETER">join_column_list</replaceable></term>
      <listitem>
       <para>
       A USING column list ( a, b, ... ) is shorthand for the ON condition
       left_table.a = right_table.a AND left_table.b = right_table.b ...
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>
  
  <refsect2 id="R2-SQL-SELECT-2">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term>Rows</term>
d352 6
a357 1
	The complete set of rows resulting from the query specification.
d363 1
a363 3
      <term>
       <returnvalue><replaceable>count</replaceable></returnvalue>
      </term>
d366 3
a368 1
	The count of rows returned by the query.
a374 61
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-SELECT-1">
  <refsect1info>
   <date>2000-12-11</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>SELECT</command> will return rows from one or more tables.
   Candidates for selection are rows which satisfy the WHERE condition;
   if WHERE is omitted, all rows are candidates.
   (See <xref linkend="sql-where" endterm="sql-where-title">.)
  </para>

  <para>
   Actually, the returned rows are not directly the rows produced by the
   FROM/WHERE/GROUP BY/HAVING clauses; rather, the output rows are formed
   by computing the SELECT output expressions for each selected row.
   <command>*</command> can be written in the output list as a shorthand
   for all the columns of the selected rows.  Also, one can write
   <replaceable class="PARAMETER">table_name</replaceable><command>.*</command>
   as a shorthand for the columns coming from just that table.
  </para>

  <para>
   DISTINCT will eliminate duplicate rows from the result.  ALL (the
   default) will return all candidate rows, including duplicates.
  </para>

  <para>
   DISTINCT ON eliminates rows that match on all the
   specified expressions, keeping only the first row of each set of
   duplicates.  The DISTINCT ON expressions are interpreted using the
   same rules as for ORDER BY items; see below.
   Note that the <quote>first row</quote> of each set is unpredictable
   unless ORDER BY is used to ensure that the desired
   row appears first.  For example,
   <programlisting>
        SELECT DISTINCT ON (location) location, time, report
        FROM weatherReports
        ORDER BY location, time DESC;
   </programlisting>
   retrieves the most recent weather report for each location.  But if
   we had not used ORDER BY to force descending order of time values
   for each location, we'd have gotten a report of unpredictable age
   for each location.
  </para>

  <para>
   The GROUP BY clause allows a user to divide a table
   into groups of rows that match on one or more values.
   (See <xref linkend="sql-groupby" endterm="sql-groupby-title">.)
  </para>

  <para>
   The HAVING clause allows selection of only those groups of rows
   meeting the specified condition.
   (See <xref linkend="sql-having" endterm="sql-having-title">.)
  </para>
d376 2
a377 38
  <para>
   The ORDER BY clause causes the returned rows to be sorted in a specified
   order.  If ORDER BY is not given, the rows are returned in whatever order
   the system finds cheapest to produce.
   (See <xref linkend="sql-orderby" endterm="sql-orderby-title">.)
  </para>
   
  <para>
   <command>SELECT</command> queries can be combined using UNION,
   INTERSECT, and EXCEPT operators.  Use parentheses if necessary to
   determine the ordering of these operators.
  </para>
   
  <para>
   The UNION operator computes the collection of rows
   returned by the queries involved.
   Duplicate rows are eliminated unless ALL is specified.
   (See <xref linkend="sql-union" endterm="sql-union-title">.)
  </para>
   
  <para>
   The INTERSECT operator computes the rows that are common to both queries.
   Duplicate rows are eliminated unless ALL is specified.
   (See <xref linkend="sql-intersect" endterm="sql-intersect-title">.)
  </para>
   
  <para>
   The EXCEPT operator computes the rows returned by the first query but
   not the second query.
   Duplicate rows are eliminated unless ALL is specified.
   (See <xref linkend="sql-except" endterm="sql-except-title">.)
  </para>
   
  <para>
   The LIMIT clause allows a subset of the rows produced by the query
   to be returned to the user.
   (See <xref linkend="sql-limit" endterm="sql-limit-title">.)
  </para>
d379 16
a394 18
  <para>
   The FOR UPDATE clause causes the <command>SELECT</command>
   statement to lock the selected rows against concurrent updates.
  </para>
   
  <para>
   You must have SELECT privilege to a table to read its values
   (See the <command>GRANT</command>/<command>REVOKE</command> statements).
   Use of FOR UPDATE requires UPDATE privilege as well.
  </para>
   
  <refsect2 id="SQL-FROM">
   <refsect2info>
    <date>2000-12-11</date>
   </refsect2info>
   <title id="sql-from-title">
    FROM Clause
   </title>
d397 4
a400 6
    The FROM clause specifies one or more source tables for the
    <command>SELECT</command>.  If multiple sources are specified, the
    result is conceptually the Cartesian product of all the rows in
    all the sources --- but usually qualification conditions are added
    to restrict the returned rows to a small subset of the Cartesian
    product.
d404 9
a412 9
    When a FROM item is a simple table name, it implicitly includes rows
    from sub-tables (inheritance children) of the table.
    <command>ONLY</command> will
    suppress rows from sub-tables of the table.  Before
    <Productname>PostgreSQL</Productname> 7.1,
    this was the default result, and adding sub-tables was done
    by appending <command>*</command> to the table name.
    This old behavior is available via the command 
    <command>SET SQL_Inheritance TO OFF</command>.
d416 9
a424 5
    A FROM item can also be a parenthesized
    sub-<command>SELECT</command> (note that an alias clause is
    required for a sub-<command>SELECT</command>!).  This is an
    extremely useful feature since it's the only way to get multiple
    levels of grouping, aggregation, or sorting in a single query.
d426 4
d432 6
a437 4
    A FROM item can be a table function (typically, a function that returns
    multiple rows and/or columns, though actually any function can be used).
    The function is invoked with the given argument value(s), and then its
    output is scanned as though it were a table.
d439 1
a439 1

d441 9
a449 9
    In some cases it is useful to define table functions that can return
    different column sets depending on how they are invoked.  To support this,
    the table function can be declared as returning the pseudo-type
    <type>record</>.  When such a function is used in FROM, it must be
    followed by an alias, or the keyword <literal>AS</> alone,
    and then by a parenthesized list of column names and types. This provides
    a query-time composite type definition. The composite type definition
    must match the actual composite type returned from the function, or an
    error will be reported at run-time.
d451 4
d457 12
a468 3
    Finally, a FROM item can be a JOIN clause, which combines two simpler
    FROM items.  (Use parentheses if necessary to determine the order
    of nesting.)
d470 1
a470 1

d472 8
a479 6
    A CROSS JOIN or INNER JOIN is a simple Cartesian product,
    the same as you get from listing the two items at the top level of FROM.
    CROSS JOIN is equivalent to INNER JOIN ON (TRUE), that is, no rows are
    removed by qualification.  These join types are just a notational
    convenience, since they do nothing you couldn't do with plain FROM and
    WHERE.
d481 1
a481 1

d483 3
a485 8
    LEFT OUTER JOIN returns all rows in the qualified Cartesian product
    (i.e., all combined rows that pass its ON condition), plus one copy of each
    row in the left-hand table for which there was no right-hand row that
    passed the ON condition.  This left-hand row is extended to the full
    width of the joined table by inserting null values for the right-hand columns.
    Note that only the <literal>JOIN</>'s own ON or USING condition is considered while
    deciding which rows have matches.  Outer ON or WHERE conditions are
    applied afterwards.
d487 1
a487 1

d489 3
a491 5
    Conversely, RIGHT OUTER JOIN returns all the joined rows, plus one row
    for each unmatched right-hand row (extended with nulls on the left).
    This is just a notational
    convenience, since you could convert it to a LEFT OUTER JOIN by switching
    the left and right inputs.
d493 1
a493 1

d495 2
a496 3
    FULL OUTER JOIN returns all the joined rows, plus one row for each
    unmatched left-hand row (extended with nulls on the right), plus one row
    for each unmatched right-hand row (extended with nulls on the left).
d498 4
d504 7
a510 10
    For all the JOIN types except CROSS JOIN, you must write exactly one of
    ON <replaceable class="PARAMETER">join_condition</replaceable>,
    USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ),
    or NATURAL.  ON is the most general case: you can write any qualification
    expression involving the two tables to be joined.
    A USING column list ( a, b, ... ) is shorthand for the ON condition
    left_table.a = right_table.a AND left_table.b = right_table.b ...
    Also, USING implies that only one of each pair of equivalent columns will
    be included in the JOIN output, not both.  NATURAL is shorthand for
    a USING list that mentions all similarly-named columns in the tables.
a511 9
  </refsect2>
   
  <refsect2 id="SQL-WHERE">
   <refsect2info>
    <date>2000-03-15</date>
   </refsect2info>
   <title id="sql-where-title">
    WHERE Clause
   </title>
d514 5
a518 1
    The optional WHERE condition has the general form:
d520 7
a526 3
    <synopsis>
WHERE <replaceable class="PARAMETER">boolean_expr</replaceable>
    </synopsis>
d528 8
a535 22
    <replaceable class="PARAMETER">boolean_expr</replaceable>
    can consist of any expression which evaluates to a Boolean value.
    In many cases, this expression will be:

    <synopsis>
     <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">cond_op</replaceable> <replaceable class="PARAMETER">expr</replaceable>
    </synopsis>

    or

    <synopsis>
     <replaceable class="PARAMETER">log_op</replaceable> <replaceable class="PARAMETER">expr</replaceable>
    </synopsis>

    where <replaceable class="PARAMETER">cond_op</replaceable>
    can be one of: =, &lt;, &lt;=, &gt;, &gt;= or &lt;&gt;,
    a conditional operator like ALL, ANY, IN, LIKE, or a
    locally defined operator, 
    and <replaceable class="PARAMETER">log_op</replaceable> can be one 
    of: AND, OR, NOT.
    SELECT will ignore all rows for which the WHERE condition does not return
    TRUE.
d538 3
a540 15
  
  <refsect2 id="SQL-GROUPBY">
   <refsect2info>
    <date>2000-03-15</date>
   </refsect2info>
   <title id="sql-groupby-title">
    GROUP BY Clause
   </title>
   <para>
    GROUP BY specifies a grouped table derived by the application
    of this clause:
    <synopsis>
GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...]
    </synopsis>
   </para>
d543 7
a549 10
    GROUP BY will condense into a single row all selected rows that
    share the same values for the grouped columns.  Aggregate
    functions, if any, are computed across all rows making up each
    group, producing a separate value for each group (whereas without
    GROUP BY, an aggregate produces a single value computed across all
    the selected rows).  When GROUP BY is present, it is not valid for
    the <command>SELECT</command> output expression(s) to refer to
    ungrouped columns except within aggregate functions, since there
    would be more than one possible value to return for an ungrouped
    column.
d553 3
a555 6
    A GROUP BY item can be an input column name, or the name or
    ordinal number of an output column (<command>SELECT</command>
    expression), or it can be an arbitrary expression formed from
    input-column values.  In case of ambiguity, a GROUP BY name will
    be interpreted as an input-column name rather than an output
    column name.
d557 1
a557 9
  </refsect2>

  <refsect2 id="SQL-HAVING">
   <refsect2info>
    <date>2000-03-15</date>
   </refsect2info>
   <title id="sql-having-title">
    HAVING Clause
   </title>
d559 6
a564 1
    The optional HAVING condition has the general form:
d566 5
a570 6
    <synopsis>
HAVING <replaceable class="PARAMETER">boolean_expr</replaceable>
    </synopsis>
    
    where <replaceable class="PARAMETER">boolean_expr</replaceable> is the same
    as specified for the WHERE clause.
d572 5
a576 1
    
d578 13
a590 6
    HAVING specifies a grouped table derived by the elimination
    of group rows that do not satisfy the
    <replaceable class="PARAMETER">boolean_expr</replaceable>.
    HAVING is different from WHERE:
    WHERE filters individual rows before application of GROUP BY,
    while HAVING filters group rows created by GROUP BY.
d594 5
a598 4
    Each column referenced in 
    <replaceable class="PARAMETER">boolean_expr</replaceable> shall unambiguously
    reference a grouping column, unless the reference appears within an
    aggregate function.
d601 1
a601 1
  
d603 13
a615 11
   <refsect2info>
    <date>2000-03-15</date>
   </refsect2info>
   <title id="sql-orderby-title">
    ORDER BY Clause
   </title>
   <para>
    <synopsis>
ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...]
    </synopsis></para>
    
d617 6
a622 5
    An ORDER BY item can be the name or ordinal number of an output
    column (<command>SELECT</command> expression), or it can be an
    arbitrary expression formed from input-column values.  In case of
    ambiguity, an ORDER BY name will be interpreted as an
    output-column name.
d624 1
d627 6
a632 7
    of the result column. This feature makes it possible to define an ordering
    on the basis of a column that does not have a unique name.
    This is never absolutely necessary because it is always possible
    to assign a name to a result column using the AS clause, e.g.:
    <programlisting>
SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
    </programlisting></para>
d635 5
a639 6
    It is also possible to ORDER BY
    arbitrary expressions (an extension to SQL92),
    including fields that do not appear in the
    SELECT result list.
    Thus the following statement is legal:
    <programlisting>
d641 5
a645 4
    </programlisting>
    A limitation of this feature is that an ORDER BY clause applying to the
    result of a UNION, INTERSECT, or EXCEPT query may only specify an output
    column name or number, not an expression.
d649 6
a654 5
    Note that if an ORDER BY item is a simple name that matches both
    a result column name and an input column name, ORDER BY will interpret
    it as the result column name.  This is the opposite of the choice that
    GROUP BY will make in the same situation.  This inconsistency is
    mandated by the SQL92 standard.
d658 2
a659 2
    Optionally one may add the key word <literal>DESC</> (descending)
    or <literal>ASC</> (ascending) after each column name in the
d662 3
a664 3
    name may be specified.  <literal>ASC</> is equivalent to
    <literal>USING &lt;</> and <literal>DESC</> is equivalent to
    <literal>USING &gt;</>.
d668 3
a670 3
   The null value sorts higher than any other value in a domain. In other
   words, with ascending sort order nulls sort at the end and with
   descending sort order nulls sort at the beginning.
a677 1

d680 3
a682 24
  <refsect2 id="SQL-UNION">
   <refsect2info>
    <date>2000-12-11</date>
   </refsect2info>
   <title id="sql-union-title">
    UNION Clause
   </title>
   <para>
    <synopsis>
<replaceable class="PARAMETER">table_query</replaceable> UNION [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
    [ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
    </synopsis>

    where
    <replaceable class="PARAMETER">table_query</replaceable>
    specifies any select expression without an ORDER BY, LIMIT, or FOR UPDATE
    clause.  (ORDER BY and LIMIT can be attached to a sub-expression
    if it is enclosed in parentheses.  Without parentheses, these clauses
    will be taken to apply to the result of the UNION, not to its right-hand
    input expression.)
   </para>
    
d684 10
a693 45
    The UNION operator computes the collection (set union) of the rows
    returned by the queries involved.  The two
    <command>SELECT</command> statements that represent the direct
    operands of the UNION must produce the same number of columns, and
    corresponding columns must be of compatible data types.
   </para>
    
   <para>
    The result of UNION does not contain any duplicate rows
    unless the ALL option is specified.  ALL prevents elimination of
    duplicates.
   </para>
    
   <para>
    Multiple UNION operators in the same <command>SELECT</command>
    statement are evaluated left to right, unless otherwise indicated
    by parentheses.
   </para>
    
   <para>
    Currently, FOR UPDATE may not be specified either for a UNION result
    or for the inputs of a UNION.
   </para>

  </refsect2>

  <refsect2 id="SQL-INTERSECT">
   <refsect2info>
    <date>2000-12-11</date>
   </refsect2info>
   <title id="sql-intersect-title">
    INTERSECT Clause
   </title>
   <para>
    <synopsis>
<replaceable class="PARAMETER">table_query</replaceable> INTERSECT [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
    [ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
    </synopsis>
    
    where
    <replaceable class="PARAMETER">table_query</replaceable>
    specifies any select expression without an ORDER BY, LIMIT, or 
    FOR UPDATE clause.
d697 6
a702 2
    INTERSECT is similar to UNION, except that it produces only rows that
    appear in both query outputs, rather than rows that appear in either.
a703 15
    
   <para>
    The result of INTERSECT does not contain any duplicate rows
    unless the ALL option is specified.  With ALL, a row that has
    m duplicates in L and n duplicates in R will appear min(m,n) times.
   </para>
    
   <para>
    Multiple INTERSECT operators in the same SELECT statement are
    evaluated left to right, unless parentheses dictate otherwise.
    INTERSECT binds more tightly than UNION --- that is,
    A UNION B INTERSECT C will be read as 
    A UNION (B INTERSECT C) unless otherwise specified by parentheses.
   </para>
  </refsect2>
a704 32
  <refsect2 id="SQL-EXCEPT">
   <refsect2info>
    <date>2000-12-11</date>
   </refsect2info>
   <title id="sql-except-title">
    EXCEPT Clause
   </title>
   <para>
    <synopsis>
<replaceable class="PARAMETER">table_query</replaceable> EXCEPT [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
    [ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
    [ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
    </synopsis>
    
    where
    <replaceable class="PARAMETER">table_query</replaceable>
    specifies any select expression without an ORDER BY, LIMIT,
    or FOR UPDATE clause.
   </para>

   <para>
    EXCEPT is similar to UNION, except that it produces only rows that
    appear in the left query's output but not in the right query's output.
   </para>
    
   <para>
    The result of EXCEPT does not contain any duplicate rows
    unless the ALL option is specified.  With ALL, a row that has
    m duplicates in L and n duplicates in R will appear max(m-n,0) times.
   </para>
    
d706 11
a716 3
    Multiple EXCEPT operators in the same SELECT statement are
    evaluated left to right, unless parentheses dictate otherwise.
    EXCEPT binds at the same level as UNION.
d720 2
a721 19
  <refsect2 id="SQL-LIMIT">
   <refsect2info>
    <date>2000-02-20</date>
   </refsect2info>
   <title id="sql-limit-title">
    LIMIT Clause
   </title>
   <para>
    <synopsis>
    LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL }
    OFFSET <replaceable class="PARAMETER">start</replaceable>
    </synopsis>
    
    where
    <replaceable class="PARAMETER">count</replaceable> specifies the
    maximum number of rows to return, and
    <replaceable class="PARAMETER">start</replaceable> specifies the
    number of rows to skip before starting to return rows.
   </para>
d724 4
a727 4
    LIMIT allows you to retrieve just a portion of the rows that are generated
    by the rest of the query.  If a limit count is given, no more than that
    many rows will be returned.  If an offset is given, that many rows will
    be skipped before starting to return rows.
d731 18
a748 18
    When using LIMIT, it is a good idea to use an ORDER BY clause that
    constrains the result rows into a unique order.  Otherwise you will get
    an unpredictable subset of the query's rows---you may be asking for
    the tenth through twentieth rows, but tenth through twentieth in what
    ordering?  You don't know what ordering unless you specify ORDER BY.
   </para>

   <para>
    As of <productname>PostgreSQL</productname> 7.0, the
    query optimizer takes LIMIT into account when generating a query plan,
    so you are very likely to get different plans (yielding different row
    orders) depending on what you use for LIMIT and OFFSET.  Thus, using
    different LIMIT/OFFSET values to select different subsets of a query
    result <emphasis>will give inconsistent results</emphasis> unless
    you enforce a predictable result ordering with ORDER BY.  This is not
    a bug; it is an inherent consequence of the fact that SQL does not
    promise to deliver the results of a query in any particular order
    unless ORDER BY is used to constrain the order.
d753 7
a759 10
   <refsect2info>
    <date>2002-08-28</date>
   </refsect2info>
   <title id="sql-for-update-title">
    FOR UPDATE Clause
   </title>
   <para>
    <synopsis>
    FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ]
    </synopsis>
d763 10
a772 10
    FOR UPDATE causes the rows retrieved by the query to be locked as
    though for update.  This prevents them from being modified or
    deleted by other transactions until the current transaction ends;
    that is, other transactions that attempt
    <command>UPDATE</command>, <command>DELETE</command>, or
    <command>SELECT FOR UPDATE</command> of these rows will be blocked
    until the current transaction ends.  Also, if an
    <command>UPDATE</command>, <command>DELETE</command>, or
    <command>SELECT FOR UPDATE</command> from another transaction has
    already locked a selected row or rows, <command>SELECT FOR
d775 2
a776 1
    row was deleted).  For further discussion see <xref linkend="mvcc">.
d780 4
a783 3
    If specific tables are named in FOR UPDATE, then only rows coming
    from those tables are locked; any other tables used in the
    <command>SELECT</command> are simply read as usual.
d787 3
a789 3
    FOR UPDATE cannot be used in contexts where returned rows can't be clearly
    identified with individual table rows; for example it can't be used with
    aggregation.
d793 5
a797 3
    FOR UPDATE may appear before LIMIT for compatibility with
    pre-7.3 applications.  However, it effectively executes after LIMIT,
    and so that is the recommended place to write it.
a799 1

d802 2
a803 4
 <refsect1 id="R1-SQL-SELECT-2">
  <title>
   Usage
  </title>
d809 1
a809 1
   <programlisting>
d814 5
a818 20
           title           | did |   name           | date_prod  | kind
---------------------------+-----+------------------+------------+----------
 The Third Man             | 101 | British Lion     | 1949-12-23 | Drama
 The African Queen         | 101 | British Lion     | 1951-08-11 | Romantic
 Une Femme est une Femme   | 102 | Jean Luc Godard  | 1961-03-12 | Romantic
 Vertigo                   | 103 | Paramount        | 1958-11-14 | Action
 Becket                    | 103 | Paramount        | 1964-02-03 | Drama
 48 Hrs                    | 103 | Paramount        | 1982-10-22 | Action
 War and Peace             | 104 | Mosfilm          | 1967-02-12 | Drama
 West Side Story           | 105 | United Artists   | 1961-01-03 | Musical
 Bananas                   | 105 | United Artists   | 1971-07-13 | Comedy
 Yojimbo                   | 106 | Toho             | 1961-06-16 | Drama
 There's a Girl in my Soup | 107 | Columbia         | 1970-06-11 | Comedy
 Taxi Driver               | 107 | Columbia         | 1975-05-15 | Action
 Absence of Malice         | 107 | Columbia         | 1981-11-15 | Action
 Storia di una donna       | 108 | Westward         | 1970-08-15 | Romantic
 The King and I            | 109 | 20th Century Fox | 1956-08-11 | Musical
 Das Boot                  | 110 | Bavaria Atelier  | 1981-11-11 | Drama
 Bed Knobs and Broomsticks | 111 | Walt Disney      |            | Musical
(17 rows)
d827 1
a827 1
SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
a835 1
(5 rows)
d845 1
a845 1
SELECT kind, SUM(len) AS total
d848 1
a848 1
    HAVING SUM(len) < INTERVAL '5 hour';
d850 1
a850 1
 kind     | total
a853 1
(2 rows)
d862 1
a862 1
   <programlisting>
a880 1
(13 rows)
d889 1
a889 1
   ALL keyword is omitted:
d901 2
a902 2
    FROM   distributors
    WHERE  distributors.name LIKE 'W%'
d905 2
a906 2
    FROM   actors
    WHERE  actors.name LIKE 'W%';
d920 2
a921 2
   This example shows how to use a table function, both with and without
   a column definition list.
d924 3
a926 12
distributors:
 did |     name
-----+--------------
 108 | Westward
 111 | Walt Disney
 112 | Warner Bros.
 ...

CREATE FUNCTION distributors(int)
  RETURNS SETOF distributors AS '
  SELECT * FROM distributors WHERE did = $1;
  ' LANGUAGE SQL;
a931 1
(1 row)
d933 3
a935 4
CREATE FUNCTION distributors_2(int)
  RETURNS SETOF RECORD AS '
  SELECT * FROM distributors WHERE did = $1;
  ' LANGUAGE SQL;
a940 1
(1 row)
d945 8
a952 4
 <refsect1 id="R1-SQL-SELECT-3">
  <title>
   Compatibility
  </title>
d954 2
a955 5
  <refsect2 id="R2-SQL-SELECT-4">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>Extensions</title>
d958 4
a961 6
<productname>PostgreSQL</productname> allows one to omit 
the <command>FROM</command> clause from a query. This feature
was retained from the original PostQUEL query language.  It has
a straightforward use to compute the results of simple expressions:

  <programlisting>
d967 5
a971 1
  </programlisting>
d973 4
a976 5
Some other <acronym>SQL</acronym> databases cannot do this except by
introducing a dummy one-row table to do the select from.  A less
obvious use is to abbreviate a normal select from one or more tables:

  <programlisting>
d979 1
a979 1
 did | name
d982 6
a987 1
  </programlisting>
d989 4
a992 4
This works because an implicit FROM item is added for each table that is
referenced in the query but not mentioned in FROM.  While this is a convenient
shorthand, it's easy to misuse.  For example, the query
  <programlisting>
d994 3
a996 3
  </programlisting>
is probably a mistake; most likely the user meant
  <programlisting>
d998 3
a1000 3
  </programlisting>
rather than the unconstrained join
  <programlisting>
d1002 10
a1011 5
  </programlisting>
that he will actually get.  To help detect this sort of mistake,
<Productname>PostgreSQL</Productname> 7.1
and later will warn if the implicit-FROM feature is used in a query that also
contains an explicit FROM clause.
d1013 8
d1022 4
d1028 10
a1037 2
    The table-function feature is a <productname>PostgreSQL</productname>
    extension.
d1041 3
a1043 7
  <refsect2 id="R2-SQL-SELECT-5">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    <acronym>SQL92</acronym>
   </title>
d1045 3
a1048 57
   
   <refsect3 id="R3-SQL-SELECT-1">
    <refsect3info>
     <date>1998-04-15</date>
    </refsect3info>
    <title>
     SELECT Clause
    </title>
    <para>
     In the <acronym>SQL92</acronym> standard, the optional keyword <literal>AS</>
     is just noise and can be 
     omitted without affecting the meaning.
     The <productname>PostgreSQL</productname> parser requires this keyword when
     renaming output columns because the type extensibility features lead to
     parsing ambiguities
     in this context.  <literal>AS</literal> is optional in FROM items, however.</para>
     
    <para>
     The DISTINCT ON phrase is not part of <acronym>SQL92</acronym>.
     Nor are LIMIT and OFFSET.
    </para>
     
    <para>
     In <acronym>SQL92</acronym>, an ORDER BY clause may only use result
     column names or numbers, while a GROUP BY clause may only use input
     column names.
     <productname>PostgreSQL</productname> extends each of these clauses to
     allow the other choice as well (but it uses the standard's interpretation
     if there is ambiguity).
     <productname>PostgreSQL</productname> also allows both clauses to specify
     arbitrary expressions.  Note that names appearing in an expression will
     always be taken as input-column names, not as result-column names.
    </para>
   </refsect3>

   <refsect3 id="R3-SQL-UNION-1">
    <refsect3info>
     <date>1998-09-24</date>
    </refsect3info>
    <title>
     UNION/INTERSECT/EXCEPT Clause
    </title>
    <para>
     The <acronym>SQL92</acronym> syntax for UNION/INTERSECT/EXCEPT allows an
     additional CORRESPONDING BY option:
     <synopsis> 
<replaceable class="PARAMETER">table_query</replaceable> UNION [ALL]
    [CORRESPONDING [BY (<replaceable class="PARAMETER">column</replaceable> [,...])]]
    <replaceable class="PARAMETER">table_query</replaceable>
     </synopsis></para>

    <para>
     The CORRESPONDING BY clause is not supported by
     <productname>PostgreSQL</productname>.
    </para>
   </refsect3>
   
@


1.65
log
@The documentation for SELECT is incorrect in a sense: the syntax for a
join is defined as:

from_item [ NATURAL ] join_type from_item
    [ ON join_condition | USING ( join_column_list ) ]

However, if the join_type is an INNER or OUTER join, an ON, USING, or
NATURAL clause *must* be specified (it's not optional, as that segment
of the docs suggest).

I'm not exactly sure what the best way to fix this is, so I've attached
a patch adding a FIXME comment to the relevant section of the SGML. If
anyone has any ideas on the proper way to outline join syntax, please
speak up.

Neil Conway <neilc@@samurai.com> || PGP Key ID: DB3C29FC
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.64 2003/01/19 00:13:31 momjian Exp $
d888 1
a888 2
    row was deleted).  For further discussion see the concurrency
    chapter of the &cite-user;.
@


1.64
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.63 2002/10/24 21:19:15 tgl Exp $
d49 5
@


1.63
log
@Add note about sort order of character datatypes being locale-dependent,
per suggestion from Nicolaus Erichsen.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.62 2002/10/18 18:26:22 tgl Exp $
d294 2
a295 4
   <command>DISTINCT</command> will eliminate duplicate rows from the
   result.
   <command>ALL</command> (the default) will return all candidate rows,
   including duplicates.
d299 1
a299 1
   <command>DISTINCT ON</command> eliminates rows that match on all the
d304 1
a304 1
   unless <command>ORDER BY</command> is used to ensure that the desired
d337 3
a339 3
   SELECT queries can be combined using UNION, INTERSECT, and EXCEPT
   operators.  Use parentheses if necessary to determine the ordering
   of these operators.
d369 2
a370 2
   The FOR UPDATE clause causes the SELECT statement to lock the selected
   rows against concurrent updates.
d388 6
a393 5
    The FROM clause specifies one or more source tables for the SELECT.
    If multiple sources are specified, the result is conceptually the
    Cartesian product of all the rows in all the sources --- but usually
    qualification conditions are added to restrict the returned rows to
    a small subset of the Cartesian product.
d409 5
a413 4
    A FROM item can also be a parenthesized sub-SELECT (note that an
    alias clause is required for a sub-SELECT!).  This is an extremely
    handy feature since it's the only way to get multiple levels of
    grouping, aggregation, or sorting in a single query.
d545 7
a551 7
    GROUP BY will condense into a single row all selected rows that share the
    same values for the grouped columns.  Aggregate functions, if any,
    are computed across all rows making up each group, producing a
    separate value for each group (whereas without GROUP BY, an
    aggregate produces a single value computed across all the selected
    rows).  When GROUP BY is present, it is not valid for the SELECT
    output expression(s) to refer to
d553 2
a554 1
    would be more than one possible value to return for an ungrouped column.
d558 6
a563 5
    A GROUP BY item can be an input column name, or the name or ordinal
    number of an output column (SELECT expression), or it can be an arbitrary
    expression formed from input-column values.  In case of ambiguity, a GROUP
    BY name will 
    be interpreted as an input-column name rather than an output column name.
d615 5
a619 4
    An ORDER BY item can be the name or ordinal
    number of an output column (SELECT expression), or it can be an arbitrary
    expression formed from input-column values.  In case of ambiguity, an
    ORDER BY name will be interpreted as an output-column name.
d703 4
a706 4
    returned by the queries involved.
    The two SELECT statements that represent the direct operands of the UNION must
    produce the same number of columns, and corresponding columns must be
    of compatible data types.
d716 3
a718 2
    Multiple UNION operators in the same SELECT statement are
    evaluated left to right, unless otherwise indicated by parentheses.
d871 14
a884 10
    FOR UPDATE causes the rows retrieved by the query to be locked as though
    for update.  This prevents them from being modified or deleted by other
    transactions until the current transaction ends; that is, other
    transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE of these
    rows will be blocked until the current transaction ends.  Also, if an
    UPDATE, DELETE, or SELECT FOR UPDATE from another transaction has already
    locked a selected row or rows, SELECT FOR UPDATE will wait for the other
    transaction to complete, and will then lock and return the updated row
    (or no row, if the row was deleted).  For further discussion see the
    concurrency chapter of the <citetitle>User's Guide</citetitle>.
d888 3
a890 3
    If specific tables are named in FOR UPDATE, then only rows coming from
    those tables are locked; any other tables used in the SELECT are simply
    read as usual.
d1108 3
a1110 3
Some other SQL databases cannot do this except by introducing a dummy one-row
table to do the select from.  A less obvious use is to abbreviate a
normal select from one or more tables:
@


1.62
log
@Improve discussion of FOR UPDATE.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.61 2002/09/21 18:32:54 petere Exp $
d621 1
a621 1
    on the basis of a column that does not have a proper name.
d664 6
@


1.61
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.60 2002/08/30 16:00:41 momjian Exp $
d371 2
a372 2
   The FOR UPDATE clause allows the SELECT statement to perform 
   exclusive locking of selected rows.
d378 1
d863 8
a870 1
    transactions until the current transaction ends.
d875 2
a876 1
    those tables are locked.
d882 7
a888 2
    aggregation.  FOR UPDATE may also appear before LIMIT for portability with
    pre-7.3 applications.
@


1.60
log
@Back out password packet length check.

Improve wording of pre-7.3 syntax mention.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.59 2002/08/30 03:18:23 momjian Exp $
d454 2
a455 2
    width of the joined table by inserting NULLs for the right-hand columns.
    Note that only the JOIN's own ON or USING condition is considered while
d650 7
a656 5
    Optionally one may add the keyword DESC (descending)
    or ASC (ascending) after each column name in the ORDER BY clause.
    If not specified, ASC is assumed by default.  Alternatively, a
    specific ordering operator name may be specified.  ASC is equivalent
    to USING &lt; and DESC is equivalent to USING &gt;.
d694 1
a694 1
    The two SELECTs that represent the direct operands of the UNION must
d1069 1
a1069 1
was retained from the original PostQuel query language.  It has
d1080 1
a1080 1
Some other DBMSes cannot do this except by introducing a dummy one-row
@


1.59
log
@Add comment on old sytax for SELECT FOR UPDATE/LIMIT and COPY.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.58 2002/08/29 00:17:01 tgl Exp $
d872 1
a872 1
    pre-7.3 servers.
@


1.58
log
@Code review for standalone composite types, query-specified composite
types, SRFs.  Not happy with memory management yet, but I'll commit these
other changes.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.57 2002/08/28 14:35:37 momjian Exp $
d871 2
a872 1
    aggregation.
@


1.57
log
@Allow FOR UPDATE to appear after LIMIT/OFFSET to match MySQL syntax and as
a more logical ordering.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.56 2002/08/15 02:59:18 momjian Exp $
d43 1
a43 1
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d46 1
a46 1
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d145 1
a145 2
	A substitute name for the preceding
	<replaceable class="PARAMETER">table_name</replaceable>.
d147 6
a152 1
	(where the same table is scanned multiple times).  If an alias is
d179 9
a187 6
	written, a column alias list can also be written to provide	substitute names
	for one or more columns of the table function. If the table function has been
	defined as returning the RECORD data type, an alias, or the keyword AS, must
    also be present, followed by a column definition list in the form
	( <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] ).
	The column definition list must match the actual number and types returned by the function.
d405 1
a405 1
    <command>SET SQL_Inheritance TO OFF;</command>
d416 16
a431 10
    A FROM item can be a table function (i.e. a function that returns
    multiple rows and columns).  When a table function is created, it may
	be defined to return a named scalar or composite data type (an existing
	scalar data type, or a table or view name), or it may be defined to return
	a RECORD data type. When a table function is defined to return RECORD, it
	must be followed in the FROM clause by an alias, or the keyword AS alone,
	and then by a parenthesized list of column names and types. This provides
	a query-time composite type definition. The FROM clause composite type
	must match the actual composite type returned from the function or an
	ERROR will be generated.
d843 32
d1067 1
a1067 2
a straightforward use to compute the results of simple constant
expressions:
d1108 5
@


1.56
log
@> Neil Conway <nconway@@klamath.dyndns.org> writes:
> > This patch improves the documentation of the UPDATE and ALTER TABLE
> > commands to elaborate on the effect of specifying an "ONLY" clause.
>
> Unfortunately this is still only half the truth ... see the
> SQL_INHERITANCE configuration variable.

Okay, I've attached an updated patch with more information on
SQL_INHERITANCE and inheritance behavior in prior releases.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.55 2002/08/04 19:48:09 momjian Exp $
a30 1
    [ FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] ]
d33 1
d110 3
a112 3
	A select statement with all features except the ORDER BY, FOR UPDATE,
	and LIMIT clauses (even those can be used when the select is
	parenthesized).
a357 5
   The FOR UPDATE clause allows the SELECT statement to perform 
   exclusive locking of selected rows.
  </para>
   
  <para>
d364 5
d669 2
a670 2
    specifies any select expression without an ORDER BY, FOR UPDATE,
    or LIMIT clause.  (ORDER BY and LIMIT can be attached to a sub-expression
d719 2
a720 2
    specifies any select expression without an ORDER BY, FOR UPDATE,
    or LIMIT clause.
d760 2
a761 2
    specifies any select expression without an ORDER BY, FOR UPDATE,
    or LIMIT clause.
@


1.55
log
@Attached are two patches to implement and document anonymous composite
types for Table Functions, as previously proposed on HACKERS. Here is a
brief explanation:

1. Creates a new pg_type typtype: 'p' for pseudo type (currently either
     'b' for base or 'c' for catalog, i.e. a class).

2. Creates new builtin type of typtype='p' named RECORD. This is the
     first of potentially several pseudo types.

3. Modify FROM clause grammer to accept:
     SELECT * FROM my_func() AS m(colname1 type1, colname2 type1, ...)
     where m is the table alias, colname1, etc are the column names, and
     type1, etc are the column types.

4. When typtype == 'p' and the function return type is RECORD, a list
     of column defs is required, and when typtype != 'p', it is
disallowed.

5. A check was added to ensure that the tupdesc provide via the parser
     and the actual return tupdesc match in number and type of
attributes.

When creating a function you can do:
     CREATE FUNCTION foo(text) RETURNS setof RECORD ...

When using it you can do:
     SELECT * from foo(sqlstmt) AS (f1 int, f2 text, f3 timestamp)
       or
     SELECT * from foo(sqlstmt) AS f(f1 int, f2 text, f3 timestamp)
       or
     SELECT * from foo(sqlstmt) f(f1 int, f2 text, f3 timestamp)

Included in the patches are adjustments to the regression test sql and
expected files, and documentation.

p.s.
     This potentially solves (or at least improves) the issue of builtin
     Table Functions. They can be bootstrapped as returning RECORD, and
     we can wrap system views around them with properly specified column
     defs. For example:

     CREATE VIEW pg_settings AS
       SELECT s.name, s.setting
       FROM show_all_settings()AS s(name text, setting text);

     Then we can also add the UPDATE RULE that I previously posted to
     pg_settings, and have pg_settings act like a virtual table, allowing
     settings to be queried and set.


Joe Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/select.sgml,v 1.54 2002/04/23 02:07:16 tgl Exp $
d134 3
a136 1
	before 7.1, <literal>ONLY</> was the default behavior.)
@


1.54
log
@Update SQL-command reference pages for schema features.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.53 2002/03/27 19:19:23 petere Exp $
d43 6
d91 1
a91 1
        A table reference, sub-SELECT, or JOIN clause.  See below for details.
d165 17
d407 13
d964 37
@


1.53
log
@Don't mark up as acronym that which is not an acronym.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.52 2002/03/22 19:20:45 petere Exp $
d122 7
a128 6
	The name of an existing table or view.  If ONLY is specified, only that
	table is scanned.  If ONLY is not specified, the table and all its
	descendant tables (if any) are scanned.  * can be appended to the
	table name to indicate that descendant tables are to be scanned,
	but in the current version, this is the default behavior.
	(In releases before 7.1, ONLY was the default behavior.)
@


1.52
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.51 2001/12/08 03:24:39 thomas Exp $
d940 1
a940 3
   <title>
    <acronym>Extensions</acronym>
   </title>
@


1.51
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.50 2001/10/31 04:50:52 momjian Exp $
d94 1
a94 1
	A boolean expression giving a result of true or false.
d371 1
a371 1
    This old behaviour is available via the command 
d452 1
a452 1
    can consist of any expression which evaluates to a boolean value.
@


1.50
log
@Attached is a small patch for the Reference Manual which adds
information about nulls and sort order.

This is based on information obtained from Peter Eisentraut and
Tom Lane on pgsql-hackers.

Please check my English and Docbook markup, as both are a second
language to me.

Rene Pijlman
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.49 2001/10/23 16:42:36 momjian Exp $
Postgres documentation
d368 1
a368 1
    <Productname>Postgres</Productname> 7.1,
d779 1
a779 1
    As of <productname>Postgres</productname> 7.0, the
d945 1
a945 1
<productname>Postgres</productname> allows one to omit 
d986 1
a986 1
<Productname>Postgres</Productname> 7.1
d1014 1
a1014 1
     The <productname>Postgres</productname> parser requires this keyword when
d1028 1
a1028 1
     <productname>Postgres</productname> extends each of these clauses to
d1031 1
a1031 1
     <productname>Postgres</productname> also allows both clauses to specify
d1055 1
a1055 1
     <productname>Postgres</productname>.
@


1.49
log
@Move ALL out of UNION|INTERSECT|EXCEPT syntax.

Alvaro Herrera
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.48 2001/10/20 02:55:38 momjian Exp $
d604 7
@


1.48
log
@Remove LIMIT #,# and suggest LIMIT # OFFSET #, per mailing list discussion.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.47 2001/09/23 03:39:01 momjian Exp $
d29 1
a29 1
    [ { UNION | INTERSECT | EXCEPT [ ALL ] } <replaceable class="PARAMETER">select</replaceable> ]
@


1.47
log
@Implement TODO item:

	* Change LIMIT val,val to offset,limit to match MySQL

Documentation updates too.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.46 2001/09/14 10:28:09 ishii Exp $
d32 1
a32 1
    [ LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
d617 1
a617 1
    [ LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
d667 1
a667 1
    [ LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
d708 1
a708 1
    [ LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
d745 1
a745 1
    LIMIT [ <replaceable class="PARAMETER">start</replaceable> , ] { <replaceable class="PARAMETER">count</replaceable> | ALL }
@


1.46
log
@Add semicolon
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.45 2001/09/13 15:55:24 petere Exp $
d32 2
a33 1
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]]
d617 2
a618 1
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]]
d667 2
a668 1
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]]
d708 2
a709 1
    [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]]
d745 1
a745 1
    LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]
d768 1
a768 1
    ordering?  You don't know what ordering, unless you specified ORDER BY.
d775 1
a775 1
    orders) depending on what you give for LIMIT and OFFSET.  Thus, using
@


1.45
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.44 2001/09/03 12:57:50 petere Exp $
d906 1
a906 1
    WHERE  actors.name LIKE 'W%'
@


1.44
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.43 2001/06/10 03:46:31 momjian Exp $
d271 1
a271 1
   Note that "the first row" of each set is unpredictable
d1000 1
a1000 1
     In the <acronym>SQL92</acronym> standard, the optional keyword "AS"
d1006 1
a1006 1
     in this context.  "AS" is optional in FROM items, however.</para>
@


1.43
log
@Update or remove mentions of versions where appropriate.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.42 2001/05/30 04:32:30 tgl Exp $
d16 1
a16 1
   Retrieves rows from a table or view
@


1.42
log
@Correct obsolete example of FROM-less query.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.41 2001/05/27 09:59:28 petere Exp $
d125 2
a126 2
	but as of <Productname>Postgres</Productname> 7.1 this is the default
	behavior.  (In releases before 7.1, ONLY was the default behavior.)
@


1.41
log
@Make UPDATE and DELETE privileges distinct.  Add REFERENCES and TRIGGER
privileges.  INSERT and COPY FROM now require INSERT (only).  Add
privileges regression test.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.40 2001/03/24 23:03:26 petere Exp $
d953 1
a953 1
SELECT distributors.* WHERE name = 'Westward';
@


1.40
log
@minor copy editing
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.39 2001/03/20 20:54:41 tgl Exp $
d8 1
a8 3
  <refentrytitle id="sql-select-title">
   SELECT
  </refentrytitle>
@


1.39
log
@Recommend CREATE TABLE AS in preference to SELECT INTO.  Remove the
(inadequate anyway) mention of SELECT INTO from the main SELECT ref page.
Point out that SELECT INTO means something else in plpgsql and ecpg.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.38 2001/02/04 12:18:08 petere Exp $
d400 1
a400 1
    (ie, all combined rows that pass its ON condition), plus one copy of each
@


1.38
log
@When making xrefs to refsects, the linkend should point to the refsect and
the endterm to the title element, not both to the title.  At least
docbook2man prefers it that way.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.37 2001/01/13 23:58:55 petere Exp $
d18 1
a18 1
   Retrieve rows from a table or view.
a26 1
    [ INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
a77 33
       </para>
      </listitem>
     </varlistentry>
     
    <varlistentry>
     <term>TEMPORARY</term>
     <term>TEMP</term>
     <listitem>
      <para>
	If TEMPORARY or TEMP is specified,
	the output table is created unique to this session, and is
	automatically dropped on session exit.
      </para>
     </listitem>
    </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">new_table</replaceable></term>
      <listitem>
       <para>
	If the INTO TABLE clause is specified, the result of the
	query will be stored in a new table with the indicated
	name, rather than being returned to the client.
	The target table (<replaceable class="PARAMETER">new_table</replaceable>) will
	be created automatically and must not exist before this command.
        Refer to <command>SELECT INTO</command> for more information.

	<note>
	 <para>
	  The <command>CREATE TABLE AS</command> statement will also
	  create a new  table from a SELECT query.
	 </para>
	</note>
@


1.37
log
@Terminology cleanup: class -> table, instance -> row, attribute -> column,
etc.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.36 2001/01/08 21:30:37 tgl Exp $
d337 1
a337 1
   (See <xref linkend="sql-orderby-title" endterm="sql-orderby-title">.)
@


1.36
log
@Document that we don't support ORDER BY with general expressions on
the output of UNION/INTERSECT/EXCEPT.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.35 2000/12/12 05:07:59 tgl Exp $
d34 1
a34 1
    [ FOR UPDATE [ OF <replaceable class="PARAMETER">class_name</replaceable> [, ...] ] ]
d400 1
a400 1
    from subclasses (inheritance children) of the table.
d402 1
a402 1
    suppress rows from subclasses of the table.  Before
d404 1
a404 1
    this was the default result, and adding subclasses was done
@


1.35
log
@Revise SELECT reference page for outer joins, subselect in FROM,
ISO-compliant UNION/INTERSECT/EXCEPT.  Revise discussion of rule
rewriter to reflect new subselect-in-FROM implementation of views.
Miscellaneous other cleanups.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.34 2000/12/08 20:11:11 momjian Exp $
d619 6
a624 1

@


1.34
log
@Fix Westwood/Westward, from Wessel van Norel.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.33 2000/10/05 19:48:18 momjian Exp $
d22 1
a22 1
   <date>1999-07-20</date>
d26 1
a26 1
    <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
d28 1
a28 1
    [ FROM [ ONLY ]<replaceable class="PARAMETER">table</replaceable> [ <replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]
d30 1
a30 1
    [ GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...] ]
d32 2
a33 2
    [ { UNION [ ALL ] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable> ]
    [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
d36 11
d51 1
a51 1
    <date>2000-03-15</date>
d69 1
a69 1
      <term><replaceable class="PARAMETER">name</replaceable></term>
d72 1
a72 1
	Specifies another name for a column or an expression using
d76 1
a76 1
	<replaceable class="PARAMETER">name</replaceable>
d89 1
a89 1
	the table is created unique to this session, and is
d101 1
a101 1
	name.
d109 1
a109 1
	  create a new  table from a select query.
d117 38
a154 1
      <term><replaceable class="PARAMETER">table</replaceable></term>
d157 6
a162 1
	The name of an existing table referenced by the FROM clause.
d171 6
a176 4
	An alternate name for the preceding
	<replaceable class="PARAMETER">table</replaceable>.
	It is used for brevity or to eliminate ambiguity for joins
	within a single table.
d182 1
a182 1
      <term><replaceable class="PARAMETER">condition</replaceable></term>
d185 5
a189 2
	A boolean expression giving a result of true or false.
	See the WHERE clause.
d195 1
a195 1
      <term><replaceable class="PARAMETER">column</replaceable></term>
d198 10
a207 1
	The name of a table's column.
d213 1
a213 1
      <term><replaceable class="PARAMETER">select</replaceable></term>
d216 3
a218 2
	A select statement with all features except the ORDER BY and
	LIMIT clauses.
d223 10
d273 1
a273 1
   <date>2000-03-15</date>
d284 1
d286 7
a292 5
  <command>ONLY</command> will eliminate rows from subclasses of the table.
  This was previously the default result, and getting subclasses was
  obtained by appending <command>*</command> to the table name.
  The old behaviour is available via the command 
  <command>SET SQL_Inheritance TO OFF;</command>
d341 7
a347 1
   The UNION operator allows the result to be the collection of rows
d349 1
d354 2
a355 1
   The INTERSECT operator gives you the rows that are common to both queries.
d360 1
a360 1
   The EXCEPT operator gives you the rows returned by the first query but
d362 1
d382 89
d522 1
a522 1
GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...]
d539 4
a542 3
    An item in GROUP BY can also be the name or ordinal number of an output
    column (SELECT expression), or it can be an arbitrary expression formed
    from input-column values.  In case of ambiguity, a GROUP BY name will
d558 1
a558 1
HAVING <replaceable class="PARAMETER">cond_expr</replaceable>
d561 1
a561 1
    where <replaceable class="PARAMETER">cond_expr</replaceable> is the same
d568 1
a568 1
    <replaceable class="PARAMETER">cond_expr</replaceable>.
d576 1
a576 1
    <replaceable class="PARAMETER">cond_expr</replaceable> shall unambiguously
d591 1
a591 1
ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...]
d595 4
a598 2
    <replaceable class="PARAMETER">column</replaceable> can be either a
    result column name or an ordinal number.
d601 1
a601 1
    The ordinal numbers refers to the ordinal (left-to-right) position
d632 1
a632 1
    to USING '&lt;' and DESC is equivalent to USING '&gt;'.
d638 1
a638 1
    <date>1998-09-24</date>
d646 2
a647 1
    [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
d652 5
a656 1
    specifies any select expression without an ORDER BY or LIMIT clause.
d660 1
a660 1
    The UNION operator allows the result to be the collection of rows
d668 3
a670 2
    By default, the result of UNION does not contain any duplicate rows
    unless the ALL clause is specified.
d675 6
a680 3
    evaluated left to right.
    Note that the ALL keyword is not global in nature, being 
    applied only for the current pair of table results.
d687 1
a687 1
    <date>1998-09-24</date>
d694 3
a696 2
<replaceable class="PARAMETER">table_query</replaceable> INTERSECT <replaceable class="PARAMETER">table_query</replaceable>
    [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
d701 2
a702 1
    specifies any select expression without an ORDER BY or LIMIT clause.
d706 8
a713 4
    The INTERSECT operator gives you the rows that are common to both queries.
    The two SELECTs that represent the direct operands of the INTERSECT must
    produce the same number of columns, and corresponding columns must be
    of compatible data types.
d719 3
d727 1
a727 1
    <date>1998-09-24</date>
d734 3
a736 2
<replaceable class="PARAMETER">table_query</replaceable> EXCEPT <replaceable class="PARAMETER">table_query</replaceable>
     [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
d741 2
a742 1
    specifies any select expression without an ORDER BY or LIMIT clause.
d746 8
a753 5
    The EXCEPT operator gives you the rows returned by the first query but
    not the second query.
    The two SELECTs that represent the direct operands of the EXCEPT must
    produce the same number of columns, and corresponding columns must be
    of compatible data types.
d755 1
a755 1

d759 1
d967 16
a982 1
was retained from the original PostQuel query language:
d990 20
d1035 1
a1035 1
     renaming columns because the type extensibility features lead to
d1037 1
a1037 1
     in this context.</para>
d1062 1
a1062 1
     UNION Clause
d1065 2
a1066 2
     The <acronym>SQL92</acronym> syntax for UNION allows an
     additional CORRESPONDING BY clause:
@


1.33
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.32 2000/07/22 04:30:27 momjian Exp $
d763 1
a763 1
SELECT distributors.* WHERE name = 'Westwood';
@


1.32
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.31 2000/07/21 18:51:24 momjian Exp $
d324 1
a324 1
    locally-defined operator, 
d587 1
a587 1
    an unpredictable subset of the query's rows --- you may be asking for
@


1.31
log
@More doc cleanups, from book.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.30 2000/06/22 22:31:16 petere Exp $
d309 1
a309 1
    In many cases, this expression will be
@


1.30
log
@Second pass over run-time configuration system. Adjust priorities on some
option settings. Sort out SIGHUP vs BACKEND -- there is no total ordering
here, so make explicit checks. Add comments explaining all of this.
Removed permissions check on SHOW command.

Add examine_subclass to the game, rename to SQL_inheritance to fit the
official data model better. Adjust documentation.

Standalone backend needs to reset all options before it starts. To
facilitate that, have IsUnderPostmaster be set by the postmaster itself,
don't wait for the magic -p switch.

Also make sure that all environment variables and argv's survive
init_ps_display(). Use strdup where necessary.

Have initdb make configuration files (postgresql.conf, pg_hba.conf) mode
0600 -- having configuration files is no fun if you can't edit them.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.29 2000/06/09 01:44:00 momjian Exp $
d35 1
a35 1
    LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]
@


1.29
log
@Inheritance overhaul by  Chris Bitmead <chris@@bitmead.com>
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.28 2000/03/27 17:14:43 thomas Exp $
d211 1
a211 1
  <command>SET EXAMINE_SUBCLASS TO 'on';</command>
@


1.28
log
@Start updating for the v7.0 release.
Use "generic functions" for math and other routines.
Use SQL92 "type 'literal'" syntax rather than Postgres "'literal'::type".
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.27 2000/03/26 18:32:27 petere Exp $
d28 1
a28 1
    [ FROM <replaceable class="PARAMETER">table</replaceable> [ <replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]
d205 7
@


1.27
log
@Updated user's guide to match new psql's output format
Fixed bug in createdb/alternative location
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.26 2000/03/15 23:31:19 tgl Exp $
d422 3
a424 2
    From release 6.4 of PostgreSQL, it is also possible to ORDER BY
    arbitrary expressions, including fields that do not appear in the
d426 1
a426 1
    Thus the following statement is now legal:
d430 1
d586 1
a586 1
    As of PostgreSQL 7.0, the
@


1.26
log
@Tweak GROUP BY so that it will still accept result-column names, but only
after trying to resolve the item as an input-column name.  This allows us
to be compliant with the SQL92 spec for queries that fall within the spec,
while still accepting the same out-of-spec queries as 6.5 did.  You'll only
lose if there is an output column name that is the same as an input
column name, but doesn't refer to the same value.  7.0 will interpret
such a GROUP BY spec differently than 6.5 did.  No way around that, because
6.5 was clearly not spec compliant.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.25 2000/02/21 01:13:52 tgl Exp $
d612 21
a632 20
title                    |did|name            | date_prod|kind
-------------------------+---+----------------+----------+----------
The Third Man            |101|British Lion    |1949-12-23|Drama
The African Queen        |101|British Lion    |1951-08-11|Romantic
Une Femme est une Femme  |102|Jean Luc Godard |1961-03-12|Romantic
Vertigo                  |103|Paramount       |1958-11-14|Action
Becket                   |103|Paramount       |1964-02-03|Drama
48 Hrs                   |103|Paramount       |1982-10-22|Action
War and Peace            |104|Mosfilm         |1967-02-12|Drama
West Side Story          |105|United Artists  |1961-01-03|Musical
Bananas                  |105|United Artists  |1971-07-13|Comedy
Yojimbo                  |106|Toho            |1961-06-16|Drama
There's a Girl in my Soup|107|Columbia        |1970-06-11|Comedy
Taxi Driver              |107|Columbia        |1975-05-15|Action
Absence of Malice        |107|Columbia        |1981-11-15|Action
Storia di una donna      |108|Westward        |1970-08-15|Romantic
The King and I           |109|20th Century Fox|1956-08-11|Musical
Das Boot                 |110|Bavaria Atelier |1981-11-11|Drama
Bed Knobs and Broomsticks|111|Walt Disney     |          |Musical
   </programlisting>
d639 1
a639 1
   <programlisting>
d642 9
a650 8
    kind      |total
    ----------+------
    Action    | 07:34
    Comedy    | 02:58
    Drama     | 14:28
    Musical   | 06:42
    Romantic  | 04:38
   </programlisting>
d658 1
a658 1
   <programlisting>
d664 6
a669 5
    kind      |total
    ----------+------
    Comedy    | 02:58
    Romantic  | 04:38
   </programlisting>
d681 17
a697 16
    did|name
    ---+----------------
    109|20th Century Fox
    110|Bavaria Atelier
    101|British Lion
    107|Columbia
    102|Jean Luc Godard
    113|Luso films
    104|Mosfilm
    103|Paramount
    106|Toho
    105|United Artists
    111|Walt Disney
    112|Warner Bros.
    108|Westward
   </programlisting>
d707 8
a714 8
   <programlisting>
    --        distributors:                actors:
    --        did|name                     id|name
    --        ---+------------             --+--------------
    --        108|Westward                  1|Woody Allen
    --        111|Walt Disney               2|Warren Beatty
    --        112|Warner Bros.              3|Walter Matthau
    --        ...                           ...
d724 9
a732 9
name
--------------
Walt Disney
Walter Matthau
Warner Bros.
Warren Beatty
Westward
Woody Allen
   </programlisting>
d756 3
a758 3
    did|name
    ---+----------------
    108|Westward
@


1.25
log
@Update SELECT documentation to have a more thorough discussion
of LIMIT, and fix a few other glitches too.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.24 2000/01/27 18:11:25 tgl Exp $
d40 1
a40 1
    <date>1998-09-24</date>
d62 6
a67 4
	the AS clause.  This name is primarily used to label the output
	column.  The <replaceable class="PARAMETER">name</replaceable>
	cannot be used in the WHERE, GROUP BY, or HAVING clauses.
	It can, however, be referenced in ORDER BY clauses.
d77 2
a78 1
	The table is created unique to this session, and is
d89 1
a89 1
	query will be stored in another table with the indicated
d92 1
a92 1
	be created automatically and should not exist before this command.
d149 2
a150 1
	A select statement with all features except the ORDER BY clause.
d195 1
a195 1
   <date>1998-09-24</date>
d217 3
a219 1
   duplicates.  Note that "the first row" of each set is unpredictable
d235 1
a235 1
   conceptually into groups.
d240 2
a241 3
   The HAVING clause specifies a grouped table derived by the
   elimination of groups from the result of the previously
   specified clause.
d246 3
a248 3
   The ORDER BY clause allows a user to specify that he/she
   wishes the rows sorted according to the ASCending or 
   DESCending mode operator.
d287 1
a287 1
    <date>1998-09-24</date>
d320 2
a321 3
    The comparison returns either TRUE or FALSE and all
    instances will be discarded
    if the expression evaluates to FALSE.
d327 1
a327 1
    <date>1998-09-24</date>
d341 1
a341 1
    GROUP BY will condense into a single row all rows that share the
d346 2
a347 1
    rows).  When GROUP BY is present, it is not valid to refer to
d351 7
d362 1
a362 1
    <date>1998-09-24</date>
d380 6
a385 2
    of groups from the result of the previously specified clause
    that do not meet the <replaceable class="PARAMETER">cond_expr</replaceable>.</para>
d397 1
a397 1
    <date>1998-09-24</date>
d408 2
a409 2
    <replaceable class="PARAMETER">column</replaceable> can be either a column
    name or an ordinal number.
d413 1
a413 1
    of the column. This feature makes it possible to define an ordering
d416 1
a416 1
    to assign a name to a calculated column using the AS clause, e.g.:
d429 5
d460 1
a460 1
    specifies any select expression without an ORDER BY clause.
d500 1
a500 1
    specifies any select expression without an ORDER BY clause.
d531 1
a531 1
    specifies any select expression without an ORDER BY clause.
d584 1
a584 1
    As of Postgres 7.0, the
d788 12
@


1.24
log
@Redesign DISTINCT ON as discussed in pgsql-sql 1/25/00: syntax is now
SELECT DISTINCT ON (expr [, expr ...]) targetlist ...
and there is a check to make sure that the user didn't specify an ORDER BY
that's incompatible with the DISTINCT operation.
Reimplement nodeUnique and nodeGroup to use the proper datatype-specific
equality function for each column being compared --- they used to do
bitwise comparisons or convert the data to text strings and strcmp().
(To add insult to injury, they'd look up the conversion functions once
for each tuple...)  Parse/plan representation of DISTINCT is now a list
of SortClause nodes.
initdb forced by querytree change...
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.23 1999/12/13 17:39:38 tgl Exp $
d33 3
a35 3
    [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
    [ FOR UPDATE [ OF class_name... ] ]
    [ LIMIT { count | ALL } [ { OFFSET | , } count ] ]
d62 4
a65 4
	the AS clause. <replaceable class="PARAMETER">name</replaceable>
	cannot be used in the WHERE
	condition. It can, however, be referenced in associated
	ORDER BY or GROUP BY clauses.
d248 1
a248 1
   The UNION clause allows the result to be the collection of rows
d254 1
a254 1
   The INTERSECT give you the rows that are common to both queries.
d259 2
a260 1
   The EXCEPT give you the rows in the upper query not in the lower query.
d270 3
a272 2
   The LIMIT clause allows control over which rows are
   returned by the query.
d400 1
a400 2
    assign a name
    to a calculated column using the AS clause, e.g.:
d406 3
a408 2
    From release 6.4 of PostgreSQL, the columns in the ORDER BY clause
    do not need to appear in the SELECT clause.
d418 3
a420 1
    If not specified, ASC is assumed by default.
d443 4
a446 4
    The UNION clause allows the result to be the collection of rows
    returned by the queries involved. (See UNION clause).
    The two tables that represent the direct operands of the UNION must
    have the same number of columns, and corresponding columns must be
d483 3
a485 4
    The INTERSECT clause allows the result to be all rows that are 
    common to the involved queries.
    The two tables that represent the direct operands of the INTERSECT must
    have the same number of columns, and corresponding columns must be
d491 1
a491 1
    evaluated left to right.
d514 4
a517 4
    The EXCEPT clause allows the result to be rows from the upper query
    that are not in the lower query.  (See EXCEPT clause).
    The two tables that represent the direct operands of the EXCEPT must
    have the same number of columns, and corresponding columns must be
d523 50
a572 1
    evaluated left to right.
d679 1
a679 1
   with letter W in each table.  Only distinct rows are to be used, so the
a764 8
     In the <acronym>SQL92</acronym> standard, the new column name 
     specified in an
     "AS" clause may be referenced in GROUP BY and HAVING clauses.
     This is not currently
     allowed in <productname>Postgres</productname>.
    </para>
     
    <para>
d766 1
@


1.23
log
@Update documentation to reflect availability of aggregate(DISTINCT).
Try to provide a more lucid discussion in 'Using Aggregate Functions'
tutorial section.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.22 1999/08/06 13:50:31 thomas Exp $
d25 1
a25 1
SELECT [ ALL | DISTINCT [ ON <replaceable class="PARAMETER">column</replaceable> ] ]
d204 1
a204 1
   <command>DISTINCT</command> will eliminate all duplicate rows from the
d206 1
a206 5
   <command>DISTINCT ON <replaceable class="PARAMETER">column</replaceable></command>
   will eliminate all duplicates in the specified column; this is
   similar to using
   <command>GROUP BY <replaceable class="PARAMETER">column</replaceable></command>.
   <command>ALL</command> will return all candidate rows,
d208 17
@


1.22
log
@Fix markup to allow clean man pages.
Add new pages for programming languages and tcl shells.
@
text
@d2 1
a2 1
$Header: /opt/postgres/cvs/pgsql/doc/src/sgml/ref/select.sgml,v 1.21 1999/07/22 15:09:14 thomas Exp $
d205 1
a205 1
   selection.
d208 1
a208 1
   equivalent to using
d323 7
a329 5
    same values for the
    grouped columns; aggregates return values derived from all rows
    that make up the group.  The value returned for an ungrouped
    and unaggregated column is dependent on the order in which rows
    happen to be read from the database.
d359 2
a360 1
    reference a grouping column.
@


1.21
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d200 1
a200 1
   (See <xref linkend="where-title" endterm="where-title">.)
d217 1
a217 1
   (See <xref linkend="group-by-title" endterm="group-by-title">.)
d224 1
a224 1
   (See <xref linkend="having-title" endterm="having-title">.)
d231 1
a231 1
   (See <xref linkend="order-by-title" endterm="order-by-title">.)
d237 1
a237 1
   (See <xref linkend="union-title" endterm="union-title">.)
d242 1
a242 1
   (See <xref linkend="intersect-title" endterm="intersect-title">.)
d247 1
a247 1
   (See <xref linkend="except-title" endterm="except-title">.)
d265 1
a265 1
  <refsect2 id="R2-SQL-WHERE-2">
d269 1
a269 1
   <title id="where-title">
d306 1
a306 1
  <refsect2 id="R2-SQL-GROUPBY-2">
d310 1
a310 1
   <title id="group-by-title">
d331 1
a331 1
  <refsect2 id="R2-SQL-HAVING-2">
d335 1
a335 1
   <title id="having-title">
d361 1
a361 1
  <refsect2 id="R2-SQL-ORDERBYCLAUSE-2">
d365 1
a365 1
   <title id="order-by-title">
d404 1
a404 1
  <refsect2 id="R2-SQL-UNION-2">
d408 1
a408 1
   <title id="union-title">
d444 1
a444 1
  <refsect2 id="R2-SQL-INTERSECT-2">
d448 1
a448 1
   <title id="intersect-title">
d476 1
a476 1
  <refsect2 id="R2-SQL-EXCEPT-2">
d480 1
a480 1
   <title id="except-title">
@


1.20
log
@Fix conflicting id tags (sql.sgml also used "select-title").
@
text
@d1 5
d22 1
a22 1
   <date>1998-09-24</date>
d272 1
d277 1
a277 1
WHERE <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">ETER">c</replaceable>e<replaceable class="PARAMETER">"PAR</replaceable>replaceable> [ <replaceable class="PARAMETER">log_op</replaceable> ... ]
d280 17
a296 3
    where <replaceable class="PARAMETER">cond_op</replaceable> can be
    one of: =, &lt;, &lt;=, &gt;, &gt;= or &lt;&gt;,
    a conditional operator like ALL, ANY, IN, LIKE, et cetera or a
a646 2
  <para>
  </para>
@


1.19
log
@Add id label to allow cross referencing.
@
text
@d3 1
a3 1
  <refentrytitle id="select-title">
@


1.18
log
@Complete first pass at markup adjustments for docbook2man man pages.
Add some internal cross references to select.sgml.
@
text
@d3 1
a3 1
  <refentrytitle>
d251 1
a251 1
   The LIMIT...OFFSET clause allows control over which rows are
@


1.17
log
@Minor updates for release.
Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml
 (the emacs parser) to handle parsing.
@
text
@d4 1
a4 1
SELECT
d10 1
a10 1
SELECT
d20 4
a23 6
SELECT [ALL|DISTINCT [ON <replaceable class="PARAMETER">column</replaceable>] ]
    <replaceable class="PARAMETER">expression</replaceable> [ AS
   <replaceable class="PARAMETER">name</replaceable> ] [, ...]
    [ INTO [TEMP] [TABLE] <replaceable class="PARAMETER">new_table</replaceable> ]
    [ FROM <replaceable class="PARAMETER">table</replaceable>
   [<replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]
d27 1
a27 2
    [ { UNION [ALL] | INTERSECT | EXCEPT } <replaceable
    class="PARAMETER">select</replaceable> ]
d29 2
a30 2
    [ FOR UPDATE [OF class_name...]]
    [ LIMIT count [OFFSET|, count]]
d40 1
a40 1
   
d44 1
a44 3
      <term>
       <replaceable class="PARAMETER">expression</replaceable>
      </term>
d53 1
a53 3
      <term>
       <replaceable class="PARAMETER">name</replaceable>
      </term>
d66 2
a67 3
     <term>
     TEMP
     </term>
d77 1
a77 3
      <term>
       <replaceable class="PARAMETER">new_table</replaceable>
      </term>
d98 1
a98 3
      <term>
       <replaceable class="PARAMETER">table</replaceable>
      </term>
d107 1
a107 3
      <term>
       <replaceable class="PARAMETER">alias</replaceable>
      </term>
d119 1
a119 3
      <term>
       <replaceable class="PARAMETER">condition</replaceable>
      </term>
d129 1
a129 3
      <term>
       <replaceable class="PARAMETER">column</replaceable>
      </term>
d138 1
a138 3
      <term>
       <replaceable class="PARAMETER">select</replaceable>
      </term>
d158 22
a179 24
	
	<variablelist>
	 <varlistentry>
	  <term>
	   Rows
	  </term>
	  <listitem>
	   <para>
		The complete set of rows resulting from the query specification.
	   </para>
	  </listitem>
	 </varlistentry>
	 
	 <varlistentry>
	  <term>
	   <returnvalue><replaceable>count</replaceable></returnvalue>
	  </term>
	  <listitem>
	   <para>
		The count of rows returned by the query.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
d183 1
a183 1
 
d194 4
a197 1
   if WHERE is omitted, all rows are candidates.</para>
d201 7
a207 4
   <command>DISTINCT ON <replaceable class="PARAMETER">column</replaceable></command> will eliminate all duplicates in the specified column; this is
equivalent to using <command>GROUP BY <replaceable
     class="PARAMETER">column</replaceable></command>.  <command>ALL</command> will return all candidate rows,
including duplicates.</para>
d211 4
a214 2
   conceptually into groups. (See GROUP BY clause).</para>
   
d218 3
a220 1
   specified clause. (See HAVING clause).</para>
d225 3
a227 1
   DESCending mode operator. (See ORDER BY clause)</para>
d231 3
a233 1
   returned by the queries involved. (See UNION clause).</para>
d237 2
a238 1
   (See INTERSECT clause).</para>
d242 2
a243 1
   (See EXCEPT clause).</para>
d248 1
a248 1
   (See EXCEPT clause).</para>
d252 2
a253 1
   returned by the query.</para>   
d257 2
a258 2
   (See <command>GRANT</command>/<command>REVOKE</command> statements).
</para>
d264 1
a264 1
   <title>
d271 1
a271 3
WHERE <replaceable class="PARAMETER">expr</replaceable> <replaceable
class="PARAMETER">ETER">c</replaceable>e<replaceable class="PARAMETER">"PAR</replaceable>replaceable> [ <replaceable
class="PARAMETER">log_op</replaceable> ... ]
d290 1
a290 1
   <title>
d298 13
a310 8
    </synopsis></para>
    <para>
     GROUP BY will condense into a single row all rows that share the same values for the
     grouped columns; aggregates return values derived from all rows that make up the group.  The value returned for an ungrouped
     and unaggregated column is dependent on the order in which rows happen to be read from the database.
    </para>
</refsect2>
    
d315 1
a315 1
   <title>
d326 2
a327 1
    as specified for the WHERE clause.</para>
d333 1
a333 1
    
d336 1
a336 1
<replaceable class="PARAMETER">cond_expr</replaceable> shall unambiguously
d345 1
a345 1
   <title>
d355 2
a356 1
    name or an ordinal number.</para>
d369 2
a370 1
    From release 6.4 of PostgreSQL, the columns in the ORDER BY clause do not need to appear in the SELECT clause.
d374 2
a375 1
    </programlisting></para>
d380 2
a381 1
    If not specified, ASC is assumed by default.</para>
d388 1
a388 1
   <title>
d393 2
a394 3
<replaceable class="PARAMETER">table_query</replaceable> UNION [ ALL ]
<replaceable class="PARAMETER">table_query</replaceable>
     [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
d396 1
a396 1
    
d399 2
a400 1
    specifies any select expression without an ORDER BY clause.</para>
d407 2
a408 1
    of compatible data types.</para>
d412 2
a413 1
    unless the ALL clause is specified.</para>
d419 3
a421 2
    applied only for the current pair of table results.</para>
    
d428 1
a428 1
   <title>
d433 2
a434 3
<replaceable class="PARAMETER">table_query</replaceable> INTERSECT
<replaceable class="PARAMETER">table_query</replaceable>
     [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
d439 3
a441 2
    specifies any select expression without an ORDER BY clause.</para>
    
d444 1
a444 1
    common to the involved queries.  (See INTERSECT clause).
d447 2
a448 1
    of compatible data types.</para>
d453 1
a453 2
    </para>
    
d460 1
a460 1
   <title>
d465 1
a465 2
<replaceable class="PARAMETER">table_query</replaceable> EXCEPT
     <replaceable class="PARAMETER">table_query</replaceable>
d471 3
a473 2
    specifies any select expression without an ORDER BY clause.</para>
    
d479 3
a481 2
    of compatible data types.</para>
    
d485 1
a485 2
    </para>
    
d487 1
a488 2
</refsect1>
  
d493 1
d497 2
a498 2
  </para>
  <programlisting>
d522 3
a524 1
  </programlisting>
d528 2
a529 2
  </para>
  <programlisting>
d539 2
a540 1
  </programlisting>
d546 2
a547 2
  </para>
  <programlisting>
d557 3
a559 1
  </programlisting>
d561 1
a561 1
    The following two examples are identical ways of sorting the individual
d564 2
a565 2
  </para>
  <programlisting>
d584 2
a585 1
  </programlisting>
d593 2
a594 2
  </para>
  <programlisting>
d619 2
a620 2
  </programlisting>
  
d720 1
a720 1
sgml-omittag:
@


1.16
log
@Add mention of FOR UPDATE and LIMIT/OFFSET>
@
text
@d21 2
a22 1
    <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
d24 2
a25 1
    [ FROM <replaceable class="PARAMETER">table</replaceable> [<replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]
d29 2
a30 1
    [ { UNION [ALL] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable> ]
d72 2
a73 2
    <VARLISTENTRY>
     <TERM>
d75 3
a77 3
     </TERM>
     <LISTITEM>
      <PARA>
d80 3
a82 3
      </PARA>
     </LISTITEM>
    </VARLISTENTRY>
d221 2
a222 1
equivalent to using <command>GROUP BY <replaceable class="PARAMETER">column</replaceable></command>.  <command>ALL</command> will return all candidate rows,
d276 3
a278 1
WHERE <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">cond_op</replaceable> <replaceable class="PARAMETER">expr</replaceable> [ <replaceable class="PARAMETER">log_op</replaceable> ... ]
d390 2
a391 1
<replaceable class="PARAMETER">table_query</replaceable> UNION [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
d427 2
a428 1
<replaceable class="PARAMETER">table_query</replaceable> INTERSECT <replaceable class="PARAMETER">table_query</replaceable>
d459 2
a460 1
<replaceable class="PARAMETER">table_query</replaceable> EXCEPT <replaceable class="PARAMETER">table_query</replaceable>
d497 19
a515 19
    title                    |did|name            | date_prod|kind
    -------------------------+---+----------------+----------+----------
    The Third Man            |101|British Lion    |1949-12-23|Drama
    The African Queen        |101|British Lion    |1951-08-11|Romantic
    Une Femme est une Femme  |102|Jean Luc Godard |1961-03-12|Romantic
    Vertigo                  |103|Paramount       |1958-11-14|Action
    Becket                   |103|Paramount       |1964-02-03|Drama
    48 Hrs                   |103|Paramount       |1982-10-22|Action
    War and Peace            |104|Mosfilm         |1967-02-12|Drama
    West Side Story          |105|United Artists  |1961-01-03|Musical
    Bananas                  |105|United Artists  |1971-07-13|Comedy
    Yojimbo                  |106|Toho            |1961-06-16|Drama
    There's a Girl in my Soup|107|Columbia        |1970-06-11|Comedy
    Taxi Driver              |107|Columbia        |1975-05-15|Action
    Absence of Malice        |107|Columbia        |1981-11-15|Action
    Storia di una donna      |108|Westward        |1970-08-15|Romantic
    The King and I           |109|20th Century Fox|1956-08-11|Musical
    Das Boot                 |110|Bavaria Atelier |1981-11-11|Drama
    Bed Knobs and Broomsticks|111|Walt Disney     |          |Musical
d599 8
a606 8
    name
    --------------
    Walt Disney
    Walter Matthau
    Warner Bros.
    Warren Beatty
    Westward
    Woody Allen
a704 75
<refentry id="SQL-SELECTINTO">
 <refmeta>
  <refentrytitle>
SELECT INTO
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
SELECT INTO
  </refname>
  <refpurpose>
Create a new table from an existing table or view
  </refpurpose></refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1998-09-22</date>
  </refsynopsisdivinfo>
  <synopsis>
SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
    INTO [TEMP] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
    [ FROM <replaceable class="PARAMETER">table</replaceable> [<replaceable class="PARAMETER">alias</replaceable>] [, ...] ]
    [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
    [ GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...] ]
    [ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
    [ { UNION [ALL] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable>]
    [ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
    [ FOR UPDATE [OF class_name...]]
    [ LIMIT count [OFFSET|, count]]
  </synopsis>
  
  <refsect2 id="R2-SQL-SELECTINTO-1">
   <refsect2info>
    <date>1998-09-22</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
All input fields are described in detail for SELECT.
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-SELECTINTO-2">
   <refsect2info>
    <date>1998-09-22</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
All output fields are described in detail for SELECT.
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-SELECTINTO-1">
  <refsect1info>
   <date>1998-09-22</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   SELECT INTO creates a new table from the results of a query. Typically, this
   query draws data from an existing table, but any SQL query is allowed.
   <note>
	<para>
	 CREATE TABLE AS is functionally equivalent to the SELECT INTO command.
	</para>
   </note>
  </para>
 </refsect1>
</refentry>

d708 1
a708 1
sgml-omittag:t
@


1.15
log
@Minor wording change.
@
text
@d29 2
d248 9
d723 2
@


1.14
log
@Update man page for select
@
text
@d88 4
a91 3
        The <replaceable class="PARAMETER">new_table</replaceable> will
        be created automatically and should not exist before this command.
	Refer to <command>SELECT INTO</command> for more information.
@


1.13
log
@Fix markup to include all closing tags.
Required by newest versions of DocBook and style sheets.
@
text
@d88 2
a89 2
	If <replaceable class="PARAMETER">new_table</replaceable> does
	not exist, it will be created automatically.
@


1.12
log
@Add EXCEPT/INTERSECT doc changes.
@
text
@d216 2
a217 2
including duplicates.
   
@


1.11
log
@More complete info from Oliver Elphick.
@
text
@d27 1
a27 1
    [ UNION [ALL] <replaceable class="PARAMETER">select</replaceable> ]
d233 10
a242 2
   The UNION clause specifies a table derived from a Cartesian
   product union join. (See UNION clause).</para>
d381 2
a382 1
    The UNION operator specifies a table derived from a Cartesian product.
d393 1
a393 1
evaluated left to right.
d395 47
a441 1
applied only for the current pair of table results.</para>
d443 19
a461 1
  </refsect2></refsect1>
d709 1
a709 1
    [ UNION [ ALL ] <replaceable class="PARAMETER">select</replaceable>]
@


1.10
log
@Add TEMP tables/indexes.  Add COPY pfree().  Other cleanups.
@
text
@d208 9
a216 3
   <command>SELECT</command> will get all rows which satisfy the
 WHERE condition
   or all rows of a table if WHERE is omitted.</para>
d256 3
a258 2
    one of: =, &lt;, &lt;=, &gt;, &gt;=, &lt;&gt;
    or a conditional operator like ALL, ANY, IN, LIKE, et cetera
d276 1
a276 1
    of the this clause:
d279 7
a285 1
    </synopsis></para></refsect2>
d343 2
a344 2
    The columns in the ORDER BY must appear in the SELECT clause.
    Thus the following statement is illegal:
d425 1
a425 1
   the reults by <literal>kind</literal>:
d441 1
a441 1
   the reults by <literal>kind</literal> and show those group totals
d578 4
@


1.9
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d22 1
a22 1
    [ INTO [TABLE] <replaceable class="PARAMETER">new_table</replaceable> ]
d67 12
d614 1
a614 1
    INTO [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
@


1.8
log
@Include example of Postgres' extended query syntax which allow one to omit
 the FROM clause. e.g. "SELECT table.*".
@
text
@d159 26
a184 23
<para>

   <variablelist>
    <varlistentry>
     <term>
      Rows
     </term>
     <listitem>
      <para>
       The complete set of rows resulting from the query specification.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <returnvalue><replaceable>count</replaceable></returnvalue>
     </term>
     <listitem>
      <para>
       The count of rows returned by the query.
   </variablelist>
   
d519 1
d620 2
d632 3
d636 16
a651 15
  <refsect1 id="R1-SQL-SELECTINTO-1">
   <refsect1info>
    <date>1998-09-22</date>
   </refsect1info>
   <title>
    Description
   </title>
   <para>
SELECT INTO creates a new table from the results of a query. Typically, this
query draws data from an existing table, but any SQL query is allowed.
<note>
<para>
CREATE TABLE AS is functionally equivalent to the SELECT INTO command.
</note>

@


1.7
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d501 21
@


1.6
log
@SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
@
text
@d4 1
a4 1
   SELECT
d10 1
a10 1
   SELECT
a174 8
      <replaceable>status</replaceable>
     </term>
     <listitem>
      <para>

   <variablelist>
    <varlistentry>
     <term>
a179 4
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
d560 1
a560 1
   SELECT INTO
d566 1
a566 1
   SELECT INTO
d569 1
a569 1
   Create a new table from an existing table or view
@


1.5
log
@Add new SQL reference page and the first utility/app reference page
 converted from the man page.
@
text
@d20 1
a20 1
SELECT [ALL|DISTINCT]
@


1.4
log
@Cleanup markup and minor editing to prepare for first release.
@
text
@d572 1
a572 1
   SELECT
@


1.3
log
@Minor wording and formatting cleanups.
@
text
@d17 1
a17 1
   <date>1998-09-06</date>
d21 8
a28 8
    <replaceable class="PARAMETER">expression</replaceable> [AS <replaceable class="PARAMETER">name</replaceable>] [, ...]
    [INTO [TABLE] <replaceable class="PARAMETER">intable</replaceable>]
    [FROM <replaceable class="PARAMETER">table</replaceable> [<replaceable class="PARAMETER">alias</replaceable>] [, ...] ]
    [WHERE <replaceable class="PARAMETER">condition</replaceable>]
    [GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...] ]
    [HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
    [UNION [ALL] <replaceable class="PARAMETER">select</replaceable>]
    [ORDER BY <replaceable class="PARAMETER">column</replaceable> [ASC | DESC] [, ...] ]
d33 1
a33 1
    <date>1998-09-06</date>
d69 1
a69 1
       <replaceable class="PARAMETER">intable</replaceable>
d76 1
a76 1
	If <replaceable class="PARAMETER">intable</replaceable> does
d78 1
a78 1
	
d154 1
a154 1
    <date>1998-09-06</date>
d159 2
d175 9
a183 1
      <returnvalue>count</returnvalue>
d192 1
d199 1
a199 1
   <date>1998-09-06</date>
d205 2
a206 1
   SELECT will get all rows which satisfy the WHERE condition
d229 2
a230 1
   (See GRANT/REVOKE statements).</para>
d234 1
a234 1
    <date>1998-09-06</date>
d237 1
a237 1
    WHERE clause
d243 1
a243 1
WHERE <replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">cond_op</replaceable> <replaceable class="PARAMETER">expr</replaceable> [<replaceable class="PARAMETER">log_op</replaceable> ...]
d259 1
a259 1
    <date>1998-09-06</date>
d262 1
a262 1
    GROUP BY clause
d268 1
a268 1
     GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...]
d273 1
a273 1
    <date>1998-09-06</date>
d276 1
a276 1
    HAVING clause
d294 2
a295 1
    Each column referenced in <replaceable class="PARAMETER">cond_expr</replaceable> shall unambiguously
d302 1
a302 1
    <date>1998-09-06</date>
d305 1
a305 1
    ORDER BY clause
d309 1
a309 1
ORDER BY <replaceable class="PARAMETER">column</replaceable> [ASC | DESC] [, ...]
d319 2
a320 1
    This is never absolutely necessary because it is always possible assign a name
d323 1
a323 1
     SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
d330 1
a330 1
     SELECT name FROM distributors ORDER BY code;
d341 1
a341 1
    <date>1998-09-06</date>
d344 1
a344 1
    UNION clause
d348 2
a349 2
<replaceable class="PARAMETER">table_query</replaceable> UNION [ALL] <replaceable class="PARAMETER">table_query</replaceable>
     [ORDER BY <replaceable class="PARAMETER">column</replaceable> [ASC | DESC] [, ...] ]
d367 4
a370 3
    Multiple UNION operators in the same SELECT statement are evaluated left to right.
    Note that the ALL keyword is not global in nature, being applied only for the current pair of
    table results.</para>
d383 3
a385 3
    SELECT f.title, f.did, d.name, f.date_prod, f.kind
        FROM distributors d, films f
        WHERE f.did = d.did
d412 1
a412 1
    SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
d429 4
a432 4
    SELECT kind, SUM(len) AS total
        FROM films
        GROUP BY kind
        HAVING SUM(len) < INTERVAL '5 hour';
d445 2
a446 2
    SELECT * FROM distributors ORDER BY name;
    SELECT * FROM distributors ORDER BY 2;
d481 1
a481 1
    SELECT distributors.name
d484 4
a487 4
    UNION
           SELECT actors.name
           FROM   actors
           WHERE  actors.name LIKE 'W%'
d510 1
a510 1
    <date>1998-09-06</date>
d523 1
a523 1
     SELECT clause
d545 1
a545 1
     <date>1998-09-06</date>
d548 1
a548 1
     UNION clause
d566 67
@


1.2
log
@Add new files from Oliver and Thomas.
@
text
@d1 19
a19 21
<REFENTRY ID="SQL-SELECT-1">
<REFMETA>
<REFENTRYTITLE>
SELECT
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
SELECT
</REFNAME>
<REFPURPOSE>
Retrieve rows from a table or view
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
d21 173
a193 171
    <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [AS <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>] [, ...]
    [INTO [TABLE] <REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE>]
    [FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [<REPLACEABLE CLASS="PARAMETER">alias</REPLACEABLE>] [, ...] ]
    [WHERE <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>]
    [GROUP BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ]
    [HAVING <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> [, ...] ]
    [UNION [ALL] <REPLACEABLE CLASS="PARAMETER">select</REPLACEABLE>]
    [ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...] ]
</SYNOPSIS>

<REFSECT2 ID="R2-SQL-SELECT-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>

<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
          The name of a table's column or an expression.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
          Specifies another name for a column or an expression using
          the AS clause. <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> cannot be used in the WHERE
          condition. It can, however, be referenced in associated
          ORDER BY or GROUP BY clauses.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
          If the INTO TABLE clause is specified, the result of the
          query will be stored in another table with the indicated
          name.
If <REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE> does not exist, it will be created automatically.

<Note>
<Para>
The CREATE TABLE AS statement will also create a new table from a select query.
</Para>
</Note>
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
          The name of an existing table referenced by FROM clause.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">alias</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An alternate name for the preceeding <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
Used for brevity or to eliminate ambiguity for joins within a single table.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An expression leading to a boolean (true/false) result.
See the WHERE clause.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
          The name of a table's column.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">select</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A select statement with all features except the ORDER BY clause.
</PARA>
</LISTITEM>
</VARLISTENTRY>

</VARIABLELIST>
</PARA>
</REFSECT2>

<REFSECT2 ID="R2-SQL-SELECT-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
   Rows
</TERM>
<LISTITEM>
<PARA>
The complete set of rows resulting from the query specification.
</PARA>
</LISTITEM>
</VARLISTENTRY>

<VARLISTENTRY>
<TERM>
<ReturnValue>count</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The count of rows returned by the query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>

</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-SQL-SELECT-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
SELECT is the principal means to access information
 in <productname>Postgres</productname>.

d195 3
a197 3
   or all rows of a table if WHERE is omitted.

<PARA>
d199 3
a201 2
   conceptually into groups. (See GROUP BY clause).

d204 3
a206 2
   specified clause. (See HAVING clause).

d209 3
a211 2
   DESCending mode operator. (See ORDER BY clause)

d213 3
a215 3
   product union join. (See UNION clause).

<PARA>
d217 35
a251 33
   (See GRANT/REVOKE statements).

<REFSECT2 ID="R2-SQL-WHERE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
WHERE clause
</TITLE>
<PARA>
         The optional WHERE condition has the general form:

<Synopsis>
WHERE <REPLACEABLE CLASS="PARAMETER">expr</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">cond_op</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">expr</REPLACEABLE> [<REPLACEABLE CLASS="PARAMETER">log_op</REPLACEABLE> ...]
</Synopsis>

         where <REPLACEABLE CLASS="PARAMETER">cond_op</REPLACEABLE> can be one of: =, &lt;, &lt;=, &gt;, &gt;=, &lt;&gt;
         or a conditional operator like ALL, ANY, IN, LIKE, et cetera
         and <REPLACEABLE CLASS="PARAMETER">log_op</REPLACEABLE> can be one of: AND, OR, NOT.
         The comparison returns either TRUE or FALSE and all
         instances will be discarded
         if the expression evaluates to FALSE.
</PARA>
</REFSECT2>

<REFSECT2 ID="R2-SQL-GROUPBY-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
GROUP BY clause
</TITLE>
<PARA>
d254 22
a275 22
<SYNOPSIS>
GROUP BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...]
</SYNOPSIS>

<REFSECT2 ID="R2-SQL-HAVING-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
HAVING clause
</TITLE>
<PARA>
         The optional HAVING condition has the general form:

<Synopsis>
HAVING <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE>
</Synopsis>

         where <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE> is the same
as specified for the WHERE clause.

<Para>
d278 4
a281 4
    that do not meet the <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE>.

<Para>
    Each column referenced in <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE> shall unambiguously
d283 19
a301 19
</PARA>
</REFSECT2>

<REFSECT2 ID="R2-SQL-ORDERBYCLAUSE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
ORDER BY clause
</TITLE>
<PARA>
<Synopsis>
ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...]
</Synopsis>

<PARA>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> can be either a column
name or an ordinal number.
<PARA>
d307 5
a311 5
<ProgramListing>
SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
</ProgramListing>

<PARA>
d314 5
a318 5
<ProgramListing>
SELECT name FROM distributors ORDER BY code;
</ProgramListing>

<PARA>
d321 46
a366 46
    If not specified, ASC is assumed by default.
</REFSECT2>

<REFSECT2 ID="R2-SQL-UNION-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
UNION clause
</TITLE>
<PARA>
<Synopsis>
<REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE> UNION [ALL] <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
    [ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...] ]
</Synopsis>

where
   <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
         specifies any select expression without an ORDER BY clause.

<PARA>
   The UNION operator specifies a table derived from a Cartesian product.
   The two tables that represent the direct operands of the UNION must
   have the same number of columns, and corresponding columns must be
   of compatible data types.

<PARA>
   By default, the result of UNION does not contain any duplicate rows
   unless the ALL clause is specified.

<Para>
Multiple UNION operators in the same SELECT statement are evaluated left to right.
Note that the ALL keyword is not global in nature, being applied only for the current pair of
table results.

</REFSECT2>

<REFSECT1 ID="R1-SQL-SELECT-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
    --Join table films with their distributors:
    --
d369 1
a369 1
        WHERE f.did = d.did;
d390 6
a395 5
</ProgramListing>
    
<ProgramListing>
    --sum column "len" of all films group by "kind":
    --
d405 1
a405 1
</ProgramListing>
d407 6
a412 4
<ProgramListing>
    --sum column length of all films group by "kind"
    --having total duration < 5 hours:
    --
d422 7
a428 5
</ProgramListing>

<ProgramListing>
    --The following two examples are identicals:
    --
d447 1
a447 1
</ProgramListing>
d449 9
a457 5
<ProgramListing>
    --union of table distributors and table actors:
    -- (only those that begin with letter W):
    --
    -- distributors:                     actors:
d464 1
a464 3
    --
    --select only distinct rows (without ALL):
    --
d471 1
a471 1
           WHERE  actors.name LIKE 'W%';
d481 87
a567 84
</ProgramListing>

</REFSECT1>

<REFSECT1 ID="R1-SQL-SELECT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>

<REFSECT2 ID="R2-SQL-SELECT-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
<Acronym>SQL92</Acronym>
</TITLE>
<PARA>
</PARA>

<REFSECT3 ID="R3-SQL-SELECT-1">
<REFSECT3INFO>
<DATE>1998-04-15</DATE>
</REFSECT3INFO>
<TITLE>
SELECT clause
</TITLE>
<PARA>
In the <Acronym>SQL92</Acronym> standard, the optional keyword "AS" is just noise and can be 
omitted without affecting the meaning.
The <ProductName>Postgres</ProductName> parser requires this keyword when
renaming columns because the type extensibility features lead to parsing ambiguities
in this context.

<PARA>
In the <Acronym>SQL92</Acronym> standard, the new column name specified in an
"AS" clause may be referenced in GROUP BY and HAVING clauses. This is not currently
allowed in <ProductName>Postgres</ProductName>.
</PARA>
</REFSECT3>

<REFSECT3 ID="R3-SQL-UNION-1">
<REFSECT3INFO>
<DATE>1998-04-15</DATE>
</REFSECT3INFO>
<TITLE>
UNION clause
</TITLE>
<PARA>
The <Acronym>SQL92</Acronym> syntax for UNION allows an additional CORRESPONDING BY clause:
<Synopsis> 
<REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE> UNION [ALL]
    [CORRESPONDING [BY (<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [,...])]]
    <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
</Synopsis>

<Para>
The CORRESPONDING BY clause is not supported by <ProductName>Postgres</ProductName>.
</PARA>
</REFSECT3>

</REFSECT2>
</REFSECT1>
</REFENTRY>

<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
@


1.1
log
@First files for reference pages.
@
text
@d191 3
a200 1
<PARA>
a204 1
<PARA>
a208 1
<PARA>
@
