advertisement
Teradata Aster MapReduce Appliance 2
Database SQL and Function Reference
Version 4.6.2 — December 14, 2011
Updated versions of this guide: http://tays.teradata.com
Contents
............................................................................................................................................................. V--v
Conventions Used in This Guide
............................................................................................................... V--v
................................................................................................................ V--vi
....................................................................................................................................... V--vi
............................................................................................................................... V--vii
Aster SQL and Function Reference
V--1
V--3
V--6
................................................................................................................................................. V--7
V--7
............................................................................................................................................. V--8
.................................................................................................................................................. V--9
................................................................................................................................................. V--15
V--16
V--17
.......................................................................................................................................................... V--18
............................................................................................................................................................ V--20
.......................................................................................................................................................... V--20
...................................................................................................................................................... V--21
.................................................................................................................................................. V--22
...................................................................................................................................................... V--22
........................................................................................................................................................... V--23
V--28
............................................................................................................................................ V--29
V--31
V--32
............................................................................................................................................. V--34
V--42
.............................................................................................................................................. V--43
V--45
..................................................................................................................................................... V--46
......................................................................................................................................................... V--49
........................................................................................................................................ V--51
V--51
December 14, 2011 V--i
................................................................................................................................................. V--52
........................................................................................................................................... V--53
V--53
V--54
................................................................................................................................................. V--55
.............................................................................................................................................................. V--56
V--57
V--57
V--61
V--64
V--66
V--69
...................................................................................................................................................... V--70
....................................................................................................................................................... V--71
................................................................................................................................................... V--74
......................................................................................................................................................... V--75
V--83
V--85
................................................................................................................................. V--87
V--88
V--89
..................................................................................................................................................... V--92
V--94
V--95
V--95
V--96
Mathematical Operators and Functions
............................................................................................... V--97
V--99
String Functions and Operators
............................................................................................................ V--100
Bit String Functions and Operators
....................................................................................................... V--103
.................................................................................................................. V--103
V--104
V--108
Datatype Formatting Functions and Operators
................................................................................. V--121
V--123
.............................................................................................................................. V--130
Aggregate Functions for Statistics
........................................................................................................ V--130
V--131
V--133
V--137
V--137
V--138
.............................................................................................................. V--139
V--145
.............................................................................................................. V--146
Repartitioning Performance for Window Functions and SQL-MapReduce Queries .....................
V--154
............................................................................................................................. V--154
V--155
V--157
.................................................................................................................. V--157
......................................................................................................................................... V--159
V--ii Database SQL and Function Reference, version 4.6.2
aster data
...................................................................................................................................... V--163
..................................................................................................................................... V--165
V--169
......................................................................................................................................... V--169
V--170
.......................................................................................................................... V--172
................................................................................................................................................. V--178
V--179
V--181
V--181
V--182
V--185
Introduction to Data Dictionary Views
................................................................................................. V--186
User-Related Data Dictionary Views
..................................................................................................... V--186
V--187
Group Membership Data Dictionary Views
........................................................................................ V--187
Database-Related Data Dictionary Views
.......................................................................................... V--187
Schema-Related Data Dictionary Views
............................................................................................. V--188
V--188
V--190
Column-Related Data Dictionary Views
.............................................................................................. V--190
Index-Related Data Dictionary Views
.................................................................................................. V--191
Constraint-Related Data Dictionary Views
.......................................................................................... V--191
V--192
Inheritance-Related Data Dictionary Views
........................................................................................ V--193
.................................................................................................................. V--193
Cluster State Data Dictionary Views
.................................................................................................... V--193
V--194
Temporary Data Dictionary Views
........................................................................................................ V--198
V--199
V--199
V--201
................................................................................................................................... V--201
............................................................................................................................................. V--203
................................................................................................................................................ V--205
V--211
December 14, 2011 V--iii
V--iv Database SQL and Function Reference, version 4.6.2
aster data
Preface
This guide provides data analysts and database administrators with detailed explanations of functions, SQL commands, datatypes, and error codes in Aster Database.
You can download other useful tools and documents from asterdata.com/support
. In addition, the Aster Data Resource Center at https://everest.asterdata.com/resourcecenter
provides documents, videos, and downloadable client software for various operating systems.
Conventions Used in This Guide
This document assumes that the reader is comfortable working in Windows and Linux/UNIX environments. Many sections assume you are familiar with SQL.
This document uses the following typographical conventions.
Typefaces
Command line input and output, commands, program code, filenames, directory names, and system variables are shown in a monospaced
font. Words in italics indicate an example or placeholder value that you must replace with a real value. Bold type is intended to draw your attention to important or changed items.
SQL Text Conventions
In the SQL synopsis sections, we follow these conventions
•
•
Square brackets ([ and ]) indicate one or more optional items.
Curly braces ({ and }) indicate that you must choose an item from the list inside the braces.
Choices are separated by vertical lines (|).
December 14, 2011 Aster Data proprietary and confidential V--v
Contacting Technical Support Aster Data proprietary and confidential
•
•
•
En ellipsis (...) means the preceding element can be repeated.
A comma and an ellipsis (, ...) means the preceding element can be repeated in a comma-separated list.
In command line instructions, SQL commands and shell commands are typically written with no preceding prompt, but where needed the default Aster Database SQL prompt is shown: beehive=>
Command Shell Text Conventions
For shell commands, the prompt is usually shown. The $ sign introduces a command that’s being run by a non-root user:
$ ls
The # sign introduces a command that’s being run as root:
# ls
Contacting Technical Support
If you need the latest documentation or client software, check the Aster Data Resource Center at https://everest.asterdata.com/resourcecenter
. Here you will find the latest documents, videos, and downloadable client software for various operating systems..
For further assistance, contact Aster Data technical support.
Support Portal: to http://tays.teradata.com
.
Email: [email protected]
Telephone: +1-650-273-5599
About Aster Data
Aster Data provides data management and advanced analytics for diverse and big data, enabling the powerful combination of cost-effective storage and ultra-fast analysis of relational and non-relational data. Aster Data is a division of Teradata and is headquartered in San Carlos,
California. For more information, go to http://tays.teradata.com
.
V--vi Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential About This Document
About This Document
This is the “Aster Data Teradata Aster MapReduce Appliance 2 Database SQL and Function
Reference,” version 4.6.2, edition B035-5488-121K. This edition covers Aster Database version
4.6.2_r27284 and was published December 14, 2011. You can open the HTML-formatted version of this document by clicking the Help link in the Aster Database AMC.
Get the latest edition of this guide! This guide updated very frequently. You can find the latest edition at www.asterdata.com/support
Copyright and Legal Statements
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, Aster Data, nCluster, SQL-MapReduce, Aprimo, BYNET, DBC/1012, DecisionCast,
DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce,
SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts,
WebAnalyst, "More Data. Big Insights," and "You’ve Never Seen Your Business Like This
Before" are trademarks or registered trademarks of Teradata Corporation or its affiliates.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc.
EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of GoldenGate Software, Inc.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business
Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI and Engenio are registered trademarks of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun
Microsystems, Inc., in the United States and other countries.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec
Corporation or its affiliates in the United States and other countries.
Unicode is a collective membership mark and a service mark of Unicode, Inc.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
December 14, 2011 V--vii
About This Document Aster Data proprietary and confidential
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS-IS”
BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT
ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE
LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country.
Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice.
If you’d like to help maintain the quality of this documentation, please send us your comments on the accuracy, clarity, organization, and usefulness of this document. You can send your comments to [email protected].
Any comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 2011 by Teradata Corporation. All Rights Reserved.
www.asterdata.com
Document revision history:
December, 2011: 4.6.2
V--viii Database SQL and Function Reference, version 4.6.2
aster data
Volume V: Aster SQL and
Function Reference
•
•
•
•
•
•
•
•
•
This volume of the guide explains the SQL commands available in Aster Database. Later sections list all functions and operators, date and time constraints, and error codes. The subsections are:
Functions and Operators (page V-95)
Data Dictionary Views (page V-185)
December 14, 2011 V--1
V--2 Database SQL and Function Reference, version 4.6.2
aster data
V--1
SQL Commands
This chapter provides a reference for SQL and SQL-like commands supported in Aster Database.
To find the command descriptions, follow the cross references in the table below. This table also lists Aster Data / PostgreSQL syntactic compatibility.
Table 1-1 Aster Data/PostgreSQL Command Compatibility
Statement Supported in Aster
Database?
Supported in
PostgreSQL?
Notes
CHECKPOINT
COMMENT
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
NO
Yes
Yes
Yes
NO
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
December 14, 2011 Aster Data proprietary and confidential V--3
Aster Data proprietary and confidential
Statement
DEALLOCATE
EXECUTE
GREATEST and LEAST (page V-133)
LISTEN
LOAD
LOCK
NOTIFY
PREPARE
PREPARE TRANSACTION
NO
Yes
Yes
Yes
NO
Yes
NO
NO
Supported in Aster
Database?
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
NO
Yes
NO
Yes
Yes
Yes
NO
Yes
Yes
Yes
Yes
NO
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Supported in
PostgreSQL?
Notes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
To load a function, use Aster
Database ACT’s
\install command.
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
V--4 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Statement
REASSIGN OWNED
RELEASE SAVEPOINT
RESET
SAVEPOINT
UNLISTEN
Supported in Aster
Database?
NO
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
NO
Yes
NO
Yes
NO
NO
Supported in
PostgreSQL?
Notes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
December 14, 2011 SQL Commands V--5
ABORT
ABORT
Aster Data proprietary and confidential
ABORT -- abort the current transaction
Synopsis
ABORT [ WORK | TRANSACTION ];
Description
ABORT rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical in behavior to the standard SQL command ROLLBACK .
Parameters
WORK and TRANSACTION These are optional keywords.
Notes
Use
COMMIT
to successfully terminate a transaction.
Issuing
ABORT
when not inside a transaction does no harm.
Examples
To abort all changes:
ABORT;
Compatibility
This command is an Aster Database extension.
ROLLBACK
is the equivalent standard SQL command.
See Also
To initiate a transaction:
•
•
To finish a transaction:
•
•
To cancel a transaction:
•
V--6 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential ALTER ROLE
ALTER INDEX
ALTER INDEX -- change the definition of an index
Synopsis
ALTER INDEX name RENAME TO new_name;
Description
ALTER INDEX changes the name of an existing index. There is no effect on the stored data.
Parameters name The name of an existing index to alter. new_name New name for the index.
Notes
These operations are also possible using
ALTER TABLE
. The phrase
ALTER INDEX
is in fact just an alias for the forms of
ALTER TABLE
that apply to indexes.
Examples
To rename an existing index:
ALTER INDEX distributors RENAME TO suppliers;
Compatibility
ALTER INDEX is an Aster Database extension.
ALTER ROLE
ALTER ROLE -- change a database role
Synopsis
ALTER ROLE name [ [ WITH ] option [ ... ] ] where option can be:
INHERIT | NOINHERIT
ALTER ROLE name RENAME TO newname
December 14, 2011 SQL Commands V--7
ALTER SCHEMA Aster Data proprietary and confidential
Description
ALTER ROLE changes the attributes of a database role.
The first variant of this command listed in the synopsis can change many of the role attributes that can be specified in CREATE ROLE. All the possible attributes are covered, except that there are no options for adding or removing memberships; use GRANT and REVOKE for that.
Attributes not mentioned in the command retain their previous settings. A superuser can change any of these settings.
The second variant changes the name of the role. Users and roles having the db_admin
privilege can rename roles.
Parameters name
- The name of the role whose attributes are to be altered.
INHERIT
,
NOINHERIT
- These clauses alter attributes originally set by CREATE ROLE. For more information, see the CREATE ROLE reference page.
newname
- The new name of the role.
Notes
Use
CREATE ROLE
to add new roles, and
DROP ROLE
to remove a role.
ALTER ROLE
cannot change a role's memberships. Use
GRANT and
REVOKE
to do that.
Compatibility
The
ALTER ROLE
statement is an Aster Database extension.
See Also
,
.
ALTER SCHEMA
Synopsis
ALTER SCHEMA name RENAME TO newname
ALTER SCHEMA name OWNER TO newowner
Description
ALTER SCHEMA changes the definition of a schema.
You must own the schema to use ALTER SCHEMA. To rename a schema you must also have the
CREATE privilege for the database. To alter the owner, you must also be a direct or indirect member of the new owning role, and you must have the CREATE privilege for the database.
Parameters name The name of an existing schema.
V--8 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential ALTER TABLE newname The new name of the schema. The new name cannot begin with nc_, as such names are reserved for system schemas.
newowner The new owner of the schema.
See Also
and “DROP SCHEMA” on page V-53 .
ALTER TABLE
ALTER TABLE -- change the definition of a table
Synopsis
ALTER TABLE [ ONLY ] name
action [, ... ];
ALTER TABLE [ ONLY ] name
RENAME [ COLUMN ] column TO new_column;
ALTER TABLE name
RENAME TO new_name;
ALTER TABLE name
SET SCHEMA new_schema;
ALTER TABLE name
ATTACH PARTITION new_partition_name (
attach_partition_list | attach_partition_range
) FROM old_table_name;
ALTER TABLE name
ALTER partition_reference ATTACH PARTITION new_partition_name (
attach_partition_list | attach_partition_range
) FROM old_table_name
ALTER TABLE name
ALTER partition_reference { NOCOMPRESS | COMPRESS [HIGH | MEDIUM | LOW] };
ALTER TABLE name
ALTER partition_reference RENAME TO new_partition_name;
ALTER TABLE name
DETACH partition_reference INTO new_table_name; where action is one of:
ADD [ COLUMN ] columnname datatype [ DEFAULT default_value ] [ column_constraint
[ ... ] ]
DROP [ COLUMN ] column [ RESTRICT | CASCADE ]
ALTER [ COLUMN ] column TYPE type [ USING expression ]
ALTER [ COLUMN ] column { SET | DROP } NOT NULL
December 14, 2011 SQL Commands V--9
ALTER TABLE Aster Data proprietary and confidential
ALTER [ COLUMN ] column SET DEFAULT default_value
ADD table_constraint
DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ]
NOCOMPRESS | COMPRESS [ HIGH | MEDIUM | LOW ]
INHERIT parent_table
NO INHERIT parent_table
OWNER TO new_owner where attach_partition_list is:
VALUES ( value_list ) where attach_partition_range is:
START { constant [ INCLUSIVE | EXCLUSIVE ] | MINVALUE }
END { constant [INCLUSIVE | EXCLUSIVE ] | MAXVALUE } where partition_reference is:
PARTITION ( partition_name [. partition_name ...] )
Description
ALTER TABLE changes the definition of an existing table.
You must own the table to use ALTER TABLE . To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the table.
(These restrictions ensure that altering the owner doesn't do anything you couldn't do by dropping and recreating the table. However, a superuser can alter ownership of any table in any way.)
Actions for ALTER TABLE
ADD COLUMN This form adds a new column to the table, using the same syntax as CREATE
TABLE. In ADD / DROP/ ALTER COLUMN, the keyword COLUMN is noise and can be omitted.
In ADD COLUMN and in ALTER COLUMN SET DEFAULT , the DEFAULT clause allows you to ensure that the column will be set to the default value if no value is provided when a row is inserted or updated. The clause takes the same form as the DEFAULT clause in
. Note that when you add a column, all existing rows in the table are initialized with the column’s DEFAULT value, or with NULL if no DEFAULT clause is specified.
V--10 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential ALTER TABLE
Tip!
In a table that contains many rows, adding a column with a DEFAULT value may take a long time, because Aster Database will add the default value to every existing row. If you wish to add a new column with a DEFAULT rule but not simultaneously add values for existing rows in the table, then you should first perform an
ALTER TABLE ADD COLUMN
without a
DEFAULT rule, and then perform a second
ALTER TABLE ALTER column_name SET
DEFAULT
to add the rule without inserting default values for existing rows.
DROP COLUMN This form drops a column from a table. If the table has indexes and table constraints that involve the column, those will be dropped automatically. If a view (or any other object outside the table) depends on the column, then you can add the keyword
CASCADE
to force the dropping of those dependent entities.
A recursive
DROP COLUMN
operation will remove a child or descendant table's column only if the descendant (a) does not inherit that column from any other parents and (b) never had an independent definition of the column.
Note: The
DROP COLUMN
form does not physically remove the column, but simply makes it invisible to SQL operations. Subsequent insert and update operations in the table will store a null value for the column. Thus, dropping a column is quick but it will not immediately reduce the on-disk size of your table, as the space occupied by the dropped column is not reclaimed. The space will be reclaimed over time as existing rows are updated.
ALTER COLUMN TYPE This form changes the type of a column of a table. Indexes and simple table constraints involving the column will be automatically converted to use the new column type by re-parsing the originally supplied expression. The optional USING clause specifies how to compute the new column value from the old; if omitted, the default conversion is the same as an assignment cast from old datatype to new. A USING clause must be provided if there is no implicit or assignment cast from old to new type.
Note: The fact that
ALTER TYPE
requires rewriting the whole table is sometimes an advantage, because the rewriting process eliminates any dead space in the table. For example, to reclaim the space occupied by a dropped column immediately, the fastest way is
ALTER TABLE table ALTER COLUMN anycol TYPE anytype; where anycol
is any remaining table column and anytype
is the same type that column already has. This results in no semantically-visible change in the table, but the command forces rewriting, which gets rid of no-longer-useful data.
SET/DROP NOT NULL These forms change whether a column is marked to allow null values or to reject null values. You can only use
SET NOT NULL
when the column contains no null values.
ADD table_constraint This form adds a new constraint to a table using the same syntax as
CREATE TABLE
. You cannot add
DISTRIBUTE BY
(or the now deprecated
PARTITION
KEY)
table constraints; see “Notes About ALTER TABLE” on page V-13
.
Adding a
CHECK
or
NOT NULL
constraint requires scanning the table to verify that existing rows meet the constraint.
In parent-child table hierarchies, adding a constraint to the parent cascades to the child only for
CHECK constraints.
DROP CONSTRAINT This form drops the specified constraint on a table. You cannot drop
DISTRIBUTE BY
(or the now deprecated
PARTITION KEY)
table constraints; see
About ALTER TABLE” on page V-13 .
December 14, 2011 SQL Commands V--11
ALTER TABLE Aster Data proprietary and confidential
ALTER TABLE test_table DROP CONSTRAINT my_constraint;
NOCOMPRESS | COMPRESS [HIGH | MEDIUM | LOW] This form alters the level of table compression to the level specified. It can change a compressed table to uncompressed, an uncompressed table to a specified level of compressions, or a compressed table to a different level of compression. See “Compression” on page II-8 for an overview of compression in Aster
Database.
INHERIT/NO INHERIT This form changes whether or not the table has an inheritance relationship with the specified parent table.
OWNER This form changes the owner of the table to the specified user. Changing the
OWNER never recurses to child tables.
ATTACH PARTITION This form takes an existing table and attaches it as a partition of an existing logically partitioned table. The tables do not need to reside in the same schema. Any table in a schema other than the current schema must be schema qualified. The database user must be an owner of both tables, and must possess the USAGE privilege for the schema(s).
ATTACH PARTITION takes as an argument either the list of values (for a PARTITION BY LIST table) or the range of values (for a PARTITION BY RANGE table) for the partition to be created.
These may not overlap with the definitions of any existing partitions of the partitioned table.
Furthermore, if the data within the table to be partitioned falls outide of the list or range of values for that partition to be created, the ATTACH will fail.
See ALTER TABLE...ATTACH PARTITION (page I-20) for more information on requirements for a table to be attached as a partition. Any existing constraints will be stripped from the table being attached and replaced with the constraints from the top level table in the partitioned table hierarchy.
DETACH PARTITION This form takes an existing partition and detaches it from its parent logically partitioned table, creating a new standalone table. The new table that is created will have the same constraints as the top level table in the partitioned table hierarchy. The detached table will be created in the same schema as the original parent table, unless another schema is specified. This operation is used when a subsequent operation must be performed on the child partition in isolation of its parent (e.g. DROP). See ALTER TABLE...ATTACH PARTITION
(page I-20) for more information.
ALTER PARTITION...NOCOMPRESS | COMPRESS [HIGH | MEDIUM | LOW] This form takes an existing partition and compresses it (or uncompresses it). If the compression is changed on a partition with sub-partitions, then each sub-partition will be compressed or uncompressed in the same way. See “Compression” on page II-8 for more information on compression.
RENAME The
RENAME
forms change the name of a table (or an index, sequence, or view) or the name of an individual column in a table. There is no effect on the stored data.
ALTER PARTITION...RENAME
takes an existing partition and renames it.
SET SCHEMA Moves the table into another schema. Associated indexes, constraints, and sequences owned by table columns are moved as well. The parameter new_schema is the name of the new schema for the table.
V--12 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential ALTER TABLE
Parameters for ALTER TABLE
The parameters for ALTER TABLE are:
name column new_column new_name type table_constraint constraint_name
CASCADE
RESTRICT
parent_table new_owner new_schema partition_reference new_partition_name old_table_name new_table_name
The name (possibly schema-qualified) of an existing table to alter. If
ONLY
is specified, only that table is altered. If
ONLY
is not specified, the table and all its child and descendant tables (if any) are updated.
Name of a new or existing column.
New name for an existing column.
New name for the table.
Datatype of the new column, or new datatype for an existing column.
New table constraint for the table. See
“Notes About ALTER TABLE” , below.
Name of an existing constraint to drop. See
, below.
Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column).
Refuse to drop the column or constraint if there are any dependent objects. This is the default behavior.
The table name of the new parent table.
The username of the new owner of the table.
The name of the new schema of which the table will be a member.
The reference to the individual partition of a logically partitioned table hierarchy.
The syntax is as follows:
partition_reference = PARTITION ( partition_name [. partition_
name ...] )
Note that to refer to a partition several level down the hierarchy, you must list each of the partitions in order, separated by “.”, and then the child partition you wish to access. For example, to refer to the partition three levels down the partition hierarchy with the name “2001_11_30” you would reference it as (year2001.2001_
november.2001_11_30).
The new name to give the partition, when renaming an existing partition.
The name of the table to be attached to a logically partitioned table as a new partition.
The name of the new table created when detaching a partition.
See “CREATE TABLE” on page V-34
for a further description of valid parameters.
Notes About ALTER TABLE
You cannot modify a distribution key column in any way. (See “Rules for distribution keys” on page I-10 .) This means:
•
•
There is no ALTER TABLE support for changing the DISTRIBUTE BY method of a table.
Instead, use a CTAS statement to re-create a new table with the distribution key you want.
For tables that use the legacy
PARTITION KEY
syntax:
• DROP CONSTRAINT
cannot drop
PARTITION KEY
table constraints.
• ADD table_constraint
cannot add
PARTITION KEY
table constraints.
ALTER TABLE Examples
To add a column of type varchar
to a table:
December 14, 2011 SQL Commands V--13
ALTER TABLE Aster Data proprietary and confidential
ALTER TABLE distributors ADD COLUMN address varchar(30);
To drop a column from a table:
ALTER TABLE distributors DROP COLUMN address RESTRICT;
To change the types of two existing columns in one operation:
ALTER TABLE distributors
ALTER COLUMN address TYPE varchar(80),
ALTER COLUMN name TYPE varchar(100);
To change an integer column containing UNIX timestamps to timestamp with time zone via a
USING
clause:
ALTER TABLE sales_fact
ALTER COLUMN sales_timestamp TYPE timestamp with time zone
USING
timestamp with time zone 'epoch' + sales_timestamp * interval '1 second';
To attach a table to a logically partitioned table as a new partition:
ALTER TABLE distributors
ATTACH PARTITION north_america (
VALUES ('US','Canada')
) FROM north_america_distributors;
To detach a partition from a logically partitioned table:
ALTER TABLE distributors DETACH PARTITION (asia) INTO asia_distributors;
To rename a partition:
ALTER TABLE distributors ALTER PARTITION (asia) RENAME TO asiapac;
To compress a partition:
ALTER TABLE distributors ALTER PARTITION (asia) COMPRESS LOW;
To rename an existing column:
ALTER TABLE distributors RENAME COLUMN address TO city;
To rename an existing table:
ALTER TABLE distributors RENAME TO suppliers;
To add a not-null constraint to a column:
ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
To remove a not-null constraint from a column:
ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
To add a check constraint to a table:
V--14 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_ length(zipcode) = 5);
To remove a check constraint from a table and all its children:
ALTER TABLE distributors DROP CONSTRAINT zipchk;
ALTER USER
Compatibility of ALTER TABLE
The
ADD
and
DROP
forms conform to the SQL standard. The other forms are Aster Database extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single
ALTER TABLE
command is an Aster Database extension.
ALTER TABLE DROP COLUMN
can be used to drop the only column of a table, leaving a zero-column table. This is an extension of SQL, and it violates the SQL rule that disallows zero-column tables.
ALTER USER
ALTER USER - changes attributes of a user
Synopsis
First variant:
ALTER USER username [ [ WITH ] option [ ... ] ] where option can be:
INHERIT | NOINHERIT | PASSWORD 'password'
Second variant:
ALTER USER username RENAME TO newname;
Third variant:
ALTER USER username SET search_path { TO | = } { value }
Example usage
ALTER USER owright PASSWORD '1st1nFlight';
ALTER USER owright RENAME TO orvillew;
ALTER USER orvillew SET search_path TO capmkts,fixedinc,public;
Description
ALTER USER changes the attributes of a database user.
The first variant of this command listed in the synopsis can change many of the user attributes that can be specified in
. All the possible attributes are covered, except that there
December 14, 2011 SQL Commands V--15
ALTER VIEW Aster Data proprietary and confidential are no options for adding or removing memberships; use
for that.
Attributes not mentioned in the command retain their previous settings. A superuser can change any of these settings. Ordinary users can only change their own password.
The second variant (
RENAME
) changes the name of the user. A superuser can change any of these settings. The current session user cannot be renamed. Connect as a different user if you need to do that. Note that when a user is renamed, the password for that user is reset to be the same as the new username. It is recommended that renaming a user and setting a new password for a user be done as part of the same transaction to avoid any security issues.
The third variant sets the default schema search path of the user. See the description of search_path
, below. When the user subsequently starts a new session, the specified schema search path is used as his default.
Parameters username
- The name of the user whose attributes are to be altered.
INHERIT | NOINHERIT
- These clauses alter attributes originally set by CREATE USER. For more information, see
PASSWORD 'password'
- Sets the user’s password to password
.
newname
- The new name of the user.
search_path
- An ordered, comma-separated list of existing schema names that will be the user’s default schema search path. When Aster Database tries to resolve an unqualified object name, it searches these schemas in the order specified here. If the user creates an object without qualifying its name with a schema, the object is created in her current schema, which, by default,
is the first schema in the search path. The user can override this default using the “ SET search_
path” command. For more details, see “Schema Search Path” on page II-108 .
Compatibility
The
ALTER USER
statement is an Aster Database extension. The SQL standard leaves the definition of users to the implementation.
See Also
ALTER VIEW
ALTER VIEW -- change the definition of a view
Synopsis
ALTER VIEW name RENAME TO newname;
Description
ALTER VIEW
changes the definition of a view. The only currently available functionality is to rename the view. To execute this command you must be the owner of the view.
V--16 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Parameters name The name (optionally schema-qualified) of an existing view. newname The new name of the view.
Notes
In Aster Database, you cannot change the schema or owner of a view.
Examples
To rename the view foo to bar:
ALTER VIEW foo RENAME TO bar;
Compatibility
ALTER VIEW is a PostgreSQL extension of the SQL standard.
See Also
CREATE VIEW, DROP VIEW
ANALYZE
ANALYZE
ANALYZE -- collect statistics about a database
Synopsis
ANALYZE table [ (column [, ...] ) ] [ CASCADE ]
Description
ANALYZE
collects statistics about the contents of the specified table in the database and stores the results in internal tables. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries.
You have the option of specifying one or more column names, in which case only the statistics for those columns are collected. If your table has child tables created through inheritance, don’t forget to include the
CASCADE
option. If the table is a logically partitioned table,
ANALYZE automatically acts on the whole hierarchy.
December 14, 2011 SQL Commands V--17
BEGIN Aster Data proprietary and confidential
Parameters table column
CASCADE
The name of a table to analyze.
The name of a column to analyze. This defaults to all columns.
Also analyzes all children of the named table.
Outputs from ANALYZE
None.
Notes About ANALYZE
It is a good idea to run ANALYZE periodically, or just after making major changes in the contents of a table. Accurate statistics will help the planner to choose the most appropriate query plan, and thereby improve the speed of query processing. Also, the information provided by the
EXPLAIN command is only as current as the last running of
ANALYZE
.
Aster Data recommends that you run
ANALYZE
after every batch of writes so that the statistics are refreshed in bulk. You should run
ANALYZE
after any running of a
CREATE TABLE AS
SELECT
,
INSERT
,
UPDATE
,
DELETE
, or
ALTER TABLE
statement. A common strategy is to run
VACUUM and ANALYZE once a day during a low-usage time of day.
Unlike VACUUM FULL , the ANALYZE command requires only a read lock on the target table, so it can run in parallel with other activity on the table.
The statistics collected by ANALYZE usually include a list of some of the most common values in each column and a histogram showing the approximate data distribution in each column. One or both of these may be omitted if ANALYZE deems them uninteresting (for example, in a unique-key column, there are no common values) or if the column datatype does not support the appropriate operators.
Compatibility
There is no
ANALYZE
statement in the SQL standard.
See Also
and
“5.3. Run ANALYZE regularly to ensure Aster Database produces the most optimal query plans” on page II-63 .
BEGIN
BEGIN -- start a transaction block
Synopsis
BEGIN [ WORK | TRANSACTION ];
Description
BEGIN
initiates a transaction block, that is, all statements after a
BEGIN
command will be executed in a single transaction until an explicit
COMMIT or
ROLLBACK
is given. By default
V--18 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential BEGIN
(without
BEGIN
), each statement is executed in its own transaction and a commit is implicitly performed at the end of the statement (if execution was successful, otherwise a rollback is done).
In Aster Database, all statements are executed in an individual transaction by default. Grouping multiple statements together into an explicit transaction block not only provides transactional atomicity, but allows transaction costs to be shared across multiple statements. When executing modifying statements, it is highly recommended that these be grouped into a transaction, as they will require replication across Aster Database.
Parameters
WORK Optional keyword. Has no effect.
TRANSACTION Optional keyword. Has no effect.
Notes
START TRANSACTION
has the same functionality as
BEGIN
.
Use
COMMIT
or
ROLLBACK
to terminate a transaction block.
Issuing
BEGIN when already inside a transaction block will not affect the state of the transaction.
Examples
To begin a transaction block:
BEGIN;
Compatibility
BEGIN
is an Aster Database language extension. It is equivalent to the SQL-standard command
START TRANSACTION
. Click on this link for additional compatibility information.
Warning! The
BEGIN
keyword is used for a different purpose in embedded SQL. You are advised to be careful about the transaction semantics when porting database applications.
See Also
To initiate a transaction:
•
To finish a transaction:
•
•
To cancel a transaction:
•
•
December 14, 2011 SQL Commands V--19
CASE
CASE
.
CLOSE
Aster Data proprietary and confidential
CLOSE -- close a cursor
Synopsis
CLOSE name;
Description
CLOSE frees the resources associated with an open cursor. After the cursor is closed, no subsequent operations are allowed on it. A cursor should be closed when it is no longer needed.
Every non-holdable open cursor is implicitly closed when a transaction is terminated by COMMIT or ROLLBACK . A holdable cursor is implicitly closed if the transaction that created it aborts via
ROLLBACK.
If the creating transaction successfully commits, the holdable cursor remains open until an explicit CLOSE is executed, or the client disconnects.
Parameters for CLOSE name The name of an open cursor to close.
Notes
Aster Database does not have an explicit OPEN cursor statement; a cursor is considered open when it is declared. Use the DECLARE statement to declare a cursor.
Examples
For example, to close the cursor, myappfetch:
CLOSE myappfetch;
Compatibility
CLOSE fully conforms to the SQL standard.
See Also
,
.
V--20 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CLUSTER
CLUSTER
The CLUSTER command clusters a table according to an index, thereby physically re-sorting records on disk according to an index. The goal is to unite on a single disk those records that you might read together.
More:
|
Description | Parameters | Notes
|
Synopsis
CLUSTER tablename [ USING indexname ]
Description
CLUSTER instructs the database to cluster the table specified by tablename
based on the index specified by indexname
. The index must already have been defined on tablename
.
When a table is clustered, it is physically reordered based on the index information. Clustering is a one-time operation: when the table is subsequently updated, the changes are not clustered. That is, no attempt is made to store new or updated rows according to their index order.
When a table is clustered, the database remembers which index it was clustered by. The form
CLUSTER tablename
re-clusters the table using the same index as before.
When a table is being clustered, an exclusive access lock is acquired on it. This prevents any other database operations (both reads and writes) from operating on the table until the CLUSTER is finished.
Parameters tablename The name (possibly schema-qualified) of a table.
indexname The name of an index.
Notes
In cases where you are accessing single rows randomly within a table, the actual order of the data in the table is unimportant. However, if you tend to access some data more than others, and there is an index that groups them together, you will benefit from using CLUSTER. If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, CLUSTER will help because once the index identifies the table page for the first row that matches, all other rows that match are probably already on the same table page, and so you save disk accesses and speed up the query.
During the cluster operation, a temporary copy of the table is created that contains the table data in the index order. Temporary copies of each index on the table are created as well. Therefore, you need free space on disk at least equal to the sum of the table size and the index sizes.
It is advisable to run ANALYZE on the newly clustered table to ensure that future query plans make good choices.
It is also important to note that, in the Aster Database implementation, clustering is done at the level of workers. There is no notion of a global clustering. However, if the index on which the clustering is done includes the distribution key, you create the effect of global clustering.
December 14, 2011 SQL Commands V--21
COALESCE Aster Data proprietary and confidential
Examples
Cluster the table employees on the basis of its index employees_ind:
CLUSTER employees USING employees_ind;
Cluster the employees table using the same index that was used before:
CLUSTER employees;
Compatibility
There is no CLUSTER statement in the SQL standard. Our syntax is however compatible with
PostgreSQL. PostgreSQL also allows an unqualified CLUSTER command that performs clustering on all tables in the system. Aster Database does not allow that since it may be too expensive an operation, and would disallow any access to any of the tables while it runs.
COALESCE
See “COALESCE” on page V-132 .
COMMIT
COMMIT -- commit the current transaction
Synopsis
COMMIT [ WORK | TRANSACTION ];
Description
COMMIT
commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs. This command is equivalent to the
Aster Database command END.
Parameters
WORK Optional keyword. Has no effect.
TRANSACTION Optional keyword. Has no effect.
Notes
Use ROLLBACK to abort a transaction.
Issuing COMMIT when not inside a transaction does no harm.
Examples
To commit the current transaction and make all changes permanent:
COMMIT;
V--22 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential COPY
Compatibility
The SQL standard only specifies the two forms COMMIT and COMMIT WORK . Otherwise, this command is fully conforming.
See Also
To initiate a transaction:
•
•
To finish a transaction:
•
To cancel a transaction:
•
•
COPY
COPY -- copy data between a client and a table
•
•
•
Parameters for COPY (page V-24)
•
•
Input Formats for COPY (page V-26)
•
Example Use of COPY (page V-27)
•
Compatibility of COPY (page V-28)
Synopsis
Copy into Aster Database:
COPY tablename [ ( column [, ...] ) ]
FROM STDIN
[ [ WITH ]
[ DELIMITER [ AS ] 'delimiter' ]
[ NULL [ AS ] 'null string' ]
[ CSV [ QUOTE [ AS ] 'quote' ]
[ ESCAPE [ AS ] 'escape' ] ] ]
[ AUTOPARTITION ]
[ LOG ERRORS
[ INTO { errortablename | NOWHERE } ]
[ WITH LABEL label ]
[ ERROR LIMIT { limit | UNLIMITED } ]
]
December 14, 2011 SQL Commands V--23
COPY Aster Data proprietary and confidential
Copy from Aster Database:
COPY tablename [ ( column [, ...] ) ]
TO STDOUT
[ [ WITH ]
[ DELIMITER [ AS ] 'delimiter' ]
[ NULL [ AS ] 'null string' ]
[ CSV
[ QUOTE [ AS ] 'quote' ]
[ ESCAPE [ AS ] 'escape' ] ] ];
Description
COPY
moves data between Aster Database tables and a remote client (
STDIN/STDOUT
), via the connection between the client and the server. Specifically,
COPY TO
copies the contents of a table to standard output, while
COPY FROM
copies data from standard input to a table
(appending the data to whatever is in the table already).
If a list of columns is specified,
COPY
will only copy the data in the specified columns to or from the source. If there are any columns in the table that are not in the column list,
COPY FROM
will insert the default value of
NULL
for those columns.
To copy data from one or more files into Aster Database, you can also use the ncluster_loader utility, as explained in “ncluster_loader Client-Side Loading Tool” on page II-130 . The ncluster_
loader tool uses the COPY command to perform the data loading.
Parameters for COPY
Table 1-2 Parameters for COPY tablename column
STDIN
STDOUT delimiter null string
The name of an existing table.
An optional list of columns to be copied. If no column list is specified, all columns of the table will be copied.
Specifies that input comes from the client application.
Specifies that output goes to the client application.
The single character that separates columns within each row (line) of the file.
The default is a tab character in text mode, a comma in CSV mode.
The string that represents a null value. The default is \N (backslash-N) in text mode, and an empty value with no quotes in CSV mode. You might prefer an empty string even in text mode for cases where you don't want to distinguish nulls from empty strings.
When loading any non-CSV delimited format (e.g. TSV), you can easily load files that contain empty strings (that is, files that don’t use the typical "\N" to represent nulls). To do this, use
COPY
with the null
keyword, followed by two double-quote characters. That is, the argument looks like:
null ""
CSV quote
Note: When using
COPY FROM
, any data item that matches this string will be stored as a null value, so you should make sure that it is not a string that might otherwise occur in the input
Selects Comma Separated Value (CSV) mode (by default, the input is expected interpreted using the text format described below).
Specifies the quotation character in CSV mode. The default is double-quote.
V--24 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential COPY escape
Output
AUTOPARTITION
Specifies the character that should appear before a
QUOTE
data character value in CSV mode. The default is the
QUOTE
value (usually double-quote).
On successful completion, a
COPY
command returns a command tag of the form:
COPY count
Where count
is the number of rows copied.
Automatically partitions data during copying. With this feature enabled, Aster
Database automatically routes each row within a logical partition hierarchy down to the appropriate child table. Logical partitioning is done based on the check constraints of the target table. See “Autopartitioning” on page II-141 .
LOG ERRORS Including the LOG ERRORS clause activates error logging. With error logging enabled, the COPY command tolerates poorly formatted input data like this:
COPY logs each malformed row to the appropriate load error logging table and continues loading additional (correctly formed) rows in the current load job.
Aster Data refers to this as “error logging”.
Omitting the LOG ERRORS phrase disables error logging. With error logging disabled, the COPY operation fails immediately when it encounters a malformed row. With error logging disabled, COPY fails or succeeds in an atomic fashion: either all rows are copied, or none are. This feature is also available in the
ncluster_loader tool as shown in “ncluster_loader Client-Side Loading Tool” on page II-130 .
By default, malformed rows for distributed tables go into table nc_ errortable_part
table, and malformed rows for replicated tables go into the nc_errortable_repl
table. Optionally, you can create your own load error logging tables, as explained in “
INTO errortablename
”, below. The schema
for error logging tables is shown in “Load Error Logging Tables” on page V-196
.
To see the number of rows that loaded or failed to load, query the load error statistics tables nc_all_errorlogging_stats
and nc_user_ errorlogging_stats
. For more information, see
INTO 'errortablename'
LOG ERRORS INTO 'errortablename'
specifies the error logging table into which malformed rows should be copied together with detailed error information. You can specify any table that inherits from the appropriate default table, nc_errortable_part
table, or nc_errortable_repl
Load Error Logging Table” on page V-197
.
If
INTO 'errortablename'
is not specified, then malformed rows go into the default tables as explained in
LOG ERRORS
, above.
WITH LABEL
NOWHERE
ERRORLIMIT limit
WITH LABEL 'label' tags failed rows with 'label'. The label is useful for finding your failed rows in the error logging table and for finding statistics about the load attempt in the nc_all_errorlogging_stats table. If you do not provide a label,
Aster Database uses a statement identifier as the label value. (There’s one statement identifier per COPY command; if there is one map entry for many input files, then you’ll have a unique statement identifier per input file.)
NOWHERE instructs the COPY command to discard all malformed rows (and continue loading correctly formed rows).
ERRORLIMIT followed by an integer limit value sets the maximum number of allowed failed rows for this COPY job before it is forced to fail. ERRORLIMIT
UNLIMITED tells the COPY to continue running, regardless of the number of error rows it encounters. Statement failure is atomic; the whole transaction aborts if the limit is reached. This value is a global limit; Aster Database aggregates the errors detected across all partitions.
December 14, 2011 SQL Commands V--25
COPY Aster Data proprietary and confidential
Notes About COPY
When a COPY operation fails, any rows it had inserted are removed, but they still occupy disk space. This may amount to a considerable amount of wasted disk space if the failure happened well into a large copy operation. You may wish to invoke
VACUUM to recover the space.
Input Formats for COPY
Input can be:
•
•
“Text Formatted Input to COPY” on page V-26 , or
“CSV Formatted Input to COPY” on page V-27
Text Formatted Input to COPY
When COPY is used without the CSV option, the data read is interpreted as a text file with one line per table row. Columns in a row are separated by the DELIMITER character. The column values themselves are strings of each attribute's datatype. The specified null string is used in place of columns that are null. COPY FROM will raise an error if any line of the input file contains more or fewer columns than are expected.
End of data can be represented by a single line containing just backslash-period (\.).
Backslash characters (\) may be used in the COPY data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the following characters must be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character.
COPY FROM matches the input against the null string before removing backslashes. Therefore, a null string such as \N cannot be confused with the actual data value \N (which would be represented as \\N).
The following special backslash sequences are recognized by COPY FROM .
Table 1-3 Backslash sequences recognized by COPY FROM
Sequence Represents
\b
\f
\n
\r
\t
Backspace (ASCII 8)
Form feed (ASCII 12)
Newline (ASCII 10)
Carriage return (ASCII 13)
Tab (ASCII 9)
Any other backslashed character that is not mentioned in the above table will be taken to represent itself. However, beware of adding backslashes unnecessarily, since that might accidentally produce a string matching the end-of-data marker (\.) or the null string (\N by default). These strings will be recognized before any other backslash processing is done.
It is strongly recommended that applications generating
COPY
data convert data newlines and carriage returns to the \n and \r sequences respectively. At present, it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline. However, these representations might not be accepted in future releases.
They are also highly vulnerable to corruption if the
COPY data is transferred across different machines (for example, from Unix to Windows or vice versa).
V--26 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential COPY
COPY FROM
can handle lines ending with newlines, carriage returns, or carriage return/newlines. To reduce the risk of error due to un-backslashed newlines or carriage returns that were meant as data,
COPY FROM
will complain if the line endings in the input are not all alike.
CSV Formatted Input to COPY
This format is used for importing and exporting the Comma Separated Value (CSV) file format used by many other programs, such as spreadsheets. Instead of the escaping used by Aster
Database's standard text mode, it recognizes the common CSV escaping mechanism.
The values in each record are separated by the DELIMITER character. If the value contains the delimiter character, the QUOTE character, the null string, a carriage return, or line feed character, then the whole value is prefixed and suffixed by the QUOTE character, and any occurrence within the value of a QUOTE character or the ESCAPE character is preceded by the escape character.
The CSV format has no standard way to distinguish a NULL value from an empty string. Aster
Database's COPY handles this by quoting. A data value matching the null string must be quoted.
Therefore, using the default settings, a NULL is written as an unquoted empty string, while an empty string is written with double quotes ("").
Because backslash is not a special character in the CSV format, \., the end-of-data marker, could also appear as a data value. To avoid any misinterpretation, a \. data value appearing as a lone entry on a line is not interpreted as the end-of-data marker if it is quoted. Therefore, if you are loading a file created by another application that has a single unquoted column and might have a value of \., you might need to quote that value in the input file.
Note: In CSV mode, all characters are significant. A quoted value surrounded by white space, or any characters other than DELIMITER will include those characters. This can cause errors if you import data from a system that pads CSV lines with white space out to some fixed width. If such a situation arises you might need to preprocess the CSV file to remove the trailing white space, before importing the data into Aster Database.
Note: CSV mode will recognize CSV files with quoted values containing embedded carriage returns and line feeds. Thus the files are not strictly one line per table row like text-mode files.
Note: Many programs produce strange and occasionally perverse CSV files, so the file format is more a convention than a standard. Thus you might encounter some files that cannot be imported using this mechanism.
Example Use of COPY
The following example copies a table from the client using text format with the default parameters:
COPY country FROM STDIN;
Here is a corresponding sample of data suitable for copying:
AF
AL
DZ
ZM
ZW
AFGHANISTAN
ALBANIA
ALGERIA
ZAMBIA
ZIMBABWE
(Note that the white space on each line is actually a tab character.)
The next example copies a table from the client using CSV format with the quote character '@':
December 14, 2011 SQL Commands V--27
CREATE DATABASE Aster Data proprietary and confidential
COPY country FROM STDIN WITH CSV QUOTE AS '@';
Here is the same sample of data encoded appropriately:
@AF@,@AFGHANISTAN@
@AL@,@ALBANIA@
@DZ@,@ALGERIA@
@ZM@,@ZAMBIA@
@ZW@,@ZIMBABWE@
Compatibility of COPY
There is no
COPY
statement in the SQL standard.
See Also
See also “ncluster_loader Client-Side Loading Tool” on page II-130 .
CREATE DATABASE
CREATE DATABASE -- create a new database
Synopsis
CREATE DATABASE name [ [WITH] ENCODING [=] encoding ];
Description
CREATE DATABASE
creates a new database in the Aster Database cluster. To create a database, you must be a superuser or have the special db_admin
privilege. See “CREATE USER” on page V-43
. The creator becomes the owner of the new database.
Important! When you create a database, no other users have the right to use it. You must manage user privileges as follows:
•
•
•
To grant users the right to use the new database, you must grant at least the CONNECT privilege on the database to the users or roles who will use it. See
To grant users the right to create tables in the new database, you must grant them at least the
CREATE privilege on one of the schemas in the database. If your Aster Database has granted ALL privileges on schema PUBLIC to users in the PUBLIC role (this is the default setting of Aster Database upon installation), then all users can, by default, create databases in new databases you create. In other words, they can create tables within the public schema in the new database. For all other set-ups, you should create one or more schemas in the database, and grant appropriate privileges on those schemas.
To deny users the right to create tables and objects in a database, see “Revoking Users
Rights to Create Tables” on page V-72 .
Parameters for CREATE DATABASE name The name of a database to create.
V--28 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE INDEX encoding The name of the database character encoding. Currently the available encoding formats are
SQL_ASCII
and
UTF8
. The default encoding for any database is
UTF8
.
Notes
CREATE DATABASE cannot be executed inside a transaction block.
Use DROP DATABASE to remove a database.
Examples
To create a new database:
CREATE DATABASE sales;
To create the database with UTF8 encoding instead:
CREATE DATABASE sales WITH ENCODING = 'UTF8';
Compatibility
There is no
CREATE DATABASE
statement in the SQL standard. Databases are equivalent to catalogs, whose creation is implementation-defined.
CREATE INDEX
CREATE INDEX -- define a new index
Synopsis
CREATE INDEX name ON table [ USING method ]
( { column | ( expression ) } [, ...] )
[ WHERE predicate ];
Description
CREATE INDEX
constructs an index name on the specified table. Indexes are primarily used to enhance database performance (though inappropriate use will result in slower performance).
The key field(s) for the index are specified as column names. Multiple fields can be specified.
An index field can be an expression computed from the values of one or more columns of the table row. This feature can be used to obtain fast access to data based on some transformation of the basic data. For example, an index computed on upper(col)
would allow the clause
WHERE upper(col) = 'JIM'
to use an index.
Aster Database supports the B-tree index method (“btree”) and the GiST method (“gist”).
When the
WHERE
clause is present, a partial index is created. A partial index is an index that contains entries for only a portion of a table, usually a portion that is more useful for indexing than the rest of the table. For example, if you have a table that contains both billed and unbilled orders, where the unbilled orders take up a small fraction of the total table and yet that is an often used section, you can improve performance by creating an index on just that portion.
The expression used in the
WHERE
clause may refer only to columns of the underlying table, but it can use all columns, not just the ones being indexed. Presently, subqueries and aggregate
December 14, 2011 SQL Commands V--29
CREATE INDEX Aster Data proprietary and confidential expressions are also forbidden in
WHERE
. The same restrictions apply to index fields that are expressions.
All functions and operators used in an index definition must be "immutable", that is, their results must depend only on their arguments and never on any outside influence (such as the contents of another table or the current time). This restriction ensures that the behavior of the index is well-defined.
Parameters name table method column expression predicate
The name of the index to be created.
The name of the table to be indexed.
The name of the method to be used for the index. The choices are btree and gist. The default method is btree. For a description of GiST indexes,
see “GiST Indexes (ip4range Indexes)” on page V-176 .
The name of a column of the table.
An expression based on one or more columns of the table. The expression usually must be written with surrounding parentheses, as shown in the syntax. However, the parentheses may be omitted if the expression has the form of a function call.
The constraint expression for a partial index.
Notes
Multicolumn indexes: The B-tree index method supports multicolumn indexes. Up to 32 fields may be specified by default.
Use
DROP INDEX
to remove an index.
Avoiding scanning of rows with nulls in a column: When a user submits a query containing an
IS NULL
or
IS NOT NULL
clause, the planner does not, by default, use an index to search for results. The best way to encourage the planner to use indexes in such cases is to create a partial index using an
IS NULL
predicate. Another, very efficient way to give your queries the ability to avoid scanning rows with a null value in a particular column is to use logical partitioning. To do this, create a parent-child table hierarchy in which the check constraints ensure that all rows with a null in the relevant column are saved in a child table set aside for that. Queries whose predicate requires a value or NOT NULL in the relevant column will not scan the null-valued rows.
Indexes on expressions Indexes on expressions (also called functional indexes or function-based indexes) are defined on the result of an expression applied to one or more columns of a single table. Indexes on expressions can be used to build the index so that it better matches the type of predicates your queries use.
For example, a common way to do case-insensitive comparisons is to use the lower
function to convert all values to lower case letters:
SELECT * FROM test1 WHERE lower(col1) = 'value';
This query can use an index, if one has been defined on the result of the lower(column) operation:
CREATE INDEX test1_lower_col1_idx ON test1 (lower(col1));
Another common use is to define less granular indexes on a timestamp column. For example:
CREATE INDEX soldone_idx ON soldone (EXTRACT(YEAR FROM timeofsale));
V--30 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE ROLE
The expression in the index definition can take more than one argument. Each argument is a column name or a constant.
Examples
To create a B-tree index on the column title in the table films:
CREATE INDEX title_idx ON films (title);
Compatibility
CREATE INDEX
is an Aster Database language extension. There are no provisions for indexes in the SQL standard.
See Also
CREATE ROLE
Synopsis
CREATE ROLE name [ [ WITH ] option [ ... ] ] where option can be:
INHERIT
| NOINHERIT
| IN ROLE rolename [, ...]
| IN GROUP rolename [, ...]
| ROLE rolename [, ...]
| ADMIN rolename [, ...]
Description
CREATE ROLE adds a new role in an Aster Database cluster. You must be a superuser (that is, a member of the db_admin
role) to use this command.
A role is an entity that can have database privileges and typically consists of users and/or roles as members. A role can be considered synonymous with a “group”, and it can also be used as a means of applying usage permissions to a user or group of users.
Roles are defined at the database cluster level, and so are valid in all databases in the cluster.
Parameters name
- The name of the new role.
INHERIT
,
NOINHERIT
- These clauses determine whether a role "inherits" the privileges of roles it is a member of. A role with the INHERIT attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of. Without
INHERIT, membership in another role only grants the ability to SET ROLE to that other role; the privileges of the other role are only available after having done so. If not specified, INHERIT is the default. Currently, SET ROLE is not supported in Aster Database.
December 14, 2011 SQL Commands V--31
CREATE SCHEMA Aster Data proprietary and confidential
IN ROLE rolename
- The IN ROLE clause lists one or more existing roles to which the new role will be immediately added as a new member. Note that there is no option to add the new role as an administrator (WITH ADMIN OPTION), use a separate GRANT command to do that.
IN GROUP rolename
- IN GROUP is an alternate spelling of IN ROLE.
ROLE rolename
- The ROLE clause lists one or more existing roles and/or users that are automatically added as members of the new role.
ADMIN rolename
- The ADMIN clause is like ROLE, but the named roles and/or users are added to the new role WITH ADMIN OPTION, giving them the right to grant membership in this role to others.
Notes
Use DROP ROLE to remove a role.
The preferred way to add and remove members of roles is to use GRANT and REVOKE.
The NOCREATEDB and NOCREATEROLE options are not supported in Aster Database.
Instead, grant a user the role db_admin to give him or her the right to create databases, users, and roles, and grant a lower-privileged role such as catalog_admin to deny the right to create databases, users, and roles. See “Default Roles and Users” on page II-95 for details.
Examples
Create a role:
CREATE ROLE admin
Compatibility
The CREATE ROLE statement is in the SQL standard, but the standard only requires the syntax
CREATE ROLE name [ WITH ADMIN rolename ]
Multiple initial administrators, and all the other options of CREATE ROLE, are Aster Database extensions.
The SQL standard defines the concepts of users and roles, but it regards them as distinct concepts. In Aster Database, we have chosen to maintain this distinction.
See Also
,
.
CREATE SCHEMA
CREATE SCHEMA -- define a new schema
Synopsis
CREATE SCHEMA schemaname
V--32 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE SCHEMA
Description
CREATE SCHEMA enters a new schema into the current database. The schema name must be distinct from the name of any existing schema in the current database. The user who creates the schema is the owner of the schema.
A schema is essentially a namespace: it contains named objects (tables, datatypes, functions, and operators) whose names can duplicate those of other objects existing in other schemas. Named objects are accessed by "qualifying" their names with the schema name as a prefix.
When you create objects such as tables, issuing a CREATE command without specifying a schema name creates the object in your current schema.
Within the CREATE SCHEMA statement, you can include an SQL statement defining an object to be created within the schema. The supported create statements are: CREATE TABLE,
CREATE VIEW, CREATE INDEX, CREATE SEQUENCE, CREATE TRIGGER and GRANT.
Parameters schemaname The name of a schema to be created. If this is omitted, the username is used as the schema name. The name cannot begin with nc_, as such names are reserved for system schemas.
See Also
“ALTER SCHEMA” on page V-8 and
December 14, 2011 SQL Commands V--33
CREATE TABLE Aster Data proprietary and confidential
CREATE TABLE
CREATE TABLE -- define a new table
Synopsis
CREATE [ TEMPORARY | TEMP ] [ FACT | DIMENSION ] TABLE table_name ( [
{ column_name data_type [ DEFAULT default_value ] [ column_constraint [ ... ] ]
| table_constraint }
[, ... ]
] )
[ DISTRIBUTE BY { HASH ( distribution_key_column_name ) | REPLICATION } ]
[ STORAGE { ROW | COLUMN } ]
[ COMPRESS [ HIGH | MEDIUM | LOW ] ]
[ PARTITION BY partition_clause ]
[ INHERITS ( parent_table ) ] where column_constraint is:
[ CONSTRAINT constraint_name ]
{ NOT NULL
| NULL
| UNIQUE
| PRIMARY KEY
| CHECK ( expression ) } where table_constraint is:
[ CONSTRAINT constraint_name ]
{ UNIQUE ( column_name [, ... ] )
| PRIMARY KEY ( column_name [, ... ] )
| PARTITION KEY ( column_name )
| CHECK ( expression ) } where partition_clause is a LIST clause or a RANGE clause:
LIST ( expression )
( [ list_partition [, ...] ] )
| RANGE ( expression [ NULLS FIRST | NULLS LAST ] )
( [ range_partition [, ...] ] ) where list_partition is
PARTITION part_name (
VALUES ( list_value [, ...] )
[ NOCOMPRESS | COMPRESS [ HIGH | MEDIUM | LOW ] ]
[ PARTITION BY partition_clause ]
) where range_partition is
PARTITION part_name (
[ START { start_value [ INCLUSIVE | EXCLUSIVE ] | MINVALUE } ]
END { end_value [ INCLUSIVE | EXCLUSIVE ] | MAXVALUE }
[ NOCOMPRESS | COMPRESS [ HIGH | MEDIUM | LOW ] ]
[ PARTITION BY partition_clause ]
V--34 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
)
CREATE TABLE
Description
CREATE TABLE creates a new table in the current database. When you create a table in Aster
Database, you should pass the keyword FACT or DIMENSION to declare it to be a fact table or a dimension table. See “Fact Tables and Dimension Tables” on page I-4 .
The table will be owned by the user issuing the command and the table is created in the current schema. The name of the table must be distinct from the name of any other table or index in the same schema.
Parameters for CREATE TABLE
FACT
or
DIMENSION
table_name
column_name
data_type
This optional clause specifies whether the new table should be a fact table or a dimension table.
•
If it is a fact table, then you must also include the
DISTRIBUTE BY HASH clause to declare the table’s distribution key.
•
If it is a dimension table, then you may make the table a replicated table (all rows are present on all v-workers) or a distributed table (rows are distributed throughout the cluster). Include the DISTRIBUTE BY REPLICATION or
DISTRIBUTE BY HASH clause, respectively, to do this.
See “Fact Tables and Dimension Tables” on page I-4 .
The name of the table to be created. See “Identifiers,
Keywords, and Naming Conventions” on page V-199 .
The name of a column to be created in the new table.
The datatype of the column. This may include array specifiers.
DEFAULT default_value This optional clause specifies a DEFAULT value for a column.
This constraint ensures that, upon insertion or update of a row, the column will be set to the default value if no value is provided in the SQL statement, or if the INSERT statement uses the keyword “DEFAULT” to request the default value.
The default_value may be a literal or a datetime value
function.
A literal is any literal value that matches the column’s datatype. It may be a signed numeric value, a character string value, a datetime value, an integer value or a boolean value.
The
A datetime_value_function is any of:
CURRENT_DATE,
CURRENT_TIME, LOCALTIME, CURRENT_TIMESTAMP,
LOCALTIMESTAMP,
or
NOW()
. You must use the function alone and not in an expression.
See “Working With Default Values” on page V-65
for information on inserting default values into rows.
You cannot specify a DEFAULT value for a column of type
SERIAL or BIGSERIAL.
column_constraint
or
table_constraint
See “Constraint Syntax for CREATE TABLE” on page V-37 .
December 14, 2011 SQL Commands V--35
CREATE TABLE Aster Data proprietary and confidential
DISTRIBUTE BY { HASH ( distribution_
key_column_name ) | REPLICATION }
STORAGE { ROW | COLUMN }
COMPRESS [ HIGH | MEDIUM | LOW ]
PARTITION BY partition_clause
Declares whether the table will be distributed (
HASH
) or replicated (
REPLICATION
). If the table is a
FACT
table, you
must
DISTRIBUTE BY HASH
. If the table is using automatic logical partitioning (see Automatic Logical Partitioning
(page I-11) ), you must explicitly declare a distribution method using DISTRIBUTE BY in the CREATE TABLE statement.
For a HASH-distributed table, you provide the distribution_
key_column_name, which is the name of the single column that is the table’s distribution key. For each row, a hash of this column’s value determines where the row is stored in the cluster, as described in “Fact Tables and Dimension Tables” on page I-4 .
The column you choose as your distribution key must have one of the datatypes listed in “Distribution Key” on page I-10 .
If the table has a primary key defined, then the distribution key must be one of the columns from the primary key. There are other rules that apply to the distribution key column. See
“Distribution Key” on page I-10 .
If no STORAGE clause is supplied, the table will be a traditional row-oriented table. Passing “STORAGE ROW” indicates the table will be a row-oriented table. Passing
“STORAGE COLUMN” indicates the table will use a column-oriented storage layout. See “Columnar Tables” on page I-31 .
Specifies the level of table compression for the newly created table. Three compression levels are available: high, medium, and low. Medium is the default. After a table is created, the compression level can be altered via
See “Compression” on page II-8 for an overview of compression in Aster Database.
Specifies that the table will be split into many smaller child tables. Upon insertion, each row is directed to the single child table whose partitioning constraint matches that row, or, if the row fails to match any constraint, the row is not inserted and an error is generated.
The partition_clause may be
•
a LIST of VALUEs: each child table has a list of key values; a row’s value must match one of the values; or
•
a RANGE: each child has a numeric, alphabetical, or date range of key values. A row’s value must match the child's range.
See “Automatic Logical Partitioning” on page I-11 .
V--36 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE TABLE
INHERITS ( parent_table ) The INHERITS clause is Aster Database’s older alternative to the newer PARTITION BY method of creating parent/child table hierarchies.
The optional
INHERITS
clause specifies the table from which the new table automatically inherits all columns. Use of
INHERITS
creates a persistent relationship between the new child table and its parent table. Schema modifications to the parent normally propagate to children as well, and by default the data of the child table is included in scans of the parent. A fact table may only inherit from another fact table, and a dimension table may only inherit from another dimension table.
What is not inherited: A child table does not inherit
PRIMARY KEY constraints, nor does it inherit UNIQUE constraints or index structures defined on the parent.
What is inherited: A child table does inherit the distribution key of its parent. In other words, the distribution key of the child is the same as that of its parent, and you cannot change it.
All check constraints and not-null constraints on the parent table are automatically inherited by its children.
When creating a child table, if you declare a column name that matches the name of a column in the parent, then the child column’s datatype must match that of the inherited column.
The column definitions are merged into a single definition for the child table column. When you create a child table, you may add constraints that its parent does not have. Constraints inherited from the parent table(s) are added to those you declare in the child table, and this forms the set of constraints on the child table.
See “Logical Partitioning Through Inheritance (Parent/Child)” on page I-26 for details and examples.
Setting Constraints in CREATE TABLE
The optional constraint clauses specify constraints (tests) that new or updated rows must satisfy for an insert or update operation to succeed. A constraint is an SQL object that helps define the set of valid values in the table in various ways.
There are two ways to define constraints: table constraints and column constraints. A column constraint is defined as part of a column definition. A table constraint definition is not tied to a particular column, and it can encompass more than one column. Every column constraint can also be written as a table constraint; a column constraint is only a notational convenience for use when the constraint only affects one column.
In the table that follows, we describe the constraint syntax.
NOT NULL
NULL
Constraint Syntax for CREATE TABLE
CONSTRAINT constraint_name
An optional name for a column or table constraint. If not specified, the system generates a name.
The column is not allowed to contain null values.
The column is allowed to contain null values. This is the default. This clause is only provided for compatibility with non-standard SQL databases.
December 14, 2011 SQL Commands V--37
CREATE TABLE Aster Data proprietary and confidential
PARTITION KEY ( column_name )
PRIMARY KEY
(as a column constraint)
PRIMARY KEY ( column_name [, ... ] )
(as a table constraint)
CHECK (expression)
Deprecated syntax for declaring the table’s distribution key.
In Aster Database 4.6 and later, you should use
DISTRIBUTE
BY
instead.
The primary key (PK) constraint specifies that a column or columns of a table may contain only unique (non-duplicate), non-null values. Technically,
PRIMARY KEY
is merely a combination of
UNIQUE
and
NOT NULL
, but identifying a set of columns as PK also provides metadata about the design of the schema, as a PK implies that other tables may rely on this set of columns as a unique identifier for rows.
Only one PK definition (containing one or more PK columns) can be specified for a table. If your PK consists of a single column, then you can instead specify the PK as a column
constraint rather than a table constraint.
For hash-distributed tables, note that while the PK may contain multiple columns, you must choose a single column as the
distribution key, and this column must be one of the PK columns.
Warning! A table that will contain a large amount of data will typically have no PK defined, because having a PK results in slower loading. Loading to a table with a PK takes longer than loading to a table without a PK because Aster Database must check the uniqueness of each PK value. If you have a large table that requires a primary key, use ALTER TABLE to add the primary key after you have loaded its data.
The
CHECK
constraint clause specifies an expression producing a Boolean result that new or updated rows must satisfy for an insert or update operation to succeed.
Expressions evaluating to
TRUE
or
UNKNOWN
succeed. Should any row of an insert or update operation produce a
FALSE result an error exception is raised and the insert or update does not alter the database.
To comply with standard SQL, a check constraint specified as a column constraint should reference that column's value only, while an expression appearing in a table constraint may reference multiple columns. However, because Aster Database treats column and table check constraints alike, setting a column constraint that references another column will not cause the statement to fail.
Currently,
CHECK
expressions cannot contain subqueries nor refer to variables other than columns of the current row.
V--38 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE TABLE
UNIQUE
(as a column constraint)
UNIQUE ( column_name [, ... ] )
(as a table constraint)
The
UNIQUE
constraint specifies that a group of one or more columns of a table can contain only unique values. The behavior of the unique table constraint is the same as that for column constraints, with the additional capability to span multiple columns.
For the purpose of a unique constraint, null values are not considered equal.
Each unique table constraint must contain the distribution key column.
Warning! A table that will contain a large amount of data will typically have no unique constraints defined, because having them results in slower loading. Loading to a table with such constraints takes longer than loading to a table without them because Aster Database must check the uniqueness of each value in the must-be-unique column. If you have a large table that requires a unique constraint, use ALTER TABLE to add the constraint after you have loaded the data.
See also “A Note on Unique Constraints” on page V-41
Notes on CREATE TABLE
Indexes: Aster Database automatically creates an index for each primary key constraint, thus, it
for more information.)
Loading Tip: If you plan to load large amounts of data to the table, Aster Data recommends that you load your data first, and define your primary key and indexes after loading. The presence of indexes slows loading!
Inheritance: In parent-child table hierarchies, primary keys are not inherited. See details in
“Logical Partitioning Through Inheritance (Parent/Child)” on page I-26 .
Limitations: A table cannot have more than 1600 columns, and in practice, the effective limit is
lower because of row-length constraints. See details in “System Limits” on page V-203 .
Examples of CREATE TABLE
This example creates the fact table films
and its associated dimension table distributors
, linked by a distributor id colunm, did
:
CREATE TABLE films (
code integer,
title varchar(40) NOT NULL,
did integer NOT NULL,
date_prod date,
kind varchar(10)
)
DISTRIBUTE BY HASH( code )
;
CREATE DIMENSION TABLE distributors (
did integer PRIMARY KEY,
name varchar(40) NOT NULL CHECK (name <> '')
);
December 14, 2011 SQL Commands V--39
CREATE TABLE Aster Data proprietary and confidential
In the following example we use a PARTITION BY RANGE clause to create a fact table trans with four daily child partitions using automatic logical partitioning (strictly speaking, the first partition is a catch-all for older records):
CREATE FACT TABLE trans( id int, country varchar, ts timestamp )
DISTRIBUTE BY HASH(id)
PARTITION BY RANGE(ts) (
PARTITION oldrecords( END '2011-01-01' ), -- everything pre-2011
PARTITION jan01_2011( END '2011-01-02' ),
PARTITION jan02_2011( END '2011-01-03' ),
PARTITION jan03_2011( END '2011-01-04' )
);
This example defines a check column constraint:
CREATE DIMENSION TABLE distributors (
did integer CHECK (did > 100),
name varchar(40)
);
This example defines a check table constraint:
CREATE DIMENSION TABLE distributors (
did integer,
name varchar(40)
CONSTRAINT con1 CHECK (did > 100 AND name <> '')
);
This example creates a distributed dimension table, distributors
, and distributes it based on its distributor id ( did
) values:
CREATE DIMENSION TABLE distributors (
did integer,
name varchar(40)
)
DISTRIBUTE BY HASH(did)
;
This example defines two
NOT NULL
column constraints on the table distributors
, one of which is explicitly given a name:
CREATE DIMENSION TABLE distributors (
did integer CONSTRAINT no_null NOT NULL,
name varchar(40) NOT NULL
);
Compatibility
The
CREATE TABLE
command conforms to the SQL standard, with exceptions listed below.
Column Check Constraints The SQL standard says that
CHECK
column constraints may only refer to the column they apply to; only
CHECK
table constraints may refer to multiple columns. Aster Database does not enforce this restriction; it treats column and table check constraints alike.
NULL
Constraint The
NULL
"constraint" (actually a non-constraint) is an Aster Database extension to the SQL standard that is included for compatibility with some other database
V--40 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE TABLE systems (and for symmetry with the
NOT NULL
constraint). Since it is the default for any column, its presence is simply noise.
Distribution Key Constraint The distribution key constraint is an Aster Database extension.
PARTITION KEY
Constraint The deprecated
PARTITION KEY
constraint is an Aster
Database extension.
See Also
A Note on Unique Constraints
Unique constraints ensure that the data contained in a column or a group of columns is unique with respect to all the rows in the table. The syntax is:
CREATE FACT TABLE products (
product_no integer UNIQUE,
name text,
price numeric
)
DISTRIBUTE BY HASH (product_no)
; when written as a column constraint, and:
CREATE FACT TABLE products (
product_no integer,
name text,
price numeric,
UNIQUE (product_no)
)
DISTRIBUTE BY HASH (product_no)
; when written as a table constraint.
If a unique constraint refers to a group of columns, the columns are listed separated by commas:
CREATE FACT TABLE example (
a integer,
b integer,
c integer,
UNIQUE (a, c)
)
DISTRIBUTE BY HASH (a)
;
This specifies that the combination of values in the indicated columns is unique across the whole table, though any one of the columns need not be (and ordinarily isn't) unique.
You can assign your own name for a unique constraint, in the usual way:
CREATE FACT TABLE products (
product_no integer CONSTRAINT must_be_different UNIQUE,
name text,
price numeric
)
DISTRIBUTE BY HASH (product_no)
;
December 14, 2011 SQL Commands V--41
CREATE TABLE AS Aster Data proprietary and confidential
In general, a unique constraint is violated when there are two or more rows in the table where the values of all of the columns included in the constraint are equal. However, two null values are not considered equal in this comparison. That means even in the presence of a unique constraint it is possible to store duplicate rows that contain a null value in at least one of the constrained columns. This behavior conforms to the SQL standard.
CREATE TABLE AS
CREATE TABLE AS - define a new table from the results of a query
Synopsis
CREATE [ FACT | DIMENSION ] TABLE table_name ( [
{ column_name data_type
| table_constraint }
[, ...]
] )
[ DISTRIBUTE BY { HASH ( column_name ) | REPLICATION } ] [ STORAGE { ROW
| COLUMN } ] [ COMPRESS [ HIGH | MEDIUM | LOW ] ] AS query
Description
CREATE TABLE AS creates a table and fills it with data computed by a SELECT command.
The table columns have the names and datatypes associated with the output columns of the
SELECT (except that you can override the column names by giving an explicit list of new column names). When you create a table in Aster Database, you should declare it to be a fact
table or a dimension table. See “Fact Tables and Dimension Tables” on page I-4 .
If the target table schema isn’t explicitly specified, it will be inferred from the output columns of the SELECT clause. Even if you do not specify names for the new tables columns, you can still specify a column as the distribution key.
CREATE TABLE AS creates a new table and evaluates the query just once to fill the new table.
The new table does not track subsequent changes to the source tables of the query.
Note that CREATE TABLE AS is not supported with logically partitioned tables (tables created with PARTITION BY HASH or PARTITION BY RANGE
)
. To work around this, see Creating a logically partitioned table from data in another table (page I-23) .
Warning!
When you
CREATE TABLE ... AS SELECT
, Aster Database runs
ANALYZE
on the new table after inserting the data. A read lock is placed on the new table while
ANALYZE
runs.
V--42 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE USER table_name column_name data_type query
DISTRIBUTE BY
Parameters
FACT or DIMENSION
This optional clause specifies whether the new table should be created as a fact table or a dimension table. If this clause is not specified, the new table will be a fact table. See “Fact Tables and Dimension Tables” on page I-4 .
Note that the distribution of the table may affect the performance of join operations. For more details on distribution, see “Distributing Tables” on page I-9 .
The name of the table to be created.
The name of a column to be created in the new table.
The datatype of the column.
A SELECT command. The following restriction applies:
The column referenced in the DISTRIBUTE BY clause must be among the columns in the SELECT clause of the query.
The DISTRIBUTE BY clause specifies either hash distribution (with a distribution key constraint) or replication.
The distribution key constraint specifies the column of a table that is to be used to determine the distribution of the table (that is, the distribution of its data in the cluster), as described in “Distribution Key” on page I-10 . For a fact table, the specification of a distribution key is mandatory.
Compatibility
CREATE TABLE AS
conforms to the SQL standard, with the following exceptions:
•
•
•
•
The standard requires parentheses around the query clause; in Aster Database, these parentheses are optional.
The standard defines a
WITH [ NO ] DATA
clause; this is not currently implemented by
Aster Database. The behavior provided by Aster Database is equivalent to the standard's
WITH DATA
case.
DISTRIBUTE BY
and the deprecated
PARTITION KEY
constraints are Aster Database extensions.
The specification of columns in the query clause is an Aster Database extension.
See Also
CREATE USER
CREATE USER
Synopsis
CREATE USER name [ [ WITH ] option [ ... ] ] PASSWORD 'password'; where option can be:
INHERIT | NOINHERIT | IN ROLE rolename [, ...] | IN GROUP rolename [,
...]
December 14, 2011 SQL Commands V--43
CREATE USER Aster Data proprietary and confidential
Description
CREATE USER adds a new user to an Aster Database cluster. A user is an entity that can login into the database, can own database objects and have database privileges. Depending on the roles you grant, the user might also have privileges to use part or all of the Aster Database AMC. You must be a superuser to use this command.
Note that users are defined at the database cluster level, and so are valid in all databases in the cluster.
Parameters name
- The name of the new user. The rules for usernames in Aster Database are as follows: A name must start with a letter or an underscore; the rest of the string can contain letters, digits, and underscores. The character limit is 63 chars. Longer entries are truncated. You cannot use following characters in a username in Aster Database: ' (single quote), " (double quote), or \
(backslash). If you have set up Aster Database to delegate the task of user authentication to an external tool, then that tool’s rules also apply to usernames you store here. See “User
Authentication” on page II-100 .
INHERIT
,
NOINHERIT
- These clauses determine whether a user "inherits" the privileges of roles it is a member of. A user with the INHERIT attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of. Without
INHERIT, membership in another role only grants the ability to SET ROLE to that other role; the privileges of the other role are only available after having done so. If not specified, INHERIT is the default. Currently, SET ROLE is not supported in Aster Database.
IN ROLE rolename
- The IN ROLE clause lists one or more existing roles to which the new user will be immediately added as a new member. Note that there is no option to add the new user as an administrator (WITH ADMIN OPTION), use a separate GRANT command to do that.
IN GROUP rolename
- IN GROUP is an alternate spelling of IN ROLE.
Notes
Use DROP USER to remove a user. See “DROP USER” on page V-54 .
Examples
Create a user with a password:
CREATE USER david WITH PASSWORD 'jw8s0F4';
Compatibility
The CREATE USER statement is in the SQL standard, but the standard only requires the syntax
CREATE USER name [ WITH ADMIN rolename ]
Multiple initial administrators, and all the other options of CREATE USER, are Aster Database extensions.
The SQL standard defines the concepts of users and roles, but it regards them as distinct concepts. In Aster Database, we have chosen to maintain this distinction.
V--44 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential CREATE VIEW
Compatibility
The CREATE USER statement is an Aster Database extension. The SQL standard leaves the definition of users to the implementation.
See Also
,
For information on creating and managing Aster Database users, generally, see “Managing
Users” on page II-95 .
For information on creating AMC users, see “Creating an AMC User in nCluster” on page III-78 .
CREATE VIEW
CREATE VIEW
Synopsis
Define a new database view. A view is a stored query accessible as a virtual table composed of the result set of a query. Unlike ordinary tables (base tables) in a relational database, a view is not part of the physical schema. Instead, it is a dynamic, virtual table computed or collated from data in the database. Changing the data in a table alters the data shown in the view.
More:
|
|
Synopsis
CREATE [ OR REPLACE ] VIEW name [ ( column_name [, ...] ) ] AS query
ALTER VIEW name RENAME TO newname
DROP VIEW [ IF EXISTS ] name [, ...] [ CASCADE ]
Description
CREATE VIEW
defines a view of a query. The view is not physically materialized. Instead, the query is run every time the view is referenced in a query.
CREATE OR REPLACE VIEW
is similar, but if a view of the same name already exists, it is replaced. You can only replace a view with a new query that generates the identical set of columns (i.e., same column names and datatypes).
ALTER VIEW
changes various auxiliary properties of a view. (If you want to modify the view’s defining query, use
CREATE OR REPLACE VIEW
.)
DROP VIEW
drops an existing view. To execute this command you must be the owner of the view.
Parameters name The name (optionally schema-qualified) of a view to be created.
December 14, 2011 SQL Commands V--45
DECLARE Aster Data proprietary and confidential column_name An optional list of names to be used for columns of the view. If not given, the column names are deduced from the query. query A
SELECT command that provides the columns and rows of the view. The query can be
an SQL-MapReduce query.
Note about views created with SQL-MapReduce queries: If you have defined a view using an
SQL-MapReduce query that queries data from a table in Aster Database, that underlying table cannot be altered. To alter such a table, you must first drop the view whose definition refers to the table.
Notes
Read-only Views are read-only in Aster Database: the system will not allow an insert, update, or delete on a view. Also, Aster Database does not provide session-level temporary views, which you may be accustomed to using on other database platforms.
Dropping a view Use the DROP VIEW statement to drop views.
Permissions Access to tables referenced in the view is determined by permissions of the view owner. However, functions called in the view are treated the same as if they had been called directly from the query using the view. Therefore the user of a view must have permissions to call all functions used by the view.
Example
This example creates a view consisting of all comedy films:
CREATE VIEW comedies AS
SELECT *
FROM films
WHERE kind = 'Comedy';
Compatibility
•
The SQL standard specifies the WITH ... CHECK OPTION clause for CREATE VIEW, but
CHECK OPTION may not be used with Aster Database views because they are read-only.
•
•
The SQL-standard LOCAL and CASCADED options are not supported in Aster Database’s implementation of views.
Aster Database follows the PostgreSQL convention, rather than the SQL standard, in using the syntax “CREATE OR REPLACE VIEW” to update views.
See also
ALTER VIEW,
DECLARE
DECLARE -- define a cursor
Synopsis
DECLARE name [ INSENSITIVE ] [ [ NO ] SCROLL ]
V--46 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
[ FOR UPDATE | FOR READ ONLY ];
DECLARE
Description
DECLARE
allows you to create a server-side cursor that can be used to retrieve a specified number of rows at a time out of a larger query. Cursors can return data in text format, the same as a
SELECT
would produce, using
FETCH
.
You can create a server-side cursor feature using the
DECLARE CURSOR
syntax on any query client (ACT, JDBC, ODBC or others). When server-side cursors are activated, the queen issues the phases for each v-worker, encapsulated in a database cursor. The queen opens parallel cursors to each vworker and handles operations through these cursors.
This allows for the following performance optimizations:
• the queen can retrieve a few rows at a time (thereby not requiring the queen to cache the entire result set from all v-workers) the v-worker can overlap the computation with the row retrieval by the queen
•
Applications that need to start streaming the results of a query as soon as possible can benefit from using the server-side cursors functionality of Aster Database. Server-side cursors allow clients to start fetching rows as soon as they are computed because the Aster Database does not wait for the entire query to complete before returning partial results. Note also that ACT, Aster
Database’s query client, provides two flags to invoke and control server-side cursors. These flags are fetch-count and fetch-limit, as explained in Throttling query results in ACT and Aster
Database (page I-43) .
December 14, 2011 SQL Commands V--47
DECLARE Aster Data proprietary and confidential
name
INSENSITIVE
SCROLL
NO SCROLL
WITH HOLD
WITHOUT HOLD
query
FOR UPDATE
FOR READ ONLY
Parameters for DECLARE
The name of the cursor to be created.
Specifies that data retrieved from the cursor should be unaffected by updates to the table(s) underlying the cursor that occur after the cursor is created. In Aster Database, this is the default behavior; so this key word has no effect and is only accepted for compatibility with the
SQL standard.
SCROLL specifies that the cursor may be used to retrieve rows in a non sequential fashion
(e.g., backward). Depending upon the complexity of the query's execution plan, specifying
SCROLL
may impose a performance penalty on the query's execution time.
NO SCROLL
specifies that the cursor cannot be used to retrieve rows in a non sequential fashion. The default is to allow scrolling in some cases; this is not the same as specifying
SCROLL
. See
for details.
WITH HOLD
specifies that the cursor may continue to be used after the transaction that created it successfully commits.
WITHOUT HOLD
specifies that the cursor cannot be used outside of the transaction that created it.
If neither
WITHOUT HOLD
nor
WITH HOLD
is specified,
WITHOUT HOLD
is the default.
A
SELECT
command that provides the rows to be returned by the cursor.
FOR READ ONLY
specifies that the cursor will be used in a read-only mode. No data updates will be allowed.
FOR UPDATE
specifies that the cursor will be an updatable cursor (that is, one that you can use to update a table or delete rows from a table). When you declare a cursor with the
FOR
UPDATE
option, you can apply updates or deletes to rows in that cursor. To perform an update or delete, use
UPDATE
or
DELETE
with the
WHERE CURRENT OF <cursor name>
clause.
You must perform all updates and deletes in the same transaction in which you declared the cursor. Inside the cursor, you cannot see the results of your updates and deletes; you can only scroll forward in an updatable cursor.
For a cursor to be updatable, it must be a NO SCROLL cursor and the SELECT statement in the cursor declaration must follow the rules shown below:
•
It not contain a join (that is, it must select from only a single table, and that table must not be joined to itself).
•
•
•
It must not contain an ORDER BY clause.
It must specify a table, not a view. (Views are read-only.)
It must not contain a GROUP BY clause.
Notes on DECLARE
Unless
WITH HOLD
is specified, the cursor created by this command can only be used within the current transaction. Thus,
DECLARE
without
WITH HOLD
is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore Aster
Database reports an error if this command is used outside a transaction block. Use
BEGIN
,
COMMIT
and
ROLLBACK
to define a transaction block.
If
WITH HOLD
is specified and the transaction that created the cursor successfully commits, the cursor can continue to be accessed by subsequent transactions in the same session. (But if the creating transaction is aborted, the cursor is removed.) A cursor created with
WITH HOLD
is closed when an explicit
CLOSE
command is issued on it, or the session ends.
The
SCROLL
option should be specified when defining a cursor that will be used to fetch backwards. This is required by the SQL standard. If
NO SCROLL
is specified, then backward fetches are disallowed in any case. Updatable cursors are always
NO SCROLL
cursors.
The SQL standard only makes provisions for cursors in embedded SQL. Aster Database does not implement an
OPEN
statement for cursors; a cursor is considered to be open when it is declared.
V--48 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Examples
To declare a cursor:
DECLARE filmcsr CURSOR FOR SELECT * FROM films;
for more examples of cursor usage.
Compatibility of DECLARE
The SQL standard allows cursors only in embedded SQL and in modules. Aster Database permits cursors to be used interactively.
See Also
, and
.
DELETE
DELETE
DELETE -- delete rows of a table
Synopsis
DELETE FROM [ ONLY ] table
[ USING usinglist ]
[ WHERE condition | WHERE CURRENT OF cursor_name ];
Description
DELETE
deletes rows that satisfy the
WHERE clause from the specified table. If the
WHERE clause is absent, the effect is to delete all rows in the table. The result is a valid, but empty table.
By default,
DELETE
will delete rows in the specified table and all its child tables. If you wish to delete only from the specific table mentioned, you must use the
ONLY
clause.
The
USING
clause can be used to delete rows in a table using information contained in other tables in the database.
You must have the
DELETE
privilege on the table to delete from it, as well as the
SELECT privilege for any table in the
USING
clause or whose values are read in the condition.
December 14, 2011 SQL Commands V--49
DELETE Aster Data proprietary and confidential
ONLY table usinglist condition
cursor_name
Parameters for DELETE
If specified, delete rows from the named table only.
When not specified, any tables inheriting from the named table are also processed.
The name of an existing table.
A list of table expressions, allowing columns from other tables to appear in the
WHERE
condition. This is similar to the list of tables that can be specified in the
FROM
clause of a
SELECT
statement; for example, an alias for the table name can be specified.
Do not repeat the target table in the usinglist
, unless you wish to set up a self-join.
A Boolean-returning expression that determines which rows will be deleted.
If usinglist
specifies multiple tables, a join predicate specified in condition
must include the distribution key columns of all included tables.
The name of the cursor to use in a
WHERE CURRENT OF
condition. The row to be deleted is the one most recently fetched from this cursor. The cursor must be a non-grouping query on the
DELETE
’s target table. Note that
WHERE CURRENT OF
cannot be specified together with a Boolean condition.
See DECLARE for more information about using cursors with
WHERE
CURRENT OF
.
Outputs
On successful completion, a
DELETE
command returns a command tag of the form
DELETE count
The count is the number of rows deleted. If count
is 0, no rows matched the condition (this is not considered an error).
Notes on DELETE
Aster Database lets you reference columns of other tables in the WHERE condition by specifying the other tables in the USING clause. For example, to delete all films produced by a given producer, one might do
DELETE FROM films USING producers
WHERE producer_id = producers.id AND producers.name = 'Smith';
What is essentially happening here is a join between films and producers, with all successfully joined films rows being marked for deletion.
Examples
Delete all films but musicals:
DELETE FROM films WHERE kind <> 'Musical';
Clear the table films:
DELETE FROM films;
V--50 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential DROP INDEX
Compatibility of DELETE
This command conforms to the SQL standard, except that the USING clause and the ability to reference other tables in the WHERE clause are Aster Database extensions.
DROP DATABASE
DROP DATABASE -- remove a database
Synopsis
DROP DATABASE name; name
Description
DROP DATABASE
drops a database. It removes the catalog entries for the database and deletes the directory containing the data. It can only be executed by the database owner. Also, it cannot be executed while you or anyone else is connected to the target database.
DROP DATABASE cannot be undone. Use it with care!
Parameters for DROP DATABASE
The name of a database to remove.
Notes
DROP DATABASE
cannot be executed inside a transaction block.
This command cannot be executed while connected to the target database.
Compatibility
There is no
DROP DATABASE
statement in the SQL standard.
See Also
“CREATE DATABASE” on page V-28 .
DROP INDEX
DROP INDEX -- remove an index
Synopsis
DROP INDEX name [, ...] [ CASCADE | RESTRICT ];
December 14, 2011 SQL Commands V--51
DROP ROLE name
CASCADE
RESTRICT
Aster Data proprietary and confidential
Description
DROP INDEX drops an existing index from the database system. To execute this command you must be the owner of the index.
Parameters for DROP INDEX
The name of an index to remove.
Automatically drop objects that depend on the index.
Refuse to drop the index if any objects depend on it. This is the default.
Examples
This command will remove the index title_idx:
DROP INDEX title_idx;
Compatibility
DROP INDEX
is an Aster Database language extension. There are no provisions for indexes in the SQL standard.
See Also
DROP ROLE
DROP ROLE -- remove a role from Aster Database
Synopsis
DROP ROLE name [, ...];
Parameters name
- The name of a role to remove.
Examples
To drop a role:
DROP ROLE ny_admins;
Description
DROP ROLE removes the specified role(s). To drop a role, you must be a superuser.
A role cannot be removed if it is still referenced in any database of the cluster; an error will be raised if so. Before dropping the role, you must drop all the objects it owns (or reassign their ownership) and revoke any privileges the role has been granted.
V--52 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential DROP TABLE
However, it is not necessary to remove role memberships involving the role; DROP ROLE automatically revokes any memberships of the target role in other roles, and of other users and roles in the target role. The other users and roles are not dropped nor otherwise affected.
Compatibility
The SQL standard defines DROP ROLE , but it allows only one role to be dropped at a time, and it specifies different privilege requirements than Aster Database uses.
See Also
“CREATE ROLE” on page V-31 and
DROP SCHEMA
Synopsis
DROP SCHEMA [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ]
Description
DROP SCHEMA removes schemas from the database.
A schema can only be dropped by its owner. Note that the owner can drop the schema (and thereby all contained objects) even if he does not own some of the objects within the schema.
Parameters
IF EXISTS Do not throw an error if the schema does not exist. A notice is issued in this case.
name The name of a schema.
CASCADE Automatically drop objects (tables, functions, etc.) that are contained in the schema.
RESTRICT Refuse to drop the schema if it contains any objects. This is the default.
See Also
and “ALTER SCHEMA” on page V-8
.
DROP TABLE
DROP TABLE -- remove a table
Synopsis
DROP TABLE [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ];
December 14, 2011 SQL Commands V--53
DROP USER Aster Data proprietary and confidential
IF EXISTS name
CASCADE
RESTRICT
Description
DROP TABLE
removes tables from the database. Only its owner may destroy a table. To empty a table of rows, without destroying the table, use
TRUNCATE
or
DELETE
.
DROP TABLE
always removes any indexes and constraints that exist for the target table.
For logically partitioned tables, issuing
DROP TABLE
drops the top level table and all child partitions as well. For parent/child tables created through inheritance, you must issue
DROP
TABLE...CASCADE
in order to drop the child tables in addition to the parent.
Parameters
Do not throw an error if the table does not exist.
The name of the table to drop.
Automatically drop objects that depend on the table.
Refuse to drop the table if any objects depend on it. This is the default.
Examples
To destroy two tables, films and distributors:
DROP TABLE films, distributors;
Compatibility
This command conforms to the SQL standard, except that the standard only allows one table to be dropped per command.
See Also
DROP USER
DROP USER -- delete a user from Aster Database
Synopsis
DROP USER name [, ...];
Example Usage
DROP USER owright;
Description
DROP USER removes the specified user(s). To drop a user, you must be a superuser.
A user cannot be removed if it is still referenced in any database of the cluster; an error will be raised if so. Before dropping the user, you must drop all the objects it owns (or reassign their ownership) and revoke any privileges the user has been granted.
V--54 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential DROP VIEW
However, it is not necessary to remove role memberships involving the user; DROP ROLE automatically revokes any memberships of the target user in other roles. The other roles are not dropped nor otherwise affected.
Compatibility
The DROP USER statement is an Aster Database extension. The SQL standard leaves the definition of users to the implementation.
See Also
DROP VIEW
DROP VIEW -- remove a view
Synopsis
DROP VIEW [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ]
Description
DROP VIEW
drops an existing view. To execute this command you must be the owner of the view.
Parameters
IF EXISTS Do not throw an error if the view does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of the view to remove.
CASCADE Automatically drop objects that depend on the view.
RESTRICT Do not drop the view if other objects depend on it. This is the default behavior.
Examples
This command will remove the view called kinds:
DROP VIEW kinds;
Compatibility
This command conforms to the SQL standard, except that the standard only allows one view to be dropped per command, and apart from the IF EXISTS option, which is an extension.
See Also
ALTER VIEW,
.
December 14, 2011 SQL Commands V--55
END
END
Aster Data proprietary and confidential
END -- commit the current transaction
Synopsis
END [ WORK | TRANSACTION ];
Description
END commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs. This command is an Aster Database extension that is equivalent to COMMIT .
Parameters
WORK or TRANSACTION Optional keywords. They have no effect.
Notes
Use
ROLLBACK
to abort a transaction.
Issuing
END
when not inside a transaction does no harm.
Examples
To commit the current transaction and make all changes permanent:
END;
Compatibility
END is an Aster Database extension that provides functionality equivalent to COMMIT , which is specified in the SQL standard.
See Also
To initiate a transaction:
•
•
To finish a transaction:
•
To cancel a transaction:
•
•
V--56 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential FETCH
EXPLAIN
EXPLAIN -- show the execution plan of a statement
Synopsis
EXPLAIN statement;
Description
This command displays the execution plan that Aster Database uses for the supplied statement, and cost estimates for each of the steps of this execution plan. The execution plan displays information on the exact SQL statements executed in order to satisfy the user-given query, including whether network transfers of data are required and for what purpose. The plan also provides the location at which each step is executed, and the low-level algorithms used to execute a step at the slowest node.
EXPLAIN itself does not execute the statement and therefore has no side-effects (e.g. EXPLAIN on a CREATE TABLE statement does not create the table).
For more details on EXPLAIN, please see “7. Tuning Techniques III: Read the EXPLAIN Plan” on page II-73 , which provides detailed documentation on interpreting EXPLAIN output.
Parameters statement A statement whose execution plan you wish to see. You cannot run EXPLAIN on a
DELETE statement.
Notes
The statement whose execution plan you wish to see should be both syntactically and semantically correct outside the
EXPLAIN
context. For instance, you cannot run
EXPLAIN
on a
SELECT
statement on a table that does not exist.
Compatibility
There is no
EXPLAIN
statement defined in the SQL standard.
See Also
“7. Tuning Techniques III: Read the EXPLAIN Plan” on page II-73 .
FETCH
FETCH -- retrieve rows from a query using a cursor
Synopsis
FETCH [ direction { FROM | IN } ] cursorname; where direction can be empty or one of:
December 14, 2011 SQL Commands V--57
FETCH Aster Data proprietary and confidential
NEXT
PRIOR
FIRST
LAST
ABSOLUTE count
RELATIVE count
count
ALL
FORWARD
FORWARD count
FORWARD ALL
BACKWARD
BACKWARD count
BACKWARD ALL
Description
FETCH retrieves rows using a previously-created cursor.
A cursor has an associated position, which is used by FETCH . The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result. When created, a cursor is positioned before the first row. After fetching some rows, the cursor is positioned on the row most recently retrieved. If FETCH runs off the end of the available rows then the cursor is left positioned after the last row, or before the first row if fetching backward. FETCH ALL or FETCH BACKWARD ALL will always leave the cursor positioned after the last row or before the first row.
The forms NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE fetch a single row after moving the cursor appropriately. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as appropriate.
The forms using FORWARD and BACKWARD retrieve the specified number of rows moving in the forward or backward direction, leaving the cursor positioned on the last-returned row (or after/before all rows, if the count exceeds the number of rows available).
RELATIVE 0, FORWARD 0 , and BACKWARD 0 all request fetching the current row without moving the cursor, that is, re-fetching the most recently fetched row. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned.
V--58 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential FETCH
direction
NEXT
PRIOR
FIRST
LAST
ABSOLUTE count
RELATIVE count
ALL
FORWARD
FORWARD count
FORWARD ALL
BACKWARD
BACKWARD count
BACKWARD ALL
count
cursorname
Parameters
direction defines the fetch direction and number of rows to fetch. This parameter can have one of the values listed below.
Fetch the next row. This is the default if direction is omitted.
Fetch the prior row.
Fetch the first row of the query (same as ABSOLUTE 1 ).
Fetch the last row of the query (same as ABSOLUTE -1 ).
Fetch the count th
row of the query, or the abs( count ) th
row from the end if count is negative. Position before first row or after last row if count is out of range; in particular, ABSOLUTE 0 positions before the first row.
Fetch the count th
succeeding row, or the abs( count ) th
prior row if count is negative.
RELATIVE 0
re-fetches the current row, if any.
Fetch all remaining rows (same as
FORWARD ALL
).
Fetch the next row (same as
NEXT
).
Fetch the next count rows.
FORWARD 0
re-fetches the current row.
Fetch all remaining rows.
Fetch the prior row (same as
PRIOR
).
Fetch the prior count rows (scanning backwards).
BACKWARD 0
re-fetches the current row.
Fetch all prior rows (scanning backwards).
count is a possibly-signed integer constant, determining the location or number of rows to fetch. If you supply a count value alone, without
FORWARD or any other keyword, Aster Database treats it as a FORWARD
count
).
If you supply a negative count value with FORWARD or BACKWARD , you reverse the sense of
FORWARD
or
BACKWARD
.
An open cursor’s name.
Output
On successful completion, a
FETCH
command returns a command tag of the form:
FETCH count where
count
is the number of rows fetched (possibly zero).
Notes
The cursor should be declared with the
SCROLL
option if one intends to use any variants of
FETCH
other than
FETCH NEXT
or
FETCH FORWARD
with a positive count. For simple queries, Aster Database will allow backwards fetch from cursors not declared with
SCROLL
, but this behavior is best not relied on. If the cursor is declared with
NO SCROLL
, no backward fetches are allowed.
ABSOLUTE
fetches are not any faster than navigating to the desired row with a relative move: the underlying implementation must traverse all the intermediate rows anyway. Negative absolute fetches are even worse: the query must be read to the end to find the last row, and then traversed backward from there. However, rewinding to the start of the query (as with
FETCH
ABSOLUTE 0
) is fast.
Updating data via a cursor is currently not supported by Aster Database.
December 14, 2011 SQL Commands V--59
FETCH Aster Data proprietary and confidential
DECLARE
is used to define a cursor. Use
MOVE
to change the cursor position without retrieving data.
Examples
The following example traverses a table using a cursor:
BEGIN WORK;
-- Set up a cursor:
DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;
-- Fetch the first 5 rows in the cursor liahona:
FETCH FORWARD 5 FROM liahona;
code | title | did | date_prod | kind
-------+-------------------------+-----+------------+----------
BL101 | The Third Man | 101 | 1949-12-23 | Drama
BL102 | The African Queen | 101 | 1951-08-11 | Romantic
JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic
P_301 | Vertigo | 103 | 1958-11-14 | Action
P_302 | Becket | 103 | 1964-02-03 | Drama
-- Fetch the previous row:
FETCH PRIOR FROM liahona;
code | title | did | date_prod | kind
-------+---------+-----+------------+--------
P_301 | Vertigo | 103 | 1958-11-14 | Action
-- Close the cursor and end the transaction:
CLOSE liahona;
COMMIT WORK;
Compatibility
The SQL standard defines
FETCH
for use in embedded SQL only. The variant of
FETCH described here returns the data as if it were a
SELECT
result rather than placing it in host variables. Other than this point,
FETCH
is fully upward-compatible with the SQL standard.
The
FETCH
forms involving
FORWARD
and
BACKWARD
, as well as the forms
FETCH
count and
FETCH ALL
, in which
FORWARD
is implicit, are Aster Database extensions.
The SQL standard allows only FROM preceding the cursor name; the option to use IN is an extension.
See Also
.
V--60 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential GRANT
GRANT
GRANT -- define access privileges
Synopsis
GRANT { { SELECT | INSERT | UPDATE | DELETE }
[,...] | ALL [ PRIVILEGES ] }
ON [ TABLE ] tablename [, ...]
TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] [ CASCADE ]
GRANT { { CREATE | CONNECT } [,...] | ALL [ PRIVILEGES ] }
ON DATABASE dbname [, ...]
TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
ON SCHEMA schemaname [, ...]
TO { username | GROUP rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { INSTALL FILE | CREATE FUNCTION } [, ...] [ PRIVILEGE ]
ON SCHEMA schemaname [, ...]
TO { username | GROUP rolename | PUBLIC } [, ...]
GRANT EXECUTE [ PRIVILEGE ]
ON FUNCTION [schemaname.]funcname
TO { username | GROUP rolename | PUBLIC } [, ...]
GRANT rolename [, ...]
TO username [, ...] [ WITH ADMIN OPTION ];
Description
The GRANT command has two basic variants: one that grants privileges on a database object like a table or database (see
“GRANT on Database Objects” on page V-61 ) and one that grants
membership in a role (see
“GRANT on Roles” on page V-63 ). These variants are similar in many
ways, but they are different enough that we’ll describe them separately, below.
GRANT on Database Objects
This variant of the
GRANT
command gives privileges on a database object to one or more roles.
These privileges are added to those already granted, if any.
The keyword
PUBLIC
specifies that the privileges are to be granted to all roles, including those that might be created later.
PUBLIC
can be thought of as an implicitly defined group that always includes all roles. Any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to
PUBLIC
.
If
WITH GRANT OPTION
is specified, the recipient of the privilege may in turn grant it to others. Without a grant option, the recipient cannot do that. Grant options cannot be granted to
PUBLIC
.
If
CASCADE
is specified, then the rights you grant on a parent table cascade to all its child tables.
CASCADE
works only when granting table privileges.
There is no need to grant privileges to the owner of an object (usually the user that created it), as the owner has all privileges by default. The right to drop an object, or to alter its definition in any
December 14, 2011 SQL Commands V--61
GRANT Aster Data proprietary and confidential way is not described by a grantable privilege; it is inherent in the owner, and cannot be granted or revoked. The owner implicitly has all grant options for the object, too.
Depending on the type of object, the initial default privileges might include granting some privileges to
PUBLIC
. The default is no public access for tables and schemas;
CONNECT privilege for databases. The object owner can of course revoke these privileges. (For maximum security, issue the
REVOKE
in the same transaction that creates the object; then there is no window in which another user can use the object.)
The possible privileges are:
CREATE For databases, gives the user/role the right to create new schemas in the database.
Note! Granting CREATE on a database does not confer the right to create tables. To do that, you must grant the user CREATE on a schema in the database.
Granting CREATE on a schema gives the user or role the right to create new tables and objects in the schema. To rename an existing object, you must own the object and have this privilege for the containing schema. See also,
“Revoking Users Rights to Create Tables” on page V-72 .
SELECT Allows SELECT from any column of the specified table. Also allows the use of COPY
TO. This privilege is also needed to reference existing column values in UPDATE or DELETE.
INSERT Allows INSERT of a new row into the specified table. Also allows COPY FROM.
UPDATE Allows UPDATE of any column of the specified table. (In practice, any nontrivial
UPDATE command will require SELECT privilege as well, since it must reference table columns to determine which rows to update, and/or to compute new values for columns.)
USAGE Granting USAGE on a schema gives the user or role the right to access objects contained in the specified schema (assuming that the objects’ own privilege requirements are also met). Essentially this allows the grantee to “look up” objects within the schema.
DELETE Allows DELETE of a row from the specified table. (In practice, any nontrivial
DELETE command will require SELECT privilege as well, since it must reference table columns to determine which rows to delete.)
CONNECT Allows the user to connect to the specified database. This privilege is checked when the user attempts to connect. For new databases you create, only you have the CONNECT privilege. If you want other users to be able to CONNECT to a database, you must GRANT
CONNECT on the database to the user or group. For example, you can give all users the right to connect as shown here:
GRANT CONNECT ON DATABASE retail_sales TO PUBLIC;
INSTALL FILE, CREATE FUNCTION Allow the user to upload and install files and
SQL-MapReduce functions, respectively, in the schema. See “SQL-MapReduce Security” on page I-79 .
EXECUTE Allows the user to run the SQL-MapReduce function. See
“SQL-MapReduce
Security” on page I-79 .
ALL PRIVILEGES Grant all of the available privileges at once. The PRIVILEGES keyword is optional.
V--62 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential GRANT
GRANT on Roles
This variant of the GRANT command grants membership in a role to one or more roles or users.
Membership in a role conveys the role’s privileges to each of its members. Note that you cannot grant db_admin
role (the Aster Database superuser role) to another role, because there is no need for multiple privileged roles in Aster Database. Also, you cannot grant a user to another user.
If WITH ADMIN OPTION is specified, the member may in turn grant membership in the role to others, and revoke membership in the role as well. Without the admin option, ordinary users cannot do that. Roles having db_admin privilege can grant or revoke membership in any role.
Unlike the case with privileges, membership in a role cannot be granted to PUBLIC . Note also that this form of the command does not allow the noise word GROUP .
Notes on GRANT
The REVOKE command is used to remove users’ access privileges.
When a non-owner of an object attempts to
GRANT
privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object. As long as some privilege is available, the command will proceed, but it will grant only those privileges for which the user has grant options.
GRANT
and
REVOKE
can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges
WITH
GRANT OPTION
on the object. In this case the privileges will be recorded as having been granted by the role that actually owns the object or holds the privileges
WITH GRANT
OPTION
. For example, if table t1 is owned by role g1, of which role u1 is a member, then u1 can grant privileges on t1 to u2, but those privileges will appear to have been granted directly by g1.
Any other member of role g1 could revoke them later.
If the role executing
GRANT
holds the required privileges indirectly via more than one role membership path, it is unspecified which containing role will be recorded as having done the grant.
Roles and privleges are one factor that determines what a user can do in the AMC. For more information on what determines the actions a user may perform in the AMC, see “Allowed
Administrative Actions” on page III-23 .
TRIGGER
and
TEMPORARY
privileges are not supported in Aster Database.
Examples
Grant insert privilege to all users on table films
:
GRANT INSERT ON films TO PUBLIC;
Grant all privileges to all users on database films
:
GRANT ALL PRIVILEGES ON DATABASE films TO PUBLIC;
Grant membership in role admins
to user jstrummer:
GRANT admins TO jstrummer;
Compatibility
The SQL standard does not support setting the privileges on more than one object per command.
December 14, 2011 SQL Commands V--63
INSERT Aster Data proprietary and confidential
Aster Database does not support the SQL-standard functionality of setting privileges for individual columns. Privileges on databases is an Aster Database extension.
See Also
. See also “Default Roles and Users” on page II-95 for descriptions of the Aster Database default roles.
INSERT
INSERT -- create new rows in a table
Synopsis
INSERT INTO table [ ( column [, ...] ) ] [ AUTOPARTITION ]
{ VALUES ( value [, ...] ) [, ...] | query }
Description
INSERT
inserts new rows into a table. One can insert one or more rows specified by value expressions, or several rows as a result of a query.
The target column names may be listed in any order. If no list of column names is given, the default is all the columns of the table in their declared order; or the first n column names, if there are only n columns supplied by the
VALUES
clause or query. The values supplied by the
VALUES
clause or query are associated with the explicit or implicit column list left-to-right.
Each column not present in the explicit or implicit column list will be filled with the default value if that column has a DEFAULT rule defined, of with a value of null if there is no
DEFAULT rule. See
“Working With Default Values” on page V-65 .
Parameters table The name of an existing table. column The name of a column into which you will insert data. The column name can be qualified with a subfield name or array subscript, if needed. (Inserting into only some fields of a composite column leaves the other fields null.) value The value to be assigned to the specified column. This may be an expression that will be evaluated at insertion time. If the value expression for any column is not of the correct datatype, Aster Database attempts an automatic type conversion.
query A query ( SELECT statement) that supplies the rows to be inserted. Refer to the SELECT statement for a description of the syntax. The following additional restrictions apply:
The SELECT statement may not be a compound query.
The
SELECT
statement must include the distribution key constraint defined on the target table.
Outputs
On successful completion, an
INSERT
command returns a command tag of the form
INSERT oid count
V--64 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential INSERT
The count is the number of rows inserted. If count is exactly one, and the target table has OIDs, then oid is the OID assigned to the inserted row. Otherwise oid is zero.
Notes
If your data model uses table inheritance, please note that INSERT always inserts into exactly the table you specify. The INSERT does not cascade to a child table. If you wish to insert into a child table of the parent table referenced in the INSERT statement, you must use the
AUTOPARTITION keyword.
The AUTOPARTITION keyword automatically partitions data during insertion. With this feature enabled, Aster Database automatically routes each row within a parent/child table hierarchy down to the appropriate child table. Logical partitioning through inheritance is done based on the check constraints of the target table. See “Autopartitioning” on page II-141 .
Examples
Insert a single row into table films
:
INSERT INTO films VALUES
('UA502', 'Bananas', 105, '1971-07-13', 'Comedy');
In this example, the kind
column is omitted and therefore it will have the default value of null:
INSERT INTO films (code, title, did, date_prod)
VALUES ('T_601', 'Yojimbo', 106, '1961-06-16');
This example inserts some rows into table films from a table tmp_films
with the same column layout as films
:
INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';
To insert multiple rows into films
using the multirow VALUES syntax:
INSERT INTO films (code, title, did, date_prod, kind) VALUES
('UA001', 'Apples', 105, '1971-07-13', 'Comedy', '82 minutes'),
('UA002', 'Bananas', 106, '1971-07-13', 'Romance', '90 minutes'),
('UA003', 'Crash', 107, '2005-11-01', 'Drama', '85 minutes'),
...
('UA999', 'Zathura', 909, '2005-07-04', 'Action', '100 minutes') ;
Working With Default Values
A column may be defined to have a default value. (See CREATE TABLE or
for instructions on defining a default value for a column.) For such a column, when you INSERT a row into a table, the default value is used if you omit the column value from the INSERT statement, or if you pass the “DEFAULT” keyword to request that the default value be used. The default value is used in these cases:
•
• if you omit the column from the columns list and the value from the VALUES list. For example:
INSERT INTO t1 (col1, col3) VALUES (1, 3); will put the default value into the column "col2". (This example assumes there is a col2.) if you include the “DEFAULT” keyword. For example, the statement
INSERT INTO t1 (col1, col2, col3) VALUES (1, DEFAULT, 3);
December 14, 2011 SQL Commands V--65
MERGE Aster Data proprietary and confidential
• will again put the default value into the column "col2".
if you omit the columns list and VALUES list and include the keywords, “DEFAULT
VALUES”. In this case Aster Database creates a row using the default values for all columns. For example:
INSERT INTO t1 DEFAULT VALUES;
Compatibility
INSERT
conforms to the SQL standard. The case in which a column name list is omitted, but not all the columns are filled from the
VALUES
clause or query, is disallowed by the standard. The case in which multiple rows are inserted as a single transaction is also disallowed by the standard.
The specification of columns in an embedded
SELECT
clause is an Aster Database extension.
Possible limitations of the query clause are documented under
SELECT
.
MERGE
MERGE -- update or insert rows of a table based on source data
Synopsis
MERGE INTO table [ [ AS ] table-alias ]
USING source [ [ AS ] source-alias ]
ON join-condition
merge-operation [...] where each merge-operation (you may have many) is one of
WHEN MATCHED THEN modification-operation [ WHERE predicate ] or
WHEN NOT MATCHED THEN insert-operation [ WHERE predicate ] where source is
TABLE | VIEW | SUBQUERY where modification-operation is
UPDATE SET column1 = value1 [, column2 = value2 ...] where insert-operation is
INSERT ( column1 [, column2 ...] ) VALUES ( value1 [, value2 ...] )
Description
MERGE performs at most one action on each row from the target table, driven by the rows from the source query. This provides a way to specify a single SQL statement that can conditionally
UPDATE or INSERT rows, a task that would otherwise require multiple procedural language statements.
V--66 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential MERGE
First, the MERGE command performs a left outer join from source query to target table, producing zero or more to-be-merged rows. For each to-be-merged row, WHEN clauses are evaluated in the specified order until one of them is activated. The corresponding action is applied, and MERGE proceeds to the next to-be-merged row. The running of MERGE affects rows in the target table only.
If no WHEN clause activates for a row, then that row is left unchanged.
Each output row of the join may activate at most one WHEN-clause. The row will be matched only once per statement, so the status of MATCHED or NOT MATCHED cannot change once testing of WHEN clauses has begun.
Parameters and Clauses table The name (optionally schema-qualified) of the table to merge into.
table-alias, source-alias The alias name of the target must be different from the alias name of the source.
source The view, table or subquery that will provide the data to be placed in the target table.
INSERT An empty column list for INSERT implies all columns of the target table, in the order in which they are defined in the target table.
join-condition The merge join predicate can be any boolean-valued expression that is a valid
ON clause in a left outer join. The merge join predicate and WHEN predicates must not invoke routines that modify data.
Output
On successful execution, MERGE returns a summary of the actions it performed. For example:
UPDATE 11, INSERT 15
.
Notes
•
•
•
•
•
Semantic rules and limitations
The following are the semantic rules and limitations of the MERGE command in Aster Database:
Multiple actions on same target row not allowed.
Multiple source rows for a given target row are allowed as long as Rule 1 is not violated.
A replicated dimension table cannot be the target table of a merge SQL statement.
MERGE fails if the target table is replicated and contains a serial/bigserial column.
Aster Database MERGE does not support a DELETE clause in its current implementation!
WHEN clauses
The merge WHEN clause predicates are applied on the rows after the join condition has found a match (for a merge WHEN MATCHED clause, a.k.a. “MWM clause”) or a non-match (for a merge WHEN NOT MATCHED clause, a.k.a. “MWNM clause”). Hence, they can be any boolean-valued expressions that use columns values from the corresponding target and the source rows.
Insert behavior when no MWNM clause matches
December 14, 2011 SQL Commands V--67
MERGE Aster Data proprietary and confidential
If you are running a merge that has MWNM clauses, but you have not defined a catch-all
MWNM clause, then it can happen that some source rows are non-matches but also fail to trigger any MWNM clause, because they do not match the predicate of any MWNM clause.
In such cases, Aster Database follows the SQL standard, which requires that the MERGE command ignore these rows. In other words, the unmatched rows are dropped. To avoid dropping rows that you might want to merge, Aster Data recommends that you add default catch-all
MWM and MWNM clauses (a catch-all is a clause without a predicate) that will merge these rows into the target, adding appropriate warning labels in each row, if needed.
User permissions
There is no MERGE privilege. The user must have the UPDATE privilege on the table if an update action is specified, the INSERT privilege if an insert action is specified. The user must also have the SELECT privilege on any table whose values are read in the expressions or conditions.
Example
As an example, imagine that our database holds user accounts in a user
table, and that we have a web application that lets a user create a new account or change his or her password. The web application’s data gets saved into a web_update
table that is periodically merged into the user table. The periodic MERGE would be done like this:
MERGE INTO user
USING web_update
ON user.userid = web_update.userid
WHEN MATCHED THEN
UPDATE SET user.passwd = web_update.passwd
WHEN NOT MATCHED THEN
INSERT (user.userid, user.passwd)
VALUES (web_update.userid, web_update.passwd);
Recall that an empty column list for the INSERT implies all columns of the target table, in the order in which they are defined in the target table. This means that we can abbreviate the last clause of the example like so:
MERGE INTO user
USING web_update
ON user.userid = web_update.userid
WHEN MATCHED THEN
UPDATE SET user.passwd = web_update.passwd
WHEN NOT MATCHED THEN
INSERT VALUES (web_update.userid, web_update.passwd);
Compatibility
Aster Database MERGE does not support a DELETE clause in its current implementation! The
SQL standard does not specify a DELETE clause for MERGE, but some other database systems do support such a clause.
See Also
V--68 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential MOVE
MOVE
MOVE -- position a cursor
Synopsis
MOVE [ direction { FROM | IN } ] cursorname;
Description
MOVE repositions a cursor without retrieving any data. MOVE works exactly like the FETCH command, except it only positions the cursor and does not return rows.
for details on syntax and usage.
Output
On successful completion, a
MOVE
command returns a command tag of the form:
MOVE count
The count is the number of rows that a
FETCH
command with the same parameters would have returned (possibly zero).
Examples
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM films;
-- Skip the first 5 rows:
MOVE FORWARD 5 IN liahona;
MOVE 5
-- Fetch the 6th row from the cursor liahona:
FETCH 1 FROM liahona;
code | title | did | date_prod | kind
-------+--------+-----+------------+--------
P_303 | 48 Hrs | 103 | 1982-10-22 | Action
(1 row
)
-- Close the cursor liahona and end the transaction:
CLOSE liahona;
COMMIT WORK;
Compatibility
There is no
MOVE
statement in the SQL standard.
See Also
.
December 14, 2011 SQL Commands V--69
REINDEX Aster Data proprietary and confidential
REINDEX
REINDEX -- rebuild indexes
Synopsis
REINDEX { INDEX | TABLE } name [ FORCE ];
Description
REINDEX rebuilds an index using the data stored in the index's table, replacing the old copy of the index. There are two main reasons to use REINDEX :
•
•
An index has become corrupt and contains invalid data. Although in theory this should never happen, in practice indexes may become corrupted due to software bugs or hardware failures.
The index in question contains a lot of dead index pages. This can occur with B-tree indexes in Aster Database under certain access patterns.
REINDEX
reclaims space by rewriting a new version of the index without the dead pages.
Parameters
INDEX
TABLE name
FORCE
Recreate the specified index.
Recreate all indexes of the specified table.
The name of the specific index, table, or database to be reindexed. Presently,
REINDEX DATABASE can only reindex the current database, so their parameter must match the current database's name.
This option is ignored if specified.
Notes
If you suspect corruption of an index on a user table, you can simply rebuild that index, or all indexes on the table, using
REINDEX INDEX
or
REINDEX TABLE
.
For all user-specified indexes,
REINDEX
is crash-safe and transaction-safe.
REINDEX
is similar to a drop and recreate of the index in that the index contents are rebuilt from scratch. However, the locking considerations are rather different.
REINDEX
locks out writes but not reads of the index's parent table. It also takes an exclusive lock on the specific index being processed, which will block reads that attempt to use that index. In contrast,
DROP INDEX momentarily takes exclusive lock on the parent table, blocking both writes and reads. The subsequent
CREATE INDEX
locks out writes but not reads; since the index is not there, no read will attempt to use it, meaning that there will be no blocking but reads may be forced into expensive sequential scans. Another important point is that the drop/create approach invalidates any cached query plans that use the index, while
REINDEX
does not.
Reindexing a single index or table requires being the owner of that index or table. Superusers can reindex anything.
Note!
Aster Database does not support reindexing the whole database. To reindex your database, run REINDEX on each table in the database.
V--70 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Examples
Recreate the indexes on the table my_table :
REINDEX TABLE my_table;
Rebuild a single index:
REINDEX INDEX my_index;
Compatibility
There is no
REINDEX
command in the SQL standard.
REVOKE
REVOKE
REVOKE -- remove access privileges
Synopsis
REVOKE [ GRANT OPTION FOR ]
{ { SELECT | INSERT | UPDATE | DELETE | REFERENCES }
[,...] | ALL [ PRIVILEGES ] }
ON [ TABLE ] tablename [, ...]
FROM { [ GROUP ] rolename | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]
{ { CREATE | CONNECT } [,...] | ALL [ PRIVILEGES ] }
ON DATABASE dbname [, ...]
FROM { [ GROUP ] rolename | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]
{ { CREATE | USAGE | INSTALL FILE | CREATE FUNCTION } [,...] | ALL [PRIVILEGES] }
ON SCHEMA schemaname [, ...]
FROM { [ GROUP ] rolename | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]
EXECUTE [ PRIVILEGES ]
ON FUNCTION [schemaname.]funcname
FROM{ [ GROUP ] rolename | PUBLIC } [, ...]
REVOKE [ ADMIN OPTION FOR ]
role [, ...] FROM username [, ...]
[ CASCADE | RESTRICT ];
Description
The
REVOKE
command revokes previously granted privileges from one or more roles or users.
The keyword
PUBLIC
refers to the implicitly defined group of all roles.
See the description of the GRANT command for the meaning of the privilege types.
December 14, 2011 SQL Commands V--71
REVOKE Aster Data proprietary and confidential
Note that any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is now a member of, and privileges granted to
PUBLIC
. Thus, for example, revoking
SELECT
privilege from
PUBLIC
does not necessarily mean that all roles have lost
SELECT
privilege on the object: those who have it granted directly or via another role will still have it.
If
GRANT OPTION FOR
is specified, only the grant option for the privilege is revoked, not the privilege itself. Otherwise, both the privilege and the grant option are revoked.
If a user holds a privilege with grant option and has granted it to other users then the privileges held by those other users are called dependent privileges. If the privilege or the grant option held by the first user is being revoked and dependent privileges exist, those dependent privileges are also revoked if
CASCADE
is specified, else the revoke action will fail. This recursive revocation only affects privileges that were granted through a chain of users that is traceable to the user that is the subject of this
REVOKE
command. Thus, the affected users may effectively keep the privilege if it was also granted through other users.
When revoking membership in a role,
GRANT OPTION
is instead called
ADMIN OPTION
, but the behavior is similar.
Notes
Revoking Users Rights to Create Tables The
CREATE
privilege on a database governs a user’s right to create schemas, not tables. Therefore,
REVOKE CREATE ON DATABASE...
only removes a user’s right to create schemas in the database. He or she can still create tables. To limit users’ rights to create tables, you can follow one of the approaches below:
•
•
•
Approach 1: Revoke the user’s connect privilege on the database. This is a broad-brushed approach; it denies the user’s right to run any queries at all on the database. For a less restrictive approach, do one of the following, instead:
Approach 2: Revoke the user’s
CREATE
privilege on the schema in which you want to restrict this right. For example, if your users work only in the
PUBLIC
schema, then you can revoke the
CREATE
privilege on the
PUBLIC
schema from the
PUBLIC
role, and then grant
CREATE
on the
PUBLIC
schema back to
OWNER
and to the other users or roles who are allowed to create tables.
Approach 3: You can use schemas to manage rights:
•
Revoke the
CREATE
privilege on the
PUBLIC
schema from the
PUBLIC
role.
•
Create appropriate schemas in each database, and grant CREATE on each schema appropriately. For example, in one database with relatively free permissions you would grant CREATE on its schema to PUBLIC role, but in other, more restricted databases you would grant CREATE on their schemas only to those users and roles whom you wish to grant rights.
Revoking Rights to Objects in a Schema For information on using REVOKE USAGE
.
Which Privileges Can I Revoke? A user can only revoke privileges that were granted directly by that user. If, for example, user A has granted a privilege with grant option to user B, and user B has in turned granted it to user C, then user A cannot revoke the privilege directly from C. Instead, user A could revoke the grant option from user B and use the CASCADE option so that the privilege is in turn revoked from user C. For another example, if both A and B have granted the same privilege to C, A can revoke his own grant but not the grant from B, so C will still effectively have the privilege.
V--72 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential REVOKE
When a non-owner of an object attempts to
REVOKE
privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object. As long as some privilege is available, the command will proceed, but it will revoke only those privileges for which the user has grant options. The
REVOKE ALL PRIVILEGES
forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held. (In principle these statements apply to the object owner as well, but since the owner is always treated as holding all grant options, the cases can never occur.)
REVOKE
can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges
WITH GRANT
OPTION
on the object. In this case the command is performed as though it were issued by the containing role that actually owns the object or holds the privileges
WITH GRANT OPTION
.
For example, if table t1 is owned by role g1, of which role u1 is a member, then u1 can revoke privileges on t1 that are recorded as being granted by g1. This would include grants made by u1 as well as by other members of role g1.
If the role executing
REVOKE
holds privileges indirectly via more than one role membership path, it is unspecified which containing role will be used to perform the command.
Roles and privleges are one factor that determines what a user can do in the AMC. For more information on what determines the actions a user may perform in the AMC, see “Allowed
Administrative Actions” on page III-23 .
Examples
Revoke connect privilege for user mjones on database imdb :
REVOKE CONNECT ON DATABASE imdb FROM mjones;
Revoke insert privilege for the public on table films
:
REVOKE INSERT ON films FROM PUBLIC;
Revoke all privileges for the public on database films:
REVOKE ALL PRIVILEGES ON DATABASE films FROM PUBLIC;
Revoke membership in role admins from user jstrummer:
REVOKE admins FROM jstrummer;
Compatibility
The compatibility notes of the
GRANT
command apply analogously to
REVOKE
.
One of
RESTRICT
or
CASCADE
is required according to the standard, but Aster Database assumes
RESTRICT
by default.
See Also
December 14, 2011 SQL Commands V--73
ROLLBACK Aster Data proprietary and confidential
ROLLBACK
ROLLBACK -- abort the current transaction
Synopsis
ROLLBACK [ WORK | TRANSACTION ];
Description
ROLLBACK rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical in behavior to the Aster Database command ABORT .
Parameters
WORK or TRANSACTION Optional keywords. They have no effect.
Notes
Use
COMMIT
to successfully terminate a transaction.
Issuing
ROLLBACK
when not inside a transaction does no harm.
Examples
To abort all changes:
ROLLBACK;
Compatibility
The SQL standard only specifies the two forms ROLLBACK and ROLLBACK WORK . Otherwise, this command is fully conforming.
See Also
To initiate a transaction:
•
•
To finish a transaction:
•
•
To cancel a transaction:
•
V--74 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
SELECT
•
•
•
•
•
SELECT -- retrieve rows from a table or view
See details in the following sections:
“Synopsis of SELECT” on page V-75
“Description of SELECT” on page V-76
“Clauses of the SELECT Statement” on page V-76
“Examples of SELECT Statements” on page V-82
“Compatibility of SELECT” on page V-82
Synopsis of SELECT
SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ]
* | expression [ [ AS ] output_name ] [, ...]
[ FROM from_item [, ...] ]
[ WHERE condition ]
[ GROUP BY expression [, ...] ]
[ HAVING condition [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL ] select ]
[ ORDER BY expression [ ASC | DESC ][ NULLS { FIRST | LAST } ] [, ...] ]
[ LIMIT { count | ALL } ]
[ OFFSET start ]; where
from_item
can refer to a table...
[ ONLY ] table_name [ * ] [ [ AS ] alias ] or a query...
( select ) [ AS ] alias or an SQL-MapReduce function call...
sqlmr_function_name
( ON { table_name | ( query ) }
PARTITION BY expression [, ...]
ORDER BY expression [ ASC | DESC ] [, ...]
[ clause_name ( literal [, ... ] ) ] [ ... ]
) [ [ AS ] alias ] or a stream function call...
STREAM
( ON { table_name | view_name | ( query ) }
PARTITION BY expression [, ...]
ORDER BY expression [ ASC | DESC ] [ , ... ]
SCRIPT ( 'scriptname' )
[ OUTPUTS ( 'column_name column_type' [ , ... ] ) ]
[ DELIMITER ( delimiter_character ) ] )
) [ [ AS ] alias ] and you can join
from_item
s in the form:
from_item [ NATURAL ] join_type from_item
[ ON join_condition | USING ( join_column [, ...] ) ]
SELECT
December 14, 2011 SQL Commands V--75
SELECT Aster Data proprietary and confidential
Description of SELECT
SELECT
retrieves rows from one table. The general processing of
SELECT
is:
1.
All elements in the
FROM
list are computed. (Each element in the
FROM
list is a real or virtual table.) If more than one element is specified in the
FROM
list, they are cross-joined
together. See “FROM Clause in SELECT” on page V-77 .
2.
If the
WHERE
clause is specified, all rows that do not satisfy the condition are eliminated
from the output. See “WHERE Clause in SELECT” on page V-78
.
3.
If the
GROUP BY
clause is specified, the output is divided into groups of rows that match on one or more values. If the
HAVING
clause is present, it eliminates groups that do not satisfy the given condition. See
“GROUP BY Clause in SELECT” on page V-78
Clause in SELECT” on page V-79 .
4.
The actual output rows are computed using the
SELECT
output expressions for each
selected row. See “The SELECT List” on page V-77 .
5.
Using the operators
UNION
,
INTERSECT
, and
EXCEPT
, the output of more than one
SELECT
statement can be combined to form a single result set. The
UNION
operator returns all rows that are in one or both of the result sets. The
INTERSECT
operator returns all rows that are strictly in both result sets. The
EXCEPT
operator returns the rows that are in the first result set but not in the second. In all three cases, duplicate rows are eliminated unless
ALL is specified. See
“UNION Clause in SELECT” on page V-79
,
, and “EXCEPT Clause in SELECT” on page V-80
.
6.
If the
ORDER BY
clause is specified, the returned rows are sorted in the specified order. If
ORDER BY
is not given, the rows are returned in whatever order the system finds fastest to
produce. See “ORDER BY Clause in SELECT” on page V-80 .
7.
DISTINCT
eliminates duplicate rows from the result.
DISTINCT ON
eliminates rows that match on all the specified expressions.
ALL
(the default) will return all candidate rows,
including duplicates. See “DISTINCT Clause in SELECT” on page V-81
.
8.
If the
LIMIT
or
OFFSET
clause is specified, the
SELECT
statement only returns a subset of
the result rows. See “LIMIT Clause in SELECT” on page V-81 .
You must have
SELECT
privilege on a table to read its values.
•
•
•
•
•
•
•
•
•
•
•
Clauses of the SELECT Statement
We discuss the SELECT command’s clauses and their parameters in these sections, below:
“The SELECT List” on page V-77
“FROM Clause in SELECT” on page V-77
“WHERE Clause in SELECT” on page V-78
“GROUP BY Clause in SELECT” on page V-78
“HAVING Clause in SELECT” on page V-79
“UNION Clause in SELECT” on page V-79
“INTERSECT Clause in SELECT” on page V-79
“EXCEPT Clause in SELECT” on page V-80
“ORDER BY Clause in SELECT” on page V-80
“DISTINCT Clause in SELECT” on page V-81
“LIMIT Clause in SELECT” on page V-81
V--76 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential SELECT
The SELECT List
The SELECT list (between the keywords SELECT and FROM ) specifies expressions that form the output rows of the SELECT statement. The expressions can (and usually do) refer to columns computed in the FROM clause. Instead of an expression, you can type the wildcard character (an asterisk,
*
) in the output list as a shorthand meaning “all the columns” of the selected rows.
Important note about using the wildcard: When you use the wildcard (*) in an Aster
Database query, Aster Database does not guarantee that the column ordering will remain the same across different versions of Aster Database. In other words, a SELECT * query in Aster
Database 4.6 might return columns in a different order than the same query run against Aster
Database 4.5. For your reporting queries, please specify the desired columns, in order, in your
SELECT list.
The optional
AS output_name
phrase declares a column name alias of output_name
, which is an alternative name you can use in the rest of your query and in the query output to refer to a column. You can use the alias to refer to the column’s value in
ORDER BY
and
DISTINCT ON clauses, but not in the
WHERE
or
HAVING
or
GROUP BY
clauses; in those clauses you must write out the expression instead. Aliased expressions can be referred to inside a window function, as long as the aliased expression itself does not contain a window function.
The
AS
keyword is optional when declaring an alias. For example,
SELECT subscriberid id has the same meaning as
SELECT subscriberid AS id
. The Aster Database parser prohibits the use of reserved words as aliases. If your statement uses a reserved word as a column alias, the statement will generate a syntax error.
FROM Clause in SELECT
The FROM clause, represented by
from_item
in the
Synopsis of SELECT , specifies one or
more source tables, subselects, SQL-MapReduce functions (see “SQL-MapReduce Query
Syntax” on page I-58 ), or stream functions (see “Stream Function Query Syntax” on page I-77 ).
The FROM clause is the source of information for the SELECT statement. The FROM clause can contain the following elements: table_name The name (optionally schema-qualified) of an existing table or view. If ONLY is specified, only that table is scanned. If ONLY is not specified, the table and all its child and descendant tables (if any) are scanned.
alias A substitute name for the table, subselect, or SQL-MapReduce function you’re querying.
You can use an alias for brevity or to eliminate ambiguity for self-joins (where the same table is scanned multiple times). When an alias is provided, it completely hides the actual name of the table or function; for example given the statement,
FROM sales AS s
, the remainder of the
SELECT must refer to this FROM item as s
instead of as sales
.
select A subselect (called
select
in the synopsis above) can appear in the
FROM
clause. This makes it appear as if the subselect output were created as a temporary table for the duration of this single
SELECT
command. Note that the subselect must be surrounded by parentheses, and an alias must be provided for it. join_type One of:
•
•
•
LEFT [ OUTER ] JOIN
RIGHT [ OUTER ] JOIN
FULL [ OUTER ] JOIN
December 14, 2011 SQL Commands V--77
SELECT Aster Data proprietary and confidential
For the
OUTER
join types, a join condition must be specified, that is, exactly one of
NATURAL,
ON join_condition
. See below for the meaning.
A
JOIN
clause combines two
FROM
items. Use parentheses if necessary to determine the order of nesting. In the absence of parentheses,
JOIN s nest left-to-right. In any case
JOIN
binds more tightly than the commas separating
FROM
items.
•
•
•
LEFT OUTER JOIN
returns all rows in the qualified Cartesian product (i.e., all combined rows that pass its join condition), plus one copy of each row in the left-hand table for which there was no right-hand row that passed the join condition. This left-hand row is extended to the full width of the joined table by inserting null values for the right-hand columns. Note that only the
JOIN
clause's own condition is considered while deciding which rows have matches. Outer conditions are applied afterwards.
Conversely,
RIGHT OUTER JOIN
returns all the joined rows, plus one row for each unmatched right-hand row (extended with nulls on the left). This is just a notational convenience, since you could convert it to a
LEFT OUTER JOIN
by switching the left and right inputs.
FULL OUTER JOIN
returns all the joined rows, plus one row for each unmatched left-hand row (extended with nulls on the right), plus one row for each unmatched right-hand row (extended with nulls on the left).
ON join_condition The join_condition
is an expression resulting in a value of type
Boolean (similar to a
WHERE clause) that specifies which rows in a join qualify as matches.
USING ( join_column [, ...] ) A clause of the form USING ( a, b, ... ) is shorthand for ON left_table.a = right_table.a AND left_table.b = right_table.b .... Also, USING implies that only one of each pair of equivalent columns will be included in the join output, not both.
NATURAL The keyword
NATURAL
is shorthand to join all like-named columns in the two tables. NATURAL and USING (in the context described just above) are mutually exclusive; choose only one of the two.
sqlmr_function_name The name of a function written using Aster Database’s
SQL-MapReduce API. The ON keyword introduces the table or query whose contents the
SQL-MapReduce function operates on. Arguments to the function are passed in the form clause_name ( literal [, ...] )
where
clause_name
is the name of an input parameter defined in the function and
literal
is the value to be assigned to that parameter. You can pass multiple parameters separated by whitespace (not commas). For details, see
“SQL-MapReduce Query Syntax” on page I-58 .
WHERE Clause in SELECT
The optional WHERE clause has the general form
WHERE condition The
WHERE condition is any expression that evaluates to a result of type
Boolean. Any row that does not satisfy this condition will be eliminated from the output. A row satisfies the condition if it returns true when the actual row values are substituted for any variable references.
GROUP BY Clause in SELECT
The optional
GROUP BY
clause has the general form
GROUP BY expression [, ...]
V--78 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential SELECT
GROUP BY
will condense into a single row all selected rows that share the same values for the grouped expressions. expression can be an input column name, or the name or ordinal number of an output column (
SELECT
list item), or an arbitrary expression formed from input-column values. In case of ambiguity, a
GROUP BY
name will be interpreted as an input-column name rather than an output column name.
Aggregate functions, if any are used, are computed across all rows making up each group, producing a separate value for each group (whereas without
GROUP BY
, an aggregate produces a single value computed across all the selected rows). When
GROUP BY
is present, it is not valid for the
SELECT
list expressions to refer to ungrouped columns except within aggregate functions, since there would be more than one possible value to return for an ungrouped column.
HAVING Clause in SELECT
The optional HAVING clause has the general form
HAVING condition where condition is the same as specified for the WHERE clause.
HAVING eliminates group rows that do not satisfy the condition. HAVING is different from
WHERE : WHERE filters individual rows before the application of GROUP BY , while HAVING filters group rows created by GROUP BY . Each column referenced in condition must unambiguously reference a grouping column, unless the reference appears within an aggregate function.
The presence of HAVING turns a query into a grouped query even if there is no GROUP BY clause. This is the same as what happens when the query contains aggregate functions but no
GROUP BY clause. All the selected rows are considered to form a single group, and the SELECT list and HAVING clause can only reference table columns from within aggregate functions. Such a query will emit a single row if the HAVING condition is true, zero rows if it is not true.
UNION Clause in SELECT
The UNION clause has this general form: select_statement UNION [ ALL ] select_statement select_statement
is any
SELECT
statement without an
ORDER BY
or
LIMIT
clause.
(ORDER BY and LIMIT can be attached to a sub expression if it is enclosed in parentheses.
Without parentheses, these clauses will be taken to apply to the result of the
UNION
, not to its right-hand input expression.)
The
UNION operator computes the set union of the rows returned by the involved
SELECT statements. A row is in the set union of two result sets if it appears in at least one of the result sets. The two
SELECT
statements that represent the direct operands of the
UNION
must produce the same number of columns, and corresponding columns must be of compatible datatypes.
The result of
UNION does not contain any duplicate rows unless the
ALL
option is specified.
ALL
prevents elimination of duplicates. (Therefore,
UNION ALL
is usually significantly quicker than
UNION
; use
ALL
when you can.)
Multiple
UNION
operators in the same
SELECT
statement are evaluated left to right, unless another order is specified using parentheses.
INTERSECT Clause in SELECT
The
INTERSECT
clause has this general form:
December 14, 2011 SQL Commands V--79
SELECT Aster Data proprietary and confidential select_statement INTERSECT [ ALL ] select_statement select_statement
is any
SELECT
statement without an
ORDER BY
or
LIMIT
clause.
The
INTERSECT
operator computes the set intersection of the rows returned by the involved
SELECT
statements. A row is in the intersection of two result sets if it appears in both result sets.
The result of
INTERSECT does not contain any duplicate rows unless the
ALL
option is specified. With
ALL
, a row that has m duplicates in the left table and n duplicates in the right table will appear min(m,n) times in the result set.
Multiple
INTERSECT
operators in the same
SELECT
statement are evaluated left to right, unless parentheses dictate otherwise.
INTERSECT
binds more tightly than UNION. That is,
A
UNION B INTERSECT C
will be read as
A UNION (B INTERSECT C)
.
EXCEPT Clause in SELECT
The EXCEPT clause has this general form: select_statement EXCEPT [ ALL ] select_statement select_statement is any SELECT statement without an ORDER BY or LIMIT clause.
The EXCEPT operator computes the set of rows that are in the result of the left SELECT statement but not in the result of the right one.
The result of EXCEPT does not contain any duplicate rows unless the ALL option is specified.
With ALL , a row that has m duplicates in the left table and n duplicates in the right table will appear max(m-n,0) times in the result set.
Multiple EXCEPT operators in the same SELECT statement are evaluated left to right, unless parentheses dictate otherwise. EXCEPT binds at the same level as UNION .
ORDER BY Clause in SELECT
The optional
ORDER BY
clause has this general form:
ORDER BY expression [ ASC | DESC ] [NULLS { FIRST | LAST }] [, ...] expression can be the name or ordinal number of an output column (
SELECT
list item), or it can be an arbitrary expression formed from input-column values.
The
ORDER BY
clause causes the result rows to be sorted according to the specified expressions.
If two rows are equal according to the leftmost expression, the are compared according to the next expression and so on. If they are equal according to all specified expressions, they are returned in an implementation-dependent order.
The ordinal number refers to the ordinal (left-to-right) position of the result column. This feature makes it possible to define an ordering on the basis of a column that does not have a unique name. This is never absolutely necessary because it is always possible to assign a name to a result column using the AS clause.
It is also possible to use arbitrary expressions in the
ORDER BY
clause, including columns that do not appear in the
SELECT
result list. Thus the following statement is valid:
SELECT name FROM distributors ORDER BY code;
If an
ORDER BY
expression is a simple name that matches both a result column name and an input column name,
ORDER BY
will interpret it as the result column name. This is the opposite
V--80 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential SELECT of the choice that
GROUP BY
will make in the same situation. This inconsistency is made to be compatible with the SQL standard.
Optionally one may add the keyword
ASC
(ascending) or
DESC
(descending) after any expression in the
ORDER BY
clause. If not specified,
ASC
is assumed by default.
If
NULLS LAST
is specified, null values sort after all non-null values; if
NULLS FIRST
is specified, null values sort before all non-null values. If neither is specified, the default behavior is
NULLS LAST
when
ASC
is specified or implied, and
NULLS FIRST
when
DESC
is specified
(thus, the default is to act as though nulls are larger than non-nulls).
Character-string data is sorted according to the locale-specific collation order that was established when the database cluster was initialized.
DISTINCT Clause in SELECT
If DISTINCT is specified, all duplicate rows are removed from the result set (one row is kept from each group of duplicates). ALL specifies the opposite: all rows are kept; that is the default.
DISTINCT ON ( expression [, ...] ) keeps only the first row of each set of rows where the given expressions evaluate to equal. The DISTINCT ON expressions are interpreted using the same rules as for ORDER BY (see above). Note that the "first row" of each set is unpredictable unless ORDER BY is used to ensure that the desired row appears first. For example:
SELECT DISTINCT ON (location) location, time, report
FROM weather_reports
ORDER BY location, time DESC;
This query retrieves the most recent weather report for each location. But if we had not used
ORDER BY to force descending order of time values for each location, we'd have gotten a report from an unpredictable time for each location.
The DISTINCT ON expression(s) must match the leftmost ORDER BY expression(s). The
ORDER BY clause will normally contain additional expression(s) that determine the desired precedence of rows within each DISTINCT ON group.
Note that aggregate functions may not be used in DISTINCT ON expressions.
LIMIT Clause in SELECT
The LIMIT clause consists of two independent sub-clauses:
LIMIT { count | ALL }
OFFSET start count
specifies the maximum number of rows to return, while start specifies the number of rows to skip before starting to return rows. When both are specified, start rows are skipped before starting to count the count rows to be returned.
When using
LIMIT
, it is a good idea to use an
ORDER BY
clause that constrains the result rows into a unique order. Otherwise you will get an unpredictable subset of the query's rows — you may be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You don't know what ordering unless you specify
ORDER BY
.
The query planner takes
LIMIT
into account when generating a query plan, so you are very likely to get different plans (yielding different row orders) depending on what you use for
LIMIT
and
OFFSET
. Thus, using different
LIMIT/OFFSET
values to select different subsets of a query result will give inconsistent results unless you enforce a predictable result ordering with
ORDER BY
. This is not a bug; it is an inherent consequence of the fact that SQL does not
December 14, 2011 SQL Commands V--81
SELECT Aster Data proprietary and confidential promise to deliver the results of a query in any particular order unless
ORDER BY
is used to constrain the order.
Tip!
If you’re using ACT to query Aster Database, you can use ACT’s FETCH_LIMIT parameter to limit the number of rows returned by a query. Using FETCH_LIMIT typically results in faster query runtimes than using a LIMIT clause. See “Using fetch-limit to set the maximum number of rows returned per query” on page I-45 .
Examples of SELECT Statements
To sum the column did
of all films and group the results by kind:
SELECT kind, sum(did) AS total FROM films GROUP BY kind;
The following two examples are identical ways of sorting the individual results according to the contents of the second column (name):
SELECT * FROM distributors ORDER BY name;
SELECT * FROM distributors ORDER BY 2;
Compatibility of SELECT
The Aster Database implementation of the
SELECT
statement is compatible with the SQL standard, but there are some extensions and some missing features.
Omitted FROM Clauses
Aster Database allows one to omit the FROM clause. It has a straightforward use to compute the results of simple expressions:
SELECT 2+2;
column
----------
4
(1 row)
Some other SQL databases cannot do this except by introducing a dummy one-row table from which to do the SELECT .
Note that if a FROM clause is not specified, the query cannot reference any database tables. For example, the following query is invalid:
SELECT * WHERE name = 'Westward';
No Support for VALUES Clause
Aster Database does not support a VALUES clause in the FROM clause of a SELECT statement.
Namespace Available to GROUP BY and ORDER BY
In the SQL-92 standard, an
ORDER BY
clause may only use result column names or numbers, while a
GROUP BY
clause may only use expressions based on input column names. Aster
V--82 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential SET
Database extends each of these clauses to allow the other choice as well (but it uses the standard's interpretation if there is ambiguity). Aster Database also allows both clauses to specify arbitrary expressions. Note that names appearing in an expression will always be taken as input-column names, not as result-column names.
SQL:1999 and later use a slightly different definition which is not entirely upward compatible with SQL-92. In most cases, however, Aster Database will interpret an
ORDER BY
or
GROUP
BY
expression the same way SQL:1999 does.
Nonstandard Clauses
The clauses LIMIT and OFFSET are not defined in the SQL standard.
SET
SET -- Set the value of a runtime configuration parameter
Synopsis
SET [ LOCAL | TRANSACTION | SESSION ] name { TO | = } value;
Description
The SET command changes the value of the runtime configuration parameter, name.
Scope of a Parameter Setting
By default, the parameter setting applies only within the current transaction. The value of the configuration parameter gets reverted to its pre-transaction setting when the transaction finishes
(COMMIT or ABORT).
By including the keyword LOCAL, TRANSACTION, or SESSION, you can set the scope of your setting. The keyword LOCAL or TRANSACTION applies the setting only to the current transaction. The keyword SESSION applies the setting to the current client session.
If you make a SESSION-scoped parameter setting inside a transaction block, it will become visible outside the transaction only if the transaction commits. If the transaction aborts, the setting rolls back to its pre-transaction value.
Runtime Parameters
You can pass the following runtime parameter names as the name clause of a SET statement. For each, we list the set or range or allowed values. When assigning a value, enclose the value in single quotes, unless otherwise specified.
Table 1-4 Runtime Parameters in Aster Database
Parameter Description client_encoding cpu_index_tuple_cost
Set the client-side encoding (character set). The default is to use the database encoding. The supported values for client encoding are SQL_ASCII and UTF8.
Sets the Local Planner's estimate of the cost of processing each index entry during an index scan. Accepts a floating point value enclosed in single quotes as input.
Default value is 0.005.
December 14, 2011 SQL Commands V--83
SET Aster Data proprietary and confidential
Parameter Description cpu_tuple_cost effective_cache_size enable_bitmapscan enable_hashagg enable_hashjoin enable_indexscan enable_mergejoin
Sets the Local Planner's estimate of the cost of processing each row during a query.
Default value is 0.01
Sets the Local Planner's assumption about the effective size of the disk cache that is available to a single query. This is factored into estimates of the costs of specific plans, i.e. whether to use an index or not. A higher value makes it more likely to use an index scan, whereas a lower value makes it more likely that sequential scans will be used. The default value is 128MB
Enable or disable the Local Planner's use of bitmap-scan plan types. Default value is 'on'
Enable or disable the Local Planner's use of hashed aggregation plan types. Default value is 'on'
Enable or disable Local Planner's use of hash-join plan types. Default value is 'on'
Enable or disable Local Planner's use of index-scan plan types. Default value is 'on'
Enable or disable Local Planner's use of merge-join plan types. Default value is 'on' enable_nestloop enable_seqscan maintenance_work_mem random_page_cost search_path
Specifies the maximum amount of memory to be used in maintenance operations, such as VACUUM, CREATE INDEX, and ALTER TABLE. The default value is
64MB
Set the Local Planner' estimate of the cost of a disk page that was fetched non-sequentially from disk. The default value is 4. Reducing this value relative to
'seq_page_cost' will cause the local planner to prefer index scans over sequential scans. Increasing this value will lead to sequential scans being preferred over index scans
Specify the order in which schemas are searched when an object (table, view, etc.) is referenced by a simple name with no schema component. The first match wins.
The value for search_path is a comma-separated list of existing schema names. The value should not be enclosed in single quotes if you are specifying multiple schemas. See “Schema Search Path” on page II-108 for details. The syntax for this is:
SET [session | transaction] search_path { TO | = } { value }
Pass the session
qualifier to limit the use of this search path to the current session. Pass the transaction
qualifier to limit the use of this search path to the current transaction. If you don’t pass a qualifier, the search_path applies to the
current transaction. To change your default search path, see ALTER USER
.
seq_page_cost statement_timeout
Enable or disable Local Planner's use of nested-loop plan types. Default value is
'off'
Enable or disable Local Planner's use of sequential-scan plan types. Default value is 'on'
Set the Local Planner's estimate of the cost of a disk page fetch that is part of a series of sequential fetches. The default value is 1
Set the maximum length of time a query invocation can run on each virtual worker.
The timeout is expressed in milliseconds. If a query is running for longer than this time, it is aborted. The default value is “0”, which Aster Database interprets as meaning no timeout should be enforced.
V--84 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Parameter work_mem
Description
SHOW
Specifies the amount of memory to be used by internal sort operations and hash tables before switching to temporary on-disk files. The default value, per virtual worker is 64MB. Note that for a complex query, several sort or hash operations might be running in parallel; each one will be allowed to use as much memory as this value specifies before it starts to put data into temporary files. Also, several running sessions could be doing such operations concurrently. Lastly, there are multiple virtual workers per worker node. So the total memory used could be many times the value of work_mem; it is necessary to keep this fact in mind when choosing the value. Sort operations are used for ORDER BY, DISTINCT, and merge joins
Examples Using SET
To enable Local Planner’s use of nested-loop plan types:
SET enable_nestloop to 'on' ;
To change the SQL statement timeout for this transaction:
SET TRANSACTION statement_timeout = '4000';
To set your session schema search path to include the schemas capmkts, fixedinc, and public:
SET session search_path TO capmkts,fixedinc,public;
Compatibility
The scope (transaction or session) of a setting made with
SET
differs among various database systems. Read the preceding sections for information about scope.
See Also
SHOW
SHOW -- Display value of a run-time configuration parameter
Synopsis
SHOW name;
Description
The SHOW command will display the value of a run-time configuration parameter. These values are applicable for Local Planners for virtual workers in Aster Database. The values of these variables can be changed using the SET statement.
December 14, 2011 SQL Commands V--85
SHOW Aster Data proprietary and confidential
Parameters for SHOW
Parameter client_encoding cpu_index_tuple_ cost cpu_tuple_cost effective_cache_ size enable_ bitmapscan enable_hashagg enable_hashjoin enable_indexscan enable_mergejoin enable_nestloop enable_seqscan maintenance_ work_mem random_page_cost search_path seq_page_cost statement_ timeout work_mem
Description
Show the current client-side encoding (character set). The default encoding is the database encoding.
Show the Local Planner's estimate of the cost of processing each index entry during an index scan.
Set the Local Planner's estimate of the cost of processing each row during the execution of a query
Show the Local Planner's assumption of the effective size of the disk cache available to a single query. This is the value used for each virtual worker in Aster Database.
Flag that dictates whether bitmap-scan plan type is enabled for the Local Planner or not.
Flag that dictates whether hashed aggregation plan type is enabled for the Local
Planner or not.
Flag that dictates whether hash join plan type is enabled for the Local Planner or not.
Flag that dictates whether index-scan plan type is enabled for the Local Planner or not.
Flag that dictates whether merge-join plan type is enabled for the Local Planner or not.
Flag that dictates whether nested-loop plan type is enabled for the Local Planner or not.
Flag that dictates whether sequential-scan plan type is enabled for the Local Planner or not.
Show the maximum amount of memory to be used, per virtual worker, for maintenance operations like VACUUM, CREATE INDEX, and ALTER TABLE.
Show the Local Planner's current estimate of the cost of a non-sequentially-fetched page from disk.
Show the schema search path that specifies the order in which schemas are searched when an object (table, view, etc.) is referenced by a simple name with no schema component. The first match wins. See “Schema Search Path” on page II-108 for details.
Show the Local Planner's current estimate of the cost of fetching a disk page as part of a series of sequential scans.
Show the current value of the upper bound on allowed query execution time. Any query that takes longer, will be automatically aborted.
Show the maximum amount of memory to be used, per virtual worker, for internal sort operations and hash tables before switching to temporary disk files.
Example of SHOW
To see the maximum amount of memory used, per virtual worker, for internal sort operations :
SHOW work_mem;
Compatibility
SHOW
is an Aster Database extension.
V--86 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
See Also
START TRANSACTION
START TRANSACTION
START TRANSACTION -- start a transaction block
Synopsis
START TRANSACTION;
Description
This command begins a new transaction block. If the isolation level or read/write mode is specified, the new transaction has those characteristics. This is the same as the
BEGIN
command.
Parameters
TRANSACTION Optional keyword. Has no effect.
Notes
START TRANSACTION has the same functionality as
Use
COMMIT
or
ROLLBACK
to terminate a transaction block.
Issuing
START TRANSACTION
when already inside a transaction block will provoke a warning message. The state of the transaction is not affected.
Example
To begin a transaction block:
START TRANSACTION;
Compatibility
In the standard, it is not necessary to issue
START TRANSACTION
to start a transaction block: any SQL command implicitly begins a block. Aster Database's behavior can be seen as implicitly issuing a
COMMIT
after each command that does not follow
START TRANSACTION
(or
BEGIN
), and it is therefore often called "autocommit".
See Also
To initiate a transaction:
•
To finish a transaction:
•
•
December 14, 2011 SQL Commands V--87
TRUNCATE Aster Data proprietary and confidential
To cancel a transaction:
•
•
TRUNCATE
TRUNCATE -- empty a table or set of tables
The TRUNCATE command empties a table or set of tables. TRUNCATE is a faster alternative to performing an unqualified DELETE on a table. DELETE operates more slowly because it does a full scan of each table before deleting the rows. TRUNCATE deletes the rows without performing a scan.
If your table has child tables created through inheritance, don’t forget to include the
CASCADE option. If the table is a logically partitioned table,
TRUNCATE
automatically acts on the whole hierarchy.
More:
|
|
Synopsis
TRUNCATE [ TABLE ] name [, ...] [ CASCADE | RESTRICT ]
Description
TRUNCATE quickly removes all rows from a set of tables. It reclaims disk space immediately, rather than requiring a subsequent VACUUM operation. This is most useful on large tables.
Parameters name The name (optionally schema-qualified) of a table to be truncated.
CASCADE Automatically truncates all child tables of the named table(s).
RESTRICT Truncate only the named tables. Do not truncate any child tables unless they are named in the statement.
Notes
Only the owner of a table can TRUNCATE it.
Examples
Truncate the tables mintemp and maxtemp:
TRUNCATE mintemp, maxtemp;
Compatibility
There is no TRUNCATE statement in the SQL standard. Aster Database’s TRUNCATE differs from that of PostgreSQL in that, in Aster Database, the CASCADE and RESTRICT keywords
V--88 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential UPDATE extend or limit the command’s applicability to child tables, rather than to tables related via a foreign key. (Aster Database does not have the notion of foreign key references.)
See Also
, and “Handling Dead Space in Aster
Database” on page II-22 .
UPDATE
UPDATE -- update rows of a table
Synopsis
UPDATE [ ONLY ] table
SET column = expression [, ...]
[ FROM fromlist ]
[ WHERE condition | WHERE CURRENT OF cursor_name ];
Description
UPDATE
changes the values of the specified columns in all rows that satisfy the condition. Only the columns to be modified need be mentioned in the
SET
clause; columns not explicitly modified retain their previous values.
By default,
UPDATE
will update rows in the specified table and all its child tables. If you wish to only update the specific table mentioned, you must use the
ONLY
clause.
The
FROM
clause can be used to modify a table using information contained in other tables in the database.
December 14, 2011 SQL Commands V--89
UPDATE Aster Data proprietary and confidential
table
column expression fromlist condition cursor_name
Parameters
The name of the table to update.
The name of a column in table.
An expression to assign to the column. The expression may use the old values of this and other columns in the table.
A list of table expressions, allowing columns from other tables to appear in the
WHERE condition and the update expressions. This is similar to the list of tables that can be specified in the FROM clause of a SELECT statement.
Note that the target table must not appear in the fromlist unless you intend a self-join (in which case it must appear with an alias in the fromlist).
An expression that returns a value of type Boolean. Only rows for which this expression returns true will be updated.
The name of the cursor to use in a
WHERE CURRENT OF
condition. The row to be updated is the one most recently fetched from this cursor. The cursor must be a non-grouping query on the
UPDATE
’s target table. Note that
WHERE
CURRENT OF
cannot be specified together with a Boolean condition. See
DECLARE for more information about using cursors with
WHERE CURRENT
OF
.
Outputs
On successful completion, an
UPDATE
command returns a command tag of the form
UPDATE count
The count is the number of rows updated. If count is 0, no rows matched the condition (this is not considered an error).
Notes
You cannot UPDATE a value in a distribution key column.
When a FROM clause is present, the target table effectively is joined to the tables mentioned in the fromlist , and each output row of the join represents an update operation for the target table . When using FROM you should ensure that the join produces at most one output row for each row to be modified. In other words, a target row shouldn't join to more than one row from the other table(s). If it does, then only one of the join rows will be used to update the target row, but which one will be used is not readily predictable.
Examples
Change the word Drama to Dramatic in the column kind of the table films:
UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama';
Adjust temperature entries and set precipitation to 0 in one row of the table weather:
UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = '0'
WHERE city = 'San Francisco' AND date = '2003-07-03';
Increment the sales count of the salesperson who manages the account for Acme Corporation, using the
FROM
clause syntax:
UPDATE employees SET sales_count = sales_count + 1 FROM accounts
WHERE accounts.name = 'Acme Corporation'
V--90 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
AND employees.id = accounts.sales_person;
UPDATE
Compatibility
This command conforms to the SQL standard, except that the FROM clause is an Aster Database extension.
Some other database systems offer a FROM option in which the target table is supposed to be listed again within FROM . That is not how Aster Database interprets FROM . Be careful when porting applications that use this extension.
December 14, 2011 SQL Commands V--91
VACUUM Aster Data proprietary and confidential
VACUUM
VACUUM -- garbage-collect and optionally analyze a table (or, if cluster is so configured, a database)
Synopsis
The default Aster Database behavior requires that you pass a tablename argument:
VACUUM [ FULL ] tablename [ CASCADE ]
When you run ANALYZE during a vacuum, you can also pass one or more columnname arguments, if you wish to update statistics for only that column or columns:
VACUUM [ FULL ] ANALYZE [ tablename [ ( columnname [, ...] ) ] ] [ CASCADE ]
Optional Aster Database behavior allows you to omit the tablename to VACUUM the whole database. This behavior is not allowed in a default Aster Database installation; contact Aster
Data support if you wish to enable it. See “Optional: Running VACUUM on a database” on page V-94
. With this feature enabled, the following synopsis applies in addition to the two above:
VACUUM [ FULL ] [ ANALYZE ]
Description
VACUUM
reclaims storage occupied by deleted rows. In normal Aster Database operation, rows that are deleted or made obsolete by an update are not physically removed from their table; they remain present until a
VACUUM
is done. Therefore it is necessary to do
VACUUM
periodically, especially on frequently-updated tables.
If your table has child tables created through inheritance, don’t forget to include the
CASCADE option. If the table is a logically partitioned table,
VACUUM
automatically acts on the whole hierarchy.
VACUUM ANALYZE
performs a
VACUUM
and then an
ANALYZE
on the specified table. This
updates the table’s statistics for proper query planning. See ANALYZE for details.
The differences between
VACUUM
and
VACUUM FULL
:
•
•
VACUUM
simply reclaims space and makes it available for re-use. This form of the command
does not take an exclusive lock on the table, so queries on the table can continue while
VACUUM
is ongoing (although you should expect them to run more slowly). Note that the reclaimed space is not returned to the system/user. Rather, obsolete rows are marked as reusable, and the space will be reclaimed by a future
INSERT
.
VACUUM FULL
takes an exclusive lock on the table so that it can move rows across blocks to compact the table to the minimum number of disk blocks. Running
VACUUM FULL
takes much longer than running
VACUUM
. While a table is being processed by
VACUUM FULL
, any new queries on that table will wait for the vacuum processing to finish. In contrast to plain
VACUUM
, space reclaimed by
VACUUM FULL
is released to the file system.
V--92 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential VACUUM
FULL
ANALYZE
tablename
columnname
CASCADE
Parameters
Selects "full" vacuum, which may reclaim more space, but takes much longer and exclusively locks the table.
Updates statistics used by the planner to determine the most efficient way to execute a query.
The name of a specific table to vacuum.
The name of a column to ANALYZE. If omitted, all columns are ANALYZEd.
Also vacuums all children of the named table.
Outputs
No output.
Notes
Usage Recommendations Observe these recommendations when deciding whether to
VACUUM
a table:
•
•
•
•
VACUUM generates a large amount of I/O traffic, which can slow other queries.
After adding or deleting a large number of rows, it’s a good idea to issue a VACUUM
ANALYZE command for the affected table. This updates the system catalogs so that query planner can plan more efficient queries.
When possible, use VACUUM rather than VACUUM FULL .
Do not run VACUUM while bulk loading is ongoing.
•
•
Do not run VACUUM FULL (especially on an entire database) on a production database on which users are actively running queries, because
VACUUM FULL
is a very expensive operation.
If you do need to run VACUUM on an active production database, then we recommend you run it at a per-table level. If a particular table has a large number of dead rows, then you can get faster results by using
CREATE TABLE AS SELECT
to replace the table, rather than vacuuming the table. That is, instead of running this:
VACUUM bloated_table;
...run this:
BEGIN;
CREATE TABLE new_table AS SELECT * FROM bloated_table;
DROP bloated_table;
ALTER TABLE RENAME new_table TO bloated_table;
END;
Checking whether a VACUUM is needed To find out whether a table would benefit from a
VACUUM
operation, you can check its dead row percentages (as well as its uncompressed table size) using the ncluster_storagestat
function. Run ACT as an administrator and check it like this:
SELECT * FROM ncluster_storagestat('sometablename');
This reveals the number of dead rows, live rows, size of dead rows, size of live rows, etc., so you can decide whether to run
VACUUM FULL
.
December 14, 2011 SQL Commands V--93
WITH Aster Data proprietary and confidential
Cancelling a VACUUM As administrator, you can cancel an issued
VACUUM
or
VACUUM
FULL
operation using the AMC interface. Use the Cancel Statement button in the Activity tab of the AMC.
Optional: Running VACUUM on a database The comands
VACUUM tablename
and
VACUUM FULL tablename
are standard Aster Database commands that run on a single table, but
VACUUM
(without a table name) and
VACUUM FULL
(without a table name) are optional Aster
Database commands that VACUUM the entire database. Warning: Running VACUUM FULL on a database, locks one table at a time while the VACUUM runs on that table, and may take a long time to run.
The ability to run VACUUM on the entire database is disabled by default in Aster Database. If you wish to run VACUUM on a database, please contact Aster Data support to have this feature enabled.
Compatibility
There is no VACUUM statement in the SQL standard.
See Also
“Handling Dead Space in Aster Database” on page II-22 .
WITH
WITH -- convenience syntax that lets you declare and name a sub-SELECT query
Synopsis
WITH queryname AS (query), queryname2 AS (query2)
SELECT ... FROM queryname, queryname2 WHERE ...;
Description
The WITH clause lets you create aliases for subqueries and is especially useful when a particular subquery appears multiple times in a single SELECT. The current implementation of the WITH clause has these limitations:
•
•
Per the SQL standard, the WITH clause subquery should be evaluated only once. Currently,
Aster Database does not materialize the WITH clause subquery’s results. As a result, the subquery might be evaluated multiple times.
You cannot rename columns in the subquery.
V--94 Database SQL and Function Reference, version 4.6.2
aster data
V--2
Functions and Operators
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
This section contains reference information for the functions and operators supported by Aster
Database.
“Logical Operators” on page V-95
“Comparison Operators” on page V-96
“Mathematical Operators and Functions” on page V-97
“Trigonometric Functions” on page V-99
“String Functions and Operators” on page V-100
“Bit String Functions and Operators” on page V-103
“SQL/MapReduce Functions” on page V-103
“Pattern Matching Functions and Operators” on page V-108
“Datatype Formatting Functions and Operators” on page V-121
“Date/Time Functions and Operators” on page V-123
“Aggregate Functions” on page V-130
“Aggregate Functions for Statistics” on page V-130
“Conditional SQL Expressions” on page V-131
“Subquery SQL Expressions” on page V-133
Logical Operators
Operator
NOT
AND or
Return Type
Boolean
Boolean
Boolean
Description
Tri-valued Boolean NOT
Tri-valued Boolean AND
Tri-valued Boolean OR
December 14, 2011 Aster Data proprietary and confidential V--95
Comparison Operators Aster Data proprietary and confidential
Comparison Operators
Aster Database supports the following comparison operators:
Operator
<
>
<=
>=
=
!=
<>
BETWEEN
NOT BETWEEN
BETWEEN SYMMETRIC
IS
IS NOT
DISTINCT FROM
Return Type Description
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Binary less than
Binary greater than
Binary less than or equal to
Binary greater than or equal to
Binary equality
Binary inequality
Binary inequality, the same as !=
Three operand input (a,b,c), evaluates b<=a<=c
Three operand input (a,b,c), the negation of BETWEEN
Same as between, except it evaluates c<=a<=b, if c<b
Equality check that works with NULL
Inequality check that works with NULL
Equality with NULL extension behavior
Comparison operators are available for all datatypes where this makes sense. All comparison operators are binary operators that return values of type Boolean; expressions like
1 < 2 < 3 are not valid (because there is no
<
operator to compare a Boolean value with
3
).
In addition to the comparison operators, the special
BETWEEN
construct is available. a BETWEEN x AND y is equivalent to: a >= x AND a <= y
Similarly, a NOT BETWEEN x AND y a < x OR a > y is equivalent to:
There is no difference between the two respective forms.
BETWEEN SYMMETRIC
is the same as
BETWEEN
except there is no requirement that the argument to the left of
AND
be less than or equal to the argument on the right; the proper range is automatically determined.
To check whether a value is or is not null, use the constructs: expression IS NULL expression IS NOT NULL
Do not use the equals sign to write “
expression = NULL
” because the keyword “
NULL
” is not equal to a
NULL
value. (The null value represents an unknown value, and thus we don’t know whether two unknown values are equal.) This behavior conforms to the SQL standard.
V--96 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Mathematical Operators and Functions
Note: If the expression is row-valued, then
IS NULL
is true
when the row expression itself is null or when all the row's fields are null, while
IS NOT NULL
is true
when the row expression itself is non-null and all the row's fields are non-null. This definition conforms to the
SQL standard.
The ordinary comparison operators yield null (signifying "unknown") when either input is null.
Another way to do comparisons is with the
IS DISTINCT FROM
construct: expression IS DISTINCT FROM expression
For non-null inputs,
IS DISTINCT FROM
is the same as the
<>
operator. However, when both inputs are null it will return false
, and when just one input is null it will return true
.
Boolean values can also be tested using the constructs: expression IS TRUE expression IS NOT TRUE expression IS FALSE expression IS NOT FALSE expression IS UNKNOWN expression IS NOT UNKNOWN
These will always return true
or false
, never a null value, even when the operand is null. A null input is treated as the logical value "unknown". Notice that
IS UNKNOWN
and
IS NOT
UNKNOWN
are effectively the same as
IS NULL
and
IS NOT NULL
, respectively, except that the input expression must be of Boolean type.
Mathematical Operators and Functions
Mathematical operators are provided for many Aster Database types. For types without common mathematical conventions for all possible permutations (e.g., date/time types) we describe the actual behavior in subsequent sections.
The following mathematical operators are supported in Aster Database:
Table 2-1 Mathematical operators supported by Aster Database.
Operat or
Description Example Result Notes
+ addition 2 + 3 5
-
*
/
% subtraction multiplication division (integer division truncates results) modulo (remainder)
2 - 3
2 * 3
4 / 2
5 % 4
-1
6
2
1
Usable on any numeric datatype
Usable on any numeric datatype
Usable on any numeric datatype
Usable on any numeric datatype
^
|/ exponentiation square root
2.0 ^ 3.0
8
|/ 25.0
5
Usable on any numeric datatype
Usable on any numeric datatype
Usable on any numeric datatype
December 14, 2011 Functions and Operators V--97
Mathematical Operators and Functions Aster Data proprietary and confidential
||/
!
!!
@
&
|
#
~
<<
>> cube root factorial factorial (prefix operator) absolute value bitwise AND bitwise OR bitwise XOR bitwise NOT bitwise shift left bitwise shift right
||/ 27.0
3
5 !
!! 5
@ -5.0
91 & 15
32 | 3
17 # 5
~1
1 << 4
8 >> 2
120
120
5
11
35
20
-2
16
2
Usable on any numeric datatype
Usable on any numeric datatype
Usable on any numeric datatype
Usable on any numeric datatype
Usable only on integral datatypes
Usable only on integral datatypes
Usable only on integral datatypes
Usable only on integral datatypes
Usable only on integral datatypes
Usable only on integral datatypes
The bitwise operators work only on integral datatypes, whereas the others are available for all numeric datatypes. The bitwise operators are also available for the bit string types bit
and bit varying
.
The following table shows the mathematical functions supported by Aster Database. In the table, dp
indicates double precision
. Many of these functions are provided in multiple forms with different argument types. Except where noted, any given form of a function returns the same datatype as its argument.
Table 2-2 Mathematical functions supported by Aster Database
Function Return Type Description Example abs(x) cbrt(dp) ceil(dp or numeric) ceiling(dp or numeric) degrees(dp)
(same type as
x) dp (double precision) absolute value cube root abs(-17.4) cbrt(27.0)
(same as input) smallest integer not less than argument
(same as input) smallest integer not less than argument (alias for ceil dp ceil(-42.8) ceiling(-95.3) radians to degrees degrees(0.5) exp(dp or numeric) floor(dp or numeric)
(same as input) exponential exp(1.0)
Result
17.4
3
-42
-95
28.64788975
65412
2.718281828
45905
-43 (same as input) largest integer not greater than argument floor(-42.8)
V--98 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Trigonometric Functions ln(dp or numeric) log(dp or numeric) log(b numeric, x numeric) mod(y, x)
(same as input) natural logarithm ln(2.0)
(same as input) base 10 logarithm log(100.0) numeric logarithm to base b log(2.0, 64.0) remainder of y/x mod(9,4)
(same as argument types) dp "\u03c0" constant pi()
0.693147180
559945
2
6.000000000
0
1 pi() power(a dp, b dp) power(a numeric, b numeric) radians(dp) dp numeric a raised to the power of b power(9.0, 3.0) a raised to the power of b power(9.0, 3.0) degrees to radians radians(45.0) dp trunc(42.8)
0.785398163
397448
42 round(dp or numeric) round(v numeric, s int) sign(dp or numeric) sqrt(dp or numeric)
(same as input) round to nearest integer numeric round to s decimal places
(same as input) sign of the argument (-1, 0,
+1)
(same as input) square root round(42.4) round(42.4382, 2)
42.44 sign(-8.4) sqrt(2.0)
-1
1.414213562
3731
42 trunc(dp or numeric) trunc(v numeric, s int)
(same as input) truncate toward zero numeric truncate to s decimal places trunc(42.4382, 2)
3.141592653
58979
729
729
42.43
Trigonometric Functions
Aster Database supports the following trigonometric functions. In the table, dp
indicates double precision
.
Table 2-3 Trigonometric functions supported by Aster Database.
Function Return Type Description acos(x) inverse cosine asin(x) atan(x) atan2(x, y) cos(x) cot(x) dp dp dp dp (double precision) dp dp inverse sine inverse tangent inverse tangent of x/y cosine cotangent
December 14, 2011 Functions and Operators V--99
String Functions and Operators Aster Data proprietary and confidential sin(x) tan(x) dp dp sine tangent
String Functions and Operators
This section describes functions and operators provided by Aster Database for examining and manipulating string values. Strings in this context include values of all the types character
, character varying
, and text
. Unless otherwise noted, all of the functions listed below work on all of these types, but be wary of potential effects of the automatic padding when using the character type. Generally, the functions described here also work on data of non-string types by converting that data to a string representation first. Some functions also exist natively for the bit-string types.
SQL String Functions and Operators
SQL defines some string functions with a special syntax where certain keywords rather than commas are used to separate the arguments. Details are listed in the following table. These functions are also implemented using the regular syntax for function invocation.
Table 2-4 String functions supported by Aster Database.
Function Retur n
Type
Description string || string text bit_length(string) char_length(string) or character_ length(string) lower(string) octet_length(string) int int text int
Concatenate strings. Note that if any value in the set of values being concatenated is a null, then the whole expression has a value of null. You can circumvent this problem using
.
Number of bits in string
Number of characters in string
Convert string to lower case
Number of bytes in string overlay(string placing string from int [for int]) position(substring in string) substring(string
[from int] [for int]) substring(string from pattern) text int text text
Replace substring
Location of specified substring
Extract substring
Extract substring matching
POSIX regular expression. See
“POSIX Regular Expressions” on page V-110
.
Example
'Bee' || 'hive' bit_length('jose') 32 char_length('jose') 4 lower('TOM') octet_ length('jose') overlay('Txxxxas' placing 'hom' from
2 for 4) position('om' in
'Thomas') substring('Thomas' from 2 for 3) substring('Thomas' from '...$')
Result
Beehive tom
4
Thomas
3 hom mas
V--100 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential String Functions and Operators substring(string from pattern for escape) trim([leading | trailing | both]
[characters] from string) upper(string) text text text
Extract substring matching SQL regular expression. See
Regular Expressions” on page V-110
.
Remove the longest string containing only the characters (a space by default) from the start/end/both ends of the string.
One or more repeated instances of
characters is removed.
Convert string to uppercase substring('Thomas' from '%#"o_a#"_' for '#') trim(both 'x' from
'xTomxx') upper('tom') oma
Tom
TOM
Additional String Functions and Operators
Table 2-5 Additional string functions supported by Aster Database.
Function Retur n
Type
Description Example Result ascii(string) int btrim(string text
[, characters text]) chr(int) decode(string text, type text) text encode(data bytea, type text) text
The “both-ends trim” function removes the longest string consisting only of characters (a space by default) from the start and end of string. One or more repeated instances of the
characters pattern is removed.
text Character with the given ASCII code bytea Decode binary data from string previously encoded with encode.
Parameter type is same as in encode.
Encode binary data to different representation. Supported types are: base64, hex, escape. Escape merely outputs null bytes as \000 and doubles backslashes. initcap(string) text
ASCII code of the first byte of the argument length(string) int lpad(string text, length int [, fill text]) text
Convert the first letter of each word to uppercase and the rest to lowercase. Words are sequences of alphanumeric characters separated by non-alphanumeric characters.
Number of characters in string
Fill up the string to length length by prepending the characters fill (a space by default). If the string is already longer than length then it is truncated (on the right). ascii('x') btrim('xyxtrimy yx', 'xy') trim chr(65) decode('MTIzAAE
=', 'base64')
123\000\001 encode(
E'123\\000\\001
', 'base64')
MTIzAAE= initcap('hi
THOMAS')
120
A
Hi Thomas length('jose') 4 lpad('hi', 5,
'xy') xyxhi
December 14, 2011 Functions and Operators V--101
String Functions and Operators Aster Data proprietary and confidential ltrim(string text
[, characters text]) md5(string) quote_ident( string) quote_literal( string) text text text regexp_replace( string text, pattern text, replacement text
[,flags text]) text regexp_split_to_ table(string text, pattern text [, flags text]) setof text text repeat(string text, number int) replace(string text, from text, to text) text rpad(string text, length int [, fill text]) text rtrim(string text
[, characters text]) split_part(string text, delimiter text, field int) text text text
The “leading-end trim” function removes the longest string consisting only of characters (a space by default) from the start of the passed string. One or more repeated instances of the
characters pattern is removed.
ltrim('zzzytrim
', 'xyz')
Calculates the MD5 hash of string, returning the result in hexadecimal md5('abc') trim
900150983cd24 fb0 d6963f7d28e17 f72
"Sales
Quarter"
Return the given string suitably quoted to be used as an identifier in an SQL statement string.
Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded).
Embedded quotes are properly doubled. quote_ ident('Sales
QuarterFoo bar')
Return the given string suitably quoted to be used as a string literal in an SQL statement string.
Embedded single-quotes and backslashes are properly doubled. quote_literal(
'O\'Reilly')
Replace substring matching
POSIX regular expression. See
“POSIX Regular Expressions” on page V-110 .
regexp_ replace('Thomas
', '.[mN]a.',
'M')
'O''Reilly'
ThM
Split string using a POSIX regular expression as the delimiter. See
Repeat string the specified number of times
Replace all occurrences in string of substring from with substring to regexp_split_ to_table('hello world',
E'\\s+') hello world
(2 rows) repeat('Bh', 4) BhBhBhBh replace(
'abcdefabcdef',
'cd', 'XX') abXXefabXXef
Fill up the string to length length by appending the characters fill
(a space by default). If the string is already longer than length then it is truncated.
The “trailing-end trim” function removes the longest string consisting only of characters (a space by default) from the end of the passed string. One or more repeated instances of the
characters pattern is removed.
rpad('hi', 5,
'xy') rtrim('trimxxxx
', 'x')
Split string on delimiter and return the given field (counting from one) hixyx trim split_ part('abc~@~def
~@~ghi', '~@~',
2) def
V--102 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential SQL/MapReduce Functions strpos(string, substring) substr(string, from [, count]) int text to_ascii(string text [, encoding text]) text to_hex(number int or bigint) text text translate(string text, from text, to text)
Location of specified substring
(same as position(substring in string)
, but note the reversed argument order) strpos('high',
'ig')
Extract substring (same as substring(string from from for count))
Convert string to ASCII from another encoding (only supports conversion from LATIN1,
LATIN2, LATIN9, and WIN1250 encodings) substr('alphabe t', 3, 2) to_ ascii('Karel') to_ hex(2147483647)
Convert number to its equivalent hexadecimal representation
Any character in string that matches a character in the from set is replaced by the corresponding character in the to set translate('1234
5', '14', 'ax')
2 ph
Karel
7fffffff a23x5
Bit String Functions and Operators
This section describes functions and operators for examining and manipulating bit strings, that is values of the types bit
and bit varying
. Aside from the usual comparison operators, the operators shown in the following table can be used. Bit string operands of
&
,
|
, and
#
must be of equal length. When bit shifting, the original length of the string is preserved, as shown in the examples.
Example Result Operato r
Description
||
&
|
#
~
<<
>> concatenation bitwise AND bitwise OR bitwise XOR bitwise NOT bitwise shift left bitwise shift right
B'10001' || B'011'
B'10001' & B'01101'
B'10001' | B'01101'
B'10001' # B'01101'
~ B'10001'
B'10001' << 3
B'10001' >> 2
10001011
00001
11101
11100
01110
01000
00100
The following SQL-standard functions work on bit strings as well as character strings: length
, bit_length
, octet_length
, position
, substring
.
SQL/MapReduce Functions
SQL-MapReduce functions allow any SQL query to invoke procedural, user-installed code that can run in a distributed fashion in Aster Database. SQL-MapReduce Functions are written in
Java and are then invoked as part of an SQL query statement. At their most basic, an
SQL-MapReduce function is a function that converts sets of rows to sets of rows. Due to Aster
December 14, 2011 Functions and Operators V--103
nPath Aster Data proprietary and confidential
Database's distributed architecture, however, an SQL-MapReduce function is parallelized to operate on rows across all nodes simultaneously. Therefore, an SQL-MapReduce function may be invoked on arbitrary sets of rows, or on rows that have been grouped together using the
PARTITION BY clause. Within each partition, rows can further be sorted using the ORDER BY clause.
Synopsis
Invoking an SQL-MapReduce function has the following syntax:
SELECT ...
FROM sqlmr_function_name(
ON { table_name | ( query ) }
PARTITION BY expression [, ...]
ORDER BY expression [ ASC | DESC ] [, ...]
[ clause_name ( literal [, ...] ) ]
[ ... ]
) [, ... ]
[ WHERE ... ]
[ GROUP BY ... ]
[ HAVING ... ]
[ ORDER BY ... ]
[ LIMIT ... ]
[ OFFSET ... ]
nPath
•
•
• nPath is an SQL/Map Reduce function that allows you to perform regular pattern matching over a sequence of rows. It allows users to:
Specify a pattern in an ordered collection -- a sequence -- of rows with symbols;
Specify additional conditions on the rows matching these symbols; and
Extract useful information from these row sequences. nPath computes SQL aggregates over the sequence of rows defined by a regular expression. A regular-expression-based approach is used for this purpose primarily due to its simplicity, popularity, and power of expression. More information about regular expressions are readily available on the web. Many other uses of regular expressions focus on matching patterns in strings of text; nPath enables matching patterns in sequences of rows. nPath can also be used to compute the SQL:1999 analytical primitives such as RANK,
LAG/LEAD, running aggregates, FIRST_VALUE, LAST_VALUE, etc.
nPath Synopsis
SELECT ...
FROM nPath(
ON { table_name | ( query ) }
PARTITION BY expression [, ...]
ORDER BY expression [ ASC | DESC ] [, ...]
MODE ( { OVERLAPPING | NONOVERLAPPING } )
PATTERN ( 'pattern_of_symbols' )
SYMBOLS ( condition AS symbol [, ...] )
RESULT ( aggregate_function( expression OF symbol ) AS alias [, ...] )
) [, ... ]
V--104 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential nPath
[ WHERE ... ]
[ GROUP BY ... ]
[ HAVING ... ]
[ ORDER BY ... ]
[ LIMIT ... ]
[ OFFSET ... ] nPath performs pattern matching and outputs a row with aggregates for each subsequence it matches.
Let us illustrate what we mean by a pattern, what it means to match the pattern against a sequence of rows, and how each matching subsequence translates to an output row.
•
•
•
•
nPath Pattern
A pattern consists of several elements:
Symbols
Operators
Nesting parentheses
Anchors
nPath Symbols
A symbol is a placeholder for a row in the row sequence. nPath uses any valid identifier (a character, followed by characters and digits) as a symbol. Symbols are case insensitive; for example A and a refer to the same symbol.
Each symbol is optionally associated with a predicate; a symbol matches a row only if the row satisfies the symbol's predicate. A symbol may be associated with the predicate "true", meaning that the symbol can match any row. Note that the predicates for different symbols may overlap, and therefore multiple symbols may match one row. These symbol predicates are specified in the
SYMBOLS clause.
nPath Operators
The following operators may be used in a pattern:
|
?
*
+
Charact er
Name
.
Description period cascade (Note: This indicates one symbol follows another. It does not represent a wildcard as in other regular expression syntaxes.) pipe symbol alternative occurs at most once question mark asterisk plus sign occurs zero or more times occurs at least once
The precedence of operators are, from highest to lowest:
1.
Cascade operator (".")
December 14, 2011 Functions and Operators V--105
nPath Aster Data proprietary and confidential
2.
Alternative operator ("|")
3.
Frequency operators ("?", "*", "+").
Operators with equal precedence associate left to right.
Nesting parentheses in nPath
Patterns can be nested using parentheses "(" and ")".
nPath Anchors
The special characters "^" and "$" are placeholders for the start and the end of the sequence respectively. "^" only makes sense at the start of a pattern, and "$" only makes sense at the end of a pattern.
nPath Examples
nPath Example 1: Lead
For each row, get its pageid
as well as the pageid
of the next row in sequence.
SELECT sessionid, pageid, next_pageid
FROM nPath(
ON clicks PARTITION BY sessionid ORDER BY ts
MODE (OVERLAPPING) PATTERN('A.B')
SYMBOLS (true AS A, true AS B)
RESULT ( FIRST(sessionid OF A) AS sessionid,
FIRST(pageid OF A) AS pageid,
FIRST(pageid OF B) AS next_pageid )
) nPath Example 2: Rank
For each row, count the number of preceding rows including this row in a given sequence.
SELECT sessionid, pageid, rank
FROM nPath(
ON clicks PARTITION BY sessionid ORDER BY ts DESC
MODE (OVERLAPPING) PATTERN('A*')
SYMBOLS (true AS A)
RESULT ( FIRST(sessionid OF A) AS sessionid,
FIRST(pageid OF A) AS pageid,
COUNT(* OF A) AS rank )
)
Note the use of DESC in the ORDER BY clause. The reason is that the pattern needs to be matched over the rows preceding the start row, while the semantics dictates that the pattern be matched over the rows following the start row. Reversing the ordering of the rows resolves the issue.
V--106 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential nPath nPath Example 3: Complex Path Query
Find user click-paths starting at page 50 and passing exclusively through either page 80 or pages in category 9 or category 10. Find the
pageid
of the last page in the path and count the number of times page 80 was visited. Report the maximum count for each last page, and sort the output by the latter. Restrict to paths containing at least 5 pages.
Ignore pages in the sequence with category < 0.
SELECT last_pageid, MAX(count_page80)
FROM nPath(
ON ( SELECT * FROM clicks WHERE category >= 0 )
PARTITION BY sessionid
ORDER BY ts
PATTERN ('A.(B|C)*') MODE (OVERLAPPING)
SYMBOLS ( pageid = 50 AS A,
pageid = 80 AS B,
pageid <> 80 AND category IN (9,10) AS C )
RESULT ( LAST(pageid OF ANY(A,B,C)) AS last_pageid,
COUNT(* OF B) AS count_page80,
COUNT(* OF ANY(A,B,C)) AS count_any )
)
WHERE count_any >= 5
GROUP BY last_pageid
ORDER BY MAX(count_page80)
nPath Aggregates
The following table lists the supported nPath aggregates.
nPath Aggregate
FIRST( <expression> OF ANY(<symbol list>) )
LAST( <expression> OF ANY(<symbol list>) )
COUNT( * OF ANY(<symbol list>) )
SUM( <expression> OF ANY(<symbol list>) )
AVG( <expression> OF ANY(<symbol list>) )
MAX( <expression> OF ANY(<symbol list>) )
MIN( <expression> OF ANY(<symbol list>) )
DUPCOUNT( <expression> OF ANY(<symbol list>) )
Description
Value of <expression> in the first row in the row sequence for the symbol list
Value of <expression> in the last row in the row sequence for the symbol list
Number of rows in the row sequence for the symbol list
Sum of the values of <expression> in the row sequence for the symbol list
Average of the values of <expression> in the row sequence for the symbol list
Max of the values of <expression> in the row sequence for the symbol list
Max of the values of <expression> in the row sequence for the symbol list
For each row in the row sequence for the symbol list, the number of times the current value of <expression> has appeared immediately preceding this row.
When <expression> is also the ORDER
BY expression, this is equivalent to
ROW_NUMBER() - RANK()
December 14, 2011 Functions and Operators V--107
Pattern Matching Functions and Operators Aster Data proprietary and confidential
DUPCOUNTCUM( <expression> OF ANY(<symbol list>) )
ACCUMULATE( <expression> OF ANY(<symbol list>) )
For each row in the row sequence for the symbol list, the number of duplicate values of <expression> that have appeared contiguously preceding this row. When
<expression> is also the ORDER BY expression, this is equivalent to ROW_
NUMBER() - DENSE_RANK()
List of the values of <expression> in the row sequence for the symbol list
Pattern Matching Functions and Operators
There are a number of approaches to pattern matching provided in Aster Database:
•
•
•
•
• nPath, the most syntactically rich approach to pattern matching (See “nPath” on page I-86 );
the traditional LIKE operator (See “LIKE” on page V-108
);
the SIMILAR TO operator (added in SQL:1999) (See “SIMILAR TO Regular Expressions” on page V-109 );
POSIX-style regular expressions (See
“POSIX Regular Expressions” on page V-110 ); and
a pattern matching function, SUBSTRING, that uses either SIMILAR TO-style or
POSIX-style regular expressions (See
“SUBSTRING Function with Two Parameters” on page V-111 ).
LIKE
string LIKE pattern [ESCAPE escape-character] string NOT LIKE pattern [ESCAPE escape-character]
Every
pattern
defines a set of strings. The
LIKE
expression returns true if the string is contained in the set of strings represented by
pattern
. (As expected, the
NOT LIKE expression returns false
if
LIKE
returns true
, and vice versa. An equivalent expression is
NOT (string LIKE pattern)
.)
If
pattern
does not contain percent signs or underscore, then the
pattern
only represents the string itself; in that case
LIKE
acts like the equals operator. An underscore (
_
) in
pattern
stands for (matches) any single character; a percent sign (
%
) matches any string of zero or more characters.
Some examples:
'abc' LIKE 'abc' true
'abc' LIKE 'a%' true
'abc' LIKE '_b_' true
'abc' LIKE 'c' false
LIKE
pattern matches always cover the entire string. To match a sequence anywhere within a string, the pattern must therefore start and end with a percent sign.
To match a literal underscore or percent sign without matching other characters, the respective character in pattern must be preceded by the escape character. The default escape character is the backslash but a different one may be selected by using the
ESCAPE
clause. To match the escape character itself, write two escape characters.
V--108 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
Note that the backslash already has a special meaning in string literals, so to write a pattern constant that contains a backslash you must write two LIKE backslashes in an SQL statement
(assuming escape string syntax is used). Thus, writing a pattern that actually matches a literal backslash means writing four backslashes in the statement. You can avoid this by selecting a different escape character with
ESCAPE
; then a backslash is not special to
LIKE
anymore. (But it is still special to the string literal parser, so you still need two of them.)
It's also possible to select no escape character by writing
ESCAPE ''
. This effectively disables the escape mechanism, which makes it impossible to turn off the special meaning of underscore and percent signs in the pattern.
The keyword
ILIKE
can be used instead of
LIKE
to make the match case-insensitive according to the active locale. This is not in the SQL standard but is an Aster Database extension.
The operator
~~
is equivalent to
LIKE
, and
~~*
corresponds to
ILIKE
. There are also
!~~
and
!~~*
operators that represent
NOT LIKE
and
NOT ILIKE
, respectively. All of these operators are Aster Database specific.
SIMILAR TO Regular Expressions
string SIMILAR TO pattern [ESCAPE escape-character] string NOT SIMILAR TO pattern [ESCAPE escape-character]
The
SIMILAR TO
operator returns true
or false
depending on whether its pattern matches the given string. It is much like
LIKE
, except that it interprets the pattern using the SQL standard's definition of a regular expression. SQL regular expressions are a curious cross between
LIKE
notation and common regular expression notation.
Like
LIKE
, the
SIMILAR TO
operator succeeds only if its
pattern
matches the entire string; this is unlike common regular expression practice, wherein the
pattern
may match any part of the string. Also like
LIKE
,
SIMILAR TO
uses
_
and
%
as wildcard characters denoting any single character and any string, respectively (these are comparable to
.
and
.*
in POSIX regular expressions).
In addition to these facilities borrowed from
LIKE
,
SIMILAR TO
supports these pattern-matching metacharacters borrowed from POSIX regular expressions:
Symbol Meaning
|
*
+
()
[...]
The pipe symbol denotes alternation (either of two alternatives).
A star denotes repetition of the previous item zero or more times.
A plus sign denotes repetition of the previous item one or more times.
Parentheses may be used to group items into a single logical item.
Square brackets surround a character class, just as in POSIX regular expressions.
Notice that bounded repetition (
?
and
{...}
) are not provided, though they exist in POSIX.
Also, the dot (
.
) is not a metacharacter.
As with
LIKE
, a backslash disables the special meaning of any of these metacharacters; or a different escape character can be specified with
ESCAPE
.
Some examples:
'abc' SIMILAR TO 'abc' true
'abc' SIMILAR TO 'a' false
'abc' SIMILAR TO '%(b|d)%' true
'abc' SIMILAR TO '(b|c)%' false
December 14, 2011 Functions and Operators V--109
Pattern Matching Functions and Operators Aster Data proprietary and confidential
SUBSTRING Function with Three Parameters
The
SUBSTRING
function with three parameters,
SUBSTRING(string FROM pattern
FOR escape-character)
, provides extraction of a substring that matches an SQL regular
expression pattern. As with
SIMILAR TO
, the specified
pattern
must match to the entire data string, else the function fails and returns null. To indicate the part of the pattern that should be returned on success, the pattern must contain two occurrences of the escape character followed by a double quote (
"
). The text matching the portion of the pattern between these markers is returned.
Some examples:
SELECT SUBSTRING('rhubarb' FROM '%#"h_b#"%' for '#'); gives the result: “hub”, and
SELECT SUBSTRING('rhubarb' FROM '#"h_b#"%' for '#'); gives the result: NULL.
POSIX Regular Expressions
The following table lists the available operators for pattern matching using POSIX regular expressions.
~
~*
!~
!~*
Operator Description Example
Matches regular expression, case sensitive
Matches regular expression, case insensitive
'thomas' ~ '.*thomas.*'
'thomas' ~* '.*Thomas.*'
Does not match regular expression, case sensitive 'thomas' !~ '.*Thomas.*'
Does not match regular expression, case insensitive
'thomas' !~* '.*vadim.*'
POSIX regular expressions provide a more powerful means for pattern matching than the
LIKE and
SIMILAR TO
operators. (Those are described elsewhere, in
SIMILAR TO Regular Expressions (page V-109) .
) Many Unix tools such as egrep
, sed
, and awk use a pattern matching language that is similar to the one described here.
A regular expression is a character sequence that is an abbreviated definition of a set of strings (a regular set). A string is said to match a regular expression if it is a member of the regular set described by the regular expression. As with
LIKE
, pattern characters match string characters exactly unless they are special characters in the regular expression language — but regular expressions use different special characters than
LIKE
does. Unlike
LIKE
patterns, a regular expression is allowed to match anywhere within a string, unless the regular expression is explicitly anchored to the beginning or end of the string.
Some examples:
'abc' ~ 'abc' true
'abc' ~ '^a' true
'abc' ~ '(b|d)' true
'abc' ~ '^(b|c)' false
V--110 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
SUBSTRING Function with Two Parameters
The
SUBSTRING
function with two parameters,
SUBSTRING(string FROM pattern)
, provides extraction of a substring that matches a POSIX regular expression pattern. It returns null if there is no match, otherwise the portion of the text that matched the pattern. But if the pattern contains any parentheses, the portion of the text that matched the first parenthesized subexpression (the one whose left parenthesis comes first) is returned. You can put parentheses around the whole expression if you want to use parentheses within it without triggering this exception. If you need parentheses in the pattern before the subexpression you want to extract, see the non-capturing parentheses described below.
Some examples:
SELECT SUBSTRING('foobar' FROM 'o.b') oob
SELECT SUBSTRING('foobar' FROM 'o(.)b') o
regexp_replace Function
The regexp_replace
function provides substitution of new text for substrings that match
POSIX regular expression patterns. It has the syntax regexp_replace(source, pattern, replacement [, flags ])
The
source
string is returned unchanged if there is no match to the pattern. If there is a match, the
source
string is returned with the
replacement
string substituted for the matching substring. The replacement string can contain
\n
, where
n
is
1
through
9
, to indicate that the source substring matching the
n
th parenthesized subexpression of the pattern should be inserted, and it can contain
\&
to indicate that the substring matching the entire pattern should be inserted.
Write
\\
if you need to put a literal backslash in the replacement text. (As always, remember to double backslashes written in literal constant strings, assuming escape string syntax is used.) The
flags
parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Flag i
specifies case-insensitive matching, while flag g
specifies replacement of each matching substring rather than only the first one.
Some examples: regexp_replace('foobarbaz', 'b..', 'X') fooXbaz regexp_replace('foobarbaz', 'b..', 'X', 'g') fooXX regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g') fooXarYXazY
regexp_split_to_table Function
The regexp_split_to_table
function splits a string using a POSIX regular expression pattern as a delimiter. It has the syntax regexp_split_to_table(string, pattern [, flags ])
If there is no match to the pattern, the function returns the string. If there is at least one match, for each match it returns the text from the end of the last match (or the beginning of the string) to the beginning of the match. When there are no more matches, it returns the text from the end of the last match to the end of the string. The flags parameter is an optional text string containing zero or more single-letter flags that change the function's behavior.
Some regexp_split_to_table Examples
SELECT regexp_split_to_table('the quick brown fox jumped over the lazy dog', '\\\s+');
foo
December 14, 2011 Functions and Operators V--111
Pattern Matching Functions and Operators Aster Data proprietary and confidential
--------
the
quick
brown
fox
jumped
over
the
lazy
dog
(9 rows)
------------------------------------------------
{the,quick,brown,fox,jumped,over,the,lazy,dog}
(1 row)
SELECT foo FROM regexp_split_to_table('the quick brown fox', '\\s*') AS foo;
foo
-----
t
h
e
q
u
i
c
k
b
r
o
w
n
f
o
x
(16 rows)
As the last example demonstrates, the regexp split functions ignore zero-length matches that occur at the start or end of the string or immediately after a previous match. This is contrary to the strict definition of regexp matching that is implemented by regexp_matches, but is usually the most convenient behavior in practice. Other software systems such as Perl use similar definitions.
Regular Expression Details
Aster Database’s regular expressions are implemented using a package written by Henry
Spencer. Much of the description of regular expressions below is copied verbatim from his manual entry.
Regular expressions (“REs”), as defined in POSIX 1003.2, come in two forms: extended REs or
EREs (roughly those of egrep
), and basic REs or BREs (roughly those of ed
). Aster Database supports both forms, and also implements some extensions that are not in the POSIX standard, but have become widely used anyway due to their availability in programming languages such as
Perl and Tcl. REs using these non-POSIX extensions are called advanced REs or AREs in this documentation. AREs are almost an exact superset of EREs, but BREs have several notational incompatibilities (as well as being much more limited). We first describe the ARE and ERE forms, noting features that apply only to AREs, and then describe how BREs differ.
V--112 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
Note: The form of regular expressions accepted by Aster Database can be chosen by setting the regex_flavor
run-time parameter. The usual setting is advanced
, but one might choose extended
for maximum backwards compatibility.
A regular expression is defined as one or more branches, separated by a pipe character (
|
). It matches anything that matches one of the branches.
A branch is zero or more quantified atoms or constraints, concatenated. It matches a match for the first, followed by a match for the second, etc; an empty branch matches the empty string.
A quantified atom is an atom possibly followed by a single quantifier. Without a quantifier, it matches a match for the atom. With a quantifier, it can match some number of matches of the atom. See the table below regarding quantifiers.
A constraint matches an empty string, but matches only when specific conditions are met. A constraint can be used where an atom could be used, except it cannot be followed by a quantifier.
Atom
Table 2-6 Table: Regular Expression Atoms
Description
(re)
(where
re
, with the match noted for possible reporting
(?:re) as above, but the match is not noted for reporting (a "non-capturing" set of parentheses) (AREs only)
.
matches any single character
[chars]
a
chars
\k
(where e.g.
\\
matches a backslash character
\c
where
EREs and BREs, this matches
c
)
{ when followed by a character other than a digit, matches the left-brace character followed by a digit, it is the beginning of a
bound
(see below)
{
; when
x
where
An RE cannot end with
\
.
Note: Remember that the backslash (
\
) already has a special meaning in Aster Database string literals. To write a pattern constant that contains a backslash, you must write two backslashes in the statement, assuming escape string syntax is used.
Table 2-7 Table: Regular Expression Quantifiers
Quantifier Matches
*
+
?
{m}
{m,}
{m,n}
*?
+?
a sequence of 0 or more matches of the atom a sequence of 1 or more matches of the atom a sequence of 0 or 1 matches of the atom a sequence of exactly
m
matches of the atom a sequence of
m
or more matches of the atom a sequence of
m
through
n
(inclusive) matches of the atom;
m
cannot exceed
n
non-greedy version of
* non-greedy version of
+
December 14, 2011 Functions and Operators V--113
Pattern Matching Functions and Operators Aster Data proprietary and confidential
??
{m}?
{m,}?
{m,n}?
non-greedy version of
?
non-greedy version of
{m} non-greedy version of
{m,} non-greedy version of
{m,n}
The forms using
{...}
are known as bounds. The numbers
m
and
n
within a bound are unsigned decimal integers with permissible values from 0 to 255 inclusive.
Non-greedy quantifiers (available in AREs only) match the same possibilities as their corresponding normal (greedy) counterparts, but prefer the smallest number rather than the largest number of matches.
Note: A quantifier cannot immediately follow another quantifier. A quantifier cannot begin an expression or subexpression or follow
^
or
|
.
Table 2-8 Table: Regular Expression Constraints
Constraint Description
^ matches at the beginning of the string
$ matches at the end of the string
(?=re)
positive lookahead matches at any point where a substring matching
re
begins (AREs only)
(?!re)
negative lookahead matches at any point where no substring matching
re
begins (AREs only)
Lookahead constraints cannot contain back references and all parentheses within them are considered non-capturing.
Bracket Expressions
A bracket expression is a list of characters enclosed in
[]
. It normally matches any single character from the list (but see below). If the list begins with
^
, it matches any single character
not from the rest of the list. If two characters in the list are separated by
-
, this is shorthand for the full range of characters between those two (inclusive) in the collating sequence, e.g.
[0-9] in ASCII matches any decimal digit. It is illegal for two ranges to share an endpoint, e.g. a-c-e
.
Ranges are very collating-sequence-dependent, so portable programs should avoid relying on them.
To include a literal
]
in the list, make it the first character (following a possible
^
). To include a literal
-
, make it the first or last character, or the second endpoint of a range. To use a literal
-
as the first endpoint of a range, enclose it in
[.
and
.]
to make it a collating element (see below).
With the exception of these characters, some combinations using
[
(see next paragraphs), and escapes (AREs only), all other special characters lose their special significance within a bracket expression. In particular,
\
is not special when following ERE or BRE rules, though it is special
(as introducing an escape) in AREs.
Within a bracket expression, a collating element (a character, a multiple-character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in
[.
and
.]
stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multiple-character collating element can thus match more than one character, e.g. if the collating sequence includes a ch
collating element, then the RE
[[.ch.]]*c
matches the first five characters of chchcc
.
V--114 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
Note: Aster Database currently has no multicharacter collating elements. This information describes possible future behavior.
Within a bracket expression, a collating element enclosed in
[=
and
=]
is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were
[.
and
.]
.) For example, if o
and
^
are the members of an equivalence class, then
[[=o=]]
,
[[=^=]]
, and
[o^]
are all synonymous. An equivalence class cannot be an endpoint of a range.
Within a bracket expression, the name of a character class enclosed in
[:
and
:]
stands for the list of all characters belonging to that class. Standard character class names are: alnum
, alpha
, blank
, cntrl
, digit
, graph
, lower
, punct
, space
, upper
, xdigit
. These stand for the character classes defined in ctype. A locale can provide others. A character class cannot be used as an endpoint of a range.
There are two special cases of bracket expressions: the bracket expressions
[[:<:]]
and
[[:>:]]
are constraints, matching empty strings at the beginning and end of a word respectively. A word is defined as a sequence of word characters that is neither preceded nor followed by word characters. A word character is an alnum
character (as defined by ctype) or an underscore. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. The constraint escapes described below are usually preferable (they are no more standard, but are certainly easier to type).
Regular Expression Escapes
Escapes are special sequences beginning with
\
followed by an alphanumeric character. Escapes come in several varieties: character entry, class shorthands, constraint escapes, and back references. A
\
followed by an alphanumeric character but not constituting a valid escape is illegal in AREs. In EREs, there are no escapes: outside a bracket expression, a
\
followed by an alphanumeric character merely stands for that character as an ordinary character, and inside a bracket expression,
\
is an ordinary character. (The latter is the one actual incompatibility between EREs and AREs.)
Character-entry escapes exist to make it easier to specify non-printing and otherwise inconvenient characters in REs.
Class-shorthand escapes provide shorthands for certain commonly-used character classes
A constraint escape is a constraint, matching the empty string if specific conditions are met, written as an escape.
A back reference (
\n
) matches the same string matched by the previous parenthesized subexpression specified by the number
n
. For example,
([bc])\1
matches bb
or cc
but not bc
or cb
. The subexpression must entirely precede the back reference in the RE. Subexpressions are numbered in the order of their leading parentheses. Non-capturing parentheses do not define subexpressions.
Note: Keep in mind that an escape's leading
\
will need to be doubled when entering the pattern as an SQL string constant. For example:
'123' ~ E'^\\d{3}' true
Table 2-9 Table: Regular Expression Character-Entry Escapes
Escape Description
\a alert (bell) character, as in C
December 14, 2011 Functions and Operators V--115
Pattern Matching Functions and Operators Aster Data proprietary and confidential
\b backspace, as in C
\B \
to help reduce the need for backslash doubling
\cX
(where same as those of
X
, and whose other bits are all zero
\e
\f the character whose collating-sequence name is
ESC
, or failing that, the character with octal value 033 form feed, as in C
\n
\r newline, as in C carriage return, as in C
\t horizontal tab, as in C
\uwxyz
(where
16-bit) character
U+wxyz
in the local byte ordering
\Ustuvwxyz
(where is exactly eight hexadecimal digits) reserved for a somewhat-hypothetical Unicode extension to 32 bits
\v vertical tab, as in C
\xhhh
(where hexadecimal value is
0xhhh
(a single character no matter how many hexadecimal digits are used)
\0 the character whose value is
0
\xy
(where character whose octal value is
0xy
\xyz
(where character whose octal value is
0xyz
Hexadecimal digits are
0
-
9
, a
f
, and
A
-
F
. Octal digits are
0
-
7
.
The character-entry escapes are always taken as ordinary characters. For example,
\135
is
]
in
ASCII, but
\135
does not terminate a bracket expression.
Table 2-10 Table: Regular Expression Class-Shorthand Escapes
Escape Description
\d
\s
\w
\D
\S
\W
[[:digit:]]
[[:space:]]
[[:alnum:]_] included)
(note underscore is
[^[:digit:]]
[^[:space:]]
[^[:alnum:]_]
(note underscore is included)
Within bracket expressions,
\d
,
\s
, and
\w
lose their outer brackets, and
\D
,
\S
, and
\W
are illegal. (So, for example,
[a-c\d]
is equivalent to
[a-c[:digit:]]
. Also,
[a-c\D]
, which is equivalent to
[a-c^[:digit:]]
, is illegal.)
V--116 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
Table 2-11 Table: Regular Expression Constraint Escapes
Escap e
Description
\A
\m
\M
\y
\Y
\Z matches only at the beginning of the string matches only at the beginning of a word matches only at the end of a word matches only at the beginning or end of a word matches only at a point that is not the beginning or end of a word matches only at the end of the string
A word is defined as in the specification of
[[:<:]]
and
[[:>:]]
above. Constraint escapes are illegal within bracket expressions.
Table 2-12 Table: Regular Expression Back References
Escape Description
\m
(where
m
'th subexpression
\mnn
(where
nn
is some more digits, and the decimal value
mnn
is not greater than the number of closing capturing parentheses seen so far) a back reference to the
mnn
'th subexpression
Note: There is an inherent historical ambiguity between octal character-entry escapes and back references, which is resolved by heuristics, as hinted at above. A leading zero always indicates an octal escape. A single non-zero digit, not followed by another digit, is always taken as a back reference. A multidigit sequence not starting with a zero is taken as a back reference if it comes after a suitable subexpression (i.e. the number is in the legal range for a back reference), and otherwise is taken as octal.
Regular Expression Metasyntax
In addition to the main syntax described above, there are some special forms and miscellaneous syntactic facilities available.
Normally the
flavor of RE being used is determined by regex_flavor
. However, this can be overridden by a director prefix. If an RE begins with
***:
, the rest of the RE is taken as an ARE regardless of regex_flavor
. If an RE begins with
***=
, the rest of the RE is taken to be a literal string, with all characters considered ordinary characters.
An ARE can begin with embedded options: a sequence
(?xyz)
(where
xyz
is one or more alphabetic characters) specifies options affecting the rest of the RE. These options override any previously determined options (including both the RE flavor and case sensitivity).
Table 2-13 Table: ARE Embedded-Option Letters
Option Description b rest of RE is a BRE
December 14, 2011 Functions and Operators V--117
Pattern Matching Functions and Operators Aster Data proprietary and confidential c e i case-sensitive matching (overrides operator type) rest of RE is an ERE case-insensitive matching (overrides operator type) m
historical n
newline-sensitive p
partial matching q rest of RE is a literal ("quoted") string, all ordinary characters s
non-newline-sensitive (default) t
tight (default; see below) w inverse partial newline-sensitive ("weird") matching x expanded syntax (see below)
Embedded options take effect at the
)
terminating the sequence. They can appear only at the start of an ARE (after the
***:
director if any).
In addition to the usual (tight) RE syntax, in which all characters are significant, there is an expanded syntax, available by specifying the embedded x
option. In the expanded syntax, white-space characters in the RE are ignored, as are all characters between a
# and the following newline (or the end of the RE). This permits paragraphing and commenting a complex RE. There are three exceptions to that basic rule: a white-space character or
#
preceded by
\
is retained white space or
#
within a bracket expression is retained white space and comments cannot appear within multicharacter symbols, such as
(?:
For this purpose, white-space characters are blank, tab, newline, and any character that belongs to the
space
character class.
Finally, in an ARE, outside bracket expressions, the sequence
(?#ttt)
(where
ttt
is any text not containing a
)
) is a comment, completely ignored. Again, this is not allowed between the characters of multicharacter symbols, like
(?:
. Such comments are more a historical artifact than a useful facility, and their use is deprecated; use the expanded syntax instead.
None of these metasyntax extensions is available if an initial
***=
director has specified that the user's input be treated as a literal string rather than as an RE.
Regular Expression Matching Rules
In the event that a regular expression (“RE”) could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, either the longest possible match or the shortest possible match will be taken, depending on whether the RE is greedy (longest match) or non-greedy (shortest).
Whether an RE is greedy or not is determined by the following rules:
•
•
Most atoms, and all constraints, have no greediness attribute (because they cannot match variable amounts of text anyway).
Adding parentheses around an RE does not change its greediness.
V--118 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Pattern Matching Functions and Operators
•
•
•
•
A quantified atom with a fixed-repetition quantifier (
{m}
or
{m}?
) has the same greediness
(possibly none) as the atom itself.
A quantified atom with other normal quantifiers (including
{m,n}
with
m
equal to
n
) is greedy (prefers longest match).
A quantified atom with a non-greedy quantifier (including
{m,n}?
with
m
equal to
n
) is non-greedy (prefers shortest match).
A branch — that is, an RE that has no top-level
|
operator — has the same greediness as the first quantified atom in it that has a greediness attribute.
An RE consisting of two or more branches connected by the
|
operator is always greedy.
•
The above rules associate greediness attributes not only with individual quantified atoms, but with branches and entire REs that contain quantified atoms. What that means is that the matching is done in such a way that the branch, or whole RE, matches the longest or shortest possible substring as a whole. Once the length of the entire match is determined, the part of it that matches any particular subexpression is determined on the basis of the greediness attribute of that subexpression, with subexpressions starting earlier in the RE taking priority over ones starting later.
An example of what this means:
SELECT SUBSTRING('XY1234Z' FROM 'Y*([0-9]{1,3})');
Result: 123
SELECT SUBSTRING('XY1234Z' FROM 'Y*?([0-9]{1,3})');
Result: 1
In the first case, the RE as a whole is greedy because
Y*
is greedy. It can match beginning at the
Y
, and it matches the longest possible string starting there, i.e.,
Y123
. The output is the parenthesized part of that, or
123
. In the second case, the RE as a whole is non-greedy because
Y*?
is non-greedy. It can match beginning at the
Y
, and it matches the shortest possible string starting there, i.e.,
Y1
. The subexpression
[0-9]{1,3}
is greedy but it cannot change the decision as to the overall match length; so it is forced to match just
1
.
In short, when an RE contains both greedy and non-greedy subexpressions, the total match length is either as long as possible or as short as possible, according to the attribute assigned to the whole RE. The attributes assigned to the subexpressions only affect how much of that match they are allowed to "eat" relative to each other.
The quantifiers
{1,1}
and
{1,1}?
can be used to force greediness or non-greediness, respectively, on a subexpression or a whole RE.
Match lengths are measured in characters, not collating elements. An empty string is considered longer than no match at all. For example: bb*
matches the three middle characters of abbbc
;
(week|wee)(night|knights)
matches all ten characters of weeknights
; when
(.*).*
is matched against abc
the parenthesized subexpression matches all three characters; and when
(a*)*
is matched against bc
both the whole RE and the parenthesized subexpression match an empty string.
If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, e.g. x
becomes
[xX]
. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, e.g.
[x]
becomes
[xX]
and
[^x]
becomes
[^xX]
.
If newline-sensitive matching is specified,
.
and bracket expressions using
^
will never match the newline character (so that matches will never cross newlines unless the RE explicitly arranges it) and
^ and
$
will match the empty string after and before a newline respectively, in
December 14, 2011 Functions and Operators V--119
Pattern Matching Functions and Operators Aster Data proprietary and confidential addition to matching at beginning and end of string respectively. But the ARE escapes
\A
and
\Z
continue to match beginning or end of string only.
If partial newline-sensitive matching is specified, this affects
.
and bracket expressions as with newline-sensitive matching, but not
^
and
$
.
If inverse partial newline-sensitive matching is specified, this affects
^
and
$
as with newline-sensitive matching, but not
.
and bracket expressions. This isn't very useful but is provided for symmetry.
Limits and Compatibility
No particular limit is imposed on the length of REs in this implementation. However, programs intended to be highly portable should not employ REs longer than 256 bytes, as a
POSIX-compliant implementation can refuse to accept such REs.
The only feature of AREs that is actually incompatible with POSIX EREs is that
\
does not lose its special significance inside bracket expressions. All other ARE features use syntax which is illegal or has undefined or unspecified effects in POSIX EREs; the
*** syntax of directors likewise is outside the POSIX syntax for both BREs and EREs.
Many of the ARE extensions are borrowed from Perl, but some have been changed to clean them up, and a few Perl extensions are not present. Incompatibilities of note include
\b
,
\B
, the lack of special treatment for a trailing newline, the addition of complemented bracket expressions to the things affected by newline-sensitive matching, the restrictions on parentheses and back references in lookahead constraints, and the longest/shortest-match (rather than first-match) matching semantics.
Two significant incompatibilities exist between AREs and the ERE syntax recognized by Aster
Database:
•
•
In AREs,
\
followed by an alphanumeric character is either an escape or an error, while in previous releases, it was just another way of writing the alphanumeric. This should not be much of a problem because there was no reason to write such a sequence in earlier releases.
In AREs,
\
remains a special character within
[]
, so a literal
\
within a bracket expression must be written
\\
.
While these differences are unlikely to create a problem for most applications, you can avoid them if necessary by setting regex_flavor
to extended
.
Basic Regular Expressions
BREs differ from EREs in several respects.
|
,
+
, and
?
are ordinary characters and there is no equivalent for their functionality. The delimiters for bounds are
\{
and
\}
, with
{ and
}
by themselves ordinary characters. The parentheses for nested subexpressions are
\(
and
\)
, with
(
and
)
by themselves ordinary characters.
^
is an ordinary character except at the beginning of the RE or the beginning of a parenthesized subexpression,
$ is an ordinary character except at the end of the RE or the end of a parenthesized subexpression, and
*
is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading
^
). Finally, single-digit back references are available, and
\<
and
\>
are synonyms for
[[:<:]]
and
[[:>:]]
respectively; no other escapes are available.
V--120 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Datatype Formatting Functions and Operators
Datatype Formatting Functions and Operators
The Aster Database formatting functions provide a powerful set of tools for converting various datatypes (date/time, integer, floating point, numeric) to formatted strings and for converting from formatted strings to specific datatypes. These functions all follow a common calling convention: the first argument is the value to be formatted and the second argument is a template that defines the output or input format.
The to_timestamp
function can also take a single double precision argument to convert from
Unix epoch to timestamp with time zone
. (Integer Unix epochs are implicitly cast to double precision
.)
Table 2-14 Datatype Conversion Functions
Function Return
Type
Description Example to_char(timestamp, text) to_char(interval, text) to_char(int, text) to_char(double precision, text) text text to_char(numeric, text) text to_date(text, text) to_number(text, text) to_timestamp(text, text) to_timestamp(double precision) text text date numeric convert time stamp to string convert interval to string to_char(current_ timestamp, 'HH12:MI:SS') to_char(interval '15h 2m
12s', 'HH24:MI:SS') to_char(125, '999') convert integer to string convert real/double precision to string to_char(125.8::real,
'999D9') convert numeric to string to_char(-125.8,
'999D99S') convert string to date to_date('05 Dec 2000',
'DD Mon YYYY') convert string to numeric to_number('12,454.8-',
'99G999D9S') convert string to time stamp to_timestamp('05 Dec
2000', 'DD Mon YYYY') timestamp with time zone timestamp with time zone convert UNIX epoch to time stamp to_timestamp(200120400)
The following table shows the template patterns available for formatting date and time values:
Table 2-15 Data and time template patterns
Pattern Description
HH
HH12
HH24
MI
SS
MS
US
SSSS hour of day (01-12) hour of day (01-12) hour of day (00-23) minute (00-59) second (00-59) millisecond (000-999) microsecond (000000-999999) seconds past midnight (0-86399)
December 14, 2011 Functions and Operators V--121
Datatype Formatting Functions and Operators Aster Data proprietary and confidential rm
TZ tz
CC
J
Q
RM
D
W
WW
IW
AM or A.M. or PM or
P.M.
am or a.m. or pm or p.m.
Y,YYY
YYYY
YYY
YY
Y
IYYY
IYY
IY
I
BC or B.C. or AD or
A.D.
meridian indicator (uppercase) meridian indicator (lowercase) year (4 and more digits) with comma year (4 and more digits) last 3 digits of year last 2 digits of year last digit of year
ISO year (4 and more digits) last 3 digits of ISO year last 2 digits of ISO year last digits of ISO year era indicator (uppercase)
DAY
Day day
DY
Dy dy
DDD
DD bc or b.c. or ad or a.d.
era indicator (lowercase)
MONTH full uppercase month name (blank-padded to 9 chars)
Month month full mixed-case month name (blank-padded to 9 chars) full lowercase month name (blank-padded to 9 chars)
MON
Mon mon
MM abbreviated uppercase month name (3 chars in English, localized lengths vary) abbreviated mixed-case month name (3 chars in English, localized lengths vary) abbreviated lowercase month name (3 chars in English, localized lengths vary) month number (01-12) full uppercase day name (blank-padded to 9 chars) full mixed-case day name (blank-padded to 9 chars) full lowercase day name (blank-padded to 9 chars) abbreviated uppercase day name (3 chars in English, localized lengths vary) abbreviated mixed-case day name (3 chars in English, localized lengths vary) abbreviated lowercase day name (3 chars in English, localized lengths vary) day of year (001-366) day of month (01-31) day of week (1-7; Sunday is 1) week of month (1-5) (The first week starts on the first day of the month.) week number of year (1-53) (The first week starts on the first day of the year.)
ISO week number of year (The first Thursday of the new year is in week 1.) century (2 digits) (The twenty-first century starts on 2001-01-01.)
Julian Day (days since January 1, 4712 BC) quarter month in Roman numerals (I-XII; I=January) (uppercase) month in Roman numerals (i-xii; i=January) (lowercase) time-zone name (uppercase) time-zone name (lowercase)
V--122 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Functions and Operators
Table 2-16 to_char Examples
Expression to_char(current_timestamp, 'Day, DD HH12:MI:SS') to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS')
Result
'Tuesday , 06 05:39:18'
'Tuesday, 6 05:39:18'
Date/Time Functions and Operators
All of the functions and operators described below that take time
or timestamp
inputs actually come in two variants: one that takes time with time zone
or timestamp with time zone
, and one that takes time without time zone
or timestamp without time zone
. For brevity, these variants are not shown separately. Also, the
+
and
* operators come in commutative pairs (for example both date + integer
and integer + date
); we show only one of each such pair.
Date/Time Operators
The following table illustrates the behaviors of the basic arithmetic operators (
+
,
*
, etc.) with date/time values:
*
*
*
-
-
-
-
-
-
+
-
+
+
+
+
+
Table 2-17 Date/Time Operators
Operat or
Example
-
date '2001-09-28' + integer '7' date '2001-09-28' + interval '1 hour' date '2001-09-28' + time '03:00' interval '1 day' + interval '1 hour' timestamp '2001-09-28 01:00' + interval '23 hours'
Result date '2001-10-05' timestamp '2001-09-28 01:00:00' timestamp '2001-09-28 03:00:00' interval '1 day 01:00:00' timestamp '2001-09-29 00:00:00' time '01:00' + interval '3 hours'
- interval '23 hours' time '04:00:00' interval '-23:00:00' date '2001-10-01' - date '2001-09-28' integer '3' date '2001-10-01' - integer '7' date '2001-09-24' date '2001-09-28' - interval '1 hour' timestamp '2001-09-27 23:00:00' time '05:00' - time '03:00' interval '02:00:00' time '05:00' - interval '2 hours' timestamp '2001-09-28 23:00' - interval '23 hours' time '03:00:00' timestamp '2001-09-28 00:00:00' interval '1 day -01:00:00' interval '1 day 15:00:00' interval '1 day' - interval '1 hour' timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00'
900 * interval '1 second'
21 * interval '1 day' double precision '3.5' * interval '1 hour' interval '00:15:00' interval '21 days' interval '03:30:00'
December 14, 2011 Functions and Operators V--123
Date/Time Functions and Operators Aster Data proprietary and confidential
/ interval '1 hour' / double precision
'1.5' interval '00:40:00'
Function
Date/Time Functions
The following table shows the available functions for date/time value processing, with additional information on several functions following:
Return
Type
Description Example Result clock_timestamp() date_part(text, timestamp) date_part(text, interval) date_trunc(text, timestamp) extract(field from timestamp) extract(field from interval) isfinite(timestamp
) isfinite(interval) justify_ days(interval) justify_ hours(interval) justify_ interval(interval) now() timestamp with time zone double precision
Current date and time
(changes during statement execution). See also now()
Get subfield (equivalent to
extract). See also “date_ part Function” on page V-127
.
SELECT clock_ timestamp(); date_part('hour', timestamp '2001-02-16
20:38:40') double precision
Get subfield (equivalent to extract) timestamp Truncate to specified
precision. See also “date_ trunc Function” on page V-128
.
double precision
Get time or date subfield.
See also
double precision
Boolean
Get time or date subfield
Test for finite time stamp
(not equal to infinity) date_part('month', interval '2 years 3 months') date_trunc('hour', timestamp '2001-02-16
20:38:40') extract(hour from timestamp '2001-02-16
20:38:40') extract(month from interval '2 years 3 months') isfinite(timestamp
'2001-02-16
21:28:30')
Boolean Test for finite interval isfinite(interval '4 hours') justify_days(interval
'30 days') interval interval
Adjust interval so 30-day time periods are represented as months
Adjust interval so 24-hour time periods are represented as days interval Adjust interval using justify_days and justify_ hours, with additional sign adjustments timestamp Date and time of the start of the transaction. See also clock_timestamp() justify_ hours(interval '24 hours') justify_ interval(interval '1 mon -1 hour')
SELECT now();
Current timestamp
20
3
2001-02-1
6 20:00:00
20
3 true true
1 month
1 day
29 days
23:00:00
.
Time of the start of this transaction
EXTRACT
Function
EXTRACT(field FROM source)
V--124 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Functions and Operators
The extract
function retrieves subfields such as year or hour from date/time values. source must be a value expression of type timestamp
, time
, or interval
. (Expressions of type date
will be cast to timestamp
and can therefore be used as well.)
field
is an identifier or string that selects what field to extract from the source value. The extract
function returns values of type double precision
. The following are valid field names:
century
Field Name
The century
SELECT EXTRACT(‘CENTURY’ FROM TIMESTAMP '2000-12-16 12:21:13');
Result: 20
SELECT EXTRACT(‘CENTURY’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 21
The first century starts at 0001-01-01 00:00:00 AD .
day
Field Name
The day (of the month) field (1 - 31)
SELECT EXTRACT(‘DAY’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16
decade
Field Name
The year field divided by 10
SELECT EXTRACT(‘DECADE’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200
dow
Field Name
The day of the week (0 - 6; Sunday is 0) (for timestamp values only)
SELECT EXTRACT(‘DOW’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5
Note that extract's day of the week numbering is different from that of the to_char function.
doy
Field Name
The day of the year (1 - 365/366) (for timestamp values only)
SELECT EXTRACT(‘DOY’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47
epoch
Field Name
For date
and timestamp
values, the number of seconds since 1970-01-01 00:00:00-00 (can be negative); for interval values, the total number of seconds in the interval
SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-08');
Result: 982384720
SELECT EXTRACT(‘EPOCH’ FROM INTERVAL '5 days 3 hours');
Result: 442800
Here is how you can convert an epoch value back to a time stamp:
December 14, 2011 Functions and Operators V--125
Date/Time Functions and Operators Aster Data proprietary and confidential
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
hour
Field Name
The hour field (0 - 23)
SELECT EXTRACT(‘HOUR’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 20
microseconds
Field Name
The seconds field, including fractional parts, multiplied by 1 000 000. Note that this includes full seconds.
SELECT EXTRACT(‘MICROSECONDS’ FROM TIME '17:12:28.5');
Result: 28500000
millenium
Field Name
The millennium
SELECT EXTRACT(‘MILLENNIUM’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 3
Years in the 1900s are in the second millennium. The third millennium starts January 1, 2001.
milliseconds
Field Name
The seconds field, including fractional parts, multiplied by 1000. Note that this includes full seconds.
SELECT EXTRACT(‘MILLISECONDS’ FROM TIME '17:12:28.5');
Result: 28500
minute
Field Name
The minutes field (0 - 59)
SELECT EXTRACT(‘MINUTE’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38
month
Field Name
For timestamp
values, the number of the month within the year (1 - 12) ; for interval values the number of months, modulo 12 (0 - 11)
SELECT EXTRACT(‘MONTH’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2
SELECT EXTRACT(‘MONTH’ FROM INTERVAL '2 years 3 months');
Result: 3
SELECT EXTRACT(‘MONTH’ FROM INTERVAL '2 years 13 months');
Result: 1
V--126 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Functions and Operators
quarter
Field Name
The quarter of the year (1 - 4) that the day is in (for timestamp values only)
SELECT EXTRACT(‘QUARTER’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 1
second
Field Name
The seconds field, including fractional parts (0 - 59)
SELECT EXTRACT(‘SECOND’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 40
SELECT EXTRACT(‘SECOND’ FROM TIME '17:12:28.5');
Result: 28.5
timezone
Field Name
The time zone offset from UTC, measured in seconds. Positive values correspond to time zones east of UTC, negative values to zones west of UTC.
timezone_hour
The hour component of the time zone offset
timezone_minute
The minute component of the time zone offset
week
Field Name
The number of the week of the year that the day is in. By definition (ISO 8601), the first week of a year contains January 4 of that year. (The ISO-8601 week starts on Monday.) In other words, the first Thursday of a year is in week 1 of that year. (for timestamp
values only)
Because of this, it is possible for early January dates to be part of the 52nd or 53rd week of the previous year. For example, 2005-01-01 is part of the 53rd week of year 2004, and 2006-01-01 is part of the 52nd week of year 2005.
SELECT EXTRACT(‘WEEK’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7
year
Field Name
The year field. Keep in mind there is no 0 AD, so subtracting BC years from AD years should be done with care.
SELECT EXTRACT(‘YEAR’ FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001
The extract function is primarily intended for computational processing. For formatting date/time values for display, see the Datatypes section.
date_part
Function
date_part('field', source)
December 14, 2011 Functions and Operators V--127
Date/Time Functions and Operators Aster Data proprietary and confidential
The date_part
function is modeled on the traditional Ingres equivalent to the SQL-standard function extract
. Note that here the
field
parameter needs to be a string value, not a name.
The valid field names for date_part
are the same as for extract
.
SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
Result: 4
date_trunc
Function
The function date_trunc
is conceptually similar to the trunc
function for numbers.
date_trunc('field', source)
source
is a value expression of type timestamp
or interval
. (Values of type date
and time
are cast automatically, to timestamp
or interval
respectively.) field selects to which precision to truncate the input value. The return value is of type timestamp
or interval with all fields that are less significant than the selected one set to zero (or one, for day and month). date_trunc Arguments
•
•
•
•
•
•
•
•
•
•
•
•
•
Valid values for field are: microseconds milliseconds second minute hour day week month quarter year decade century millennium date_trunc Examples
SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-02-16 20:00:00
SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
Result: 2001-01-01 00:00:00
V--128 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Functions and Operators
Current Date/Time
Aster Database provides a number of functions that return values related to the current date and time. These SQL-standard functions all return values based on the start time of the current transaction:
CURRENT_DATE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_TIME(precision)
CURRENT_TIMESTAMP(precision)
LOCALTIME
LOCALTIMESTAMP
LOCALTIME(precision)
LOCALTIMESTAMP(precision)
CURRENT_TIME and CURRENT_TIMESTAMP deliver values with time zone; LOCALTIME and LOCALTIMESTAMP deliver values without time zone.
CURRENT_TIME, CURRENT_TIMESTAMP, LOCALTIME, and LOCALTIMESTAMP can optionally take a precision parameter, which causes the result to be rounded to that many fractional digits in the seconds field. Without a precision parameter, the result is given to the full available precision.
Some examples: beehive=> SELECT CURRENT_TIME;
current_time
--------------------
16:58:54.222959-07
(1 row) beehive=> SELECT CURRENT_DATE;
current_date
--------------
2011-03-15
(1 row) beehive=> SELECT CURRENT_TIMESTAMP;
current_timestamp
-------------------------------
2011-03-15 16:59:13.883053-07
(1 row) beehive=> SELECT CURRENT_TIMESTAMP(1);
current_timestamp(1)
---------------------------
2011-03-15 16:59:24.80-07
(1 row) beehive=> SELECT LOCALTIMESTAMP;
localtimestamp
---------------------------
2011-03-15 16:59:33.00688
(1 row)
December 14, 2011 Functions and Operators V--129
Aggregate Functions Aster Data proprietary and confidential
Since these functions return the start time of the current transaction, their values do not change during the transaction. This is considered a feature: the intent is to allow a single transaction to have a consistent notion of the “current” time, so that multiple modifications within the same transaction bear the same time stamp.
Aggregate Functions
Aggregate functions, also called “the SQL aggregates,” compute a single result value from a set of input values. The following built-in aggregate functions are supported in Aster Database:
Table 2-18 Basic Aggregate Functions
Function Argument Type
AVG(expression)
COUNT(*)
COUNT(expression)
MAX(expression)
MIN(expression)
SUM(expression)
Return Type Description smallint, int, bigint, real, double precision, numeric, or interval any any numeric, string, or date/time type any numeric, string, or date/time type smallint, int, bigint, real, double precision, numeric, or interval numeric for any integer type argument, double precision for a floating-point argument, otherwise the same as the argument datatype bigint bigint same as argument type same as argument type bigint for smallint or int arguments, numeric for bigint arguments, double precision for floating-point arguments, otherwise the same as the argument datatype the average (arithmetic mean) of all input values number of input rows number of input rows for which the value of expression is not null maximum value of expression across all input values minimum value of expression across all input values sum of expression across all input values
It should be noted that except for COUNT(), these functions return a null value when no rows are selected. In particular, SUM() of no rows returns null, not zero as one might expect. The
COALESCE function may be used to substitute zero for null when necessary.
The SQL aggregates typically operate on a window of values, as explained in
.
See also “Aggregate Functions for Statistics” on page V-130
.
Aggregate Functions for Statistics
nClsuter supports a number of aggregate functions typically used in statistical analysis.
V--130 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Conditional SQL Expressions
Table 2-19 Aggregate Functions for Statistics
Function Argument Type
STDDEV(expression)
STDDEV_POP(expression)
STDDEV_SAMP(expression)
VARIANCE(expression)
VAR_POP(expression)
VAR_SAMP(expression)
Return Type Description smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric historical alias for stddev_ samp smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric population standard deviation of the input values sample standard deviation of the input values smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric smallint, int, bigint, real, double precision, or numeric double precision for floating-point arguments, otherwise numeric historical alias for var_ samp population variance of the input values (square of the population standard deviation) sample variance of the input values (square of the sample standard deviation)
Conditional SQL Expressions
This section describes the SQL-compliant conditional expressions available in Aster Database.
CASE
The SQL
CASE
expression is a generic conditional expression, similar to if/else statements in other languages:
CASE WHEN condition THEN result
[WHEN ...]
[ELSE result]
END
CASE
clauses can be used wherever an expression is valid. condition is an expression that returns a Boolean result. If the result is true then the value of the
CASE
expression is the result that follows the condition. If the result is false any subsequent
WHEN
clauses are searched in the same manner. If no
WHEN
condition is true then the value of the case expression is the result in the
ELSE
clause. If the
ELSE
clause is omitted and no condition matches, the result is null.
An example:
SELECT * FROM test;
a
---
1
2
3
SELECT a,
December 14, 2011 Functions and Operators V--131
Conditional SQL Expressions Aster Data proprietary and confidential
CASE WHEN a=1 THEN 'one'
WHEN a=2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
The datatypes of all the result expressions must be convertible to a single output type.
The following "simple"
CASE
expression is a specialized variant of the general form above:
CASE expression
WHEN value THEN result
[WHEN ...]
[ELSE result]
END
The expression is computed and compared to all the value specifications in the
WHEN
clauses until one is found that is equal. If no match is found, the result in the
ELSE clause (or a null value) is returned. This is similar to the switch
statement in C.
The example above can be written using the simple
CASE
syntax:
SELECT a,
CASE a WHEN 1 THEN 'one'
WHEN 2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+-------
1 | one
2 | two
3 | other
A
CASE
expression does not evaluate any subexpressions that are not needed to determine the result. For example, this is a possible way of avoiding a division-by-zero failure:
SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
COALESCE
COALESCE(value [, ...])
The
COALESCE
function returns the first of its arguments that is not null. Null is returned only if all arguments are null. It is often used to substitute a default value for null values when data is retrieved for display, for example:
SELECT COALESCE(description, short_description, '(none)') ...
Like a
CASE
expression,
COALESCE
will not evaluate arguments that are not needed to determine the result; that is, arguments to the right of the first non-null argument are not evaluated. This SQL-standard function provides capabilities similar to
NVL
and
IFNULL
, which are used in some other database systems.
V--132 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Subquery SQL Expressions
NULLIF
NULLIF(value1, value2)
The
NULLIF
function returns a null value if
value1
and
value2
are equal; otherwise it returns
value1
. This can be used to perform the inverse operation of the
COALESCE
example given above:
SELECT NULLIF(value, '(none)') ...
If
value1
is (none), return a null, otherwise return
value1
.
GREATEST
and
LEAST
GREATEST(value [, ...])
LEAST(value [, ...])
The
GREATEST
and
LEAST
functions select the largest or smallest value from a list of any number of expressions. The expressions must all be convertible to a common datatype, which will be the type of the result.
NULL
values in the list are ignored. The result will be
NULL
only if all the expressions evaluate to
NULL
.
Note that
GREATEST
and
LEAST
are not in the SQL standard, but are a common extension.
Subquery SQL Expressions
This section describes the SQL-compliant subquery expressions available in Aster Database. All of the expression forms documented in this section return Boolean (true/false) results.
EXISTS
EXISTS (subquery)
The argument of
EXISTS
is an arbitrary
SELECT
statement, or subquery. The subquery is evaluated to determine whether it returns any rows. If it returns at least one row, the result of
EXISTS
is true
; if the subquery returns no rows, the result of
EXISTS
is false
.
The subquery will generally only be executed far enough to determine whether at least one row is returned, not all the way to completion. It is unwise to write a subquery that has any side effects; whether the side effects occur or not may be difficult to predict.
Since the result depends only on whether any rows are returned, and not on the contents of those rows, the output list of the subquery is normally uninteresting. A common coding convention is to write all
EXISTS
tests in the form
EXISTS(SELECT 1 WHERE ...)
. There are exceptions to this rule however, such as subqueries that use
INTERSECT
.
IN
expression IN (subquery)
The right-hand side is a parenthesized subquery, which must return exactly one column. The left-hand expression is evaluated and compared to each row of the subquery result. The result of
IN
is true
if any equal subquery row is found. The result is false
if no equal row is found
(including the special case where the subquery returns no rows).
December 14, 2011 Functions and Operators V--133
Subquery SQL Expressions Aster Data proprietary and confidential
Note that if the left-hand expression yields null, or if there are no equal right-hand values and at least one right-hand row yields null, the result of the
IN
construct will be null, not false
. This is in accordance with SQL’s normal rules for Boolean combinations of null values.
As with
EXISTS
, it's unwise to assume that the subquery will be evaluated completely.
Note on SQL compliance: There is a small difference between a fully SQL-compliant implementation of IN/NOT IN and the Aster Database implementation. We can illustrate this with the example expression, “
1 IN (<subquery>)
”. Three cases are possible:
•
•
•
Case 1: The subquery output contains 1. In this case both SQL-compliant implementations and Aster Database return true.
Case 2: The subquery output does not contain 1, and does not contain a NULL. In this case, both SQL-compliant implementations and Aster Database return false.
Case 3: The subquery output does not contain 1, but it does contain a NULL. In this case, an
SQL-compliant implementation returns NULL, but the Aster Database implementation returns false.
NOT IN
expression NOT IN (subquery)
The right-hand side is a parenthesized subquery, which must return exactly one column. The left-hand expression is evaluated and compared to each row of the subquery result. The result of
NOT IN
is true
if only unequal subquery rows are found (including the special case where the subquery returns no rows). The result is false
if any equal row is found.
Note that if the left-hand expression yields null, or if there are no equal right-hand values and at least one right-hand row yields null, the result of the
NOT IN
construct will be null, not true
.
This is in accordance with SQL’s normal rules for Boolean combinations of null values.
As with
EXISTS
, it's unwise to assume that the subquery will be evaluated completely.
See also the Note on SQL Compliance in the section above explaining “IN”.
ANY/SOME
expression operator ANY (subquery) expression operator SOME (subquery)
Used as an equality, ANY evaluates to TRUE if any one of a set of comparisons is TRUE. The right-hand side is a parenthesized subquery, which must return exactly one column. The left-hand expression is evaluated and compared to each row of the subquery result using the given operator, which must yield a Boolean result. The result of
ANY
is true
if any true
result is obtained. The result is false
if no true
result is found (including the special case where the subquery returns no rows).
SOME
is a synonym for
ANY
.
IN
is equivalent to
= ANY
.
Note that if there are no successes and at least one right-hand row yields null for the operator's result, the result of the
ANY
construct will be null, not false
. This is in accordance with SQL’s normal rules for Boolean combinations of null values.
As with
EXISTS
, it's unwise to assume that the subquery will be evaluated completely.
V--134 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Subquery SQL Expressions
ALL
expression operator ALL (subquery)
The right-hand side is a parenthesized subquery, which must return exactly one column. The left-hand expression is evaluated and compared to each row of the subquery result using the given operator, which must yield a Boolean result. The result of
ALL
is true
if all rows yield true
(including the special case where the subquery returns no rows). The result is false
if any false
result is found. The result is
NULL
if the comparison does not return false
for any row, and it returns
NULL
for at least one row.
NOT IN
is equivalent to
<> ALL
.
As with
EXISTS
, it's unwise to assume that the subquery will be evaluated completely.
December 14, 2011 Functions and Operators V--135
Subquery SQL Expressions Aster Data proprietary and confidential
V--136 Database SQL and Function Reference, version 4.6.2
aster data
V--3
Window Functions
Window functions allow the calculation of aggregates and other values on a per-row basis as opposed to a per-set or per-group basis. Part of the SQL 2003 standard, window functions offer performance advantages for many OLAP applications that otherwise would have to calculate such values through other, less convenient, means. For example, a window function may be used to compute a running sum, a moving average, a delta between values in neighboring rows, as well as apply ranking and row numbering to a table.
This section explains the different types of window functions and is divided into the following subsections:
•
•
•
•
•
•
•
Synopsis of Window Function Syntax (page V-137)
Window Function Order of Evaluation (page V-138)
Numbering Window Functions (page V-139)
LEAD and LAG functions (page V-145)
Aggregate Window Functions (page V-146)
Deprecated Behavior (page V-154)
Window Function Known Issues (page V-155)
Example queries appear throughout the chapter.
Synopsis of Window Function Syntax
Invoking a window function has the following common syntax:
SELECT function( arg )
OVER ( PARTITION BY partition_expression [ , ... ]
ORDER BY order_expression [ ASC | DESC ] [ NULLS { FIRST | LAST } ]
[ ,... ]
)
FROM ...
where
•
•
•
function is the name of the window function;
arg is replaced with zero or more arguments to the function, as explained in the function descriptions below; and the
OVER
clause defines the partitions (sets) of rows the window function operates on, and the sorting of rows inside each partition; the clause consists of:
December 14, 2011 Aster Data proprietary and confidential V--137
Window Function Order of Evaluation Aster Data proprietary and confidential
•
• a PARTITION BY clause whose partition_expression is used to group rows into partitions (rows that evaluate equally for this expression are considered a partition); and/or an ORDER BY clause whose order_expression provides the sorting criteria and whose
optional parameters such as ASC further specify the sorting behavior. See “ORDER BY
Clause in SELECT” on page V-80 for details. The default sorting behavior is “ASC
NULLS LAST”.
Window function behavior is defined largely by the PARTITION BY and ORDER BY clauses in the OVER clause, which group and sort the input rows consumed by the window function. A partition is defined as all the rows for which the PARTITION BY expression evaluates to the same value. Each partition is sorted according to the ORDER BY clause (if present). The window function is then computed over each partition, considering each row in order and returning an output value for each row. Because window functions are computed on a per-row basis, the number of rows is not changed by using a window function. The OVER clause does not determine the ordering of output rows.
Important!
Window functions themselves provide no guarantee of the ordering of output
rows. The ORDER BY subclause of the OVER clause does not determine the ordering of output rows. To sort output rows, the query must have a query-wide ORDER BY clause in
addition to those used in any window functions. For details, see “Window Function Example
4: Output Row Ordering” on page V-142 .
Certain subclauses of the OVER clause may be required or optional, depending on the type of window function you are using:
•
•
•
The PARTITION BY clause is optional, but using one is strongly recommended. If no
PARTITION BY clause is present, the entire input relation is considered to be one partition.
See the warning in
ORDER BY without PARTITION BY (page V-156) .
The ORDER BY clause is required if the function is a numbering window function, and
optional otherwise. See Numbering Window Functions (page V-139) .
If your window function is an aggregate window function, then the OVER clause can optionally include a ROWS or RANGE clause that defines a window frame (not shown in
the syntax synopsis above), as explained in “Window Frame Syntax” on page V-147 .
Window Function Order of Evaluation
From the point of view of the person querying the database, window functions are evaluated
after all filtering, grouping, and aggregation is done. This means that a window function can
SELECT clause except another window function. (That is, you may not nest window functions.)
Aster Database-supported window functions may be divided broadly into three categories:
•
•
•
numbering window functions, e.g., RANK(), DENSE_RANK(), and ROW_NUMBER()
aggregate window functions, e.g. AVG(), SUM(), COUNT(). All SQL aggregates supported
in Aster Database may be used as window functions. (See “Aggregate Functions” on page V-130 .)
lead/lag window functions, which take as input an expression evaluated at a specified offset ahead of or behind the current row, respectively.
V--138 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Numbering Window Functions
The syntax and behavior of these three categories of functions differs slightly, so we will present each independently below. Examples of window function usage may be found throughout this section.
For all examples in this section we will assume the following relation, the employees
table:
Table "public.employees"
Column | Type | Modifiers
--------+---------+-----------
empnum | integer |
dept | integer |
salary | integer |
age | integer |
Table Type: fact
Distribution Key: empnum
Compression Level: none
The employees
table contains:
SELECT * FROM employees;
empnum | dept | salary | age
--------+------+--------+-----
3 | 100 | 42000 | 23
11 | 100 | 50000 | 65
5 | 101 | 56000 | 32
7 | 101 | 122345 | 87
1 | 100 | 50010 | 27
9 | 100 | 48765 | 33
4 | 233 | 130000 | 55
6 | 100 | 49333 | 44
8 | 100 | 50000 | 34
2 | 101 | 45000 | 30
10 | 101 | 387999 | 32
(11 rows)
Numbering Window Functions
The numbering window functions are ROW_NUMBER(), RANK(), and DENSE_RANK().
All numbering window functions require an ORDER BY expression within the OVER clause.
The numbering window functions do not require or allow any function arguments.
ROW_NUMBER()
The row number function is very straightforward. It applies a sequential row number, starting at
1, to each row in a partition. The ordering of the rows is required.
The tie-breaker behavior is as follows: Rows that compare as equal in the sort order will be sorted arbitrarily within the scope of the tie, and all rows will be given unique row numbers.
RANK()
The RANK() function assigns the current row-count number as the row’s rank, provided the row does not sort as equal (tie) with another row. The tie-breaker behavior is as follows: Rows that
December 14, 2011 Window Functions V--139
Numbering Window Functions Aster Data proprietary and confidential compare as equal in the sort order are sorted arbitrarily within the scope of the tie, and the sorted-as-equal rows get the same rank number.
When RANK() increments the rank number, it sets it to the current count of the current row as if the rank had increased by one with every row ranked so far. As a result, a gap appears in the rank sequence immediately after any group of equally sorted rows. See the example,
Function Example 2: RANK()” on page V-140
.
DENSE_RANK()
DENSE_RANK() behaves like the RANK() function, except that it never places gaps in the rank sequence. The tie-breaker behavior is the same as that of RANK(), in that the sorted-as-equal rows receive the same rank. With DENSE_RANK(), however, the next row after the set of
equally ranked rows gets a rank 1 higher than preceding tied rows. See the example, “Window
Function Example 3: DENSE_RANK()” on page V-141 .
Numbering Window Function Examples
The following examples demonstrate the differences between the numbering window functions as well as highlight some other features of window functions in general.
Window Function Example 1: ROW_NUMBER()
Append a row_number
to each row, partitioning by department and ordering by age.
SELECT
empnum, dept, salary, age,
ROW_NUMBER() OVER
(
PARTITION BY dept
ORDER BY age
)
AS row_number
FROM employees;
empnum | dept | salary | age | row_number
--------+------+--------+-----+------------
2 | 101 | 45000 | 30 | 1
5 | 101 | 56000 | 32 | 2
10 | 101 | 38799 | 32 | 3
7 | 101 | 122345 | 87 | 4
4 | 233 | 130000 | 55 | 1
3 | 100 | 42000 | 23 | 1
1 | 100 | 50010 | 27 | 2
9 | 100 | 48765 | 33 | 3
8 | 100 | 50000 | 34 | 4
6 | 100 | 49333 | 44 | 5
11 | 100 | 50000 | 65 | 6
(11 rows)
----------------------------------------------
Window Function Example 2: RANK()
Append a rank to each row, partitioning by department and ordering by age.
SELECT
empnum, dept, salary, age,
V--140 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Numbering Window Functions
RANK() OVER
(
PARTITION BY dept
ORDER BY age
)
AS rank
FROM employees;
empnum | dept | salary | age | rank
--------+------+--------+-----+------
2 | 101 | 45000 | 30 | 1
5 | 101 | 56000 | 32 | 2
10 | 101 | 38799 | 32 | 2
7 | 101 | 122345 | 87 | 4
4 | 233 | 130000 | 55 | 1
3 | 100 | 42000 | 23 | 1
1 | 100 | 50010 | 27 | 2
9 | 100 | 48765 | 33 | 3
8 | 100 | 50000 | 34 | 4
6 | 100 | 49333 | 44 | 5
11 | 100 | 50000 | 65 | 6
(11 rows)
Above, we see that in Department 101, employees number 5 and 10 share the same age and therefore the same rank. Notice that this tie results in a gap in the rank values between rank 2 and rank 4. The results of RANK() are allowed to have such holes, because rank is assigned based on the algorithm described in
.
Window Function Example 3: DENSE_RANK()
Append a dense rank to each row, partitioning by department and ordering by salary.
SELECT
empnum, dept, salary, age,
DENSE_RANK() OVER
(
PARTITION BY dept
ORDER BY salary
)
AS dense_rank
FROM employees;
empnum | dept | salary | age | dense_rank
--------+------+--------+-----+------------
10 | 101 | 38799 | 32 | 1
2 | 101 | 45000 | 30 | 2
5 | 101 | 56000 | 32 | 3
7 | 101 | 122345 | 87 | 4
4 | 233 | 130000 | 55 | 1
3 | 100 | 42000 | 23 | 1
9 | 100 | 48765 | 33 | 2
6 | 100 | 49333 | 44 | 3
8 | 100 | 50000 | 34 | 4
11 | 100 | 50000 | 65 | 4
1 | 100 | 50010 | 27 | 5
(11 rows)
This time we order by salary rather than age, so that the tie occurs in Dept. 100. Here, employees number 8 and 11 share the same salary and therefore the same rank. Notice that this tie results in no gap in the rank values: employees 8 and 11 share rank 4, and the next rank value is 5.
December 14, 2011 Window Functions V--141
Numbering Window Functions Aster Data proprietary and confidential
This is the difference between DENSE_RANK() and RANK(): The DENSE_RANK() function does not put gaps in the series of rank values. See
“DENSE_RANK()” on page V-140 .
Window Function Example 4: Output Row Ordering
This example demonstrates two things:
•
• that each window function can use its own, unique ORDER BY clause; and that the ordering of output rows is unpredictable unless you add an ORDER BY clause after the FROM clause:
SELECT
empnum, dept, salary, age,
ROW_NUMBER() OVER
(
PARTITION BY dept
ORDER BY age
)
AS row_number,
RANK() OVER
(
PARTITION BY dept
ORDER BY age
)
AS rank,
DENSE_RANK() OVER
(
PARTITION BY dept
ORDER BY salary
)
AS dense_rank
FROM employees;
empnum | dept | salary | age | row_number | rank | dense_rank
--------+------+--------+-----+------------+------+------------
2 | 101 | 45000 | 30 | 1 | 1 | 1
5 | 101 | 56000 | 32 | 2 | 2 | 2
7 | 101 | 122345 | 87 | 4 | 4 | 3
10 | 101 | 387999 | 32 | 3 | 2 | 4
4 | 233 | 130000 | 55 | 1 | 1 | 1
3 | 100 | 42000 | 23 | 1 | 1 | 1
9 | 100 | 48765 | 33 | 3 | 3 | 2
6 | 100 | 49333 | 44 | 5 | 5 | 3
8 | 100 | 50000 | 34 | 4 | 4 | 4
11 | 100 | 50000 | 65 | 6 | 6 | 4
1 | 100 | 50010 | 27 | 2 | 2 | 5
(11 rows)
In the query output above, we see two things:
•
•
Different window functions in the same query need not have the same ordering clause. They also need not have the same partitioning clause, as we’ll show in Example 5.
Window functions themselves provide no guarantee of the ordering of output rows. In the query output above, notice how the values in the rank
and row_number
columns are no longer ordered. To sort output, the query must include an ORDER BY clause after the
FROM clause.
V--142 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Numbering Window Functions
Window Function Example 5: Multiple RANK()s
Append the rank of salaries, partitioned by department, and the rank of salaries, partitioned by age.
SELECT
empnum, dept, salary, age,
RANK() OVER
(
PARTITION BY dept
ORDER BY salary
)
AS rank_in_dept,
RANK() OVER
(
PARTITION BY age
ORDER BY salary
)
AS rank_in_age_group
FROM employees;
empnum | dept | salary | age | rank_in_dept | rank_in_age_group
--------+------+--------+-----+--------------+-------------------
1 | 100 | 50010 | 27 | 6 | 1
3 | 100 | 42000 | 23 | 1 | 1
4 | 233 | 130000 | 55 | 1 | 1
7 | 101 | 122345 | 87 | 3 | 1
9 | 100 | 48765 | 33 | 2 | 1
11 | 100 | 50000 | 65 | 4 | 1
6 | 100 | 49333 | 44 | 3 | 1
2 | 101 | 45000 | 30 | 1 | 1
5 | 101 | 56000 | 32 | 2 | 1
10 | 101 | 387999 | 32 | 4 | 2
8 | 100 | 50000 | 34 | 4 | 1
(11 rows)
As we see above, two window functions in the same query need not have the same partitioning
clause.
Window Function Example 6: Attributes
Window functions can use attributes that are available but not present in the SELECT list.
SELECT
empnum,
dept AS department,
salary,
RANK() OVER
(
PARTITION BY dept
ORDER BY age
)
AS age_rank_in_department
FROM employees;
empnum | department | salary | age_rank_in_department
--------+------------+--------+------------------------
2 | 101 | 45000 | 1
5 | 101 | 56000 | 2
10 | 101 | 387999 | 2
7 | 101 | 122345 | 4
December 14, 2011 Window Functions V--143
Numbering Window Functions Aster Data proprietary and confidential
4 | 233 | 130000 | 1
3 | 100 | 42000 | 1
1 | 100 | 50010 | 2
9 | 100 | 48765 | 3
8 | 100 | 50000 | 4
6 | 100 | 49333 | 5
11 | 100 | 50000 | 6
(11 rows)
The window function in this example orders by age (an attribute that is available in the input, but not included in the SELECT list).
Window Function Example 7: Expressions, Improper Use
You cannot refer to a window function from another expression in the SELECT:
SELECT empnum,
dept AS department,
salary,
RANK() OVER
(
PARTITION BY dept
ORDER BY salary
)
AS salary_rank,
salary_rank - 1
FROM employees;
ERROR: column "salary_rank" does not exist
Above, when we try to use salary_rank in a separate expression, it fails.
Window Function Example 8: Expressions, Proper Use
You can use window functions in expressions:
SELECT
empnum,
dept AS department,
salary,
RANK() OVER
(
PARTITION BY dept
ORDER BY salary
) - 1
AS salary_rank
FROM employees
ORDER BY department, salary;
empnum | department | salary | salary_rank
--------+------------+--------+-------------
3 | 100 | 42000 | 0
9 | 100 | 48765 | 1
6 | 100 | 49333 | 2
11 | 100 | 50000 | 3
8 | 100 | 50000 | 3
1 | 100 | 50010 | 5
2 | 101 | 45000 | 0
5 | 101 | 56000 | 1
7 | 101 | 122345 | 2
10 | 101 | 387999 | 3
V--144 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential LEAD and LAG functions
4 | 233 | 130000 | 0
(11 rows)
Above, we have written a query similar to that shown in Example 7, but this time we perform the subtraction operation directly on the window function, which is the proper usage.
LEAD and LAG functions
LEAD and LAG are functions that can be used to evaluate an expression at a constant offset from the current row. The offset is expressed as the count of rows ahead of or behind the current row in the sort order of the partition.
The partitioning and sorting syntax is the same as that of other window functions -- there is an
OVER clause with PARTITION BY and ORDER BY expressions -- but in this case the ORDER
BY clause is required and three additional arguments are required: an SQL expression, an offset, and a default value. As with numbering window functions, if two or more rows sort as equals
(tie) in the sort order, the function arbitrarily sorts the sorted-as-equal rows.
Syntax
The syntax is
LEAD(sql_expression, offset, default) OVER( ... )
LAG(sql_expression, offset, default) OVER( ... ) where the arguments are
•
•
•
sql_expression: an SQL expression that retrieves the desired value. This is typically just the name of a column, but it can be any expression that could appear in the SELECT clause except for expressions that contain window functions. This may also be an alias.
offset: a positive (non zero) integer indicating the number of rows to count back or forward from the current row to retrieve the desired row.
default: the value to be used if the lead or lag offset points to a location outside the bounds of the partition. It must be of the same type as the sql_expression’s return value.
LEAD/LAG Examples
Window Function Example 9: LEAD()
Below, we compute the difference between an employee's salary and that of the next employee in the sort order (which will be the next older employee, or one whose age is the same):
SELECT
dept, empnum, salary, age,
salary - LEAD(salary, 1, 0) OVER
(
ORDER BY age ASC
)
AS salary_diff
FROM employees;
dept | empnum | salary | age | salary_diff
------+--------+--------+-----+-------------
100 | 3 | 42000 | 23 | -8010
100 | 1 | 50010 | 27 | 5010
December 14, 2011 Window Functions V--145
Aggregate Window Functions Aster Data proprietary and confidential
101 | 2 | 45000 | 30 | -342999
101 | 10 | 387999 | 32 | 331999
101 | 5 | 56000 | 32 | 7235
100 | 9 | 48765 | 33 | -1235
100 | 8 | 50000 | 34 | 667
100 | 6 | 49333 | 44 | -80667
233 | 4 | 130000 | 55 | 80000
100 | 11 | 50000 | 65 | -72345
101 | 7 | 122345 | 87 | 122345
(11 rows)
In this example we see the LEAD window function in action. The expression
LEAD(salary,
1, 0)
tells LEAD() to evaluate the expression salary on the row that is positioned one row
following the current row. If there is no such row (as is the case on the last row of the partition or relation), then the default value of 0 is used.
Window Function Example 10: LAG()
Compute the difference between an employee’s salary and that of the next employee in the sort order (which will be the next younger employee, or one whose age is the same):
SELECT
dept, empnum, salary, age,
salary - LAG(salary, 1, 0) OVER
(
ORDER BY age ASC
)
AS salary_diff
FROM employees;
dept | empnum | salary | age | salary_diff
------+--------+--------+-----+-------------
100 | 3 | 42000 | 23 | 42000
100 | 1 | 50010 | 27 | 8010
101 | 2 | 45000 | 30 | -5010
101 | 10 | 387999 | 32 | 342999
101 | 5 | 56000 | 32 | -331999
100 | 9 | 48765 | 33 | -7235
100 | 8 | 50000 | 34 | 1235
100 | 6 | 49333 | 44 | -667
233 | 4 | 130000 | 55 | 80667
100 | 11 | 50000 | 65 | -80000
101 | 7 | 122345 | 87 | 72345
(11 rows)
In this example we see the LAG() window function in action. The expression LAG(salary,
1, 0) means to evaluate the expression salary on the row that is positioned one row preceding the current row. If there is no such row (as is the case on the first row of the partition or relation), then the default value of 0 is used.
Aggregate Window Functions
Any of the SQL aggregates (such as AVG(), COUNT(), MAX(), MIN() , and SUM() ) may be used as an aggregate window function by appending an OVER clause to the aggregate
window function in the SELECT clause. (See “Aggregate Functions” on page V-130
for information on the aggregates.)
V--146 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Aggregate Window Functions
Unlike LEAD, LAG, and the numbering window functions, the SQL aggregates do not require the presence of an ORDER BY expression in the OVER clause. Therefore, the OVER clause may be empty, it may contain both a PARTITION BY and an ORDER BY expression, or it may contain just one of the two. (However, please note that if your table contains more than a small amount of data, Aster Data does not recommend using ORDER BY without a PARTITION BY
clause. See “Window Function Known Issues” on page V-155 .)
The OVER clause for an aggregate window function may also include a window frame specification. The window frame defines what part of the partition to include in the aggregated value. An example is a running SUM(), which is the sum of all values in the partition so far, including the current row. If no window frame is specified in the OVER clause, a default window frame is used. The particular default window frame that is used depends on the presence or absence of an ORDER BY expression in the OVER clause. More on that later.
In this section we will first describe the window frame syntax and semantics. Then we will present the default window frame semantics for aggregate window functions specified without explicit window frames.
Window Frame Syntax
A window frame specification (a ROWS clause or a RANGE clause) may appear within the
OVER clause of an aggregate window function after the PARTITION BY and ORDER BY expressions. The syntax is
SELECT
aggregate_function( arg )
OVER
(
PARTITION BY partition_expression [ , ... ]
ORDER BY order_expression [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [ , ... ]
[window_frame]
)
FROM ...
where
•
•
•
•
aggregate_function is function name and arg is its argument, (typically a column name);
partition_expression is a clause that groups rows into partitions (see
Function Syntax” on page V-137 );
order_expression, is an expression that sorts rows in each partition; and
window_frame is clause specifying the beginning and end of the set of rows the aggregate window function operates on. This clause uses the syntax shown below.
For row-based frames, the window frame syntax is:
December 14, 2011 Window Functions V--147
Aggregate Window Functions
For range-based frames, the window frame syntax is:
Aster Data proprietary and confidential
The valid endpoint specifications are:
•
•
•
•
UNBOUNDED PRECEDING
: The beginning of the partition.
n PRECEDING
: A fixed, unsigned number, n, of rows preceding or a range of values less than, the current row, given a ROWS or RANGE window type, respectively.
CURRENT ROW
: The current row being processed.
n FOLLOWING
: A fixed, unsigned number, n, of rows following, or a range of values less than, the current row, given a ROWS or RANGE window type, respectively.
UNBOUNDED FOLLOWING
: The end of the partition.
•
See the usage examples in the next section.
Window Frame Requirements
It is required that the left end point precede or equal the right end point. The two end points may also not be both
UNBOUNDED PRECEDING
or both
UNBOUNDED FOLLOWING
.
Optionally, only one end point may be specified. If this is the case, then the
CURRENT ROW
is implicitly added as the other end point specification on either the left or right side of the window so as to produce as valid window frame.
Valid Examples
Examples of valid window frames are:
ROWS BETWEEN 5 PRECEDING and 2 PRECEDING
ROWS BETWEEN 5 PRECEDING AND 5 PRECEDING
ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
ROWS BETWEEN CURRENT ROW AND CURRENT ROW
ROWS BETWEEN CURRENT ROW AND 2 FOLLOWING
ROWS BETWEEN 2 FOLLOWING AND 2 FOLLOWING
ROWS BETWEEN 2 FOLLOWING AND 5 FOLLOWING
ROWS BETWEEN UNBOUNDED PRECEDING AND 2 PRECEDING
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
ROWS BETWEEN UNBOUNDED PRECEDING AND 5 FOLLOWING
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
ROWS BETWEEN 2 PRECEDING AND UNBOUNDED FOLLOWING
ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING
ROWS BETWEEN 4 FOLLOWING AND UNBOUNDED FOLLOWING
ROWS UNBOUNDED PRECEDING
ROWS 5 PRECEDING
ROWS CURRENT ROW
ROWS 5 FOLLOWING
ROWS UNBOUNDED FOLLOWING
Invalid Examples
Examples of invalid window frames:
V--148 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Aggregate Window Functions
ROWS BETWEEN 2 PRECEDING AND 5 PRECEDING
ROWS BETWEEN CURRENT ROW AND 2 PRECEDING
ROWS BETWEEN 2 FOLLOWING AND CURRENT ROW
ROWS BETWEEN 5 FOLLOWING AND 2 FOLLOWING
ROWS BETWEEN UNBOUNDED FOLLOWING AND CURRENT ROW
ROWS BETWEEN CURRENT ROW AND UNBOUNDED PRECEDING
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED PRECEDING
ROWS BETWEEN UNBOUNDED FOLLOWING AND UNBOUNDED FOLLOWING
ORDER BY Required
Note that if there is no ORDER BY clause present, the only allowed frame is ROWS BETWEEN
UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING , that is, a frame encompassing the entire partition. All other frames have a moving endpoint which requires ordered input.
Window Frame Types: ROWS vs. RANGE
Two types of window frames are supported for aggregate window functions: ROWS-based frames and RANGE-based frames. The two window frame types have important differences in semantics.
A ROWS-based window frame applied to an aggregate window function computes the aggregate one row (record) at a time. The implication is that if two rows have equal ordering, the tie is broken arbitrarily, and one of the rows is added to the aggregate before the other.
Consider the following example where we compute a running average of age when the employees are sorted by salary. There are two employees who make 50,000, and each of those rows is aggregated into the running average independently.
Window Function Example 11: Running AVG()
Calculating a cumulative moving average, or running average, provides a simple example of an aggregate window function that uses a ROWS-based window frame:
SELECT
empnum, dept, salary, age,
AVG(age) OVER
(
ORDER BY salary
ROWS UNBOUNDED PRECEDING
)
AS "Running Avg Age"
FROM employees ORDER BY salary;
empnum | dept | salary | age | Running Avg Age
--------+------+--------+-----+---------------------
3 | 100 | 42000 | 23 | 23.0000000000000000
2 | 101 | 45000 | 30 | 26.5000000000000000
9 | 100 | 48765 | 33 | 28.6666666666666667
6 | 100 | 49333 | 44 | 32.5000000000000000
8 | 100 | 50000 | 34 | 32.8000000000000000
11 | 100 | 50000 | 65 | 38.1666666666666667
1 | 100 | 50010 | 27 | 36.5714285714285714
5 | 101 | 56000 | 32 | 36.0000000000000000
7 | 101 | 122345 | 87 | 41.6666666666666667
4 | 233 | 130000 | 55 | 43.0000000000000000
10 | 101 | 387999 | 32 | 42.0000000000000000
(11 rows)
December 14, 2011 Window Functions V--149
Aggregate Window Functions Aster Data proprietary and confidential
Window Function Example 12: Moving AVG()
You can also define a ROWS-based frame using constant-offset endpoints relative to the
CURRENT ROW. An example of such a window frame is
ROWS BETWEEN 2 PRECEDING
AND 2 FOLLOWING
. This window frame represents a sliding window of five rows (two preceding, two following, and the current row) and is useful for computing a moving average.
In this example we compute the moving average salary using a window ordered by employee age and a sliding ROWS-based window.
SELECT
empnum, dept, salary, age,
AVG(salary) OVER
(
ORDER BY age
ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING
)
AS "Moving Avg Salary"
FROM employees ORDER BY age;
empnum | dept | salary | age | Moving Avg Salary
--------+------+--------+-----+---------------------
3 | 100 | 42000 | 23 | 45670.000000000000
1 | 100 | 50010 | 27 | 131252.250000000000
2 | 101 | 45000 | 30 | 116201.800000000000
10 | 101 | 387999 | 32 | 117554.800000000000
5 | 101 | 56000 | 32 | 117552.800000000000
9 | 100 | 48765 | 33 | 118419.400000000000
8 | 100 | 50000 | 34 | 66819.600000000000
6 | 100 | 49333 | 44 | 65619.600000000000
4 | 233 | 130000 | 55 | 80335.600000000000
11 | 100 | 50000 | 65 | 87919.500000000000
7 | 101 | 122345 | 87 | 100781.666666666667
(11 rows)
Here, the equal ranking of employee 10 and employee 5 is resolved arbitrarily, and the moving average is calculated for each row.
Window Function Example 13: Cumulative Running AVG()
A RANGE-based window frame applied to an aggregate window function handles rows with equal ordering differently than a ROWS-based window. In a RANGE-based window, such equal-ordered values are considered to have occurred together, and therefore all receive the same aggregate value. This is best illustrated with an example.
Below, we again compute the running average age, but this time we use a RANGE-based window frame.
SELECT
empnum, dept, salary, age,
AVG(age) OVER
(
ORDER BY salary
RANGE UNBOUNDED PRECEDING
)
AS "Running Avg Age"
V--150 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Aggregate Window Functions
FROM employees ORDER BY salary;
empnum | dept | salary | age | Running Avg Age
--------+------+--------+-----+---------------------
3 | 100 | 42000 | 23 | 23.0000000000000000
2 | 101 | 45000 | 30 | 26.5000000000000000
9 | 100 | 48765 | 33 | 28.6666666666666667
6 | 100 | 49333 | 44 | 32.5000000000000000
8 | 100 | 50000 | 34 | 38.1666666666666667
11 | 100 | 50000 | 65 | 38.1666666666666667
1 | 100 | 50010 | 27 | 36.5714285714285714
5 | 101 | 56000 | 32 | 36.0000000000000000
7 | 101 | 122345 | 87 | 41.6666666666666667
4 | 233 | 130000 | 55 | 43.0000000000000000
10 | 101 | 387999 | 32 | 42.0000000000000000
(11 rows)
Above, we see that the two employees with a salary of 50,000 are given the same average age because this query uses a RANGE-based window frame.
Important: See
“Limited Support for RANGE-Based Window Frames” on page V-156
for an explanation on the limits of RANGE-based window frames in this version of Aster Database.
The Default Window Frame
Specifying the window frame is optional, but for all aggregate window functions, a default window frame is used if you fail to specify a window frame. This default depends on the presence or absence of the ORDER BY expression(s) in the OVER clause.
•
•
If no frame is specified and the OVER clause contains an ORDER BY expression, then the default window frame is RANGE BETWEEN UNBOUNDED PRECEDING AND
CURRENT ROW. Essentially, this is a running aggregate in which rows that sort equally are treated according to RANGE semantics described above.
If no frame is specified and the OVER clause does not contain an ORDER BY expression, then the default window frame is ROWS BETWEEN UNBOUNDED PRECEDING AND
UNBOUNDED FOLLOWING, that is, the entire partition.
Window Function Example 14: Running SUM()
Below, our query omits the window frame definition:
SELECT
empnum,
dept AS department,
age,
salary,
SUM(salary) OVER
(
PARTITION BY dept ORDER BY age
)
AS running_sum_salary
FROM employees
ORDER BY department, age;
empnum | department | age | salary | running_sum_salary
--------+------------+-----+--------+--------------------
3 | 100 | 23 | 42000 | 42000
1 | 100 | 27 | 50010 | 92010
December 14, 2011 Window Functions V--151
Aggregate Window Functions Aster Data proprietary and confidential
9 | 100 | 33 | 48765 | 140775
8 | 100 | 34 | 50000 | 190775
6 | 100 | 44 | 49333 | 240108
11 | 100 | 65 | 50000 | 290108
2 | 101 | 30 | 45000 | 45000
5 | 101 | 32 | 56000 | 488999
10 | 101 | 32 | 387999 | 488999
7 | 101 | 87 | 122345 | 611344
4 | 233 | 55 | 130000 | 130000
(11 rows)
Note that the default window frame RANGE BETWEEN UNBOUNDED PRECEDING AND
CURRENT ROW is being used.
Window Function Example 15: ORDER BY SUM()
You can also use SQL aggregates inside the OVER clause, as shown in the ORDER BY clause, below:
SELECT
dept,
SUM(salary),
RANK() OVER
(
ORDER BY SUM(salary)
)
AS dept_salary_rank
FROM employees
GROUP BY dept;
dept | sum(salary) | dept_salary_rank
------+-------------+------------------
233 | 130000 | 1
100 | 290108 | 2
101 | 611344 | 3
(3 rows)
Note: In this example, the PARTITION BY clause has been omitted. This causes the window function to compute the window function over all data. There is a potential performance impact here as all data must be processed at one node. See
“ORDER BY without PARTITION BY” on page V-156 .
Window Function Example 16: SUM(SUM(n))
Window functions can compute aggregates of aggregates:
SELECT
dept,
SUM(salary),
SUM(SUM(salary)) OVER
(
ORDER BY SUM(salary)
)
AS dept_salary_running_sum
FROM employees
GROUP BY dept;
V--152 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Aggregate Window Functions
dept | sum(salary) | dept_salary_running_sum
------+--------------+-------------------------
233 | 130000 | 130000
100 | 290108 | 420108
101 | 611344 | 1031452
(3 rows)
Consistent Sort Behavior of Input Rows
Two (or more) window functions in the same query that use identical PARTITION BY and
ORDER BY clauses are processed over the same input ordering. This is both more efficient and required by the standard.
This is particularly important for ROWS-based window frames, because in such frames the ordering of sorted-as-equal rows (that is, rows that tie in the sort order) is important. This ensures that different window functions that use the same PARTITION BY and ORDER BY clauses will process the sorted-as-equal rows in the same order.
Warning: Rewrite When Using Specific Left Endpoint and
Unbounded Right Endpoint
Aggregate window function queries that use a specific left endpoint and an unbounded right endpoint represent a very important exception to the rule regarding consistent sort order.
Consider the following query:
SELECT
empnum,
dept AS department,
age,
salary,
SUM(salary) OVER
(
PARTITION BY dept
ORDER BY age
ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING
)
AS "following sum",
SUM(salary) OVER
(
PARTITION BY dept
ORDER BY age
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
)
AS "preceding sum"
FROM employees
ORDER BY department, age;
In the case where the left endpoint is not UNBOUNDED, but the right end point is
UNBOUNDED, Aster Database rewrites the window function and its ORDER BY expression to flip the window so that it is UNBOUNDED on the left side. This results in much more efficient processing, but does not guarantee that rows that sort equally will be processed in the same order here as they would in another ROWS-based window frame that uses the same PARTITION BY and ORDER BY clauses.
If your queries rely on the exact same ordering being used for a given PARTITION BY/ORDER
BY combination that you employ in multiple queries, then you must write an ORDER BY expression that guarantees no rows tie in the sort order (sort as equal).
December 14, 2011 Window Functions V--153
Repartitioning Performance for Window Functions and SQL-MapReduce Queries Aster Data proprietary and confidential
Repartitioning Performance for Window Functions and
SQL-MapReduce Queries
If you run a window function or SQL-MapReduce function and partition based on a column other than the declared DISTRIBUTE BY HASH key of the target table, then Aster Database uses the last of the columns listed in your PARTITION BY statement to repartition the data.
To get the best possible performance from your queries, you may have to rewrite them so that the desired partitioning column comes last in the PARTITION BY list.
Below is an example that uses a window function. This is equally applicable to SQL-MapReduce operators.
beehive=> \d foo
Table "public.foo"
Column | Type | Modifiers
--------+---------+-----------
a | integer |
b | integer |
c | integer |
Table Type:
fact
Distribution Key:
a
Compression Level:
none
SELECT SUM(a) OVER (PARTITION BY b, c ORDER BY b, c) FROM foo;
Since table foo's distribution key, "a", is not present in the PARTITION BY clause, Aster
Database will pick the last element "c" to repartition foo. However, it may so happen that repartitioning foo on "b" (rather than on "c") will lead to a more uniform distribution across the worker nodes.
In such a case, the user must rewrite the PARTITION BY clause, so that the query reads:
SELECT SUM(a) OVER (PARTITION BY c, b ORDER BY b, c) FROM foo;
Based on the rewritten query, Aster Database will pick "b" (the last element in the PARTITION
BY clause) as the expression to repartition the input rows. This leads to better distribution of foo's data and higher parallelism among the worker nodes.
Deprecated Behavior
In previous releases of Aster Database, window functions could refer to other SELECT clause expressions by their aliases as long as the aliased expression did not itself contain a window function. In order to address odd variable scoping and ambiguity issues and to move closer to the
SQL standard, this behavior has been deprecated since Aster Database version 4.5. In subsequent releases of Aster Database, the aliases will not be allowed within window function expressions.
In versions 4.5 and 4.6, the old, aliases-allowed behavior is still enabled by default, but can be disabled if needed. If you suspect that queries run on your Aster Database installation might include aliases in window functions, then, before you upgrade to a release subsequent to 4.6.1,
Aster Data encourages you to try running your query workload with the aliases-allowed behavior
V--154 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Window Function Known Issues disabled, as that behavior will not be supported in subsequent versions of Aster Database.
Contact Aster Data support if you wish to disable the behavior.
Examples of the Old Aliasing Behavior
Example That Uses an Alias in a Window Function (Deprecated)
A deprecated feature allows window functions to reference aliases from the same SELECT clause. Aster Data recommends that you do not refer to aliases in you window functions, because support for doing so will be dropped in an upcoming release.
SELECT
empnum, dept AS department, salary,
RANK() OVER
(
PARTITION BY department
ORDER BY age
)
AS age_rank_in_department
FROM employees;
empnum | department | salary | age_rank_in_department
--------+------------+--------+------------------------
2 | 101 | 45000 | 1
5 | 101 | 56000 | 2
10 | 101 | 387999 | 2
7 | 101 | 122345 | 4
4 | 233 | 130000 | 1
3 | 100 | 42000 | 1
1 | 100 | 50010 | 2
9 | 100 | 48765 | 3
8 | 100 | 50000 | 4
6 | 100 | 49333 | 5
11 | 100 | 50000 | 6
(11 rows)
The window function in this example partitions by department (an alias) and orders by age (an attribute that is available in the input, but not included in the SELECT list).
This behavior is deprecated and the use of the “department” alias will fail in future versions of
Aster Database. Instead, the query, when run in those versions, must use “dept” or
“employees.dept” within the window function.
Window Function Known Issues
There are a few issues to be aware of when using window functions in Aster Database:
COUNT(*)
COUNT(*) is currently not supported in a window function.
December 14, 2011 Window Functions V--155
Window Function Known Issues Aster Data proprietary and confidential
ORDER BY without PARTITION BY
Omitting a PARTITION BY expression but including an ORDER BY expression may result in poor performance. This is because omitting the PARTITION BY clause means that the entire input is considered one partition. Performing an ORDER BY without a PARTITION BY means the entire input must be sorted as a single set, which is an expensive operation on an MPP system such as Aster Database. When possible, avoid such window functions over very large data sets.
Use in SELECT Clause Only
Window functions may only appear in the SELECT clause.
No Support for WINDOW Clause
Aster Database does not support the WINDOW clause for naming windows.
Size Limit of Sliding Window Frames
Sliding window frames are currently limited to windows with a length of 1000 rows or less. If you require larger windows, please contact Aster Data Support.
Limited Support for RANGE-Based Window Frames
RANGE-based window frames with non-UNBOUNDED endpoints other than CURRENT ROW are currently not supported in Aster Database. In such a window frame, the constant value specifies a value range of the ORDER BY column rather than a fixed number of ROWS. Again,
this is NOT supported in Aster Database 4.6 and later.
V--156 Database SQL and Function Reference, version 4.6.2
aster data
V--4
Datatypes
•
•
•
•
•
•
•
•
•
•
Aster Database has a rich set of native datatypes available to users. This section explains each datatype and shows you how to work with each.
List of Supported Datatypes (page V-157)
Network Address Types (page V-172)
List of Supported Datatypes
The following table shows all of the built-in general-purpose datatypes. The specified aliases can also be used in lieu of the type names.
List of Types
Table 4-1 General Purpose Datatypes in Aster Database
Name Aliases Description bigint int8 bigserial bit [(n)] bit varying [(n)]
Boolean varbit bool
See page signed eight-byte integer
autoincrementing eight-byte integer fixed-length bit string
variable-length bit string
logical Boolean (true/false)
December 14, 2011 Aster Data proprietary and confidential V--157
List of Supported Datatypes Aster Data proprietary and confidential
Name Aliases Description See page bytea character varying [(n)] varchar [(n)] character [(n)] date double precision ip4 ip4range integer interval numeric [(p, s)] real serial smallint text time [(p)] [without time zone] time [(p)] with time zone timestamp [(p)]
[without time zone] timestamp [(p)] with time zone char [(n)] float, float8, float(n) int, int4 decimal [(p,s)] float4 int2 timetz timestamptz variable-length binary string variable-length character string
fixed-length character string
calendar date (year, month, day)
double precision floating-point number
IP address range of IP addresses signed four-byte integer
time interval
exact numeric of selectable precision
single precision floating-point number autoincrementing four-byte integer signed two-byte integer
variable-length character string time of day
time of day, including time zone
date and time
date and time, including time zone
Compatibility
The following types (or spellings thereof) are specified by SQL: bit bit varying boolean char character varying character varchar date double precision
V--158 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Numeric Types integer interval numeric decimal real smallint time (with or without time zone) timestamp (with or without time zone)
Each datatype has an external representation determined by its input and output functions. Many of the built-in types have obvious external formats. However, several types are either unique to
Aster Database, such as serial types, or have several possibilities for formats, such as the date and time types. Some of the input and output functions are not invertible. That is, the result of an output function may lose accuracy when compared to the original input.
Numeric Types
Numeric types consist of two-, four-, and eight-byte integers, four- and eight-byte floating-point numbers, and selectable-precision decimals.
Name smallint integer bigint numeric, numeric(p), numeric(p,s) real double precision serial bigserial
Aliases Storage
Size
Description Range See page int2 int, int4 int8 decimal float, float4, float8, float(n) serial4
2 bytes small-range integer -32768 to +32767
4 bytes usual choice for integer
-2147483648 to
+2147483647
8 bytes large-range integer -9223372036854775808 to
9223372036854775807
Variable user-specified precision, exact
4 bytes variable-precision, inexact no limit
6 decimal digits precision
8 bytes variable-precision, inexact
15 decimal digits precision
1 to 2147483647 serial8
4 bytes autoincrementing integer
8 bytes autoincrementing bigint
1 to
9223372036854775807
Integer Types
The types smallint
, integer
, and bigint
store whole numbers, that is, numbers without fractional components, of various ranges. Attempts to store values outside of the allowed range will result in an error.
The type integer
is the usual choice, as it offers the best balance between range, storage size, and performance. The smallint
type is generally only used if disk space is at a premium. The
December 14, 2011 Datatypes V--159
Numeric Types Aster Data proprietary and confidential bigint
type should only be used if the integer range is not sufficient, because the latter is definitely faster.
SQL only specifies the integer types integer
(or int
), smallint
, and bigint
. The type names int2
, int4
, and int8
are extensions.
Arbitrary Precision Numbers
The type numeric
can store numbers with up to 1000 digits of precision and perform calculations exactly. It is especially recommended for storing monetary amounts and other quantities where exactness is required. However, arithmetic on numeric values is very slow compared to the integer types, or to the floating-point types described in the next section.
In what follows we use these terms: The scale of a numeric
is the count of decimal digits in the fractional part, to the right of the decimal point. The precision of a numeric
is the total count of significant digits in the whole number, that is, the number of digits to both sides of the decimal point. So the number 23.5141 has a precision of 6 and a scale of 4. Integers can be considered to have a scale of zero.
Both the maximum precision and the maximum scale of a numeric
column can be configured.
To declare a column of type numeric
use the syntax:
NUMERIC(precision, scale)
The precision must be positive, the scale zero or positive. Alternatively:
NUMERIC(precision) selects a scale of 0. Specifying:
NUMERIC without any precision or scale creates a column in which numeric values of any precision and scale can be stored, up to the implementation limit on precision. A column of this kind will not coerce input values to any particular scale, whereas numeric columns with a declared scale will coerce input values to that scale.
If the scale of a value to be stored is greater than the declared scale of the column, the system will round the value to the specified number of fractional digits. Then, if the number of digits to the left of the decimal point exceeds the declared precision minus the declared scale, an error is raised.
Numeric values are physically stored without any extra leading or trailing zeroes. Thus, the declared precision and scale of a column are maximums, not fixed allocations. (In this sense the numeric type is more akin to varchar(n) than to char(n).) The actual storage requirement is two bytes for each group of four decimal digits, plus five to eight bytes overhead.
In addition to ordinary numeric values, the numeric type allows the special value NaN, meaning
"not-a-number". Any operation on NaN yields another NaN. When writing this value as a constant in an SQL command, you must put quotes around it, for example UPDATE table SET x
= 'NaN'. On input, the string NaN is recognized in a case-insensitive manner.
Note: In most implementations of the "not-a-number" concept, NaN is not considered equal to any other numeric
value (including NaN). In order to allow numeric
values to be sorted and used in tree-based indexes, Aster Database treats NaN values as equal, and greater than all non-NaN values.
The types decimal
and numeric
are equivalent. Both types are part of the SQL standard.
V--160 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Numeric Types
Floating-Point Types
The datatypes real
and double precision
are inexact, variable-precision numeric types.
In practice, these types are usually implementations of IEEE Standard 754 for Binary
Floating-Point Arithmetic (single and double precision, respectively), to the extent that the underlying processor supports it.
Warning!
Floating point types are inexact. If you require exact storage and calculations (such as for monetary amounts), use the numeric
type instead.
Aster Database also supports the SQL-standard notations float
and float(p)
for specifying inexact numeric types. Declaring a datatype of float(p)
creates either a real
or double precision
column) depending on the value of p. Here, p
specifies the minimum acceptable precision in binary digits. For float(1)
through float(24)
, the real datatype is used. For float
(with no p specified) and for float(25)
through float(53)
, the double precision datatype is used. Values of p
outside the allowed range draw an error.
These types are called “inexact” because some values cannot be converted exactly to the internal format and are stored as approximations, so that storing and printing back out a value might show slight discrepancies. Managing these errors and how they propagate through calculations is the subject of an entire branch of mathematics and computer science and will not be discussed further here, except for the following points:
•
•
If you require exact storage and calculations (such as for monetary amounts), use the numeric
type instead.
If you want to do complicated calculations with these types for anything important, especially if you rely on certain behavior in boundary cases (infinity, underflow), you should evaluate the implementation carefully.
Comparing two floating-point values for equality might or might not work as expected.
•
On most platforms, the real
type has a range of at least 1.0 x 10
-37
to 1.0 x 10
37
with a precision of at least 6 decimal digits. The double precision
type typically has a range of approximately 1.0 x 10
-307
to 1.0 x 10
308
with a precision of at least 15 digits. Values that are too large or too small will cause an error. Rounding might take place if the precision of an input number is too high. Numbers too close to zero that are not representable as distinct from zero will cause an underflow error.
In addition to ordinary numeric values, the floating-point types have several special values:
Infinity
-Infinity
NaN
These represent the IEEE 754 special values "infinity", "negative infinity", and "not-a-number", respectively. (On a machine whose floating-point arithmetic does not follow IEEE 754, these values will probably not work as expected.) When writing these values as constants in an SQL command, you must put quotes around them, for example
UPDATE table SET x =
'Infinity'
. On input, these strings are recognized in a case-insensitive manner.
Note: IEEE754 specifies that NaN should not compare as equal to any other floating-point value
(including NaN). In order to allow floating-point values to be sorted and used in tree-based indexes, Aster Database treats NaN values as equal, and greater than all non-NaN values.
December 14, 2011 Datatypes V--161
Numeric Types Aster Data proprietary and confidential
Serial Types
The datatypes serial
(also aliased as serial4
) and bigserial
(also aliased as serial8
) are not true types, but merely a notational convenience for setting up unique identifier columns
(similar to the AUTO_INCREMENT property supported by some other databases).
Local and Global
Due to its unique distributed architecture, Aster Database supports two notions of serial types: global
and local
:
•
•
A serial global
type ensures the serial
property across all nodes in the system.
A serial local
type ensures the serial
property local to each partition of data (that is, local to each v-worker). The local
modifier is not applicable to dimension tables created without distribution keys.
For tables with distribution keys, Aster Database does not support having serial global columns. For such tables, only serial local
type is supported. For such tables, the value of the distribution column taken in conjunction with the value of the serial local
column provides the equivalent of a serial global
property.
Table 4-2 Compatibility of serial types with Aster Database table types
Table Type Allowed Serial Type
Fact table
Dimension table with DISTRIBUTE BY HASH
Dimension table without
DISTRIBUTE BY HASH
SERIAL LOCAL
SERIAL LOCAL
SERIAL GLOBAL
Creating Columns of Type Serial
You can create a column of serial global
type as:
CREATE DIMENSION TABLE mydimtable (
columna SERIAL GLOBAL,
columnb VARCHAR
);
A column of bigserial local
type can be created as:
CREATE FACT TABLE myfacttable
(
columna BIGSERIAL LOCAL,
columnb VARCHAR
)
DISTRIBUTE BY HASH(columnb);
Each of the above examples creates an integer
or a bigint
column, respectively, and arranges for its default values to be assigned from a sequence generator. A NOT NULL constraint is applied to ensure that a null value cannot be explicitly inserted, either.
Automatic Numbering
When inserting rows, you can have Aster Database automatically set the serial value for each row. to the next value in the serial sequence. To do this, you must excluding the column from the
V--162 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Character Types list of columns in the INSERT statement. For example, using the myfacttable
we defined above:
INSERT INTO myfacttable (columnb) VALUES ('New Moon');
You cannot simply omit the value for the serial column from your insert statement. For example, this will fail:
INSERT INTO myfacttable VALUES ('New Moon');
Primary Key Constraint Not Recommended on Serial Columns
For distributed tables, you cannot impose a primary key constraint on a serial-type column.
For non-distributed tables, Aster Data does not recommend imposing a primary key constraint on a serial-type column. The database does not prevent users from manually inserting values into the serial column, and, if a user does perform such manual insertions, it will render the table unable accept new rows whose serial value would conflict with the user-inserted serial value.
Actual Datatype of a Serial Column
When you declare a column of type serial
, it’s actual datatype is integer
. For bigserial
, the actual type is bigint
. Use bigserial
if you anticipate the use of more than 2
31
identifiers over the lifetime of the table.
The sequence created for a serial
column is automatically dropped when the owning column is dropped.
Character Types
Table 4-3 Supported character datatypes in Aster Database
Name Description character varying(n), varchar(n), varchar character(n), char(n), character, char text variable-length with limit – 1GB maximum length fixed-length, blank padded – 1GB maximum length variable - unlimited length
SQL defines two primary character types: character varying(n)
and character(n)
, where n
is a positive integer. Both of these types can store strings up to n characters in length.
An attempt to store a longer string into a column of these types will result in an error, unless the excess characters are all spaces, in which case the string will be truncated to the maximum length. If the string to be stored is shorter than the declared length, values of type character will be space-padded; values of type character varying will simply store the shorter string.
If one explicitly casts a value to character varying(n)
or character(n)
, then an over-length value will be truncated to n characters without raising an error. (This, too, is required by the SQL standard.)
The notations varchar(n)
and char(n)
are aliases for character varying(n)
and character(n)
, respectively. character
without length specifier is equivalent to character(1)
. If character varying
is used without length specifier, the type accepts strings of any size.
In addition, Aster Database provides the text
type, which stores strings of any length. Although the type text
is not in the SQL standard, several other SQL database management systems have it as well.
December 14, 2011 Datatypes V--163
Character Types Aster Data proprietary and confidential
Values of type character
are physically padded with spaces to the specified width n
, and are stored and displayed that way. However, the padding spaces are treated as semantically insignificant. Trailing spaces are disregarded when comparing two values of type character
, and they will be removed when converting a character value to one of the other string types.
Note that trailing spaces are semantically significant in character varying
and text values.
Storage Requirements
The storage requirement for a short string (up to 126 bytes) is 1 byte plus the actual string, which includes the space padding in the case of character
. Longer strings have 4 bytes overhead instead of 1. Long strings are compressed by the system automatically, so the physical requirement on disk might be less. Very long values are also stored in background tables so that they do not interfere with rapid access to shorter column values. In any case, the longest possible character string that can be stored is about 1 GB. (The maximum value that will be allowed for n in the datatype declaration is less than that. It wouldn't be very useful to change this because with multibyte character encodings the number of characters and bytes can be quite different anyway.
If you desire to store long strings with no specific upper limit, use text
or character varying
without a length specifier, rather than making up an arbitrary length limit.)
Tip for Using Character Types
There are no performance differences between these three types, apart from increased storage size when using the blank-padded type, and a few extra cycles to check the length when storing into a length-constrained column. While character(n)
has performance advantages in some other database systems, it has no such advantages in Aster Database. In most situations text
or character varying
should be used instead.
Examples
Examples using character types:
CREATE TABLE test1 (a character(4));
INSERT INTO test1 VALUES ('ok');
SELECT a, char_length(a) FROM test1;
a | char_length
------+-------------
ok | 2
CREATE TABLE test2 (b varchar(5));
INSERT INTO test2 VALUES ('ok');
INSERT INTO test2 VALUES ('good ');
INSERT INTO test2 VALUES ('too long');
ERROR: value too long for type character varying(5)
INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
SELECT b, char_length(b) FROM test2;
b | char_length
-------+-------------
ok | 2
good | 5
too l | 5
V--164 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Types
Date/Time Types
Aster Database supports the following date and time datatypes.
Table 4-4 Date and time datatypes supported in Aster Database
Name Storage
Size
Description Low Value timestamp [ (p) ] [ without time zone ] timestamp [ (p) ] with time zone interval date time [ (p) ] [ without time zone ] time [ (p) ] with time zone
8 bytes
8 bytes both date and
12 bytes time interval -178000000 years
4 bytes both date and time time, with time zone dates only
8 bytes times of day
12 bytes only times of day only, with time zone
4713 BC
4713 BC
4713 BC
00:00:00
High Value
5874897 AD
5874897 AD
178000000 years
5874897 AD
24:00:00
Resolution
1 microsecond /
14 digits
1 microsecond /
14 digits
1 microsecond /
14 digits
1 day
1 microsecond /
14 digits
00:00:00+1459 24:00:00-1459 1 microsecond /
14 digits
The datatypes time
and timestamp
accept an optional precision value p
which specifies the number of fractional digits retained in the seconds field. By default, there is no explicit bound on precision. The allowed range of p
is from 0 to 6 for the timestamp
type.
For the time
types, the allowed range of p
is from 0 to 6 when eight-byte integer storage is used, or from 0 to 10 when floating-point storage is used.
The type time with time zone
is defined by the SQL standard, but the definition exhibits properties which lead to questionable usefulness. In most cases, a combination of date
, time
, timestamp without time zone
, and timestamp with time zone
should provide a complete range of date/time functionality required by any application.
Aliases:
•
• timetz
is an alias for time with time zone timestamptz
is an alias for timestamp with time zone
Date/Time Input
Date and time input is accepted in almost any reasonable format, including ISO 8601,
SQL-compatible, and others. For some formats, ordering of month, day, and year in date input is ambiguous and there is support for specifying the expected ordering of these fields. Set the
DateStyle parameter to MDY to select month-day-year interpretation, DMY to select day-month-year interpretation, or YMD to select year-month-day interpretation.
Remember that any date or time literal input needs to be enclosed in single quotes, like text strings. SQL requires the following syntax: type [ (p) ] 'value' where p
in the optional precision specification is an integer corresponding to the number of fractional digits in the seconds field. Precision can be specified for time
and timestamp
. The
December 14, 2011 Datatypes V--165
Date/Time Types Aster Data proprietary and confidential
•
•
•
• allowed values are mentioned above. If no precision is specified in a constant specification, it defaults to the precision of the literal value.
We provide more details in these sections:
“Date Input Formats” on page V-166
“Time Input Formats” on page V-166
“Time Stamp Input Formats” on page V-167
Date Input Formats
Table 4-5 Examples of date inputs:
Date Result
January 8, 1999
1999-01-08
1/8/1999
1/18/1999
01/02/03
1999-Jan-08
Jan-08-1999
08-Jan-1999
99-Jan-08
08-Jan-99
Jan-08-99
19990108
990108
1999.008
J2451187
January 8, 99 BC unambiguous in any datestyle input mode
ISO 8601; January 8 in any mode (recommended format)
January 8 in MDY mode; August 1 in DMY mode
January 18 in MDY mode; rejected in other modes
January 2, 2003 in MDY mode; February 1, 2003 in
DMY mode; February 3, 2001 in YMD mode
January 8 in any mode
January 8 in any mode
January 8 in any mode
January 8 in YMD mode, else error
January 8, except error in YMD mode
January 8, except error in YMD mode
ISO 8601; January 8, 1999 in any mode
ISO 8601; January 8, 1999 in any mode year and day of year
Julian day year 99 before the Common Era
Time Input Formats
The time-of-day types are time [(p)] without time zone
and time [(p)] with time zone
. Writing just time
is equivalent to writing time without time zone
.
Valid input for these types consists of a time of day followed by an optional time zone. If a time zone is specified in the input for time without time zone, it is silently ignored. You can also specify a date but it will be ignored, except when you use a time zone name that involves a daylight-savings rule, such as America/New_York. In this case specifying the date is required in order to determine whether standard or daylight-savings time applies. The appropriate time zone offset is recorded in the time with time zone value.
V--166 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Date/Time Types
Table 4-6 Examples of time inputs:
Allowed Example Notes
04:05:06.789
04:05:06
04:05
040506
04:05 AM
04:05 PM
04:05:06.789-8
04:05:06-08:00
04:05-08:00
040506-08
04:05:06 PST
2003-04-12 04:05:06
America/New_York
ISO 8601
ISO 8601
ISO 8601
ISO 8601 same as 04:05; AM does not affect value same as 16:05; input hour must be <= 12
ISO 8601
ISO 8601
ISO 8601
ISO 8601 time zone specified by abbreviation time zone specified by full name
Table 4-7 Examples of time zone inputs:
Allowed Example Notes
PST
America/New_York
PST8PDT
-8:00
-800
-8 zulu z
Abbreviation (for Pacific Standard
Time)
Full time zone name
POSIX-style time zone specification
ISO-8601 offset for PST
ISO-8601 offset for PST
ISO-8601 offset for PST
Military abbreviation for UTC
Short form of zulu
Time Stamp Input Formats
Valid input for the time stamp types consists of a concatenation of a date and a time, followed by an optional time zone, followed by an optional AD or BC. (Alternatively, AD/BC can appear before the time zone, but this is not the preferred ordering.) Thus:
1999-01-08 04:05:06 and:
1999-01-08 04:05:06 -8:00 are valid values, which follow the ISO 8601 standard. In addition, the wide-spread format:
January 8 04:05:06 1999 PST is supported.
The SQL standard differentiates timestamp without time zone and timestamp with time zone literals by the presence of a "+" or "-". Hence, according to the standard,
TIMESTAMP '2004-10-19 10:23:54'
December 14, 2011 Datatypes V--167
Date/Time Types Aster Data proprietary and confidential is a timestamp without time zone
, while
TIMESTAMP '2004-10-19 10:23:54+02' is a timestamp with time zone
. Aster Database never examines the content of a literal string before determining its type, and therefore will treat both of the above as timestamp without time zone
. To ensure that a literal is treated as timestamp with time zone
, give it the correct explicit type:
TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
In a literal that has been decided to be timestamp without time zone, Aster Database will silently ignore any time zone indication. That is, the resulting value is derived from the date/time fields in the input value, and is not adjusted for time zone.
For timestamp with time zone
, the internally stored value is always in UTC (Universal
Coordinated Time, traditionally known as Greenwich Mean Time, GMT). An input value that has an explicit time zone specified is converted to UTC using the appropriate offset for that time zone. If no time zone is stated in the input string, then it is assumed to be in the time zone indicated by the system's timezone parameter, and is converted to UTC using the offset for the timezone zone.
Intervals
Interval values and interval-typed columns have the following properties:
Table 4-8 Interval datatype
Name Description interval
Time interval
Low Value
-178000000 years
High Value
178000000 years
Resolution
1 microsecond / 14 digits interval values can be written with the following syntax:
[@] quantity unit [quantity unit...] [direction]
Where:
quantity
is a number (possibly signed);
unit
is second
, minute
, hour
, day
, week
, month
, year
, decade
, century
, millennium
, or abbreviations or plurals of these units;
direction
can be ago
or empty. The at sign (
@
) is optional noise. The amounts of different units are implicitly added up with appropriate sign accounting.
Quantities of days, hours, minutes, and seconds can be specified without explicit unit markings.
For example, '
1 12:59:10
' is read the same as '
1 day 12 hours 59 min 10 sec
'.
Date/Time Output
The output format of the date/time types is the default of ISO 8601.
Example of ISO style date/time:
1997-12-17 07:37:16-08
V--168 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Boolean Types
Time Zones
Aster Database currently supports daylight-savings rules over the time period 1902 through 2038
(corresponding to the full range of conventional Unix system time). Times outside that range are taken to be in "standard time" for the selected time zone, no matter what part of the year they fall in.
Bit String Types
Bit strings are strings of 1's and 0's. They can be used to store or visualize bit masks. There are two SQL bit types: bit(n)
and bit varying(n)
, where n is a positive integer.
Values of type bit
must match the length n exactly; it is an error to attempt to store shorter or longer bit
strings. Fields of type bit varying
are of variable length up to the maximum length n; longer strings are rejected. Writing bit
without a length is equivalent to bit(1)
, while bit varying
without a length specification means unlimited length.
Note: If you explicitly cast a bit-string value to bit(n)
, it will be truncated or zero-padded on the right to be exactly n bits, without raising an error. Similarly, if you explicitly cast a bit-string value to bit varying(n)
, it will be truncated on the right if it is more than n bits.
Example using the bit string types:
CREATE FACT TABLE testbit
(
a INT,
b BIT(3),
c BIT VARYING(5)
)
DISTRIBUTE BY HASH(a); beehive=> insert into testbit values (0, B'101', B'00'); beehive=> insert into testbit values (1, B'10', B'101');
ERROR: bit string length 2 does not match type bit(3) beehive=> insert into testbit values (1, B'10'::bit(3), B'101'); select * from testbit;
a | b | c
---+-----+-----
0 | 101 | 00
1 | 100 | 101
A bit string value requires 1 byte for each group of 8 bits, plus 5 or 8 bytes overhead depending on the length of the string.
Boolean Types
Aster Database provides the standard SQL type boolean
. A boolean
can have one of only two states: "true" or "false". A third state, "unknown", is represented by the SQL null value.
Allowed Boolean Values
Valid literal values for the "true" state are:
TRUE
't'
December 14, 2011 Datatypes V--169
Binary Types Aster Data proprietary and confidential
'true'
'y'
'yes'
'1'
For the "false" state, the following values can be used:
FALSE
'f'
'false'
'n'
'no'
'0'
Leading and trailing whitespace is ignored. Using the keywords TRUE and FALSE is preferred
(and SQL-compliant).
Examples
Examples using the Boolean type:
CREATE TABLE test1 (a boolean, b text);
INSERT INTO test1 VALUES (TRUE, 'sic est');
INSERT INTO test1 VALUES (FALSE, 'non est');
SELECT * FROM test1;
a | b
---+---------
t | sic est
f | non est
SELECT * FROM test1 WHERE a;
a | b
---+---------
t | sic est boolean
values are output using the letters t and f. boolean
uses 1 byte of storage.
Binary Types
The bytea
datatype allows storage of binary strings.
Table 4-9 Binary Datatypes
Name Storage Size bytea 1 or 4 bytes plus the actual binary string
Description variable-length binary string
A binary string is a sequence of octets (or bytes). Binary strings are distinguished from character strings by two characteristics:
•
•
Binary strings specifically allow storing octets of value zero and other "non-printable" octets
(usually, octets outside the range 32 to 126). Character strings disallow zero octets, and also disallow any other octet values and sequences of octet values that are invalid according to the database's selected character set encoding.
Operations on binary strings process the actual bytes, whereas the processing of character strings depends on locale settings. In short, binary strings are appropriate for storing data
V--170 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Binary Types that the programmer thinks of as "raw bytes", whereas character strings are appropriate for storing text.
Entering bytea Values
When entering bytea
values, octets of certain values must be escaped (but all octet values can be escaped) when used as part of a string literal in an SQL statement. In general, to escape an octet, it is converted into the three-digit octal number equivalent of its decimal octet value and
preceded by two backslashes. Table 4-10
shows the characters that must be escaped, and gives the alternative escape sequences where applicable.
Table 4-10 bytea Literal Escaped Octets
Decimal
Octet
Value
Description Escaped Input
Representation
0 zero octet
39
92
0 to 31 and
127 to 255 single quote backslash
"non-printable" octets
Example
E'\\000'
'''' or E'\\047'
SELECT
E'\\000'::bytea;
SELECT
E'\\047'::bytea;
E'\\\\' or E'\\134' SELECT
E'\\\\'::bytea;
E'\\xxx'
(octal value)
SELECT
E'\\001'::bytea;
Output
Representation
\000
'
\\
\001
The requirement to escape "non-printable" octets actually varies depending on locale settings. In some instances you can get away with leaving them unescaped. Note that the result in each of the examples in
was exactly one octet in length, even though the output representation of the zero octet and backslash are more than one character.
The reason that you have to write so many backslashes, as shown in Table 4-10 , is that an input
string written as a string literal must pass through two parse phases in the database server. The first backslash of each pair is interpreted as an escape character by the string-literal parser
(assuming escape string syntax is used) and is therefore consumed, leaving the second backslash of the pair. (Dollar-quoted strings can be used to avoid this level of escaping.) The remaining backslash is then recognized by the bytea
input function as starting either a three digit octal value or escaping another backslash. For example, a string literal passed to the server as
E'\\001'
becomes
\001
after passing through the escape string parser. The
\001
is then sent to the bytea input function, where it is converted to a single octet with a decimal value of 1. Note that the single-quote character is not treated specially by bytea
, so it follows the normal rules for string literals.
bytea Output Representations
Bytea octets are also escaped in the output. In general, each "non-printable" octet is converted into its equivalent three-digit octal value and preceded by one backslash. Most "printable" octets are represented by their standard representation in the client character set. The octet with decimal value 92 (backslash) has a special alternative output representation. Details are in
.
December 14, 2011 Datatypes V--171
Network Address Types Aster Data proprietary and confidential
Table 4-11 bytea Output Escaped Octets
Decimal
Octet Value
Description Escaped Output
Representation
Example
92
0 to 31 and
127 to 255
32 to 126 backslash
"printable" octets
\\
"non-printable" octets
\xxx
(octal value) client character set representation
SELECT E'\\134'::bytea;
SELECT E'\\001'::bytea;
SELECT E'\\176'::bytea;
Output
Result
\\
\001
~
Depending on the query tool you use, you might have additional work to do in terms of escaping and unescaping bytea
strings. For example, you might also have to escape line feeds and carriage returns if your interface automatically translates these.
Compatibility
The SQL standard defines a different binary string type, called
BLOB
or
BINARY LARGE
OBJECT
. The input format is different from bytea
, but the provided functions and operators are mostly the same.
Network Address Types ip4 and ip4range Datatypes in Aster Database
Aster Database supports the ip4 datatype for IPv4 network addresses, the ip4range datatype for ranges of network addresses, and the GiST index type for creating an index on a column of type ip4range.
The GiST index type lets you perform index lookups that take a given IP address and search through a table of IP address ranges to find the ranges that include that address. Expressed in
SQL, the lookup has the form, column >>= address.
The types are:
•
• ip4 - a single IPv4 address ip4range - an arbitrary range of IPv4 addresses
Simple usage examples
CREATE TABLE ipranges (range ip4range primary key, description text not null);
CREATE INDEX ipranges_range_idx ON ipranges USING gist (range);
INSERT INTO ipranges VALUES ('10.0.0.0/8','rfc1918 block 1');
INSERT INTO ipranges VALUES ('172.16.0.0/12','rfc1918 block 2');
INSERT INTO ipranges VALUES ('192.168.0.0/16','rfc1918 block 3');
INSERT INTO ipranges VALUES ('0.0.0.0/1','classical class A space');
INSERT INTO ipranges VALUES ('10.0.1.10-10.0.1.20','my internal network');
INSERT INTO ipranges VALUES ('127.0.0.1','localhost');
CREATE TABLE access_log (id serial primary key, ip ip4 not null);
CREATE INDEX access_log_ip_idx ON access_log (ip);
INSERT INTO access_log(ip) VALUES ('10.0.1.15');
INSERT INTO access_log(ip) VALUES ('24.1.2.3');
INSERT INTO access_log(ip) VALUES ('192.168.10.20');
V--172 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Network Address Types
INSERT INTO access_log(ip) VALUES ('127.0.0.1');
Find all accesses from 10.0.0.0/8
SELECT * FROM access_log WHERE ip BETWEEN '10.0.0.0' AND '10.255.255.255';
Find all applicable descriptions for all entry in the access log. This example returns multiple rows for each entry if there are overlapping ranges:
SELECT id,ip,range,description FROM access_log, ipranges WHERE ip <<= range;
Find only the most specific description for all IPs in the access log
SELECT DISTINCT ON (ip) ip,range,description
FROM access_log, ipranges
WHERE ip <<= range
ORDER BY ip,ip4range_size(range);
ip4 Datatype
ip4 accepts input in the form 'nnn.nnn.nnn.nnn' in decimal base only (no hex, octal, etc.). An ip4 value is a single IP address, and is stored as a 32-bit unsigned integer.
Type Conversions ip4 supports the following type conversions:
Source type Dest type ip4 text ip4 bigint ip4 float8 ip4 text ip4 bigint ip4
Form ip4::text (explicit) text::ip4 (explicit) ip4::bigint (explicit) bigint::ip4 (explicit) float8 ip4 ip4::float8 (explicit) float8::ip4 (explicit) ip4range ip4range(ip4) or ip4::ip4range (implicit)
The conversions from bigint and float8 accept values which are exact integers in the range 0 ..
2^32-1, which are converted to IPs in the range 0.0.0.0 - 255.255.255.255 in the obvious way.
This is useful for conversions from applications which store IPs in numeric form, as is often done for performance in certain other databases.
An ip4 value implicitly converts to an ip4range range containing only the single IP address.
The ip4 datatype supports the following operators in line with their conventional meanings: =,
<>, <, >, <=, >=, and supports ORDER BY and btree indexes in the usual fashion. However, the planner does not understand how to transform a query that tests for containment using syntax like
WHERE ip4column <<= value into a btree range scan. As a workaround, use syntax like the following instead:
WHERE ip4column BETWEEN lower(value) AND upper(value) which will use a btree range scan.
December 14, 2011 Datatypes V--173
Network Address Types Aster Data proprietary and confidential
Operators and Functions
The ip4 datatype supports the following additional operators and functions: ip4_netmask(integer)
Given an integer CIDR prefix length (the integer value that follows the slash in a
CIDR-formatted address), the ip4_netmask function returns an ip4 value that represents the netmask for that prefix length.
ip4_net_lower(ip4, integer)
For a specified IPv4 address and CIDR prefix length, the ip4_net_lower function returns the lowest address in the CIDR block in which the specified address falls. The datatype of the returned value is ip4.
ip4_net_upper(ip4, integer)
For a specified IPv4 address and CIDR prefix length, the ip4_net_upper function returns the highest address in the CIDR block in which the specified address falls. The datatype of the returned value is ip4.
Operator ip4 + integer ip4 - integer ip4 + bigint ip4 - bigint ip4 - ip4 ip4 & ip4 ip4 | ip4 ip4 # ip4
~ ip4
Description add the given integer to the IP subtract the given integer from the IP add the given integer to the IP subtract the given integer from the IP
(returns bigint) difference between two IPs bitwise-AND the two values bitwise-OR the two values bitwise-XOR the two values bitwise-NOT the value
Arithmetic on ip4 values does not wrap below 0.0.0.0 or above 255.255.255.255 - attempting to go beyond these limits raises an error.
More complex arithmetic on IP addresses can be performed by converting the IPs to bigint first; the above are only intended to cover the common cases without requiring casts.
ip4range Datatype
An ip4range value denotes a single range of one or more IP addresses, for example
'192.0.2.100-192.0.2.200'. All four octets must be supplied. Arbitrary ranges are allowed, though input can also be in the form of CIDR netblocks, e.g. '192.0.2.0/24' is equivalent to
'192.0.2.0-192.0.2.255'. A single value such as '192.0.2.25' represents a range containing only that value.
Values are displayed in CIDR form if they represent a CIDR range, otherwise in range form.
An ip4range value can be constructed from two IPs explicitly using the function ip4range(ip4,ip4)
. The ends of the range can be specified in either order.
V--174 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Network Address Types
Typecasting for ip4range ip4range supports the following type conversions:
Source type Dest type ip4 ip4range text ip4range text ip4range
Form ip4range(ip4) or ip4::ip4range (implicit) ip4range::text (explicit) ip4range(text) or text::ip4range (explicit)
Functions for ip4range ip4range supports the following functions: is_cidr(ip4range)
Returns TRUE if the ip4range value is a valid CIDR range. The value returned is a boolean.
lower(ip4range)
Returns the lowest address in the specified ip4range range. The value returned is an ip4 value.
upper(ip4range)
Returns the highest address in the specified ip4range range. The value returned is an ip4 value.
ip4range_size(ip4range)
Returns the number of IP addresses in the specified range. The value returned is a double precision value.
ip4range_union(ip4range, ip4range)
Returns a union of the two specified ranges. If a gap exists between the two ranges, the addresses in the gap are included in the union. The value returned is an ip4range.
ip4range_inter(ip4range, ip4range)
Returns the intersection of the two specified ranges. The value returned is an ip4range. If the two ranges do not intersect, no value is returned.
Operator a = b a <> b a < b a <= b a > b a >= b a >>= b a >> b a <<= b a << b a && b
Operators for ip4range
The ip4range type supports the following operators:
Description exact equality exact inequality ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
a contains b or is equal to b a strictly contains b a is contained in b or is equal to b a is strictly contained in b a and b overlap
December 14, 2011 Datatypes V--175
Network Address Types Aster Data proprietary and confidential
Operator a <<< b a >>> b
Description strictly less than. (a <<< b) if all IPs contained in a are strictly less than all IPs contained in b.
strictly greater than. (a >>> b) if all IPs contained in a are strictly greater than all IPs contained in b.
The @ operator is equivalent to >>=, and the ~ operator is equivalent to <<=, but use of these is not recommended in new code.
For testing whether an ip4range range contains a specified single ip, use the >>= operator, i.e. ip4range >>= ip4. The implicit conversion from ip4 to ip4range handles this case.
GiST Indexes (ip4range Indexes)
ip4range values can be indexed in several ways.
A conventional btree index on ip4range values will work for the purposes of unique/primary key constraints, ordering, and equality lookups (i.e. WHERE column = value). Btree indexes are created in the usual way and are the default index type.
However, ip4range’s utility comes from its ability to use GiST indexes to support the following lookup types:
WHERE column >>= value (or >>)
WHERE column <<= value (or <<)
WHERE column && value
These lookups require a GiST index. This can be created as follows:
CREATE INDEX indexname ON tablename USING gist (column);
For an example showing the use of GiST indexes, see “Indexing Example: A Geographic-IP
Address Join” on page II-19 .
Use Cases for ip4range
A typical use case that requires representation of ranges of IP addresses is for applications to create two integer columns, and do range queries of the form:
WHERE value BETWEEN column1 and column2
This is an attempt to get some use out of a btree index, but it performs poorly in most cases. This can also be converted to use a functional ip4range index as follows:
CREATE INDEX indexname ON tablename
USING gist (ip4range(column1::ip4,column2::ip4)); and then doing queries of the form:
WHERE ip4range(column1::ip4,column2::ip4) >>= value
One advantage of this method is that the ip4range type can be dropped and recreated without losing data. This is useful for accelerating queries on an existing table designed without ip4range in mind.
Another common use case is to get the longest-prefix (most specific) match to an IP address from a table of ranges or CIDR prefixes. This can usually be best achieved using ORDER BY ip4range_size(column), for example:
SELECT * FROM tablename
WHERE column >>= value
ORDER BY ip4range_size(column)
V--176 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Network Address Types
LIMIT 1
When looking up multiple IPs, one can do queries of the following form:
SELECT DISTINCT ON (ips.ip) ips.ip, ranges.range
FROM ips, ranges
WHERE ranges.range >>= ips.ip
ORDER BY ips.ip, ip4range_size(ranges.range)
Examples Using ip4 and ip4range
Below, we provide examples of common uses of the ip4 and ip4range types and their associated utility functions.
Example: GiST indexes
See “Indexing Example: A Geographic-IP Address Join” on page II-19 .
Example: Joins on IP addresses and ranges
BEGIN;
CREATE TABLE ip1(a ip4, b ip4range, c int) distribute by hash(a);
CREATE TABLE ip2(a ip4, b ip4range, c int) distribute by hash(b);
SELECT * FROM ip1 , ip2 WHERE ip1.a <<= ip2.b ORDER BY ip1.c;
SELECT * FROM ip1 , ip2 WHERE ip1.a = ip2.a ORDER BY ip1.c;
SELECT * FROM ip1 , ip2 WHERE ip1.b >>= ip2.a ORDER BY ip1.c;
SELECT * FROM ip1 , ip2 WHERE ip1.b = ip2.b ORDER BY ip1.c;
ABORT;
Examples: IP address-related functions and operators
BEGIN;
CREATE TABLE ip1(a ip4, b ip4range, c ip4, d bigint, e float) distribute by hash(a);
INSERT INTO ip1
VALUES
(
'79.43.226.6',
'79.43.0.0/16',
'79.43.0.0',
1232328732,
1232328732.0
);
SELECT
a::ip4range,
a::varchar,
a::bigint,
a::float8,
b::varchar,
d::ip4,
e::ip4
FROM ip1;
SELECT '234.34.222.1'::ip4, '12.233.22.0/24'::ip4range;
SELECT lower(ip4range(a,c)) FROM ip1;
December 14, 2011 Datatypes V--177
UUID Type Aster Data proprietary and confidential
SELECT lower(ip4range(c,a)) FROM ip1;
SELECT upper(ip4range(a,c)) FROM ip1;
SELECT upper(ip4range(c,a)) FROM ip1;
SELECT ip4_netmask(24);
SELECT ip4_net_lower(a,16) FROM ip1;
SELECT ip4_net_upper(a,16) FROM ip1;
SELECT a+1, a-1, a-c, a-6, a&c, a|c, a#c, ~a FROM ip1;
SELECT
is_cidr('10.23.0.0-10.23.255.255'),
is_cidr('10.23.0.0-10.23.255.254');
SELECT ip4range_size(b) FROM ip1;
SELECT
ip4range_inter('10.23.33.46-10.23.33.200','10.23.0.0/16'),
ip4range_union('10.20.3.23-10.22.11.2','10.10.3.23-10.10.11.2');
ABORT;
UUID Type
The datatype uuid
stores Universally Unique Identifiers (UUID) as defined by RFC 4122,
ISO/IEC 9834-8:2005, and related standards. Such an identifier is a 128-bit quantity that is generated by an algorithm chosen to make it very unlikely that the same identifier will be generated by anyone else in the known universe using the same algorithm. Therefore, for distributed systems, these identifiers provide a better uniqueness guarantee than that which can be achieved using sequence generators, which are only unique within a single database.
Aster Database supports storing and comparing UUID values, but not generating them; we assume that your applications will generate the UUIDs. You may use a UUID column as a distribution key in Aster Database.
A UUID is written as a sequence of lower-case hexadecimal digits, in several groups separated by hyphens, specifically a group of 8 digits followed by three groups of 4 digits followed by a group of 12 digits, for a total of 32 digits representing the 128 bits. An example of a UUID in this standard form is: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Aster Database also accepts the following alternative forms for input: use of upper-case digits, the standard format surrounded by braces, and omitting the hyphens. Examples are:
A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11} a0eebc999c0b4ef8bb6d6bb9bd380a11
Output is always in the standard form.
V--178 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Type Casts
Type Casts
Aster Database accepts two equivalent syntaxes for type casts to convert from one datatype to another.
CAST ( expression AS type ) and expression::type
When a cast is applied to a value expression of a known type, it represents a run-time type conversion. The cast will succeed only if a suitable type conversion operation exists.
December 14, 2011 Datatypes V--179
Type Casts Aster Data proprietary and confidential
V--180 Database SQL and Function Reference, version 4.6.2
aster data
V--5
Date and Time
Aster Database uses an internal heuristic parser for all date/time input support. Dates and times are input as strings, and are broken up into distinct fields with a preliminary determination of what kind of information may be in the field. Each field is interpreted and either assigned a numeric value, ignored, or rejected. The parser contains internal lookup tables for all textual fields, including months, days of the week, and time zones.
This section includes information on the content of these lookup tables and describes the steps used by the parser to decode dates and times.
•
•
“Date/Time Input Interpretation” on page V-181
“Date/Time Keywords” on page V-182
Date/Time Input Interpretation
The date/time type inputs are all decoded using the following procedure:
1.
Break the input string into tokens and categorize each token as a string, time, time zone, or number.
•
•
If the numeric token contains a colon (:), this is a time string. Include all subsequent digits and colons.
If the numeric token contains a dash (-), slash (/), or two or more dots (.), this is a date string which may have a text month.
•
•
If the token is numeric only, then it is either a single field or an ISO 8601 concatenated date (e.g., 19990113 for January 13, 1999) or time (e.g., 141516 for 14:15:16).
If the token starts with a plus (+) or minus (-), then it is either a time zone or a special field.
2.
If the token is a text string, match up with possible strings.
•
Do a binary-search table lookup for the token as either a special string (e.g., today), day
(e.g., Thursday), month (e.g., January), or noise word (e.g., at, on). Set field values and bit mask for fields. For example, set year, month, day for today, and additionally hour, minute, second for now.
3.
•
•
If not found, do a similar binary-search table lookup to match the token with a time zone.
•
If still not found, throw an error.
When the token is a number or number field:
If there are eight or six digits, and if no other date fields have been previously read, then interpret as a "concatenated date" (e.g., 19990118 or 990118). The interpretation is
YYYYMMDD or YYMMDD.
December 14, 2011 Aster Data proprietary and confidential V--181
Date/Time Keywords Aster Data proprietary and confidential
•
•
•
•
If the token is three digits and a year has already been read, then interpret as day of year.
If four or six digits and a year has already been read, then interpret as a time (HHMM or
HHMMSS).
If three or more digits and no date fields have yet been found, interpret as a year (this forces yy-mm-dd ordering of the remaining date fields).
Otherwise the date field ordering is assumed to follow the DateStyle setting: mm-dd-yy, dd-mm-yy, or yy-mm-dd. Throw an error if a month or day field is found to be out of range.
4.
If BC has been specified, negate the year and add one for internal storage. (There is no year zero in the Gregorian calendar, so numerically 1 BC becomes year zero.)
5.
If BC was not specified, and if the year field was two digits in length, then adjust the year to four digits. If the field is less than 70, then add 2000, otherwise add 1900.
Tip: Gregorian years AD 1-99 may be entered by using 4 digits with leading zeros (e.g., 0099 is
AD 99).
Date/Time Keywords
•
•
Day-of-Week Names (page V-182)
•
Date Time Field Modifiers (page V-183)
Month Names
The table below shows the tokens that are recognized as names of months.
Table 5-1 Month Names
Month Abbreviations
January
February
March
April
Jan
Feb
Mar
Apr
May May
June Jun
July
August
Jul
Aug
September
October
November
December
Sep, Sept
Oct
Nov
Dec
Day-of-Week Names
The table shows the tokens that are recognized as names of days of the week.
V--182 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Table 5-2 Day-of-week names
Day Abbreviations
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sun
Mon
Tue, Tues
Wed, Weds
Thu, Thur, Thurs
Fri
Sat
Date Time Field Modifiers
The table below shows the tokens that serve various modifier purposes.
Table 5-3 Date Time Field Modifiers
Identifier Description
ABSTIME
AM
AT
JULIAN, JD, J
ON
PM
T
Ignored
Time is before 12:00
Ignored
Next field is Julian Day
Ignored
Time is on or after 12:00
Next field is time
The keyword
ABSTIME
is ignored for historical reasons.
Date/Time Keywords
December 14, 2011 Date and Time V--183
Date/Time Keywords Aster Data proprietary and confidential
V--184 Database SQL and Function Reference, version 4.6.2
aster data
December 14, 2011
V--6
Data Dictionary Views
The queen node is the host for the data dictionary views and system tables. Aster’s data dictionary views are an SQL interface where you can examine the state of the cluster, its databases, and its data. The data dictionary views can be divided into the following categories:
Introduction to Data Dictionary Views (page V-186)
User-Related Data Dictionary Views (page V-186)
Role-Related Data Dictionary Views (page V-187)
Group Membership Data Dictionary Views (page V-187)
Database-Related Data Dictionary Views (page V-187)
Schema-Related Data Dictionary Views (page V-188)
SQL-MapReduce and Installed File-Related Data Dictionary Views (page V-188)
Table-Related Data Dictionary Views (page V-190)
Column-Related Data Dictionary Views (page V-190)
Index-Related Data Dictionary Views (page V-191)
Constraint-Related Data Dictionary Views (page V-191)
Logical Partition-Related Data Dictionary Views (page V-192)
Inheritance-Related Data Dictionary Views (page V-193)
Types Data Dictionary View (page V-193)
Cluster State Data Dictionary Views (page V-193)
Physical Node State: nc_physical_node_state (page V-193)
Storage State: nc_cluster_storage (page V-194)
Activity Data Dictionary Views (page V-194)
Session Statistics: nc_all_sessions (page V-194)
Transaction Statistics: nc_all_transactions (page V-195)
Transaction Phases: nc_all_transaction_phases (page V-195)
Statement Statistics: nc_all_statements (page V-195)
Load Error Logging Tables (page V-196)
Load Error Statistics Tables (page V-197)
Temporary Data Dictionary Views (page V-198)
Aster Data proprietary and confidential V--185
Introduction to Data Dictionary Views Aster Data proprietary and confidential
Introduction to Data Dictionary Views
The data dictionary views contain the metadata information about the various database elements.
These are read-only views and are located in the nc_system schema. References to data dictionary views that are not schema qualified will automatically resolve to the nc_system schema.
Warning!
Note that the data dictionary views were migrated to the nc_system schema beginning in Aster Database version 4.6. Prior to that, they were located in the public schema.
If you have scripts that use schema-qualified references to data dictionary views, you must change them to use nc_system as the schema when upgrading to a 4.6 or higher version of
Aster Database.
There are three versions for most data dictionary views. The version a logged-in user sees is based on his or her privileges.
•
•
•
nc_user_owned_XXX: These data dictionary views show the database elements that the user owns. An owner can complete any operation on an object they own.
nc_user_XXX: These data dictionary views show the database elements which the user has privileges to view. If a user has read-access on a database object, then the user can view the metadata related to that object. If a user has write-access or write-privilege, the user can modify the object regardless of whether they own it.
nc_all_XXX: These data dictionary views show all the database elements in the database.
This set of views is accessible only to members of the catalog_admin
and db_admin roles.
These views are explained in greater detail in the following sections.
User-Related Data Dictionary Views
The data dictionary views nc_users and nc_all_users contain information about the users in the system. nc_users will display all users for which the currently logged in user has the USAGE privilege. These views have the following schema: schemapath varchar cancreaterole bool
User’s default schema path
Can create additional users and roles autoinheritgrouppriv bool
If true, user automatically inherits group privileges. If false, user needs to execute
SET ROLE to group role before it obtains group privileges. Currently, SET ROLE is not supported in Aster Database and the value for this column defaults to true number of concurrent connections this user can make. -1 means no limit
V--186 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Database-Related Data Dictionary Views
Role-Related Data Dictionary Views
The data dictionary views nc_roles and nc_all_roles contain information about the roles in the system. nc_roles will display all roles for which the currently logged in user has the USAGE privilege. These views have the following schema: cancreaterole bool autoinheritgrouppriv bool
Can create additional roles
If true, role automatically inherits group privileges. If false, role needs to execute SET
ROLE to group role before it obtains group privileges. Currently, SET ROLE is not supported in Aster Database and the value for this column defaults to true
Group Membership Data Dictionary Views
The data dictionary views nc_group_members and nc_all_group_members record users’ memberships in roles (groups). nc_group_members displays information about all groups in which the currently logged in user is either a group owner or is a member of the group. For information about the role (group) itself, see the corresponding entry in the Aster Database roles view. These views have the following schema: others
Database-Related Data Dictionary Views
The data dictionary views nc_user_owned_databases, nc_user_databases and nc_all_
databases contain information about all the databases in the system. nc_user_databases will display all databases for which the currently logged in user has the CONNECT privilege. All three views have the following schema:
Figure 6-1 Schema of nc_user_owned_databases, nc_user_databases and nc_all_ databases dbid int
Unique database Id
December 14, 2011 Data Dictionary Views V--187
Schema-Related Data Dictionary Views Aster Data proprietary and confidential dbencoding varchar
Character encoding for this database permissions varchar Access privileges for this database
Schema-Related Data Dictionary Views
Aster Database supports schemas for managing users’ rights to database objects. See
for information on how to assign users’s rights. A schema is a separately managed part of a database. Creating a database with multiple schemas allows multiple groups to use the database while preserving each group’s control over the structure of tables that belong to that group. Each group can be granted (if desired) database-wide SELECT and INSERT rights, but each group can only modify those tables and database objects that fall inside that group’s realm.
The data dictionary views nc_user_owned_schemas, nc_user_schemas and nc_all_schemas contain information about all the schemas in the system. The nc_user_schemas table displays all schemas for which the currently logged in user has the USAGE privilege. All three views have the following schema:
Figure 6-2 Schema of nc_user_owned_schemas, nc_user_schemas and nc_all_ schemas
Field Type Description dbname schemaid schemaname schemaowner permissions varchar int varchar varchar varchar
Database name to which this schema belongs
Unique schema Id
Database name
Database owner name
Access privileges for this schema
SQL-MapReduce and Installed File-Related Data Dictionary
Views
Below, we explain the views that hold information about installed files, installed
SQL-MapReduce functions, and the privileges that grant users rights to install files and run
SQL-MapReduce functions in Aster Database. These views help the Aster Database administrator perform privileges reporting for installed files and SQL-MapReduce functions.
Related topics
•
•
For information on setting users’ SQL-MapReduce privileges, see “SQL-MapReduce
Security” on page I-79 .
The \dF command provides an alternative way to see the list of installed files and functions.
See “Getting information about currently-installed functions” on page I-81 .
nc_user_installed_files, nc_user_owned_installed_files, nc_all_ installed_files
Lists installed files in the database. The three variations on the table list different sets of installed files:
• nc_user_installed_files
lists installed files to which the current user has mangement
(download and uninstall) rights. Note! In version 4.6 and later, a user can only download and
V--188 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Views
SQL-MapReduce and Installed File-Related Data Dictionary
•
•
•
•
• uninstall the functions that he installed, so the results returned by querying nc_user_ installed_files
are the same as those returned from nc_user_owned_installed_ files
.
nc_user_owned_installed_files
lists installed files owned by the current user.
nc_all_installed_files
lists all installed files in the database. This view is only viewable by the administrator.
The columns are:
•
•
•
•
schemaid: ID number of the schema this file belongs to.
fileid: Aster Database-generated ID number of the file.
filename: As-installed name of the file. This is the name you use to access or manage the file with the install, uninstall, and download commands in Aster Database.
filetype: When the file is installed, nClsuter recognizes its type based on its filename extension. The value will be “sql-mr” for SQL-MapReduce function files and “regular” for all other files.
fileowner: SQL user who installed the file. Only this user or the administrator can remove the file.
md5hash: The MD5 hash of the file.
uploadtime: Date and time when this file was installed.
nc_user_sqlmr_funcs, nc_user_owned_sqlmr_funcs, nc_all_sqlmr_ funcs
Lists SQL-MR functions installed in the database. The three variations on the table list different sets of installed functions:
•
•
• nc_user_sqlmr_funcs
lists installed functions to which the current user has EXECUTE privileges.
nc_user_owned_sqlmr_funcs
lists installed functions owned by the current user.
nc_all_sqlmr_funcs
lists all installed functions in the database.This view is only viewable by the administrator.
The columns are:
•
•
•
•
•
•
schemaid: ID number of the schema that this function belongs to.
fileid: ID number of the file that contains the function. You can look up the file in the corresponding nc_*_installed_files view.
funcid: Aster Database-generated ID number of the function.
funcname: As-installed name of the function. This is the name you use to access, call or manage the function with other Aster Database commands.
funcowner: Name of SQL user who created the function. Only this user or the administrator can uninstall the function.
creationtime: When this function was created.
nc_user_sqlmr_func_privs, nc_user_owned_sqlmr_func_privs, nc_ all_sqlmr_func_privs
Lists users’ EXECUTE privileges on functions in the database. The three variations on the table list different sets of installed functions:
December 14, 2011 Data Dictionary Views V--189
Table-Related Data Dictionary Views Aster Data proprietary and confidential
•
•
•
•
•
•
• nc_user_sqlmr_func_privs
lists, for each function on which the current user has
EXECUTE privileges, all the EXECUTE privileges that have been granted. In other words, if you’re using a function and you want to know who else can use it, query this view.
nc_user_owned_sqlmr_func_privs
lists, for all the functions owned by the current user, all the EXECUTE privileges that have been granted. In other words, if you want to know who else can use the functions you’ve created, query this view.
nc_all_sqlmr_func_privs
lists all installed functions in the database.This view is only viewable by the administrator.
The columns are:
•
grantor: user who granted this privilege
grantee: user who has this privilege
funcid: ID number of the SQL-MapReduce function governed by this privilege
privtype: type of privilege. An EXECUTE privilege gives the user the right to run the function.
isgrantable: Indicates whether the grantee can grant this privilege to other users.
Table-Related Data Dictionary Views
The data dictionary views nc_user_owned_tables, nc_user_tables and nc_all_tables contain information about the tables in the database to which the current session has been established.
The table nc_user_tables displays all tables for which the currently logged in user has the
SELECT privilege. All three views have the following schema:
Figure 6-3 Schema of nc_user_owned_tables, nc_user_tables and nc_all_tables schemaid int Schema id to which this table belongs tableid int
Unique table Id tableowner varchar
Table owner name compresslevel varchar
Compression level for that table: { 'none' , 'low' , 'medium' , 'high' } storagetype varchar partitionkey varchar
Table storage type: {‘row’, ‘column’}
Distribution key/partition key of table (not the key for a logical partition) permissions varchar
Access privileges for this table
Column-Related Data Dictionary Views
The data dictionary views nc_user_owned_columns, nc_user_columns and nc_all_columns contain information about all the user table columns in the database to which the current session has been established. nc_user_columns will display columns for all the tables for which the currently logged in user has the SELECT privilege. All three views have the following schema:
Figure 6-4 Schema of nc_user_owned_columns, nc_user_columns and nc_all_columns
V--190 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Constraint-Related Data Dictionary Views ispartitionkey bool true if column is a distribution key/partition key (not the key for a logical partition) isinherited bool true if column is inherited from parent defaultval text
Default value for the column, if one is defined
Index-Related Data Dictionary Views
The data dictionary views nc_user_owned_indexes, nc_user_indexes and nc_all_indexes contain information about all the user table indexes in the database to which the current session has been established. nc_user_indexes will display indexes for all the tables for which the currently logged in user has the SELECT privilege. All three views have the following schema:
Figure 6-5 Schema of nc_user_owned_indexes, nc_user_indexes and nc_all_indexes tableid int
Table id of table on which index was created indexid int Unique index Id indexname varchar
Index name isprimary bool true if this is a primary key index
Constraint-Related Data Dictionary Views
The data dictionary views nc_user_owned_constraints, nc_user_constraints and nc_all_
constraints contain information about all the user table constraints in the database to which the current session has been established. nc_user_constraints will display constraints for all the tables for which the currently logged in user has the SELECT privilege. All three views have the following schema:
Figure 6-6 Schema of nc_user_owned_constraints, nc_user_constraints and nc_all_ constraints
Field Type Description tableid int contype char
Table id of table on which the constraint is defined conid int
Unique constraint Id conname varchar
Constraint name c = check constraint, p = primary key constraint
December 14, 2011 Data Dictionary Views V--191
Logical Partition-Related Data Dictionary Views Aster Data proprietary and confidential collist varchar
List of column positions for columns that form this constraint
Logical Partition-Related Data Dictionary Views
The data dictionary views nc_all_child_partitions, nc_user_child_partitions and nc_user_
owned_child_partitions contain information about all the child partitions in logically partitioned tables. nc_user_child_partitions will display child partitions for all the tables for which the currently logged in user has the SELECT privilege. All three views have the following schema:
Figure 6-7 Schema of nc_all_child_partitions, nc_user_child_partitions and nc_user_ owned_child_partitions partitionid bigint
Partition ID for this child partition at lower levels, this is the ID of the parent partition.
partitionname varchar compressinfo varchar
Name of child partition (unique among partitions with the same parent)
Compression level of the partition: { 'none' , 'low' , 'medium' , 'high' } partitionexpr varchar nullsfirst bool constraintdef varchar
Expression that the partitioning is based on
True if nulls are sorted first
Definition of the constraint. Some examples of constraintdef:
* VALUES (NULL, 'a', 'b')
* START (0) INCLUSIVE END (10) EXCLUSIVE
The data dictionary views nc_all_parent_partitions, nc_user_parent_partitions and nc_user_
owned_parent_partitions contain information about all the parent partitions in logically partitioned tables. nc_user_parent_partitions will display parent partitions for all the tables for which the currently logged in user has the SELECT privilege.
If a table is partitioned, but has zero children, nc_parent_partitions will show the partition expression, whereas nc_child_partitions will not have any rows.
All three views have the following schema:
Figure 6-8 Schema of nc_all_parent_partitions, nc_user_parent_partitions and nc_user_ owned_parent_partitions at lower levels, this is the ID of the parent partition.
partitionexpr varchar nullsfirst bool
Expression that the partitioning is based on
True if nulls are sorted first
V--192 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Cluster State Data Dictionary Views
Inheritance-Related Data Dictionary Views
The data dictionary views nc_user_owned_inherit, nc_user_inherit and nc_all_inherit contain information about all the user table inheritance relationships in the database to which the current session has been established. nc_user_inherit will display inheritance relationships for all the tables for which the currently logged in user has the SELECT privilege. All three views have the following schema:
Figure 6-9 Schema of nc_user_owned_inherit, nc_user_inherit and nc_all_inherit
Field Type Description parentid int childid int
Table id of parent table
Table id of child table
Types Data Dictionary View
The data dictionary view nc_types contains information about all the datatypes supported in
Aster Database.
Figure 6-10 Schema of nc_types
Field Type Description typeid typename typelen int For a fixed-size type, typlen is the number of bytes in the internal representation of the type. For a variable-length type, typlen is -1
Cluster State Data Dictionary Views
This set of data dictionary views maintains information about the state of the cluster. Only members of the roles catalog_admin and db_admin can access these tables, all of which are read-only. See:
•
•
Physical Node State: nc_physical_node_state (page V-193)
Storage State: nc_cluster_storage (page V-194)
Physical Node State: nc_physical_node_state
The data dictionary view nc_physical_node_state contains information about the worker nodes
(machines) in the cluster. The schema is:
Figure 6-11 Schema of nc_physical_node_state
Field Type Description macaddr varchar ipaddr varchar type varchar
Mac address of the node
Assigned ip address of node
Type of the node: { 'Worker' , 'Loader' ,
'Backup' }
December 14, 2011 Data Dictionary Views V--193
Activity Data Dictionary Views Aster Data proprietary and confidential state varchar lastupdatetime timestamp without timezone
State of the node: { 'Active' , 'Failed' , 'Suspect'
, 'Prepared' , 'Preparing' , 'New' , 'Passive' ,
'Upgrading' }
Time at which node state was last updated
Storage State: nc_cluster_storage
The data dictionary view nc_cluster_storage contains information about the storage utilization of the cluster.
Figure 6-12 Schema of nc_cluster_storage
Field Type Description totalstorage bigint activestorage bigint replicastorage bigint systemstorage bigint lastupdatetime timestamp without timezone
Total storage in the cluster
Storage used by active data in the cluster
Storage used by the replica data in the cluster
Storage used by the system data in the cluster
Time at which storage state was last updated
Activity Data Dictionary Views
This set of data dictionary views, sometimes referred to as the “Stats DB,” maintains information and statistics about various activities in the database cluster. This set of views is accessible only to members of the roles catalog_admin and db_admin and all of these are read-only. See:
•
•
•
•
•
•
Session Statistics: nc_all_sessions (page V-194)
Transaction Statistics: nc_all_transactions (page V-195)
Transaction Phases: nc_all_transaction_phases (page V-195)
Statement Statistics: nc_all_statements (page V-195)
Load Error Logging Tables (page V-196)
Load Error Statistics Tables (page V-197)
Session Statistics: nc_all_sessions
The data dictionary view nc_all_sessions contains information about current and past sessions to
Aster Database.
Figure 6-13 Schema of nc_all_sessions
Field Type Description sessionid bigint username varchar clientip character(16) dbname varchar starttime endtime timestamp without time zone timestamp without time zone
Unique session id
Session username
Client ip address
Name of database to which connection was established
Session start time
Session end time
V--194 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Activity Data Dictionary Views
Transaction Statistics: nc_all_transactions
The data dictionary view nc_all_transactions contains information about each transaction executed in Aster Database. Everything in a begin ... end block represents an explicit transaction.
Individual statements are implemented as stand-alone transactions.
Figure 6-14 Schema of nc_all_transactions
Field Type Description xactionid sessionid bigint starttime endtime timestamp without time zone timestamp without time zone
Session id of session to which the transaction belongs
Start time of transaction
End time of transaction phase
Transaction Phases: nc_all_transaction_phases
The data dictionary view nc_all_transaction_phases contains information about the phases of each transaction executed in Aster Database.
Figure 6-15 Schema of nc_all_transaction_phases
Field Type Description phase xactionid sessionid starttime endtime character(20) Phase description bigint Transaction id of transaction bigint Session id of session to which the transaction belongs timestamp without time zone timestamp without time zone
Start time of transaction phase
End time of transaction phase
Statement Statistics: nc_all_statements
The data dictionary view nc_all_statements contains information about recently executed statements in Aster Database. By default, the table retains three days worth of statements, but your asterdata.com/support
representative can change the retention policy for you.
Figure 6-16 The nc_all_statements Table
Field Type statementid xactionid sessionid retrynum statement starttime endtime
Description bigint bigint bigint
Unique statement id
Transaction id of transaction to which this statement belongs
Session id of session to which the statement belongs
Retry count of this statement integer character varying Statement string timestamp without time zone Start time of statement timestamp without time zone End time of statement
December 14, 2011 Data Dictionary Views V--195
Activity Data Dictionary Views Aster Data proprietary and confidential iscancelable
Boolean true if statement is cancelable
Load Error Logging Tables
The COPY command and the ncluster_loader tool allow you to direct failed rows into a load error logging table. You can use the default error logging tables or create your own. By default, malformed rows for hash-distributed tables go into table nc_errortable_part
table, and malformed rows for replicated tables go into the nc_errortable_repl
table. To create your own error logging table, see
“Creating a Load Error Logging Table” on page V-197 .
Schema of the Load Error Logging Tables
Table 6-1 Columns of the nc_errortable_part table and nc_errortable_repl table
Column Type Description key tupletimestamp label targettable dmltype errmessage sqlerrcode rawdata linenumber columnname bigint Distribution key/partition key (not the key for a logical partition)
Date and time when this error occurred.
timestamp with time zone character varying User-specified label provided in WITH LABEL or
--el-label
flag, or the system default label.
character varying Intended destination table for this row.
character(1) Type of operation that generated the error.
Currently, this is always 'C' indicating COPY.
character varying Error message returned by PostgreSQL when rejecting the row.
character(5) SQL code associated with the rejection.
bytea bigint varchar
The failed row itself.
Line number where the error occurred in the file.
Name of the column where the error occurred in the file.
Sample Entries in a Load Error Logging Table
Below we show an example of a load into a simple clicks
table that includes malformed rows.
beehive=> CREATE FACT TABLE clicks (pageid bigint,
userid bigint,
ts timestamp)
distribute by hash(pageid);
CREATE TABLE beehive=> COPY clicks FROM STDIN LOG ERRORS INTO nc_errortable_part;
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> 1 123 May 20 11:18:56 2009
>> 2 a May 20 11:19:30 2009
>> 1 May 20 11:18:56 2009
>> 3 3 2345 May 20 11:10:02 2009
>> 4 23333 May 20 11:18:56 2009 \N
>> \.
beehive=>
V--196 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Activity Data Dictionary Views
As shown above, 4 of the 5 rows that we tried to load were malformed, which leaves us with one row successfully loaded to our “clicks” table and four error rows in the error logging table, nc_ errortable_part. The successfully loaded row: beehive=> SELECT * FROM clicks;
pageid | userid | ts
--------+--------+---------------------
1 | 123 | 2009-05-20 11:18:56
(1 row)
To view the rows that failed to load, we type: beehive=> SELECT * FROM nc_errortable_part; which returns:
Table 6-2 Sample COPY error rows in nc_errortable_part
key tupletimestamp label target
- table dml- type errmessage sqlerr- code
1 2009-05-20
15:20:05.281138-07
0 clicks C 22P02
1 2009-05-20
15:20:05.281389-07
0 clicks C invalid input syntax for integer: "a" extra data after last expected column
22P04
0 2009-05-20
15:20:05.116448-07
0 clicks C
rawdata linenumber
2\x09a\x09May
20 11:19:30
2009
2
5 4\x0923333\x0
9May 20
11:18:56
2009\x09\N
1\x09May 20
11:18:56 2009
3
0 2009-05-20
15:20:05.116737-07
0 clicks C invalid input syntax for integer: "May 20
11:18:56 2009"
22P02 extra data after last expected column
22P04 3\x093\x09234
5\x09May 20
11:10:02 2009
4
columnname
userid ts
Creating a Load Error Logging Table
To create and use your own error logging table:
1.
Log into ACT as a user with the catalog_admin privilege.
2.
Create a table that inherits from the nc_errortable_part
table (if you are loading to a
hash-distributed table) or the nc_errortable_repl
table (if you are loading to a
replicated table). In other words, your error table must contain at least those table attributes that are in nc_errortable_part
or nc_errortable_repl
.
3.
To use the custom error logging table, use the INTO 'errortablename' parameter with the COPY command in SQL, or, if you are using the ncluster_loader tool, pass the
--el-table =
'errortablename' flag, where errortablename is the name of your custom load error logging table.
For more details on error logging during loading, see “Error Logging” on page II-142 or
“Parameters for COPY” on page V-24 .
Load Error Statistics Tables
The nc_all_errorlogging_stats and nc_user_errorlogging_stats tables provide details about bulk loads that have been done or attempted using ncluster_loader or the SQL
COPY
command.
December 14, 2011 Data Dictionary Views V--197
Temporary Data Dictionary Views Aster Data proprietary and confidential
Each loading command generates a row in the tables. For a given transaction, the totalcount
, goodcount
, and malformedcount
columns show the total number of rows you tried to load, the number of rows that successfully loaded, and the number of rows not loaded, respectively.
Table 6-3 The nc_all_errorlogging_stats and nc_user_errorlogging_stats tables
Field Description username sessionid transactionid statementid targettable eltable dmltype label totalcount goodcount malformedcount
User who performed the load attempt.
Session ID of the load attempt.
Transaction ID of the load attempt.
Statement ID of the load attempt.
Table into which data is being loaded.
Error logging table that received the bad rows for this load attempt.
DML action of the load attempt. Currently this is always “C”, meaning “copy”.
Label that identifies this load attempt. This is the label the user specified with the
--el-label
or label
argument when he ran the load attempt.
Number of rows that this load attempt tried to load.
Number of rows successfully loaded in this load attempt.
Number of rows that failed to load in this load attempt. Look in the error logging table for failed row details.
For more details on error logging during loading, see “Error Logging” on page II-142 or
“Parameters for COPY” on page V-24 .
Temporary Data Dictionary Views
You may occasionally see tables names “ nc_temp_
” followed by a number, as in nc_temp_
21
. These are temporary data dictionary views, and Aster Database automatically deletes them at a regular interval. As administrator, you do not need to monitor or remove them.
V--198 Database SQL and Function Reference, version 4.6.2
aster data
V--7
SQL Vocabulary
SQL input consists of a sequence of commands. A command is composed of a sequence of tokens, terminated by a semicolon (";"). The end of the input stream also terminates a command.
Which tokens are valid depends on the syntax of the particular command.
A token can be a keyword, an identifier, a quoted identifier, a literal (or constant), or a special character symbol. Tokens are normally separated by whitespace (space, tab, newline), but need not be if there is no ambiguity (which is generally only the case if a special character is adjacent to some other token type).
Additionally, comments can occur in SQL input. They are not tokens, they are effectively equivalent to whitespace.
For example, the following is (syntactically) valid SQL input:
SELECT * FROM MY_TABLE;
UPDATE MY_TABLE SET A = 5;
INSERT INTO MY_TABLE VALUES (3, 'hi there');
This is a sequence of three commands, one per line (although this is not required; more than one command can be on a line, and commands can usefully be split across lines).
The SQL syntax is not very consistent regarding what tokens identify commands and which are operands or parameters. The first few tokens are generally the command name, so in the above example we would usually speak of a "SELECT", an "UPDATE", and an "INSERT" command.
But for instance the UPDATE command always requires a SET token to appear in a certain position, and this particular variation of INSERT also requires a VALUES in order to be complete.
Identifiers, Keywords, and Naming Conventions
Tokens such as SELECT, UPDATE, or VALUES in the example above are examples of keywords, that is, words that have a fixed meaning in the SQL language. The tokens MY_
TABLE and A are examples of identifiers. They identify names of tables, columns, or other database objects, depending on the command they are used in. Therefore they are sometimes simply called "names". Keywords and identifiers have the same lexical structure, meaning that one cannot know whether a token is an identifier or a keyword without knowing the language.
Identifiers such as table names, column names, and database names must begin with a letter (a-z, but also letters with diacritical marks and non-Latin letters) or an underscore (_). Subsequent characters in an identifier or key word can be letters, underscores, digits (0-9), or dollar signs ($).
(Note that dollar signs are not allowed in identifiers according to the SQL standard, so their use may render your table or column unusable in certain applications.) Identifiers in Aster Database
December 14, 2011 Aster Data proprietary and confidential V--199
Identifiers, Keywords, and Naming Conventions Aster Data proprietary and confidential cannot begin with the prefix “_bee”, which is reserved for use in naming Aster Database system objects.
The SQL standard will not define a keyword that contains digits or starts or ends with an underscore, so identifiers of this form are safe against possible conflict with future extensions of the standard.
The maximum identifier length depends on the type of object. Tables and columns may have names up to 63 bytes long. The database name length limit is shorter; see “Database Name
Limitations” on page II-5 .
Identifier and keyword names are case insensitive (unless they are quoted identifiers, which we’ll explain in a minute). Therefore
UPDATE MY_TABLE SET A = 5; can equivalently be written as uPDaTE my_TabLE SeT a = 5;
A convention often used is to write keywords in upper case and names in lower case, e.g.,
UPDATE my_table SET a = 5;
Quoted Identifiers
There is a second kind of identifier: the delimited identifier or quoted identifier. It is formed by enclosing an arbitrary sequence of characters in double-quotes (
"
) or in square brackets (
[ ]
).
Tip!
By default, quoted identifiers are allowed in Aster Database, but your database administrator also has the option of turning off this feature, in which case each double-quoted string is interpreted as a literal string constant. See “Quoted-Identifier Handling” on page I-111 .
A quoted identifier is always an identifier, never a keyword. So
"select"
with its surrounding double-quotes could be used to refer to a column or table named
"select"
, whereas an unquoted select
would be taken as a keyword and would therefore provoke a parsing error when used where a table or column name is expected.
Using quoted identifiers lets you construct table or column names that would otherwise not be possible, such as ones containing spaces or ampersands. The length limitation still applies.
Quoting an identifier also makes it case-sensitive, whereas unquoted names are always folded to lower case. For example, the identifiers ASTER, aster, and "aster" are considered the same by
Aster Database, but "Aster" and "ASTER" are different from these three and each other.
A variation on the earlier example can be written with quoted identifiers like this:
UPDATE "my table" SET "a" = 5; or like this:
UPDATE [my table] SET [a] = 5;
These rules apply to quoted identifiers:
•
Quoted identifiers surrounded by double-quote marks can contain any character except the
following characters: single quotes, double quotes, backslashes, and the character with code zero.
V--200 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential Value Expressions
•
Quoted identifiers surrounded by square brackets can contain any character except the
following characters: single quotes, double quotes, square brackets, backslashes, and the character with code zero.
Comments in SQL
A comment is an arbitrary sequence of characters beginning with double dashes and extending to the end of the line, e.g.:
-- This is a standard SQL comment
Alternatively, C-style block comments can be used:
/* multiline comment
* with nesting: /* nested block comment */
*/ where the comment begins with /* and extends to the matching occurrence of */. These block comments nest, as specified in the SQL standard but unlike C, so that one can comment out larger blocks of code that may contain existing block comments.
A comment is removed from the input stream before further syntax analysis and is effectively replaced by whitespace.
Value Expressions
Value expressions are used in a variety of contexts, such as in the target list of the SELECT command, as new column values in INSERT or UPDATE, or in search conditions in a number of commands. The result of a value expression is sometimes called a scalar, to distinguish it from the result of a table expression (which is a table). Value expressions are therefore also called scalar expressions (or even simply expressions). The expression syntax allows the calculation of values from primitive parts using arithmetic, logical, set, and other operations.
•
•
•
•
•
•
•
•
•
•
•
•
•
A value expression is one of the following:
A constant or literal value.
A column reference.
A positional parameter reference, in the body of a function definition or prepared statement.
A subscripted expression.
A field selection expression.
An operator invocation.
A function call.
An aggregate expression.
A type cast.
A scalar subquery.
An array constructor.
A row constructor.
Another value expression in parentheses, useful to group subexpressions and override precedence.
December 14, 2011 SQL Vocabulary V--201
Value Expressions Aster Data proprietary and confidential
In addition to this list, there are a number of constructs that can be classified as an expression but do not follow any general syntax rules. These generally have the semantics of a function or operator., An example is the IS NULL clause.
Column References
A column can be referenced in the form correlation.columnname
In this example, correlation is the name of a table (possibly qualified with a schema name), or an alias for a table defined by means of a FROM clause, or one of the keywords NEW or OLD.
(NEW and OLD can only appear in rewrite rules, while other correlation names can be used in any SQL statement.) The correlation name and separating dot may be omitted if the column name is unique across all the tables being used in the current query.
V--202 Database SQL and Function Reference, version 4.6.2
aster data
System Limits
Most capacity and usage limits of your Aster Database deployment depend on the quantity of nodes and disk space you add to the cluster.
Table 8-1 Aster Database System Limits
Description Limit
Maximum size of a database
Maximum size of a hash distributed table
Practically unlimited
Practically unlimited
Maximum size of a non-distributed DIMENSION table
32TB
Maximum size of a row
Maximum size of a character field
Maximum size of a text field
Maximum number of rows in a table
Maximum number of columns in a table
400 GB
1 GB
Practically unlimited
Practically unlimited
250-1600 depending on datatypes used.
Effective limit is also affected by the row-size constraint.
Practically unlimited
63 characters
Maximum number of indexes on a table
Maximum length of a table name, column name, or view name
Maximum length of a database name
Maximum number of columns in a SELECT
Maximum number of users
Maximum number of connections
Maximum number of nodes
Maximum length of an SQL query
50 characters
1660 columns
Practically unlimited
Practically unlimited
Practically unlimited
Practically unlimited
December 14, 2011 Aster Data proprietary and confidential V--203
Aster Data proprietary and confidential
V--204 Database SQL and Function Reference, version 4.6.2
aster data
Error Codes
All messages emitted by the Aster Database are assigned five-character error codes that follow the SQL standard's conventions for “SQLSTATE” codes. Applications that need to know which error condition has occurred should usually test the error code, rather than looking at the textual error message. Note that some, but not all, of the error codes produced by Aster Database are defined by the SQL standard; some additional error codes for conditions not defined by the standard have been invented or borrowed from other databases.
According to the standard, the first two characters of an error code denote a class of errors, while the last three characters indicate a specific condition within that class. Thus, an application that does not recognize the specific error code can still be able to infer what to do from the error class.
In the tables that follow, we list the Aster Database error codes and the meaning of each.
Table 9-2 Error Code Class 00 - Successful Completion Codes
Error Code Error Description
0 SUCCESSFUL COMPLETION
Table 9-3 Error Code Class 0A - Feature Not Supported
Error Code Error Description
0A000 FEATURE NOT SUPPORTED
Table 9-4 Error Code Class 21 - Cardinality Violation
Error Code Error Description
21000 CARDINALITY VIOLATION
Table 9-5 Error Code Class 22 - Data Exception
Error Code Error Description
22000
22021
22008
22012
22005
2200B
22022
22015
2201E
2201F
DATA EXCEPTION
CHARACTER NOT IN REPERTOIRE
DATETIME FIELD OVERFLOW
DIVISION BY ZERO
ERROR IN ASSIGNMENT
ESCAPE CHARACTER CONFLICT
INDICATOR OVERFLOW
INTERVAL FIELD OVERFLOW
INVALID ARGUMENT FOR LOGARITHM
INVALID ARGUMENT FOR POWER FUNCTION
December 14, 2011 Aster Data proprietary and confidential V--205
Aster Data proprietary and confidential
Error Code
22003
22026
22001
22011
22027
22024
2200F
22P01
22P02
22P03
22P04
22P05
22020
22023
2201B
22009
2200C
2200G
22004
22002
2201G
22018
22007
22019
2200D
22025
22P06
22010
Error Description
INVALID ARGUMENT FOR WIDTH BUCKET FUNCTION
INVALID CHARACTER VALUE FOR CAST
INVALID DATETIME FORMAT
INVALID ESCAPE CHARACTER
INVALID ESCAPE OCTET
INVALID ESCAPE SEQUENCE
NONSTANDARD USE OF ESCAPE CHARACTER
INVALID INDICATOR PARAMETER VALUE
INVALID LIMIT VALUE
INVALID PARAMETER VALUE
INVALID REGULAR EXPRESSION
INVALID TIME ZONE DISPLACEMENT VALUE
INVALID USE OF ESCAPE CHARACTER
MOST SPECIFIC TYPE MISMATCH
NULL VALUE NOT ALLOWED
NULL VALUE NO INDICATOR PARAMETER
NUMERIC VALUE OUT OF RANGE
STRING DATA LENGTH MISMATCH
STRING DATA RIGHT TRUNCATION
SUBSTRING ERROR
TRIM ERROR
UNTERMINATED C STRING
ZERO LENGTH CHARACTER STRING
FLOATING POINT EXCEPTION
INVALID TEXT REPRESENTATION
INVALID BINARY REPRESENTATION
BAD COPY FILE FORMAT
UNTRANSLATABLE CHARACTER
Table 9-6 Error Code Class 23 - Integrity Constraint Violation
Error Code Error Description
23000
23502
23514
23518
INTEGRITY CONSTRAINT VIOLATION
NOT NULL VIOLATION
CHECK VIOLATION
PARTITION KEY ERROR
V--206 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Table 9-7 Error Code Class 25 - Invalid Transaction State
Error Code Error Description
25000
25P02
INVALID TRANSACTION STATE
IN FAILED SQL TRANSACTION
Table 9-8 Error Code Class 26 - Invalid SQL Statement Name
Error Code Error Description
26000 INVALID SQL STATEMENT NAME
Table 9-9 Error Code Class 28 - Invalid Authorization Specification
Error Code Error Description
28000 INVALID AUTHORIZATION SPECIFICATION
Table 9-10 Error Code Class 2B - Dependent Privilege Descriptors Still Exist
Error Code Error Description
2BP01 DEPENDENT OBJECTS STILL EXIST
Table 9-11 Error Code Class 2D - Invalid Transaction Termination
Error Code Error Description
2D000 INVALID TRANSACTION TERMINATION
Table 9-12 Error Code Class 34 - Invalid Cursor Name
Error Code Error Description
34000 INVALID CURSOR NAME
Table 9-13 Error Code Class 40 - Transaction Rollback
Error Code Error Description
40000
40002
40001
40003
40P01
TRANSACTION ROLLBACK
TRANSACTION INTEGRITY CONSTRAINT VIOLATION
SERIALIZATION FAILURE
STATEMENT COMPLETION UNKNOWN
DEADLOCK DETECTED
Table 9-14 Error Code Class 42 - Syntax Error or Access Rule Violation
Error Code Error Description
42000
42601
42501
42846
SYNTAX ERROR OR ACCESS RULE VIOLATION
SYNTAX ERROR
INSUFFICIENT PRIVILEGE
CANNOT COERCE
December 14, 2011 Error Codes V--207
Aster Data proprietary and confidential
Error Code
42611
42P11
42P12
42P13
42P16
42P17
42P07
42712
42710
42702
42725
42P08
42P09
42P10
42883
42P01
42P02
42704
42701
42P03
42P04
42723
42803
42602
42622
42939
42804
42P18
42809
42703
Table 9-15 Error Code Class 53 - Insufficient Resources
Error Code Error Description
53000
53100
53200
53300
INSUFFICIENT RESOURCES
DISK FULL
OUT OF MEMORY
TOO MANY CONNECTIONS
Error Description
GROUPING ERROR
INVALID NAME
NAME TOO LONG
RESERVED NAME
DATATYPE MISMATCH
INDETERMINATE DATATYPE
WRONG OBJECT TYPE
UNDEFINED COLUMN
UNDEFINED FUNCTION
UNDEFINED TABLE
UNDEFINED PARAMETER
UNDEFINED OBJECT
DUPLICATE COLUMN
DUPLICATE CURSOR
DUPLICATE DATABASE
DUPLICATE FUNCTION
DUPLICATE TABLE
DUPLICATE ALIAS
DUPLICATE OBJECT
AMBIGUOUS COLUMN
AMBIGUOUS FUNCTION
AMBIGUOUS PARAMETER
AMBIGUOUS ALIAS
INVALID COLUMN REFERENCE
INVALID COLUMN DEFINITION
INVALID CURSOR DEFINITION
INVALID DATABASE DEFINITION
INVALID FUNCTION DEFINITION
INVALID TABLE DEFINITION
INVALID OBJECT DEFINITION
V--208 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Table 9-16 Error Code Class 54 - Program Limit Exceeded
Error Code Error Description
54000
54001
54011
54023
PROGRAM LIMIT EXCEEDED
STATEMENT TOO COMPLEX
TOO MANY COLUMNS
TOO MANY ARGUMENTS
Table 9-17 Error Code Class 55 - Object Not In Prerequisite State
Error Code Error Description
55000
55006
55P03
OBJECT NOT IN PREREQUISITE STATE
OBJECT IN USE
LOCK NOT AVAILABLE
Table 9-18 Error Code Class XX - Internal Error
Error Code Error Description
XX000 INTERNAL ERROR
December 14, 2011 Error Codes V--209
Aster Data proprietary and confidential
V--210 Database SQL and Function Reference, version 4.6.2
aster data
Index
A
access permissions, V-188 list of SQL-MapReduce privileges, V-188 managing using schemas, V-188
account
activity statistics tables, V-194
aggregate window functions, V-146
aggregates of aggregates, V-152
used inside a window function definition, V-152
alias, V-77 column name alias, V-77 required for subselects, V-77 table name alias, V-77
set DEFAULT value for column, V-10
ANALYZE, V-17 command reference, V-17
ARE, RE, BRE, and ERE, switching between, V-117
AS, V-77 column alias, V-77 table alias, V-77
December 14, 2011
autopartitioning
cumulative running average, V-150 moving average, V-150
B
back reference in regex, V-115 backslash, V-115 in regex, V-115
bigint, serialized, V-162 bigserial, V-162 bigserial column, V-162
bit_length operator for bit strings, character strings, V-103
checking a Boolean value, V-97
C
GRANT table privileges and, V-61
Index V--211
case-sensitivity in identifiers, V-200
CAST, V-179 cast datatype to another type, V-179
character set encoding
UTF-8 is the default, V-29 character support, V-29
character value, manipulating, V-100 char_length function, V-100
CHECK
child table
change inheritance with ALTER TABLE, V-12
create with CREATE TABLE, V-37
inheriting parent table privileges, V-61
clock_timestamp() function, V-124
CLUSTER, V-21 partitioning and, V-21
list of columns in database, V-190
column naming conventions, V-199
command reference, V-3 commands, V-3
compatibility of nCluster with PostgreSQL, V-3
compress data
compression
concatenate
conditional SQL expressions, V-131
configuration
configuration flag, V-154 enableDeprecatedWindowFunctionAliasBehaviour, V-
V--212 Database SQL and Function Reference, version 4.6.2
ALTER TABLE’s ADD command, V-11
error-capture tables for, V-196
count characters in string, V-101
revoke user’s right to create tables, V-72
cumulative running average, V-150
CURRENT ROW in window frame, V-148
D data
database
default character encoding, V-29
arbitrary precision numbers, V-160
bit and bit varying, operations on, V-103
casting to another type, V-179
date and time functions, V-123
date and time, reformatting, V-121
formatting functions for, V-121
aster data
listing from SQL prompt, V-193
datatype formatting functions, V-121
templates for formatting, V-121
date datatype
date values, retrieving, V-168
day in timestamp, V-125 day of week in timestamp, V-125 day of year in timestamp, V-125
default character encoding for databases, V-29
DEFAULT values for a column, V-10
DELETE, V-49 delete rows, V-49
delimited identifier, V-200 delimited identifier (object name), V-200 delimiters, V-200
distribution key
declaring in CREATE TABLE, V-36
documentation conventions, V-v
documentation version and updates, V-vii
double precision datatype, V-161
dow in timestamp, V-125 doy in timestamp, V-125
December 14, 2011
E
encoding
error codes, V-205 list of error codes in nCluster, V-205
error logging
statistics about loading attempts, V-197
tables to capture load errors, V-196
tables to capture load errors, custom, V-197
escape character
regex escape characters, V-115 escape characters in regex, V-115
exclamation point in regex, V-110
synopsis, V-124 extract subset of date/time value, V-124
F
float and float(p) datatypes, V-161 floating point datatypes, V-161
ROWS-type vs. RANGE-type, V-149
usage note re: UNBOUNDED L/R sides, V-153
free space
VACUUM command reference, V-92
Index V--213
G
get latest documentation, V-vii
GREATEST SQL commands
greedy regular expression, V-118
group
GROUP BY
H
hexadecimal, convert to, V-103
I
identifier, quoted or delimited, V-200
V--214 Database SQL and Function Reference, version 4.6.2
null values and indexing, V-30
indexing
inequality, checking for, V-97
infinity as floating-point type, V-161
INHERIT
ALTER TABLE option, V-12 change inheritance with ALTER TABLE, V-12
inheritance
CREATE TABLE option, V-37 limitations on inheritance, V-37 what is and what is not inherited?, V-37
input format, time and date values, V-165
example using VALUES to insert multiple rows, V-65
INSERT INTO ... SELECT ... statement, V-64
installed files
int, int2, int4, and int8 datatypes, V-160
IP address range datatype, V-174
ip4range
IS NULL
J join
justify_days function, V-124 justify_interval function, V-124
aster data
K
known issues
L
leading spaces, trimming, V-102
LEAD() function, V-145 example, V-145
length operator for bit strings, character strings, V-103
load
loading log
handling nulls in COPY loads, V-24
logical partitioning
GRANT table privileges and, V-61
Logical Partition-Related System Tables, V-192
lowercase, to, V-100 lower() function, V-100
M
md5 hash, V-102 md5() function, V-102
microseconds in timestamp, V-126 millenium in timestamp, V-126 milliseconds in timestamp, V-126
December 14, 2011
N
naming, V-199 naming conventions, V-199
nCluster-PostgreSQL command compatibility, V-3
ncluster_loader
error-capture tables for, V-196
nc_all_databases, V-187 nc_all_group_members, V-187
nc_all_transactions, V-195 nc_all_transaction_phases, V-195
nc_users, V-186 nc_user_ tables, V-186
nc_user_owned_constraints, V-191
nc_user_owned_databases, V-187
negative infinity as floating-point type, V-161
network address
network address datatypes, V-172
node
node state in system tables, V-193
serialize values across all nodes, V-162
Index V--215
nPath
null
handling nulls in COPY loads, V-24
null value, checking for, in SQL, V-96
numbering window functions, V-139
O
GRANT on database objects, V-61
object naming conventions, V-199
octet_length operator for bit strings, character strings, V-103
octet_length() function, V-100
ON
ON DUPLICATE KEY UPDATE: Use MERGE instead, V-66
consistent sorting of window function input rows, V-153
PARTITION BY should always be used, V-156
output format, time and date values, V-168
OVER, V-137 in window function, V-137
not used to sort output, V-138
sort order of input rows, V-146
V--216 Database SQL and Function Reference, version 4.6.2
P
padding out text strings, V-101
parameter, V-83 performance settings, V-83
SET value, V-83 settings for SQL, V-83
change inheritance with ALTER TABLE, V-12
declare parent of new child table, V-37
passing along table privileges to children, V-61
always include when sorting, V-156
performance considerations, V-154
partition key
cannot add to or drop from existing table, V-13
CREATE TABLE AS with partition key, V-42
partition key: See distribution key
partitioning
automatic partition during COPY, V-25
repartitioning perfomance for window functions, V-154
list of approaches to pattern matching, V-108
with POSIX regular expression, V-110
pattern matching functions, V-108
avoiding scanning for IS NULL, V-30
permissions
list of SQL-MapReduce privileges, V-188
schemas for setting user rights, V-188
pipe operator for concatenation, V-100
position operator for bit strings, character strings, V-103
POSIX regular expression, V-110
PostgreSQL-nCluster command compatibility, V-3
cannot add to or drop from existing table, V-13
declaring in CREATE TABLE, V-38
aster data
Q
QTR in timestamp, V-127 quarter in timestamp, V-127
query
quote characters, V-200 quoted identifier, V-200 quoted identifier (object name), V-200
quote_ident() function, V-102 quote_literal() function, V-102
R
RANGE UNBOUNDED FOLLOWING, V-148
RANGE UNBOUNDED PRECEDING, V-148
RANGE UNBOUNDED PRECEDING example, V-150
RANGE-based window frames, V-149
compared with DENSE_RANK(), V-141
regex types, switching between, V-117
regexp_replace() function, V-102
regexp_split_to_table() function, V-102
greedy or not, V-118 matching rules, V-118
RE vs. ERE vs. ARE vs. BRE, V-112
regex types, switching between, V-117
regular expressions
rename queried column with AS, V-77 rename queried table with AS, V-77
December 14, 2011
replace characters in a string, V-103
REPLACE INTO: Use MERGE instead, V-66
revoke user’s right to create tables, V-72
rights, applying to users, V-31
ROWS UNBOUNDED FOLLOWING, V-148
ROWS UNBOUNDED PRECEDING, V-148
ROWS-based window frames, V-149
rpad() function, V-102 rtrim() function, V-102
runtime settings
S
scanning, avoiding for IS NULL queries, V-30
list of schemas in database, V-188
schema search path
search_path
security
SQL-MapReduce system tables for, V-188
AS keyword for column alias, V-77
AS keyword for table alias, V-77
creating a table with SELECT output, V-42
Index V--217
serial, V-162 serial column, V-162
primary key declaration not recommended, V-163
server-side cursors, V-46 in SQL, V-46
session statistics, V-194 sessions statistics, V-194
SET, V-83 command reference, V-83
settings
shift left, bitwise operator, V-103 shift right, bitwise operator, V-103
SHOW, V-85 command reference, V-85
single quotes
for time and date values, V-165
space
spaces in table and column names, V-200
spaces, trimming leading spaces, V-102 split_part() function, V-102
SQL command compatibility, V-3
V--218 Database SQL and Function Reference, version 4.6.2
ORDER BY in a window function, V-137
PARTITION BY in a window function, V-137
SQL functions
regexp_replace, V-111 regexp_split_to_table, V-111
SQL-MapReduce
repartitioning perfomance, V-154
square brackets for quoting, V-200
statements, list of statements run, V-195
statistics tables, V-194 stats db, V-194 statsdb, V-194
count characters in, V-101 padding out with filler text, V-101
splitting, V-102 trim spaces or characters, V-102
string value, manipulating, V-100
substring operator for bit strings, character strings, V-103
substring, finding, V-100 substring() function, V-100
SUM() function
aster data
nc_all_child_partitions, V-192
nc_all_databases, V-187 nc_all_group_members, V-187
nc_all_transactions, V-195 nc_all_transaction_phases, V-195
nc_user_child_partitions, V-192
nc_user_owned_child_partitions, V-192
nc_user_owned_constraints, V-191
nc_user_owned_databases, V-187
T table
list of tables in database, V-190
revoke user’s right to create tables, V-72
table naming conventions, V-199
technical support, V-vi telephone number, V-vi
TEMPORARY privilege not supported, V-63
temporary system tables, V-198
December 14, 2011
clock_timestamp() function, V-124
templates for formatting, V-121
time values, retrieving, V-168
time zone, V-165 in data input, V-165
extract subset, V-124 vs. now() function, V-124
to_number function, V-121 to_timestamp function, V-121
transaction
start time of transaction, V-124
TRIGGER privilege not supported, V-63
trim spaces or characters from strings, V-102
troubleshooting
cannot update or drop table, V-46
listing from SQL prompt, V-193
U
unique ID across cluster, V-162
universally unique identifier, V-178
Index V--219
cannot update a partition key value, V-90
uppercase, to, V-101 upper() function, V-101
user
permissions list for SQL-MapReduce, V-188 permissions set using schemas, V-188
UTF-8
utilities
V
VACUUM, V-92 command reference, V-92
VALUES
VALUES clause
not supported in nCluster SELECT, V-82
version
virtual worker
memory settings per worker, V-85
W
whitespace in table and column names, V-200
wildcard character, V-77 column sort order, V-77
WINDOW clause: not supported, V-156
window function
consistent sorting of input rows, V-153
repartitioning perfomance, V-154
aggregate window functions, V-146
V--220 Database SQL and Function Reference, version 4.6.2
numbering window functions, V-139
usage note regarding frames, V-153
worker node
memory settings per virtual worker, V-85
X
Y
Symbols
, , =, != operators in SQL, V-96
aster data
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
advertisement
Table of contents
- 5 Conventions Used in This Guide
- 5 Typefaces
- 5 SQL Text Conventions
- 6 Command Shell Text Conventions
- 6 Contacting Technical Support
- 6 About Aster Data
- 7 About This Document
- 14 ABORT
- 14 ABORT -- abort the current transaction
- 14 Synopsis
- 14 Description
- 14 Parameters
- 14 Notes
- 14 Examples
- 14 Compatibility
- 14 See Also
- 15 ALTER INDEX
- 15 ALTER INDEX -- change the definition of an index
- 15 Synopsis
- 15 Description
- 15 Parameters
- 15 Notes
- 15 Examples
- 15 Compatibility
- 15 ALTER ROLE
- 15 ALTER ROLE -- change a database role
- 15 Synopsis
- 16 Description
- 16 Parameters
- 16 Notes
- 16 Compatibility
- 16 See Also
- 16 ALTER SCHEMA
- 16 Synopsis
- 16 Description
- 16 Parameters
- 17 See Also
- 17 ALTER TABLE
- 17 ALTER TABLE -- change the definition of a table
- 17 Synopsis
- 18 Description
- 18 Actions for ALTER TABLE
- 21 Parameters for ALTER TABLE
- 21 Notes About ALTER TABLE
- 21 ALTER TABLE Examples
- 23 Compatibility of ALTER TABLE
- 23 ALTER USER
- 23 ALTER USER - changes attributes of a user
- 23 Synopsis
- 23 Example usage
- 23 Description
- 24 Parameters
- 24 Compatibility
- 24 See Also
- 24 ALTER VIEW
- 24 ALTER VIEW -- change the definition of a view
- 24 Synopsis
- 24 Description
- 25 Parameters
- 25 Notes
- 25 Examples
- 25 Compatibility
- 25 See Also
- 25 ANALYZE
- 25 ANALYZE -- collect statistics about a database
- 25 Synopsis
- 25 Description
- 26 Parameters
- 26 Outputs from ANALYZE
- 26 Notes About ANALYZE
- 26 Compatibility
- 26 See Also
- 26 BEGIN
- 26 BEGIN -- start a transaction block
- 26 Synopsis
- 26 Description
- 27 Parameters
- 27 Notes
- 27 Examples
- 27 Compatibility
- 27 See Also
- 28 CASE
- 28 CLOSE
- 28 CLOSE -- close a cursor
- 28 Synopsis
- 28 Description
- 28 Parameters for CLOSE
- 28 Notes
- 28 Examples
- 28 Compatibility
- 28 See Also
- 29 CLUSTER
- 29 Synopsis
- 29 Description
- 29 Parameters
- 29 Notes
- 30 Examples
- 30 Compatibility
- 30 COALESCE
- 30 COMMIT
- 30 COMMIT -- commit the current transaction
- 30 Synopsis
- 30 Description
- 30 Parameters
- 30 Notes
- 30 Examples
- 31 Compatibility
- 31 See Also
- 31 COPY
- 31 COPY -- copy data between a client and a table
- 31 Synopsis
- 31 Copy into Aster Database:
- 32 Copy from Aster Database:
- 32 Description
- 32 Parameters for COPY
- 34 Notes About COPY
- 34 Input Formats for COPY
- 34 Text Formatted Input to COPY
- 35 CSV Formatted Input to COPY
- 35 Example Use of COPY
- 36 Compatibility of COPY
- 36 See Also
- 36 CREATE DATABASE
- 36 CREATE DATABASE -- create a new database
- 36 Synopsis
- 36 Description
- 36 Parameters for CREATE DATABASE
- 37 Notes
- 37 Examples
- 37 Compatibility
- 37 CREATE INDEX
- 37 CREATE INDEX -- define a new index
- 37 Synopsis
- 37 Description
- 38 Parameters
- 38 Notes
- 39 Examples
- 39 Compatibility
- 39 See Also
- 39 CREATE ROLE
- 39 Synopsis
- 39 Description
- 39 Parameters
- 40 Notes
- 40 Examples
- 40 Compatibility
- 40 See Also
- 40 CREATE SCHEMA
- 40 CREATE SCHEMA -- define a new schema
- 40 Synopsis
- 41 Description
- 41 Parameters
- 41 See Also
- 42 CREATE TABLE
- 42 CREATE TABLE -- define a new table
- 42 Synopsis
- 43 Description
- 43 Parameters for CREATE TABLE
- 45 Setting Constraints in CREATE TABLE
- 45 Constraint Syntax for CREATE TABLE
- 47 Notes on CREATE TABLE
- 47 Examples of CREATE TABLE
- 48 Compatibility
- 49 See Also
- 49 A Note on Unique Constraints
- 50 CREATE TABLE AS
- 50 CREATE TABLE AS - define a new table from the results of a query
- 50 Synopsis
- 50 Description
- 51 Parameters
- 51 Compatibility
- 51 See Also
- 51 CREATE USER
- 51 CREATE USER
- 51 Synopsis
- 52 Description
- 52 Parameters
- 52 Notes
- 52 Examples
- 52 Compatibility
- 53 Compatibility
- 53 See Also
- 53 CREATE VIEW
- 53 CREATE VIEW
- 53 Synopsis
- 53 Synopsis
- 53 Description
- 53 Parameters
- 54 Notes
- 54 Example
- 54 Compatibility
- 54 See also
- 54 DECLARE
- 54 DECLARE -- define a cursor
- 54 Synopsis
- 55 Description
- 56 Parameters for DECLARE
- 56 Notes on DECLARE
- 57 Examples
- 57 Compatibility of DECLARE
- 57 See Also
- 57 DELETE
- 57 DELETE -- delete rows of a table
- 57 Synopsis
- 57 Description
- 58 Parameters for DELETE
- 58 Outputs
- 58 Notes on DELETE
- 58 Examples
- 59 Compatibility of DELETE
- 59 DROP DATABASE
- 59 DROP DATABASE -- remove a database
- 59 Synopsis
- 59 Description
- 59 Parameters for DROP DATABASE
- 59 Notes
- 59 Compatibility
- 59 See Also
- 59 DROP INDEX
- 59 DROP INDEX -- remove an index
- 59 Synopsis
- 60 Description
- 60 Parameters for DROP INDEX
- 60 Examples
- 60 Compatibility
- 60 See Also
- 60 DROP ROLE
- 60 DROP ROLE -- remove a role from Aster Database
- 60 Synopsis
- 60 Parameters
- 60 Examples
- 60 Description
- 61 Compatibility
- 61 See Also
- 61 DROP SCHEMA
- 61 Synopsis
- 61 Description
- 61 Parameters
- 61 See Also
- 61 DROP TABLE
- 61 DROP TABLE -- remove a table
- 61 Synopsis
- 62 Description
- 62 Parameters
- 62 Examples
- 62 Compatibility
- 62 See Also
- 62 DROP USER
- 62 DROP USER -- delete a user from Aster Database
- 62 Synopsis
- 62 Example Usage
- 62 Description
- 63 Compatibility
- 63 See Also
- 63 DROP VIEW
- 63 DROP VIEW -- remove a view
- 63 Synopsis
- 63 Description
- 63 Parameters
- 63 Examples
- 63 Compatibility
- 63 See Also
- 64 END
- 64 END -- commit the current transaction
- 64 Synopsis
- 64 Description
- 64 Parameters
- 64 Notes
- 64 Examples
- 64 Compatibility
- 64 See Also
- 65 EXPLAIN
- 65 EXPLAIN -- show the execution plan of a statement
- 65 Synopsis
- 65 Description
- 65 Parameters
- 65 Notes
- 65 Compatibility
- 65 See Also
- 65 FETCH
- 65 FETCH -- retrieve rows from a query using a cursor
- 65 Synopsis
- 66 Description
- 67 Parameters
- 67 Output
- 67 Notes
- 68 Examples
- 68 Compatibility
- 68 See Also
- 69 GRANT
- 69 GRANT -- define access privileges
- 69 Synopsis
- 69 Description
- 69 GRANT on Database Objects
- 71 GRANT on Roles
- 71 Notes on GRANT
- 71 Examples
- 71 Compatibility
- 72 See Also
- 72 INSERT
- 72 INSERT -- create new rows in a table
- 72 Synopsis
- 72 Description
- 72 Parameters
- 72 Outputs
- 73 Notes
- 73 Examples
- 73 Working With Default Values
- 74 Compatibility
- 74 MERGE
- 74 MERGE -- update or insert rows of a table based on source data
- 74 Synopsis
- 74 Description
- 75 Parameters and Clauses
- 75 Output
- 75 Notes
- 76 Example
- 76 Compatibility
- 76 See Also
- 77 MOVE
- 77 MOVE -- position a cursor
- 77 Synopsis
- 77 Description
- 77 Output
- 77 Examples
- 77 Compatibility
- 77 See Also
- 78 REINDEX
- 78 REINDEX -- rebuild indexes
- 78 Synopsis
- 78 Description
- 78 Parameters
- 78 Notes
- 79 Examples
- 79 Compatibility
- 79 REVOKE
- 79 REVOKE -- remove access privileges
- 79 Synopsis
- 79 Description
- 80 Notes
- 81 Examples
- 81 Compatibility
- 81 See Also
- 82 ROLLBACK
- 82 ROLLBACK -- abort the current transaction
- 82 Synopsis
- 82 Description
- 82 Parameters
- 82 Notes
- 82 Examples
- 82 Compatibility
- 82 See Also
- 83 SELECT
- 83 SELECT -- retrieve rows from a table or view
- 83 Synopsis of SELECT
- 84 Description of SELECT
- 84 Clauses of the SELECT Statement
- 85 The SELECT List
- 85 FROM Clause in SELECT
- 86 WHERE Clause in SELECT
- 86 GROUP BY Clause in SELECT
- 87 HAVING Clause in SELECT
- 87 UNION Clause in SELECT
- 87 INTERSECT Clause in SELECT
- 88 EXCEPT Clause in SELECT
- 88 ORDER BY Clause in SELECT
- 89 DISTINCT Clause in SELECT
- 89 LIMIT Clause in SELECT
- 90 Examples of SELECT Statements
- 90 Compatibility of SELECT
- 90 Omitted FROM Clauses
- 90 No Support for VALUES Clause
- 90 Namespace Available to GROUP BY and ORDER BY
- 91 Nonstandard Clauses
- 91 SET
- 91 SET -- Set the value of a runtime configuration parameter
- 91 Synopsis
- 91 Description
- 91 Scope of a Parameter Setting
- 91 Runtime Parameters
- 93 Examples Using SET
- 93 Compatibility
- 93 See Also
- 93 SHOW
- 93 SHOW -- Display value of a run-time configuration parameter
- 93 Synopsis
- 93 Description
- 94 Parameters for SHOW
- 94 Example of SHOW
- 94 Compatibility
- 95 See Also
- 95 START TRANSACTION
- 95 START TRANSACTION -- start a transaction block
- 95 Synopsis
- 95 Description
- 95 Parameters
- 95 Notes
- 95 Example
- 95 Compatibility
- 95 See Also
- 96 TRUNCATE
- 96 TRUNCATE -- empty a table or set of tables
- 96 Synopsis
- 96 Description
- 96 Parameters
- 96 Notes
- 96 Examples
- 96 Compatibility
- 97 See Also
- 97 UPDATE
- 97 UPDATE -- update rows of a table
- 97 Synopsis
- 97 Description
- 98 Parameters
- 98 Outputs
- 98 Notes
- 98 Examples
- 99 Compatibility
- 100 VACUUM
- 100 VACUUM -- garbage-collect and optionally analyze a table (or, if cluster is so configured, a database)
- 100 Synopsis
- 100 Description
- 101 Parameters
- 101 Outputs
- 101 Notes
- 102 Compatibility
- 102 See Also
- 102 WITH
- 102 WITH -- convenience syntax that lets you declare and name a sub-SELECT query
- 102 Synopsis
- 102 Description
- 103 Logical Operators
- 104 Comparison Operators
- 105 Mathematical Operators and Functions
- 107 Trigonometric Functions
- 108 String Functions and Operators
- 108 SQL String Functions and Operators
- 109 Additional String Functions and Operators
- 111 Bit String Functions and Operators
- 111 SQL/MapReduce Functions
- 112 Synopsis
- 112 nPath
- 112 nPath Synopsis
- 113 nPath Pattern
- 113 nPath Symbols
- 113 nPath Operators
- 114 Nesting parentheses in nPath
- 114 nPath Anchors
- 114 nPath Examples
- 114 nPath Example 1: Lead
- 114 nPath Example 2: Rank
- 115 nPath Example 3: Complex Path Query
- 115 nPath Aggregates
- 116 Pattern Matching Functions and Operators
- 116 LIKE
- 117 SIMILAR TO Regular Expressions
- 118 SUBSTRING Function with Three Parameters
- 118 POSIX Regular Expressions
- 119 SUBSTRING Function with Two Parameters
- 119 regexp_replace Function
- 119 regexp_split_to_table Function
- 119 Some regexp_split_to_table Examples
- 120 Regular Expression Details
- 122 Bracket Expressions
- 123 Regular Expression Escapes
- 125 Regular Expression Metasyntax
- 126 Regular Expression Matching Rules
- 128 Limits and Compatibility
- 128 Basic Regular Expressions
- 129 Datatype Formatting Functions and Operators
- 131 Date/Time Functions and Operators
- 131 Date/Time Operators
- 132 Date/Time Functions
- 132 EXTRACT Function
- 133 century Field Name
- 133 day Field Name
- 133 decade Field Name
- 133 dow Field Name
- 133 doy Field Name
- 133 epoch Field Name
- 134 hour Field Name
- 134 microseconds Field Name
- 134 millenium Field Name
- 134 milliseconds Field Name
- 134 minute Field Name
- 134 month Field Name
- 135 quarter Field Name
- 135 second Field Name
- 135 timezone Field Name
- 135 week Field Name
- 135 year Field Name
- 135 date_part Function
- 136 date_trunc Function
- 136 date_trunc Arguments
- 136 date_trunc Examples
- 137 Current Date/Time
- 138 Aggregate Functions
- 138 Aggregate Functions for Statistics
- 139 Conditional SQL Expressions
- 139 CASE
- 140 COALESCE
- 141 NULLIF
- 141 GREATEST and LEAST
- 141 Subquery SQL Expressions
- 141 EXISTS
- 141 IN
- 142 NOT IN
- 142 ANY/SOME
- 143 ALL
- 145 Synopsis of Window Function Syntax
- 146 Window Function Order of Evaluation
- 147 Numbering Window Functions
- 147 ROW_NUMBER()
- 147 RANK()
- 148 DENSE_RANK()
- 148 Numbering Window Function Examples
- 148 Window Function Example 1: ROW_NUMBER()
- 148 Window Function Example 2: RANK()
- 149 Window Function Example 3: DENSE_RANK()
- 150 Window Function Example 4: Output Row Ordering
- 151 Window Function Example 5: Multiple RANK()s
- 151 Window Function Example 6: Attributes
- 152 Window Function Example 7: Expressions, Improper Use
- 152 Window Function Example 8: Expressions, Proper Use
- 153 LEAD and LAG functions
- 153 Syntax
- 153 LEAD/LAG Examples
- 153 Window Function Example 9: LEAD()
- 154 Window Function Example 10: LAG()
- 154 Aggregate Window Functions
- 155 Window Frame Syntax
- 156 Window Frame Requirements
- 156 Valid Examples
- 156 Invalid Examples
- 157 ORDER BY Required
- 157 Window Frame Types: ROWS vs. RANGE
- 157 Window Function Example 11: Running AVG()
- 158 Window Function Example 12: Moving AVG()
- 158 Window Function Example 13: Cumulative Running AVG()
- 159 The Default Window Frame
- 159 Window Function Example 14: Running SUM()
- 160 Window Function Example 15: ORDER BY SUM()
- 160 Window Function Example 16: SUM(SUM(n))
- 161 Consistent Sort Behavior of Input Rows
- 161 Warning: Rewrite When Using Specific Left Endpoint and Unbounded Right Endpoint
- 162 Repartitioning Performance for Window Functions and SQL-MapReduce Queries
- 162 Deprecated Behavior
- 163 Examples of the Old Aliasing Behavior
- 163 Example That Uses an Alias in a Window Function (Deprecated)
- 163 Window Function Known Issues
- 163 COUNT(*)
- 164 ORDER BY without PARTITION BY
- 164 Use in SELECT Clause Only
- 164 No Support for WINDOW Clause
- 164 Size Limit of Sliding Window Frames
- 164 Limited Support for RANGE-Based Window Frames
- 165 List of Supported Datatypes
- 165 List of Types
- 166 Compatibility
- 167 Numeric Types
- 167 Integer Types
- 168 Arbitrary Precision Numbers
- 169 Floating-Point Types
- 170 Serial Types
- 170 Local and Global
- 170 Creating Columns of Type Serial
- 170 Automatic Numbering
- 171 Primary Key Constraint Not Recommended on Serial Columns
- 171 Actual Datatype of a Serial Column
- 171 Character Types
- 172 Storage Requirements
- 172 Tip for Using Character Types
- 172 Examples
- 173 Date/Time Types
- 173 Date/Time Input
- 174 Date Input Formats
- 174 Time Input Formats
- 175 Time Stamp Input Formats
- 176 Intervals
- 176 Date/Time Output
- 177 Time Zones
- 177 Bit String Types
- 177 Boolean Types
- 177 Allowed Boolean Values
- 178 Examples
- 178 Binary Types
- 179 Entering bytea Values
- 179 bytea Output Representations
- 180 Compatibility
- 180 Network Address Types
- 180 ip4 and ip4range Datatypes in Aster Database
- 180 Simple usage examples
- 181 ip4 Datatype
- 181 Type Conversions
- 182 Operators and Functions
- 182 ip4range Datatype
- 183 Typecasting for ip4range
- 183 Functions for ip4range
- 183 Operators for ip4range
- 184 GiST Indexes (ip4range Indexes)
- 184 Use Cases for ip4range
- 185 Examples Using ip4 and ip4range
- 185 Example: GiST indexes
- 185 Example: Joins on IP addresses and ranges
- 185 Examples: IP address-related functions and operators
- 186 UUID Type
- 187 Type Casts
- 189 Date/Time Input Interpretation
- 190 Date/Time Keywords
- 190 Month Names
- 190 Day-of-Week Names
- 191 Date Time Field Modifiers
- 194 Introduction to Data Dictionary Views
- 194 User-Related Data Dictionary Views
- 195 Role-Related Data Dictionary Views
- 195 Group Membership Data Dictionary Views
- 195 Database-Related Data Dictionary Views
- 196 Schema-Related Data Dictionary Views
- 196 SQL-MapReduce and Installed File-Related Data Dictionary Views
- 196 nc_user_installed_files, nc_user_owned_installed_files, nc_all_ installed_files
- 197 nc_user_sqlmr_funcs, nc_user_owned_sqlmr_funcs, nc_all_sqlmr_ funcs
- 197 nc_user_sqlmr_func_privs, nc_user_owned_sqlmr_func_privs, nc_ all_sqlmr_func_privs
- 198 Table-Related Data Dictionary Views
- 198 Column-Related Data Dictionary Views
- 199 Index-Related Data Dictionary Views
- 199 Constraint-Related Data Dictionary Views
- 200 Logical Partition-Related Data Dictionary Views
- 201 Inheritance-Related Data Dictionary Views
- 201 Types Data Dictionary View
- 201 Cluster State Data Dictionary Views
- 201 Physical Node State: nc_physical_node_state
- 202 Storage State: nc_cluster_storage
- 202 Activity Data Dictionary Views
- 202 Session Statistics: nc_all_sessions
- 203 Transaction Statistics: nc_all_transactions
- 203 Transaction Phases: nc_all_transaction_phases
- 203 Statement Statistics: nc_all_statements
- 204 Load Error Logging Tables
- 204 Schema of the Load Error Logging Tables
- 204 Sample Entries in a Load Error Logging Table
- 205 Creating a Load Error Logging Table
- 205 Load Error Statistics Tables
- 206 Temporary Data Dictionary Views
- 207 Identifiers, Keywords, and Naming Conventions
- 208 Quoted Identifiers
- 209 Comments in SQL
- 209 Value Expressions
- 210 Column References
- 219 A
- 219 B
- 219 C
- 220 D
- 221 E
- 221 F
- 222 G
- 222 H
- 222 I
- 222 J
- 223 K
- 223 L
- 223 M
- 223 N
- 224 O
- 224 P
- 225 Q
- 225 R
- 225 S
- 227 T
- 227 U
- 228 V
- 228 W
- 228 X
- 228 Y
- 228 Symbols