← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/index-catalog.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/index-catalog.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Catalog Entries for Indexes</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Index Access Method Interface Definition"
 
16
HREF="indexam.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Index Access Method Interface Definition"
 
19
HREF="indexam.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Index Access Method Functions"
 
22
HREF="index-functions.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Index Access Method Interface Definition"
 
57
HREF="indexam.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="Index Access Method Interface Definition"
 
67
HREF="indexam.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 52. Index Access Method Interface Definition</TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Index Access Method Interface Definition"
 
81
HREF="indexam.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="Index Access Method Functions"
 
90
HREF="index-functions.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="SECT1"
 
101
><H1
 
102
CLASS="SECT1"
 
103
><A
 
104
NAME="INDEX-CATALOG"
 
105
>52.1. Catalog Entries for Indexes</A
 
106
></H1
 
107
><P
 
108
>   Each index access method is described by a row in the
 
109
   <TT
 
110
CLASS="STRUCTNAME"
 
111
>pg_am</TT
 
112
> system catalog (see
 
113
   <A
 
114
HREF="catalog-pg-am.html"
 
115
>Section 45.3</A
 
116
>).  The principal contents of a
 
117
   <TT
 
118
CLASS="STRUCTNAME"
 
119
>pg_am</TT
 
120
> row are references to
 
121
   <A
 
122
HREF="catalog-pg-proc.html"
 
123
><TT
 
124
CLASS="STRUCTNAME"
 
125
>pg_proc</TT
 
126
></A
 
127
>
 
128
   entries that identify the index access
 
129
   functions supplied by the access method.  The APIs for these functions
 
130
   are defined later in this chapter.  In addition, the
 
131
   <TT
 
132
CLASS="STRUCTNAME"
 
133
>pg_am</TT
 
134
> row specifies a few fixed properties of
 
135
   the access method, such as whether it can support multicolumn indexes.
 
136
   There is not currently any special support
 
137
   for creating or deleting <TT
 
138
CLASS="STRUCTNAME"
 
139
>pg_am</TT
 
140
> entries;
 
141
   anyone able to write a new access method is expected to be competent
 
142
   to insert an appropriate row for themselves.
 
143
  </P
 
144
><P
 
145
>   To be useful, an index access method must also have one or more
 
146
   <I
 
147
CLASS="FIRSTTERM"
 
148
>operator families</I
 
149
> and
 
150
   <I
 
151
CLASS="FIRSTTERM"
 
152
>operator classes</I
 
153
> defined in
 
154
   <A
 
155
HREF="catalog-pg-opfamily.html"
 
156
><TT
 
157
CLASS="STRUCTNAME"
 
158
>pg_opfamily</TT
 
159
></A
 
160
>,
 
161
   <A
 
162
HREF="catalog-pg-opclass.html"
 
163
><TT
 
164
CLASS="STRUCTNAME"
 
165
>pg_opclass</TT
 
166
></A
 
167
>,
 
168
   <A
 
169
HREF="catalog-pg-amop.html"
 
170
><TT
 
171
CLASS="STRUCTNAME"
 
172
>pg_amop</TT
 
173
></A
 
174
>, and
 
175
   <A
 
176
HREF="catalog-pg-amproc.html"
 
177
><TT
 
178
CLASS="STRUCTNAME"
 
179
>pg_amproc</TT
 
180
></A
 
181
>.
 
182
   These entries allow the planner
 
183
   to determine what kinds of query qualifications can be used with
 
184
   indexes of this access method.  Operator families and classes are described
 
185
   in <A
 
186
HREF="xindex.html"
 
187
>Section 35.14</A
 
188
>, which is prerequisite material for reading
 
189
   this chapter.
 
190
  </P
 
191
><P
 
192
>   An individual index is defined by a
 
193
   <A
 
194
HREF="catalog-pg-class.html"
 
195
><TT
 
196
CLASS="STRUCTNAME"
 
197
>pg_class</TT
 
198
></A
 
199
>
 
200
   entry that describes it as a physical relation, plus a
 
201
   <A
 
202
HREF="catalog-pg-index.html"
 
203
><TT
 
204
CLASS="STRUCTNAME"
 
205
>pg_index</TT
 
206
></A
 
207
>
 
208
   entry that shows the logical content of the index &mdash; that is, the set
 
209
   of index columns it has and the semantics of those columns, as captured by
 
210
   the associated operator classes.  The index columns (key values) can be
 
211
   either simple columns of the underlying table or expressions over the table
 
212
   rows.  The index access method normally has no interest in where the index
 
213
   key values come from (it is always handed precomputed key values) but it
 
214
   will be very interested in the operator class information in
 
215
   <TT
 
216
CLASS="STRUCTNAME"
 
217
>pg_index</TT
 
218
>.  Both of these catalog entries can be
 
219
   accessed as part of the <TT
 
220
CLASS="STRUCTNAME"
 
221
>Relation</TT
 
222
> data structure that is
 
223
   passed to all operations on the index.
 
224
  </P
 
225
><P
 
226
>   Some of the flag columns of <TT
 
227
CLASS="STRUCTNAME"
 
228
>pg_am</TT
 
229
> have nonobvious
 
230
   implications.  The requirements of <TT
 
231
CLASS="STRUCTFIELD"
 
232
>amcanunique</TT
 
233
>
 
234
   are discussed in <A
 
235
HREF="index-unique-checks.html"
 
236
>Section 52.5</A
 
237
>.
 
238
   The <TT
 
239
CLASS="STRUCTFIELD"
 
240
>amcanmulticol</TT
 
241
> flag asserts that the
 
242
   access method supports multicolumn indexes, while
 
243
   <TT
 
244
CLASS="STRUCTFIELD"
 
245
>amoptionalkey</TT
 
246
> asserts that it allows scans
 
247
   where no indexable restriction clause is given for the first index column.
 
248
   When <TT
 
249
CLASS="STRUCTFIELD"
 
250
>amcanmulticol</TT
 
251
> is false,
 
252
   <TT
 
253
CLASS="STRUCTFIELD"
 
254
>amoptionalkey</TT
 
255
> essentially says whether the
 
256
   access method supports full-index scans without any restriction clause.
 
257
   Access methods that support multiple index columns <SPAN
 
258
CLASS="emphasis"
 
259
><I
 
260
CLASS="EMPHASIS"
 
261
>must</I
 
262
></SPAN
 
263
>
 
264
   support scans that omit restrictions on any or all of the columns after
 
265
   the first; however they are permitted to require some restriction to
 
266
   appear for the first index column, and this is signaled by setting
 
267
   <TT
 
268
CLASS="STRUCTFIELD"
 
269
>amoptionalkey</TT
 
270
> false.
 
271
   One reason that an index AM might set
 
272
   <TT
 
273
CLASS="STRUCTFIELD"
 
274
>amoptionalkey</TT
 
275
> false is if it doesn't index
 
276
   NULLs.  Since most indexable operators are
 
277
   strict and hence cannot return TRUE for NULL inputs,
 
278
   it is at first sight attractive to not store index entries for null values:
 
279
   they could never be returned by an index scan anyway.  However, this
 
280
   argument fails when an index scan has no restriction clause for a given
 
281
   index column.  In practice this means that
 
282
   indexes that have <TT
 
283
CLASS="STRUCTFIELD"
 
284
>amoptionalkey</TT
 
285
> true must
 
286
   index nulls, since the planner might decide to use such an index
 
287
   with no scan keys at all.  A related restriction is that an index
 
288
   access method that supports multiple index columns <SPAN
 
289
CLASS="emphasis"
 
290
><I
 
291
CLASS="EMPHASIS"
 
292
>must</I
 
293
></SPAN
 
294
>
 
295
   support indexing null values in columns after the first, because the planner
 
296
   will assume the index can be used for queries that do not restrict
 
297
   these columns.  For example, consider an index on (a,b) and a query with
 
298
   <TT
 
299
CLASS="LITERAL"
 
300
>WHERE a = 4</TT
 
301
>.  The system will assume the index can be
 
302
   used to scan for rows with <TT
 
303
CLASS="LITERAL"
 
304
>a = 4</TT
 
305
>, which is wrong if the
 
306
   index omits rows where <TT
 
307
CLASS="LITERAL"
 
308
>b</TT
 
309
> is null.
 
310
   It is, however, OK to omit rows where the first indexed column is null.
 
311
   An index access method that does index nulls may also set
 
312
   <TT
 
313
CLASS="STRUCTFIELD"
 
314
>amsearchnulls</TT
 
315
>, indicating that it supports
 
316
   <TT
 
317
CLASS="LITERAL"
 
318
>IS NULL</TT
 
319
> and <TT
 
320
CLASS="LITERAL"
 
321
>IS NOT NULL</TT
 
322
> clauses as search
 
323
   conditions.
 
324
  </P
 
325
></DIV
 
326
><DIV
 
327
CLASS="NAVFOOTER"
 
328
><HR
 
329
ALIGN="LEFT"
 
330
WIDTH="100%"><TABLE
 
331
SUMMARY="Footer navigation table"
 
332
WIDTH="100%"
 
333
BORDER="0"
 
334
CELLPADDING="0"
 
335
CELLSPACING="0"
 
336
><TR
 
337
><TD
 
338
WIDTH="33%"
 
339
ALIGN="left"
 
340
VALIGN="top"
 
341
><A
 
342
HREF="indexam.html"
 
343
ACCESSKEY="P"
 
344
>Prev</A
 
345
></TD
 
346
><TD
 
347
WIDTH="34%"
 
348
ALIGN="center"
 
349
VALIGN="top"
 
350
><A
 
351
HREF="index.html"
 
352
ACCESSKEY="H"
 
353
>Home</A
 
354
></TD
 
355
><TD
 
356
WIDTH="33%"
 
357
ALIGN="right"
 
358
VALIGN="top"
 
359
><A
 
360
HREF="index-functions.html"
 
361
ACCESSKEY="N"
 
362
>Next</A
 
363
></TD
 
364
></TR
 
365
><TR
 
366
><TD
 
367
WIDTH="33%"
 
368
ALIGN="left"
 
369
VALIGN="top"
 
370
>Index Access Method Interface Definition</TD
 
371
><TD
 
372
WIDTH="34%"
 
373
ALIGN="center"
 
374
VALIGN="top"
 
375
><A
 
376
HREF="indexam.html"
 
377
ACCESSKEY="U"
 
378
>Up</A
 
379
></TD
 
380
><TD
 
381
WIDTH="33%"
 
382
ALIGN="right"
 
383
VALIGN="top"
 
384
>Index Access Method Functions</TD
 
385
></TR
 
386
></TABLE
 
387
></DIV
 
388
></BODY
 
389
></HTML
 
390
>
 
 
b'\\ No newline at end of file'