database sql and function reference

December 14, 2011 V--i

Teradata Aster MapReduce Appliance 2 Database SQL and Function Reference

Version 4.6.2 — December 14, 2011Updated versions of this guide: http://tays.teradata.com

Contents

Preface ............................................................................................................................................................. V--v

Conventions Used in This Guide ............................................................................................................... V--vContacting Technical Support ................................................................................................................ V--viAbout Aster Data ....................................................................................................................................... V--viAbout This Document ............................................................................................................................... V--vii

Aster SQL and Function Reference V--1

V--1 SQL Commands V--3

ABORT ........................................................................................................................................................... V--6ALTER INDEX ................................................................................................................................................. V--7ALTER ROLE ................................................................................................................................................... V--7ALTER SCHEMA ............................................................................................................................................. V--8ALTER TABLE .................................................................................................................................................. V--9ALTER USER ................................................................................................................................................. V--15ALTER VIEW ................................................................................................................................................. V--16ANALYZE ...................................................................................................................................................... V--17BEGIN .......................................................................................................................................................... V--18CASE ............................................................................................................................................................ V--20CLOSE .......................................................................................................................................................... V--20CLUSTER ...................................................................................................................................................... V--21COALESCE .................................................................................................................................................. V--22COMMIT ...................................................................................................................................................... V--22COPY ........................................................................................................................................................... V--23CREATE DATABASE ..................................................................................................................................... V--28CREATE INDEX ............................................................................................................................................ V--29CREATE ROLE .............................................................................................................................................. V--31CREATE SCHEMA ....................................................................................................................................... V--32CREATE TABLE ............................................................................................................................................. V--34CREATE TABLE AS ....................................................................................................................................... V--42CREATE USER .............................................................................................................................................. V--43CREATE VIEW .............................................................................................................................................. V--45DECLARE ..................................................................................................................................................... V--46DELETE ......................................................................................................................................................... V--49DROP DATABASE ........................................................................................................................................ V--51DROP INDEX ................................................................................................................................................ V--51

http://tays.teradata.com/

V--ii Database SQL and Function Reference, version 4.6.2 aster data

DROP ROLE ................................................................................................................................................. V--52DROP SCHEMA ........................................................................................................................................... V--53DROP TABLE ................................................................................................................................................ V--53DROP USER .................................................................................................................................................. V--54DROP VIEW ................................................................................................................................................. V--55END .............................................................................................................................................................. V--56EXPLAIN ....................................................................................................................................................... V--57FETCH .......................................................................................................................................................... V--57GRANT ......................................................................................................................................................... V--61INSERT .......................................................................................................................................................... V--64MERGE ......................................................................................................................................................... V--66MOVE .......................................................................................................................................................... V--69REINDEX ...................................................................................................................................................... V--70REVOKE ....................................................................................................................................................... V--71ROLLBACK ................................................................................................................................................... V--74SELECT ......................................................................................................................................................... V--75SET ............................................................................................................................................................... V--83SHOW .......................................................................................................................................................... V--85START TRANSACTION ................................................................................................................................. V--87TRUNCATE ................................................................................................................................................... V--88UPDATE ........................................................................................................................................................ V--89VACUUM ..................................................................................................................................................... V--92WITH ............................................................................................................................................................. V--94

V--2 Functions and Operators V--95

Logical Operators ..................................................................................................................................... V--95Comparison Operators ............................................................................................................................ V--96Mathematical Operators and Functions ............................................................................................... V--97Trigonometric Functions ........................................................................................................................... V--99String Functions and Operators ............................................................................................................ V--100Bit String Functions and Operators ....................................................................................................... V--103SQL/MapReduce Functions .................................................................................................................. V--103nPath ......................................................................................................................................................... V--104Pattern Matching Functions and Operators ....................................................................................... V--108Datatype Formatting Functions and Operators ................................................................................. V--121Date/Time Functions and Operators ................................................................................................... V--123Aggregate Functions .............................................................................................................................. V--130Aggregate Functions for Statistics ........................................................................................................ V--130Conditional SQL Expressions ................................................................................................................. V--131Subquery SQL Expressions ..................................................................................................................... V--133

V--3 Window Functions V--137

Synopsis of Window Function Syntax ................................................................................................... V--137Window Function Order of Evaluation ................................................................................................. V--138Numbering Window Functions .............................................................................................................. V--139LEAD and LAG functions ........................................................................................................................ V--145Aggregate Window Functions .............................................................................................................. V--146Repartitioning Performance for Window Functions and SQL-MapReduce Queries ..................... V--154Deprecated Behavior ............................................................................................................................. V--154Window Function Known Issues ............................................................................................................ V--155

V--4 Datatypes V--157

List of Supported Datatypes .................................................................................................................. V--157Numeric Types ......................................................................................................................................... V--159

December 14, 2011 V--iii

Character Types ...................................................................................................................................... V--163Date/Time Types ..................................................................................................................................... V--165Bit String Types ......................................................................................................................................... V--169Boolean Types ......................................................................................................................................... V--169Binary Types ............................................................................................................................................. V--170Network Address Types .......................................................................................................................... V--172UUID Type ................................................................................................................................................. V--178Type Casts ................................................................................................................................................ V--179

V--5 Date and Time V--181

Date/Time Input Interpretation ............................................................................................................. V--181Date/Time Keywords .............................................................................................................................. V--182

V--6 Data Dictionary Views V--185

Introduction to Data Dictionary Views ................................................................................................. V--186User-Related Data Dictionary Views ..................................................................................................... V--186Role-Related Data Dictionary Views .................................................................................................... V--187Group Membership Data Dictionary Views ........................................................................................ V--187Database-Related Data Dictionary Views .......................................................................................... V--187Schema-Related Data Dictionary Views ............................................................................................. V--188SQL-MapReduce and Installed File-Related Data Dictionary Views ............................................... V--188Table-Related Data Dictionary Views .................................................................................................. V--190Column-Related Data Dictionary Views .............................................................................................. V--190Index-Related Data Dictionary Views .................................................................................................. V--191Constraint-Related Data Dictionary Views .......................................................................................... V--191Logical Partition-Related Data Dictionary Views ................................................................................ V--192Inheritance-Related Data Dictionary Views ........................................................................................ V--193Types Data Dictionary View .................................................................................................................. V--193Cluster State Data Dictionary Views .................................................................................................... V--193Activity Data Dictionary Views .............................................................................................................. V--194Temporary Data Dictionary Views ........................................................................................................ V--198

V--7 SQL Vocabulary V--199

Identifiers, Keywords, and Naming Conventions ............................................................................... V--199Comments in SQL ................................................................................................................................... V--201Value Expressions ................................................................................................................................... V--201

System Limits ............................................................................................................................................. V--203

Error Codes ................................................................................................................................................ V--205

Index .............................................................................................................................................................. V--211

V--iv Database SQL and Function Reference, version 4.6.2 aster data

December 14, 2011 Aster Data proprietary and confidential V--v

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 GuideThis 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.

TypefacesCommand 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 ConventionsIn 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 (|).

http://www.asterdata.com/support/index.php

https://everest.asterdata.com/resourcecenter

Contacting Technical Support Aster Data proprietary and confidential

V--vi Database SQL and Function Reference, version 4.6.2 aster data

• 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 ConventionsFor 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 SupportIf 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 DataAster 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.

https://everest.asterdata.com/resourcecenter



Aster Data proprietary and confidential About This Document

December 14, 2011 V--vii

About This DocumentThis 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.

http://www.asterdata.com/support

About This Document Aster Data proprietary and confidential

V--viii Database SQL and Function Reference, version 4.6.2 aster data

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

http://www.asterdata.com

December 14, 2011 V--1

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)

V--2 Database SQL and Function Reference, version 4.6.2 aster data

December 14, 2011 Aster Data proprietary and confidential V--3

V--1

SQL Commands

This chapter provides a reference for SQL and SQL-like commands supported in Aster Database. To find the command descriptions, follow the cross references in the table below. This table also lists Aster Data / PostgreSQL syntactic compatibility.

Table 1-1 Aster Data/PostgreSQL Command Compatibility

Statement Supported in Aster Database?

Supported in PostgreSQL?

Notes

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

Aster Data proprietary and confidential


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 To load a function, use Aster Database ACT’s \install command.

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



Notes


December 14, 2011 SQL Commands V--5

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



Notes

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:

• ROLLBACK (page V-74)

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

SynopsisALTER ROLE name [ [ WITH ] option [ ... ] ]

where option can be:

INHERIT | NOINHERIT

ALTER ROLE name RENAME TO newname

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

SynopsisALTER 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.

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

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.



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.

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.



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.



Parameters for ALTER TABLE

The parameters for ALTER TABLE are:

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:

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.



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:

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 [ ... ] ]


INHERIT | NOINHERIT | PASSWORD 'password'

Second variant:

ALTER USER username RENAME TO newname;

Third variant:

ALTER USER username SET search_path { TO | = } { value }

Example usageALTER 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

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

SynopsisALTER 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.

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

SynopsisANALYZE 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.

BEGIN Aster Data proprietary and confidential


Parameters

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

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.

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





• END (page V-56)


• ABORT (page V-6)


CASE Aster Data proprietary and confidential


CASESee “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.

Aster Data proprietary and confidential CLUSTER


CLUSTERThe 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

SynopsisCLUSTER 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.

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.

COALESCESee “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.


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;

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





• END (page V-56)




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 } ] ]

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.



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.

COPY Aster Data proprietary and confidential


Notes About COPYWhen 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 COPYInput 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

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).

Sequence Represents

\b Backspace (ASCII 8)

\f Form feed (ASCII 12)

\n Newline (ASCII 10)

\r Carriage return (ASCII 13)

\t Tab (ASCII 9)



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 COPYThe 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 AFGHANISTANAL ALBANIADZ ALGERIAZM ZAMBIAZW 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 '@':

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 COPYThere is no COPY statement in the SQL standard.

See AlsoSee 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.

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

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

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));

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.

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

SynopsisCREATE ROLE name [ [ WITH ] option [ ... ] ]


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.

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

SynopsisCREATE SCHEMA schemaname

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.

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 ]

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 TABLEFACT 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 See “Constraint Syntax for CREATE TABLE” on page V-37.



DISTRIBUTE BY { HASH ( distribution_key_column_name ) | REPLICATION }

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.



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

INHERITS ( parent_table ) The INHERITS clause is Aster Database’s older alternative to the newer PARTITION BY method of creating parent/child table hierarchies.

The optional INHERITS clause specifies the table from which the new table automatically inherits all columns. Use of INHERITS creates a persistent relationship between the new child table and its parent table. Schema modifications to the parent normally propagate to children as well, and by default the data of the child table is included in scans of the parent. A fact table may only inherit from another fact table, and a dimension table may only inherit from another dimension table.

What is not inherited: A child table does not inherit PRIMARY KEY constraints, nor does it inherit UNIQUE constraints or index structures defined on the parent.

What is inherited: A child table does inherit the distribution key of its parent. In other words, the distribution key of the child is the same as that of its parent, and you cannot change it. All check constraints and not-null constraints on the parent table are automatically inherited by its children.

When creating a child table, if you declare a column name that matches the name of a column in the parent, then the child column’s datatype must match that of the inherited column. The column definitions are merged into a single definition for the child table column. When you create a child table, you may add constraints that its parent does not have. Constraints inherited from the parent table(s) are added to those you declare in the child table, and this forms the set of constraints on the child table.

See “Logical Partitioning Through Inheritance (Parent/Child)” on page I-26 for details and examples.

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.



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)

PRIMARY KEY ( column_name [, ... ] ) (as a table 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.

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.



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 <> ''));

UNIQUE (as a column constraint)

UNIQUE ( column_name [, ... ] ) (as a table constraint)

The UNIQUE constraint specifies that a group of one or more columns of a table can contain only unique values. The behavior of the unique table constraint is the same as that for column constraints, with the additional capability to span multiple columns.

For the purpose of a unique constraint, null values are not considered equal.

Each unique table constraint must contain the distribution key column.

Warning! A table that will contain a large amount of data will typically have no unique constraints defined, because having them results in slower loading. Loading to a table with such constraints takes longer than loading to a table without them because Aster Database must check the uniqueness of each value in the must-be-unique column. If you have a large table that requires a unique constraint, use ALTER TABLE to add the constraint after you have loaded the data.

See also “A Note on Unique Constraints” on page V-41



In the following example we use a PARTITION BY RANGE clause to create a fact table trans with four daily child partitions using automatic logical partitioning (strictly speaking, the first partition is a catch-all for older records):

CREATE FACT TABLE trans( id int, country varchar, ts timestamp ) DISTRIBUTE BY HASH(id) PARTITION BY RANGE(ts) (

PARTITION oldrecords( END '2011-01-01' ), -- everything pre-2011 PARTITION jan01_2011( END '2011-01-02' ), PARTITION jan02_2011( END '2011-01-03' ), PARTITION jan03_2011( END '2011-01-04' ) );

This example defines a check column constraint:

CREATE DIMENSION TABLE distributors ( did integer CHECK (did > 100), name varchar(40));

This example defines a check table constraint:

CREATE DIMENSION TABLE distributors ( did integer, name varchar(40) CONSTRAINT con1 CHECK (did > 100 AND name <> ''));

This example creates a distributed dimension table, distributors, and distributes it based on its distributor id (did) values:

CREATE DIMENSION TABLE distributors ( did integer, name varchar(40) ) DISTRIBUTE BY HASH(did);

This example defines two NOT NULL column constraints on the table distributors, one of which is explicitly given a name:

CREATE DIMENSION TABLE distributors ( did integer CONSTRAINT no_null NOT NULL, name varchar(40) NOT NULL);

Compatibility

The CREATE TABLE command conforms to the SQL standard, with exceptions listed below.

Column Check Constraints The SQL standard says that CHECK column constraints may only refer to the column they apply to; only CHECK table constraints may refer to multiple columns. Aster Database does not enforce this restriction; it treats column and table check constraints alike.

NULL Constraint The NULL "constraint" (actually a non-constraint) is an Aster Database extension to the SQL standard that is included for compatibility with some other database



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);

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.

Aster Data proprietary and confidential CREATE USER


Parameters

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

SynopsisCREATE USER name [ [ WITH ] option [ ... ] ] PASSWORD 'password';


INHERIT | NOINHERIT | IN ROLE rolename [, ...] | IN GROUP rolename [, ...]

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.

DISTRIBUTE BY The DISTRIBUTE BY clause specifies either hash distribution (with a distribution key constraint) or replication.

The distribution key constraint specifies the column of a table that is to be used to determine the distribution of the table (that is, the distribution of its data in the cluster), as described in “Distribution Key” on page I-10. For a fact table, the specification of a distribution key is mandatory.

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.

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

SynopsisCREATE [ 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.

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 ]

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).

DECLARE Aster Data proprietary and confidential


Parameters for DECLARE

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.

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.

SCROLLNO 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 HOLDWITHOUT 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 UPDATEFOR READ ONLY

FOR READ ONLY specifies that the cursor will be used in a read-only mode. No data updates will be allowed.

FOR UPDATE specifies that the cursor will be an updatable cursor (that is, one that you can use to update a table or delete rows from a table). When you declare a cursor with the FOR UPDATE option, you can apply updates or deletes to rows in that cursor. To perform an update or delete, use UPDATE or DELETE with the WHERE CURRENT OF <cursor name> clause. You must perform all updates and deletes in the same transaction in which you declared the cursor. Inside the cursor, you cannot see the results of your updates and deletes; you can only scroll forward in an updatable cursor.

For a cursor to be updatable, it must be a NO SCROLL cursor and the SELECT statement in the cursor declaration must follow the rules shown below:

• It not contain a join (that is, it must select from only a single table, and that table must not be joined to itself).

• It must not contain an ORDER BY clause.

• It must specify a table, not a view. (Views are read-only.)

• It must not contain a GROUP BY clause.

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.

DELETE Aster Data proprietary and confidential


Parameters for DELETE

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;

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.

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

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 ];

name The name of a database to remove.

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

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

SynopsisDROP 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.

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.

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

SynopsisDROP 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 ];

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

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

SynopsisDROP USER name [, ...];

Example UsageDROP 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.

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.

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

SynopsisDROP 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.

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









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:

FETCH Aster Data proprietary and confidential


NEXTPRIORFIRSTLASTABSOLUTE countRELATIVE countcountALLFORWARDFORWARD countFORWARD ALLBACKWARDBACKWARD countBACKWARD 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.

Aster Data proprietary and confidential FETCH


Parameters

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.

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.

cursorname An open cursor’s name.

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.

Aster Data proprietary and confidential GRANT


GRANT

GRANT -- define access privileges

Synopsis GRANT { { SELECT | INSERT | UPDATE | DELETE } [,...] | ALL [ PRIVILEGES ] } ON [ TABLE ] tablename [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] [ CASCADE ]

GRANT { { CREATE | CONNECT } [,...] | ALL [ PRIVILEGES ] } ON DATABASE dbname [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ]

GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ON SCHEMA schemaname [, ...] TO { username | GROUP rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ]

GRANT { INSTALL FILE | CREATE FUNCTION } [, ...] [ PRIVILEGE ] ON SCHEMA schemaname [, ...] TO { username | GROUP rolename | PUBLIC } [, ...]

GRANT EXECUTE [ PRIVILEGE ] ON FUNCTION [schemaname.]funcname TO { username | GROUP rolename | PUBLIC } [, ...]

GRANT rolename [, ...] TO username [, ...] [ WITH ADMIN OPTION ];

Description

The GRANT command has two basic variants: one that grants privileges on a database object like a table or database (see “GRANT on Database Objects” on page V-61) and one that grants membership in a role (see “GRANT on Roles” on page V-63). These variants are similar in many ways, but they are different enough that we’ll describe them separately, below.

GRANT on Database Objects

This variant of the GRANT command gives privileges on a database object to one or more roles. These privileges are added to those already granted, if any.

The keyword PUBLIC specifies that the privileges are to be granted to all roles, including those that might be created later. PUBLIC can be thought of as an implicitly defined group that always includes all roles. Any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to PUBLIC.

If WITH GRANT OPTION is specified, the recipient of the privilege may in turn grant it to others. Without a grant option, the recipient cannot do that. Grant options cannot be granted to PUBLIC.

If CASCADE is specified, then the rights you grant on a parent table cascade to all its child tables. CASCADE works only when granting table privileges.

There is no need to grant privileges to the owner of an object (usually the user that created it), as the owner has all privileges by default. The right to drop an object, or to alter its definition in any

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.

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.

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

Outputs

On successful completion, an INSERT command returns a command tag of the form

INSERT oid count

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.

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);

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.

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

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)

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.

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

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.

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.

Note! Aster Database does not support reindexing the whole database. To reindex your database, run REINDEX on each table in the database.

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.

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.

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

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






• END (page V-56)



Aster Data proprietary and confidential SELECT


SELECT

SELECT -- retrieve rows from a table or viewSee 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 SELECTSELECT [ 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 [, ...] ) ]

SELECT Aster Data proprietary and confidential


Description of SELECTSELECT 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 StatementWe 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



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.

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

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.



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 [, ...]



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:



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



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



promise to deliver the results of a query in any particular order unless ORDER BY is used to constrain the order.

Examples of SELECT StatementsTo 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 SELECTThe 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

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.

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.

SET Aster Data proprietary and confidential


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.


Aster Data proprietary and confidential SHOW


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

SynopsisSHOW 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.

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


SHOW Aster Data proprietary and confidential


Parameters for SHOW

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.


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.

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


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





• END (page V-56)

TRUNCATE Aster Data proprietary and confidential





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

