OReilly practical PostgreSQL jan 2002 ISBN 1565928466

Use CREATE INDEX to build an optimization index on a specified table, based onone or more of its columns.. Column index You may create an index specifying a list of one or more table col

Practical PostgreSQL

CREATE INDEX

CREATE INDEX Places an index on a table

trees

The PostgreSQL implementation of Lehman-Yao high-concurrency B-rtree

The PostgreSQL implementation of standard R-trees using Guttman'squadratic split algorithm

The PostgreSQL implementation of Litwin's linear hashing

column

The name of the column (or comma-delimited list of columns) on which toplace the index

op_class

The optionally specified associated operator class For most users, thisshould not be specified

func_name

The name of a function you wish CREATE INDEX to use on the specifiedcolumns (rather than on the data values literally in those columns) Thespecified function must return a valid value that can be indexed (e.g., not aset of values)

Use CREATE INDEX to build an optimization index on a specified table, based onone or more of its columns Remember that while indices are designed to

improve the performance and effectiveness of your database, using them ontables whose cost of index maintenance outweighs the practical benefit actually

decreases overall performance.

Column index

You may create an index specifying a list of one or more table columns This isthe "traditional" index type It may be used by queries that directly reference theindexed columns in a WHERE clause Note that R-tree and Hash indices may onlyindex one column, though B-tree indices can index up to sixteen columns

Functional index

An alternate type of index is one called a functional index A functional index is

an index based on the returned value of a function applied to one or more

columns Such an index is useful for queries that use the same function in aWHERE clause frequently.

For example, if you have a query that always references upper(last_name) inits WHERE clause, you could optimized that query by creating a functional index

on upper(last_name)

Operators and operator classes

The PostgreSQL query optimizer will use different indices for different operatorsused in a comparison It will choose which type of index to used based on thepre-defined list shown in Table 14-1

Table 14-1 Operator/index correspondence

Index Operator

B- <, <=,

Practical PostgreSQL

CREATE GROUP

CREATE GROUP Creates a new PostgreSQL group within the database

The user (or comma-delimited list of users) that you wish to automaticallyinclude in the group you are creating The users listed in this parametermust already exist within the database

The error returned if the username in the WITH USER clause does notcurrently exist.

A database superuser can use CREATE GROUP to create a new group in

PostgreSQL A group is a system-wide database object that can be assignedprivileges (with the GRANT command), and have users added to it as members.Members of a group are assigned its privileges by proxy

To modify a group (and the list of users that it is composed of it), use the ALTER GROUP command If you wish to remove a group entirely, use the DROP GROUPcommand

CREATE GROUP

Practical PostgreSQL

CREATE LANGUAGE

CREATE LANGUAGE Defines a new language to be used by functions

functions

PROCEDURAL

The optional PROCEDURAL noise term This may be used to increase

readability of your CREATE LANGUAGE statements, but has no effect

langname

The name of the new procedural language to define This name is caseinsensitive A procedural language will not (and cannot) override an

Results

Note: If you use CREATE LANGUAGE to create a language in the template1database, all subsequent databases that are created from the template1 (thedefault template) will support that language

In order for a procedural language to be used by PostgreSQL, a call handler must

be written for it That call handler must be compiled into a binary form; it istherefore required that the language used to write a handler be one that compilesinto a binary format, such as C or C++

The call handler must be created within PostgreSQL as a function that does notaccept arguments and has a return type of opaque By defining the handler

function in this manner, you enable PostgreSQL to prevent the function (andthus, the language) from ever being used in an arbitrary SQL statement

A handler must already exist for the language in question when you use the

CREATE LANGUAGE command The first step in registering a procedural language

to create a function that specifies the location of object code for the call handler.The following example creates an example call handler, whose object code is

Practical PostgreSQL

CREATE INDEX

CREATE INDEX Places an index on a table

trees

The PostgreSQL implementation of Lehman-Yao high-concurrency B-rtree

The PostgreSQL implementation of standard R-trees using Guttman'squadratic split algorithm

The PostgreSQL implementation of Litwin's linear hashing

column

The name of the column (or comma-delimited list of columns) on which toplace the index

op_class

The optionally specified associated operator class For most users, thisshould not be specified

func_name

The name of a function you wish CREATE INDEX to use on the specifiedcolumns (rather than on the data values literally in those columns) Thespecified function must return a valid value that can be indexed (e.g., not aset of values)

Use CREATE INDEX to build an optimization index on a specified table, based onone or more of its columns Remember that while indices are designed to

improve the performance and effectiveness of your database, using them ontables whose cost of index maintenance outweighs the practical benefit actually

decreases overall performance.

Column index

You may create an index specifying a list of one or more table columns This isthe "traditional" index type It may be used by queries that directly reference theindexed columns in a WHERE clause Note that R-tree and Hash indices may onlyindex one column, though B-tree indices can index up to sixteen columns

Functional index

An alternate type of index is one called a functional index A functional index is

an index based on the returned value of a function applied to one or more

columns Such an index is useful for queries that use the same function in aWHERE clause frequently.

For example, if you have a query that always references upper(last_name) inits WHERE clause, you could optimized that query by creating a functional index

on upper(last_name)

Operators and operator classes

The PostgreSQL query optimizer will use different indices for different operatorsused in a comparison It will choose which type of index to used based on thepre-defined list shown in Table 14-1

Table 14-1 Operator/index correspondence

Index Operator

B- <, <=,

Copyright (c) 2001 by Command Prompt, Inc This material may be distributedonly subject to the terms and conditions set forth in the Open PublicationLicense, v1.0 or later (the latest version is presently available at

http://www.opencontent.org/openpub/)

'Distribution of substantively modified versions of this document is prohibitedwithout the explicit permission of the copyright holder.' to the license reference

or copy

to the license reference or copy

Although every reasonable effort has been made to incorporate accurate anduseful information into this book, the copyright holders make no representationabout the suitability of this book or the information therein for any purpose It is

Creating and Removing a DatabaseMaintaining a Database

Using Variables

Controlling Program Flow

PL/pgSQL and Triggers

COMMIT Ends the current transaction block and finalizes changesmade within it

COPY Copies data between files and tables

CREATE AGGREGATE Defines a new aggregate function withinthe database

CREATE DATABASE Creates a new database in PostgreSQL

CREATE FUNCTION Defines a new function within the database

CREATE GROUP Creates a new PostgreSQL group within thedatabase

CREATE INDEX Places an index on a table

CREATE LANGUAGE Defines a new language to be used by

RESET Restores runtime variables to their default settings

REVOKE Revokes access privileges from a user, a group, or allusers

ROLLBACK Aborts the current transaction block and abandonsany modifications it would have made

SELECT Retrieves rows from a table or view

SELECT INTO Construct a new table from the results of aSELECT

SET Set runtime variables

SET CONSTRAINTS Sets the constraint mode for the currenttransaction block

SET TRANSACTION Sets the transaction isolation level for thecurrent transaction block

SHOW Displays the values of runtime variables

TRUNCATE Empties the contents of a table

UNLISTEN Stops the backend process from listening for anotification event

Next

Practical PostgreSQL

Chapter 14 PostgreSQL Command Reference

COMMENT Adds a comment to an object within the database

COMMIT Ends the current transaction block and finalizes changes madewithin it

COPY Copies data between files and tables

CREATE AGGREGATE Defines a new aggregate function within thedatabase

Each reference entry is broken up into three sections: a synopsis, a description, and an examples section The synopsis contains a syntax diagram, parameter

explanation, and a list of possible results from executing the command Thedescription briefly summarizes the general use of the command The examplessection contains at least one functional example of using the command

PostgreSQL Command

Reference

Practical PostgreSQL

CREATE FUNCTION

CREATE FUNCTION Defines a new function within the database

allows the function to accept arguments of invalid SQL types The opaquetype is generally used by internal functions, or functions written in internallanguage such as C, or PL/pgSQL, where the return type is not provided as

a standard SQL data type

returntype

The data type of the value or values returned by the new function This may

be set as a base type, complex type, setof type (a normal data type,

prefixed by setof), or the opaque type

Using the setof modifier determines that the function will return multiplerows worth of data (by default, a function returns only one row) For

example, a return type defined as setof integer creates a function that canreturn more than a single row of integer values

attribute

definition

The definition of the function to create This is entered as a string, bound byquotes, though its contents vary widely between languages The exact

content of this string may be an internal function name, a SQL statement, orprocedural code in a language such as PL/pgSQL

Results

CREATE

The message returned when a function is created successfully

Differing from PostgreSQL's ability to overload functions based on argumenttypes, two compiled C functions in one object file are unable to share the samename To avoid this problem, you can arbitrarily rename the second C functionthat you wish to overload within PostgreSQL to a unique function name in your

parameter as that arbitrary name when creating the overloaded C function

The following example creates a simple SQL function that returns a book titlebased on the ID number passed to the function:

Practical PostgreSQL

CREATE OPERATOR

CREATE OPERATOR Defines a new operator within the database

The function that implements the the new operator

type1

The type of the left-hand argument Do not use this option with a unaryoperator that always appears to the left of the value on which it operates

type2

The data type of the right-hand argument Do not use this option with aunary operator that always appears to the right of the value on which it

operates

com_op

The commutator operator for the new operator A commutator is anotherexisting operator which executes the commutation (order reversal) of theprocedure defined for the new operator, e.g., with the left argument treated

as the right argument, and the right argument treated as the left argument

neg_op

The negator operator for the new operator A negator is another existingoperator which executes the literal inversion of the procedure define for the

res_proc

The name of the restriction selectivity estimator function for the new

operator This function must already exist, must accept arguments of thesame data types as defined for this new operator, and return a floating pointvalue

join_proc

The name of the join selectivity estimator function for the new operator.This function must already exist, and must be defined to accept arguments

of the same data types as defined for this new operator, and return a floatingpoint value

right_sort_op

The operator that sorts right-hand values, if the new operator can support amerge join

Results

CREATE

The message returned when a new operator is created successfully

Use the CREATE OPERATOR command to define a new operator The PostgreSQLuser that creates the operator becomes the operator owner when creation issuccessful

The operator name is a character sequence up to 31 characters in length

Characters in the operator name must be within the following list of acceptedcharacters:

+ - * / < > = ~ ! @ # % ^ & | ` ? $

There are some restrictions on allowed character sequences for the name:

The dollar sign ($) is only allowed within an operator name consisting ofmultiple characters It cannot be specified as single-character operatorname

The double-dash (- -) and the forward slash and star ( /*) character

combinations cannot appear anywhere in an operator name, as they will beinterpreted as the start of a comment

A multiple character operator cannot end with a plus sign (+) or dash (-),unless the name also contains at least one of the following characters:Tilde (~)

you should make it a habit to separate adjacent operators with a space toclearly define your intended meaning

When you create an operator , you must include at least one LEFTARG or oneRIGHTARG (as the operator must take an argument) If you are defining a binary

operator (one which operators on a value to the left and right of the operator),

both the LEFTARG and RIGHTARG must be specified If you are creating a rightunary operator, you will only need to define LEFTARG; likewise, when creating aleft unary operator, you will only need to define RIGHTARG

Note: The function you specify as the func_name parameter when creating

an operator must have been defined to accept the correct number of

arguments for that operator

For the query optimizer to correctly reverse the order of operands, it needs toknow what the commutator operator is (if it exists) For some operators, a

commutator should exist (or at least, the existence of one would make sense).For example, the commutator of the greater-than symbol (>) is the less-than (<)symbol, and it makes sense that both of these should exist, and be related to oneanother in this fashion With this information, your operator order can easily bereversed, changing something like x < y to y > x if the query optimizer finds it

to be more efficient

In the same way that specifying the commutator operator can help the optimizer,

so can specifying a negator operator (if one exists) The negator to the equalssign (=) is !=, signifying not-equals or not-equivalent When a negator is

specified, the query optimizer can simplify statements like this: