1 /*-------------------------------------------------------------------------
4 * general index access method routines
6 * Copyright (c) 1994, Regents of the University of California
10 * $Header: /cvsroot/pgsql/src/backend/access/index/indexam.c,v 1.36 1999/09/18 19:06:04 tgl Exp $
13 * index_open - open an index relation by relationId
14 * index_openr - open a index relation by name
15 * index_close - close a index relation
16 * index_beginscan - start a scan of an index
17 * index_rescan - restart a scan of an index
18 * index_endscan - end a scan
19 * index_insert - insert an index tuple into a relation
20 * index_delete - delete an item from an index relation
21 * index_markpos - mark a scan position
22 * index_restrpos - restore a scan position
23 * index_getnext - get the next tuple from a scan
24 * ** index_fetch - retrieve tuple with tid
25 * ** index_replace - replace a tuple
26 * ** index_getattr - get an attribute from an index tuple
27 * index_getprocid - get a support procedure id from the rel tuple
29 * IndexScanIsValid - check index scan
32 * This file contains the index_ routines which used
33 * to be a scattered collection of stuff in access/genam.
35 * The ** routines: index_fetch, index_replace, and index_getattr
36 * have not yet been implemented. They may not be needed.
39 * Scans are implemented as follows:
41 * `0' represents an invalid item pointer.
42 * `-' represents an unknown item pointer.
43 * `X' represents a known item pointers.
44 * `+' represents known or invalid item pointers.
45 * `*' represents any item pointers.
47 * State is represented by a triple of these symbols in the order of
48 * previous, current, next. Note that the case of reverse scans works
52 * (1) + + - + 0 0 (if the next item pointer is invalid)
53 * (2) + X - (otherwise)
54 * (3) * 0 0 * 0 0 (no change)
55 * (4) + X 0 X 0 0 (shift)
56 * (5) * + X + X - (shift, add unknown)
58 * All other states cannot occur.
60 * Note: It would be possible to cache the status of the previous and
61 * next item pointer using the flags.
63 *-------------------------------------------------------------------------
68 #include "access/genam.h"
69 #include "access/heapam.h"
70 #include "utils/relcache.h"
73 * undefine macros we aren't going to use that would otherwise
74 * get in our way.. delete is defined in c.h and the am's are
88 /* ----------------------------------------------------------------
89 * macros used in index_ routines
90 * ----------------------------------------------------------------
92 #define RELATION_CHECKS \
94 AssertMacro(RelationIsValid(relation)), \
95 AssertMacro(PointerIsValid(relation->rd_am)) \
100 AssertMacro(IndexScanIsValid(scan)), \
101 AssertMacro(RelationIsValid(scan->relation)), \
102 AssertMacro(PointerIsValid(scan->relation->rd_am)) \
105 #define GET_REL_PROCEDURE(x,y) \
107 procedure = relation->rd_am->y, \
108 (!RegProcedureIsValid(procedure)) ? \
109 elog(ERROR, "index_%s: invalid %s regproc", \
110 CppAsString(x), CppAsString(y)) \
114 #define GET_SCAN_PROCEDURE(x,y) \
116 procedure = scan->relation->rd_am->y, \
117 (!RegProcedureIsValid(procedure)) ? \
118 elog(ERROR, "index_%s: invalid %s regproc", \
119 CppAsString(x), CppAsString(y)) \
124 /* ----------------------------------------------------------------
125 * index_ interface functions
126 * ----------------------------------------------------------------
129 * index_open - open an index relation by relationId
131 * presently the relcache routines do all the work we need
132 * to open/close index relations. However, callers of index_open
133 * expect it to succeed, so we need to check for a failure return.
135 * Note: we acquire no lock on the index. An AccessShareLock is
136 * acquired by index_beginscan (and released by index_endscan).
140 index_open(Oid relationId)
144 r = RelationIdGetRelation(relationId);
146 if (! RelationIsValid(r))
147 elog(ERROR, "Index %u does not exist", relationId);
149 if (r->rd_rel->relkind != RELKIND_INDEX)
150 elog(ERROR, "%s is not an index relation", r->rd_rel->relname.data);
156 * index_openr - open a index relation by name
158 * As above, but lookup by name instead of OID.
162 index_openr(char *relationName)
166 r = RelationNameGetRelation(relationName);
168 if (! RelationIsValid(r))
169 elog(ERROR, "Index '%s' does not exist", relationName);
171 if (r->rd_rel->relkind != RELKIND_INDEX)
172 elog(ERROR, "%s is not an index relation", r->rd_rel->relname.data);
178 * index_close - close a index relation
180 * presently the relcache routines do all the work we need
181 * to open/close index relations.
185 index_close(Relation relation)
187 RelationClose(relation);
191 * index_insert - insert an index tuple into a relation
195 index_insert(Relation relation,
198 ItemPointer heap_t_ctid,
201 RegProcedure procedure;
202 InsertIndexResult specificResult;
205 GET_REL_PROCEDURE(insert, aminsert);
208 * have the am's insert proc do all the work.
211 specificResult = (InsertIndexResult)
212 fmgr(procedure, relation, datum, nulls, heap_t_ctid, heapRel, NULL);
214 /* must be pfree'ed */
215 return specificResult;
219 * index_delete - delete an item from an index relation
223 index_delete(Relation relation, ItemPointer indexItem)
225 RegProcedure procedure;
228 GET_REL_PROCEDURE(delete, amdelete);
230 fmgr(procedure, relation, indexItem);
234 * index_beginscan - start a scan of an index
238 index_beginscan(Relation relation,
243 IndexScanDesc scandesc;
244 RegProcedure procedure;
247 GET_REL_PROCEDURE(beginscan, ambeginscan);
249 RelationIncrementReferenceCount(relation);
252 * Acquire AccessShareLock for the duration of the scan
254 * Note: we could get an SI inval message here and consequently have
255 * to rebuild the relcache entry. The refcount increment above
256 * ensures that we will rebuild it and not just flush it...
259 LockRelation(relation, AccessShareLock);
261 scandesc = (IndexScanDesc)
262 fmgr(procedure, relation, scanFromEnd, numberOfKeys, key);
268 * index_rescan - restart a scan of an index
272 index_rescan(IndexScanDesc scan, bool scanFromEnd, ScanKey key)
274 RegProcedure procedure;
277 GET_SCAN_PROCEDURE(rescan, amrescan);
279 fmgr(procedure, scan, scanFromEnd, key);
283 * index_endscan - end a scan
287 index_endscan(IndexScanDesc scan)
289 RegProcedure procedure;
292 GET_SCAN_PROCEDURE(endscan, amendscan);
294 fmgr(procedure, scan);
296 /* Release lock and refcount acquired by index_beginscan */
298 UnlockRelation(scan->relation, AccessShareLock);
300 RelationDecrementReferenceCount(scan->relation);
304 * index_markpos - mark a scan position
308 index_markpos(IndexScanDesc scan)
310 RegProcedure procedure;
313 GET_SCAN_PROCEDURE(markpos, ammarkpos);
315 fmgr(procedure, scan);
319 * index_restrpos - restore a scan position
323 index_restrpos(IndexScanDesc scan)
325 RegProcedure procedure;
328 GET_SCAN_PROCEDURE(restrpos, amrestrpos);
330 fmgr(procedure, scan);
334 * index_getnext - get the next tuple from a scan
336 * A RetrieveIndexResult is a index tuple/heap tuple pair
340 index_getnext(IndexScanDesc scan,
341 ScanDirection direction)
343 RegProcedure procedure;
344 RetrieveIndexResult result;
347 GET_SCAN_PROCEDURE(getnext, amgettuple);
350 * have the am's gettuple proc do all the work.
353 result = (RetrieveIndexResult) fmgr(procedure, scan, direction);
361 * Some indexed access methods may require support routines that are
362 * not in the operator class/operator model imposed by pg_am. These
363 * access methods may store the OIDs of registered procedures they
364 * need in pg_amproc. These registered procedure OIDs are ordered in
365 * a way that makes sense to the access method, and used only by the
366 * access method. The general index code doesn't know anything about
367 * the routines involved; it just builds an ordered list of them for
368 * each attribute on which an index is defined.
370 * This routine returns the requested procedure OID for a particular
375 index_getprocid(Relation irel,
382 natts = irel->rd_rel->relnatts;
384 loc = irel->rd_support;
388 return loc[(natts * (procnum - 1)) + (attnum - 1)];
392 GetIndexValue(HeapTuple tuple,
395 AttrNumber *attrNums,
396 FuncIndexInfo *fInfo,
402 if (PointerIsValid(fInfo) && FIgetProcOid(fInfo) != InvalidOid)
405 Datum *attData = (Datum *) palloc(FIgetnArgs(fInfo) * sizeof(Datum));
407 for (i = 0; i < FIgetnArgs(fInfo); i++)
409 attData[i] = heap_getattr(tuple,
416 returnVal = (Datum) fmgr_array_args(FIgetProcOid(fInfo),
424 returnVal = heap_getattr(tuple, attrNums[attOff], hTupDesc, attNull);