Download Contents Aster SQL and Function Reference

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
Preface .............................................................................................................................................................
V--v
Conventions Used in This Guide ............................................................................................................... V--v
Contacting Technical Support ................................................................................................................ V--vi
About Aster Data ....................................................................................................................................... V--vi
About This Document ............................................................................................................................... V--vii
Aster SQL and Function Reference
V--1
V--1 SQL Commands
V--3
ABORT ........................................................................................................................................................... V--6
ALTER INDEX ................................................................................................................................................. V--7
ALTER ROLE ................................................................................................................................................... V--7
ALTER SCHEMA ............................................................................................................................................. V--8
ALTER TABLE .................................................................................................................................................. V--9
ALTER USER ................................................................................................................................................. V--15
ALTER VIEW ................................................................................................................................................. V--16
ANALYZE ...................................................................................................................................................... V--17
BEGIN .......................................................................................................................................................... V--18
CASE ............................................................................................................................................................ V--20
CLOSE .......................................................................................................................................................... V--20
CLUSTER ...................................................................................................................................................... V--21
COALESCE .................................................................................................................................................. V--22
COMMIT ...................................................................................................................................................... V--22
COPY ........................................................................................................................................................... V--23
CREATE DATABASE ..................................................................................................................................... V--28
CREATE INDEX ............................................................................................................................................ V--29
CREATE ROLE .............................................................................................................................................. V--31
CREATE SCHEMA ....................................................................................................................................... V--32
CREATE TABLE ............................................................................................................................................. V--34
CREATE TABLE AS ....................................................................................................................................... V--42
CREATE USER .............................................................................................................................................. V--43
CREATE VIEW .............................................................................................................................................. V--45
DECLARE ..................................................................................................................................................... V--46
DELETE ......................................................................................................................................................... V--49
DROP DATABASE ........................................................................................................................................ V--51
DROP INDEX ................................................................................................................................................ V--51
December 14, 2011
V--i
DROP ROLE .................................................................................................................................................
DROP SCHEMA ...........................................................................................................................................
DROP TABLE ................................................................................................................................................
DROP USER ..................................................................................................................................................
DROP VIEW .................................................................................................................................................
END ..............................................................................................................................................................
EXPLAIN .......................................................................................................................................................
FETCH ..........................................................................................................................................................
GRANT .........................................................................................................................................................
INSERT ..........................................................................................................................................................
MERGE .........................................................................................................................................................
MOVE ..........................................................................................................................................................
REINDEX ......................................................................................................................................................
REVOKE .......................................................................................................................................................
ROLLBACK ...................................................................................................................................................
SELECT .........................................................................................................................................................
SET ...............................................................................................................................................................
SHOW ..........................................................................................................................................................
START TRANSACTION .................................................................................................................................
TRUNCATE ...................................................................................................................................................
UPDATE ........................................................................................................................................................
VACUUM .....................................................................................................................................................
WITH .............................................................................................................................................................
V--2 Functions and Operators
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
Logical Operators ..................................................................................................................................... V--95
Comparison Operators ............................................................................................................................ V--96
Mathematical Operators and Functions ............................................................................................... V--97
Trigonometric Functions ........................................................................................................................... V--99
String Functions and Operators ............................................................................................................ V--100
Bit String Functions and Operators ....................................................................................................... V--103
SQL/MapReduce Functions .................................................................................................................. V--103
nPath ......................................................................................................................................................... V--104
Pattern Matching Functions and Operators ....................................................................................... V--108
Datatype Formatting Functions and Operators ................................................................................. V--121
Date/Time Functions and Operators ................................................................................................... V--123
Aggregate Functions .............................................................................................................................. V--130
Aggregate Functions for Statistics ........................................................................................................ V--130
Conditional SQL Expressions ................................................................................................................. V--131
Subquery SQL Expressions ..................................................................................................................... V--133
V--3 Window Functions
V--137
Synopsis of Window Function Syntax ...................................................................................................
Window Function Order of Evaluation .................................................................................................
Numbering Window Functions ..............................................................................................................
LEAD and LAG functions ........................................................................................................................
Aggregate Window Functions ..............................................................................................................
Repartitioning Performance for Window Functions and SQL-MapReduce Queries .....................
Deprecated Behavior .............................................................................................................................
Window Function Known Issues ............................................................................................................
V--4 Datatypes
V--137
V--138
V--139
V--145
V--146
V--154
V--154
V--155
V--157
List of Supported Datatypes .................................................................................................................. V--157
Numeric Types ......................................................................................................................................... V--159
V--ii
Database SQL and Function Reference, version 4.6.2
aster data
Character Types ......................................................................................................................................
Date/Time Types .....................................................................................................................................
Bit String Types .........................................................................................................................................
Boolean Types .........................................................................................................................................
Binary Types .............................................................................................................................................
Network Address Types ..........................................................................................................................
UUID Type .................................................................................................................................................
Type Casts ................................................................................................................................................
V--5 Date and Time
V--163
V--165
V--169
V--169
V--170
V--172
V--178
V--179
V--181
Date/Time Input Interpretation ............................................................................................................. V--181
Date/Time Keywords .............................................................................................................................. V--182
V--6 Data Dictionary Views
Introduction to Data Dictionary Views .................................................................................................
User-Related Data Dictionary Views .....................................................................................................
Role-Related Data Dictionary Views ....................................................................................................
Group Membership Data Dictionary Views ........................................................................................
Database-Related Data Dictionary Views ..........................................................................................
Schema-Related Data Dictionary Views .............................................................................................
SQL-MapReduce and Installed File-Related Data Dictionary Views ...............................................
Table-Related Data Dictionary Views ..................................................................................................
Column-Related Data Dictionary Views ..............................................................................................
Index-Related Data Dictionary Views ..................................................................................................
Constraint-Related Data Dictionary Views ..........................................................................................
Logical Partition-Related Data Dictionary Views ................................................................................
Inheritance-Related Data Dictionary Views ........................................................................................
Types Data Dictionary View ..................................................................................................................
Cluster State Data Dictionary Views ....................................................................................................
Activity Data Dictionary Views ..............................................................................................................
Temporary Data Dictionary Views ........................................................................................................
V--7 SQL Vocabulary
V--185
V--186
V--186
V--187
V--187
V--187
V--188
V--188
V--190
V--190
V--191
V--191
V--192
V--193
V--193
V--193
V--194
V--198
V--199
Identifiers, Keywords, and Naming Conventions ............................................................................... V--199
Comments in SQL ................................................................................................................................... V--201
Value Expressions ................................................................................................................................... V--201
System Limits .............................................................................................................................................
V--203
Error Codes ................................................................................................................................................
V--205
Index ..............................................................................................................................................................
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:
•
SQL Commands (page V-3)
•
Functions and Operators (page V-95)
•
Window Functions (page V-137)
•
Datatypes (page V-157)
•
Date and Time (page V-181)
•
Data Dictionary Views (page V-185)
•
SQL Vocabulary (page V-199)
•
System Limits (page V-203)
•
Error Codes (page V-205)
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?
ABORT (page V-6)
Yes
Yes
ALL (page V-135)
Yes
Yes
ALTER INDEX (page V-7)
Yes
Yes
ALTER ROLE (page V-7)
Yes
Yes
ALTER SCHEMA (page V-8)
Yes
Yes
ALTER TABLE (page V-9)
Yes
Yes
ALTER USER (page V-15)
Yes
Yes
ALTER VIEW (page V-16)
Yes
Yes
ANALYZE (page V-17)
Yes
Yes
ANY/SOME (page V-134)
Yes
Yes
BEGIN (page V-18)
Yes
Yes
CASE (page V-131)
Yes
Yes
CHECKPOINT
NO
Yes
CLOSE (page V-20)
Yes
Yes
CLUSTER (page V-21)
Yes
Yes
COALESCE (page V-132)
Yes
Yes
COMMENT
NO
Yes
COMMIT (page V-22)
Yes
Yes
COPY (page V-23)
Yes
Yes
CREATE DATABASE (page V-28)
Yes
Yes
CREATE INDEX (page V-29)
Yes
Yes
CREATE ROLE (page V-31)
Yes
Yes
CREATE SCHEMA (page V-32)
Yes
Yes
December 14, 2011
Notes
Aster Data proprietary and confidential V--3
Aster Data proprietary and confidential
Statement
Supported
in Aster
Database?
Supported in
PostgreSQL?
CREATE TABLE (page V-34)
Yes
Yes
CREATE TABLE AS (page V-42)
Yes
Yes
CREATE USER (page V-43)
Yes
Yes
CREATE VIEW (page V-45)
Yes
Yes
DEALLOCATE
NO
Yes
DECLARE (page V-46)
Yes
Yes
DELETE (page V-49)
Yes
Yes
DROP DATABASE (page V-51)
Yes
Yes
DROP INDEX (page V-51)
Yes
Yes
DROP ROLE (page V-52)
Yes
Yes
DROP SCHEMA (page V-53)
Yes
Yes
DROP TABLE (page V-53)
Yes
Yes
DROP USER (page V-54)
Yes
Yes
DROP VIEW (page V-55)
Yes
Yes
END (page V-56)
Yes
Yes
EXECUTE
NO
Yes
EXISTS (page V-133)
Yes
Yes
EXPLAIN (page V-57)
Yes
Yes
EXTRACT Function (page V-124)
Yes
Yes
FETCH (page V-57)
Yes
Yes
GRANT (page V-61)
Yes
Yes
GREATEST and LEAST (page V-133)
Yes
Yes
IN (page V-133)
Yes
Yes
INSERT (page V-64)
Yes
Yes
LISTEN
NO
Yes
LIKE (page V-108)
Yes
Yes
LOAD
NO
Yes
LOCK
NO
Yes
MERGE (page V-66)
Yes
No
MOVE (page V-69)
Yes
Yes
NOT IN (page V-134)
Yes
Yes
NOTIFY
NO
Yes
NULLIF (page V-133)
Yes
Yes
PREPARE
NO
Yes
PREPARE TRANSACTION
NO
Yes
V--4
Database SQL and Function Reference, version 4.6.2
Notes
To load a function, use Aster
Database ACT’s \install
command.
aster data
Aster Data proprietary and confidential
Statement
Supported
in Aster
Database?
Supported in
PostgreSQL?
REASSIGN OWNED
NO
Yes
REINDEX (page V-70)
Yes
Yes
RELEASE SAVEPOINT
NO
Yes
RESET
NO
Yes
REVOKE (page V-71)
Yes
Yes
ROLLBACK (page V-74)
Yes
Yes
SAVEPOINT
NO
Yes
SELECT (page V-75)
Yes
Yes
SET (page V-83)
Yes
Yes
SHOW (page V-85)
Yes
Yes
START TRANSACTION (page V-87)
Yes
Yes
TRUNCATE (page V-88)
Yes
Yes
UNLISTEN
NO
Yes
UPDATE (page V-89)
Yes
Yes
VACUUM (page V-92)
Yes
Yes
WITH (page V-94)
Yes
Yes
December 14, 2011
Notes
SQL Commands V--5
ABORT
Aster Data proprietary and confidential
ABORT
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:
•
BEGIN (page V-18)
•
START TRANSACTION (page V-87)
To finish a transaction:
•
COMMIT (page V-22)
•
END (page V-56)
To cancel a transaction:
•
V--6
ROLLBACK (page V-74)
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
“CREATE ROLE” on page V-31, “DROP ROLE” on page V-52, “GRANT” on page V-61,
“REVOKE” on page V-71.
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
“CREATE SCHEMA” on page V-32 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 CREATE
TABLE. 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 “Notes
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
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.
column
Name of a new or existing column.
new_column
New name for an existing column.
new_name
New name for the table.
type
Datatype of the new column, or new datatype for an existing column.
table_constraint
New table constraint for the table. See “Notes About ALTER TABLE”, below.
constraint_name
Name of an existing constraint to drop. See “Notes About ALTER TABLE”, below.
CASCADE
Automatically drop objects that depend on the dropped column or constraint (for
example, views referencing the column).
RESTRICT
Refuse to drop the column or constraint if there are any dependent objects. This is
the default behavior.
parent_table
The table name of the new parent table.
new_owner
The username of the new owner of the table.
new_schema
The name of the new schema of which the table will be a member.
partition_reference
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).
new_partition_name
The new name to give the partition, when renaming an existing partition.
old_table_name
The name of the table to be attached to a logically partitioned table as a new
partition.
new_table_name
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 USER
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;
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 CREATE USER. 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 GRANT and REVOKE 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 “CREATE USER” on page V-43.
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 ROLE” on page V-7, “CREATE USER” on page V-43
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
ANALYZE
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 -- 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
The name of a table to analyze.
column
The name of a column to analyze. This defaults to all columns.
CASCADE
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
“EXPLAIN” on page V-57 and “VACUUM” on page V-92, 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:
•
START TRANSACTION (page V-87)
To finish a transaction:
•
COMMIT (page V-22)
•
END (page V-56)
To cancel a transaction:
•
ABORT (page V-6)
•
ROLLBACK (page V-74)
December 14, 2011
SQL Commands
V--19
CASE
Aster Data proprietary and confidential
CASE
See “CASE” on page V-131.
CLOSE
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
“DECLARE” on page V-46, “FETCH” on page V-57, and “MOVE” on page V-69.
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: Synopsis | Description | Parameters | Notes | Examples | Compatibility
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:
•
BEGIN (page V-18)
•
START TRANSACTION (page V-87)
To finish a transaction:
•
END (page V-56)
To cancel a transaction:
•
ABORT (page V-6)
•
ROLLBACK (page V-74)
COPY
COPY -- copy data between a client and a table
•
Synopsis (page V-23)
•
Description (page V-24)
•
Parameters for COPY (page V-24)
•
Notes About COPY (page V-26)
•
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
The name of an existing table.
column
An optional list of columns to be copied. If no column list is specified, all
columns of the table will be copied.
STDIN
Specifies that input comes from the client application.
STDOUT
Specifies that output goes to the client application.
delimiter
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.
null string
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 ""
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
CSV
Selects Comma Separated Value (CSV) mode (by default, the input is expected
interpreted using the text format described below).
quote
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
Specifies the character that should appear before a QUOTE data character value
in CSV mode. The default is the QUOTE value (usually double-quote).
Output
On successful completion, a COPY command returns a command tag of the
form:
COPY count
Where count is the number of rows copied.
AUTOPARTITION
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 “Load Error Statistics
Tables” on page V-197.
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. See “Creating a
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
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
NOWHERE instructs the COPY command to discard all malformed rows (and
continue loading correctly formed rows).
ERRORLIMIT limit
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
Backspace (ASCII 8)
\f
Form feed (ASCII 12)
\n
Newline (ASCII 10)
\r
Carriage return (ASCII 13)
\t
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 GRANT for details.
•
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
The name of the index to be created.
table
The name of the table to be indexed.
method
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.
column
The name of a column of the table.
expression
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.
predicate
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
“DROP INDEX” on page V-51.
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
“ALTER ROLE” on page V-7, “DROP ROLE” on page V-52, “GRANT” on page V-61, and
“REVOKE” on page V-71.
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 “DROP SCHEMA” on page V-53.
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
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.
table_name
The name of the table to be created. See “Identifiers,
Keywords, and Naming Conventions” on page V-199.
column_name
The name of a column to be created in the new table.
data_type
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
December 14, 2011
See “Constraint Syntax for CREATE TABLE” on page V-37.
SQL Commands
V--35
CREATE TABLE
DISTRIBUTE BY { HASH ( distribution_
key_column_name ) | REPLICATION }
Aster Data proprietary and confidential
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.
STORAGE { ROW | COLUMN }
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.
COMPRESS [ HIGH | MEDIUM | LOW ]
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 ALTER TABLE
(page V-9).
See “Compression” on page II-8 for an overview of
compression in Aster Database.
PARTITION BY partition_clause
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
INHERITS ( parent_table )
CREATE 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.
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.
NOT NULL
The column is not allowed to contain null values.
NULL
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 )
Deprecated syntax for declaring the table’s distribution key.
In Aster Database 4.6 and later, you should use DISTRIBUTE
BY instead.
PRIMARY KEY (as a column constraint)
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.
PRIMARY KEY ( column_name [, ... ] )
(as a table constraint)
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.
CHECK (expression)
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
UNIQUE (as a column constraint)
UNIQUE ( column_name [, ... ] ) (as a
table constraint)
CREATE TABLE
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
is not necessary to create an index explicitly for primary key columns. (See “CREATE INDEX”
on page V-29 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(
DISTRIBUTE BY HASH(id)
PARTITION BY RANGE(ts)
PARTITION oldrecords(
PARTITION jan01_2011(
PARTITION jan02_2011(
PARTITION jan03_2011(
);
id int, country varchar, ts timestamp )
(
END
END
END
END
'2011-01-01'
'2011-01-02'
'2011-01-03'
'2011-01-04'
), -- everything pre-2011
),
),
)
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
“DROP TABLE” on page V-53
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
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.
table_name
The name of the table to be created.
column_name
The name of a column to be created in the new table.
data_type
The datatype of the column.
query
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.
DISTRIBUTE BY
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 TABLE” on page V-34, “SELECT” on page V-75.
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
“CREATE ROLE” on page V-31, “GRANT” on page V-61, “REVOKE” on page V-71, “ALTER
USER” on page V-15, “DROP USER” on page V-54.
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 | Description | Parameters | Notes | Example | Compatibility
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, DROP 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
DECLARE
CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
[ FOR UPDATE | FOR READ ONLY ];
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
Parameters for DECLARE
name
The name of the cursor to be created.
INSENSITIVE
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
NO SCROLL
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 Notes on DECLARE for details.
WITH HOLD
WITHOUT HOLD
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.
query
A SELECT command that provides the rows to be returned by the cursor.
FOR UPDATE
FOR READ ONLY
will be allowed.
FOR READ ONLY specifies that the cursor will be used in a read-only mode. No data updates
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
DELETE
Examples
To declare a cursor:
DECLARE filmcsr CURSOR FOR SELECT * FROM films;
See “FETCH” on page V-57 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
“CLOSE” on page V-20, “FETCH” on page V-57, and “MOVE” on page V-69.
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
Parameters for DELETE
ONLY
If specified, delete rows from the named table only.
When not specified, any tables inheriting from the named table are also
processed.
table
The name of an existing table.
usinglist
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.
condition
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.
cursor_name
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;
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
name
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
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
name
The name of an index to remove.
CASCADE
Automatically drop objects that depend on the index.
RESTRICT
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
“CREATE INDEX” on page V-29
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 “ALTER ROLE” on page V-7.
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
“CREATE SCHEMA” on page V-32 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
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
IF EXISTS
Do not throw an error if the table does not exist.
name
The name of the table to drop.
CASCADE
Automatically drop objects that depend on the table.
RESTRICT
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
“TRUNCATE” on page V-88, “DELETE” on page V-49, and “CREATE TABLE” on page V-34
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
“CREATE USER” on page V-43, “REVOKE” on page V-71, and “DROP ROLE” on page V-52.
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, CREATE VIEW.
December 14, 2011
SQL Commands
V--55
END
Aster Data proprietary and confidential
END
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:
•
BEGIN (page V-18)
•
START TRANSACTION (page V-87)
To finish a transaction:
•
COMMIT (page V-22)
To cancel a transaction:
•
ABORT (page V-6)
•
ROLLBACK (page V-74)
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
“ANALYZE” on page V-17, and “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
Parameters
direction
direction defines the fetch direction and number of rows to fetch. This
parameter can have one of the values listed below.
NEXT
Fetch the next row. This is the default if direction is omitted.
PRIOR
Fetch the prior row.
FIRST
Fetch the first row of the query (same as ABSOLUTE 1).
LAST
Fetch the last row of the query (same as ABSOLUTE -1).
ABSOLUTE count
Fetch the countth 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.
RELATIVE count
Fetch the countth succeeding row, or the abs(count)th prior row if count
is negative. RELATIVE 0 re-fetches the current row, if any.
ALL
Fetch all remaining rows (same as FORWARD ALL).
FORWARD
Fetch the next row (same as NEXT).
FORWARD count
Fetch the next count rows. FORWARD 0 re-fetches the current row.
FORWARD ALL
Fetch all remaining rows.
BACKWARD
Fetch the prior row (same as PRIOR).
BACKWARD count
Fetch the prior count rows (scanning backwards). BACKWARD 0 re-fetches
the current row.
BACKWARD ALL
Fetch all prior rows (scanning backwards).
count
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.
cursorname
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
“CLOSE” on page V-20, “DECLARE” on page V-46, and “MOVE” on page V-69.
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
[,...] | ALL
ON [ TABLE ]
TO { [ GROUP
| INSERT | UPDATE | DELETE }
[ PRIVILEGES ] }
tablename [, ...]
] 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
“REVOKE” on page V-71. 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 ALTER TABLE 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
INSERT (page V-64), UPDATE (page V-89)
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.
Refer to “FETCH” on page V-57 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
“CLOSE” on page V-20, “DECLARE” on page V-46, and “FETCH” on page V-57.
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
Recreate the specified index.
TABLE
Recreate all indexes of the specified table.
name
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.
FORCE
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
REVOKE
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 -- 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
ON SCHEMA to limit user’s access to objects contained in a schema, see the note in “USAGE”
on page V-62.
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
“GRANT” on page V-61
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:
•
BEGIN (page V-18)
•
START TRANSACTION (page V-87)
To finish a transaction:
•
COMMIT (page V-22)
•
END (page V-56)
To cancel a transaction:
•
ABORT (page V-6)
V--74 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
SELECT
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_items in the form:
from_item [ NATURAL ] join_type from_item
[ ON join_condition | USING ( join_column [, ...] ) ]
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 and “HAVING
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, “INTERSECT 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, JOINs 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
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.
cpu_index_tuple_cost
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
Sets the Local Planner's estimate of the cost of processing each row during a query.
Default value is 0.01
effective_cache_size
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_bitmapscan
Enable or disable the Local Planner's use of bitmap-scan plan types. Default value
is 'on'
enable_hashagg
Enable or disable the Local Planner's use of hashed aggregation plan types. Default
value is 'on'
enable_hashjoin
Enable or disable Local Planner's use of hash-join plan types. Default value is 'on'
enable_indexscan
Enable or disable Local Planner's use of index-scan plan types. Default value is 'on'
enable_mergejoin
Enable or disable Local Planner's use of merge-join plan types. Default value is 'on'
enable_nestloop
Enable or disable Local Planner's use of nested-loop plan types. Default value is
'off'
enable_seqscan
Enable or disable Local Planner's use of sequential-scan plan types. Default value
is 'on'
maintenance_work_mem
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
random_page_cost
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
search_path
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
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
statement_timeout
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
SHOW
Parameter
Description
work_mem
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” on page V-85
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
Description
client_encoding
Show the current client-side encoding (character set). The default encoding is the
database encoding.
cpu_index_tuple_
cost
Show the Local Planner's estimate of the cost of processing each index entry during an
index scan.
cpu_tuple_cost
Set the Local Planner's estimate of the cost of processing each row during the execution
of a query
effective_cache_
size
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.
enable_
bitmapscan
Flag that dictates whether bitmap-scan plan type is enabled for the Local Planner or
not.
enable_hashagg
Flag that dictates whether hashed aggregation plan type is enabled for the Local
Planner or not.
enable_hashjoin
Flag that dictates whether hash join plan type is enabled for the Local Planner or not.
enable_indexscan
Flag that dictates whether index-scan plan type is enabled for the Local Planner or not.
enable_mergejoin
Flag that dictates whether merge-join plan type is enabled for the Local Planner or not.
enable_nestloop
Flag that dictates whether nested-loop plan type is enabled for the Local Planner or not.
enable_seqscan
Flag that dictates whether sequential-scan plan type is enabled for the Local Planner or
not.
maintenance_
work_mem
Show the maximum amount of memory to be used, per virtual worker, for maintenance
operations like VACUUM, CREATE INDEX, and ALTER TABLE.
random_page_cost
Show the Local Planner's current estimate of the cost of a non-sequentially-fetched
page from disk.
search_path
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.
seq_page_cost
Show the Local Planner's current estimate of the cost of fetching a disk page as part of
a series of sequential scans.
statement_
timeout
Show the current value of the upper bound on allowed query execution time. Any query
that takes longer, will be automatically aborted.
work_mem
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
START TRANSACTION
See Also
“SET” on page V-83
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 “BEGIN” on page V-18.
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:
•
BEGIN (page V-18)
To finish a transaction:
•
COMMIT (page V-22)
•
END (page V-56)
December 14, 2011
SQL Commands
V--87
TRUNCATE
Aster Data proprietary and confidential
To cancel a transaction:
•
ABORT (page V-6)
•
ROLLBACK (page V-74)
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 | Description | Parameters | Notes | Examples | Compatibility
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
“DELETE” on page V-49, “VACUUM” on page V-92, 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
Parameters
table
The name of the table to update.
column
The name of a column in table.
expression
An expression to assign to the column. The expression may use the old values
of this and other columns in the table.
fromlist
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).
condition
An expression that returns a value of type Boolean. Only rows for which this
expression returns true will be updated.
cursor_name
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
UPDATE
AND employees.id = accounts.sales_person;
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
Parameters
FULL
Selects "full" vacuum, which may reclaim more space, but takes much longer and exclusively
locks the table.
ANALYZE
Updates statistics used by the planner to determine the most efficient way to execute a query.
tablename
The name of a specific table to vacuum.
columnname
The name of a column to ANALYZE. If omitted, all columns are ANALYZEd.
CASCADE
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
“ANALYZE” on page V-17, and “REINDEX” on page V-70, “TRUNCATE” on page V-88, and
“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
•
“nPath” on page V-104
•
“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
Return Type
Description
NOT
Boolean
Tri-valued Boolean NOT
AND
Boolean
Tri-valued Boolean AND
or
Boolean
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
Return Type
Description
<
Boolean
Binary less than
>
Boolean
Binary greater than
<=
Boolean
Binary less than or equal to
>=
Boolean
Binary greater than or equal to
=
Boolean
Binary equality
!=
Boolean
Binary inequality
<>
Boolean
Binary inequality, the same as !=
BETWEEN
Boolean
Three operand input (a,b,c), evaluates b<=a<=c
NOT BETWEEN
Boolean
Three operand input (a,b,c), the negation of BETWEEN
BETWEEN SYMMETRIC
Boolean
Same as between, except it evaluates c<=a<=b, if c<b
IS
Boolean
Equality check that works with NULL
IS NOT
Boolean
Inequality check that works with NULL
DISTINCT FROM
Boolean
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
is equivalent to:
a < x OR a > y
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
expression
expression
expression
expression
expression
IS
IS
IS
IS
IS
IS
TRUE
NOT TRUE
FALSE
NOT FALSE
UNKNOWN
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
Usable on any numeric
datatype
-
subtraction
2 - 3
-1
Usable on any numeric
datatype
*
multiplication
2 * 3
6
Usable on any numeric
datatype
/
division (integer
division truncates
results)
4 / 2
2
Usable on any numeric
datatype
%
modulo (remainder)
5 % 4
1
Usable on any numeric
datatype
^
exponentiation
2.0 ^ 3.0
8
Usable on any numeric
datatype
|/
square root
|/ 25.0
5
Usable on any numeric
datatype
December 14, 2011
Functions and Operators V--97
Mathematical Operators and Functions
Aster Data proprietary and confidential
||/
cube root
||/ 27.0
3
Usable on any numeric
datatype
!
factorial
5 !
120
Usable on any numeric
datatype
!!
factorial (prefix
operator)
!! 5
120
Usable on any numeric
datatype
@
absolute value
@ -5.0
5
Usable on any numeric
datatype
&
bitwise AND
91 & 15
11
Usable only on integral
datatypes
|
bitwise OR
32 | 3
35
Usable only on integral
datatypes
#
bitwise XOR
17 # 5
20
Usable only on integral
datatypes
~
bitwise NOT
~1
-2
Usable only on integral
datatypes
<<
bitwise shift left
1 << 4
16
Usable only on integral
datatypes
>>
bitwise shift right
8 >> 2
2
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
Result
abs(x)
(same type as
x)
absolute value
abs(-17.4)
17.4
cbrt(dp)
dp (double
precision)
cube root
cbrt(27.0)
3
ceil(dp or numeric)
(same as input)
smallest integer
not less than
argument
ceil(-42.8)
-42
ceiling(dp or numeric)
(same as input)
smallest integer
not less than
argument (alias
for ceil
ceiling(-95.3)
-95
degrees(dp)
dp
radians to degrees degrees(0.5)
28.64788975
65412
exp(dp or numeric)
(same as input)
exponential
exp(1.0)
2.718281828
45905
floor(dp or numeric)
(same as input)
largest integer not
greater than
argument
floor(-42.8)
-43
V--98 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Trigonometric Functions
ln(dp or numeric)
(same as input)
natural logarithm
0.693147180
559945
log(dp or numeric)
(same as input)
base 10 logarithm log(100.0)
2
log(b numeric, x
numeric)
numeric
logarithm to base
b
log(2.0, 64.0)
6.000000000
0
mod(y, x)
(same as
argument
types)
remainder of y/x
mod(9,4)
1
pi()
dp
"\u03c0" constant pi()
3.141592653
58979
power(a dp, b dp)
dp
a raised to the
power of b
power(9.0, 3.0)
729
power(a numeric, b
numeric)
numeric
a raised to the
power of b
power(9.0, 3.0)
729
radians(dp)
dp
degrees to radians radians(45.0)
0.785398163
397448
round(dp or numeric)
(same as input)
round to nearest
integer
round(42.4)
42
round(v numeric, s int)
numeric
round to s
decimal places
round(42.4382, 2) 42.44
sign(dp or numeric)
(same as input)
sign of the
argument (-1, 0,
+1)
sign(-8.4)
-1
sqrt(dp or numeric)
(same as input)
square root
sqrt(2.0)
1.414213562
3731
trunc(dp or numeric)
(same as input)
truncate toward
zero
trunc(42.8)
42
trunc(v numeric, s int)
numeric
truncate to s
decimal places
trunc(42.4382, 2) 42.43
ln(2.0)
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)
dp (double
precision)
inverse cosine
asin(x)
dp
inverse sine
atan(x)
dp
inverse tangent
atan2(x, y)
dp
inverse tangent of x/y
cos(x)
dp
cosine
cot(x)
dp
cotangent
December 14, 2011
Functions and Operators V--99
String Functions and Operators
Aster Data proprietary and confidential
sin(x)
dp
sine
tan(x)
dp
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
Example
Result
string || string
text
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 COALESCE.
'Bee' || 'hive'
Beehive
bit_length(string)
int
Number of bits in string
bit_length('jose')
32
char_length(string)
or character_
length(string)
int
Number of characters in string
char_length('jose')
4
lower(string)
text
Convert string to lower case
lower('TOM')
tom
octet_length(string)
int
Number of bytes in string
octet_
length('jose')
4
overlay(string
placing string from
int [for int])
text
Replace substring
overlay('Txxxxas'
placing 'hom' from
2 for 4)
Thomas
position(substring
in string)
int
Location of specified substring
position('om' in
'Thomas')
3
substring(string
[from int] [for
int])
text
Extract substring
substring('Thomas'
from 2 for 3)
hom
substring(string
from pattern)
text
Extract substring matching
POSIX regular expression. See
“POSIX Regular Expressions” on
page V-110.
substring('Thomas'
from '...$')
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)
text
Extract substring matching SQL
regular expression. See “POSIX
Regular Expressions” on
page V-110.
substring('Thomas'
from '%#"o_a#"_'
for '#')
oma
trim([leading |
trailing | both]
[characters] from
string)
text
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.
trim(both 'x' from
'xTomxx')
Tom
upper(string)
text
Convert string to uppercase
upper('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
ASCII code of the first byte of
the argument
ascii('x')
120
btrim(string text
[, characters
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.
btrim('xyxtrimy
yx', 'xy')
trim
chr(int)
text
Character with the given ASCII
code
chr(65)
A
decode(string
text, type text)
bytea
Decode binary data from string
previously encoded with encode.
Parameter type is same as in
encode.
decode('MTIzAAE
=', 'base64')
123\000\001
encode(data bytea,
type text)
text
Encode binary data to different
representation. Supported types
are: base64, hex, escape. Escape
merely outputs null bytes as \000
and doubles backslashes.
encode(
E'123\\000\\001
', 'base64')
MTIzAAE=
initcap(string)
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.
initcap('hi
THOMAS')
Hi Thomas
length(string)
int
Number of characters in string
length('jose')
4
lpad(string text,
length int [, fill
text])
text
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).
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])
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')
trim
md5(string)
text
Calculates the MD5 hash of
string, returning the result in
hexadecimal
md5('abc')
900150983cd24
fb0
d6963f7d28e17
f72
quote_ident(
string)
text
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')
"Sales
Quarter"
quote_literal(
string)
text
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')
'O''Reilly'
regexp_replace(
string text,
pattern text,
replacement text
[,flags text])
text
Replace substring matching
POSIX regular expression. See
“POSIX Regular Expressions” on
page V-110.
regexp_
replace('Thomas
', '.[mN]a.',
'M')
ThM
regexp_split_to_
table(string text,
pattern text [,
flags text])
setof
text
Split string using a POSIX
regular expression as the
delimiter. See “POSIX Regular
Expressions” on page V-110.
regexp_split_
to_table('hello
world',
E'\\s+')
hello
world
(2 rows)
repeat(string
text, number int)
text
Repeat string the specified
number of times
repeat('Bh', 4)
BhBhBhBh
replace(string
text, from text,
to text)
text
Replace all occurrences in string
of substring from with substring
to
replace(
'abcdefabcdef',
'cd', 'XX')
abXXefabXXef
rpad(string text,
length int [, fill
text])
text
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.
rpad('hi', 5,
'xy')
hixyx
rtrim(string text
[, characters
text])
text
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.
rtrim('trimxxxx
', 'x')
trim
split_part(string
text, delimiter
text, field int)
text
Split string on delimiter and
return the given field (counting
from one)
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)
int
Location of specified substring
(same as
position(substring in
string), but note the reversed
argument order)
strpos('high',
'ig')
2
substr(string,
from [, count])
text
Extract substring (same as
substring(string from from for
count))
substr('alphabe
t', 3, 2)
ph
to_ascii(string
text [, encoding
text])
text
Convert string to ASCII from
another encoding (only supports
conversion from LATIN1,
LATIN2, LATIN9, and WIN1250
encodings)
to_
ascii('Karel')
Karel
to_hex(number int
or bigint)
text
Convert number to its equivalent
hexadecimal representation
to_
hex(2147483647)
7fffffff
translate(string
text, from text,
to text)
text
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')
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.
Operato
r
Description
Example
Result
||
concatenation
B'10001' || B'011'
10001011
&
bitwise AND
B'10001' & B'01101'
00001
|
bitwise OR
B'10001' | B'01101'
11101
#
bitwise XOR
B'10001' # B'01101'
11100
~
bitwise NOT
~ B'10001'
01110
<<
bitwise shift left
B'10001' << 3
01000
>>
bitwise shift right
B'10001' >> 2
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
?
question
mark
occurs at most once
*
asterisk
occurs zero or more times
+
plus sign
occurs at least once
The precedence of operators are, from highest to lowest:
1.
December 14, 2011
Cascade operator (".")
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
Description
FIRST( <expression> OF ANY(<symbol list>) )
Value of <expression> in the first row in
the row sequence for the symbol list
LAST( <expression> OF ANY(<symbol list>) )
Value of <expression> in the last row in
the row sequence for the symbol list
COUNT( * OF ANY(<symbol list>) )
Number of rows in the row sequence for
the symbol list
SUM( <expression> OF ANY(<symbol list>) )
Sum of the values of <expression> in the
row sequence for the symbol list
AVG( <expression> OF ANY(<symbol list>) )
Average of the values of <expression> in
the row sequence for the symbol list
MAX( <expression> OF ANY(<symbol list>) )
Max of the values of <expression> in the
row sequence for the symbol list
MIN( <expression> OF ANY(<symbol list>) )
Max of the values of <expression> in the
row sequence for the symbol list
DUPCOUNT( <expression> OF ANY(<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>) )
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()
ACCUMULATE( <expression> OF ANY(<symbol list>) )
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'
'abc'
'abc'
'abc'
LIKE
LIKE
LIKE
LIKE
'abc'
'a%'
'_b_'
'c'
true
true
true
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'
'abc'
'abc'
'abc'
December 14, 2011
SIMILAR
SIMILAR
SIMILAR
SIMILAR
TO
TO
TO
TO
'abc'
'a'
'%(b|d)%'
'(b|c)%'
true
false
true
false
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
'thomas' ~ '.*thomas.*'
~*
Matches regular expression, case insensitive
'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 LIKE (page V-108) and
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'
'abc'
'abc'
~
~
~
~
'abc'
'^a'
'(b|d)'
'^(b|c)'
true
true
true
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')
SELECT SUBSTRING('foobar' FROM 'o(.)b')
oob
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 nth 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')
regexp_replace('foobarbaz', 'b..', 'X', 'g')
regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
fooXbaz
fooXX
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.
Table 2-6 Table: Regular Expression Atoms
Atom
Description
(re)
(where re is any regular expression) matches a match for 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 bracket expression, matching any one of the chars
\k
(where k is a non-alphanumeric character) matches that character taken as an ordinary character,
e.g. \\ matches a backslash character
\c
where c is alphanumeric (possibly followed by other characters) is an escape, s (AREs only; in
EREs and BREs, this matches c)
{
when followed by a character other than a digit, matches the left-brace character {; when
followed by a digit, it is the beginning of a bound (see below)
x
where x is a single character with no other significance, matches that character
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
*
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
{m}
a sequence of exactly m matches of the atom
{m,}
a sequence of m or more matches of the atom
{m,n}
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
??
non-greedy version of ?
{m}?
non-greedy version of {m}
{m,}?
non-greedy version of {m,}
{m,n}?
non-greedy version of {m,n}
Aster Data proprietary and confidential
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, print, 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
synonym for \ to help reduce the need for backslash doubling
\cX
(where X is any character) the character whose low-order 5 bits are the
same as those of X, and whose other bits are all zero
\e
the character whose collating-sequence name is ESC, or failing that, the
character with octal value 033
\f
form feed, as in C
\n
newline, as in C
\r
carriage return, as in C
\t
horizontal tab, as in C
\uwxyz
(where wxyz is exactly four hexadecimal digits) the UTF16 (Unicode,
16-bit) character U+wxyz in the local byte ordering
\Ustuvwxyz
(where stuvwxyz is exactly eight hexadecimal digits) reserved for a
somewhat-hypothetical Unicode extension to 32 bits
\v
vertical tab, as in C
\xhhh
(where hhh is any sequence of hexadecimal digits) the character whose
hexadecimal value is 0xhhh (a single character no matter how many
hexadecimal digits are used)
\0
the character whose value is 0
\xy
(where xy is exactly two octal digits, and is not a back reference) the
character whose octal value is 0xy
\xyz
(where xyz is exactly three octal digits, and is not a back reference) the
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
[[:digit:]]
\s
[[:space:]]
\w
[[:alnum:]_] (note underscore is
included)
\D
[^[:digit:]]
\S
[^[:space:]]
\W
[^[: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 Description
e
\A
matches only at the beginning of the string
\m
matches only at the beginning of a word
\M
matches only at the end of a word
\y
matches only at the beginning or end of a
word
\Y
matches only at a point that is not the
beginning or end of a word
\Z
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 is a nonzero digit) a back reference to the m'th
subexpression
\mnn
(where m is a nonzero digit, and 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
December 14, 2011
rest of RE is a BRE
Functions and Operators
V--117
Pattern Matching Functions and Operators
Aster Data proprietary and confidential
c
case-sensitive matching (overrides operator type)
e
rest of RE is an ERE
i
case-insensitive matching (overrides operator type)
m
historical synonym for n
n
newline-sensitive matching
p
partial newline-sensitive matching
q
rest of RE is a literal ("quoted") string, all ordinary
characters
s
non-newline-sensitive matching (default)
t
tight syntax (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)
text
convert time stamp to
string
to_char(current_
timestamp, 'HH12:MI:SS')
to_char(interval, text)
text
convert interval to string
to_char(interval '15h 2m
12s', 'HH24:MI:SS')
to_char(int, text)
text
convert integer to string
to_char(125, '999')
to_char(double precision,
text)
text
convert real/double
precision to string
to_char(125.8::real,
'999D9')
to_char(numeric, text)
text
convert numeric to string
to_char(-125.8,
'999D99S')
to_date(text, text)
date
convert string to date
to_date('05 Dec 2000',
'DD Mon YYYY')
to_number(text, text)
numeric
convert string to numeric
to_number('12,454.8-',
'99G999D9S')
to_timestamp(text, text)
timestamp
with time
zone
convert string to time
stamp
to_timestamp('05 Dec
2000', 'DD Mon YYYY')
to_timestamp(double
precision)
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
hour of day (01-12)
HH12
hour of day (01-12)
HH24
hour of day (00-23)
MI
minute (00-59)
SS
second (00-59)
MS
millisecond (000-999)
US
microsecond (000000-999999)
SSSS
seconds past midnight (0-86399)
December 14, 2011
Functions and Operators
V--121
Datatype Formatting Functions and Operators
Aster Data proprietary and confidential
AM or A.M. or PM or
P.M.
meridian indicator (uppercase)
am or a.m. or pm or
p.m.
meridian indicator (lowercase)
Y,YYY
year (4 and more digits) with comma
YYYY
year (4 and more digits)
YYY
last 3 digits of year
YY
last 2 digits of year
Y
last digit of year
IYYY
ISO year (4 and more digits)
IYY
last 3 digits of ISO year
IY
last 2 digits of ISO year
I
last digits of ISO year
BC or B.C. or AD or
A.D.
era indicator (uppercase)
bc or b.c. or ad or a.d.
era indicator (lowercase)
MONTH
full uppercase month name (blank-padded to 9 chars)
Month
full mixed-case month name (blank-padded to 9 chars)
month
full lowercase month name (blank-padded to 9 chars)
MON
abbreviated uppercase month name (3 chars in English, localized lengths vary)
Mon
abbreviated mixed-case month name (3 chars in English, localized lengths vary)
mon
abbreviated lowercase month name (3 chars in English, localized lengths vary)
MM
month number (01-12)
DAY
full uppercase day name (blank-padded to 9 chars)
Day
full mixed-case day name (blank-padded to 9 chars)
day
full lowercase day name (blank-padded to 9 chars)
DY
abbreviated uppercase day name (3 chars in English, localized lengths vary)
Dy
abbreviated mixed-case day name (3 chars in English, localized lengths vary)
dy
abbreviated lowercase day name (3 chars in English, localized lengths vary)
DDD
day of year (001-366)
DD
day of month (01-31)
D
day of week (1-7; Sunday is 1)
W
week of month (1-5) (The first week starts on the first day of the month.)
WW
week number of year (1-53) (The first week starts on the first day of the year.)
IW
ISO week number of year (The first Thursday of the new year is in week 1.)
CC
century (2 digits) (The twenty-first century starts on 2001-01-01.)
J
Julian Day (days since January 1, 4712 BC)
Q
quarter
RM
month in Roman numerals (I-XII; I=January) (uppercase)
rm
month in Roman numerals (i-xii; i=January) (lowercase)
TZ
time-zone name (uppercase)
tz
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
Result
to_char(current_timestamp, 'Day, DD
HH12:MI:SS')
to_char(current_timestamp, 'FMDay, FMDD
HH12:MI:SS')
'Tuesday
, 06
'Tuesday, 6
05:39:18'
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-10-05'
+
date '2001-09-28' + interval '1 hour'
timestamp '2001-09-28 01:00:00'
+
date '2001-09-28' + time '03:00'
timestamp '2001-09-28 03:00:00'
+
interval '1 day' + interval '1 hour'
interval '1 day 01:00:00'
+
timestamp '2001-09-28 01:00' +
interval '23 hours'
timestamp '2001-09-29 00:00:00'
+
time '01:00' + interval '3 hours'
time '04:00:00'
-
- interval '23 hours'
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'
time '03:00:00'
-
timestamp '2001-09-28 23:00' interval '23 hours'
timestamp '2001-09-28 00:00:00'
-
interval '1 day' - interval '1 hour'
interval '1 day -01:00:00'
-
timestamp '2001-09-29 03:00' timestamp '2001-09-27 12:00'
interval '1 day 15:00:00'
*
900 * interval '1 second'
interval '00:15:00'
*
21 * interval '1 day'
interval '21 days'
*
double precision '3.5' * interval '1
hour'
interval '03:30:00'
December 14, 2011
Result
Functions and Operators
V--123
Date/Time Functions and Operators
/
interval '1 hour' / double precision
'1.5'
Aster Data proprietary and confidential
interval '00:40:00'
Date/Time Functions
The following table shows the available functions for date/time value processing, with additional
information on several functions following:
Function
Return
Type
Description
Example
Result
clock_timestamp()
timestamp
with time
zone
SELECT clock_
timestamp();
Current
timestamp
date_part(text,
timestamp)
double
precision
date_part('hour',
timestamp '2001-02-16
20:38:40')
20
date_part(text,
interval)
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.
Get subfield (equivalent to
extract)
3
date_trunc(text,
timestamp)
timestamp
date_part('month',
interval '2 years 3
months')
date_trunc('hour',
timestamp '2001-02-16
20:38:40')
extract(field from
timestamp)
double
precision
20
extract(field from
interval)
double
precision
isfinite(timestamp
)
Boolean
Test for finite time stamp
(not equal to infinity)
isfinite(interval)
Boolean
Test for finite interval
justify_
days(interval)
interval
justify_
hours(interval)
interval
interval
justify_
hours(interval '24
hours')
justify_
interval(interval '1
mon -1 hour')
1 day
justify_
interval(interval)
now()
timestamp
Adjust interval so 30-day
time periods are
represented as months
Adjust interval so 24-hour
time periods are
represented as days
Adjust interval using
justify_days and justify_
hours, with additional sign
adjustments
Date and time of the start
of the transaction. See also
clock_timestamp()
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')
isfinite(interval '4
hours')
justify_days(interval
'30 days')
SELECT now();
Time of
the start of
this
transaction
.
Truncate to specified
precision. See also “date_
trunc Function” on
page V-128.
Get time or date subfield.
See also “EXTRACT
Function” on page V-124.
Get time or date subfield
2001-02-1
6 20:00:00
3
true
true
1 month
29 days
23:00:00
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
Return Type
Description
AVG(expression)
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
the average (arithmetic
mean) of all input
values
bigint
number of input rows
COUNT(*)
COUNT(expression)
any
bigint
number of input rows
for which the value of
expression is not null
MAX(expression)
any numeric, string, or
date/time type
same as argument type
maximum value of
expression across all
input values
MIN(expression)
any numeric, string, or
date/time type
same as argument type
minimum value of
expression across all
input values
SUM(expression)
smallint, int, bigint,
real, double precision,
numeric, or interval
bigint for smallint or int
arguments, numeric for bigint
arguments, double precision for
floating-point arguments,
otherwise the same as the argument
datatype
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 “Window
Functions” on page V-137.
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
Return Type
Description
STDDEV(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
historical alias for stddev_
samp
STDDEV_POP(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
population standard
deviation of the input
values
STDDEV_SAMP(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
sample standard deviation
of the input values
VARIANCE(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
historical alias for var_
samp
VAR_POP(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
population variance of the
input values (square of the
population standard
deviation)
VAR_SAMP(expression)
smallint, int, bigint,
real, double
precision, or numeric
double precision for
floating-point arguments,
otherwise numeric
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
V--136 Database SQL and Function Reference, version 4.6.2
Aster Data proprietary and confidential
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
refer to an aggregated value. (See “Window Function Example 15: ORDER BY SUM()” on
page V-152.) In fact, window functions may include any expression that may appear in the
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, “Window
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“RANK()” on page V-139.
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
4 |
3 |
1 |
9 |
8 |
6 |
11 |
(11 rows)
Aster Data proprietary and confidential
233
100
100
100
100
100
100
| 130000 |
| 42000 |
| 50010 |
| 48765 |
| 50000 |
| 49333 |
| 50000 |
1
1
2
3
4
5
6
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
4 |
(11 rows)
LEAD and LAG functions
233 | 130000 |
0
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
101 |
101 |
101 |
100 |
100 |
100 |
233 |
100 |
101 |
(11 rows)
Aster Data proprietary and confidential
2
10
5
9
8
6
4
11
7
| 45000 |
| 387999 |
| 56000 |
| 48765 |
| 50000 |
| 49333 |
| 130000 |
| 50000 |
| 122345 |
30
32
32
33
34
44
55
65
87
|
|
|
|
|
|
|
|
|
-342999
331999
7235
-1235
667
-80667
80000
-72345
122345
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 “Synopsis of Window
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
Aster Data proprietary and confidential
For range-based frames, the window frame syntax is:
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
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
BETWEEN 5 PRECEDING and 2 PRECEDING
BETWEEN 5 PRECEDING AND 5 PRECEDING
BETWEEN 2 PRECEDING AND CURRENT ROW
BETWEEN CURRENT ROW AND CURRENT ROW
BETWEEN CURRENT ROW AND 2 FOLLOWING
BETWEEN 2 FOLLOWING AND 2 FOLLOWING
BETWEEN 2 FOLLOWING AND 5 FOLLOWING
BETWEEN UNBOUNDED PRECEDING AND 2 PRECEDING
BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
BETWEEN UNBOUNDED PRECEDING AND 5 FOLLOWING
BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
BETWEEN 2 PRECEDING AND UNBOUNDED FOLLOWING
BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING
BETWEEN 4 FOLLOWING AND UNBOUNDED FOLLOWING
UNBOUNDED PRECEDING
5 PRECEDING
CURRENT ROW
5 FOLLOWING
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
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
ROWS
BETWEEN
BETWEEN
BETWEEN
BETWEEN
BETWEEN
BETWEEN
BETWEEN
BETWEEN
Aggregate Window Functions
2 PRECEDING AND 5 PRECEDING
CURRENT ROW AND 2 PRECEDING
2 FOLLOWING AND CURRENT ROW
5 FOLLOWING AND 2 FOLLOWING
UNBOUNDED FOLLOWING AND CURRENT ROW
CURRENT ROW AND UNBOUNDED PRECEDING
UNBOUNDED PRECEDING AND UNBOUNDED PRECEDING
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
9 |
8 |
6 |
11 |
2 |
5 |
10 |
7 |
4 |
(11 rows)
Aster Data proprietary and confidential
100
100
100
100
101
101
101
101
233
|
|
|
|
|
|
|
|
|
33
34
44
65
30
32
32
87
55
| 48765 |
| 50000 |
| 49333 |
| 50000 |
| 45000 |
| 56000 |
| 387999 |
| 122345 |
| 130000 |
140775
190775
240108
290108
45000
488999
488999
611344
130000
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)
•
Numeric Types (page V-159)
•
Character Types (page V-163)
•
Date/Time Types (page V-165)
•
Bit String Types (page V-169)
•
Boolean Types (page V-169)
•
Binary Types (page V-170)
•
Network Address Types (page V-172)
•
UUID Type (page V-178)
•
Type Casts (page V-179)
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
See page
bigint
int8
signed eight-byte integer
Numeric Types
(page V-159)
bigserial
autoincrementing
eight-byte integer
Numeric Types
(page V-159)
bit [(n)]
fixed-length bit string
Bit String Types
(page V-169)
bit varying [(n)]
varbit
variable-length bit string
Bit String Types
(page V-169)
Boolean
bool
logical Boolean (true/false)
Boolean Types
(page V-169)
December 14, 2011
Aster Data proprietary and confidential
V--157
List of Supported Datatypes
Name
Aster Data proprietary and confidential
Aliases
bytea
Description
See page
variable-length binary
string
Binary Types
(page V-170)
character varying [(n)]
varchar [(n)]
variable-length character
string
Character Types
(page V-163)
character [(n)]
char [(n)]
fixed-length character
string
Character Types
(page V-163)
calendar date (year, month,
day)
Date/Time Types
(page V-165)
double precision
floating-point number
Numeric Types
(page V-159)
ip4
IP address
Network Address Types
(page V-172)
ip4range
range of IP addresses
ip4range Datatype
(page V-174)
signed four-byte integer
Numeric Types
(page V-159)
time interval
Intervals (page V-168)
date
double precision
integer
float, float8,
float(n)
int, int4
interval
numeric [(p, s)]
decimal [(p,s)]
exact numeric of selectable
precision
Numeric Types
(page V-159)
real
float4
single precision
floating-point number
Numeric Types
(page V-159)
autoincrementing four-byte Numeric Types
integer
(page V-159)
serial
signed two-byte integer
Numeric Types
(page V-159)
text
variable-length character
string
Character Types
(page V-163)
time [(p)] [without
time zone]
time of day
Date/Time Types
(page V-165)
time of day, including time
zone
Date/Time Types
(page V-165)
date and time
Date/Time Types
(page V-165)
date and time, including
time zone
Date/Time Types
(page V-165)
smallint
int2
time [(p)] with time
zone
timetz
timestamp [(p)]
[without time zone]
timestamp [(p)] with
time zone
timestamptz
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
Aliases
Storage
Size
Description
smallint
int2
2 bytes
small-range integer -32768 to +32767
Integer Types
(page V-159)
integer
int, int4
4 bytes
usual choice for
integer
-2147483648 to
+2147483647
Integer Types
(page V-159)
bigint
int8
8 bytes
large-range integer
-9223372036854775808 to Integer Types
9223372036854775807
(page V-159)
numeric,
numeric(p),
numeric(p,s)
decimal
Variable
user-specified
precision, exact
no limit
Arbitrary
Precision
Numbers
(page V-160)
4 bytes
variable-precision,
inexact
6 decimal digits precision
Floating-Point
Types
(page V-161)
real
Range
See page
double
precision
float,
float4,
float8,
float(n)
8 bytes
variable-precision,
inexact
15 decimal digits precision Floating-Point
Types
(page V-161)
serial
serial4
4 bytes
autoincrementing
integer
1 to 2147483647
Serial Types
(page V-162)
bigserial
serial8
8 bytes
autoincrementing
bigint
1 to
9223372036854775807
Serial Types
(page V-162)
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 1037 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 10308 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
SERIAL LOCAL
Dimension table with DISTRIBUTE BY HASH
SERIAL LOCAL
Dimension table without DISTRIBUTE BY HASH
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 231 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
variable-length with limit – 1GB maximum length
character(n), char(n), character, char
fixed-length, blank padded – 1GB maximum length
text
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
High Value
Resolution
timestamp [ (p) ] [
without time zone ]
8 bytes
both date and
time
4713 BC
5874897 AD
1 microsecond /
14 digits
timestamp [ (p) ] with
time zone
8 bytes
both date and
time, with
time zone
4713 BC
5874897 AD
1 microsecond /
14 digits
interval
12 bytes
time interval
-178000000
years
178000000
years
1 microsecond /
14 digits
date
4 bytes
dates only
4713 BC
5874897 AD
1 day
time [ (p) ] [ without
time zone ]
8 bytes
times of day
only
00:00:00
24:00:00
1 microsecond /
14 digits
time [ (p) ] with time
zone
12 bytes
times of day
only, with
time zone
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
•
“Intervals” on page V-168
Date Input Formats
Table 4-5 Examples of date inputs:
Date
Result
January 8, 1999
unambiguous in any datestyle input mode
1999-01-08
ISO 8601; January 8 in any mode (recommended
format)
1/8/1999
January 8 in MDY mode; August 1 in DMY mode
1/18/1999
January 18 in MDY mode; rejected in other modes
01/02/03
January 2, 2003 in MDY mode; February 1, 2003 in
DMY mode; February 3, 2001 in YMD mode
1999-Jan-08
January 8 in any mode
Jan-08-1999
January 8 in any mode
08-Jan-1999
January 8 in any mode
99-Jan-08
January 8 in YMD mode, else error
08-Jan-99
January 8, except error in YMD mode
Jan-08-99
January 8, except error in YMD mode
19990108
ISO 8601; January 8, 1999 in any mode
990108
ISO 8601; January 8, 1999 in any mode
1999.008
year and day of year
J2451187
Julian day
January 8, 99 BC
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
ISO 8601
04:05:06
ISO 8601
04:05
ISO 8601
040506
ISO 8601
04:05 AM
same as 04:05; AM does not affect value
04:05 PM
same as 16:05; input hour must be <= 12
04:05:06.789-8
ISO 8601
04:05:06-08:00
ISO 8601
04:05-08:00
ISO 8601
040506-08
ISO 8601
04:05:06 PST
time zone specified by abbreviation
2003-04-12 04:05:06
America/New_York
time zone specified by full name
Table 4-7 Examples of time zone inputs:
Allowed Example
Notes
PST
Abbreviation (for Pacific Standard
Time)
America/New_York
Full time zone name
PST8PDT
POSIX-style time zone specification
-8:00
ISO-8601 offset for PST
-800
ISO-8601 offset for PST
-8
ISO-8601 offset for PST
zulu
Military abbreviation for UTC
z
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
Low Value
High Value
Resolution
interval
Time interval
-178000000 years
178000000 years
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
beehive=> insert into testbit values
ERROR: bit string length 2 does not
beehive=> insert into testbit values
(0, B'101', B'00');
(1, B'10', B'101');
match type bit(3)
(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
Description
bytea
1 or 4 bytes plus the actual binary string
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
Example
Output
Representation
0
zero octet
E'\\000'
SELECT
E'\\000'::bytea;
\000
39
single quote
'''' or E'\\047'
SELECT
E'\\047'::bytea;
'
92
backslash
E'\\\\' or E'\\134'
SELECT
E'\\\\'::bytea;
\\
0 to 31 and
127 to 255
"non-printable"
octets
E'\\xxx' (octal value)
SELECT
E'\\001'::bytea;
\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 Table 4-10 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 Table 4-11.
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
Output
Result
92
backslash
\\
SELECT E'\\134'::bytea;
\\
0 to 31 and
127 to 255
"non-printable" octets
\xxx (octal
value)
SELECT E'\\001'::bytea;
\001
32 to 126
"printable" octets
client character
set representation
SELECT E'\\176'::bytea;
~
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
CREATE
INSERT
INSERT
INSERT
INSERT
INSERT
INSERT
TABLE ipranges (range ip4range primary key, description text not null);
INDEX ipranges_range_idx ON ipranges USING gist (range);
INTO ipranges VALUES ('10.0.0.0/8','rfc1918 block 1');
INTO ipranges VALUES ('172.16.0.0/12','rfc1918 block 2');
INTO ipranges VALUES ('192.168.0.0/16','rfc1918 block 3');
INTO ipranges VALUES ('0.0.0.0/1','classical class A space');
INTO ipranges VALUES ('10.0.1.10-10.0.1.20','my internal network');
INTO ipranges VALUES ('127.0.0.1','localhost');
CREATE
CREATE
INSERT
INSERT
INSERT
TABLE access_log (id serial primary key, ip ip4 not null);
INDEX access_log_ip_idx ON access_log (ip);
INTO access_log(ip) VALUES ('10.0.1.15');
INTO access_log(ip) VALUES ('24.1.2.3');
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
FROM
WHERE
ORDER
DISTINCT ON (ip) ip,range,description
access_log, ipranges
ip <<= range
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
Form
ip4
text
ip4::text
(explicit)
text
ip4
text::ip4
(explicit)
ip4
bigint
ip4::bigint
(explicit)
bigint
ip4
bigint::ip4
(explicit)
ip4
float8
ip4::float8
(explicit)
float8
ip4
float8::ip4
(explicit)
ip4
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
Description
ip4 + integer
add the given integer to the IP
ip4 - integer
subtract the given integer from the IP
ip4 + bigint
add the given integer to the IP
ip4 - bigint
subtract the given integer from the IP
ip4 - ip4
(returns bigint) difference between two IPs
ip4 & ip4
bitwise-AND the two values
ip4 | ip4
bitwise-OR the two values
ip4 # ip4
bitwise-XOR the two values
~ ip4
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
Form
ip4
ip4range
ip4range(ip4)
ip4range
text
ip4range::text (explicit)
text
ip4range
ip4range(text) or
or
ip4::ip4range
(implicit)
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.
Operators for ip4range
The ip4range type supports the following operators:
Operator
Description
a = b
exact equality
a <> b
exact inequality
a < b
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
a <= b
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
a > b
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
a >= b
ordering for the purposes of btree indexes. Does a lexicographic ordering of (lower,upper).
a >>= b
a contains b or is equal to b
a >> b
a strictly contains b
a <<= b
a is contained in b or is equal to b
a << b
a is strictly contained in b
a && b
a and b overlap
December 14, 2011
Datatypes
V--175
Network Address Types
Aster Data proprietary and confidential
Operator
Description
a <<< b
strictly less than. (a <<< b) if all IPs contained in a are strictly less than all IPs contained in b.
a >>> 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
FROM
WHERE
ORDER
DISTINCT ON (ips.ip) ips.ip, ranges.range
ips, ranges
ranges.range >>= ips.ip
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
CREATE
SELECT
SELECT
SELECT
SELECT
ABORT;
TABLE ip1(a ip4,
TABLE ip2(a ip4,
* FROM ip1 , ip2
* FROM ip1 , ip2
* FROM ip1 , ip2
* FROM ip1 , ip2
b ip4range,
b ip4range,
WHERE ip1.a
WHERE ip1.a
WHERE ip1.b
WHERE ip1.b
c int) distribute by hash(a);
c int) distribute by hash(b);
<<= ip2.b ORDER BY ip1.c;
= ip2.a ORDER BY ip1.c;
>>= ip2.a ORDER BY ip1.c;
= ip2.b ORDER BY ip1.c;
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
V--180 Database SQL and Function Reference, version 4.6.2
Aster Data proprietary and confidential
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.
2.
3.
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.
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.
•
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:
•
December 14, 2011
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.
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
•
Month Names (page V-182)
•
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
Jan
February
Feb
March
Mar
April
Apr
May
May
June
Jun
July
Jul
August
Aug
September
Sep, Sept
October
Oct
November
Nov
December
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
Date/Time Keywords
Table 5-2 Day-of-week names
Day
Abbreviations
Sunday
Sun
Monday
Mon
Tuesday
Tue, Tues
Wednesday
Wed, Weds
Thursday
Thu, Thur, Thurs
Friday
Fri
Saturday
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
Ignored
AM
Time is before 12:00
AT
Ignored
JULIAN, JD, J
Next field is Julian Day
ON
Ignored
PM
Time is on or after 12:00
T
Next field is time
The keyword ABSTIME is ignored for historical reasons.
December 14, 2011
Date and Time V--183
Date/Time Keywords
V--184 Database SQL and Function Reference, version 4.6.2
Aster Data proprietary and confidential
aster data
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)
December 14, 2011
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:
Field
Type
Description
userid
int
Unique user Id
username
varchar
Username
schemapath
varchar
User’s default schema path
cancreaterole
bool
Can create additional users and roles
cancreatedb
bool
Can create databases
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
connlimit
int
For users that can log in, this sets maximum
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:
Field
Type
Description
roleid
int
Unique role Id
rolename
varchar
Role name
cancreaterole
bool
Can create additional roles
cancreatedb
bool
Can create databases
autoinheritgrouppriv
bool
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:
Field
Type
Description
groupid
int
Id of group
memberid
int
Id of member of group
grantorid
int
Id which granted this membership
cangrant
bool
true if member can grant membership in this group to
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
Field
Type
Description
dbid
int
Unique database Id
dbname
varchar
Database name
dbowner
varchar
Database owner name
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 GRANT
(page V-61) 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
varchar
Database name to which this schema belongs
schemaid
int
Unique schema Id
schemaname
varchar
Database name
schemaowner
varchar
Database owner name
permissions
varchar
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
Field
Type
Description
schemaid
int
Schema id to which this table belongs
tableid
int
Unique table Id
tablename
varchar
Table name
tableowner
varchar
Table owner name
tabletype
varchar
Table type: { 'fact' , 'dimension' }
compresslevel
varchar
Compression level for that table: { 'none' , 'low' , 'medium' , 'high' }
storagetype
varchar
Table storage type: {‘row’, ‘column’}
partitionkey
varchar
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
Field
Type
Description
V--190 Database SQL and Function Reference, version 4.6.2
aster data
Aster Data proprietary and confidential
Constraint-Related Data Dictionary Views
relid
int
Table id of table to which this column belongs
colname
varchar
Column name
coltype
varchar
Column type
typeid
int
Type id of column type
typemod
int
Type modifier of column type
colnum
int
Columns number
isnotnull
bool
true if there is a not-null constraint on this column
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
Field
Type
Description
tableid
int
Table id of table on which index was created
indexid
int
Unique index Id
indexname
varchar
Index name
collist
varchar
List of column positions for columns that form this index
isprimary
bool
true if this is a primary key index
indexdef
varchar
CREATE INDEX command for 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
Table id of table on which the constraint is defined
conid
int
Unique constraint Id
conname
varchar
Constraint name
contype
char
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
condef
varchar
Constraint definition
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
Field
Type
Description
partitionid
bigint
Partition ID for this child partition
parentid
bigint
ID of the parent. For partitions at the first level, this is a table ID. For partitions
at lower levels, this is the ID of the parent partition.
tableid
bigint
The table ID of the table where this child partition is defined
partitionname
varchar
Name of child partition (unique among partitions with the same parent)
compressinfo
varchar
Compression level of the partition: { 'none' , 'low' , 'medium' , 'high' }
format
varchar
Format of the partitioning (LIST or RANGE)
partitionexpr
varchar
Expression that the partitioning is based on
nullsfirst
bool
True if nulls are sorted first
constraintdef
varchar
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
Field
Type
Description
parentid
bigint
ID of the parent. For partitions at the first level, this is a table ID. For partitions
at lower levels, this is the ID of the parent partition.
tableid
bigint
The table ID of the table where this child partition is defined
format
varchar
Format of the partitioning (LIST or RANGE)
partitionexpr
varchar
Expression that the partitioning is based on
nullsfirst
bool
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
Table id of parent table
childid
int
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
int
Unique type Id
typename
varchar
Type name
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
Mac address of the node
ipaddr
varchar
Assigned ip address of node
type
varchar
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
State of the node: { 'Active' , 'Failed' , 'Suspect'
, 'Prepared' , 'Preparing' , 'New' , 'Passive' ,
'Upgrading' }
lastupdatetime
timestamp without timezone
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
Total storage in the cluster
activestorage
bigint
Storage used by active data in the cluster
replicastorage
bigint
Storage used by the replica data in the cluster
systemstorage
bigint
Storage used by the system data in the cluster
lastupdatetime
timestamp without timezone
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
Unique session id
username
varchar
Session username
clientip
character(16)
Client ip address
dbname
varchar
Name of database to which connection was
established
starttime
timestamp without time zone
Session start time
endtime
timestamp without time zone
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
bigint
Unique transaction id
sessionid
bigint
Session id of session to which the
transaction belongs
starttime
timestamp without time zone
Start time of transaction
endtime
timestamp without time zone
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
character(20)
Phase description
xactionid
bigint
Transaction id of transaction
sessionid
bigint
Session id of session to which the
transaction belongs
starttime
timestamp without time zone
Start time of transaction phase
endtime
timestamp without time zone
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
Description
statementid
bigint
Unique statement id
xactionid
bigint
Transaction id of transaction to which
this statement belongs
sessionid
bigint
Session id of session to which the
statement belongs
retrynum
integer
Retry count of this statement
statement
character varying
Statement string
starttime
timestamp without time zone
Start time of statement
endtime
timestamp without time zone
End time of statement
December 14, 2011
Data Dictionary Views
V--195
Activity Data Dictionary Views
iscancelable
Aster Data proprietary and confidential
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
bigint
Distribution key/partition key (not the key for a
logical partition)
tupletimestamp
timestamp with
time zone
Date and time when this error occurred.
label
character varying
User-specified label provided in WITH LABEL or
--el-label flag, or the system default label.
targettable
character varying
Intended destination table for this row.
dmltype
character(1)
Type of operation that generated the error.
Currently, this is always 'C' indicating COPY.
errmessage
character varying
Error message returned by PostgreSQL when
rejecting the row.
sqlerrcode
character(5)
SQL code associated with the rejection.
rawdata
bytea
The failed row itself.
linenumber
bigint
Line number where the error occurred in the file.
columnname
varchar
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 dml- table type
errmessage
sqlerrcode
rawdata
linenumber
1
2009-05-20
0
15:20:05.281138-07
clicks
C
invalid input
syntax for
integer: "a"
22P02
2\x09a\x09May 2
20 11:19:30
2009
1
2009-05-20
0
15:20:05.281389-07
clicks
C
extra data after
last expected
column
22P04
4\x0923333\x0
9May 20
11:18:56
2009\x09\N
5
0
2009-05-20
0
15:20:05.116448-07
clicks
C
invalid input
22P02
syntax for
integer: "May 20
11:18:56 2009"
1\x09May 20
11:18:56 2009
3
0
2009-05-20
0
15:20:05.116737-07
clicks
C
extra data after
last expected
column
3\x093\x09234
5\x09May 20
11:10:02 2009
4
22P04
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
User who performed the load attempt.
sessionid
Session ID of the load attempt.
transactionid
Transaction ID of the load attempt.
statementid
Statement ID of the load attempt.
targettable
Table into which data is being loaded.
eltable
Error logging table that received the bad rows for this load attempt.
dmltype
DML action of the load attempt. Currently this is always “C”,
meaning “copy”.
label
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.
totalcount
Number of rows that this load attempt tried to load.
goodcount
Number of rows successfully loaded in this load attempt.
malformedcount
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
Practically unlimited
Maximum size of a hash distributed table
Practically unlimited
Maximum size of a non-distributed DIMENSION
table
32TB
Maximum size of a row
400 GB
Maximum size of a character field
1 GB
Maximum size of a text field
Practically unlimited
Maximum number of rows in a table
Practically unlimited
Maximum number of columns in a table
250-1600 depending on datatypes used.
Effective limit is also affected by the
row-size constraint.
Maximum number of indexes on a table
Practically unlimited
Maximum length of a table name, column name,
or view name
63 characters
Maximum length of a database name
50 characters
Maximum number of columns in a SELECT
1660 columns
Maximum number of users
Practically unlimited
Maximum number of connections
Practically unlimited
Maximum number of nodes
Practically unlimited
Maximum length of an SQL query
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
DATA EXCEPTION
22021
CHARACTER NOT IN REPERTOIRE
22008
DATETIME FIELD OVERFLOW
22012
DIVISION BY ZERO
22005
ERROR IN ASSIGNMENT
2200B
ESCAPE CHARACTER CONFLICT
22022
INDICATOR OVERFLOW
22015
INTERVAL FIELD OVERFLOW
2201E
INVALID ARGUMENT FOR LOGARITHM
2201F
INVALID ARGUMENT FOR POWER FUNCTION
December 14, 2011
Aster Data proprietary and confidential
V--205
Aster Data proprietary and confidential
Error Code
Error Description
2201G
INVALID ARGUMENT FOR WIDTH BUCKET FUNCTION
22018
INVALID CHARACTER VALUE FOR CAST
22007
INVALID DATETIME FORMAT
22019
INVALID ESCAPE CHARACTER
2200D
INVALID ESCAPE OCTET
22025
INVALID ESCAPE SEQUENCE
22P06
NONSTANDARD USE OF ESCAPE CHARACTER
22010
INVALID INDICATOR PARAMETER VALUE
22020
INVALID LIMIT VALUE
22023
INVALID PARAMETER VALUE
2201B
INVALID REGULAR EXPRESSION
22009
INVALID TIME ZONE DISPLACEMENT VALUE
2200C
INVALID USE OF ESCAPE CHARACTER
2200G
MOST SPECIFIC TYPE MISMATCH
22004
NULL VALUE NOT ALLOWED
22002
NULL VALUE NO INDICATOR PARAMETER
22003
NUMERIC VALUE OUT OF RANGE
22026
STRING DATA LENGTH MISMATCH
22001
STRING DATA RIGHT TRUNCATION
22011
SUBSTRING ERROR
22027
TRIM ERROR
22024
UNTERMINATED C STRING
2200F
ZERO LENGTH CHARACTER STRING
22P01
FLOATING POINT EXCEPTION
22P02
INVALID TEXT REPRESENTATION
22P03
INVALID BINARY REPRESENTATION
22P04
BAD COPY FILE FORMAT
22P05
UNTRANSLATABLE CHARACTER
Table 9-6 Error Code Class 23 - Integrity Constraint Violation
Error Code
Error Description
23000
INTEGRITY CONSTRAINT VIOLATION
23502
NOT NULL VIOLATION
23514
CHECK VIOLATION
23518
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
INVALID TRANSACTION STATE
25P02
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
TRANSACTION ROLLBACK
40002
TRANSACTION INTEGRITY CONSTRAINT VIOLATION
40001
SERIALIZATION FAILURE
40003
STATEMENT COMPLETION UNKNOWN
40P01
DEADLOCK DETECTED
Table 9-14 Error Code Class 42 - Syntax Error or Access Rule Violation
Error Code
Error Description
42000
SYNTAX ERROR OR ACCESS RULE VIOLATION
42601
SYNTAX ERROR
42501
INSUFFICIENT PRIVILEGE
42846
CANNOT COERCE
December 14, 2011
Error Codes
V--207
Aster Data proprietary and confidential
Error Code
Error Description
42803
GROUPING ERROR
42602
INVALID NAME
42622
NAME TOO LONG
42939
RESERVED NAME
42804
DATATYPE MISMATCH
42P18
INDETERMINATE DATATYPE
42809
WRONG OBJECT TYPE
42703
UNDEFINED COLUMN
42883
UNDEFINED FUNCTION
42P01
UNDEFINED TABLE
42P02
UNDEFINED PARAMETER
42704
UNDEFINED OBJECT
42701
DUPLICATE COLUMN
42P03
DUPLICATE CURSOR
42P04
DUPLICATE DATABASE
42723
DUPLICATE FUNCTION
42P07
DUPLICATE TABLE
42712
DUPLICATE ALIAS
42710
DUPLICATE OBJECT
42702
AMBIGUOUS COLUMN
42725
AMBIGUOUS FUNCTION
42P08
AMBIGUOUS PARAMETER
42P09
AMBIGUOUS ALIAS
42P10
INVALID COLUMN REFERENCE
42611
INVALID COLUMN DEFINITION
42P11
INVALID CURSOR DEFINITION
42P12
INVALID DATABASE DEFINITION
42P13
INVALID FUNCTION DEFINITION
42P16
INVALID TABLE DEFINITION
42P17
INVALID OBJECT DEFINITION
Table 9-15 Error Code Class 53 - Insufficient Resources
Error Code
Error Description
53000
INSUFFICIENT RESOURCES
53100
DISK FULL
53200
OUT OF MEMORY
53300
TOO MANY CONNECTIONS
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
PROGRAM LIMIT EXCEEDED
54001
STATEMENT TOO COMPLEX
54011
TOO MANY COLUMNS
54023
TOO MANY ARGUMENTS
Table 9-17 Error Code Class 55 - Object Not In Prerequisite State
Error Code
Error Description
55000
OBJECT NOT IN PREREQUISITE STATE
55006
OBJECT IN USE
55P03
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
ABORT, V-6
about this book, V-vii
ABS() function, V-98
access permissions, V-188
list of SQL-MapReduce privileges, V-188
managing using schemas, V-188
account
system table for, V-186
ACOS() function, V-99
activity statistics tables, V-194
aggregate, V-137
aggregate functions, V-130
aggregate window functions, V-146
aggregates of aggregates, V-152
statistics functions, V-130
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
ALL, V-135
ALTER INDEX, V-7
ALTER ROLE, V-7
ALTER SCHEMA, V-8
ALTER TABLE, V-9
set DEFAULT value for column, V-10
ALTER USER, V-15
ANALYZE, V-17
command reference, V-17
AND/OR/NOT operators, V-95
AND, bitwise, V-103
ANY, V-134
ANY/SOME, V-134
ARE (type of regex), V-112
ARE, RE, BRE, and ERE, switching between, V-117
AS, V-77
column alias, V-77
table alias, V-77
ASC, V-80
ASCII, convert to, V-103
ascii() function, V-101
ASIN() function, V-99
Aster datatypes, V-157
Aster Data, about, V-vi
Aster support portal, V-vi
Asterix, V-77
December 14, 2011
ATAN2() function, V-99
ATAN() function, V-99
autopartitioning
COPY and, V-25
AVG() function, V-130
as window function, V-149
cumulative running average, V-150
moving average, V-150
B
back reference in regex, V-115
backslash, V-115
in regex, V-115
in regular expression, V-113
BEGIN, V-18
START TRANSACTION, V-87
BETWEEN, V-96
BETWEEN operator, V-96
BETWEEN SYMMETRIC, V-96
bigint datatype, V-159
bigint, serialized, V-162
bigserial, V-162
bigserial column, V-162
binary data, encoding, V-101
binary string datatype, V-170
bit string operators, V-103
bit string type, V-169
bitwise operators, V-97
for bit strings, V-103
bit_length function, V-100
bit_length operator for bit strings, character strings, V-103
Boolean operators, V-95
Boolean type, V-169
checking a Boolean value, V-97
bracket expression, V-114
brackets for quoting, V-200
BRE, V-120
BRE (type of regex), V-112
btrim() function, V-101
bytea datatype, V-170
C
capitalize words, V-101
CASCADE, V-53
ALTER TABLE and, V-9
GRANT table privileges and, V-61
Index
V--211
CASE, V-131
case-sensitivity in identifiers, V-200
CAST, V-179
cast datatype to another type, V-179
CBRT() function, V-98
CEILING() function, V-98
CEIL() function, V-98
century in timestamp, V-125
char or character type, V-163
functions and, V-100
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
add check constraint, V-14
defined, V-38
child table
change inheritance with ALTER TABLE, V-12
create with CREATE TABLE, V-37
inheriting parent table privileges, V-61
chr() function, V-101
cleanup, V-92
clock_timestamp() function, V-124
CLOSE, V-20
CLUSTER, V-21
partitioning and, V-21
COALESCE, V-132
column, V-190
add or remove, V-10
default value for, V-10, V-35
list of columns in database, V-190
column alias, V-77
column naming conventions, V-199
column sort order, V-77
command, V-3
list of, V-3
SET, V-83
command reference, V-3
commands, V-3
COMMIT, V-22
comparison operators, V-96
compatibility of nCluster with PostgreSQL, V-3
compress data
ALTER TABLE and, V-12
CREATE TABLE and, V-36
compression
CREATE TABLE and, V-36
concatenate
bitwise operator, V-103
concatenation operator, V-100
CONCAT() equivalent, V-100
conditional SQL expressions, V-131
configuration
performance settings, V-83
SET value, V-83
configuration flag, V-154
enableDeprecatedWindowFunctionAliasBehaviour, V154
CONSTRAINT, V-40
add or remove, V-11
ALTER TABLE’s ADD command, V-11
list of, V-191
conventions, V-v
convert string, V-103
COPY, V-23
autopartitioning, V-25
error-capture tables for, V-196
copyright, V-vii
COS() function, V-99
COT() function, V-99
count characters in string, V-101
count function, V-130
CREATE DATABASE, V-28
CREATE INDEX, V-29
CREATE ROLE, V-31
CREATE SCHEMA, V-32
CREATE TABLE, V-34
revoke user’s right to create tables, V-72
CREATE TABLE AS SELECT, V-42
CREATE USER, V-43
CREATE VIEW, V-45
CTAS, V-42
cumulative running average, V-150
CURRENT ROW in window frame, V-148
cursor, V-46
creating, V-46
DECLARE, V-46
FETCH, V-57
MOVE, V-69
updatable, V-48
customer support, V-vi
D
data
loading, statistics on, V-197
data dictionary, V-185
database
CREATE DATABASE, V-28
default character encoding, V-29
deleting, V-51
DROP DATABASE, V-51
datatype, V-157
arbitrary precision numbers, V-160
bigserial, V-162
binary type, bytea, V-170
bit and bit varying, operations on, V-103
bit string, V-169
Boolean, V-169
bytea, V-170
casting to another type, V-179
character datatypes, V-163
date and time functions, V-123
date and time types, V-165
date and time, reformatting, V-121
floating point, V-161
formatting functions for, V-121
ip4, V-172
ip4range, V-174
list of, V-157
V--212 Database SQL and Function Reference, version 4.6.2
aster data
listing from SQL prompt, V-193
network address types, V-172
numeric, V-159
serial, V-162
text datatypes, V-163
time, V-165
time functions, V-123
uuid, V-178
datatype formatting functions, V-121
date, V-165
extract subset, V-124
functions, V-123
return current date, V-129
templates for formatting, V-121
date datatype
functions for, V-123
date datatypes, V-165
date of publication, V-vii
date values, inserting, V-165
date values, retrieving, V-168
date_part function, V-127
synopsis, V-124
date_trunc function, V-128
synopsis, V-124
day in timestamp, V-125
day of week in timestamp, V-125
day of year in timestamp, V-125
daylight savings rules, V-169
decade in timestamp, V-125
DECLARE, V-46
DECLARE CURSOR, V-46
decode() function, V-101
DEFAULT, V-35
default character encoding for databases, V-29
DEFAULT values for a column, V-10
DEGREES() function, V-98
DELETE, V-49
delete rows, V-49
delimited identifier, V-200
delimited identifier (object name), V-200
delimiters, V-200
DENSE_RANK() function, V-139
an example, V-141
another example, V-142
compared with RANK(), V-141
DESC, V-80
DISTINCT, V-81
IS DISTINCT FROM, V-97
DISTINCT Clause, V-81
DISTINCT FROM, V-96
distribution key
declaring in CREATE TABLE, V-36
documentation conventions, V-v
documentation version and updates, V-vii
documentation, about, V-v
double precision datatype, V-161
double tilde, V-109
double-quote character, V-200
dow in timestamp, V-125
doy in timestamp, V-125
dp datatype, V-161
DROP DATABASE, V-51
December 14, 2011
DROP INDEX, V-51
DROP ROLE, V-52
DROP SCHEMA, V-53
DROP TABLE, V-53
DROP USER, V-54
E
edition, V-vii
empty a table of rows, V-88
encode() function, V-101
encoding
UTF-8 is the default, V-29
END, V-56
epoch in timestamp, V-125
equality, checking, V-97
ERE (type of regex), V-112
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
EXCEPT Clause, V-80
exclamation point in regex, V-110
EXISTS, V-133
EXPLAIN, V-57
expression, V-133
ALL, V-135
ANY/SOME, V-134
EXISTS, V-133
IN, V-133
in index definition, V-30
NOT IN, V-134
SOME, V-134
expression-based index, V-30
EXP() function, V-98
extract function, V-124
date_part, V-127
synopsis, V-124
extract subset of date/time value, V-124
F
FALSE, V-97
FETCH, V-57
float and float(p) datatypes, V-161
floating point datatypes, V-161
FLOOR() function, V-98
frame, V-146
default, V-151
limitations of, V-156
ROWS-type vs. RANGE-type, V-149
usage note re: UNBOUNDED L/R sides,
free space
VACUUM command reference, V-92
FROM clause, V-77
AS to rename table, V-77
omission OK, V-82
V-153
Index
V--213
FULL JOIN, V-77
FULL OUTER JOIN, V-77
functional index, V-30
functions, V-95
AVG, V-146
COUNT, V-146
date and time, V-123
DENSE_RANK, V-139
formatting datatypes, V-121
LAG, V-145
LEAD, V-145
mathematical, V-97
MAX, V-146
MIN, V-146
ncluster_storagestat, V-93
RANK, V-139
ROW_NUMBER, V-139
STDDEV, V-131
STDDEV_POP, V-131
STDDEV_SAMP, V-131
string, V-100
SUM, V-146
VARIANCE, V-131
VAR_POP, V-131
VAR_SAMP, V-131
window functions, V-137
G
garbage collection, V-92
get latest documentation, V-vii
GiST index, V-176
GRANT, V-61
greater than, V-96
GREATEST SQL commands
GREATEST, V-133
greedy regular expression, V-118
group
vs. role, V-31
GROUP BY
namespace, V-82
no aliases allowed in, V-77
window function with, V-152
GROUP BY Clause, V-78
H
hash function, V-102
HAVING Clause, V-79
help, V-vi
hexadecimal, convert to, V-103
history of queries, V-195
hour in timestamp, V-126
I
identifier, quoted or delimited, V-200
IIS, V-64
ILIKE, V-109
IN, V-133
index, V-29
CREATE INDEX, V-29
expression-based index, V-30
list of indexes, V-191
null values and indexing, V-30
system tables for, V-191
type B-tree, V-29
type GiST, V-176
indexing
CREATE INDEX, V-29
REINDEX, V-70
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
table privileges and, V-61
INHERITS, V-37
CREATE TABLE option, V-37
limitations on inheritance, V-37
what is and what is not inherited?, V-37
initcap() function, V-101
IN/NOT IN, V-133
input format, time and date values, V-165
INSERT, V-64
example using VALUES to insert multiple rows, V-65
VALUES clause, V-64
INSERT INTO ... SELECT ... statement, V-64
installed files
system tables for, V-188
integer datatype, V-159
integer, serialized, V-162
INTERSECT Clause, V-79
interval datatype, V-165
in expressions, V-123
interval functions, V-124
int, int2, int4, and int8 datatypes, V-160
IP address datatype, V-172
IP address range datatype, V-174
ip4 datatype, V-172
ip4r datatype, V-174
ip4range
index of, V-176
ip4range datatype, V-174
IPv4 datatype, V-172
IS DISTINCT FROM, V-97
IS NOT, V-96
IS NULL
indexes and, V-30
IS NULL, V-96
isfinite function, V-124
IS, our definition of, V-96
J
join
type, V-77
join type, V-77
justify_days function, V-124
justify_interval function, V-124
V--214 Database SQL and Function Reference, version 4.6.2
aster data
K
N
keywords, V-3
keyword, rules for, V-200
known issues
window functions, V-155
naming, V-199
naming conventions, V-199
NaN, V-161
NATURAL join, V-78
nCluster-PostgreSQL command compatibility, V-3
ncluster_loader
error-capture tables for, V-196
ncluster_storagestat, V-93
nc_ tables, V-194
nc_all_ tables, V-186
nc_all_columns, V-190
nc_all_constraints, V-191
nc_all_databases, V-187
nc_all_group_members, V-187
nc_all_indexes, V-191
nc_all_inherit, V-193
nc_all_roles, V-187
nc_all_schemas, V-188
nc_all_sessions, V-194
nc_all_statements, V-195
nc_all_tables, V-190
nc_all_transactions, V-195
nc_all_transaction_phases, V-195
nc_all_users, V-186
nc_cluster_storage, V-194
nc_group_members, V-187
nc_physical_node_state, V-193
nc_roles, V-187
nc_temp tables, V-198
nc_types, V-193
nc_users, V-186
nc_user_ tables, V-186
nc_user_columns, V-190
nc_user_constraints, V-191, V-192
nc_user_databases, V-187
nc_user_indexes, V-191
nc_user_inherit, V-193
nc_user_owned_ tables, V-186
nc_user_owned_columns, V-190
nc_user_owned_constraints, V-191
nc_user_owned_databases, V-187
nc_user_owned_indexes, V-191
nc_user_owned_inherit, V-193
nc_user_owned_schemas, V-188
nc_user_owned_tables, V-190
nc_user_schemas, V-188
negative infinity as floating-point type, V-161
network address
index for, V-176
network address datatypes, V-172
node
node state in system tables, V-193
serialize values across all nodes, V-162
not a number, V-161
NOT BETWEEN, V-96
not equal to, V-97
NOT IN, V-134
NOT UNKNOWN, V-97
NOT/AND/OR operators, V-95
NOT, bitwise, V-103
L
LAG() function, V-145
example, V-146
language support, V-29
leading spaces, trimming, V-102
LEAD() function, V-145
example, V-145
LEAST, V-133
LEFT JOIN, V-77
LEFT OUTER JOIN, V-77
length operator for bit strings, character strings, V-103
length() function, V-101
less than, V-96
LIKE, V-108
LIMIT, V-81
LIMIT Clause, V-81
LN() function, V-99
load
statistics about, V-197
loading
handling nulls in COPY loads, V-24
log
query history, V-195
Logical, V-192
logical partitioning
GRANT table privileges and, V-61
Logical Partition-Related System Tables, V-192
LOG() function, V-99
lowercase, to, V-100
lower() function, V-100
lpad() function, V-101
ltrim() function, V-102
M
maintenance, V-92
mathematical functions, V-98
mathematical operators, V-97
max function, V-130
md5 hash, V-102
md5() function, V-102
memory settings, V-85
MERGE, V-66
metadata system tables, V-186
microseconds in timestamp, V-126
millenium in timestamp, V-126
milliseconds in timestamp, V-126
min function, V-130
minute in timestamp, V-126
MOD() function, V-99
month in timestamp, V-126
MOVE, V-69
moving average, V-150
December 14, 2011
Index
V--215
now(), V-129
now() function, V-124
nPath
examples, V-104
null
add NOT NULL constraint, V-9
handling nulls in COPY loads, V-24
indexes and nulls, V-30
null value, checking for, in SQL, V-96
NULLIF, V-133
NULLS FIRST, V-80
window functions and, V-137
NULLS LAST, V-80
window functions and, V-137
numbering window functions, V-139
O
object, V-61
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
OFFSET, V-81
ON
ON, for join conditions, V-78
ON DUPLICATE KEY UPDATE: Use MERGE
instead, V-66
ONLY, V-77
in ALTER TABLE, V-13
in DELETE, V-49
in SELECT, V-77
in UPDATE, V-89
operators, V-95
comparison, V-96
date and time, V-123
logical, V-95
mathematical, V-97
string, V-100
OR/AND/NOT operators, V-95
ORDER BY, V-80
consistent sorting of window function input
rows, V-153
in OVER clause, V-146
namespace, V-82
PARTITION BY should always be used, V-156
window frames and, V-149
window functions and, V-137
order of input rows, V-146
order of output rows, V-80
window functions and, V-138
OR, bitwise, V-103
output format, time and date values, V-168
output row ordering, V-80
window functions and, V-138
OVER, V-137
in window function, V-137
not used to sort output, V-138
sort order of input rows, V-146
overlay() function, V-100
P
padding out text strings, V-101
parameter, V-83
performance settings, V-83
SET value, V-83
settings for SQL, V-83
parent table, V-37
change inheritance with ALTER TABLE, V-12
declare parent of new child table, V-37
passing along table privileges to children, V-61
PARTITION BY, V-137
always include when sorting, V-156
in window function, V-137
performance considerations, V-154
partition key
cannot add to or drop from existing table, V-13
CLUSTER and, V-21
CREATE TABLE AS with partition key, V-42
UPDATE not allowed, V-90
partition key: See distribution key
partitioning
automatic partition during COPY, V-25
CLUSTER and, V-21
repartitioning perfomance for window
functions, V-154
serialized IDs and, V-162
pattern matching, V-108
bracket expression, V-114
list of approaches to pattern matching, V-108
regex matching rules, V-118
search and replace, V-111
with LIKE, V-108
with POSIX regular expression, V-110
with SIMILAR TO, V-109
with SUBSTRING, V-111
pattern matching functions, V-108
performance tuning, V-83
avoiding scanning for IS NULL, V-30
server-side cursors, V-46
SET command, V-83
permissions
applying to users, V-31
GRANT, V-61
list of SQL-MapReduce privileges, V-188
REVOKE, V-71
schemas for setting user rights, V-188
pipe operator for concatenation, V-100
PI() function, V-99
planner settings, V-83
portal, V-vi
position operator for bit strings, character strings, V-103
position() function, V-100
POSIX regular expression, V-110
PostgreSQL-nCluster command compatibility, V-3
POWER() function, V-99
primary key, V-38
cannot add to or drop from existing table, V-13
declaring in CREATE TABLE, V-38
serial columns and, V-163
V--216 Database SQL and Function Reference, version 4.6.2
aster data
Q
QTR in timestamp, V-127
quarter in timestamp, V-127
query
anayzing, V-57
list of statements run, V-195
query planner settings, V-83
quote characters, V-200
quoted identifier, V-200
quoted identifier (object name), V-200
quote_ident() function, V-102
quote_literal() function, V-102
quoting conventions, V-200
R
RADIANS() function, V-99
RANGE, V-147
RANGE clause syntax, V-148
range of IP addresses, V-174
RANGE UNBOUNDED FOLLOWING, V-148
RANGE UNBOUNDED PRECEDING, V-148
RANGE UNBOUNDED PRECEDING example, V-150
RANGE-based window frames, V-149
example, V-150
RANK() function, V-139
compared with DENSE_RANK(), V-141
example, V-140, V-142, V-143
RE (type of regex), V-112
real datatype, V-161
regex, V-110
bracket expression, V-114
BRE, V-120
detailed syntax, V-112
matching rules, V-118
regex types, switching between, V-117
regexp_replace, V-111
regexp_replace() function, V-102
regexp_split_to_table, V-111
regexp_split_to_table() function, V-102
regular expression, V-110
atom syntax, V-113
bracket expression, V-114
BRE, V-120
constraint syntax, V-114
detailed syntax, V-112
escape characters, V-115
greedy or not, V-118
matching rules, V-118
quantifier syntax, V-113
RE vs. ERE vs. ARE vs. BRE, V-112
regex types, switching between, V-117
regular expressions
metasyntax for, V-117
REINDEX, V-70
release notes, V-154
window functions, V-155
rename queried column with AS, V-77
rename queried table with AS, V-77
repartitioning, V-154
repeat() function, V-102
December 14, 2011
replace characters in a string, V-103
REPLACE INTO: Use MERGE instead, V-66
replace() function, V-102
reserved words, V-3
REVOKE, V-71
revoke user’s right to create tables, V-72
RIGHT JOIN, V-77
RIGHT OUTER JOIN, V-77
rights, applying to users, V-31
role, V-187
CREATE ROLE, V-31
deleting, V-52
GRANT on roles, V-63
REVOKE, V-71
system table for, V-187
vs. group, V-31
ROLLBACK, V-74
ROUND() function, V-99
ROWS, V-147
ROWS clause syntax, V-147
ROWS syntax examples, V-148
ROWS n FOLLOWING, V-148
ROWS n PRECEDING, V-148
ROWS UNBOUNDED FOLLOWING, V-148
ROWS UNBOUNDED PRECEDING, V-148
ROWS-based window frames, V-149
example, V-150
ROW_NUMBER() function, V-139
example, V-140, V-142
row, deleting, V-49
rpad() function, V-102
rtrim() function, V-102
running average, V-149
running sum, V-151
runtime settings
SET value, V-83
S
scalar functions, V-95
scanning, avoiding for IS NULL queries, V-30
schema, V-32
ALTER SCHEMA, V-8
CREATE SCHEMA, V-32
DROP SCHEMA, V-53
list of schemas in database, V-188
schema search path
setting with SET, V-84
scope of user rights, V-188
search and replace, V-111
search_path
SET and, V-84
second in timestamp, V-127
security
SQL-MapReduce system tables for, V-188
SELECT, V-75
AS keyword for column alias, V-77
AS keyword for table alias, V-77
command reference, V-75
creating a table with SELECT output, V-42
DISTINCT Clause, V-81
examples, V-82
Index
V--217
EXCEPT Clause, V-80
FROM clause, V-77
GROUP BY Clause, V-78
HAVING Clause, V-79
INTERSECT Clause, V-79
LIMIT Clause, V-81
ORDER BY clause, V-80
processing order, V-76
WHERE Clause, V-78
serial, V-162
serial column, V-162
primary key declaration not recommended, V-163
serial global column, V-162
serial local, V-162
serial4, V-162
serial8, V-162
serialize values across nodes, V-162
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
performance tuning, V-83
SET value, V-83
shift left, bitwise operator, V-103
shift right, bitwise operator, V-103
SHOW, V-85
command reference, V-85
SIGN() function, V-99
SIMILAR TO, V-109
single quotes
for time and date values, V-165
SIN() function, V-100
smallint datatype, V-159
SOME, V-134
sorting input rows, V-146
consistency of, V-153
OVER clause, V-146
sorting output rows, V-80
window functions and, V-138
space
storage state, V-194
spaces in table and column names, V-200
spaces, trimming leading spaces, V-102
split_part() function, V-102
SQL, V-3
SQL aggregate, V-137
SQL command compatibility, V-3
SQL commands, V-3
ALL, V-135
ALTER SCHEMA, V-8
ANY, V-134
CASE, V-131
CLOSE, V-20
COALESCE, V-132
CREATE SCHEMA, V-32
DROP SCHEMA, V-53
EXISTS, V-133
INSERT, V-64
LEAST, V-133
LIKE, V-108
MERGE, V-66
NOT IN, V-134
NULLIF, V-133
ORDER BY in a window function, V-137
OVER, V-137
PARTITION BY in a window function, V-137
SIMILAR TO, V-109
SOME, V-134
SUBSTRING, V-110
SQL functions
regexp_replace, V-111
regexp_split_to_table, V-111
SUBSTRING, V-111
SQL-MapReduce
repartitioning perfomance, V-154
security system tables, V-188
views and, V-46
SQRT() function, V-99
square brackets for quoting, V-200
START TRANSACTION, V-87
state tables, V-193
statements, list of statements run, V-195
statistics, V-194
data loading stats, V-197
statistics functions, V-130
statistics tables, V-194
stats db, V-194
statsdb, V-194
STDDEV function, V-131
STDDEV_POP function, V-131
STDDEV_SAMP function, V-131
storage state, V-194
string, V-100
convert to ASCII, V-103
count characters in, V-101
padding out with filler text, V-101
replace characters in, V-103
split into rows, V-111
splitting, V-102
trim spaces or characters, V-102
string functions, V-100
string operators, V-103
string value, manipulating, V-100
strpos() function, V-103
subselect, V-77
SUBSTRING, V-110, V-111
example, V-119
substring, V-102
extract, V-103
replace, V-102
substring operator for bit strings, character strings, V-103
substring, finding, V-100
substring() function, V-100
substr() function, V-103
sum function, V-130
SUM() function
example, running sum, V-151
support, V-vi
symbols, V-96
V--218 Database SQL and Function Reference, version 4.6.2
aster data
mathematical, V-97
symmetric between, V-96
system state, V-193
system statistics, V-194
system tables, V-185
nc_all_child_partitions, V-192
nc_all_columns, V-190
nc_all_constraints, V-191
nc_all_databases, V-187
nc_all_group_members, V-187
nc_all_indexes, V-191
nc_all_inherit, V-193
nc_all_roles, V-187
nc_all_schemas, V-188
nc_all_sessions, V-194
nc_all_statements, V-195
nc_all_tables, V-190
nc_all_transactions, V-195
nc_all_transaction_phases, V-195
nc_all_users, V-186
nc_cluster_storage, V-194
nc_group_members, V-187
nc_physical_node_state, V-193
nc_roles, V-187
nc_types, V-193
nc_users, V-186
nc_user_child_partitions, V-192
nc_user_columns, V-190
nc_user_constraints, V-191, V-192
nc_user_databases, V-187
nc_user_indexes, V-191
nc_user_inherit, V-193
nc_user_owned_child_partitions, V-192
nc_user_owned_columns, V-190
nc_user_owned_constraints, V-191
nc_user_owned_databases, V-187
nc_user_owned_indexes, V-191
nc_user_owned_inherit, V-193
nc_user_owned_schemas, V-188
nc_user_owned_tables, V-190
nc_user_schemas, V-188
SQL-MapReduce-related, V-188
statistics tables, V-194
T
table
CREATE TABLE, V-34
list of tables in database, V-190
removing, V-53
revoke user’s right to create tables, V-72
table alias, V-77
table naming conventions, V-199
case sensitivity, V-200
TAN() function, V-100
technical support, V-vi
telephone number, V-vi
TEMPORARY privilege not supported, V-63
temporary system tables, V-198
text datatype, V-163
text substitution, V-111
tilde operator, V-109, V-110
December 14, 2011
time, V-165
clock_timestamp() function, V-124
daylight savings rules, V-169
functions for, V-123
now() function, V-124
return current time, V-129
templates for formatting, V-121
time datatypes, V-165
functions for, V-123
time values, inserting, V-165
time values, retrieving, V-168
time zone, V-165
in data input, V-165
timestamp, V-124, V-129
extract subset, V-124
vs. now() function, V-124
timestamp input format, V-167
timezone in timestamp, V-127
to_ functions, V-121
to_ascii() function, V-103
to_char function, V-121
examples, V-123
to_date function, V-121
to_hex() function, V-103
to_number function, V-121
to_timestamp function, V-121
transaction
COMMIT, V-22
END, V-56
phases, V-195
ROLLBACK, V-74
start time of transaction, V-124
starting, V-87
statistics, V-195
translate() function, V-103
TRIGGER privilege not supported, V-63
trigonometric functions, V-99
trim spaces or characters from strings, V-102
trim() function, V-101
troubleshooting
cannot update or drop table, V-46
TRUE, V-97
true/false datatype, V-169
TRUNCATE, V-88
truncate date, V-128
synopsis, V-124
TRUNC() function, V-99
tuning, V-83
SET command, V-83
typeface conventions, V-v
types, V-157
listing from SQL prompt, V-193
U
unicode, V-29
UNION Clause, V-79
unique ID across cluster, V-162
universally unique identifier, V-178
UNKNOWN, V-97
updatable cursor, V-48
UPDATE, V-89
Index
V--219
cannot update a partition key value, V-90
command reference, V-89
updated documentation, V-vii
uppercase, to, V-101
upper() function, V-101
URL, V-vi
Aster Data Support URL, V-vi
user
CREATE USER, V-43
deleting, V-54
GRANT permissions, V-61
permissions list for SQL-MapReduce, V-188
permissions set using schemas, V-188
privileges in database, V-31
REVOKE permissions, V-71
system table for, V-186
user activity tables, V-194
UTF-8
default encoding, V-29
utilities
ncluster_storagestat, V-93
uuid datatype, V-178
V
VACUUM, V-92
command reference, V-92
VALUES
example, V-65
reference, V-64
VALUES clause
example, V-65
not supported in nCluster SELECT, V-82
reference, V-64
varchar, V-163
functions and, V-100
VARIANCE function, V-131
VAR_POP function, V-131
VAR_SAMP function, V-131
version
documentation version, V-vii
view, V-45
and SQL-MapReduce, V-46
virtual worker
memory settings per worker, V-85
AVG, V-146
COUNT, V-146
default frame, V-151
DENSE_RANK, V-139
frame, V-146
frame limitations, V-156
frame types, V-149
known issues, V-155
LAG, V-145
LEAD, V-145
MAX, V-146
MIN, V-146
numbering window functions, V-139
RANGE, V-149
RANK, V-139
ROWS, V-149
ROW_NUMBER, V-139
SUM, V-146
syntax synopsis, V-137
usage note regarding frames, V-153
window table functions, V-139
worker node
memory settings per virtual worker, V-85
X
XOR, bitwise, V-103
Y
year in timestamp,
V-127
Symbols
_bee_stats, V-194
, , =, != operators in SQL, V-96
:: for CAST, V-179
+, -, =, etc., V-97
<> operator, V-97
W
week in timestamp, V-127
WHERE Clause, V-78
WHERE CURRENT OF, V-48
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
sorting output rows, V-138
window functions, V-137
aggregate window functions, V-146
V--220 Database SQL and Function Reference, version 4.6.2
aster data