SynopsisTRUNCATE [ 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

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.

UPDATE Aster Data proprietary and confidential


Parameters

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'

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.

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.

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.

Aster Data proprietary and confidential VACUUM


Parameters

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.

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.

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--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

Comparison Operators Aster Data proprietary and confidential


Comparison OperatorsAster Database supports the following comparison operators:

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 NULLexpression 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.

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

Aster Data proprietary and confidential Mathematical Operators and Functions

December 14, 2011 Functions and Operators V--97

Note: If the expression is row-valued, then IS NULL is true when the row expression itself is null or when all the row's fields are null, while IS NOT NULL is true when the row expression itself is non-null and all the row's fields are non-null. This definition conforms to the SQL standard.

The ordinary comparison operators yield null (signifying "unknown") when either input is null. Another way to do comparisons is with the IS DISTINCT FROM construct:

expression IS DISTINCT FROM expression

For non-null inputs, IS DISTINCT FROM is the same as the <> operator. However, when both inputs are null it will return false, and when just one input is null it will return true.

Boolean values can also be tested using the constructs:

expression IS TRUEexpression IS NOT TRUEexpression IS FALSEexpression IS NOT FALSEexpression IS UNKNOWNexpression IS NOT UNKNOWN

These will always return true or false, never a null value, even when the operand is null. A null input is treated as the logical value "unknown". Notice that IS UNKNOWN and IS NOT UNKNOWN are effectively the same as IS NULL and IS NOT NULL, respectively, except that the input expression must be of Boolean type.

Mathematical Operators and FunctionsMathematical 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.

Operator

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

Mathematical Operators and Functions Aster Data proprietary and confidential


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

||/ 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

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.6478897565412

exp(dp or numeric) (same as input) exponential exp(1.0) 2.71828182845905

floor(dp or numeric) (same as input) largest integer not greater than argument

floor(-42.8) -43

Aster Data proprietary and confidential Trigonometric Functions


Trigonometric FunctionsAster Database supports the following trigonometric functions. In the table, dp indicates double precision.

Table 2-3 Trigonometric functions supported by Aster Database.

ln(dp or numeric) (same as input) natural logarithm ln(2.0) 0.693147180559945

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.0000000000

mod(y, x) (same as argument types)

remainder of y/x mod(9,4) 1

pi() dp "\u03c0" constant pi() 3.14159265358979

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.785398163397448

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.4142135623731

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

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

String Functions and Operators Aster Data proprietary and confidential


String Functions and OperatorsThis 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 OperatorsSQL 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.

sin(x) dp sine

tan(x) dp tangent

Function Return 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

Aster Data proprietary and confidential String Functions and Operators


Additional String Functions and Operators

Table 2-5 Additional string functions supported by Aster Database.

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



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('xyxtrimyyx', '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

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') 900150983cd24fb0 d6963f7d28e17f72

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+')

helloworld(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

Aster Data proprietary and confidential SQL/MapReduce Functions


Bit String Functions and OperatorsThis 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.

The following SQL-standard functions work on bit strings as well as character strings: length, bit_length, octet_length, position, substring.

SQL/MapReduce FunctionsSQL-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

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('alphabet', 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('12345', '14', 'ax')

a23x5

Operator


|| 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

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 ... ]

nPathnPath 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 SynopsisSELECT ...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 [, ...] ) ) [, ... ]

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 PatternA pattern consists of several elements:

• Symbols

• Operators

• Nesting parentheses

• Anchors

nPath SymbolsA 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 OperatorsThe following operators may be used in a pattern:

The precedence of operators are, from highest to lowest:

1. Cascade operator (".")

Character

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

nPath Aster Data proprietary and confidential


2. Alternative operator ("|")

3. Frequency operators ("?", "*", "+").

Operators with equal precedence associate left to right.

Nesting parentheses in nPathPatterns can be nested using parentheses "(" and ")".

nPath AnchorsThe 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_pageidFROM 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, rankFROM 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.

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 >= 5GROUP BY last_pageidORDER BY MAX(count_page80)

nPath AggregatesThe 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()

Pattern Matching Functions and Operators Aster Data proprietary and confidential


Pattern Matching Functions and OperatorsThere 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).

LIKEstring LIKE pattern [ESCAPE escape-character]string NOT LIKE pattern [ESCAPE escape-character]

Every pattern defines a set of strings. The LIKE expression returns true if the string is contained in the set of strings represented by pattern. (As expected, the NOT LIKE expression returns false if LIKE returns true, and vice versa. An equivalent expression is NOT (string LIKE pattern).)

If pattern does not contain percent signs or underscore, then the pattern only represents the string itself; in that case LIKE acts like the equals operator. An underscore (_) in pattern stands for (matches) any single character; a percent sign (%) matches any string of zero or more characters.

Some examples:

'abc' LIKE 'abc' true'abc' LIKE 'a%' true'abc' LIKE '_b_' true'abc' LIKE 'c' false

LIKE pattern matches always cover the entire string. To match a sequence anywhere within a string, the pattern must therefore start and end with a percent sign.

To match a literal underscore or percent sign without matching other characters, the respective character in pattern must be preceded by the escape character. The default escape character is the backslash but a different one may be selected by using the ESCAPE clause. To match the escape character itself, write two escape characters.

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

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 Expressionsstring 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:

Notice that bounded repetition (? and {...} ) are not provided, though they exist in POSIX. Also, the dot (.) is not a metacharacter.

As with LIKE, a backslash disables the special meaning of any of these metacharacters; or a different escape character can be specified with ESCAPE.

Some examples:

'abc' SIMILAR TO 'abc' true'abc' SIMILAR TO 'a' false'abc' SIMILAR TO '%(b|d)%' true'abc' SIMILAR TO '(b|c)%' false

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.



SUBSTRING Function with Three ParametersThe 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 ExpressionsThe following table lists the available operators for pattern matching using POSIX regular expressions.

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' true'abc' ~ '^a' true'abc' ~ '(b|d)' true'abc' ~ '^(b|c)' false

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.*'



SUBSTRING Function with Two ParametersThe 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') oobSELECT SUBSTRING('foobar' FROM 'o(.)b') o

regexp_replace FunctionThe 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') fooXbazregexp_replace('foobarbaz', 'b..', 'X', 'g') fooXXregexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g') fooXarYXazY

regexp_split_to_table FunctionThe 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 ExamplesSELECT regexp_split_to_table('the quick brown fox jumped over the lazy dog', '\\\s+');

foo



-------- 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 DetailsAster 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.



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

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

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

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 +



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

Lookahead constraints cannot contain back references and all parentheses within them are considered non-capturing.

Bracket ExpressionsA 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.

?? non-greedy version of ?

{m}? non-greedy version of {m}

{m,}? non-greedy version of {m,}

{m,n}? non-greedy version of {m,n}

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)



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 EscapesEscapes 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



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

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.)

\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

Escape Description

\d [[:digit:]]

\s [[:space:]]

\w [[:alnum:]_] (note underscore is included)

\D [^[:digit:]]

\S [^[:space:]]

\W [^[:alnum:]_] (note underscore is included)



Table 2-11 Table: Regular Expression Constraint Escapes

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

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 MetasyntaxIn 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

Escape

Description

\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

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

Option Description

b rest of RE is a BRE



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 RulesIn 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.

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)



• 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



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 CompatibilityNo 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 ExpressionsBREs 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.

Aster Data proprietary and confidential Datatype Formatting Functions and Operators


Datatype Formatting Functions and OperatorsThe 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

The following table shows the template patterns available for formatting date and time values:

Table 2-15 Data and time template patterns


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)

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)

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)

Aster Data proprietary and confidential Date/Time Functions and Operators


Table 2-16 to_char Examples

Date/Time Functions and OperatorsAll 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 OperatorsThe following table illustrates the behaviors of the basic arithmetic operators (+, *, etc.) with date/time values:

Table 2-17 Date/Time Operators

Expression Result

to_char(current_timestamp, 'Day, DD HH12:MI:SS') 'Tuesday , 06 05:39:18'

to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS') 'Tuesday, 6 05:39:18'

Operator

Example Result

+ 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'

Date/Time Functions and Operators Aster Data proprietary and confidential


Date/Time FunctionsThe following table shows the available functions for date/time value processing, with additional information on several functions following:

EXTRACT FunctionEXTRACT(field FROM source)

/ interval '1 hour' / double precision '1.5'

interval '00:40:00'



clock_timestamp() timestamp with time zone

Current date and time (changes during statement execution). See also now()

SELECT clock_timestamp();

Current timestamp

date_part(text, timestamp)

double precision

Get subfield (equivalent to extract). See also “date_part Function” on page V-127.

date_part('hour', timestamp '2001-02-16 20:38:40')

20

date_part(text, interval)

double precision

Get subfield (equivalent to extract)

date_part('month', interval '2 years 3 months')

3

date_trunc(text, timestamp)

timestamp Truncate to specified precision. See also “date_trunc Function” on page V-128.

date_trunc('hour', timestamp '2001-02-16 20:38:40')

2001-02-16 20:00:00

extract(field from timestamp)

double precision

Get time or date subfield. See also “EXTRACT Function” on page V-124.

extract(hour from timestamp '2001-02-16 20:38:40')

20

extract(field from interval)

double precision

Get time or date subfield extract(month from interval '2 years 3 months')

3

isfinite(timestamp)

Boolean Test for finite time stamp (not equal to infinity)

isfinite(timestamp '2001-02-16 21:28:30')

true

isfinite(interval) Boolean Test for finite interval isfinite(interval '4 hours')

true

justify_days(interval)

interval Adjust interval so 30-day time periods are represented as months

justify_days(interval '30 days')

1 month

justify_hours(interval)

interval Adjust interval so 24-hour time periods are represented as days

justify_hours(interval '24 hours')

1 day

justify_interval(interval)

interval Adjust interval using justify_days and justify_hours, with additional sign adjustments

justify_interval(interval '1 mon -1 hour')

29 days 23:00:00

now() timestamp Date and time of the start of the transaction. See also clock_timestamp()

SELECT now(); Time of the start of this transaction.



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:



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



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 Functiondate_part('field', source)



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 FunctionThe 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 ExamplesSELECT 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



Current Date/TimeAster 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_DATECURRENT_TIMECURRENT_TIMESTAMPCURRENT_TIME(precision)CURRENT_TIMESTAMP(precision)LOCALTIMELOCALTIMESTAMPLOCALTIME(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)

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 FunctionsAggregate 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

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 StatisticsnClsuter supports a number of aggregate functions typically used in statistical analysis.

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

COUNT(*) bigint number of input rows

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

Aster Data proprietary and confidential Conditional SQL Expressions


Table 2-19 Aggregate Functions for Statistics

Conditional SQL ExpressionsThis section describes the SQL-compliant conditional expressions available in Aster Database.

CASEThe 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,

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


population standard deviation of the input values

STDDEV_SAMP(expression) smallint, int, bigint, real, double precision, or numeric


sample standard deviation of the input values

VARIANCE(expression) smallint, int, bigint, real, double precision, or numeric


historical alias for var_samp

VAR_POP(expression) smallint, int, bigint, real, double precision, or numeric


population variance of the input values (square of the population standard deviation)

VAR_SAMP(expression) smallint, int, bigint, real, double precision, or numeric


sample variance of the input values (square of the sample standard deviation)

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;

COALESCECOALESCE(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.

Aster Data proprietary and confidential Subquery SQL Expressions


NULLIFNULLIF(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 LEASTGREATEST(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 ExpressionsThis 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.

EXISTSEXISTS (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.

INexpression 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).

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 INexpression 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.


See also the Note on SQL Compliance in the section above explaining “IN”.

ANY/SOMEexpression 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.


Aster Data proprietary and confidential Subquery SQL Expressions


ALLexpression 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.


Subquery SQL Expressions Aster Data proprietary and confidential



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 SyntaxInvoking 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:

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.

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 EvaluationFrom 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.

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.

Aster Data proprietary and confidential Numbering Window Functions

December 14, 2011 Window Functions V--139

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 FunctionsThe 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

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 ExamplesThe 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_numberFROM 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,



RANK() OVER ( PARTITION BY dept ORDER BY age ) AS rankFROM 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_rankFROM 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.



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_rankFROM 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.



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_groupFROM 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_departmentFROM 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 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_rankFROM employeesORDER 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

Aster Data proprietary and confidential LEAD and LAG functions


4 | 233 | 130000 | 0(11 rows)

Above, we have written a query similar to that shown in Example 7, but this time we perform the subtraction operation directly on the window function, which is the proper usage.

LEAD and LAG functionsLEAD 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.

SyntaxThe 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_diffFROM employees;

dept | empnum | salary | age | salary_diff ------+--------+--------+-----+------------- 100 | 3 | 42000 | 23 | -8010 100 | 1 | 50010 | 27 | 5010

Aggregate Window Functions Aster Data proprietary and confidential


101 | 2 | 45000 | 30 | -342999 101 | 10 | 387999 | 32 | 331999 101 | 5 | 56000 | 32 | 7235 100 | 9 | 48765 | 33 | -1235 100 | 8 | 50000 | 34 | 667 100 | 6 | 49333 | 44 | -80667 233 | 4 | 130000 | 55 | 80000 100 | 11 | 50000 | 65 | -72345 101 | 7 | 122345 | 87 | 122345(11 rows)

In this example we see the LEAD window function in action. The expression LEAD(salary, 1, 0) tells LEAD() to evaluate the expression salary on the row that is positioned one row following the current row. If there is no such row (as is the case on the last row of the partition or relation), then the default value of 0 is used.

Window Function Example 10: LAG()

Compute the difference between an employee’s salary and that of the next employee in the sort order (which will be the next younger employee, or one whose age is the same):

SELECT dept, empnum, salary, age, salary - LAG(salary, 1, 0) OVER ( ORDER BY age ASC ) AS salary_diffFROM 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 FunctionsAny 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.)

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 SyntaxA 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:



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 RequirementsIt is required that the left end point precede or equal the right end point. The two end points may also not be both UNBOUNDED PRECEDING or both UNBOUNDED FOLLOWING.

Optionally, only one end point may be specified. If this is the case, then the CURRENT ROW is implicitly added as the other end point specification on either the left or right side of the window so as to produce as valid window frame.

Valid Examples

Examples of valid window frames are:

ROWS BETWEEN 5 PRECEDING and 2 PRECEDINGROWS BETWEEN 5 PRECEDING AND 5 PRECEDINGROWS BETWEEN 2 PRECEDING AND CURRENT ROWROWS BETWEEN CURRENT ROW AND CURRENT ROWROWS BETWEEN CURRENT ROW AND 2 FOLLOWINGROWS BETWEEN 2 FOLLOWING AND 2 FOLLOWINGROWS BETWEEN 2 FOLLOWING AND 5 FOLLOWINGROWS BETWEEN UNBOUNDED PRECEDING AND 2 PRECEDINGROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROWROWS BETWEEN UNBOUNDED PRECEDING AND 5 FOLLOWINGROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWINGROWS BETWEEN 2 PRECEDING AND UNBOUNDED FOLLOWINGROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWINGROWS BETWEEN 4 FOLLOWING AND UNBOUNDED FOLLOWINGROWS UNBOUNDED PRECEDINGROWS 5 PRECEDINGROWS CURRENT ROWROWS 5 FOLLOWINGROWS UNBOUNDED FOLLOWING

Invalid Examples

Examples of invalid window frames:



ROWS BETWEEN 2 PRECEDING AND 5 PRECEDINGROWS BETWEEN CURRENT ROW AND 2 PRECEDINGROWS BETWEEN 2 FOLLOWING AND CURRENT ROWROWS BETWEEN 5 FOLLOWING AND 2 FOLLOWINGROWS BETWEEN UNBOUNDED FOLLOWING AND CURRENT ROWROWS BETWEEN CURRENT ROW AND UNBOUNDED PRECEDINGROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED PRECEDINGROWS BETWEEN UNBOUNDED FOLLOWING AND UNBOUNDED FOLLOWING

ORDER BY Required

Note that if there is no ORDER BY clause present, the only allowed frame is ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING, that is, a frame encompassing the entire partition. All other frames have a moving endpoint which requires ordered input.

Window Frame Types: ROWS vs. RANGETwo 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)



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"



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 FrameSpecifying 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_salaryFROM employeesORDER BY department, age;

empnum | department | age | salary | running_sum_salary --------+------------+-----+--------+-------------------- 3 | 100 | 23 | 42000 | 42000 1 | 100 | 27 | 50010 | 92010



9 | 100 | 33 | 48765 | 140775 8 | 100 | 34 | 50000 | 190775 6 | 100 | 44 | 49333 | 240108 11 | 100 | 65 | 50000 | 290108 2 | 101 | 30 | 45000 | 45000 5 | 101 | 32 | 56000 | 488999 10 | 101 | 32 | 387999 | 488999 7 | 101 | 87 | 122345 | 611344 4 | 233 | 55 | 130000 | 130000(11 rows)

Note that the default window frame RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW is being used.

Window Function Example 15: ORDER BY SUM()

You can also use SQL aggregates inside the OVER clause, as shown in the ORDER BY clause, below:

SELECT dept, SUM(salary), RANK() OVER ( ORDER BY SUM(salary) ) AS dept_salary_rankFROM employeesGROUP 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_sumFROM employeesGROUP BY dept;



dept | sum(salary) | dept_salary_running_sum ------+--------------+------------------------- 233 | 130000 | 130000 100 | 290108 | 420108 101 | 611344 | 1031452(3 rows)

Consistent Sort Behavior of Input RowsTwo (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 employeesORDER 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).

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 BehaviorIn 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

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_departmentFROM 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 IssuesThere 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.

Window Function Known Issues Aster Data proprietary and confidential


ORDER BY without PARTITION BYOmitting 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 OnlyWindow functions may only appear in the SELECT clause.

No Support for WINDOW ClauseAster Database does not support the WINDOW clause for naming windows.

Size Limit of Sliding Window FramesSliding 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 FramesRANGE-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--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 DatatypesThe 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)

List of Supported Datatypes Aster Data proprietary and confidential


Compatibility

The following types (or spellings thereof) are specified by SQL:

bitbit varyingbooleancharcharacter varyingcharactervarchardatedouble precision

bytea 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


date calendar date (year, month, day)

Date/Time Types (page V-165)

double precision float, float8, float(n)

double precision floating-point number


ip4 IP address Network Address Types (page V-172)

ip4range range of IP addresses ip4range Datatype (page V-174)

integer int, int4 signed four-byte integer Numeric Types (page V-159)

interval time interval Intervals (page V-168)

numeric [(p, s)] decimal [(p,s)] exact numeric of selectable precision


real float4 single precision floating-point number


serial autoincrementing four-byte integer


smallint int2 signed two-byte integer Numeric Types (page V-159)

text variable-length character string


time [(p)] [without time zone]

time of day Date/Time Types (page V-165)

time [(p)] with time zone

timetz time of day, including time zone


timestamp [(p)] [without time zone]

date and time Date/Time Types (page V-165)

timestamp [(p)] with time zone

timestamptz date and time, including time zone


Name Aliases Description See page

Aster Data proprietary and confidential Numeric Types

December 14, 2011 Datatypes V--159

integerintervalnumericdecimalrealsmallinttime (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 TypesNumeric types consist of two-, four-, and eight-byte integers, four- and eight-byte floating-point numbers, and selectable-precision decimals.

Integer TypesThe 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

Name Aliases Storage Size

Description Range See page

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 9223372036854775807

Integer Types (page V-159)

numeric, numeric(p), numeric(p,s)

decimal Variable user-specified precision, exact

no limit Arbitrary Precision Numbers (page V-160)

real 4 bytes variable-precision, inexact

6 decimal digits precision Floating-Point Types (page V-161)

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)

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 NumbersThe 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.

Aster Data proprietary and confidential Numeric Types


Floating-Point TypesThe 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.

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.

Warning! Floating point types are inexact. If you require exact storage and calculations (such as for monetary amounts), use the numeric type instead.

Numeric Types Aster Data proprietary and confidential


Serial TypesThe 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

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

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

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

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.

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

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 RequirementsThe 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 TypesThere 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.

ExamplesExamples 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 | 2CREATE 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 truncationSELECT b, char_length(b) FROM test2; b | char_length-------+------------- ok | 2 good | 5 too l | 5

Aster Data proprietary and confidential Date/Time Types


Date/Time TypesAster Database supports the following date and time datatypes.

Table 4-4 Date and time datatypes supported in Aster Database

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 InputDate 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

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

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:

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.

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

Aster Data proprietary and confidential Date/Time Types


Table 4-6 Examples of time inputs:

Table 4-7 Examples of time zone inputs:

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'

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

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

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

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 OutputThe 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

Name Description Low Value High Value Resolution

interval Time interval -178000000 years 178000000 years 1 microsecond / 14 digits

Aster Data proprietary and confidential Boolean Types


Time ZonesAster 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 TypesBit strings are strings of 1's and 0's. They can be used to store or visualize bit masks. There are two SQL bit types: bit(n) and bit varying(n), where n is a positive integer.

Values of type bit must match the length n exactly; it is an error to attempt to store shorter or longer bit strings. Fields of type bit varying are of variable length up to the maximum length n; longer strings are rejected. Writing bit without a length is equivalent to bit(1), while bit varying without a length specification means unlimited length.

Note: If you explicitly cast a bit-string value to bit(n), it will be truncated or zero-padded on the right to be exactly n bits, without raising an error. Similarly, if you explicitly cast a bit-string value to bit varying(n), it will be truncated on the right if it is more than n bits.

Example using the bit string types:

CREATE FACT TABLE testbit ( a INT, b BIT(3), c BIT VARYING(5) ) DISTRIBUTE BY HASH(a);

beehive=> insert into testbit values (0, B'101', B'00');beehive=> insert into testbit values (1, B'10', B'101');ERROR: bit string length 2 does not match type bit(3)beehive=> insert into testbit values (1, B'10'::bit(3), B'101');

select * from testbit; a | b | c---+-----+----- 0 | 101 | 00 1 | 100 | 101

A bit string value requires 1 byte for each group of 8 bits, plus 5 or 8 bytes overhead depending on the length of the string.

Boolean TypesAster 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 ValuesValid literal values for the "true" state are:

TRUE't'

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).

ExamplesExamples 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 estSELECT * 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 TypesThe bytea datatype allows storage of binary strings.

Table 4-9 Binary Datatypes

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

Name Storage Size Description

bytea 1 or 4 bytes plus the actual binary string variable-length binary string

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 ValuesWhen 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

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 RepresentationsBytea 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.

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

Network Address Types Aster Data proprietary and confidential


Table 4-11 bytea Output Escaped Octets

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.

CompatibilityThe 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 DatabaseAster 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 examplesCREATE TABLE ipranges (range ip4range primary key, description text not null);CREATE INDEX ipranges_range_idx ON ipranges USING gist (range);INSERT INTO ipranges VALUES ('10.0.0.0/8','rfc1918 block 1');INSERT INTO ipranges VALUES ('172.16.0.0/12','rfc1918 block 2');INSERT INTO ipranges VALUES ('192.168.0.0/16','rfc1918 block 3');INSERT INTO ipranges VALUES ('0.0.0.0/1','classical class A space');INSERT INTO ipranges VALUES ('10.0.1.10-10.0.1.20','my internal network');INSERT INTO ipranges VALUES ('127.0.0.1','localhost');

CREATE TABLE access_log (id serial primary key, ip ip4 not null);CREATE INDEX access_log_ip_idx ON access_log (ip);INSERT INTO access_log(ip) VALUES ('10.0.1.15');INSERT INTO access_log(ip) VALUES ('24.1.2.3');INSERT INTO access_log(ip) VALUES ('192.168.10.20');

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; ~

Aster Data proprietary and confidential Network Address Types


INSERT INTO access_log(ip) VALUES ('127.0.0.1');

Find all accesses from 10.0.0.0/8

SELECT * FROM access_log WHERE ip BETWEEN '10.0.0.0' AND '10.255.255.255';

Find all applicable descriptions for all entry in the access log. This example returns multiple rows for each entry if there are overlapping ranges:

SELECT id,ip,range,description FROM access_log, ipranges WHERE ip <<= range;

Find only the most specific description for all IPs in the access log

SELECT DISTINCT ON (ip) ip,range,description FROM access_log, ipranges WHERE ip <<= range ORDER BY ip,ip4range_size(range);

ip4 Datatypeip4 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:

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.

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)



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.

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 DatatypeAn 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.

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



Typecasting for ip4range

ip4range supports the following type conversions:

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:

Source type Dest type Form

ip4 ip4range ip4range(ip4) or ip4::ip4range (implicit)

ip4range text ip4range::text (explicit)

text ip4range ip4range(text) or text::ip4range (explicit)


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



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 ip4rangeA 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)

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.




LIMIT 1

When looking up multiple IPs, one can do queries of the following form:

SELECT DISTINCT ON (ips.ip) ips.ip, ranges.range FROM ips, ranges WHERE ranges.range >>= ips.ip ORDER BY ips.ip, ip4range_size(ranges.range)

Examples Using ip4 and ip4rangeBelow, 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 rangesBEGIN;CREATE TABLE ip1(a ip4, b ip4range, c int) distribute by hash(a);CREATE TABLE ip2(a ip4, b ip4range, c int) distribute by hash(b);SELECT * FROM ip1 , ip2 WHERE ip1.a <<= ip2.b ORDER BY ip1.c;SELECT * FROM ip1 , ip2 WHERE ip1.a = ip2.a ORDER BY ip1.c;SELECT * FROM ip1 , ip2 WHERE ip1.b >>= ip2.a ORDER BY ip1.c;SELECT * FROM ip1 , ip2 WHERE ip1.b = ip2.b ORDER BY ip1.c;ABORT;

Examples: IP address-related functions and operatorsBEGIN;

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;

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 TypeThe 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.

Aster Data proprietary and confidential Type Casts


Type CastsAster 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.

Type Casts Aster Data proprietary and confidential



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 InterpretationThe date/time type inputs are all decoded using the following procedure:

1. Break the input string into tokens and categorize each token as a string, time, time zone, or number.

• If the numeric token contains a colon (:), this is a time string. Include all subsequent digits and colons.

• If the numeric token contains a dash (-), slash (/), or two or more dots (.), this is a date string which may have a text month.

• If the token is numeric only, then it is either a single field or an ISO 8601 concatenated date (e.g., 19990113 for January 13, 1999) or time (e.g., 141516 for 14:15:16).

• If the token starts with a plus (+) or minus (-), then it is either a time zone or a special field.

2. If the token is a text string, match up with possible strings.

• Do a binary-search table lookup for the token as either a special string (e.g., today), day (e.g., Thursday), month (e.g., January), or noise word (e.g., at, on). Set field values and bit mask for fields. For example, set year, month, day for today, and additionally hour, minute, second for now.

• 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.

3. When the token is a number or number field:

• If there are eight or six digits, and if no other date fields have been previously read, then interpret as a "concatenated date" (e.g., 19990118 or 990118). The interpretation is YYYYMMDD or YYMMDD.

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 NamesThe table below shows the tokens that are recognized as names of months.

Table 5-1 Month Names

Day-of-Week NamesThe table shows the tokens that are recognized as names of days of the week.

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

Aster Data proprietary and confidential Date/Time Keywords

December 14, 2011 Date and Time V--183

Table 5-2 Day-of-week names

Date Time Field ModifiersThe table below shows the tokens that serve various modifier purposes.

Table 5-3 Date Time Field Modifiers

The keyword ABSTIME is ignored for historical reasons.

Day Abbreviations

Sunday Sun

Monday Mon

Tuesday Tue, Tues

Wednesday Wed, Weds

Thursday Thu, Thur, Thurs

Friday Fri

Saturday Sat

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

Date/Time Keywords Aster Data proprietary and confidential



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)

Introduction to Data Dictionary Views Aster Data proprietary and confidential


Introduction to Data Dictionary ViewsThe 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.

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 ViewsThe 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:

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.

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

Aster Data proprietary and confidential Database-Related Data Dictionary Views

December 14, 2011 Data Dictionary Views V--187

Role-Related Data Dictionary ViewsThe 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:

Group Membership Data Dictionary ViewsThe 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:

Database-Related Data Dictionary ViewsThe 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


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


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


dbid int Unique database Id

dbname varchar Database name

dbowner varchar Database owner name

Schema-Related Data Dictionary Views Aster Data proprietary and confidential


Schema-Related Data Dictionary ViewsAster 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

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

dbencoding varchar Character encoding for this database

permissions varchar Access privileges for this database


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

Aster Data proprietary and confidential SQL-MapReduce and Installed File-Related Data Dictionary Views


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:

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 ViewsThe 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

Column-Related Data Dictionary ViewsThe 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


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


Aster Data proprietary and confidential Constraint-Related Data Dictionary Views


Index-Related Data Dictionary ViewsThe 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

Constraint-Related Data Dictionary ViewsThe 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

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


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


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

Logical Partition-Related Data Dictionary Views Aster Data proprietary and confidential


Logical Partition-Related Data Dictionary ViewsThe 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

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

collist varchar List of column positions for columns that form this constraint

condef varchar Constraint definition


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


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

Aster Data proprietary and confidential Cluster State Data Dictionary Views


Inheritance-Related Data Dictionary ViewsThe 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

Types Data Dictionary ViewThe data dictionary view nc_types contains information about all the datatypes supported in Aster Database.

Figure 6-10 Schema of nc_types

Cluster State Data Dictionary ViewsThis 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_stateThe 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


parentid int Table id of parent table

childid int Table id of child table


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


macaddr varchar Mac address of the node

ipaddr varchar Assigned ip address of node

type varchar Type of the node: { 'Worker' , 'Loader' , 'Backup' }

Activity Data Dictionary Views Aster Data proprietary and confidential


Storage State: nc_cluster_storageThe data dictionary view nc_cluster_storage contains information about the storage utilization of the cluster.

Figure 6-12 Schema of nc_cluster_storage

Activity Data Dictionary ViewsThis 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_sessionsThe data dictionary view nc_all_sessions contains information about current and past sessions to Aster Database.

Figure 6-13 Schema of nc_all_sessions

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


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


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

Aster Data proprietary and confidential Activity Data Dictionary Views


Transaction Statistics: nc_all_transactionsThe 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

Transaction Phases: nc_all_transaction_phasesThe 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

Statement Statistics: nc_all_statementsThe 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


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


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


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

http://www.asterdata.com/support/index.php

Activity Data Dictionary Views Aster Data proprietary and confidential


Load Error Logging TablesThe 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

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 TABLEbeehive=> 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=>

iscancelable Boolean true if statement is cancelable

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.

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

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 TablesThe 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.

key tupletimestamp labeltarget- table

dmltype errmessage

sqlerrcode rawdata linenumber columnname

1 2009-05-20 15:20:05.281138-07

0 clicks C invalid input syntax for integer: "a"

22P02 2\x09a\x09May 20 11:19:30 2009

2 userid

1 2009-05-20 15:20:05.281389-07

0 clicks C extra data after last expected column

22P04 4\x0923333\x09May 20 11:18:56 2009\x09\N

5

0 2009-05-20 15:20:05.116448-07

0 clicks C invalid input syntax for integer: "May 20 11:18:56 2009"

22P02 1\x09May 20 11:18:56 2009

3 ts

0 2009-05-20 15:20:05.116737-07

0 clicks C extra data after last expected column

22P04 3\x093\x092345\x09May 20 11:10:02 2009

4

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

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 ViewsYou 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.

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.


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 ConventionsTokens 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

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 ( [ ] ).

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.

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.

Aster Data proprietary and confidential Value Expressions

December 14, 2011 SQL Vocabulary V--201

• 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 SQLA 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 ExpressionsValue 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.

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 ReferencesA 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.


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


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

Table 9-3 Error Code Class 0A - Feature Not Supported

Table 9-4 Error Code Class 21 - Cardinality Violation

Table 9-5 Error Code Class 22 - Data Exception

Error Code Error Description

0 SUCCESSFUL COMPLETION


0A000 FEATURE NOT SUPPORTED


21000 CARDINALITY VIOLATION


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



Table 9-6 Error Code Class 23 - Integrity Constraint Violation

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


23000 INTEGRITY CONSTRAINT VIOLATION

23502 NOT NULL VIOLATION

23514 CHECK VIOLATION

23518 PARTITION KEY ERROR



December 14, 2011 Error Codes V--207

Table 9-7 Error Code Class 25 - Invalid Transaction State

Table 9-8 Error Code Class 26 - Invalid SQL Statement Name

Table 9-9 Error Code Class 28 - Invalid Authorization Specification

Table 9-10 Error Code Class 2B - Dependent Privilege Descriptors Still Exist

Table 9-11 Error Code Class 2D - Invalid Transaction Termination

Table 9-12 Error Code Class 34 - Invalid Cursor Name

Table 9-13 Error Code Class 40 - Transaction Rollback

Table 9-14 Error Code Class 42 - Syntax Error or Access Rule Violation


25000 INVALID TRANSACTION STATE

25P02 IN FAILED SQL TRANSACTION


26000 INVALID SQL STATEMENT NAME


28000 INVALID AUTHORIZATION SPECIFICATION


2BP01 DEPENDENT OBJECTS STILL EXIST


2D000 INVALID TRANSACTION TERMINATION


34000 INVALID CURSOR NAME


40000 TRANSACTION ROLLBACK

40002 TRANSACTION INTEGRITY CONSTRAINT VIOLATION

40001 SERIALIZATION FAILURE

40003 STATEMENT COMPLETION UNKNOWN

40P01 DEADLOCK DETECTED


42000 SYNTAX ERROR OR ACCESS RULE VIOLATION

42601 SYNTAX ERROR

42501 INSUFFICIENT PRIVILEGE

42846 CANNOT COERCE



Table 9-15 Error Code Class 53 - Insufficient Resources

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


53000 INSUFFICIENT RESOURCES

53100 DISK FULL

53200 OUT OF MEMORY

53300 TOO MANY CONNECTIONS



December 14, 2011 Error Codes V--209

Table 9-16 Error Code Class 54 - Program Limit Exceeded

Table 9-17 Error Code Class 55 - Object Not In Prerequisite State

Table 9-18 Error Code Class XX - Internal Error


54000 PROGRAM LIMIT EXCEEDED

54001 STATEMENT TOO COMPLEX

54011 TOO MANY COLUMNS

54023 TOO MANY ARGUMENTS


55000 OBJECT NOT IN PREREQUISITE STATE

55006 OBJECT IN USE

55P03 LOCK NOT AVAILABLE


XX000 INTERNAL ERROR

December 14, 2011 Index V--211

IndexAABORT, V-6about this book, V-viiABS() function, V-98access permissions, V-188

list of SQL-MapReduce privileges, V-188managing using schemas, V-188

accountsystem table for, V-186

ACOS() function, V-99activity statistics tables, V-194aggregate, V-137aggregate functions, V-130

aggregate window functions, V-146aggregates of aggregates, V-152statistics functions, V-130used inside a window function definition, V-152

alias, V-77column name alias, V-77required for subselects, V-77table name alias, V-77

ALL, V-135ALTER INDEX, V-7ALTER ROLE, V-7ALTER SCHEMA, V-8ALTER TABLE, V-9

set DEFAULT value for column, V-10ALTER USER, V-15ANALYZE, V-17

command reference, V-17AND/OR/NOT operators, V-95AND, bitwise, V-103ANY, V-134ANY/SOME, V-134ARE (type of regex), V-112ARE, RE, BRE, and ERE, switching between, V-117AS, V-77

column alias, V-77table alias, V-77

ASC, V-80ASCII, convert to, V-103ascii() function, V-101ASIN() function, V-99Aster datatypes, V-157Aster Data, about, V-viAster support portal, V-viAsterix, V-77

ATAN2() function, V-99ATAN() function, V-99autopartitioning

COPY and, V-25AVG() function, V-130

as window function, V-149cumulative running average, V-150moving average, V-150

Bback reference in regex, V-115backslash, V-115

in regex, V-115in regular expression, V-113

BEGIN, V-18START TRANSACTION, V-87

BETWEEN, V-96BETWEEN operator, V-96BETWEEN SYMMETRIC, V-96bigint datatype, V-159bigint, serialized, V-162bigserial, V-162bigserial column, V-162binary data, encoding, V-101binary string datatype, V-170bit string operators, V-103bit string type, V-169bitwise operators, V-97

for bit strings, V-103bit_length function, V-100bit_length operator for bit strings, character strings, V-103Boolean operators, V-95Boolean type, V-169

checking a Boolean value, V-97bracket expression, V-114brackets for quoting, V-200BRE, V-120BRE (type of regex), V-112btrim() function, V-101bytea datatype, V-170

Ccapitalize words, V-101CASCADE, V-53

ALTER TABLE and, V-9GRANT table privileges and, V-61


CASE, V-131case-sensitivity in identifiers, V-200CAST, V-179cast datatype to another type, V-179CBRT() function, V-98CEILING() function, V-98CEIL() function, V-98century in timestamp, V-125char or character type, V-163

functions and, V-100character set encoding

UTF-8 is the default, V-29character support, V-29character value, manipulating, V-100char_length function, V-100CHECK

add check constraint, V-14defined, V-38

child tablechange inheritance with ALTER TABLE, V-12create with CREATE TABLE, V-37inheriting parent table privileges, V-61

chr() function, V-101cleanup, V-92clock_timestamp() function, V-124CLOSE, V-20CLUSTER, V-21

partitioning and, V-21COALESCE, V-132column, V-190

add or remove, V-10default value for, V-10, V-35list of columns in database, V-190

column alias, V-77column naming conventions, V-199column sort order, V-77command, V-3

list of, V-3SET, V-83

command reference, V-3commands, V-3COMMIT, V-22comparison operators, V-96compatibility of nCluster with PostgreSQL, V-3compress data

ALTER TABLE and, V-12CREATE TABLE and, V-36

compressionCREATE TABLE and, V-36

concatenatebitwise operator, V-103

concatenation operator, V-100CONCAT() equivalent, V-100conditional SQL expressions, V-131configuration

performance settings, V-83SET value, V-83

configuration flag, V-154enableDeprecatedWindowFunctionAliasBehaviour, V-

154CONSTRAINT, V-40

add or remove, V-11ALTER TABLE’s ADD command, V-11list of, V-191

conventions, V-vconvert string, V-103COPY, V-23

autopartitioning, V-25error-capture tables for, V-196

copyright, V-viiCOS() function, V-99COT() function, V-99count characters in string, V-101count function, V-130CREATE DATABASE, V-28CREATE INDEX, V-29CREATE ROLE, V-31CREATE SCHEMA, V-32CREATE TABLE, V-34

revoke user’s right to create tables, V-72CREATE TABLE AS SELECT, V-42CREATE USER, V-43CREATE VIEW, V-45CTAS, V-42cumulative running average, V-150CURRENT ROW in window frame, V-148cursor, V-46

creating, V-46DECLARE, V-46FETCH, V-57MOVE, V-69updatable, V-48

customer support, V-vi

Ddata

loading, statistics on, V-197data dictionary, V-185database

CREATE DATABASE, V-28default character encoding, V-29deleting, V-51DROP DATABASE, V-51

datatype, V-157arbitrary precision numbers, V-160bigserial, V-162binary type, bytea, V-170bit and bit varying, operations on, V-103bit string, V-169Boolean, V-169bytea, V-170casting to another type, V-179character datatypes, V-163date and time functions, V-123date and time types, V-165date and time, reformatting, V-121floating point, V-161formatting functions for, V-121ip4, V-172ip4range, V-174list of, V-157


listing from SQL prompt, V-193network address types, V-172numeric, V-159serial, V-162text datatypes, V-163time, V-165time functions, V-123uuid, V-178

datatype formatting functions, V-121date, V-165

extract subset, V-124functions, V-123return current date, V-129templates for formatting, V-121

date datatypefunctions for, V-123

date datatypes, V-165date of publication, V-viidate values, inserting, V-165date values, retrieving, V-168date_part function, V-127

synopsis, V-124date_trunc function, V-128

synopsis, V-124day in timestamp, V-125day of week in timestamp, V-125day of year in timestamp, V-125daylight savings rules, V-169decade in timestamp, V-125DECLARE, V-46DECLARE CURSOR, V-46decode() function, V-101DEFAULT, V-35default character encoding for databases, V-29DEFAULT values for a column, V-10DEGREES() function, V-98DELETE, V-49delete rows, V-49delimited identifier, V-200delimited identifier (object name), V-200delimiters, V-200DENSE_RANK() function, V-139

an example, V-141another example, V-142compared with RANK(), V-141

DESC, V-80DISTINCT, V-81

IS DISTINCT FROM, V-97DISTINCT Clause, V-81DISTINCT FROM, V-96distribution key

declaring in CREATE TABLE, V-36documentation conventions, V-vdocumentation version and updates, V-viidocumentation, about, V-vdouble precision datatype, V-161double tilde, V-109double-quote character, V-200dow in timestamp, V-125doy in timestamp, V-125dp datatype, V-161DROP DATABASE, V-51

DROP INDEX, V-51DROP ROLE, V-52DROP SCHEMA, V-53DROP TABLE, V-53DROP USER, V-54

Eedition, V-viiempty a table of rows, V-88encode() function, V-101encoding

UTF-8 is the default, V-29END, V-56epoch in timestamp, V-125equality, checking, V-97ERE (type of regex), V-112error codes, V-205

list of error codes in nCluster, V-205error logging

statistics about loading attempts, V-197tables to capture load errors, V-196tables to capture load errors, custom, V-197

escape characterregex escape characters, V-115

escape characters in regex, V-115EXCEPT Clause, V-80exclamation point in regex, V-110EXISTS, V-133EXPLAIN, V-57expression, V-133

ALL, V-135ANY/SOME, V-134EXISTS, V-133IN, V-133in index definition, V-30NOT IN, V-134SOME, V-134

expression-based index, V-30EXP() function, V-98extract function, V-124

date_part, V-127synopsis, V-124

extract subset of date/time value, V-124

FFALSE, V-97FETCH, V-57float and float(p) datatypes, V-161floating point datatypes, V-161FLOOR() function, V-98frame, V-146

default, V-151limitations of, V-156ROWS-type vs. RANGE-type, V-149usage note re: UNBOUNDED L/R sides, V-153

free spaceVACUUM command reference, V-92

FROM clause, V-77AS to rename table, V-77omission OK, V-82


FULL JOIN, V-77FULL OUTER JOIN, V-77functional index, V-30functions, V-95

AVG, V-146COUNT, V-146date and time, V-123DENSE_RANK, V-139formatting datatypes, V-121LAG, V-145LEAD, V-145mathematical, V-97MAX, V-146MIN, V-146ncluster_storagestat, V-93RANK, V-139ROW_NUMBER, V-139STDDEV, V-131STDDEV_POP, V-131STDDEV_SAMP, V-131string, V-100SUM, V-146VARIANCE, V-131VAR_POP, V-131VAR_SAMP, V-131window functions, V-137

Ggarbage collection, V-92get latest documentation, V-viiGiST index, V-176GRANT, V-61greater than, V-96GREATEST SQL commands

GREATEST, V-133greedy regular expression, V-118group

vs. role, V-31GROUP BY

namespace, V-82no aliases allowed in, V-77window function with, V-152

GROUP BY Clause, V-78

Hhash function, V-102HAVING Clause, V-79help, V-vihexadecimal, convert to, V-103history of queries, V-195hour in timestamp, V-126

Iidentifier, quoted or delimited, V-200IIS, V-64ILIKE, V-109IN, V-133index, V-29

CREATE INDEX, V-29expression-based index, V-30list of indexes, V-191null values and indexing, V-30system tables for, V-191type B-tree, V-29type GiST, V-176

indexingCREATE INDEX, V-29REINDEX, V-70

inequality, checking for, V-97infinity as floating-point type, V-161INHERIT

ALTER TABLE option, V-12change inheritance with ALTER TABLE, V-12

inheritancetable privileges and, V-61

INHERITS, V-37CREATE TABLE option, V-37limitations on inheritance, V-37what is and what is not inherited?, V-37

initcap() function, V-101IN/NOT IN, V-133input format, time and date values, V-165INSERT, V-64

example using VALUES to insert multiple rows, V-65VALUES clause, V-64

INSERT INTO ... SELECT ... statement, V-64installed files

system tables for, V-188integer datatype, V-159integer, serialized, V-162INTERSECT Clause, V-79interval datatype, V-165

in expressions, V-123interval functions, V-124int, int2, int4, and int8 datatypes, V-160IP address datatype, V-172IP address range datatype, V-174ip4 datatype, V-172ip4r datatype, V-174ip4range

index of, V-176ip4range datatype, V-174IPv4 datatype, V-172IS DISTINCT FROM, V-97IS NOT, V-96IS NULL

indexes and, V-30IS NULL, V-96isfinite function, V-124IS, our definition of, V-96

Jjoin

type, V-77join type, V-77justify_days function, V-124justify_interval function, V-124


Kkeywords, V-3keyword, rules for, V-200known issues

window functions, V-155

LLAG() function, V-145

example, V-146language support, V-29leading spaces, trimming, V-102LEAD() function, V-145

example, V-145LEAST, V-133LEFT JOIN, V-77LEFT OUTER JOIN, V-77length operator for bit strings, character strings, V-103length() function, V-101less than, V-96LIKE, V-108LIMIT, V-81LIMIT Clause, V-81LN() function, V-99load

statistics about, V-197loading

handling nulls in COPY loads, V-24log

query history, V-195Logical, V-192logical partitioning

GRANT table privileges and, V-61Logical Partition-Related System Tables, V-192LOG() function, V-99lowercase, to, V-100lower() function, V-100lpad() function, V-101ltrim() function, V-102

Mmaintenance, V-92mathematical functions, V-98mathematical operators, V-97max function, V-130md5 hash, V-102md5() function, V-102memory settings, V-85MERGE, V-66metadata system tables, V-186microseconds in timestamp, V-126millenium in timestamp, V-126milliseconds in timestamp, V-126min function, V-130minute in timestamp, V-126MOD() function, V-99month in timestamp, V-126MOVE, V-69moving average, V-150

Nnaming, V-199naming conventions, V-199NaN, V-161NATURAL join, V-78nCluster-PostgreSQL command compatibility, V-3ncluster_loader

error-capture tables for, V-196ncluster_storagestat, V-93nc_ tables, V-194nc_all_ tables, V-186nc_all_columns, V-190nc_all_constraints, V-191nc_all_databases, V-187nc_all_group_members, V-187nc_all_indexes, V-191nc_all_inherit, V-193nc_all_roles, V-187nc_all_schemas, V-188nc_all_sessions, V-194nc_all_statements, V-195nc_all_tables, V-190nc_all_transactions, V-195nc_all_transaction_phases, V-195nc_all_users, V-186nc_cluster_storage, V-194nc_group_members, V-187nc_physical_node_state, V-193nc_roles, V-187nc_temp tables, V-198nc_types, V-193nc_users, V-186nc_user_ tables, V-186nc_user_columns, V-190nc_user_constraints, V-191, V-192nc_user_databases, V-187nc_user_indexes, V-191nc_user_inherit, V-193nc_user_owned_ tables, V-186nc_user_owned_columns, V-190nc_user_owned_constraints, V-191nc_user_owned_databases, V-187nc_user_owned_indexes, V-191nc_user_owned_inherit, V-193nc_user_owned_schemas, V-188nc_user_owned_tables, V-190nc_user_schemas, V-188negative infinity as floating-point type, V-161network address

index for, V-176network address datatypes, V-172node

node state in system tables, V-193serialize values across all nodes, V-162

not a number, V-161NOT BETWEEN, V-96not equal to, V-97NOT IN, V-134NOT UNKNOWN, V-97NOT/AND/OR operators, V-95NOT, bitwise, V-103


now(), V-129now() function, V-124nPath

examples, V-104null

add NOT NULL constraint, V-9handling nulls in COPY loads, V-24indexes and nulls, V-30null value, checking for, in SQL, V-96

NULLIF, V-133NULLS FIRST, V-80

window functions and, V-137NULLS LAST, V-80

window functions and, V-137numbering window functions, V-139

Oobject, V-61

GRANT on database objects, V-61object naming conventions, V-199octet_length operator for bit strings, character

strings, V-103octet_length() function, V-100OFFSET, V-81ON

ON, for join conditions, V-78ON DUPLICATE KEY UPDATE: Use MERGE

instead, V-66ONLY, V-77

in ALTER TABLE, V-13in DELETE, V-49in SELECT, V-77in UPDATE, V-89

operators, V-95comparison, V-96date and time, V-123logical, V-95mathematical, V-97string, V-100

OR/AND/NOT operators, V-95ORDER BY, V-80

consistent sorting of window function input rows, V-153

in OVER clause, V-146namespace, V-82PARTITION BY should always be used, V-156window frames and, V-149window functions and, V-137

order of input rows, V-146order of output rows, V-80

window functions and, V-138OR, bitwise, V-103output format, time and date values, V-168output row ordering, V-80

window functions and, V-138OVER, V-137

in window function, V-137not used to sort output, V-138sort order of input rows, V-146

overlay() function, V-100

Ppadding out text strings, V-101parameter, V-83

performance settings, V-83SET value, V-83settings for SQL, V-83

parent table, V-37change inheritance with ALTER TABLE, V-12declare parent of new child table, V-37passing along table privileges to children, V-61

PARTITION BY, V-137always include when sorting, V-156in window function, V-137performance considerations, V-154

partition keycannot add to or drop from existing table, V-13CLUSTER and, V-21CREATE TABLE AS with partition key, V-42UPDATE not allowed, V-90

partition key: See distribution keypartitioning

automatic partition during COPY, V-25CLUSTER and, V-21repartitioning perfomance for window

functions, V-154serialized IDs and, V-162

pattern matching, V-108bracket expression, V-114list of approaches to pattern matching, V-108regex matching rules, V-118search and replace, V-111with LIKE, V-108with POSIX regular expression, V-110with SIMILAR TO, V-109with SUBSTRING, V-111

pattern matching functions, V-108performance tuning, V-83

avoiding scanning for IS NULL, V-30server-side cursors, V-46SET command, V-83

permissionsapplying to users, V-31GRANT, V-61list of SQL-MapReduce privileges, V-188REVOKE, V-71schemas for setting user rights, V-188

pipe operator for concatenation, V-100PI() function, V-99planner settings, V-83portal, V-viposition operator for bit strings, character strings, V-103position() function, V-100POSIX regular expression, V-110PostgreSQL-nCluster command compatibility, V-3POWER() function, V-99primary key, V-38

cannot add to or drop from existing table, V-13declaring in CREATE TABLE, V-38serial columns and, V-163


QQTR in timestamp, V-127quarter in timestamp, V-127query

anayzing, V-57list of statements run, V-195

query planner settings, V-83quote characters, V-200quoted identifier, V-200quoted identifier (object name), V-200quote_ident() function, V-102quote_literal() function, V-102quoting conventions, V-200

RRADIANS() function, V-99RANGE, V-147

RANGE clause syntax, V-148range of IP addresses, V-174RANGE UNBOUNDED FOLLOWING, V-148RANGE UNBOUNDED PRECEDING, V-148RANGE UNBOUNDED PRECEDING example, V-150RANGE-based window frames, V-149

example, V-150RANK() function, V-139

compared with DENSE_RANK(), V-141example, V-140, V-142, V-143

RE (type of regex), V-112real datatype, V-161regex, V-110

bracket expression, V-114BRE, V-120detailed syntax, V-112matching rules, V-118regex types, switching between, V-117

regexp_replace, V-111regexp_replace() function, V-102regexp_split_to_table, V-111regexp_split_to_table() function, V-102regular expression, V-110

atom syntax, V-113bracket expression, V-114BRE, V-120constraint syntax, V-114detailed syntax, V-112escape characters, V-115greedy or not, V-118matching rules, V-118quantifier syntax, V-113RE vs. ERE vs. ARE vs. BRE, V-112regex types, switching between, V-117

regular expressionsmetasyntax for, V-117

REINDEX, V-70release notes, V-154

window functions, V-155rename queried column with AS, V-77rename queried table with AS, V-77repartitioning, V-154repeat() function, V-102

replace characters in a string, V-103REPLACE INTO: Use MERGE instead, V-66replace() function, V-102reserved words, V-3REVOKE, V-71revoke user’s right to create tables, V-72RIGHT JOIN, V-77RIGHT OUTER JOIN, V-77rights, applying to users, V-31role, V-187

CREATE ROLE, V-31deleting, V-52GRANT on roles, V-63REVOKE, V-71system table for, V-187vs. group, V-31

ROLLBACK, V-74ROUND() function, V-99ROWS, V-147

ROWS clause syntax, V-147ROWS syntax examples, V-148

ROWS n FOLLOWING, V-148ROWS n PRECEDING, V-148ROWS UNBOUNDED FOLLOWING, V-148ROWS UNBOUNDED PRECEDING, V-148ROWS-based window frames, V-149

example, V-150ROW_NUMBER() function, V-139

example, V-140, V-142row, deleting, V-49rpad() function, V-102rtrim() function, V-102running average, V-149running sum, V-151runtime settings

SET value, V-83

Sscalar functions, V-95scanning, avoiding for IS NULL queries, V-30schema, V-32

ALTER SCHEMA, V-8CREATE SCHEMA, V-32DROP SCHEMA, V-53list of schemas in database, V-188

schema search pathsetting with SET, V-84

scope of user rights, V-188search and replace, V-111search_path

SET and, V-84second in timestamp, V-127security

SQL-MapReduce system tables for, V-188SELECT, V-75

AS keyword for column alias, V-77AS keyword for table alias, V-77command reference, V-75creating a table with SELECT output, V-42DISTINCT Clause, V-81examples, V-82


EXCEPT Clause, V-80FROM clause, V-77GROUP BY Clause, V-78HAVING Clause, V-79INTERSECT Clause, V-79LIMIT Clause, V-81ORDER BY clause, V-80processing order, V-76WHERE Clause, V-78

serial, V-162serial column, V-162

primary key declaration not recommended, V-163serial global column, V-162serial local, V-162serial4, V-162serial8, V-162serialize values across nodes, V-162server-side cursors, V-46

in SQL, V-46session statistics, V-194sessions statistics, V-194SET, V-83

command reference, V-83settings

performance tuning, V-83SET value, V-83

shift left, bitwise operator, V-103shift right, bitwise operator, V-103SHOW, V-85

command reference, V-85SIGN() function, V-99SIMILAR TO, V-109single quotes

for time and date values, V-165SIN() function, V-100smallint datatype, V-159SOME, V-134sorting input rows, V-146

consistency of, V-153OVER clause, V-146

sorting output rows, V-80window functions and, V-138

spacestorage state, V-194

spaces in table and column names, V-200spaces, trimming leading spaces, V-102split_part() function, V-102SQL, V-3SQL aggregate, V-137SQL command compatibility, V-3SQL commands, V-3

ALL, V-135ALTER SCHEMA, V-8ANY, V-134CASE, V-131CLOSE, V-20COALESCE, V-132CREATE SCHEMA, V-32DROP SCHEMA, V-53EXISTS, V-133INSERT, V-64

LEAST, V-133LIKE, V-108MERGE, V-66NOT IN, V-134NULLIF, V-133ORDER BY in a window function, V-137OVER, V-137PARTITION BY in a window function, V-137SIMILAR TO, V-109SOME, V-134SUBSTRING, V-110

SQL functionsregexp_replace, V-111regexp_split_to_table, V-111SUBSTRING, V-111

SQL-MapReducerepartitioning perfomance, V-154security system tables, V-188views and, V-46

SQRT() function, V-99square brackets for quoting, V-200START TRANSACTION, V-87state tables, V-193statements, list of statements run, V-195statistics, V-194

data loading stats, V-197statistics functions, V-130statistics tables, V-194stats db, V-194statsdb, V-194STDDEV function, V-131STDDEV_POP function, V-131STDDEV_SAMP function, V-131storage state, V-194string, V-100

convert to ASCII, V-103count characters in, V-101padding out with filler text, V-101replace characters in, V-103split into rows, V-111splitting, V-102trim spaces or characters, V-102

string functions, V-100string operators, V-103string value, manipulating, V-100strpos() function, V-103subselect, V-77SUBSTRING, V-110, V-111

example, V-119substring, V-102

extract, V-103replace, V-102

substring operator for bit strings, character strings, V-103substring, finding, V-100substring() function, V-100substr() function, V-103sum function, V-130SUM() function

example, running sum, V-151support, V-visymbols, V-96


mathematical, V-97symmetric between, V-96system state, V-193system statistics, V-194system tables, V-185

nc_all_child_partitions, V-192nc_all_columns, V-190nc_all_constraints, V-191nc_all_databases, V-187nc_all_group_members, V-187nc_all_indexes, V-191nc_all_inherit, V-193nc_all_roles, V-187nc_all_schemas, V-188nc_all_sessions, V-194nc_all_statements, V-195nc_all_tables, V-190nc_all_transactions, V-195nc_all_transaction_phases, V-195nc_all_users, V-186nc_cluster_storage, V-194nc_group_members, V-187nc_physical_node_state, V-193nc_roles, V-187nc_types, V-193nc_users, V-186nc_user_child_partitions, V-192nc_user_columns, V-190nc_user_constraints, V-191, V-192nc_user_databases, V-187nc_user_indexes, V-191nc_user_inherit, V-193nc_user_owned_child_partitions, V-192nc_user_owned_columns, V-190nc_user_owned_constraints, V-191nc_user_owned_databases, V-187nc_user_owned_indexes, V-191nc_user_owned_inherit, V-193nc_user_owned_schemas, V-188nc_user_owned_tables, V-190nc_user_schemas, V-188SQL-MapReduce-related, V-188statistics tables, V-194

Ttable

CREATE TABLE, V-34list of tables in database, V-190removing, V-53revoke user’s right to create tables, V-72

table alias, V-77table naming conventions, V-199

case sensitivity, V-200TAN() function, V-100technical support, V-vitelephone number, V-viTEMPORARY privilege not supported, V-63temporary system tables, V-198text datatype, V-163text substitution, V-111tilde operator, V-109, V-110

time, V-165clock_timestamp() function, V-124daylight savings rules, V-169functions for, V-123now() function, V-124return current time, V-129templates for formatting, V-121

time datatypes, V-165functions for, V-123

time values, inserting, V-165time values, retrieving, V-168time zone, V-165

in data input, V-165timestamp, V-124, V-129

extract subset, V-124vs. now() function, V-124

timestamp input format, V-167timezone in timestamp, V-127to_ functions, V-121to_ascii() function, V-103to_char function, V-121

examples, V-123to_date function, V-121to_hex() function, V-103to_number function, V-121to_timestamp function, V-121transaction

COMMIT, V-22END, V-56phases, V-195ROLLBACK, V-74start time of transaction, V-124starting, V-87statistics, V-195

translate() function, V-103TRIGGER privilege not supported, V-63trigonometric functions, V-99trim spaces or characters from strings, V-102trim() function, V-101troubleshooting

cannot update or drop table, V-46TRUE, V-97true/false datatype, V-169TRUNCATE, V-88truncate date, V-128

synopsis, V-124TRUNC() function, V-99tuning, V-83

SET command, V-83typeface conventions, V-vtypes, V-157

listing from SQL prompt, V-193

Uunicode, V-29UNION Clause, V-79unique ID across cluster, V-162universally unique identifier, V-178UNKNOWN, V-97updatable cursor, V-48UPDATE, V-89


cannot update a partition key value, V-90command reference, V-89

updated documentation, V-viiuppercase, to, V-101upper() function, V-101URL, V-vi

Aster Data Support URL, V-viuser

CREATE USER, V-43deleting, V-54GRANT permissions, V-61permissions list for SQL-MapReduce, V-188permissions set using schemas, V-188privileges in database, V-31REVOKE permissions, V-71system table for, V-186

user activity tables, V-194UTF-8

default encoding, V-29utilities

ncluster_storagestat, V-93uuid datatype, V-178

VVACUUM, V-92

command reference, V-92VALUES

example, V-65reference, V-64

VALUES clauseexample, V-65not supported in nCluster SELECT, V-82reference, V-64

varchar, V-163functions and, V-100

VARIANCE function, V-131VAR_POP function, V-131VAR_SAMP function, V-131version

documentation version, V-viiview, V-45

and SQL-MapReduce, V-46virtual worker

memory settings per worker, V-85

Wweek in timestamp, V-127WHERE Clause, V-78WHERE CURRENT OF, V-48whitespace in table and column names, V-200wildcard character, V-77

column sort order, V-77WINDOW clause: not supported, V-156window function

consistent sorting of input rows, V-153repartitioning perfomance, V-154sorting output rows, V-138

window functions, V-137aggregate window functions, V-146

AVG, V-146COUNT, V-146default frame, V-151DENSE_RANK, V-139frame, V-146frame limitations, V-156frame types, V-149known issues, V-155LAG, V-145LEAD, V-145MAX, V-146MIN, V-146numbering window functions, V-139RANGE, V-149RANK, V-139ROWS, V-149ROW_NUMBER, V-139SUM, V-146syntax synopsis, V-137usage note regarding frames, V-153

window table functions, V-139worker node

memory settings per virtual worker, V-85

XXOR, bitwise, V-103

Yyear in timestamp, V-127

Symbols_bee_stats, V-194, , =, != operators in SQL, V-96:: for CAST, V-179+, -, =, etc., V-97<> operator, V-97

database sql and function reference

Documents

sql commands v

function reference v

alter index

alter role

alter schema

alter table

alter user

alter view