Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
*
|
2019-12-27 00:09:00 +01:00
|
|
|
* amapi.h
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
* API for Postgres index access methods.
|
|
|
|
*
|
2023-01-02 21:00:37 +01:00
|
|
|
* Copyright (c) 2015-2023, PostgreSQL Global Development Group
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
*
|
2019-12-27 00:09:00 +01:00
|
|
|
* src/include/access/amapi.h
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
*
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*/
|
2019-12-27 00:09:00 +01:00
|
|
|
#ifndef AMAPI_H
|
|
|
|
#define AMAPI_H
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
2019-12-27 00:09:00 +01:00
|
|
|
#include "access/genam.h"
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
|
|
|
/*
|
|
|
|
* We don't wish to include planner header files here, since most of an index
|
|
|
|
* AM's implementation isn't concerned with those data structures. To allow
|
|
|
|
* declaring amcostestimate_function here, use forward struct references.
|
|
|
|
*/
|
|
|
|
struct PlannerInfo;
|
|
|
|
struct IndexPath;
|
|
|
|
|
|
|
|
/* Likewise, this file shouldn't depend on execnodes.h. */
|
|
|
|
struct IndexInfo;
|
|
|
|
|
|
|
|
|
2016-08-14 00:31:14 +02:00
|
|
|
/*
|
|
|
|
* Properties for amproperty API. This list covers properties known to the
|
|
|
|
* core code, but an index AM can define its own properties, by matching the
|
|
|
|
* string property name.
|
|
|
|
*/
|
|
|
|
typedef enum IndexAMProperty
|
|
|
|
{
|
|
|
|
AMPROP_UNKNOWN = 0, /* anything not known to core code */
|
|
|
|
AMPROP_ASC, /* column properties */
|
|
|
|
AMPROP_DESC,
|
|
|
|
AMPROP_NULLS_FIRST,
|
|
|
|
AMPROP_NULLS_LAST,
|
|
|
|
AMPROP_ORDERABLE,
|
|
|
|
AMPROP_DISTANCE_ORDERABLE,
|
|
|
|
AMPROP_RETURNABLE,
|
|
|
|
AMPROP_SEARCH_ARRAY,
|
|
|
|
AMPROP_SEARCH_NULLS,
|
|
|
|
AMPROP_CLUSTERABLE, /* index properties */
|
|
|
|
AMPROP_INDEX_SCAN,
|
|
|
|
AMPROP_BITMAP_SCAN,
|
|
|
|
AMPROP_BACKWARD_SCAN,
|
|
|
|
AMPROP_CAN_ORDER, /* AM properties */
|
|
|
|
AMPROP_CAN_UNIQUE,
|
|
|
|
AMPROP_CAN_MULTI_COL,
|
2018-04-08 07:02:05 +02:00
|
|
|
AMPROP_CAN_EXCLUDE,
|
|
|
|
AMPROP_CAN_INCLUDE,
|
2016-08-14 00:31:14 +02:00
|
|
|
} IndexAMProperty;
|
|
|
|
|
2020-08-01 23:12:47 +02:00
|
|
|
/*
|
|
|
|
* We use lists of this struct type to keep track of both operators and
|
|
|
|
* support functions while building or adding to an opclass or opfamily.
|
|
|
|
* amadjustmembers functions receive lists of these structs, and are allowed
|
|
|
|
* to alter their "ref" fields.
|
|
|
|
*
|
|
|
|
* The "ref" fields define how the pg_amop or pg_amproc entry should depend
|
|
|
|
* on the associated objects (that is, which dependency type to use, and
|
|
|
|
* which opclass or opfamily it should depend on).
|
|
|
|
*
|
|
|
|
* If ref_is_hard is true, the entry will have a NORMAL dependency on the
|
|
|
|
* operator or support func, and an INTERNAL dependency on the opclass or
|
|
|
|
* opfamily. This forces the opclass or opfamily to be dropped if the
|
|
|
|
* operator or support func is dropped, and requires the CASCADE option
|
|
|
|
* to do so. Nor will ALTER OPERATOR FAMILY DROP be allowed. This is
|
|
|
|
* the right behavior for objects that are essential to an opclass.
|
|
|
|
*
|
|
|
|
* If ref_is_hard is false, the entry will have an AUTO dependency on the
|
|
|
|
* operator or support func, and also an AUTO dependency on the opclass or
|
|
|
|
* opfamily. This allows ALTER OPERATOR FAMILY DROP, and causes that to
|
|
|
|
* happen automatically if the operator or support func is dropped. This
|
|
|
|
* is the right behavior for inessential ("loose") objects.
|
|
|
|
*/
|
|
|
|
typedef struct OpFamilyMember
|
|
|
|
{
|
|
|
|
bool is_func; /* is this an operator, or support func? */
|
|
|
|
Oid object; /* operator or support func's OID */
|
|
|
|
int number; /* strategy or support func number */
|
|
|
|
Oid lefttype; /* lefttype */
|
|
|
|
Oid righttype; /* righttype */
|
|
|
|
Oid sortfamily; /* ordering operator's sort opfamily, or 0 */
|
|
|
|
bool ref_is_hard; /* hard or soft dependency? */
|
|
|
|
bool ref_is_family; /* is dependency on opclass or opfamily? */
|
|
|
|
Oid refobjid; /* OID of opclass or opfamily */
|
|
|
|
} OpFamilyMember;
|
|
|
|
|
2016-08-14 00:31:14 +02:00
|
|
|
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/*
|
|
|
|
* Callback function signatures --- see indexam.sgml for more info.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* build new index */
|
|
|
|
typedef IndexBuildResult *(*ambuild_function) (Relation heapRelation,
|
|
|
|
Relation indexRelation,
|
|
|
|
struct IndexInfo *indexInfo);
|
|
|
|
|
|
|
|
/* build empty index */
|
|
|
|
typedef void (*ambuildempty_function) (Relation indexRelation);
|
|
|
|
|
|
|
|
/* insert this tuple */
|
|
|
|
typedef bool (*aminsert_function) (Relation indexRelation,
|
|
|
|
Datum *values,
|
|
|
|
bool *isnull,
|
|
|
|
ItemPointer heap_tid,
|
|
|
|
Relation heapRelation,
|
Allow index AMs to cache data across aminsert calls within a SQL command.
It's always been possible for index AMs to cache data across successive
amgettuple calls within a single SQL command: the IndexScanDesc.opaque
field is meant for precisely that. However, no comparable facility
exists for amortizing setup work across successive aminsert calls.
This patch adds such a feature and teaches GIN, GIST, and BRIN to use it
to amortize catalog lookups they'd previously been doing on every call.
(The other standard index AMs keep everything they need in the relcache,
so there's little to improve there.)
For GIN, the overall improvement in a statement that inserts many rows
can be as much as 10%, though it seems a bit less for the other two.
In addition, this makes a really significant difference in runtime
for CLOBBER_CACHE_ALWAYS tests, since in those builds the repeated
catalog lookups are vastly more expensive.
The reason this has been hard up to now is that the aminsert function is
not passed any useful place to cache per-statement data. What I chose to
do is to add suitable fields to struct IndexInfo and pass that to aminsert.
That's not widening the index AM API very much because IndexInfo is already
within the ken of ambuild; in fact, by passing the same info to aminsert
as to ambuild, this is really removing an inconsistency in the AM API.
Discussion: https://postgr.es/m/27568.1486508680@sss.pgh.pa.us
2017-02-09 17:52:12 +01:00
|
|
|
IndexUniqueCheck checkUnique,
|
2021-01-13 17:11:00 +01:00
|
|
|
bool indexUnchanged,
|
Allow index AMs to cache data across aminsert calls within a SQL command.
It's always been possible for index AMs to cache data across successive
amgettuple calls within a single SQL command: the IndexScanDesc.opaque
field is meant for precisely that. However, no comparable facility
exists for amortizing setup work across successive aminsert calls.
This patch adds such a feature and teaches GIN, GIST, and BRIN to use it
to amortize catalog lookups they'd previously been doing on every call.
(The other standard index AMs keep everything they need in the relcache,
so there's little to improve there.)
For GIN, the overall improvement in a statement that inserts many rows
can be as much as 10%, though it seems a bit less for the other two.
In addition, this makes a really significant difference in runtime
for CLOBBER_CACHE_ALWAYS tests, since in those builds the repeated
catalog lookups are vastly more expensive.
The reason this has been hard up to now is that the aminsert function is
not passed any useful place to cache per-statement data. What I chose to
do is to add suitable fields to struct IndexInfo and pass that to aminsert.
That's not widening the index AM API very much because IndexInfo is already
within the ken of ambuild; in fact, by passing the same info to aminsert
as to ambuild, this is really removing an inconsistency in the AM API.
Discussion: https://postgr.es/m/27568.1486508680@sss.pgh.pa.us
2017-02-09 17:52:12 +01:00
|
|
|
struct IndexInfo *indexInfo);
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
2023-11-25 20:27:04 +01:00
|
|
|
/* cleanup after insert */
|
|
|
|
typedef void (*aminsertcleanup_function) (struct IndexInfo *indexInfo);
|
|
|
|
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* bulk delete */
|
|
|
|
typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
|
|
|
|
IndexBulkDeleteResult *stats,
|
|
|
|
IndexBulkDeleteCallback callback,
|
|
|
|
void *callback_state);
|
|
|
|
|
|
|
|
/* post-VACUUM cleanup */
|
|
|
|
typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
|
|
|
|
IndexBulkDeleteResult *stats);
|
|
|
|
|
|
|
|
/* can indexscan return IndexTuples? */
|
|
|
|
typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
|
|
|
|
|
|
|
|
/* estimate cost of an indexscan */
|
|
|
|
typedef void (*amcostestimate_function) (struct PlannerInfo *root,
|
|
|
|
struct IndexPath *path,
|
|
|
|
double loop_count,
|
|
|
|
Cost *indexStartupCost,
|
|
|
|
Cost *indexTotalCost,
|
|
|
|
Selectivity *indexSelectivity,
|
2017-02-15 19:53:24 +01:00
|
|
|
double *indexCorrelation,
|
|
|
|
double *indexPages);
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
|
|
|
/* parse index reloptions */
|
|
|
|
typedef bytea *(*amoptions_function) (Datum reloptions,
|
|
|
|
bool validate);
|
|
|
|
|
2016-08-14 00:31:14 +02:00
|
|
|
/* report AM, index, or index column property */
|
|
|
|
typedef bool (*amproperty_function) (Oid index_oid, int attno,
|
|
|
|
IndexAMProperty prop, const char *propname,
|
|
|
|
bool *res, bool *isnull);
|
|
|
|
|
Report progress of CREATE INDEX operations
This uses the progress reporting infrastructure added by c16dc1aca5e0,
adding support for CREATE INDEX and CREATE INDEX CONCURRENTLY.
There are two pieces to this: one is index-AM-agnostic, and the other is
AM-specific. The latter is fairly elaborate for btrees, including
reportage for parallel index builds and the separate phases that btree
index creation uses; other index AMs, which are much simpler in their
building procedures, have simplistic reporting only, but that seems
sufficient, at least for non-concurrent builds.
The index-AM-agnostic part is fairly complete, providing insight into
the CONCURRENTLY wait phases as well as block-based progress during the
index validation table scan. (The index validation index scan requires
patching each AM, which has not been included here.)
Reviewers: Rahila Syed, Pavan Deolasee, Tatsuro Yamada
Discussion: https://postgr.es/m/20181220220022.mg63bhk26zdpvmcj@alvherre.pgsql
2019-04-02 20:18:08 +02:00
|
|
|
/* name of phase as used in progress reporting */
|
|
|
|
typedef char *(*ambuildphasename_function) (int64 phasenum);
|
|
|
|
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* validate definition of an opclass for this AM */
|
|
|
|
typedef bool (*amvalidate_function) (Oid opclassoid);
|
|
|
|
|
2020-08-01 23:12:47 +02:00
|
|
|
/* validate operators and support functions to be added to an opclass/family */
|
|
|
|
typedef void (*amadjustmembers_function) (Oid opfamilyoid,
|
|
|
|
Oid opclassoid,
|
|
|
|
List *operators,
|
|
|
|
List *functions);
|
|
|
|
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* prepare for index scan */
|
|
|
|
typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
|
|
|
|
int nkeys,
|
|
|
|
int norderbys);
|
|
|
|
|
|
|
|
/* (re)start index scan */
|
|
|
|
typedef void (*amrescan_function) (IndexScanDesc scan,
|
|
|
|
ScanKey keys,
|
|
|
|
int nkeys,
|
|
|
|
ScanKey orderbys,
|
|
|
|
int norderbys);
|
|
|
|
|
|
|
|
/* next valid tuple */
|
|
|
|
typedef bool (*amgettuple_function) (IndexScanDesc scan,
|
|
|
|
ScanDirection direction);
|
|
|
|
|
|
|
|
/* fetch all valid tuples */
|
|
|
|
typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
|
|
|
|
TIDBitmap *tbm);
|
|
|
|
|
|
|
|
/* end index scan */
|
|
|
|
typedef void (*amendscan_function) (IndexScanDesc scan);
|
|
|
|
|
|
|
|
/* mark current scan position */
|
|
|
|
typedef void (*ammarkpos_function) (IndexScanDesc scan);
|
|
|
|
|
|
|
|
/* restore marked scan position */
|
|
|
|
typedef void (*amrestrpos_function) (IndexScanDesc scan);
|
|
|
|
|
2017-01-24 22:42:58 +01:00
|
|
|
/*
|
|
|
|
* Callback function signatures - for parallel index scans.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* estimate size of parallel scan descriptor */
|
|
|
|
typedef Size (*amestimateparallelscan_function) (void);
|
|
|
|
|
|
|
|
/* prepare for parallel index scan */
|
|
|
|
typedef void (*aminitparallelscan_function) (void *target);
|
|
|
|
|
|
|
|
/* (re)start parallel index scan */
|
|
|
|
typedef void (*amparallelrescan_function) (IndexScanDesc scan);
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
|
|
|
/*
|
|
|
|
* API struct for an index AM. Note this must be stored in a single palloc'd
|
|
|
|
* chunk of memory.
|
|
|
|
*/
|
|
|
|
typedef struct IndexAmRoutine
|
|
|
|
{
|
|
|
|
NodeTag type;
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Total number of strategies (operators) by which we can traverse/search
|
|
|
|
* this AM. Zero if AM does not have a fixed set of strategy assignments.
|
|
|
|
*/
|
|
|
|
uint16 amstrategies;
|
|
|
|
/* total number of support functions that this AM uses */
|
|
|
|
uint16 amsupport;
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
/* opclass options support function number or 0 */
|
|
|
|
uint16 amoptsprocnum;
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* does AM support ORDER BY indexed column's value? */
|
|
|
|
bool amcanorder;
|
|
|
|
/* does AM support ORDER BY result of an operator on indexed column? */
|
|
|
|
bool amcanorderbyop;
|
|
|
|
/* does AM support backward scanning? */
|
|
|
|
bool amcanbackward;
|
|
|
|
/* does AM support UNIQUE indexes? */
|
|
|
|
bool amcanunique;
|
|
|
|
/* does AM support multi-column indexes? */
|
|
|
|
bool amcanmulticol;
|
|
|
|
/* does AM require scans to have a constraint on the first index column? */
|
|
|
|
bool amoptionalkey;
|
|
|
|
/* does AM handle ScalarArrayOpExpr quals? */
|
|
|
|
bool amsearcharray;
|
|
|
|
/* does AM handle IS NULL/IS NOT NULL quals? */
|
|
|
|
bool amsearchnulls;
|
|
|
|
/* can index storage data type differ from column data type? */
|
|
|
|
bool amstorage;
|
|
|
|
/* can an index of this type be clustered on? */
|
|
|
|
bool amclusterable;
|
|
|
|
/* does AM handle predicate locks? */
|
|
|
|
bool ampredlocks;
|
2017-02-15 19:53:24 +01:00
|
|
|
/* does AM support parallel scan? */
|
|
|
|
bool amcanparallel;
|
2018-04-07 22:00:39 +02:00
|
|
|
/* does AM support columns included with clause INCLUDE? */
|
|
|
|
bool amcaninclude;
|
2020-01-15 02:54:14 +01:00
|
|
|
/* does AM use maintenance_work_mem? */
|
|
|
|
bool amusemaintenanceworkmem;
|
Ignore BRIN indexes when checking for HOT updates
When determining whether an index update may be skipped by using HOT, we
can ignore attributes indexed by block summarizing indexes without
references to individual tuples that need to be cleaned up.
A new type TU_UpdateIndexes provides a signal to the executor to
determine which indexes to update - no indexes, all indexes, or only the
summarizing indexes.
This also removes rd_indexattr list, and replaces it with rd_attrsvalid
flag. The list was not used anywhere, and a simple flag is sufficient.
This was originally committed as 5753d4ee32, but then got reverted by
e3fcca0d0d because of correctness issues.
Original patch by Josef Simanek, various fixes and improvements by Tomas
Vondra and me.
Authors: Matthias van de Meent, Josef Simanek, Tomas Vondra
Reviewed-by: Tomas Vondra, Alvaro Herrera
Discussion: https://postgr.es/m/05ebcb44-f383-86e3-4f31-0a97a55634cf@enterprisedb.com
Discussion: https://postgr.es/m/CAFp7QwpMRGcDAQumN7onN9HjrJ3u4X3ZRXdGFT0K5G2JWvnbWg%40mail.gmail.com
2023-03-20 10:34:07 +01:00
|
|
|
/* does AM store tuple information only at block granularity? */
|
|
|
|
bool amsummarizing;
|
2020-01-15 02:54:14 +01:00
|
|
|
/* OR of parallel vacuum flags. See vacuum.h for flags. */
|
|
|
|
uint8 amparallelvacuumoptions;
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* type of data stored in index, or InvalidOid if variable */
|
|
|
|
Oid amkeytype;
|
|
|
|
|
2018-04-08 07:02:05 +02:00
|
|
|
/*
|
|
|
|
* If you add new properties to either the above or the below lists, then
|
|
|
|
* they should also (usually) be exposed via the property API (see
|
|
|
|
* IndexAMProperty at the top of the file, and utils/adt/amutils.c).
|
|
|
|
*/
|
|
|
|
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
/* interface functions */
|
|
|
|
ambuild_function ambuild;
|
|
|
|
ambuildempty_function ambuildempty;
|
|
|
|
aminsert_function aminsert;
|
2023-11-25 20:27:04 +01:00
|
|
|
aminsertcleanup_function aminsertcleanup;
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
ambulkdelete_function ambulkdelete;
|
|
|
|
amvacuumcleanup_function amvacuumcleanup;
|
|
|
|
amcanreturn_function amcanreturn; /* can be NULL */
|
|
|
|
amcostestimate_function amcostestimate;
|
|
|
|
amoptions_function amoptions;
|
2016-08-14 00:31:14 +02:00
|
|
|
amproperty_function amproperty; /* can be NULL */
|
Report progress of CREATE INDEX operations
This uses the progress reporting infrastructure added by c16dc1aca5e0,
adding support for CREATE INDEX and CREATE INDEX CONCURRENTLY.
There are two pieces to this: one is index-AM-agnostic, and the other is
AM-specific. The latter is fairly elaborate for btrees, including
reportage for parallel index builds and the separate phases that btree
index creation uses; other index AMs, which are much simpler in their
building procedures, have simplistic reporting only, but that seems
sufficient, at least for non-concurrent builds.
The index-AM-agnostic part is fairly complete, providing insight into
the CONCURRENTLY wait phases as well as block-based progress during the
index validation table scan. (The index validation index scan requires
patching each AM, which has not been included here.)
Reviewers: Rahila Syed, Pavan Deolasee, Tatsuro Yamada
Discussion: https://postgr.es/m/20181220220022.mg63bhk26zdpvmcj@alvherre.pgsql
2019-04-02 20:18:08 +02:00
|
|
|
ambuildphasename_function ambuildphasename; /* can be NULL */
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
amvalidate_function amvalidate;
|
2020-08-01 23:12:47 +02:00
|
|
|
amadjustmembers_function amadjustmembers; /* can be NULL */
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
ambeginscan_function ambeginscan;
|
|
|
|
amrescan_function amrescan;
|
|
|
|
amgettuple_function amgettuple; /* can be NULL */
|
|
|
|
amgetbitmap_function amgetbitmap; /* can be NULL */
|
|
|
|
amendscan_function amendscan;
|
|
|
|
ammarkpos_function ammarkpos; /* can be NULL */
|
|
|
|
amrestrpos_function amrestrpos; /* can be NULL */
|
2017-01-24 22:42:58 +01:00
|
|
|
|
|
|
|
/* interface functions to support parallel index scans */
|
|
|
|
amestimateparallelscan_function amestimateparallelscan; /* can be NULL */
|
|
|
|
aminitparallelscan_function aminitparallelscan; /* can be NULL */
|
|
|
|
amparallelrescan_function amparallelrescan; /* can be NULL */
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
} IndexAmRoutine;
|
|
|
|
|
|
|
|
|
2019-12-27 00:09:00 +01:00
|
|
|
/* Functions in access/index/amapi.c */
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
|
2016-08-14 00:31:14 +02:00
|
|
|
extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
|
Restructure index access method API to hide most of it at the C level.
This patch reduces pg_am to just two columns, a name and a handler
function. All the data formerly obtained from pg_am is now provided
in a C struct returned by the handler function. This is similar to
the designs we've adopted for FDWs and tablesample methods. There
are multiple advantages. For one, the index AM's support functions
are now simple C functions, making them faster to call and much less
error-prone, since the C compiler can now check function signatures.
For another, this will make it far more practical to define index access
methods in installable extensions.
A disadvantage is that SQL-level code can no longer see attributes
of index AMs; in particular, some of the crosschecks in the opr_sanity
regression test are no longer possible from SQL. We've addressed that
by adding a facility for the index AM to perform such checks instead.
(Much more could be done in that line, but for now we're content if the
amvalidate functions more or less replace what opr_sanity used to do.)
We might also want to expose some sort of reporting functionality, but
this patch doesn't do that.
Alexander Korotkov, reviewed by Petr Jelínek, and rather heavily
editorialized on by me.
2016-01-18 01:36:59 +01:00
|
|
|
|
2019-12-27 00:09:00 +01:00
|
|
|
#endif /* AMAPI_H */
|