Skip to content

P
Postgres FD Implementation
Commit d6efbf19 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Significant update from Vince Vielhaber.

parent 874957a3
Hide whitespace changes
Inline Side-by-side
Showing with 543 additions and 451 deletions
doc/src/sgml/xindex.sgml
View file @ d6efbf19
<Chapter Id="xindex"> <chapter id="xindex">
<Title>Interfacing Extensions To Indices</Title> <title>Interfacing Extensions To Indices</title>
<Para> <para>
The procedures described thus far let you define a new The procedures described thus far let you define a new type, new
type, new functions and new operators. However, we functions and new operators. However, we cannot yet define a secondary
cannot yet define a secondary index (such as a <Acronym>B-tree</Acronym>, index (such as a <acronym>B-tree</acronym>, <acronym>R-tree</acronym> or
<Acronym>R-tree</Acronym> or hash access method) over a new type or its hash access method) over a new type or its operators.
operators. </para>
</Para>
<para>
<Para> Look back at
Look back at <xref endterm="EXTEND-CATALOGS" linkend="EXTEND-CATALOGS">.
<XRef LinkEnd="EXTEND-CATALOGS" EndTerm="EXTEND-CATALOGS">. The right half shows the catalogs that we must modify in order to tell
The right half shows the catalogs <productname>Postgres</productname> how to use a user-defined type and/or
that we must modify in order to tell <ProductName>Postgres</ProductName> how user-defined operators with an index (i.e., <filename>pg_am, pg_amop,
to use a user-defined type and/or user-defined operators pg_amproc, pg_operator</filename> and <filename>pg_opclass</filename>).
with an index (i.e., <FileName>pg_am, pg_amop, pg_amproc</FileName> and Unfortunately, there is no simple command to do this. We will demonstrate
<FileName>pg_opclass</FileName>). Unfortunately, there is no simple command how to modify these catalogs through a running example: a new operator
to do this. We will demonstrate how to modify these class for the <acronym>B-tree</acronym> access method that stores and
catalogs through a running example: a new operator sorts complex numbers in ascending absolute value order.
class for the <Acronym>B-tree</Acronym> access method that sorts integers </para>
in ascending absolute value order.
</Para> <para>
The <filename>pg_am</filename> class contains one instance for every user
<Para> defined access method. Support for the heap access method is built into
The <FileName>pg_am</FileName> class contains one instance for every user <productname>Postgres</productname>, but every other access method is
defined access method. Support for the heap access described here. The schema is
method is built into <ProductName>Postgres</ProductName>, but every other access
method is described here. The schema is <table tocentry="1">
<title>Index Schema</title>
<TABLE TOCENTRY="1"> <titleabbrev>Indices</titleabbrev>
<Title>Index Schema</Title> <tgroup cols="2">
<TitleAbbrev>Indices</TitleAbbrev> <thead>
<TGroup Cols="2"> <row>
<THead> <entry>Attribute</entry>
<Row> <entry>Description</entry>
<Entry>Attribute</Entry> </row>
<Entry>Description</Entry> </thead>
</Row> <tbody>
</THead> <row>
<TBody> <entry>amname</entry>
<Row> <entry>name of the access method</entry>
<Entry>amname</Entry> </row>
<Entry>name of the access method</Entry> <row>
</Row> <entry>amowner</entry>
<Row> <entry>object id of the owner's instance in pg_user</entry>
<Entry>amowner</Entry> </row>
<Entry>object id of the owner's instance in pg_user</Entry> <row>
</Row> <entry>amkind</entry>
<Row> <entry>not used at present, but set to 'o' as a place holder</entry>
<Entry>amkind</Entry> </row>
<Entry>not used at present, but set to 'o' as a place holder</Entry> <row>
</Row> <entry>amstrategies</entry>
<Row> <entry>number of strategies for this access method (see below)</entry>
<Entry>amstrategies</Entry> </row>
<Entry>number of strategies for this access method (see below)</Entry> <row>
</Row> <entry>amsupport</entry>
<Row> <entry>number of support routines for this access method (see below)</entry>
<Entry>amsupport</Entry> </row>
<Entry>number of support routines for this access method (see below)</Entry> <row>
</Row> <entry>amgettuple</entry>
<Row> </row>
<Entry>amgettuple <row>
aminsert <entry>aminsert</entry>
...</Entry> </row>
<row>
<Entry>procedure identifiers for interface routines to the access <entry>...</entry>
method. For example, regproc ids for opening, closing, and <entry>procedure identifiers for interface routines to the access
getting instances from the access method appear here. </Entry> method. For example, regproc ids for opening, closing, and
</Row> getting instances from the access method appear here.</entry>
</TBody> </row>
</TGroup> </tbody>
</TABLE> </tgroup>
</Para> </table>
</para>
<Para>
The <Acronym>object ID</Acronym> of the instance in <FileName>pg_am</FileName> is used as a <para>
foreign key in lots of other classes. You don't need The <acronym>object ID</acronym> of the instance in
to add a new instance to this class; all you're interested in <filename>pg_am</filename> is used as a foreign key in lots of other
is the <Acronym>object ID</Acronym> of the access method instance classes. You don't need to add a new instance to this class; all
you want to extend: you're interested in is the <acronym>object ID</acronym> of the access
method instance you want to extend:
<ProgramListing>
<programlisting>
SELECT oid FROM pg_am WHERE amname = 'btree'; SELECT oid FROM pg_am WHERE amname = 'btree';
+----+ +----+
...@@ -89,181 +90,187 @@ SELECT oid FROM pg_am WHERE amname = 'btree'; ...@@ -89,181 +90,187 @@ SELECT oid FROM pg_am WHERE amname = 'btree';
+----+ +----+
|403 | |403 |
+----+ +----+
</ProgramListing> </programlisting>
</Para>
We will use that <command>SELECT</command> in a <command>WHERE</command>
<Para> clause later.
The <FileName>amstrategies</FileName> attribute exists to standardize </para>
comparisons across data types. For example, <Acronym>B-tree</Acronym>s
impose a strict ordering on keys, lesser to greater. <para>
Since <ProductName>Postgres</ProductName> allows the user to define operators, The <filename>amstrategies</filename> attribute exists to standardize
<ProductName>Postgres</ProductName> cannot look at the name of an operator (eg, ">" comparisons across data types. For example, <acronym>B-tree</acronym>s
or "<") and tell what kind of comparison it is. In fact, impose a strict ordering on keys, lesser to greater. Since
some access methods don't impose any ordering at all. <productname>Postgres</productname> allows the user to define operators,
For example, <Acronym>R-tree</Acronym>s express a rectangle-containment <productname>Postgres</productname> cannot look at the name of an operator
relationship, whereas a hashed data structure expresses (eg, ">" or "<") and tell what kind of comparison it is. In fact,
only bitwise similarity based on the value of a hash some access methods don't impose any ordering at all. For example,
function. <ProductName>Postgres</ProductName> needs some consistent way of taking <acronym>R-tree</acronym>s express a rectangle-containment relationship,
a qualification in your query, looking at the operator whereas a hashed data structure expresses only bitwise similarity based
and then deciding if a usable index exists. This on the value of a hash function. <productname>Postgres</productname>
implies that <ProductName>Postgres</ProductName> needs to know, for example, that needs some consistent way of taking a qualification in your query,
the "<=" and ">" operators partition a <Acronym>B-tree</Acronym>. <ProductName>Postgres</ProductName> looking at the operator and then deciding if a usable index exists. This
uses strategies to express these relationships between implies that <productname>Postgres</productname> needs to know, for
operators and the way they can be used to scan indices. example, that the "<=" and ">" operators partition a
</Para> <acronym>B-tree</acronym>. <productname>Postgres</productname>
uses strategies to express these relationships between
<Para> operators and the way they can be used to scan indices.
Defining a new set of strategies is beyond the scope of </para>
this discussion, but we'll explain how <Acronym>B-tree</Acronym> strategies
work because you'll need to know that to add a new <para>
operator class. In the <FileName>pg_am</FileName> class, the amstrategies Defining a new set of strategies is beyond the scope of this discussion,
attribute is the number of strategies defined for this but we'll explain how <acronym>B-tree</acronym> strategies work because
access method. For <Acronym>B-tree</Acronym>s, this number is 5. These you'll need to know that to add a new operator class. In the
strategies correspond to <filename>pg_am</filename> class, the amstrategies attribute is the
number of strategies defined for this access method. For
<TABLE TOCENTRY="1"> <acronym>B-tree</acronym>s, this number is 5. These strategies
<Title>B-tree Strategies</Title> correspond to
<TitleAbbrev>B-tree</TitleAbbrev>
<TGroup Cols="2"> <table tocentry="1">
<THead> <title>B-tree Strategies</title>
<Row> <titleabbrev>B-tree</titleabbrev>
<Entry>Operation</Entry> <tgroup cols="2">
<Entry>Index</Entry> <thead>
</Row> <row>
</THead> <entry>Operation</entry>
<TBody> <entry>Index</entry>
<Row> </row>
<Entry>less than</Entry> </thead>
<Entry>1</Entry> <tbody>
</Row> <row>
<Row> <entry>less than</entry>
<Entry>less than or equal</Entry> <entry>1</entry>
<Entry>2</Entry> </row>
</Row> <row>
<Row> <entry>less than or equal</entry>
<Entry>equal</Entry> <entry>2</entry>
<Entry>3</Entry> </row>
</Row> <row>
<Row> <entry>equal</entry>
<Entry>greater than or equal</Entry> <entry>3</entry>
<Entry>4</Entry> </row>
</Row> <row>
<Row> <entry>greater than or equal</entry>
<Entry>greater than</Entry> <entry>4</entry>
<Entry>5</Entry> </row>
</Row> <row>
</TBody> <entry>greater than</entry>
</TGroup> <entry>5</entry>
</TABLE> </row>
</Para> </tbody>
</tgroup>
<Para> </table>
The idea is that you'll need to add procedures corresponding </para>
to the comparisons above to the <FileName>pg_amop</FileName> relation
(see below). The access method code can use these <para>
strategy numbers, regardless of data type, to figure The idea is that you'll need to add procedures corresponding to the
out how to partition the <Acronym>B-tree</Acronym>, compute selectivity, comparisons above to the <filename>pg_amop</filename> relation (see below).
and so on. Don't worry about the details of adding The access method code can use these strategy numbers, regardless of data
procedures yet; just understand that there must be a type, to figure out how to partition the <acronym>B-tree</acronym>,
set of these procedures for <FileName>int2, int4, oid,</FileName> and every compute selectivity, and so on. Don't worry about the details of adding
other data type on which a <Acronym>B-tree</Acronym> can operate. procedures yet; just understand that there must be a set of these
procedures for <filename>int2, int4, oid,</filename> and every other
Sometimes, strategies aren't enough information for the data type on which a <acronym>B-tree</acronym> can operate.
system to figure out how to use an index. Some access </para>
methods require other support routines in order to
work. For example, the <Acronym>B-tree</Acronym> access method must be <para>
able to compare two keys and determine whether one is Sometimes, strategies aren't enough information for the system to figure
greater than, equal to, or less than the other. out how to use an index. Some access methods require other support
Similarly, the <Acronym>R-tree</Acronym> access method must be able to compute routines in order to work. For example, the <acronym>B-tree</acronym>
intersections, unions, and sizes of rectangles. These access method must be able to compare two keys and determine whether one
operations do not correspond to user qualifications in is greater than, equal to, or less than the other. Similarly, the
SQL queries; they are administrative routines used by <acronym>R-tree</acronym> access method must be able to compute
the access methods, internally. intersections, unions, and sizes of rectangles. These
</Para> operations do not correspond to user qualifications in
SQL queries; they are administrative routines used by
<Para> the access methods, internally.
In order to manage diverse support routines </para>
consistently across all <ProductName>Postgres</ProductName> access methods, <FileName>pg_am</FileName>
includes an attribute called <FileName>amsupport</FileName>. This attribute <para>
records the number of support routines used by an In order to manage diverse support routines consistently across all
access method. For <Acronym>B-tree</Acronym>s, this number is one -- the <productname>Postgres</productname> access methods,
routine to take two keys and return -1, 0, or +1, <filename>pg_am</filename> includes an attribute called
depending on whether the first key is less than, equal <filename>amsupport</filename>. This attribute records the number of
to, or greater than the second. support routines used by an access method. For <acronym>B-tree</acronym>s,
<Note> this number is one -- the routine to take two keys and return -1, 0, or
<Para> +1, depending on whether the first key is less than, equal
Strictly speaking, this routine can return a negative to, or greater than the second.
number (< 0), 0, or a non-zero positive number (> 0).
</Para> <note>
</Note> <para>
</para> Strictly speaking, this routine can return a negative
<Para> number (< 0), 0, or a non-zero positive number (> 0).
The <FileName>amstrategies</FileName> entry in pg_am is just the number of </para>
strategies defined for the access method in question. </note>
The procedures for less than, less equal, and so on </para>
don't appear in <FileName>pg_am</FileName>. Similarly, <FileName>amsupport</FileName> is just
the number of support routines required by the access <para>
method. The actual routines are listed elsewhere. The <filename>amstrategies</filename> entry in pg_am is just the number
</Para> of strategies defined for the access method in question. The procedures
for less than, less equal, and so on don't appear in
<Para> <filename>pg_am</filename>. Similarly, <filename>amsupport</filename>
The next class of interest is pg_opclass. This class is just the number of support routines required by the access
exists only to associate a name with an oid. In method. The actual routines are listed elsewhere.
pg_amop, every <Acronym>B-tree</Acronym> operator class has a set of </para>
procedures, one through five, above. Some existing
opclasses are <FileName>int2_ops, int4_ops, and oid_ops</FileName>. You <para>
need to add an instance with your opclass name (for The next class of interest is pg_opclass. This class exists only to
example, <FileName>complex_abs_ops</FileName>) to <FileName>pg_opclass</FileName>. The <FileName>oid</FileName> of associate a name and default type with an oid. In pg_amop, every
this instance is a foreign key in other classes. <acronym>B-tree</acronym> operator class has a set of procedures, one
through five, above. Some existing opclasses are <filename>int2_ops,
<ProgramListing> int4_ops, and oid_ops</filename>. You need to add an instance with your
INSERT INTO pg_opclass (opcname) VALUES ('complex_abs_ops'); opclass name (for example, <filename>complex_abs_ops</filename>) to
<filename>pg_opclass</filename>. The <filename>oid</filename> of
SELECT oid, opcname this instance is a foreign key in other classes.
<programlisting>
INSERT INTO pg_opclass (opcname, opcdeftype)
SELECT 'complex_abs_ops', oid FROM pg_type WHERE typname = 'complex_abs';
SELECT oid, opcname, opcdeftype
FROM pg_opclass FROM pg_opclass
WHERE opcname = 'complex_abs_ops'; WHERE opcname = 'complex_abs_ops';
+------+--------------+ +------+-----------------+------------+
|oid | opcname | |oid | opcname | opcdeftype |
+------+--------------+ +------+-----------------+------------+
|17314 | int4_abs_ops | |17314 | complex_abs_ops | 29058 |
+------+--------------+ +------+-----------------+------------+
</ProgramListing> </programlisting>
Note that the oid for your <FileName>pg_opclass</FileName> instance will be Note that the oid for your <filename>pg_opclass</filename> instance will
different! You should substitute your value for 17314 be different! Don't worry about this though. We'll get this number
wherever it appears in this discussion. from the system later just like we got the oid of the type here.
</Para> </para>
<Para> <para>
So now we have an access method and an operator class. So now we have an access method and an operator class.
We still need a set of operators; the procedure for We still need a set of operators; the procedure for
defining operators was discussed earlier in this manual. defining operators was discussed earlier in this manual.
For the complex_abs_ops operator class on Btrees, For the complex_abs_ops operator class on Btrees,
the operators we require are: the operators we require are:
<ProgramListing> <programlisting>
absolute value less-than absolute value less-than
absolute value less-than-or-equal absolute value less-than-or-equal
absolute value equal absolute value equal
absolute value greater-than-or-equal absolute value greater-than-or-equal
absolute value greater-than absolute value greater-than
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
Suppose the code that implements the functions defined Suppose the code that implements the functions defined
is stored in the file is stored in the file
<FileName>PGROOT/src/tutorial/complex.c</FileName> <filename>PGROOT/src/tutorial/complex.c</filename>
</Para> </para>
<Para> <para>
Part of the code look like this: (note that we will Part of the code look like this: (note that we will only show the
only show the equality operator for the rest of the equality operator for the rest of the examples. The other four
examples. The other four operators are very similar. operators are very similar. Refer to <filename>complex.c</filename>
Refer to <FileName>complex.c</FileName> or <FileName>complex.sql</FileName> for the details.) or <filename>complex.source</filename> for the details.)
<ProgramListing> <programlisting>
#define Mag(c) ((c)-&gt;x*(c)-&gt;x + (c)-&gt;y*(c)-&gt;y) #define Mag(c) ((c)-&gt;x*(c)-&gt;x + (c)-&gt;y*(c)-&gt;y)
bool bool
...@@ -272,61 +279,57 @@ SELECT oid, opcname ...@@ -272,61 +279,57 @@ SELECT oid, opcname
double amag = Mag(a), bmag = Mag(b); double amag = Mag(a), bmag = Mag(b);
return (amag==bmag); return (amag==bmag);
} }
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
There are a couple of important things that are happening below. There are a couple of important things that are happening below.
</Para> </para>
<Para> <para>
First, note that operators for less-than, less-than-or First, note that operators for less-than, less-than-or equal, equal,
equal, equal, greater-than-or-equal, and greater-than greater-than-or-equal, and greater-than for <filename>int4</filename>
for <FileName>int4</FileName> are being defined. All of these operators are are being defined. All of these operators are already defined for
already defined for <FileName>int4</FileName> under the names &lt;, &lt;=, =, &gt;=, <filename>int4</filename> under the names &lt;, &lt;=, =, &gt;=,
and &gt;. The new operators behave differently, of and &gt;. The new operators behave differently, of course. In order
course. In order to guarantee that <ProductName>Postgres</ProductName> uses these to guarantee that <productname>Postgres</productname> uses these
new operators rather than the old ones, they need to be new operators rather than the old ones, they need to be named differently
named differently from the old ones. This is a key from the old ones. This is a key point: you can overload operators in
point: you can overload operators in <ProductName>Postgres</ProductName>, but only <productname>Postgres</productname>, but only if the operator isn't
if the operator isn't already defined for the argument already defined for the argument types. That is, if you have &lt;
types. That is, if you have &lt; defined for (int4, defined for (int4, int4), you can't define it again.
int4), you can't define it again. <ProductName>Postgres</ProductName> does not <productname>Postgres</productname> does not check this when you define
check this when you define your operator, so be careful. your operator, so be careful. To avoid this problem, odd names will be
To avoid this problem, odd names will be used for used for the operators. If you get this wrong, the access methods
the operators. If you get this wrong, the access methods are likely to crash when you try to do scans.
are likely to crash when you try to do scans. </para>
</Para>
<para>
<Para> The other important point is that all the operator functions return
The other important point is that all the operator Boolean values. The access methods rely on this fact. (On the other
functions return Boolean values. The access methods hand, the support function returns whatever the particular access method
rely on this fact. (On the other hand, the support expects -- in this case, a signed integer.) The final routine in the
function returns whatever the particular access method file is the "support routine" mentioned when we discussed the amsupport
expects -- in this case, a signed integer.) attribute of the <filename>pg_am</filename> class. We will use this
The final routine in the file is the "support routine" later on. For now, ignore it.
mentioned when we discussed the amsupport attribute of </para>
the <FileName>pg_am</FileName> class. We will use this later on. For now,
ignore it. <para>
</Para> <programlisting>
CREATE FUNCTION complex_abs_eq(complex_abs, complex_abs)
<Para>
<ProgramListing>
CREATE FUNCTION complex_abs_eq(complex, complex)
RETURNS bool RETURNS bool
AS 'PGROOT/tutorial/obj/complex.so' AS 'PGROOT/tutorial/obj/complex.so'
LANGUAGE 'c'; LANGUAGE 'c';
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
Now define the operators that use them. As noted, the Now define the operators that use them. As noted, the operator names
operator names must be unique among all operators that must be unique among all operators that take two <filename>int4</filename>
take two <FileName>int4</FileName> operands. In order to see if the operands. In order to see if the operator names listed below are taken,
operator names listed below are taken, we can do a query on we can do a query on <filename>pg_operator</filename>:
<FileName>pg_operator</FileName>:
<ProgramListing> <programlisting>
/* /*
* this query uses the regular expression operator (~) * this query uses the regular expression operator (~)
* to find three-character operator names that end in * to find three-character operator names that end in
...@@ -335,95 +338,93 @@ CREATE FUNCTION complex_abs_eq(complex, complex) ...@@ -335,95 +338,93 @@ CREATE FUNCTION complex_abs_eq(complex, complex)
SELECT * SELECT *
FROM pg_operator FROM pg_operator
WHERE oprname ~ '^..&amp;$'::text; WHERE oprname ~ '^..&amp;$'::text;
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
to see if your name is taken for the types you want. to see if your name is taken for the types you want. The important
The important things here are the procedure (which are things here are the procedure (which are the <acronym>C</acronym>
the <Acronym>C</Acronym> functions defined above) and the restriction and functions defined above) and the restriction and join selectivity
join selectivity functions. You should just use the functions. You should just use the ones used below--note that there
ones used below--note that there are different such are different such functions for the less-than, equal, and greater-than
functions for the less-than, equal, and greater-than cases. These must be supplied, or the access method will crash when it
cases. These must be supplied, or the access method tries to use the operator. You should copy the names for restrict and
will crash when it tries to use the operator. You join, but use the procedure names you defined in the last step.
should copy the names for restrict and join, but use
the procedure names you defined in the last step. <programlisting>
<ProgramListing>
CREATE OPERATOR = ( CREATE OPERATOR = (
leftarg = complex, rightarg = complex, leftarg = complex_abs, rightarg = complex_abs,
procedure = complex_abs_eq, procedure = complex_abs_eq,
restrict = eqsel, join = eqjoinsel restrict = eqsel, join = eqjoinsel
) )
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
Notice that five operators corresponding to less, less Notice that five operators corresponding to less, less equal, equal,
equal, equal, greater, and greater equal are defined. greater, and greater equal are defined.
</Para> </para>
<Para> <para>
We're just about finished. the last thing we need to do We're just about finished. the last thing we need to do is to update
is to update the <FileName>pg_amop</FileName> relation. To do this, we need the <filename>pg_amop</filename> relation. To do this, we need the
the following attributes: following attributes:
<TABLE TOCENTRY="1"> <table tocentry="1">
<Title><FileName>pg_amproc</FileName> Schema</Title> <title><filename>pg_amproc</filename> Schema</title>
<TitleAbbrev><FileName>pg_amproc</FileName></TitleAbbrev> <titleabbrev><filename>pg_amproc</filename></titleabbrev>
<TGroup Cols="2"> <tgroup cols="2">
<THead> <thead>
<Row> <row>
<Entry>Attribute</Entry> <entry>Attribute</entry>
<Entry>Description</Entry> <entry>Description</entry>
</Row> </row>
</THead> </thead>
<TBody> <tbody>
<Row> <row>
<Entry>amopid</Entry> <entry>amopid</entry>
<Entry>the <FileName>oid</FileName> of the <FileName>pg_am</FileName> instance <entry>the <filename>oid</filename> of the <filename>pg_am</filename> instance
for B-tree (== 403, see above)</Entry> for B-tree (== 403, see above)</entry>
</Row> </row>
<Row> <row>
<Entry>amopclaid</Entry> <entry>amopclaid</entry>
<Entry>the <FileName>oid</FileName> of the <entry>the <filename>oid</filename> of the
<FileName>pg_opclass</FileName> instance for <FileName>int4_abs_ops</FileName> <filename>pg_opclass</filename> instance for <filename>complex_abs_ops</filename>
(== whatever you got instead of <FileName>17314</FileName>, see above)</Entry> (== whatever you got instead of <filename>17314</filename>, see above)</entry>
</Row> </row>
<Row> <row>
<Entry>amopopr</Entry> <entry>amopopr</entry>
<Entry>the <FileName>oid</FileName>s of the operators for the opclass <entry>the <filename>oid</filename>s of the operators for the opclass
(which we'll get in just a minute)</Entry> (which we'll get in just a minute)</entry>
</Row> </row>
<Row> <row>
<Entry>amopselect, amopnpages</Entry> <entry>amopselect, amopnpages</entry>
<Entry>cost functions</Entry> <entry>cost functions</entry>
</Row> </row>
</TBody> </tbody>
</TGroup> </tgroup>
</TABLE> </table>
The cost functions are used by the query optimizer to The cost functions are used by the query optimizer to decide whether or
decide whether or not to use a given index in a scan. not to use a given index in a scan. Fortunately, these already exist.
Fortunately, these already exist. The two functions The two functions we'll use are <filename>btreesel</filename>, which
we'll use are <FileName>btreesel</FileName>, which estimates the selectivity estimates the selectivity of the <acronym>B-tree</acronym>, and
of the <Acronym>B-tree</Acronym>, and <FileName>btreenpage</FileName>, which estimates the <filename>btreenpage</filename>, which estimates the number of pages a
number of pages a search will touch in the tree. search will touch in the tree.
</Para> </para>
<Para> <para>
So we need the <FileName>oid</FileName>s of the operators we just defined. So we need the <filename>oid</filename>s of the operators we just
We'll look up the names of all the operators that take defined. We'll look up the names of all the operators that take
two <FileName>int4</FileName>s, and pick ours out: two <filename>complex</filename>es, and pick ours out:
<ProgramListing> <programlisting>
SELECT o.oid AS opoid, o.oprname SELECT o.oid AS opoid, o.oprname
INTO TABLE complex_ops_tmp INTO TABLE complex_ops_tmp
FROM pg_operator o, pg_type t FROM pg_operator o, pg_type t
WHERE o.oprleft = t.oid and o.oprright = t.oid WHERE o.oprleft = t.oid and o.oprright = t.oid
and t.typname = 'complex'; and t.typname = 'complex_abs';
+------+---------+ +------+---------+
|oid | oprname | |oid | oprname |
...@@ -438,78 +439,169 @@ CREATE OPERATOR = ( ...@@ -438,78 +439,169 @@ CREATE OPERATOR = (
+------+---------+ +------+---------+
|17325 | &gt; | |17325 | &gt; |
+------+---------+ +------+---------+
</ProgramListing> </programlisting>
(Again, some of your <FileName>oid</FileName> numbers will almost certainly (Again, some of your <filename>oid</filename> numbers will almost
be different.) The operators we are interested in are certainly be different.) The operators we are interested in are those
those with <FileName>oid</FileName>s 17321 through 17325. The values you with <filename>oid</filename>s 17321 through 17325. The values you
get will probably be different, and you should get will probably be different, and you should substitute them for the
substitute them for the values below. We can look at the values below. We will do this with a select statement.
operator names and pick out the ones we just added. </para>
</Para>
<para>
<Para> Now we're ready to update <filename>pg_amop</filename> with our new
Now we're ready to update <FileName>pg_amop</FileName> with our new operator operator class. The most important thing in this entire discussion
class. The most important thing in this entire is that the operators are ordered, from less equal through greater
discussion is that the operators are ordered, from less equal equal, in <filename>pg_amop</filename>. We add the instances we need:
through greater equal, in <FileName>pg_amop</FileName>. We add the
instances we need: <programlisting>
INSERT INTO pg_amop (amopid, amopclaid, amopopr, amopstrategy,
<ProgramListing> amopselect, amopnpages)
INSERT INTO pg_amop (amopid, amopclaid, SELECT am.oid, opcl.oid, c.opoid, 1,
amopopr, amopstrategy, 'btreesel'::regproc, 'btreenpage'::regproc
amopselect, amopnpages) FROM pg_am am, pg_opclass opcl, complex_abs_ops_tmp c
SELECT am.oid, opcl.oid, c.opoid, 3, WHERE amname = 'btree' AND
'btreesel'::regproc, 'btreenpage'::regproc opcname = 'complex_abs_ops' AND
FROM pg_am am, pg_opclass opcl, complex_ops_tmp c c.oprname = '<';
WHERE amname = 'btree' </programlisting>
and opcname = 'complex_abs_ops'
and c.oprname = '='; Now do this for the other operators substituting for the "1" in the
</ProgramListing> third line above and the "<" in the last line. Note the order:
"less than" is 1, "less than or equal" is 2, "equal" is 3, "greater
Note the order: "less than" is 1, "less than or equal" than or equal" is 4, and "greater than" is 5.
is 2, "equal" is 3, "greater than or equal" is 4, and </para>
"greater than" is 5.
</Para> <para>
The next step is registration of the "support routine" previously
<Para> described in our discussion of <filename>pg_am</filename>. The
The last step (finally!) is registration of the <filename>oid</filename> of this support routine is stored in the
"support routine" previously described in our discussion of <filename>pg_amproc</filename> class, keyed by the access method
<FileName>pg_am</FileName>. The <FileName>oid</FileName> of this support routine is stored in <filename>oid</filename> and the operator class <filename>oid</filename>.
the <FileName>pg_amproc</FileName> class, keyed by the access method <FileName>oid</FileName> and First, we need to register the function in
the operator class <FileName>oid</FileName>. First, we need to register the <productname>Postgres</productname> (recall that we put the
function in <ProductName>Postgres</ProductName> (recall that we put the <Acronym>C</Acronym> code <acronym>C</acronym> code that implements this routine in the bottom of
that implements this routine in the bottom of the file the file in which we implemented the operator routines):
in which we implemented the operator routines):
<programlisting>
<ProgramListing> CREATE FUNCTION complex_abs_cmp(complex, complex)
CREATE FUNCTION int4_abs_cmp(int4, int4)
RETURNS int4 RETURNS int4
AS 'PGROOT/tutorial/obj/complex.so' AS 'PGROOT/tutorial/obj/complex.so'
LANGUAGE 'c'; LANGUAGE 'c';
SELECT oid, proname FROM pg_proc SELECT oid, proname FROM pg_proc
WHERE prname = 'int4_abs_cmp'; WHERE proname = 'complex_abs_cmp';
+------+--------------+ +------+-----------------+
|oid | proname | |oid | proname |
+------+--------------+ +------+-----------------+
|17328 | int4_abs_cmp | |17328 | complex_abs_cmp |
+------+--------------+ +------+-----------------+
</ProgramListing> </programlisting>
(Again, your <FileName>oid</FileName> number will probably be different and (Again, your <filename>oid</filename> number will probably be different
you should substitute the value you see for the value and you should substitute the value you see for the value below.)
below.) Recalling that the <Acronym>B-tree</Acronym> instance's oid is We can add the new instance as follows:
403 and that of <FileName>int4_abs_ops</FileName> is 17314, we can add the
new instance as follows: <programlisting>
<ProgramListing>
INSERT INTO pg_amproc (amid, amopclaid, amproc, amprocnum) INSERT INTO pg_amproc (amid, amopclaid, amproc, amprocnum)
VALUES ('403'::oid, -- btree oid SELECT a.oid, b.oid, c.oid, 1
'17314'::oid, -- pg_opclass tuple FROM pg_am a, pg_opclass b, pg_proc c
'17328'::oid, -- new pg_proc oid WHERE a.amname = 'btree' AND
'1'::int2); b.opcname = 'complex_abs_ops' AND
</ProgramListing> c.proname = 'complex_abs_cmp';
</Para> </programlisting>
</Chapter> </para>
<para>
Now we need to add a hashing strategy to allow the type to be indexed.
We do this by using another type in pg_am but we reuse the sames ops.
<programlisting>
INSERT INTO pg_amop (amopid, amopclaid, amopopr, amopstrategy,
amopselect, amopnpages)
SELECT am.oid, opcl.oid, c.opoid, 1,
'hashsel'::regproc, 'hashnpage'::regproc
FROM pg_am am, pg_opclass opcl, complex_abs_ops_tmp c
WHERE amname = 'hash' AND
opcname = 'complex_abs_ops' AND
c.oprname = '=';
</programlisting>
</para>
<para>
In order to use this index in a where clause, we need to modify the
<filename>pg_operator</filename> class as follows.
<programlisting>
UPDATE pg_operator
SET oprrest = 'eqsel'::regproc, oprjoin = 'eqjoinsel'
WHERE oprname = '=' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'neqsel'::regproc, oprjoin = 'neqjoinsel'
WHERE oprname = '<filename>' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'neqsel'::regproc, oprjoin = 'neqjoinsel'
WHERE oprname = '<filename>' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'intltsel'::regproc, oprjoin = 'intltjoinsel'
WHERE oprname = '<' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'intltsel'::regproc, oprjoin = 'intltjoinsel'
WHERE oprname = '<=' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'intgtsel'::regproc, oprjoin = 'intgtjoinsel'
WHERE oprname = '>' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');
UPDATE pg_operator
SET oprrest = 'intgtsel'::regproc, oprjoin = 'intgtjoinsel'
WHERE oprname = '>=' AND
oprleft = oprright AND
oprleft = (SELECT oid FROM pg_type WHERE typname = 'complex_abs');</filename></filename>
</programlisting>
</para>
<para>
And last (Finally!) we register a description of this type.
<programlisting>
INSERT INTO pg_description (objoid, description)
SELECT oid, 'Two part G/L account'
FROM pg_type WHERE typname = 'complex_abs';
</programlisting>
</para>
</chapter>
<!-- 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:
-->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment