HP Vertica Analytics Platform 7.0.x SQL Reference Manual

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 1539

DownloadHP Vertica Analytics Platform 7.0.x SQL Reference Manual
Open PDF In BrowserView PDF
SQL Reference Manual
HP Vertica Analytic Database
Software Version: 7.0.x

Document Release Date: 2/24/2014

Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be
construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.

Restricted Rights Legend
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer
Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial
license.

Copyright Notice
© Copyright 2006 - 2014 Hewlett-Packard Development Company, L.P.

Trademark Notices
Adobe® is a trademark of Adobe Systems Incorporated.
Microsoft® and Windows® are U.S. registered trademarks of Microsoft Corporation.
UNIX® is a registered trademark of The Open Group.

HP Vertica Analytic Database (7.0.x)

Page 2 of 1539

Contents
Contents

3

SQL Overview

39

HP Vertica Support for ANSI SQL Standards

39

Support for Historical Queries

39

Joins

39

Transactions

39

System Limits

41

SQL Language Elements

43

Keywords and Reserved Words

44

Keywords

44

Reserved Words

47

Identifiers

48

Non-ASCII Characters
Literals

48
51

Number-Type Literals

51

String Literals

54

Character String Literals

54

Single Quotes in a String

54

Standard Conforming Strings and Escape Characters

55

Dollar-Quoted String Literals

56

Unicode String Literals

57

Using Standard Conforming Strings

57

VARBINARY String Literals

58

Extended String Literals

59

Standard Conforming Strings and Escape Characters

60

Identifying Strings That Are Not Standard Conforming

61

Doubled Single Quotes

62

Date/Time Literals
Time Zone Values

HP Vertica Analytic Database (7.0.x)

64
64

Page 3 of 1539

SQL Reference Manual
Contents

Day of the Week Names

65

Month Names

65

Interval Values

66

Interval-Literal

67

Interval-Qualifier

70

Operators

72

Binary Operators

72

Boolean Operators

74

Comparison Operators

75

Data Type Coercion Operators (CAST)

75

Date/Time Operators

78

Mathematical Operators

79

NULL Operators

81

String Concatenation Operators

81

Expressions

83

Operator Precedence

83

Expression Evaluation Rules

84

Aggregate Expressions

84

CASE Expressions

85

Column References

87

Comments

88

Date/Time Expressions

88

NULL Value

91

Numeric Expressions

91

Predicates

93

BETWEEN-predicate

93

Boolean-Predicate

93

Column-Value-Predicate

94

IN-predicate

95

INTERPOLATE

95

Join-Predicate

99

HP Vertica Analytic Database (7.0.x)

Page 4 of 1539

SQL Reference Manual
Contents

LIKE-predicate

100

NULL-predicate

104

SQL Data Types

107

Binary Data Types

109

Boolean Data Type

113

Character Data Types

114

The Difference Between NULL and NUL
Date/Time Data Types

115
117

Time Zone Abbreviations for Input

117

DATE

118

DATETIME

119

INTERVAL

120

Displaying or Omitting Interval Units in Output

120

Specifying Units on Input

122

How the Interval-Qualifier Affects Output Units

123

Specifying Precision

124

Casting with Intervals

125

Processing Signed Intervals

126

Processing Interval-Literals Without Units

127

Using INTERVALYM for INTERVAL YEAR TO MONTH

128

Operations with Intervals

129

Fractional Seconds in Interval Units

129

Interval-Literal

132

Interval-Qualifier

134

SMALLDATETIME

135

TIME

136

TIME AT TIME ZONE

137

TIMESTAMP

139

TIMESTAMP AT TIME ZONE

144

Long Data Types

146

Numeric Data Types

149

HP Vertica Analytic Database (7.0.x)

Page 5 of 1539

SQL Reference Manual
Contents

DOUBLE PRECISION (FLOAT)

150

INTEGER

152

NUMERIC

153

Numeric Data Type Overflow

156

Data Type Coercion

158

Data Type Coercion Chart

163

SQL Functions
Aggregate Functions

167
168

APPROXIMATE_COUNT_DISTINCT

168

APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS

170

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS

173

AVG [Aggregate]

174

BIT_AND

175

BIT_OR

176

BIT_XOR

178

CORR

179

COUNT [Aggregate]

180

COVAR_POP

184

COVAR_SAMP

185

MAX [Aggregate]

185

MIN [Aggregate]

186

REGR_AVGX

187

REGR_AVGY

188

REGR_COUNT

188

REGR_INTERCEPT

189

REGR_R2

189

REGR_SLOPE

190

REGR_SXX

190

REGR_SXY

191

REGR_SYY

192

STDDEV [Aggregate]

192

HP Vertica Analytic Database (7.0.x)

Page 6 of 1539

SQL Reference Manual
Contents

STDDEV_POP [Aggregate]

193

STDDEV_SAMP [Aggregate]

194

SUM [Aggregate]

196

SUM_FLOAT [Aggregate]

197

VAR_POP [Aggregate]

198

VAR_SAMP [Aggregate]

198

VARIANCE [Aggregate]

200

Analytic Functions

202

Analytic Function Syntax

202

Analytic Syntactic Construct

202

window_partition_clause

204

window_order_clause

204

window_frame_clause

206

Window Aggregates

209

named_windows

211

AVG [Analytic]

212

CONDITIONAL_CHANGE_EVENT [Analytic]

213

CONDITIONAL_TRUE_EVENT [Analytic]

214

COUNT [Analytic]

216

CUME_DIST [Analytic]

218

DENSE_RANK [Analytic]

219

EXPONENTIAL_MOVING_AVERAGE [Analytic]

221

FIRST_VALUE [Analytic]

224

LAG [Analytic]

227

LAST_VALUE [Analytic]

231

LEAD [Analytic]

233

MAX [Analytic]

236

MEDIAN [Analytic]

237

MIN [Analytic]

238

NTILE [Analytic]

240

PERCENT_RANK [Analytic]

241

HP Vertica Analytic Database (7.0.x)

Page 7 of 1539

SQL Reference Manual
Contents

PERCENTILE_CONT [Analytic]

243

PERCENTILE_DISC [Analytic]

246

RANK [Analytic]

248

ROW_NUMBER [Analytic]

250

STDDEV [Analytic]

252

STDDEV_POP [Analytic]

254

STDDEV_SAMP [Analytic]

255

SUM [Analytic]

256

VAR_POP [Analytic]

258

VAR_SAMP [Analytic]

259

VARIANCE [Analytic]

260

Date/Time Functions

263

Usage

263

Daylight Savings Time Considerations

263

Date/Time Functions in Transactions

263

ADD_MONTHS

264

AGE_IN_MONTHS

265

AGE_IN_YEARS

267

CLOCK_TIMESTAMP

268

CURRENT_DATE

269

CURRENT_TIME

269

CURRENT_TIMESTAMP

270

DATE_PART

271

DATE

280

DATE_TRUNC

280

DATEDIFF

282

DAY

289

DAYOFMONTH

290

DAYOFWEEK

290

DAYOFWEEK_ISO

291

DAYOFYEAR

292

HP Vertica Analytic Database (7.0.x)

Page 8 of 1539

SQL Reference Manual
Contents

DAYS

293

EXTRACT

294

GETDATE

301

GETUTCDATE

302

HOUR

303

ISFINITE

304

JULIAN_DAY

304

LAST_DAY

305

LOCALTIME

306

LOCALTIMESTAMP

306

MICROSECOND

307

MIDNIGHT_SECONDS

308

MINUTE

309

MONTH

309

MONTHS_BETWEEN

310

NEW_TIME

312

NEXT_DAY

314

NOW [Date/Time]

315

OVERLAPS

316

QUARTER

317

ROUND [Date/Time]

318

SECOND

319

STATEMENT_TIMESTAMP

320

SYSDATE

321

TIME_SLICE

322

TIMEOFDAY

327

TIMESTAMPADD

328

TIMESTAMPDIFF

330

TIMESTAMP_ROUND

332

TIMESTAMP_TRUNC

333

TRANSACTION_TIMESTAMP

335

HP Vertica Analytic Database (7.0.x)

Page 9 of 1539

SQL Reference Manual
Contents

TRUNC [Date/Time]

335

WEEK

337

WEEK_ISO

337

YEAR

339

YEAR_ISO

339

Formatting Functions

341

TO_BITSTRING

341

TO_CHAR

342

TO_DATE

345

TO_HEX

346

TO_TIMESTAMP

347

TO_TIMESTAMP_TZ

349

TO_NUMBER

351

Template Patterns for Date/Time Formatting

353

Template Pattern Modifiers for Date/Time Formatting
Template Patterns for Numeric Formatting
Geospatial Package SQL Functions

355
356
357

To Install the Geospatial package:

357

Contents of the Geospatial Package

357

Using Geospatial Package SQL Functions

357

Using Built-In HP Vertica Functions for Geospatial Analysis

358

Geospatial SQL Functions

358

WGS-84 SQL Functions

358

Earth Radius, Radius of Curvature, and Bearing SQL Functions

359

ECEF Conversion SQL Functions

359

Bounding Box SQL Functions

360

Miles/Kilometer Conversion SQL Functions

360

BB_WITHIN

360

BEARING

361

CHORD_TO_ARC

362

DWITHIN

363

HP Vertica Analytic Database (7.0.x)

Page 10 of 1539

SQL Reference Manual
Contents

ECEF_CHORD

364

ECEF_x

365

ECEF_y

366

ECEF_z

367

ISLEFT

367

KM2MILES

368

LAT_WITHIN

369

LL_WITHIN

370

LLD_WITHIN

371

LON_WITHIN

372

MILES2KM

373

RADIUS_LON

374

RADIUS_M

374

RADIUS_N

375

RADIUS_R

376

RADIUS_Ra

377

RADIUS_Rc

377

RADIUS_Rv

378

RADIUS_SI

379

RAYCROSSING

379

WGS84_a

381

WGS84_b

382

WGS84_e2

382

WGS84_f

383

WGS84_if

383

WGS84_r1

384

IP Conversion Functions

385

INET_ATON

385

INET_NTOA

386

V6_ATON

387

V6_NTOA

388

HP Vertica Analytic Database (7.0.x)

Page 11 of 1539

SQL Reference Manual
Contents

V6_SUBNETA

389

V6_SUBNETN

390

V6_TYPE

392

Mathematical Functions

394

ABS

394

ACOS

394

ASIN

395

ATAN

396

ATAN2

396

CBRT

397

CEILING (CEIL)

398

COS

398

COT

399

DEGREES

400

DISTANCE

401

DISTANCEV

401

EXP

402

FLOOR

403

HASH

404

LN

405

LOG

406

MOD

406

MODULARHASH

408

PI

409

POWER (or POW)

409

RADIANS

410

RANDOM

411

RANDOMINT

411

ROUND

412

SIGN

414

SIN

415

HP Vertica Analytic Database (7.0.x)

Page 12 of 1539

SQL Reference Manual
Contents

SQRT

415

TAN

416

TRUNC

416

WIDTH_BUCKET

417

NULL-handling Functions

420

COALESCE

420

IFNULL

421

ISNULL

422

NULLIF

424

NULLIFZERO

425

NVL

426

NVL2

428

ZEROIFNULL

429

Pattern Matching Functions

431

EVENT_NAME

431

MATCH_ID

433

PATTERN_ID

434

Regular Expression Functions

436

ISUTF8

436

REGEXP_COUNT

437

REGEXP_INSTR

439

REGEXP_LIKE

442

REGEXP_REPLACE

445

REGEXP_SUBSTR

448

Sequence Functions

451

NEXTVAL

451

CURRVAL

453

LAST_INSERT_ID

455

String Functions

459

ASCII

459

BIT_LENGTH

460

HP Vertica Analytic Database (7.0.x)

Page 13 of 1539

SQL Reference Manual
Contents

BITCOUNT

461

BITSTRING_TO_BINARY

462

BTRIM

463

CHARACTER_LENGTH

464

CHR

465

CONCAT

466

DECODE

466

GREATEST

468

GREATESTB

469

HEX_TO_BINARY

471

HEX_TO_INTEGER

472

INET_ATON

473

INET_NTOA

474

INITCAP

475

INITCAPB

476

INSERT

477

INSTR

478

INSTRB

481

ISUTF8

482

LEAST

483

LEASTB

484

LEFT

486

LENGTH

487

LOWER

488

LOWERB

489

LPAD

490

LTRIM

490

MD5

491

OCTET_LENGTH

492

OVERLAY

493

OVERLAYB

494

HP Vertica Analytic Database (7.0.x)

Page 14 of 1539

SQL Reference Manual
Contents

POSITION

496

POSITIONB

498

QUOTE_IDENT

498

QUOTE_LITERAL

499

REPEAT

500

REPLACE

501

RIGHT

502

RPAD

503

RTRIM

504

SPACE

505

SPLIT_PART

506

SPLIT_PARTB

507

STRPOS

508

STRPOSB

509

SUBSTR

510

SUBSTRB

511

SUBSTRING

512

TO_BITSTRING

514

TO_HEX

515

TRANSLATE

516

TRIM

516

UPPER

518

UPPERB

519

V6_ATON

519

V6_NTOA

521

V6_SUBNETA

522

V6_SUBNETN

523

V6_TYPE

524

System Information Functions

527

CURRENT_DATABASE

527

CURRENT_SCHEMA

527

HP Vertica Analytic Database (7.0.x)

Page 15 of 1539

SQL Reference Manual
Contents

CURRENT_USER

529

DBNAME (function)

529

HAS_TABLE_PRIVILEGE

530

SESSION_USER

532

USER

533

USERNAME

533

VERSION

534

Timeseries Functions

535

TS_FIRST_VALUE

535

TS_LAST_VALUE

536

URI Encode/Decode Functions

539

URI_PERCENT_DECODE

539

URI_PERCENT_ENCODE

540

HP Vertica Meta-Functions
Alphabetical List of HP Vertica Meta-Functions
ADD_LOCATION
Storage Location Subdirectories

541
542
542
543

ADVANCE_EPOCH

544

ALTER_LOCATION_USE

545

USER Storage Location Restrictions

546

Monitoring Storage Locations

546

ALTER_LOCATION_LABEL

546

ANALYZE_CONSTRAINTS

548

Detecting Constraint Violations During a Load Process

549

Understanding Function Failures

550

ANALYZE_CORRELATIONS

556

ANALYZE_HISTOGRAM

558

ANALYZE_STATISTICS

561

ANALYZE_WORKLOAD

564

AUDIT

568

AUDIT_FLEX

572

HP Vertica Analytic Database (7.0.x)

Page 16 of 1539

SQL Reference Manual
Contents

AUDIT_LICENSE_SIZE

574

AUDIT_LICENSE_TERM

575

BUILD_FLEXTABLE_VIEW

575

CANCEL_REBALANCE_CLUSTER

579

CANCEL_REFRESH

579

CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY

580

CHANGE_RUNTIME_PRIORITY

581

CLEAR_CACHES

582

CLEAR_DATA_COLLECTOR

583

CLEAR_PROFILING

584

CLEAR_PROJECTION_REFRESHES

585

CLEAR_RESOURCE_REJECTIONS

586

CLEAR_OBJECT_STORAGE_POLICY

587

CLOSE_SESSION

588

Controlling Sessions

590

CLOSE_ALL_SESSIONS

592

Controlling Sessions

594

COMPUTE_FLEXTABLE_KEYS

595

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

597

CURRENT_SCHEMA

598

DATA_COLLECTOR_HELP

599

DISABLE_DUPLICATE_KEY_ERROR

601

DISABLE_ELASTIC_CLUSTER

604

DISABLE_LOCAL_SEGMENTS

605

DISABLE_PROFILING

605

DISPLAY_LICENSE

606

DO_TM_TASK

607

DROP_LICENSE

609

DROP_LOCATION

610

Retiring or Dropping a Storage Location

610

Storage Locations with Temp and Data Files

610

HP Vertica Analytic Database (7.0.x)

Page 17 of 1539

SQL Reference Manual
Contents

DROP_PARTITION

611

DROP_STATISTICS

614

DUMP_CATALOG

616

DUMP_LOCKTABLE

617

DUMP_PARTITION_KEYS

618

DUMP_PROJECTION_PARTITION_KEYS

619

DUMP_TABLE_PARTITION_KEYS

620

ENABLE_ELASTIC_CLUSTER

622

ENABLE_LOCAL_SEGMENTS

622

ENABLE_PROFILING

623

EVALUATE_DELETE_PERFORMANCE

624

EXPORT_CATALOG

627

EXPORT_OBJECTS

628

EXPORT_STATISTICS

630

EXPORT_TABLES

632

FLUSH_DATA_COLLECTOR

633

GET_AHM_EPOCH

634

GET_AHM_TIME

635

GET_AUDIT_TIME

636

GET_COMPLIANCE_STATUS

636

GET_CURRENT_EPOCH

637

GET_DATA_COLLECTOR_POLICY

638

GET_LAST_GOOD_EPOCH

639

GET_NUM_ACCEPTED_ROWS

639

GET_NUM_REJECTED_ROWS

640

GET_PROJECTION_STATUS

640

GET_PROJECTIONS, GET_TABLE_PROJECTIONS

642

HAS_ROLE

644

IMPORT_STATISTICS

646

INTERRUPT_STATEMENT

647

INSTALL_LICENSE

650

HP Vertica Analytic Database (7.0.x)

Page 18 of 1539

SQL Reference Manual
Contents

LAST_INSERT_ID

651

MAKE_AHM_NOW

653

MARK_DESIGN_KSAFE

655

MATERIALIZE_FLEXTABLE_COLUMNS

657

MEASURE_LOCATION_PERFORMANCE

659

MERGE_PARTITIONS

661

MOVE_PARTITIONS_TO_TABLE

662

PARTITION_PROJECTION

663

PARTITION_TABLE

665

PURGE

667

PURGE_PARTITION

667

PURGE_PROJECTION

669

PURGE_TABLE

670

REALIGN_CONTROL_NODES

672

REBALANCE_CLUSTER

672

REENABLE_DUPLICATE_KEY_ERROR

674

REFRESH

674

RELEASE_ALL_JVM_MEMORY

677

RELEASE_JVM_MEMORY

678

RELOAD_SPREAD

678

RESET_LOAD_BALANCE_POLICY

680

RESTORE_LOCATION

680

Effects of Restoring a Previously Retired Location

681

Monitoring Storage Locations

681

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

681

RETIRE_LOCATION

683

Effects of Retiring a Storage Location

683

Monitoring Storage Locations

684

SET_AHM_EPOCH

684

SET_AHM_TIME

686

SET_AUDIT_TIME

688

HP Vertica Analytic Database (7.0.x)

Page 19 of 1539

SQL Reference Manual
Contents

SET_CONTROL_SET_SIZE

689

SET_DATA_COLLECTOR_POLICY

690

SET_DATA_COLLECTOR_TIME_POLICY

692

SET_LOAD_BALANCE_POLICY

695

SET_LOCATION_PERFORMANCE

696

SET_SCALING_FACTOR

697

SET_OBJECT_STORAGE_POLICY

697

New Storage Policy

698

Existing Storage Policy

698

Forcing Existing Data Storage to a New Storage Location

698

SHUTDOWN

699

SLEEP

701

START_REBALANCE_CLUSTER

702

START_REFRESH

703

SYNCH_WITH_HCATALOG_SCHEMA

704

Catalog Management Functions

707

DROP_LICENSE

707

DUMP_CATALOG

707

EXPORT_CATALOG

708

EXPORT_OBJECTS

709

INSTALL_LICENSE

711

MARK_DESIGN_KSAFE

711

SYNCH_WITH_HCATALOG_SCHEMA

714

Client Connection Management Functions

715

SET_LOAD_BALANCE_POLICY

715

RESET_LOAD_BALANCE_POLICY

716

Cluster Management Functions

717

SET_CONTROL_SET_SIZE

717

REALIGN_CONTROL_NODES

718

RELOAD_SPREAD

719

REBALANCE_CLUSTER

720

HP Vertica Analytic Database (7.0.x)

Page 20 of 1539

SQL Reference Manual
Contents

Cluster Scaling Functions

722

CANCEL_REBALANCE_CLUSTER

722

DISABLE_ELASTIC_CLUSTER

722

DISABLE_LOCAL_SEGMENTS

723

ENABLE_ELASTIC_CLUSTER

723

ENABLE_LOCAL_SEGMENTS

724

REBALANCE_CLUSTER

725

SET_SCALING_FACTOR

726

START_REBALANCE_CLUSTER

727

Constraint Management Functions

729

ANALYZE_CONSTRAINTS

729

Detecting Constraint Violations During a Load Process

730

Understanding Function Failures

731

ANALYZE_CORRELATIONS

737

DISABLE_DUPLICATE_KEY_ERROR

739

LAST_INSERT_ID

742

REENABLE_DUPLICATE_KEY_ERROR

744

Data Collector Functions

746

Related Topics

746

CLEAR_DATA_COLLECTOR

746

DATA_COLLECTOR_HELP

747

FLUSH_DATA_COLLECTOR

749

GET_DATA_COLLECTOR_POLICY

750

SET_DATA_COLLECTOR_POLICY

751

SET_DATA_COLLECTOR_TIME_POLICY

753

Database Designer Functions

756

DESIGNER_ADD_DESIGN_QUERIES

757

DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS

760

DESIGNER_ADD_DESIGN_QUERY

762

DESIGNER_ADD_DESIGN_TABLES

763

DESIGNER_CANCEL_POPULATE_DESIGN

765

HP Vertica Analytic Database (7.0.x)

Page 21 of 1539

SQL Reference Manual
Contents

DESIGNER_CREATE_DESIGN

766

DESIGNER_DESIGN_PROJECTION_ENCODINGS

768

DESIGNER_DROP_ALL_DESIGNS

769

DESIGNER_DROP_DESIGN

770

DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS

771

DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT

773

DESIGNER_RESET_DESIGN

774

DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY

775

DESIGNER_SET_ANALYZE_CORRELATIONS_MODE

777

DESIGNER_SET_DESIGN_KSAFETY

779

DESIGNER_SET_DESIGN_TYPE

781

DESIGNER_SET_OPTIMIZATION_OBJECTIVE

782

DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS

784

DESIGNER_WAIT_FOR_DESIGN

785

Database Management Functions

787

CLEAR_RESOURCE_REJECTIONS

787

DUMP_LOCKTABLE

787

DUMP_PARTITION_KEYS

788

EXPORT_TABLES

790

HAS_ROLE

791

SET_CONFIG_PARAMETER

793

SHUTDOWN

794

Epoch Management Functions

797

ADVANCE_EPOCH

797

GET_AHM_EPOCH

797

GET_AHM_TIME

798

GET_CURRENT_EPOCH

799

GET_LAST_GOOD_EPOCH

799

MAKE_AHM_NOW

800

SET_AHM_EPOCH

801

SET_AHM_TIME

803

HP Vertica Analytic Database (7.0.x)

Page 22 of 1539

SQL Reference Manual
Contents

Flex Table Functions

805

COMPUTE_FLEXTABLE_KEYS

805

COMPUTE_FLEXTABLE_KEYS

807

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

809

MATERIALIZE_FLEXTABLE_COLUMNS

810

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

812

License Management Functions

814

AUDIT

814

AUDIT_FLEX

818

AUDIT_LICENSE_SIZE

820

AUDIT_LICENSE_TERM

821

GET_AUDIT_TIME

821

GET_COMPLIANCE_STATUS

822

DISPLAY_LICENSE

823

SET_AUDIT_TIME

824

Partition Management Functions

825

DROP_PARTITION

825

DUMP_PROJECTION_PARTITION_KEYS

828

DUMP_TABLE_PARTITION_KEYS

829

MERGE_PARTITIONS

830

MOVE_PARTITIONS_TO_TABLE

832

PARTITION_PROJECTION

833

PARTITION_TABLE

835

PURGE_PARTITION

836

Profiling Functions

839

CLEAR_PROFILING

839

DISABLE_PROFILING

839

ENABLE_PROFILING

840

Projection Management Functions

842

EVALUATE_DELETE_PERFORMANCE

842

GET_PROJECTION_STATUS

845

HP Vertica Analytic Database (7.0.x)

Page 23 of 1539

SQL Reference Manual
Contents

GET_PROJECTIONS, GET_TABLE_PROJECTIONS

846

REFRESH

848

START_REFRESH

851

Purge Functions

853

PURGE

853

PURGE_PARTITION

854

PURGE_PROJECTION

855

PURGE_TABLE

856

Session Management Functions

859

CANCEL_REFRESH

859

CLOSE_ALL_SESSIONS

860

Controlling Sessions

862

CLOSE_SESSION
Controlling Sessions

863
866

GET_NUM_ACCEPTED_ROWS

867

GET_NUM_REJECTED_ROWS

868

INTERRUPT_STATEMENT

868

RELEASE_ALL_JVM_MEMORY

872

RELEASE_JVM_MEMORY

873

Statistic Management Functions

874

ANALYZE_HISTOGRAM

874

ANALYZE_STATISTICS

877

DROP_STATISTICS

881

EXPORT_STATISTICS

883

IMPORT_STATISTICS

885

Storage Management Functions

887

ADD_LOCATION
Storage Location Subdirectories
ALTER_LOCATION_USE

887
888
889

USER Storage Location Restrictions

890

Monitoring Storage Locations

890

HP Vertica Analytic Database (7.0.x)

Page 24 of 1539

SQL Reference Manual
Contents

ALTER_LOCATION_LABEL

890

CLEAR_CACHES

892

CLEAR_OBJECT_STORAGE_POLICY

893

DROP_LOCATION

894

Retiring or Dropping a Storage Location

894

Storage Locations with Temp and Data Files

894

MEASURE_LOCATION_PERFORMANCE

895

RESTORE_LOCATION

897

Effects of Restoring a Previously Retired Location

897

Monitoring Storage Locations

897

RETIRE_LOCATION

898

Effects of Retiring a Storage Location

898

Monitoring Storage Locations

899

SET_LOCATION_PERFORMANCE

899

SET_OBJECT_STORAGE_POLICY

901

New Storage Policy

901

Existing Storage Policy

901

Forcing Existing Data Storage to a New Storage Location

902

Tuple Mover Functions

903

DO_TM_TASK

903

Workload Management Functions

906

ANALYZE_WORKLOAD

906

CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY

909

CHANGE_RUNTIME_PRIORITY

910

CLEAR_CACHES

911

SLEEP

912

SQL Statements

915

ALTER DATABASE

915

ALTER FAULT GROUP

916

ALTER FUNCTION

917

ALTER LIBRARY

920

HP Vertica Analytic Database (7.0.x)

Page 25 of 1539

SQL Reference Manual
Contents

ALTER NODE

921

ALTER NETWORK INTERFACE

922

ALTER PROJECTION RENAME

922

ALTER PROFILE

923

ALTER PROFILE RENAME

926

ALTER RESOURCE POOL

927

ALTER ROLE RENAME

938

ALTER SCHEMA

938

ALTER SEQUENCE

940

ALTER SUBNET

943

ALTER TABLE

944

Table Behavior After Alteration

955

Changing a Data Type for a Column Specified in a SEGMENTED BY Clause

955

Locked Tables

956

Adding and Changing Constraints on Columns Using ALTER TABLE

956

Adding and Dropping NOT NULL Column Constraints

957

Table-Constraint

958

Specifying Primary and Foreign Keys

959

Adding Constraints to Views

959

ALTER USER
Database Account Changes Users Can Make

959
959

ALTER VIEW

963

BEGIN

963

COMMENT ON Statements

966

COMMENT ON COLUMN

966

COMMENT ON CONSTRAINT

968

COMMENT ON FUNCTION

969

COMMENT ON LIBRARY

971

COMMENT ON NODE

972

COMMENT ON PROJECTION

974

COMMENT ON SCHEMA

975

HP Vertica Analytic Database (7.0.x)

Page 26 of 1539

SQL Reference Manual
Contents

COMMENT ON SEQUENCE

976

COMMENT ON TABLE

978

COMMENT ON TRANSFORM FUNCTION

979

COMMENT ON VIEW

981

COMMIT

982

CONNECT

983

Connection Details
COPY

984
984

COPY Option Summary

995

Setting vsql Variables

997

Using Compressed Data and Named Pipes

998

COPY LOCAL

999

How Copy Local Works

1000

Viewing Copy Local Operations in a Query Plan

1000

COPY FROM VERTICA
Source and Destination Column Mapping

1000
1003

CREATE EXTERNAL TABLE AS COPY

1004

CREATE FAULT GROUP

1006

CREATE FLEX TABLE

1008

Unsupported CREATE Options for Flex Tables

1009

Default Flex Table and Keys Table Projections

1009

CREATE FLEX EXTERNAL TABLE AS COPY

1010

CREATE FUNCTION Statements

1013

About Creating User Defined Transform Functions (UDTFs)

1014

CREATE AGGREGATE FUNCTION

1014

CREATE ANALYTIC FUNCTION

1017

CREATE FILTER

1018

CREATE FUNCTION (SQL Functions)

1020

CREATE FUNCTION (UDF)

1024

CREATE PARSER

1026

CREATE SOURCE

1029

HP Vertica Analytic Database (7.0.x)

Page 27 of 1539

SQL Reference Manual
Contents

CREATE TRANSFORM FUNCTION
UDTF Query Restrictions

1031
1032

CREATE HCATALOG SCHEMA

1033

CREATE LIBRARY

1035

CREATE LOCAL TEMPORARY VIEW

1037

CREATE NETWORK INTERFACE

1040

CREATE PROCEDURE

1040

CREATE PROFILE

1042

CREATE PROJECTION

1045

Projections and Superprojections

1051

Checking Column Constraints

1051

Updating the Projection Using Refresh

1051

Creating Unsegmented Projections with the ALL NODES Option

1052

Encoding-Type

1053

ENCODING AUTO (default)

1053

ENCODING BLOCK_DICT

1053

ENCODING BLOCKDICT_COMP

1053

ENCODING COMMONDELTA_COMP

1054

ENCODING DELTARANGE_COMP

1054

ENCODING DELTAVAL

1054

ENCODING GCDDELTA

1054

ENCODING RLE

1055

ENCODING NONE

1055

Hash-Segmentation-Clause

1055

CREATE RESOURCE POOL

1057

Permissions

1065

Built-In Pools

1067

Built-In Pool

1067

Settings

1067

Upgrade From Earlier Versions of HP Vertica

1069

Built-In Pool Configuration

HP Vertica Analytic Database (7.0.x)

1069

Page 28 of 1539

SQL Reference Manual
Contents

GENERAL

1070

SYSQUERY

1071

SYSDATA

1072

WOSDATA

1073

TM

1073

REFRESH

1074

RECOVERY

1074

DBD

1075

JVM

1075

CREATE ROLE

1076

CREATE SCHEMA

1076

CREATE SEQUENCE

1078

Incrementing and Obtaining Sequence Values

1080

Removing a Sequence

1081

CREATE SUBNET

1083

CREATE TABLE

1084

Automatic Projection Creation

1090

Partition Clauses

1090

Column-Definition (table)

1095

Column-Name-List (table)

1096

Column-Constraint

1099

Table-Constraint

1106

Specifying Primary and Foreign Keys

1107

Adding Constraints to Views

1107

Hash-Segmentation-Clause (table)

1108

CREATE TEMPORARY TABLE

1109

Column-Definition (temp table)

1115

Column-Name-List (temp table)

1117

Hash-Segmentation-Clause (temp table)

1119

CREATE USER

1121

CREATE VIEW

1125

HP Vertica Analytic Database (7.0.x)

Page 29 of 1539

SQL Reference Manual
Contents

Transforming a SELECT Query to Use a View

1126

Dropping a View

1127

Renaming a View

1127

DELETE
Using the DELETE Statement

1128
1129

DISCONNECT

1130

DROP AGGREGATE FUNCTION

1131

DROP FAULT GROUP

1133

DROP FUNCTION

1134

DROP SOURCE

1135

DROP FILTER

1137

DROP PARSER

1138

DROP LIBRARY

1139

DROP NETWORK INTERFACE

1140

DROP PROCEDURE

1141

DROP PROFILE

1142

DROP PROJECTION

1143

DROP RESOURCE POOL

1144

Transferring Resource Requests

1145

DROP ROLE

1145

DROP SCHEMA

1146

DROP SEQUENCE

1147

DROP SUBNET

1149

DROP TABLE

1149

DROP TRANSFORM FUNCTION

1151

DROP USER

1152

DROP VIEW

1154

END

1154

EXPLAIN

1155

EXPORT TO VERTICA

1156

Source and Destination Column Mapping

HP Vertica Analytic Database (7.0.x)

1157

Page 30 of 1539

SQL Reference Manual
Contents

GRANT Statements

1160

GRANT (Database)

1160

GRANT (Procedure)

1161

GRANT (Resource Pool)

1163

GRANT (Role)

1163

Creating Roles

1164

Activating a Role

1164

Granting One Role To Another

1165

Checking for Circular References

1165

Granting Administrative Privileges

1165

GRANT (Schema)

1166

GRANT (Sequence)

1167

GRANT (Storage Location)

1168

GRANT (Table)

1170

GRANT (User Defined Extension)

1172

GRANT (View)

1174

INSERT

1176

MERGE

1178

Using Named Sequences

1183

Improving MERGE Performance

1183

PROFILE

1183

Real-Time Profiling Example

1184

How to Use the Linux watch Command

1185

How to Find Out Which Counters are Available

1185

RELEASE SAVEPOINT

1186

REVOKE Statements

1188

REVOKE (Database)

1188

REVOKE (Procedure)

1189

REVOKE (Resource Pool)

1191

REVOKE (Role)

1191

REVOKE (Schema)

1192

HP Vertica Analytic Database (7.0.x)

Page 31 of 1539

SQL Reference Manual
Contents

REVOKE (Sequence)

1194

REVOKE (Storage Location)

1195

REVOKE (Table)

1196

REVOKE (User Defined Extension)

1198

REVOKE (View)

1200

ROLLBACK

1201

ROLLBACK TO SAVEPOINT

1202

SAVEPOINT

1203

SELECT

1205

Parameters

1206

EXCEPT Clause

1208

FROM Clause

1212

Table-Reference

1212

Table-Primary

1213

Joined-Table

1213

GROUP BY Clause

1213

HAVING Clause

1215

INTERSECT Clause

1216

INTO Clause

1220

LIMIT Clause

1221

MATCH Clause

1222

Pattern Semantic Evaluation

1225

MINUS Clause

1227

OFFSET Clause

1227

ORDER BY Clause

1228

TIMESERIES Clause

1230

UNION Clause

1233

WHERE Clause

1236

WINDOW Clause

1238

WITH Clause

1238

SET DATESTYLE

HP Vertica Analytic Database (7.0.x)

1240

Page 32 of 1539

SQL Reference Manual
Contents

SET ESCAPE_STRING_WARNING

1241

SET INTERVALSTYLE

1242

Output Intervals with Units

1243

Output Intervals Without Units

1243

Displaying the Current Interval OUTPUT Style

1243

SET LOCALE

1244

SET ROLE

1248

SET SEARCH_PATH

1249

SET SESSION AUTOCOMMIT

1251

SET SESSION CHARACTERISTICS

1251

Understanding READ COMMITTED and Snapshot Isolation

1252

Using SERIALIZABLE Transaction Isolation

1253

Setting READ ONLY Transaction Mode

1253

SET SESSION MEMORYCAP

1253

SET SESSION RESOURCE_POOL

1254

SET SESSION RUNTIMECAP

1255

SET SESSION TEMPSPACECAP

1257

SET STANDARD_CONFORMING_STRINGS

1259

SET TIME ZONE

1260

Time Zone Names for Setting TIME ZONE
SHOW

1261
1263

How to Display All Current Run-Time Parameter Settings

1264

Displaying Current Search Path Settings

1265

Displaying the Transaction Isolation Level

1265

START TRANSACTION

1265

TRUNCATE TABLE

1269

UPDATE

1270

HP Vertica System Tables
V_CATALOG Schema

1275
1276

ALL_TABLES

1276

CLUSTER_LAYOUT

1277

HP Vertica Analytic Database (7.0.x)

Page 33 of 1539

SQL Reference Manual
Contents

COLUMNS

1278

COMMENTS

1281

CONSTRAINT_COLUMNS

1282

DATABASES

1283

DUAL

1284

ELASTIC_CLUSTER

1285

EPOCHS

1286

FAULT_GROUPS

1287

FOREIGN_KEYS

1288

GRANTS

1290

HCATALOG_COLUMNS

1294

HCATALOG_SCHEMATA

1298

HCATALOG_TABLES

1300

HCATALOG_TABLE_LIST

1302

LARGE_CLUSTER_CONFIGURATION_STATUS

1304

LICENSE_AUDITS

1304

LICENSES

1305

MATERIALIZE_FLEXTABLE_COLUMNS_RESULTS

1306

NODES

1307

ODBC_COLUMNS

1308

PASSWORDS

1310

PRIMARY_KEYS

1310

PROFILE_PARAMETERS

1311

PROFILES

1312

PROJECTION_CHECKPOINT_EPOCHS

1313

PROJECTION_COLUMNS

1314

PROJECTION_DELETE_CONCERNS

1321

PROJECTIONS

1321

RESOURCE_POOL_DEFAULTS

1324

RESOURCE_POOLS

1325

ROLES

1331

HP Vertica Analytic Database (7.0.x)

Page 34 of 1539

SQL Reference Manual
Contents

SCHEMATA

1332

SEQUENCES

1333

STORAGE_LOCATIONS

1336

SYSTEM_COLUMNS

1340

SYSTEM_TABLES

1341

TABLE_CONSTRAINTS

1342

TABLES

1344

TYPES

1346

USER_AUDITS

1348

USER_FUNCTIONS

1349

USER_PROCEDURES

1350

USER_TRANSFORMS

1351

USERS

1352

VIEW_COLUMNS

1354

VIEWS

1356

V_MONITOR Schema

1358

ACTIVE_EVENTS

1358

COLUMN_STORAGE

1360

CONFIGURATION_CHANGES

1363

CONFIGURATION_PARAMETERS

1365

CPU_USAGE

1366

CRITICAL_HOSTS

1366

CRITICAL_NODES

1367

CURRENT_SESSION

1367

DATA_COLLECTOR

1373

DATABASE_BACKUPS

1378

DATABASE_CONNECTIONS

1379

DATABASE_SNAPSHOTS

1380

DELETE_VECTORS

1381

DEPLOY_STATUS

1382

DEPLOYMENT_PROJECTION_STATEMENTS

1383

HP Vertica Analytic Database (7.0.x)

Page 35 of 1539

SQL Reference Manual
Contents

DEPLOYMENT_PROJECTIONS

1385

DESIGN_QUERIES

1387

DESIGN_STATUS

1389

DESIGN_TABLES

1391

DESIGNS

1392

DISK_RESOURCE_REJECTIONS

1394

DISK_STORAGE

1395

ERROR_MESSAGES

1400

EVENT_CONFIGURATIONS

1402

EXECUTION_ENGINE_PROFILES

1403

HOST_RESOURCES

1415

IO_USAGE

1418

LOAD_STREAMS

1418

LOCK_USAGE

1420

LOCKS

1423

LOGIN_FAILURES

1427

MEMORY_USAGE

1429

MONITORING_EVENTS

1430

NETWORK_INTERFACES

1432

NETWORK_USAGE

1434

NODE_RESOURCES

1434

NODE_STATES

1436

OUTPUT_DEPLOYMENT_STATUS

1437

OUTPUT_EVENT_HISTORY

1439

PARTITION_REORGANIZE_ERRORS

1442

PARTITION_STATUS

1443

PARTITIONS

1444

PROCESS_SIGNALS

1445

PROJECTION_RECOVERIES

1446

PROJECTION_REFRESHES

1449

PROJECTION_STORAGE

1453

HP Vertica Analytic Database (7.0.x)

Page 36 of 1539

SQL Reference Manual
Contents

PROJECTION_USAGE

1456

QUERY_EVENTS

1458

QUERY_METRICS

1463

QUERY_PLAN_PROFILES

1464

QUERY_PROFILES

1466

QUERY_REQUESTS

1469

REBALANCE_PROJECTION_STATUS

1472

REBALANCE_TABLE_STATUS

1474

RECOVERY_STATUS

1476

RESOURCE_ACQUISITIONS

1477

RESOURCE_POOL_STATUS

1480

RESOURCE_QUEUES

1485

RESOURCE_REJECTION_DETAILS

1485

RESOURCE_REJECTIONS

1487

RESOURCE_USAGE

1490

SESSION_PROFILES

1492

SESSIONS

1494

STORAGE_CONTAINERS

1498

STORAGE_POLICIES

1502

STORAGE_TIERS

1503

STORAGE_USAGE

1504

STRATA

1506

STRATA_STRUCTURES

1508

SYSTEM

1511

SYSTEM_RESOURCE_USAGE

1512

SYSTEM_SERVICES

1514

SYSTEM_SESSIONS

1516

TRANSACTIONS

1519

TUNING_RECOMMENDATIONS

1521

TUPLE_MOVER_OPERATIONS

1523

UDX_FENCED_PROCESSES

1526

HP Vertica Analytic Database (7.0.x)

Page 37 of 1539

SQL Reference Manual
Contents

USER_LIBRARIES

1527

USER_LIBRARY_MANIFEST

1528

USER_SESSIONS

1529

WOS_CONTAINER_STORAGE

1532

Appendix: Compatibility with Other RDBMS
Data Type Mappings Between HP Vertica and Oracle

We appreciate your feedback!

HP Vertica Analytic Database (7.0.x)

1535
1535

1539

Page 38 of 1539

SQL Reference Manual
SQL Overview

SQL Overview
An abbreviation for Structured Query Language, SQL is a widely-used, industry standard data
definition and data manipulation language for relational databases.
Note: In HP Vertica, use a semicolon to end a statement or to combine multiple statements on
one line.

HP Vertica Support for ANSI SQL Standards
HP Vertica SQL supports a subset of ANSI SQL-99.
See BNF Grammar for SQL-99

Support for Historical Queries
Unlike most databases, the DELETE command in HP Vertica does not delete data; it marks
records as deleted. The UPDATE command performs an INSERT and a DELETE. This behavior is
necessary for historical queries. See Historical (Snapshot) Queries in the Programmer's Guide.

Joins
HP Vertica supports typical data warehousing query joins. For details, see Joins in the
Programmer's Guide.
HP Vertica also provides the INTERPOLATE predicate, which allows for a special type of join. The
event series join is an HP Vertica SQL extension that lets you analyze two event series when their
measurement intervals don’t align precisely—such as when timestamps don't match. These joins
provide a natural and efficient way to query misaligned event data directly, rather than having to
normalize the series to the same measurement interval. See Event Series Joins in the
Programmer's Guide for details.

Transactions
Session-scoped isolation levels determine transaction characteristics for transactions within a
specific user session. You set them through the SET SESSION CHARACTERISTICS command.
Specifically, they determine what data a transaction can access when other transactions are
running concurrently. See Transactions in the Concepts Guide.

HP Vertica Analytic Database (7.0.x)

Page 39 of 1539

SQL Reference Manual
SQL Overview

HP Vertica Analytic Database (7.0.x)

Page 40 of 1539

SQL Reference Manual
System Limits

System Limits
This section describes the system limits on the size and number of objects in an HP Vertica
database. In most cases, computer memory and disk drive are the limiting factors.
Item

Limit

Number of nodes

Maximum 128 (without HP Vertica assistance).

Database size

Approximates the number of files times the file size on a platform, depending
on the maximum disk configuration.

Table size

2^64 rows per node, or 2^63 bytes per column, whichever is smaller.

Row size

32 MB. The row size is approximately the sum of its maximum column
sizes, where, for example, a VARCHAR(80) has a maximum size of 80
bytes.

Key size

Limited only by row size

Number of
tables/projections
per database

Limited by physical RAM, as the catalog must fit in memory.

Number of
concurrent
connections per
node

Default of 50, limited by physical RAM (or threads per process), typically
1024.

Number of
concurrent
connections per
cluster

Limited by physical RAM of a single node (or threads per process), typically
1024.

Number of
columns per table

1600.

Number of rows
per load

2^63.

Number of
partitions

1024.
l

While HP Vertica supports a maximum of 1024 partitions, few, if any,
organizations will need to approach that maximum. Fewer partitions are
likely to meet your business needs, while also ensuring maximum
performance. Many customers, for example, partition their data by month,
bringing their partition count to 12. HP Vertica recommends you keep the
number of partitions between 10 and 20 to achieve excellent
performance.

HP Vertica Analytic Database (7.0.x)

Page 41 of 1539

SQL Reference Manual
System Limits

Item

Limit

Length for a fixed- 65000 bytes.
length column
Length for a
variable-length
column

65000 bytes.

Length of basic
names

128 bytes. Basic names include table names, column names, etc.

Query length

No limit.

Depth of nesting
subqueries

Unlimited in FROM, WHERE, or HAVING clause.

HP Vertica Analytic Database (7.0.x)

Page 42 of 1539

SQL Reference Manual
SQL Language Elements

SQL Language Elements
This chapter presents detailed descriptions of the language elements and conventions of HP
Vertica SQL.

HP Vertica Analytic Database (7.0.x)

Page 43 of 1539

SQL Reference Manual
SQL Language Elements

Keywords and Reserved Words
Keywords are words that have a specific meaning in the SQL language. Although SQL is not casesensitive with respect to keywords, they are generally shown in uppercase letters throughout this
documentation for readability purposes.
Some SQL keywords are also reserved words that cannot be used in an identifier unless enclosed
in double quote (") characters. Some unreserved keywords can be used in statements by preceding
them with AS. For example, SOURCE is a keyword, but is not reserved, and you can use it as
follows:
VMART=> select my_node AS SOURCE from nodes;

Keywords
Keyword are words that are specially handled by the grammar. Every SQL statement contains one
or more keywords.
Begins
with
Keyword
A

ABORT, ABSOLUTE, ACCESS, ACCESRANK, ACCOUNT, ACTION, ADD,
ADMIN, AFTER, AGGREGATE, ALL, ALSO, ALTER, ANALYSE, ANALYZE, AND,
ANY, ARRAY, AS, ASC, ASSERTION, ASSIGNMENT, AT, AUTHORIZATION,
AUTO, AUTO_INCREMENT, AVAILABLE

B

BACKWARD, BEFORE, BEGIN, BETWEEN, BIGINT, BINARY, BIT, BLOCK_
DICT, BLOCKDICT_COMP, BOOLEAN, BOTH, BY, BYTEA, BZIP

C

CACHE, CALLED, CASCADE, CASE, CAST, CATALOGPATH, CHAIN, CHAR,
CHAR_LENGTH, CHARACTER, CHARACTER_LENGTH, CHARACTERISTICS,
CHARACTERS, CHECK, CHECKPOINT, CLASS, CLOSE, CLUSTER, COLLATE,
COLUMN, COLUMNS_COUNT, COMMENT, COMMIT, COMMITTED,
COMMONDELTA_COMP, CONNECT, CONSTRAINT, CONSTRAINTS, COPY,
CORRELATION, CREATE, CREATEDB, CREATEUSER, CROSS, CSV,
CURRENT, CURRENT_DATABASE, CURRENT_DATE, CURRENT_SCHEMA,
CURRENT_TIME, CURRENT_TIMESTAMP, CURRENT_USER, CURSOR,
CYCLE

D

DATA, DATABASE, DATAPATH, DATE, DATEDIFF, DATETIME, DAY,
DEALLOCATE, DEC, DECIMAL, DECLARE, DECODE, DEFAULT, DEFAULTS,
DEFERRABLE, DEFERRED, DEFINE, DEFINER, DELETE, DELIMITER,
DELIMITERS, DELTARANGE_COMP, DELTARANGE_COMP_SP, DELTAVAL,
DESC, DETERMINES, DIRECT, DIRECTCOLS, DIRECTGROUPED,
DIRECTPROJ, DISABLE, DISCONNECT, DISTINCT, DISTVALINDEX, DO,
DOMAIN, DOUBLE, DROP, DURABLE

HP Vertica Analytic Database (7.0.x)

Page 44 of 1539

SQL Reference Manual
SQL Language Elements

Begins
with
Keyword
E

EACH, ELSE, ENABLE, ENABLED, ENCLOSED, ENCODED, ENCODING,
ENCRYPTED, END, ENFORCELENGTH, EPHEMERAL, EPOCH, ERROR,
ESCAPE, EVENT, EVENTS, EXCEPT, EXCEPTIONS, EXCLUDE, EXCLUDING,
EXCLUSIVE, EXECUTE, EXISTS, EXPIRE, EXPLAIN, EXPORT, EXTERNAL,
EXTRACT

F

FAILED_LOGIN_ATTEMPTS, FALSE, FETCH, FILLER, FIRST, FLOAT,
FOLLOWING, FOR, FORCE, FOREIGN, FORMAT, FORWARD, FREEZE, FROM,
FULL, FUNCTION

G

GCDDELTA, GLOBAL, GRANT, GROUP, GROUPED, GZIP

H

HANDLER, HASH, HAVING, HOLD, HOSTNAME, HOUR, HOURS

I

IDENTIFIED, IDENTITY, IF, IGNORE, ILIKE, ILIKEB, IMMEDIATE, IMMUTABLE,
IMPLICIT, IN, INCLUDING, INCREMENT, INDEX, INHERITS, INITIALLY, INNER,
INOUT, INPUT, INSENSITIVE, INSERT, INSTEAD, INT, INTEGER,
INTERPOLATE, INTERSECT, INTERVAL, INTERVALYM, INTO, INVOKER, IS,
ISNULL, ISOLATION

J

JOIN

K

KEY, KSAFE

L

LANCOMPILER, LANGUAGE, LARGE, LAST, LATEST, LEADING, LEFT, LESS,
LEVEL, LIBRARY, LIKE, LIKEB, LIMIT, LISTEN, LOAD, LOCAL, LOCALTIME,
LOCALTIMESTAMP, LOCATION, LOCK

M

MANAGED, MATCH, MAXCONCURRENCY, MAXMEMORYSIZE, MAXVALUE,
MEMORYCAP, MEMORYSIZE, MERGE, MERGEOUT, MICROSECONDS,
MILLISECONDS, MINUTE, MINUTES, MINVALUE, MODE, MONEY, MONTH,
MOVE, MOVEOUT

N

NAME, NATIONAL, NATIVE, NATURAL, NCHAR, NEW, NEXT, NO,
NOCREATEDB, NOCREATEUSER, NODE, NODES, NONE, NOT, NOTHING,
NOTIFY, NOTNULL, NOWAIT, NULL, NULLCOLS, NULLS, NULLSEQUAL,
NULLIF, NUMBER, NUMERIC

O

OBJECT, OCTETS, OF, OFF, OFFSET, OIDS, OLD, ON, ONLY, OPERATOR,
OPTION, OR, ORDER, OTHERS, OUT, OUTER, OVER, OVERLAPS, OVERLAY,
OWNER

HP Vertica Analytic Database (7.0.x)

Page 45 of 1539

SQL Reference Manual
SQL Language Elements

Begins
with
Keyword
P

PARTIAL, PARTITION, PASSWORD, PASSWORD_GRACE_TIME, PASSWORD_
LIFE_TIME, PASSWORD_LOCK_TIME, PASSWORD_MAX_LENGTH,
PASSWORD_MIN_DIGITS, PASSWORD_MIN_LENGTH, PASSWORD_MIN_
LETTERS, PASSWORD_MIN_LOWERCASE_LETTERS, PASSWORD_MIN_
SYMBOLS, PASSWORD_MIN_UPPERCASE_LETTERS,PASSWORD_REUSE_
MAX, PASSWORD_REUSE_TIME, PATTERN, PERCENT, PERMANENT,
PINNED, PLACING, PLANNEDCONCURRENCY, POOL, POSITION,
PRECEDING, PRECISION, PREPARE, PRESERVE, PREVIOUS, PRIMARY,
PRIOR, PRIORITY, PRIVILEGES, PROCEDURAL, PROCEDURE, PROFILE,
PROJECTION

Q

QUEUETIMEOUT, QUOTE

R

RANGE, RAW, READ, REAL, RECHECK, RECORD, RECOVER, REFERENCES,
REFRESH, REINDEX, REJECTED, REJECTMAX, RELATIVE, RELEASE,
RENAME, REPEATABLE, REPLACE, RESET, RESOURCE, RESTART,
RESTRICT, RESULTS, RETURN, RETURNREJECTED, REVOKE, RIGHT, RLE,
ROLE, ROLES, ROLLBACK, ROW, ROWS, RULE, RUNTIMECAP

S

SAMPLE, SAVEPOINT, SCHEMA, SCROLL, SECOND, SECONDS, SECURITY,
SEGMENTED, SELECT, SEQUENCE, SERIALIZABLE, SESSION, SESSION_
USER, SET, SETOF, SHARE, SHOW, SIMILAR, SIMPLE, SINGLEINITIATOR,
SITE, SITES, SKIP, SMALLDATETIME, SMALLINT, SOME, SOURCE, SPLIT,
STABLE, START, STATEMENT, STATISTICS, STDERR, STDIN, STDOUT,
STORAGE, STREAM, STRENGTH, STRICT, SUBSTRING, SYSDATE, SYSID,
SYSTEM

T

TABLE, TABLESPACE, TEMP, TEMPLATE, TEMPORARY, TEMPSPACECAP,
TERMINATOR, THAN, THEN, TIES, TIME, TIMESERIES, TIMESTAMP,
TIMESTAMPADD, TIMESTAMPDIFF, TIMESTAMPTZ, TIMETZ, TIMEZONE,
TINYINT, TO, TOAST, TRAILING, TRANSACTION, TRANSFORM, TREAT,
TRICKLE, TRIGGER, TRIM, TRUE, TRUNCATE, TRUSTED, TUNING, TYPE

U

UNBOUNDED, UNCOMMITTED, UNCOMPRESSED, UNENCRYPTED, UNION,
UNIQUE, UNKNOWN, UNLIMITED, UNLISTEN, UNLOCK, UNSEGMENTED,
UNTIL, UPDATE, USAGE, USER, USING

V

VACUUM, VALIDATOR, VALINDEX, VALUE, VALUES, VARBINARY, VARCHAR,
VARCHAR2, VARYING, VERBOSE, VERTICA, VIEW, VOLATILE

W

WAIT, WHEN, WHERE, WINDOW, WITH, WITHIN, WITHOUT, WORK, WRITE

Y

YEAR

Z

ZONE

HP Vertica Analytic Database (7.0.x)

Page 46 of 1539

SQL Reference Manual
SQL Language Elements

Reserved Words
Many SQL keywords are also reserved words, but a reserved word is not necessarily a keyword.
For example, a reserved word might be reserved for other/future use. In HP Vertica, reserved words
can be used anywhere identifiers can be used, as long as you double-quote them.
Begins
with
Reserved Word
A

ALL, ANALYSE, ANALYZE, AND, ANY, ARRAY, AS, ASC

B

BINARY, BOTH

C

CASE, CAST, CHECK, COLUMN, CONSTRAINT, CORRELATION, CREATE,
CURRENT_DATABASE, CURRENT_DATE, CURRENT_SCHEMA, CURRENT_
TIME, CURRENT_TIMESTAMP, CURRENT_USER

D

DEFAULT, DEFERRABLE, DESC, DISTINCT, DO

E

ELSE, ENCODED, END, EXCEPT

F

FALSE, FOR, FOREIGN, FROM

G

GRANT, GROUP, GROUPED

H

HAVING

I

IN, INITIALLY, INTERSECT, INTERVAL, INTERVALYM, INTO

J

JOIN

K

KSAFE

L

LEADING, LIMIT, LOCALTIME, LOCALTIMESTAMP

M

MATCH

N

NEW, NOT, NULL, NULLSEQUAL

O

OFF, OFFSET, OLD, ON, ONLY, OR, ORDER

P

PINNED, PLACING, PRIMARY, PROJECTION

R

REFERENCES

S

SCHEMA, SEGMENTED, SELECT, SESSION_USER, SOME, SYSDATE

T

TABLE, THEN, TIMESERIES, TO, TRAILING, TRUE

U

UNBOUNDED, UNION, UNIQUE, UNSEGMENTED, USER, USING

W

WHEN, WHERE, WINDOW, WITH, WITHIN

HP Vertica Analytic Database (7.0.x)

Page 47 of 1539

SQL Reference Manual
SQL Language Elements

Identifiers
Identifiers (names) of objects such as schema, table, projection, column names, and so on, can be
up to 128 bytes in length.

Unquoted Identifiers
Unquoted SQL identifiers must begin with one of the following:
l

Letters such as A–Z or a–z, including letters with diacritical marks and non-Latin letters)

l

Underscore (_)

Subsequent characters in an identifier can be:
l

Letters

l

Digits(0–9)

l

Dollar sign ($). Dollar sign is not allowed in identifiers according to the SQL standard and could
cause application portability problems.

l

Underscore (_)

Quoted Identifiers
Identifiers enclosed in double quote (") characters can contain any character. If you want to include
a double quote, you need a pair of them; for example """". You can use names that would
otherwise be invalid, such as names that include only numeric characters ("123") or contain space
characters, punctuation marks, keywords, and so on; for example:
CREATE SEQUENCE "my sequence!";

Double quotes are required for non-alphanumerics and SQL keywords such as "1time", "Next
week" and "Select".
Note: Identifiers are not case-sensitive. Thus, identifiers "ABC", "ABc", and "aBc" are
synonymous, as are ABC, ABc, and aBc.

Non-ASCII Characters
HP Vertica accepts non-ASCII UTF-8 Unicode characters for table names, column names, and
other Identifiers, extending the cases in which upper/lower case distinctions are ignored (casefolded) to all alphabets, including Latin, Cyrillic, and Greek.

HP Vertica Analytic Database (7.0.x)

Page 48 of 1539

SQL Reference Manual
SQL Language Elements

Identifiers Are Stored As Created
SQL identifiers, such as table and column names, are no longer converted to lowercase. They are
stored as created, and references to them are resolved using case-insensitive compares. It is not
necessary to double quote mixed-case identifiers. For example, The following statement creates
table ALLCAPS.
=> CREATE TABLE ALLCAPS(c1 varchar(30));
=> INSERT INTO ALLCAPS values('upper case');

The following statements are variations of the same query and all return identical results:
=> SELECT * FROM ALLCAPS;
=> SELECT * FROM allcaps;
=> SELECT * FROM "allcaps";

All three commands return the same result:
c1
-----------upper case
(1 row)

Note that the system returns an error if you try to create table AllCaps:
=> CREATE TABLE allcaps(c1 varchar(30));
ROLLBACK: table "AllCaps" already exists

See QUOTE_IDENT for additional information.

Case-Sensitive System Tables
The V_CATALOG.TABLES.TABLE_SCHEMA and TABLE_NAME columns are case sensitive when used
with an equality (=) predicate in queries. For example, given the following sample schema, if you
execute a query using the = predicate, HP Vertica returns 0 rows:
=> CREATE SCHEMA SS;
=> CREATE TABLE SS.TT (c1 int);
=> INSERT INTO ss.tt VALUES (1);
=> SELECT table_schema, table_name FROM v_catalog.tables
WHERE table_schema ='ss';
table_schema | table_name
--------------+-----------(0 rows)

Tip: Use the case-insensitive ILIKE predicate to return the expected results.

HP Vertica Analytic Database (7.0.x)

Page 49 of 1539

SQL Reference Manual
SQL Language Elements

=> SELECT table_schema, table_name FROM v_catalog.tables
WHERE table_schema ILIKE 'ss';
table_schema | table_name
-------------+-----------SS
| TT
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 50 of 1539

SQL Reference Manual
SQL Language Elements

Literals
Literals are numbers or strings used in SQL as constants. Literals are included in the select-list,
along with expressions and built-in functions and can also be constants.
HP Vertica provides support for number-type literals (integers and numerics), string literals,
VARBINARY string literals, and date/time literals. The various string literal formats are discussed
in this section.

Number-Type Literals
There are three types of numbers in HP Vertica: Integers, numerics, and floats.
l

Integers are whole numbers less than 2^63 and must be digits.

l

Numerics are whole numbers larger than 2^63 or that include a decimal point with a precision
and a scale. Numerics can contain exponents. Numbers that begin with 0x are hexadecimal
numerics.

Numeric-type values can also be generated using casts from character strings. This is a more
general syntax. See the Examples section below, as well as Data Type Coercion Operators
(CAST).

Syntax
digits
digits.[digits] | [digits].digits
digits e[+-]digits | [digits].digits e[+-]digits | digits.[digits] e[+-]digits

Parameters
digits

Represents one or more numeric characters (0 through 9).

e

Represents an exponent marker.

Notes
l

At least one digit must follow the exponent marker (e), if e is present.

l

There cannot be any spaces or other characters embedded in the constant.

l

Leading plus (+) or minus (–) signs are not considered part of the constant; they are unary
operators applied to the constant.

HP Vertica Analytic Database (7.0.x)

Page 51 of 1539

SQL Reference Manual
SQL Language Elements

l

In most cases a numeric-type constant is automatically coerced to the most appropriate type
depending on context. When necessary, you can force a numeric value to be interpreted as a
specific data type by casting it as described in Data Type Coercion Operators (CAST).

l

Floating point literals are not supported. If you specifically need to specify a float, you can cast
as described in Data Type Coercion Operators (CAST).

l

HP Vertica follows the IEEE specification for floating point, including NaN (not a number) and
Infinity (Inf).

l

A NaN is not greater than and at the same time not less than anything, even itself. In other
words, comparisons always return false whenever a NaN is involved. See Numeric Expressions
for examples.

l

Dividing INTEGERS (x / y) yields a NUMERIC result. You can use the // operator to truncate
the result to a whole number.

Examples
The following are examples of number-type literals:
42
3.5
4.
.001
5e2
1.925e-3

Scientific notation:
=> SELECT NUMERIC '1e10';
?column?
------------10000000000
(1 row)

BINARY scaling:
=> SELECT NUMERIC '1p10';
?column?
---------1024
(1 row)
=> SELECT FLOAT 'Infinity';
?column?
---------Infinity
(1 row)

The following examples illustrated using the / and // operators to divide integers:

HP Vertica Analytic Database (7.0.x)

Page 52 of 1539

SQL Reference Manual
SQL Language Elements

VMart=> SELECT 40/25;
?column?
---------------------1.600000000000000000
(1 row)
VMart=> SELECT 40//25;
?column?
---------1
(1 row)

See Also
l

Data Type Coercion

HP Vertica Analytic Database (7.0.x)

Page 53 of 1539

SQL Reference Manual
SQL Language Elements

String Literals
String literals are string values surrounded by single or double quotes. Double-quoted strings are
subject to the backslash, but single-quoted strings do not require a backslash, except for \' and \\.
You can embed single quotes and backslashes into single-quoted strings.
To include other backslash (escape) sequences, such as \t (tab), you must use the double-quoted
form.
Precede single-quoted strings with a space between the string and its preceding word, since single
quotes are allowed in identifiers.

See Also
l

SET STANDARD_CONFORMING_STRINGS

l

SET ESCAPE_STRING_WARNING

l

Internationalization Parameters

l

Implement Locales for International Data Sets

Character String Literals
Character string literals are a sequence of characters from a predefined character set and are
enclosed by single quotes. If the single quote is part of the sequence, it must be doubled as "''".

Syntax
'characters'

Parameters
characters

Arbitrary sequence of characters bounded by single quotes (')

Single Quotes in a String
The SQL standard way of writing a single-quote character within a string literal is to write two
adjacent single quotes. for example:
=> SELECT 'Chester''s gorilla';
?column?
------------------Chester's gorilla

HP Vertica Analytic Database (7.0.x)

Page 54 of 1539

SQL Reference Manual
SQL Language Elements

(1 row)

Standard Conforming Strings and Escape Characters
HP Vertica uses standard conforming strings as specified in the SQL standard, which means that
backslashes are treated as string literals, not escape characters.
Note: Earlier versions of HP Vertica did not use standard conforming strings, and backslashes
were always considered escape sequences. To revert to this older behavior, set the
StandardConformingStrings parameter to '0', as described in Configuration Parameters in
the Administrator's Guide.

Examples
=> SELECT 'This is a string';
?column?
-----------------This is a string
(1 row)
=> SELECT 'This \is a string';
WARNING: nonstandard use of escape in a string literal at character 8
HINT: Use the escape string syntax for escapes, e.g., E'\r\n'.
?column?
-----------------This is a string
(1 row)
vmartdb=> SELECT E'This \is a string';
?column?
-----------------This is a string
=> SELECT E'This is a \n new line';
?column?
---------------------This is a
new line
(1 row)
=> SELECT 'String''s characters';
?column?
-------------------String's characters
(1 row)

See Also
l

SET STANDARD_CONFORMING_STRINGS

l

SET ESCAPE_STRING_WARNING

HP Vertica Analytic Database (7.0.x)

Page 55 of 1539

SQL Reference Manual
SQL Language Elements

l

Internationalization Parameters

l

Implement Locales for International Data Sets

Dollar-Quoted String Literals
Dollar-quoted string literals are rarely used, but are provided here for your convenience.
The standard syntax for specifying string literals can be difficult to understand. To allow more
readable queries in such situations, HP Vertica SQL provides dollar quoting. Dollar quoting is
not part of the SQL standard, but it is often a more convenient way to write complicated string
literals than the standard-compliant single quote syntax.

Syntax
$$characters$$

Parameters
characters

Arbitrary sequence of characters bounded by paired dollar signs ($$)

Dollar-quoted string content is treated as a literal. Single quote, backslash, and dollar sign
characters have no special meaning within a dollar-quoted string.

Notes
A dollar-quoted string that follows a keyword or identifier must be separated from the preceding
word by whitespace; otherwise, the dollar-quoting delimiter is taken as part of the preceding
identifier.

Examples
=> SELECT $$Fred's\n car$$;
?column?
------------------Fred's\n car
(1 row)
=> SELECT 'SELECT 'fact';';
ERROR: syntax error at or near "';'" at character 21
LINE 1: SELECT 'SELECT 'fact';';
=> SELECT 'SELECT $$fact';$$;
?column?
--------------SELECT $$fact

HP Vertica Analytic Database (7.0.x)

Page 56 of 1539

SQL Reference Manual
SQL Language Elements

(1 row)
=> SELECT 'SELECT ''fact'';';
?column?
---------------SELECT 'fact';
(1 row)

Unicode String Literals
Syntax
U&'characters' [ UESCAPE '' ]

Parameters
characters

Arbitrary sequence of UTF-8 characters bounded by single quotes (')

Unicode escape character

A single character from the source language character set other than
a hexit, plus sign (+), quote ('), double quote (''), or white space

Using Standard Conforming Strings
With StandardConformingStrings enabled, HP Vertica supports SQL standard Unicode
character string literals (the character set is UTF-8 only).
Before you enter a Unicode character string literal, enable standard conforming strings in one of the
following ways.
l

To enable for all sessions, update the StandardConformingStrings configuration parameter.
See Configuration Parameters in the Administrator's Guide.

l

To treat backslashes as escape characters for the current session, use the SET STANDARD_
CONFORMING_STRINGS statement.

See also Extended String Literals.

Examples
To enter a Unicode character in hexadecimal, such as the Russian phrase for "thank you, use the
following syntax:
=> SET STANDARD_CONFORMING_STRINGS TO ON;
=> SELECT U&'\0441\043F\0430\0441\0438\0431\043E' as 'thank you';
thank you

HP Vertica Analytic Database (7.0.x)

Page 57 of 1539

SQL Reference Manual
SQL Language Elements

----------спасибо
(1 row)

To enter the German word mude (where u is really u-umlaut) in hexadecimal:
=> SELECT U&'m\00fcde';
?column?
---------müde
(1 row)
=> SELECT 'ü';
?column?
---------ü
(1 row)

To enter the LINEAR B IDEOGRAM B240 WHEELED CHARIOT in hexadecimal:
=> SELECT E'\xF0\x90\x83\x8C';
?column?
---------(wheeled chariot character)
(1 row)

Note: Not all fonts support the wheeled chariot character.

See Also
l

SET STANDARD_CONFORMING_STRINGS

l

SET ESCAPE_STRING_WARNING

l

Internationalization Parameters

l

Implement Locales for International Data Sets

VARBINARY String Literals
VARBINARY string literals allow you to specify hexadecimal or binary digits in a string literal.

Syntax
X''B''

HP Vertica Analytic Database (7.0.x)

Page 58 of 1539

SQL Reference Manual
SQL Language Elements

Parameters
X

Specifies hexadecimal digits. The  string must be enclosed in single
quotes (').

B

Specifies binary digits. The  string must be enclosed in single quotes (').

Examples
=> SELECT X'abcd';
?column?
---------\253\315
(1 row)
=> SELECT B'101100';
?column?
---------,
(1 row)

Extended String Literals
Syntax
E'characters'

Parameters
characters

Arbitrary sequence of characters bounded by single quotes (')

You can use C-style backslash sequence in extended string literals, which are an extension to the
SQL standard. You specify an extended string literal by writing the letter E as a prefix (before the
opening single quote); for example:
E'extended character string\n'

Within an extended string, the backslash character (\) starts a C-style backslash sequence, in
which the combination of backslash and following character or numbers represent a special byte
value, as shown in the following list. Any other character following a backslash is taken literally; for
example, to include a backslash character, write two backslashes (\\).
l

\\ is a backslash

l

\b is a backspace

HP Vertica Analytic Database (7.0.x)

Page 59 of 1539

SQL Reference Manual
SQL Language Elements

l

\f is a form feed

l

\n is a newline

l

\r is a carriage return

l

\t is a tab

l

\x##,where ## is a 1 or 2-digit hexadecimal number; for example \x07 is a tab

l

\###, where ### is a 1, 2, or 3-digit octal number representing a byte with the corresponding
code.

When an extended string literal is concatenated across lines, write only E before the first opening
quote:
=> SELECT E'first part o'
->
'f a long line';
?column?
--------------------------first part of a long line
(1 row)

Two adjacent single quotes are used as one single quote:
=> SELECT 'Aren''t string literals fun?';
?column?
----------------------------Aren't string literals fun?
(1 row)

Standard Conforming Strings and Escape Characters
When interpreting commands, such as those entered in vsql or in queries passed via JDBC or
ODBC, HP Vertica uses standard conforming strings as specified in the SQL standard. In standard
conforming strings, backslashes are treated as string literals (ordinary characters), not escape
characters.
Note: Text read in from files or streams (such as the data inserted using the COPY statement)
are not treated as literal strings. The COPY command defines its own escape characters for
the data it reads. See the COPY statement documentation for details.
In HP Vertica databases prior to 4.0, the standard conforming strings was not on by default, and
backslashes were considered escape sequences. After 4.0, escape sequences, including
Windows path names, did not work as they had previously. For example, the TAB character '\t' is
two characters: '\' and 't'.
E'...' is the Extended character string literal format, so to treat backslashes as escape
characters, use E'\t'.

HP Vertica Analytic Database (7.0.x)

Page 60 of 1539

SQL Reference Manual
SQL Language Elements

The following options are available, but HP recommends that you migrate your application to use
standard conforming strings at your earliest convenience, after warnings have been addressed.
l

To revert to pre 4.0 behavior, set the StandardConformingStrings parameter to '0', as
described in Configuration Parameters in the Administrator's Guide.

l

To enable standard conforming strings permanently, set the StandardConformingStrings
parameter to '1', as described in the procedure in the section, "Identifying Strings that are not
Standard Conforming," below.

l

To enable standard conforming strings per session, use SET STANDARD_CONFORMING_
STRING TO ON, which treats backslashes as escape characters for the current session only.

The two sections that follow help you identify issues between HP Vertica 3.5 and 4.0.

Identifying Strings That Are Not Standard Conforming
The following procedure can be used to identify non-standard conforming strings in your application
so that you can convert them into standard conforming strings:
1. Be sure the StandardConformingStrings parameter is off, as described in
Internationalization Parameters in the Administrator's Guide.
=> SELECT SET_CONFIG_PARAMETER ('StandardConformingStrings' ,'0');

Note: HP recommends that you migrate your application to use Standard Conforming
Strings at your earliest convenience.
2. Turn on the EscapeStringWarning parameter. (ON is the default in HP Vertica Version 4.0 and
later.)
=> SELECT SET_CONFIG_PARAMETER ('EscapeStringWarning','1');

HP Vertica now returns a warning each time it encounters an escape string within a string
literal. For example, HP Vertica interprets the \n in the following example as a new line:
=> SELECT 'a\nb';
WARNING: nonstandard use of escape in a string literal at character 8
HINT: Use the escape string syntax for escapes, e.g., E'\r\n'.
?column?
---------a
b
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 61 of 1539

SQL Reference Manual
SQL Language Elements

When StandardConformingStrings is ON, the string is interpreted as four characters: a \ n
b.
Modify each string that HP Vertica flags by extending it as in the following example:
E'a\nb'

Or if the string has quoted single quotes, double them; for example, 'one'' double'.
3. Turn on the StandardConformingStrings parameter for all sessions:
SELECT SET_CONFIG_PARAMETER ('StandardConformingStrings' ,'1');

Doubled Single Quotes
This section discusses vsql inputs that are not passed on to the server.
HP Vertica recognizes two consecutive single quotes within a string literal as one single quote
character. For example, the following inputs, 'You''re here!' ignored the second consecutive
quote and returns the following:
=> SELECT 'You''re here!';
?column?
-------------You're here!
(1 row)

This is the SQL standard representation and is preferred over the form, 'You\'re here!', because
backslashes are not parsed as before. You need to escape the backslash:
=> SELECT (E'You\'re here!');
?column?
-------------You're here!
(1 row)

This behavior change introduces a potential incompatibility in the use of the vsql \set command,
which automatically concatenates its arguments. For example, the following works in both HP
Vertica 3.5 and 4.0:
\set file

'\''

`pwd`

'/file.txt'

'\''\echo :file

vsql takes the four arguments and outputs the following:
'/home/vertica/file.txt'

HP Vertica Analytic Database (7.0.x)

Page 62 of 1539

SQL Reference Manual
SQL Language Elements

In HP Vertica 3.5 the above \set file command could be written all with the arguments run
together, but in 4.0 the adjacent single quotes are now parsed differently:
\set file '\''`pwd`'/file.txt''\''\echo :file
'/home/vertica/file.txt''

Note the extra single quote at the end. This is due to the pair of adjacent single quotes together with
the backslash-quoted single quote.
The extra quote can be resolved either as in the first example above, or by combining the literals as
follows:
\set file '\''`pwd`'/file.txt'''\echo :file
'/home/vertica/file.txt'

In either case the backslash-quoted single quotes should be changed to doubled single quotes as
follows:
\set file '''' `pwd` '/file.txt'''

Additional Examples
=> SELECT 'This \is a string';
?column?
-----------------This \is a string
(1 row)
=> SELECT E'This \is a string';
?column?
-----------------This is a string
=> SELECT E'This is a \n new line';
?column?
---------------------This is a
new line
(1 row)
=> SELECT 'String''s characters';
?column?
-------------------String's characters
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 63 of 1539

SQL Reference Manual
SQL Language Elements

Date/Time Literals
Date or time literal input must be enclosed in single quotes. Input is accepted in almost any
reasonable format, including ISO 8601, SQL-compatible, traditional POSTGRES, and others.
HP Vertica is more flexible in handling date/time input than the SQL standard requires.The exact
parsing rules of date/time input and for the recognized text fields including months, days of the
week, and time zones are described in Date/Time Expressions.

Time Zone Values
HP Vertica attempts to be compatible with the SQL standard definitions for time zones. However,
the SQL standard has an odd mix of date and time types and capabilities. Obvious problems are:
l

Although the DATE type does not have an associated time zone, the TIME type can. Time
zones in the real world have little meaning unless associated with a date as well as a time, since
the offset can vary through the year with daylight-saving time boundaries.

l

HP Vertica assumes your local time zone for any data type containing only date or time.

l

The default time zone is specified as a constant numeric offset from UTC. It is therefore not
possible to adapt to daylight-saving time when doing date/time arithmetic across DST
boundaries.

To address these difficulties, HP recommends using Date/Time types that contain both date and
time when you use time zones. HP recommends that you do not use the type TIME WITH TIME
ZONE, even though it is supported it for legacy applications and for compliance with the SQL
standard.
Time zones and time-zone conventions are influenced by political decisions, not just earth
geometry. Time zones around the world became somewhat standardized during the 1900's, but
continue to be prone to arbitrary changes, particularly with respect to daylight-savings rules.
HP Vertica 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 in which
they occur.
Example Description
PST

Pacific Standard Time

-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

HP Vertica Analytic Database (7.0.x)

Page 64 of 1539

SQL Reference Manual
SQL Language Elements

Day of the Week Names
The following tokens are recognized as names of days of the week:
Day

Abbreviations

SUNDAY

SUN

MONDAY

MON

TUESDAY

TUE, TUES

WEDNESDAY WED, WEDS
THURSDAY

THU, THUR, THURS

FRIDAY

FRI

SATURDAY

SAT

Month Names
The following tokens are recognized as names of months:
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

HP Vertica Analytic Database (7.0.x)

Page 65 of 1539

SQL Reference Manual
SQL Language Elements

Interval Values
An interval value represents the duration between two points in time.

Syntax
[ @ ] quantity unit [ quantity unit... ] [ AGO ]

Parameters
@

(at sign) is optional and ignored

quantity

Is an integer numeric constant

unit

Is one of the following units or abbreviations or plurals of the following units:
MILLISECONDSECOND
MINUTE
HOUR

AGO

DAYWEEK
MONTH
YEAR

DECADECENTURY
MILLENNIUM

[Optional] specifies a negative interval value (an interval going back in time). 'AGO' is
a synonym for '-'.

The amounts of different units are implicitly added up with appropriate sign accounting.

Notes
l

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'

l

l

l

The boundaries of an interval constant are:
n

'9223372036854775807 usec' to '9223372036854775807 usec ago'

n

296533 years 3 mons 21 days 04:00:54.775807 to -296533 years -3 mons -21 days 04:00:54.775807

The range of an interval constant is +/– 263 – 1 (plus or minus two to the sixty-third minus one)
microseconds.
In HP Vertica, the interval fields are additive and accept large floating-point numbers.

HP Vertica Analytic Database (7.0.x)

Page 66 of 1539

SQL Reference Manual
SQL Language Elements

Examples
=> SELECT INTERVAL '1 12:59:10';
?column?
-----------1 12:59:10
(1 row)
=> SELECT INTERVAL '9223372036854775807 usec';
?column?
--------------------------106751991 04:00:54.775807
(1 row)
=> SELECT INTERVAL '-9223372036854775807 usec';
?column?
----------------------------106751991 04:00:54.775807
(1 row)
=> SELECT INTERVAL '-1 day 48.5 hours';
?column?
----------3 00:30
(1 row)
=> SELECT TIMESTAMP 'Apr 1, 07' - TIMESTAMP 'Mar 1, 07';
?column?
---------31
(1 row)
=> SELECT TIMESTAMP 'Mar 1, 07' - TIMESTAMP 'Feb 1, 07';
?column?
---------28
(1 row)
=> SELECT TIMESTAMP 'Feb 1, 07' + INTERVAL '29 days';
?column?
--------------------03/02/2007 00:00:00
(1 row)
=> SELECT TIMESTAMP WITHOUT TIME ZONE '1999-10-01 00:00:01' +
INTERVAL '1 month - 1 second' AS "Oct 31";
Oct 31
--------------------1999-10-31 00:00:00
(1 row)

Interval-Literal
The following table lists the units allowed for the required interval-literal parameter.

HP Vertica Analytic Database (7.0.x)

Page 67 of 1539

SQL Reference Manual
SQL Language Elements

Unit

Description

a

Julian year, 365.25 days exactly

ago

Indicates negative time offset

c, cent, century

Century

centuries

Centuries

d, day

Day

days

Days

dec, decade

Decade

decades, decs

Decades

h, hour, hr

Hour

hours, hrs

Hours

ka

Julian kilo-year, 365250 days exactly

m

Minute or month for year/month, depending on context. See
Notes below this table.

microsecond

Microsecond

microseconds

Microseconds

mil, millennium

Millennium

millennia, mils

Millennia

millisecond

Millisecond

milliseconds

Milliseconds

min, minute, mm

Minute

mins, minutes

Minutes

mon, month

Month

mons, months

Months

ms, msec, millisecond

Millisecond

mseconds, msecs

Milliseconds

q, qtr, quarter

Quarter

qtrs, quarters

Quarters

HP Vertica Analytic Database (7.0.x)

Page 68 of 1539

SQL Reference Manual
SQL Language Elements

Unit

Description

s, sec, second

Second

seconds, secs

Seconds

us, usec

Microsecond

microseconds, useconds, usecs

Microseconds

w, week

Week

weeks

Weeks

y, year, yr

Year

years, yrs

Years

Processing the Input Unit 'm'
The input unit 'm' can represent either 'months' or 'minutes,' depending on the context. For
instance, the following command creates a one-column table with an interval value:
=> CREATE TABLE int_test(i INTERVAL YEAR TO MONTH);

In the first INSERT statement, the values are inserted as 1 year, six months:
=> INSERT INTO int_test VALUES('1 year 6 months');

The second INSERT statement results in an error from specifying minutes for a YEAR TO MONTH
interval. At runtime, the result will be a NULL:
=> INSERT INTO int_test VALUES('1 year 6 minutes');
ERROR: invalid input syntax for type interval year to month: "1 year 6 minutes"

In the third INSERT statement, the 'm' is processed as months (not minutes), because DAY TO
SECOND is truncated:
=> INSERT INTO int_test VALUES('1 year 6 m');
-- the m counts as months

The table now contains two identical values, with no minutes:
=> SELECT * FROM int_test;
i
----1 year 6 months
1 year 6 months
(2 rows)

HP Vertica Analytic Database (7.0.x)

Page 69 of 1539

SQL Reference Manual
SQL Language Elements

In the following command, the 'm' counts as minutes, because the DAY TO SECOND interval-qualifier
extracts day/time values from the input:
=> SELECT INTERVAL '1y6m' DAY TO SECOND;
?column?
----------365 days 6 mins
(1 row)

Interval-Qualifier
The following table lists the optional interval qualifiers. Values in INTERVAL fields, other than
SECOND, are integers with a default precision of 2 when they are not the first field.
You cannot combine day/time and year/month qualifiers. For example, the following intervals are
not allowed:
l

DAY TO YEAR

l

HOUR TO MONTH

Interval
Type
Day/time
intervals

Units

Valid interval-literal entries

DAY

Unconstrained.

DAY TO HOUR

An interval that represents a span of days and hours.

DAY TO MINUTE

An interval that represents a span of days and minutes.

DAY TO SECOND

(Default) interval that represents a span of days, hours,
minutes, seconds, and fractions of a second if subtype
unspecified.

HOUR

Hours within days.

HOUR TO MINUTE

An interval that represents a span of hours and minutes.

HOUR TO SECOND

An interval that represents a span of hours and seconds.

MINUTE

Minutes within hours.

MINUTE TO SECOND

An interval that represents a span of minutes and seconds.

HP Vertica Analytic Database (7.0.x)

Page 70 of 1539

SQL Reference Manual
SQL Language Elements

Interval
Type

Units

Valid interval-literal entries

SECOND

Seconds within minutes.
Note: The SECOND field can have an interval fractional seconds
precision, which indicates the number of decimal digits
maintained following the decimal point in the SECONDS value.
When SECOND is not the first field, it has a precision of 2 places
before the decimal point.

Year/month MONTH
intervals

Months within year.

YEAR

Unconstrained.

YEAR TO MONTH

An interval that represents a span of years and months.

HP Vertica Analytic Database (7.0.x)

Page 71 of 1539

SQL Reference Manual
SQL Language Elements

Operators
Operators are logical, mathematical, and equality symbols used in SQL to evaluate, compare, or
calculate values.

Binary Operators
Each of the functions in the following table works with BINARY and VARBINARY data types.
Operator Function

Description

'='

binary_eq

Equal to

'<>'

binary_ne

Not equal to

'<'

binary_lt

Less than

'<='

binary_le

Less than or equal to

'>'

binary_gt

Greater than

binary_ge

Greater than or equal to

'&'

binary_and

And

'~'

binary_not

Not

'|'

binary_or

Or

'#'

binary_xor

Either or

'||'

binary_cat

Concatenate

'>='

Notes
l

If the arguments vary in length binary operators treat the values as though they are all equal in
length by right-extending the smaller values with the zero byte to the full width of the column
(except when using the binary_cat function). For example, given the values 'ff' and 'f', the
value 'f' is treated as 'f0'.

l

Operators are strict with respect to nulls. The result is null if any argument is null. For example,
null <> 'a'::binary returns null.

l

To apply the OR ('|') operator to a VARBINARY type, explicitly cast the arguments; for
example:
=> SELECT '1'::VARBINARY | '2'::VARBINARY;
?column?

HP Vertica Analytic Database (7.0.x)

Page 72 of 1539

SQL Reference Manual
SQL Language Elements

---------3
(1 row)

Similarly, to apply the LENGTH, REPEAT, TO_HEX, and SUBSTRING functions to a BINARY
type, explicitly cast the argument; for example:
=> SELECT LENGTH('\\001\\002\\003\\004'::varbinary(4));
LENGTH
-------4
(1 row)

When applying an operator or function to a column, the operator's or function's argument type is
derived from the column type.

Examples
In the following example, the zero byte is not removed from column cat1 when values are
concatenated:
=> SELECT 'ab'::BINARY(3) || 'cd'::BINARY(2) AS cat1,
'ab'::VARBINARY(3) ||
'cd'::VARBINARY(2) AS cat2;
cat1
| cat2
----------+-----ab\000cd | abcd
(1 row)

When the binary value 'ab'::binary(3) is translated to varbinary, the result is equivalent to
'ab\\000'::varbinary(3); for example:
=> SELECT 'ab'::binary(3); binary
-------ab\000
(1 row)

The following example performs a bitwise AND operation on the two input values (see also BIT_
AND):
=> SELECT '10001' & '011' as AND;
AND
----1
(1 row)

The following example performs a bitwise OR operation on the two input values (see also BIT_OR):

HP Vertica Analytic Database (7.0.x)

Page 73 of 1539

SQL Reference Manual
SQL Language Elements

=> SELECT '10001' | '011' as OR;
OR
------10011
(1 row)

The following example concatenates the two input values:
=> SELECT '10001' || '011' as CAT;
CAT
---------10001011
(1 row)

Boolean Operators
Syntax
[ AND | OR | NOT ]

Parameters
SQL uses a three-valued Boolean logic where the null value represents "unknown."
a

b

a AND b a OR b

TRUE

TRUE

TRUE

TRUE

FALSE FALSE

TRUE

TRUE

NULL

TRUE

NULL

TRUE

FALSE FALSE FALSE

FALSE

FALSE NULL

FALSE

NULL

NULL

NULL

NULL

NULL

a

NOT a

TRUE

FALSE

FALSE TRUE
NULL

NULL

HP Vertica Analytic Database (7.0.x)

Page 74 of 1539

SQL Reference Manual
SQL Language Elements

Notes
l

The operators AND and OR are commutative, that is, you can switch the left and right operand
without affecting the result. However, the order of evaluation of subexpressions is not defined.
When it is essential to force evaluation order, use a CASE construct.

l

Do not confuse Boolean operators with the Boolean-Predicate or the Boolean data type, which
can have only two values: true and false.

Comparison Operators
Comparison operators are available for all data types where comparison makes sense. All
comparison operators are binary operators that return values of True, False, or NULL.

Syntax and Parameters
<

less than

>

greater than

<=

less than or equal to

>=

greater than or equal to

= or <=>

equal

<> or !=

not equal

Notes
l

The != operator is converted to <> in the parser stage. It is not possible to implement != and <>
operators that do different things.

l

The comparison operators return NULL (signifying "unknown") when either operand is null.

l

The <=> operator performs an equality comparison like the = operator, but it returns true, instead
of NULL, if both operands are NULL, and false, instead of NULL, if one operand is NULL.

Data Type Coercion Operators (CAST)
Data type coercion (casting) passes an expression value to an input conversion routine for a
specified data type, resulting in a constant of the indicated type.

Syntax
SELECT CAST ( expression AS data_type )
SELECT expression::data_type

HP Vertica Analytic Database (7.0.x)

Page 75 of 1539

SQL Reference Manual
SQL Language Elements

SELECT data_type 'string'

Parameters
expression

An expression of any type

data_type

Converts the value of expression to one of the following data types:
BINARY
BOOLEAN
CHARACTER
DATE/TIME
NUMERIC

Notes
l

In HP Vertica, data type coercion (casting) can be invoked by an explicit cast request. It must
use one of the following constructs:
=> SELECT CAST ( expression AS data_type )
=> SELECT expression::data_type
=> SELECT data_type 'string'

l

The explicit type cast can be omitted if there is no ambiguity as to the type the constant must be.
For example, when a constant is assigned directly to a column, it is automatically coerced to the
column's data type.

l

If a binary value is cast (implicitly or explicitly) to a binary type with a smaller length, the value is
silently truncated. For example:
=> SELECT 'abcd'::BINARY(2);
?column?
---------ab
(1 row)

l

Similarly, if a character value is cast (implicitly or explicitly) to a character value with a smaller
length, the value is silently truncated. For example:
=> SELECT 'abcd'::CHAR(3);

HP Vertica Analytic Database (7.0.x)

Page 76 of 1539

SQL Reference Manual
SQL Language Elements

?column?
---------abc

l

l

HP Vertica supports only casts and resize operations as follows:
n

BINARY to and from VARBINARY

n

VARBINARY to and from LONG VARBINARY

n

BINARY to and from LONG VARBINARY

On binary data that contains a value with fewer bytes than the target column, values are rightextended with the zero byte '\0' to the full width of the column. Trailing zeros on variable-length
binary values are not right-extended:
=> SELECT 'ab'::BINARY(4), 'ab'::VARBINARY(4), 'ab'::LONG VARBINARY(4);
?column? | ?column? | ?column?
------------+----------+---------ab\000\000 | ab
| ab
(1 row)

Examples
=> SELECT CAST((2 + 2) AS VARCHAR);
?column?
---------4
(1 row)
=> SELECT (2 + 2)::VARCHAR;
?column?
---------4
(1 row)
=> SELECT INTEGER '123';
?column?
---------123
(1 row)
=> SELECT (2 + 2)::LONG VARCHAR
?column?
---------4
(1 row)
=> SELECT '2.2' + 2;
ERROR: invalid input syntax for integer: "2.2"

HP Vertica Analytic Database (7.0.x)

Page 77 of 1539

SQL Reference Manual
SQL Language Elements

=> SELECT FLOAT '2.2' + 2;
?column?
---------4.2
(1 row)

See Also
l

Data Type Conversions

l

Data Type Coercion Chart

Date/Time Operators
Syntax
[ + | – | * | / ]

Parameters
+
–
*
/

Addition
Subtraction
Multiplication
Division

Notes
l

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

l

The + and * operators come in commutative pairs (for example both DATE + INTEGER and
INTEGER + DATE); only one of each such pair is shown.

Example

Result Type

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'

HP Vertica Analytic Database (7.0.x)

Page 78 of 1539

SQL Reference Manual
SQL Language Elements

Example

Result Type

Result

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

INTERVAL '1 HOUR' /
DOUBLE PRECISION '1.5'

INTERVAL

INTERVAL

'00:40:00'

Mathematical Operators
Mathematical operators are provided for many data types.
Operator Description

Example

Result

!

Factorial

5 !

120

+

Addition

2 + 3

5

–

Subtraction

2 – 3

–1

*

Multiplication

2 * 3

6

/

Division (integer division produces NUMERIC results).

4 / 2

2.00...

HP Vertica Analytic Database (7.0.x)

Page 79 of 1539

SQL Reference Manual
SQL Language Elements

Operator Description

Example

Result

//

With integer division, returns an INTEGER rather than a
NUMERIC.

117.32 // 2.5

46

%

Modulo (remainder)

5 % 4

1

^

Exponentiation

2.0 ^ 3.0

8

|/

Square root

|/ 25.0

5

||/

Cube root

||/ 27.0

3

!!

Factorial (prefix operator)

!! 5

120

@

Absolute value

@ -5.0

5

&

Bitwise AND

91 & 15

11

|

Bitwise OR

32 | 3

35

#

Bitwise XOR

17 # 5

20

~

Bitwise NOT

~1

-2

<<

Bitwise shift left

1 << 4

16

>>

Bitwise shift right

8 >> 2

2

Notes
l

The bitwise operators work only on integer data types, whereas the others are available for all
numeric data types.

l

HP Vertica supports the use of the factorial operators on positive and negative floating point
(DOUBLE PRECISION) numbers as well as integers. For example:
=> SELECT 4.98!;
?column?
-----------------115.978600750905
(1 row)

l

Factorial is defined in term of the gamma function, where (-1) = Infinity and the other negative
integers are undefined. For example:
(–4)! = NaN
–! = –(4!) = –24

HP Vertica Analytic Database (7.0.x)

Page 80 of 1539

SQL Reference Manual
SQL Language Elements

l

Factorial is defined as z! = gamma(z+1) for all complex numbers z. See the Handbook of
Mathematical Functions (1964) Section 6.1.5.

l

See MOD() for details about the behavior of %.

NULL Operators
To check whether a value is or is not NULL, use the constructs:
expression IS NULL expression IS NOT NULL

Alternatively, use equivalent, but nonstandard, constructs:
expression ISNULL expression NOTNULL

Do not write expression = NULL because NULL represents an unknown value, and two unknown
values are not necessarily equal. This behavior conforms to the SQL standard.
Note: Some applications might expect that expression = NULL returns true if expression
evaluates to null. HP Vertica strongly recommends that these applications be modified to
comply with the SQL standard.

String Concatenation Operators
To concatenate two strings on a single line, use the concatenation operator (two consecutive
vertical bars).

Syntax
string || string

Parameters
string

Is an expression of type CHAR or VARCHAR

Notes
l

|| is used to concatenate expressions and constants. The expressions are cast to VARCHAR if
possible, otherwise to VARBINARY, and must both be one or the other.

l

Two consecutive strings within a single SQL statement on separate lines are automatically
concatenated

HP Vertica Analytic Database (7.0.x)

Page 81 of 1539

SQL Reference Manual
SQL Language Elements

Examples
The following example is a single string written on two lines:
=> SELECT E'xx'-> '\\';
?column?
---------xx\
(1 row)

The following examples show two strings concatenated:
=> SELECT E'xx' ||-> '\\';
?column?
---------xx\\
(1 row)
=> SELECT 'auto' || 'mobile';
?column?
---------automobile
(1 row)
=> SELECT 'auto'-> 'mobile';
?column?
---------automobile
(1 row)
=> SELECT 1 || 2;
?column?
---------12
(1 row)
=> SELECT '1' || '2';
?column?
---------12
(1 row)=> SELECT '1'-> '2';
?column?
---------12
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 82 of 1539

SQL Reference Manual
SQL Language Elements

Expressions
SQL expressions are the components of a query that compare a value or values against other
values. They can also perform calculations. Expressions found inside any SQL command are
usually in the form of a conditional statement.

Operator Precedence
The following table shows operator precedence in decreasing (high to low) order.
Note: When an expression includes more than one operator, HP recommends that you specify
the order of operation using parentheses, rather than relying on operator precedence.
Operator/Element Associativity Description
.

left

table/column name separator

::

left

typecast

[ ]

left

array element selection

-

right

unary minus

^

left

exponentiation

* / %

left

multiplication, division, modulo

+ -

left

addition, subtraction

IS

IS TRUE, IS FALSE, IS UNKNOWN, IS NULL

IN

set membership

BETWEEN

range containment

OVERLAPS

time interval overlap

LIKE

string pattern matching

< >

less than, greater than

=

right

equality, assignment

NOT

right

logical negation

AND

left

logical conjunction

OR

left

logical disjunction

HP Vertica Analytic Database (7.0.x)

Page 83 of 1539

SQL Reference Manual
SQL Language Elements

Expression Evaluation Rules
The order of evaluation of subexpressions is not defined. In particular, the inputs of an operator or
function are not necessarily evaluated left-to-right or in any other fixed order. To force evaluation in
a specific order, use a CASE construct. For example, this is an untrustworthy way of trying to avoid
division by zero in a WHERE clause:
=> SELECT x, y WHERE x <> 0 AND y/x > 1.5;

But this is safe:
=> SELECT x, y
WHERE
CASE
WHEN x <> 0 THEN y/x > 1.5
ELSE false
END;

A CASE construct used in this fashion defeats optimization attempts, so use it only when
necessary. (In this particular example, it would be best to avoid the issue by writing y > 1.5*x
instead.)

Aggregate Expressions
An aggregate expression represents the application of an aggregate function across the rows or
groups of rows selected by a query.
Using AVG() as an example, the syntax of an aggregate expression is one of the following:
l

Invokes the aggregate across all input rows for which the given expression yields a non-null
value:
AVG (expression)

l

Is the same as AVG(expression), because ALL is the default:
AVG (ALL expression)

l

Invokes the AVG() function across all input rows for all distinct, non-null values of the
expression, where expression is any value expression that does not itself contain an aggregate
expression.
AVG (DISTINCT expression)

HP Vertica Analytic Database (7.0.x)

Page 84 of 1539

SQL Reference Manual
SQL Language Elements

An aggregate expression only can appear in the select list or HAVING clause of a SELECT statement.
It is forbidden in other clauses, such as WHERE, because those clauses are evaluated before the
results of aggregates are formed.

CASE Expressions
The CASE expression is a generic conditional expression that can be used wherever an expression
is valid. It is similar to case and if/then/else statements in other languages.

Syntax (form 1)
CASE
WHEN condition THEN result
[ WHEN condition THEN result ]
...
[ ELSE result ]
END

Parameters
condition

Is an expression that returns a boolean (true/false) result. If the result is false,
subsequent WHEN clauses are evaluated in the same manner.

result

Specifies the value to return when the associated condition is true.

ELSE result

If no 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.

Syntax (form 2)
CASE expression
WHEN value THEN result
[ WHEN value THEN result ]
...
[ ELSE result ]
END

Parameters
expression

An expression that is evaluated and compared to all the value specifications in the
WHEN clauses until one is found that is equal.

value

Specifies a value to compare to the expression.

result

Specifies the value to return when the expression is equal to the specified value.

ELSE result

Specifies the value to return when the expression is not equal to any value; if no
ELSE clause is specified, the value returned is null.

HP Vertica Analytic Database (7.0.x)

Page 85 of 1539

SQL Reference Manual
SQL Language Elements

Notes
The data types of all the result expressions must be convertible to a single output type.

Examples
The following examples show two uses of the CASE statement.
=> SELECT * FROM test;
a
--1
2
3
=> SELECT a,
CASE WHEN a=1 THEN 'one'
WHEN a=2 THEN 'two'
ELSE 'other'
END
FROM test;
a | case
---+------1 | one
2 | two
3 | other
=> 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

Special Example
A CASE expression does not evaluate subexpressions that are not needed to determine the result.
You can use this behavior to avoid division-by-zero errors:
=> SELECT x FROM T1 WHERE
CASE WHEN x <> 0 THEN y/x > 1.5
ELSE false
END;

HP Vertica Analytic Database (7.0.x)

Page 86 of 1539

SQL Reference Manual
SQL Language Elements

Column References
Syntax
[ [ [db-name.]schema. ] tablename. ] columnname

Parameters
[ [db-name.]schema. ]

[Optional] Specifies the database name and optional schema name.
Using a database name identifies objects that are not unique within the
current search path (see Setting Search Paths). You must be connected
to the database you specify, and you cannot change objects in other
databases.
Specifying different database objects lets you qualify database objects
as explicitly as required. For example, you can use a database and a
schema name (mydb.myschema).

tablename.

columnname

Is one of:
l

The name of a table

l

An alias for a table defined by means of a FROM clause in a query

Is the name of a column that must be unique across all the tables being
used in a query

Notes
There are no space characters in a column reference.
If you do not specify a schema, HP Vertica searches the existing schemas according to the order
defined in the SET SEARCH_PATH command.

Example
This example uses the schema from the VMart database. See Introducing the VMart Example
Database.
In the following command, transaction_type and transaction_time are the unique column
references, store is the name of the schema, and store_sales_fact is the table name:
=> SELECT transaction_type, transaction_time
FROM store.store_sales_fact
ORDER BY transaction_time;
transaction_type | transaction_time
------------------+------------------

HP Vertica Analytic Database (7.0.x)

Page 87 of 1539

SQL Reference Manual
SQL Language Elements

purchase
purchase
purchase
purchase
purchase
purchase
purchase
return
return
purchase
purchase
purchase
purchase
purchase
purchase
purchase
purchase
purchase
return
purchase
(20 rows)

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

00:00:23
00:00:32
00:00:54
00:00:54
00:01:15
00:01:30
00:01:50
00:03:34
00:03:35
00:03:39
00:05:13
00:05:20
00:05:23
00:05:27
00:05:30
00:05:35
00:05:35
00:05:42
00:06:36
00:06:39

Comments
A comment is an arbitrary sequence of characters beginning with two consecutive hyphen
characters and extending to the end of the line. For example:
-- This is a standard SQL comment

A comment is removed from the input stream before further syntax analysis and is effectively
replaced by white space.
Alternatively, C-style block comments can be used where the comment begins with /* and extends
to the matching occurrence of */.
/* multiline comment
* with nesting: /* nested block comment */
*/

These block comments nest, as specified in the SQL standard. Unlike C, you can comment out
larger blocks of code that might contain existing block comments.

Date/Time Expressions
HP Vertica 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 might 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.
The date/time type inputs are decoded using the following procedure.

HP Vertica Analytic Database (7.0.x)

Page 88 of 1539

SQL Reference Manual
SQL Language Elements

l

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

l

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

l

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

l

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

l

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

l

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

l

Do a binary-search table lookup for the token as either a special string (for example, today), day
(for example, Thursday), month (for example, January), or noise word (for example, at, on).

l

Set field values and bit mask for fields. For example, set year, month, day for today, and
additionally hour, minute, second for now.

l

If not found, do a similar binary-search table lookup to match the token with a time zone.

l

If still not found, throw an error.

l

When the token is a number or number field:

l

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

l

If the token is three digits and a year has already been read, then interpret as day of year.

l

If four or six digits and a year has already been read, then interpret as a time (HHMM or HHMMSS).

l

If three or more digits and no date fields have yet been found, interpret as a year (this forces yymm-dd ordering of the remaining date fields).

l

Otherwise the date field ordering is assumed to follow the DateStyle setting: mm-dd-yy, ddmm-yy, or yy-mm-dd. Throw an error if a month or day field is found to be out of range.

l

If BC has been specified, negate the year and add one for internal storage. (There is no year zero
in the our implementation, so numerically 1 BC becomes year zero.)

l

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 can be entered by using 4 digits with leading zeros (for example,

HP Vertica Analytic Database (7.0.x)

Page 89 of 1539

SQL Reference Manual
SQL Language Elements

0099 is AD 99).

Month Day Year Ordering
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.

Special Date/Time Values
HP Vertica supports several special date/time values for convenience, as shown below. All of
these values need to be written in single quotes when used as constants in SQL statements.
The values INFINITY and -INFINITY are specially represented inside the system and are displayed
the same way. The others are simply notational shorthands that are converted to ordinary date/time
values when read. (In particular, NOW and related strings are converted to a specific time value as
soon as they are read.)
String

Valid Data Types

Description

epoch

DATE, TIMESTAMP

1970-01-01 00:00:00+00 (UNIX SYSTEM TIME ZERO)

INFINITY

TIMESTAMP

Later than all other time stamps

-INFINITY

TIMESTAMP

Earlier than all other time stamps

NOW

DATE, TIME, TIMESTAMP

Current transaction's start time
Note: NOW is not the same as the NOW function.

TODAY

DATE, TIMESTAMP

Midnight today

TOMORROW

DATE, TIMESTAMP

Midnight tomorrow

YESTERDAY

DATE, TIMESTAMP

Midnight yesterday

ALLBALLS

TIME

00:00:00.00 UTC

The following SQL-compatible functions can also be used to obtain the current time value for the
corresponding data type:
l

CURRENT_DATE

l

CURRENT_TIME

l

CURRENT_TIMESTAMP

l

LOCALTIME

l

LOCALTIMESTAMP

HP Vertica Analytic Database (7.0.x)

Page 90 of 1539

SQL Reference Manual
SQL Language Elements

The latter four accept an optional precision specification. (See Date/Time Functions.) However,
these functions are SQL functions and are not recognized as data input strings.

NULL Value
NULL is a reserved keyword used to indicate that a data value is unknown.
Be very careful when using NULL in expressions. NULL is not greater than, less than, equal to, or not
equal to any other expression. Use the Boolean-Predicate for determining whether an expression
value is NULL.

Notes
l

HP Vertica stores data in projections, which are sorted in a specific way. All columns are
stored in ASC (ascending) order. For columns of data type NUMERIC, INTEGER, DATE, TIME,
TIMESTAMP, and INTERVAL, NULL values are placed at the beginning of sorted projections (NULLS
FIRST), while for columns of data type FLOAT, STRING, and BOOLEAN, NULL values are placed at
the end (NULLS LAST). For details, see Analytics Null Placement and Minimizing Sort
Operations in the Programmer's Guide.

l

HP Vertica also accepts NUL characters ('\0') in constant strings and no longer removes null
characters from VARCHAR fields on input or output. NUL is the ASCII abbreviation for the NULL
character.

l

You can write queries with expressions that contain the <=> operator for NULL=NULL joins. See
Equi-joins and Non Equi-Joins in the Programmer's Guide.

See Also
l

NULL-handling Functions

Numeric Expressions
HP Vertica follows the IEEE specification for floating point, including NaN.
A NaN is not greater than and at the same time not less than anything, even itself. In other words,
comparisons always return false whenever a NaN is involved.

Examples
=> SELECT CBRT('Nan'); -- cube root
CBRT
-----NaN
(1 row)
=> SELECT 'Nan' > 1.0;
?column?

HP Vertica Analytic Database (7.0.x)

Page 91 of 1539

SQL Reference Manual
SQL Language Elements

---------f
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 92 of 1539

SQL Reference Manual
SQL Language Elements

Predicates
Predicates are truth-tests. If the predicate test is true, it returns a value. Each predicate is
evaluated per row, so that when the predicate is part of an entire table SELECT statement, the
statement can return multiple results.
Predicates consist of a set of parameters and arguments. For example, in the following example
WHERE clause:
WHERE name = 'Smith';
l

name = 'Smith' is the predicate

l

'Smith' is an expression

BETWEEN-predicate
The special BETWEEN predicate is available as a convenience.

Syntax
a BETWEEN x AND y

Notes
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

Boolean-Predicate
Retrieves rows where the value of an expression is true, false, or unknown (null).

HP Vertica Analytic Database (7.0.x)

Page 93 of 1539

SQL Reference Manual
SQL Language Elements

Syntax
expression IS [NOT] TRUE
expression IS [NOT] FALSE
expression IS [NOT] UNKNOWN

Notes
l

A null input is treated as the value UNKNOWN.

l

IS UNKNOWN and IS NOT UNKNOWN are effectively the same as the NULL-predicate, except that
the input expression does not have to be a single column value. To check a single column value
for NULL, use the NULL-predicate.

l

Do not confuse the boolean-predicate with Boolean Operators or the Boolean data type, which
can have only two values: true and false.

Column-Value-Predicate
Syntax
column-name comparison-op constant-expression

Parameters
column-name

A single column of one the tables specified in the FROM Clause.

comparison-op

A Comparison Operators.

constant-expression

A constant value of the same data type as the column-name.

Notes
To check a column value for NULL, use the NULL-predicate.

Examples
table.column1 = 2
table.column2 = 'Seafood'
table.column3 IS NULL

HP Vertica Analytic Database (7.0.x)

Page 94 of 1539

SQL Reference Manual
SQL Language Elements

IN-predicate
Syntax
column-expression [ NOT ] IN ( list-expression )

Parameters
column-expression

One or more columns from the tables specified in the FROM Clause.

list-expression

Comma-separated list of constant values matching the data type of the
column-expression

Examples
x, y IN ((1,2), (3, 4)), OR x, y IN
(SELECT a, b FROM table)x IN (5, 6, 7)

INTERPOLATE
Used to join two event series together using some ordered attribute, event series joins let you
compare values from two series directly, rather than having to normalize the series to the same
measurement interval.

Syntax
expression1 INTERPOLATE PREVIOUS VALUE expression2

Parameters
expression1expression2

olumn-reference from one the tables specified in the FROM Clause.
The column-reference can be any data type, but DATE/TIME types are
the most useful, especially TIMESTAMP,since you are joining data
that represents an event series.

PREVIOUS VALUE

Pads the non-preserved side with the previous values from relation
when there is no match.
Input rows are sorted in ascending logical order of the join column.
Note: An ORDER BY clause, if used, does not determine the input
order but only determines query output order.

HP Vertica Analytic Database (7.0.x)

Page 95 of 1539

SQL Reference Manual
SQL Language Elements

Notes
l

An event series join is an extension of a regular outer join. Instead of padding the non-preserved
side with null values when there is no match, the event series join pads the non-preserved side
with the previous values from the table.

l

The difference between expressing a regular outer join and an event series join is the
INTERPOLATE predicate, which is used in the ON clause. See the Examples section below
Notes and Restrictions. See also Event Series Joins in the Programmer's Guide.

l

Data is logically partitioned on the table in which it resides, based on other ON clause equality
predicates.

l

Interpolated values come from the table that contains the null, not from the other table.

l

HP Vertica does not guarantee that there will be no null values in the output. If there is no
previous value for a mismatched row, that row will be padded with nulls.

l

Event series join requires that both tables be sorted on columns in equality predicates, in any
order, followed by the INTERPOLATED column. If data is already sorted in this order, then an
explicit sort is avoided, which can improve query performance. For example, given the following
tables:
ask: exchange, stock, ts, pricebid: exchange,
stock, ts, price

In the query that follows
n

ask is sorted on exchange, stock (or the reverse), ts

n

bid is sorted on exchange, stock (or the reverse), ts
SELECT ask.price - bid.price, ask.ts, ask.stock, ask.exchange
FROM ask FULL OUTER JOIN bid
ON ask.stock = bid.stock AND ask.exchange =
bid.exchange AND ask.ts INTERPOLATE PREVIOUS
VALUE bid.ts;

Restrictions
l

Only one INTERPOLATE expression is allowed per join.

l

INTERPOLATE expressions are used only with ANSI SQL-99 syntax (the ON clause), which is
already true for full outer joins.

l

INTERPOLATE can be used with equality predicates only.

HP Vertica Analytic Database (7.0.x)

Page 96 of 1539

SQL Reference Manual
SQL Language Elements

l

The AND operator is supported but not the OR and NOT operators.

l

Expressions and implicit or explicit casts are not supported, but subqueries are allowed.

Example
The examples that follow use this simple schema.
CREATE TABLE t(x TIME);
CREATE TABLE t1(y TIME);
INSERT INTO t VALUES('12:40:23');
INSERT INTO t VALUES('14:40:25');
INSERT INTO t VALUES('14:45:00');
INSERT INTO t VALUES('14:49:55');
INSERT INTO t1 VALUES('12:40:23');
INSERT INTO t1 VALUES('14:00:00');
COMMIT;

Normal Full Outer Join
=> SELECT * FROM t FULL OUTER JOIN t1 ON t.x = t1.y;

Notice the null rows from the non-preserved table:
x
|
y
----------+---------12:40:23 | 12:40:23
14:40:25 |
14:45:00 |
14:49:55 |
| 14:00:00
(5 rows)

Full Outer Join with Interpolation
=> SELECT * FROM t FULL OUTER JOIN t1 ON t.x INTERPOLATE
PREVIOUS VALUE t1.y;

In this case, the rows with no entry point are padded with values from the previous row.
x
|
y
----------+---------12:40:23 | 12:40:23
12:40:23 | 14:00:00
14:40:25 | 14:00:00
14:45:00 | 14:00:00
14:49:55 | 14:00:00

HP Vertica Analytic Database (7.0.x)

Page 97 of 1539

SQL Reference Manual
SQL Language Elements

(5 rows)

Normal Left Outer Join
=> SELECT * FROM t LEFT OUTER JOIN t1 ON t.x = t1.y;

Again, there are nulls in the non-preserved table
x
|
y
----------+---------12:40:23 | 12:40:23
14:40:25 |
14:45:00 |
14:49:55 |
(4 rows)

Left Outer Join with Interpolation
=> SELECT * FROM t LEFT OUTER JOIN t1 ON t.x INTERPOLATE
PREVIOUS VALUE t1.y;

Nulls padded with interpolated values.
x
|
y
----------+---------12:40:23 | 12:40:23
14:40:25 | 14:00:00
14:45:00 | 14:00:00
14:49:55 | 14:00:00
(4 rows)

Inner Joins
For inner joins, there is no difference between a regular inner join and an event series inner join.
Since null values are eliminated from the result set, there is nothing to interpolate.
A regular inner join returns only the single matching row at 12:40:23:
=> SELECT * FROM t INNER JOIN t1 ON t.x = t1.y;
x
|
y
----------+---------12:40:23 | 12:40:23
(1 row)

An event series inner join finds the same single-matching row at 12:40:23:

HP Vertica Analytic Database (7.0.x)

Page 98 of 1539

SQL Reference Manual
SQL Language Elements

=> SELECT * FROM t INNER JOIN t1 ON t.x INTERPOLATE
PREVIOUS VALUE t1.y;
x
|
y
----------+---------12:40:23 | 12:40:23
(1 row)

Semantics
When you write an event series join in place of normal join, values are evaluated as follows (using
the schema in the above examples):
l

t is the outer, preserved table

l

t1 is the inner, non-preserved table

l

For each row in outer table t, the ON clause predicates are evaluated for each combination of
each row in the inner table t1.

l

If the ON clause predicates evaluate to true for any combination of rows, those combination
rows are produced at the output.

l

If the ON clause is false for all combinations, a single output row is produced with the values of
the row from t along with the columns of t1 chosen from the row in t1 with the greatest t1.y
value such that t1.y < t.x; If no such row is found, pad with nulls.
Note: t LEFT OUTER JOIN t1 is equivalent to t1 RIGHT OUTER JOIN t.

In the case of a full outer join, all values from both tables are preserved.

See Also
l

Join-Predicate
Combines records from two or more tables in a database.

Syntax
column-reference

= column-reference

Parameters
column-reference

Refers to a column of one the tables specified in the FROM Clause.

HP Vertica Analytic Database (7.0.x)

Page 99 of 1539

SQL Reference Manual
SQL Language Elements

LIKE-predicate
Retrieves rows where the string value of a column matches a specified pattern. The pattern can
contain one or more wildcard characters. ILIKE is equivalent to LIKE except that the match is caseinsensitive (non-standard extension).

Syntax
string [ NOT ]{ LIKE | ILIKE | LIKEB | ILIKEB }
... pattern
[ESCAPE 'escape-character' ]

Parameters
string

(CHAR, VARCHAR, BINARY, VARBINARY) is the column value to be compared to
the pattern.

NOT

Returns true if LIKE returns false, and the reverse; equivalent to NOT string
LIKE pattern.

pattern

Specifies a string containing wildcard characters.

ESCAPE

l

Underscore (_) matches any single character.

l

Percent sign (%) matches any string of zero or more characters.

Specifies an escape-character. An ESCAPE character can be used to
escape itself, underscore (_), and % only. This is enforced only for non-default
collations.
To match the ESCAPE character itself, use two consecutive escape
characters. The default ESCAPE character is the backslash (\) character,
although standard SQL specifies no default ESCAPE character. ESCAPE works
for CHAR and VARCHAR strings only.

escape-character

Causes character to be treated as a literal, rather than a wildcard, when
preceding an underscore or percent sign character in the pattern.

Notes
l

The LIKE predicate is compliant with the SQL standard.

l

In the default locale, LIKE and ILIKE handle UTF-8 character-at-a-time, locale-insensitive
comparisons. ILIKE handles language-independent case-folding.
Note: In non-default locales, LIKE and ILIKE do locale-sensitive string comparisons,

HP Vertica Analytic Database (7.0.x)

Page 100 of 1539

SQL Reference Manual
SQL Language Elements

including some automatic normalization, using the same algorithm as the "=" operator on
VARCHAR types.
l

The LIKEB and ILIKEB predicates do byte-at-a-time ASCII comparisons, providing access to
HP Vertica 4.0 functionality.

l

LIKE and ILIKE are stable for character strings, but immutable for binary strings, while LIKEB
and ILIKEB are both immutable.

l

For collation=binary settings, the behavior is similar to HP Vertica 4.0. For other collations,
LIKE operates on UTF-8 character strings, with the exact behavior dependent on collation
parameters, such as strength. In particular, ILIKE works by setting S=2 (ignore case) in the
current session locale. See Locale Specification in the Administrator's Guide.

l

Although the SQL standard specifies no default ESCAPE character, in HP Vertica the default is
the backslash (\) and works for CHAR and VARCHAR strings only.
Tip: HP recommends that you specify an explicit escape character in all cases, to avoid
problems should this behavior change. To use a backslash character as a literal, either
specify a different escape character or use two backslashes.

l

ESCAPE expressions evaluate to exactly one octet—or one UTF-8 character for non-default
locales.

l

An ESCAPE character can be used only to escape itself, _, and %. This is enforced only for nondefault collations.

l

LIKE requires that the entire string expression match the pattern. To match a sequence of
characters anywhere within a string, the pattern must start and end with a percent sign.

l

The LIKE predicate does not ignore trailing "white space" characters. If the data values that you
want to match have unknown numbers of trailing spaces, tabs, etc., terminate each LIKE
predicate pattern with the percent sign wildcard character.

l

To use binary data types, you must use a valid binary character as the escape character, since
backslash is not a valid BINARY character.

l

The following symbols are substitutes for the actual keywords:
~~
~#
~~*
~#*
!~~
!~#

LIKE
LIKEB
ILIKE
ILIKEB
NOT LIKE
NOT LIKEB

HP Vertica Analytic Database (7.0.x)

Page 101 of 1539

SQL Reference Manual
SQL Language Elements

!~~*
!~#*

NOT ILIKE
NOT IILIKEB

The ESCAPE keyword is not valid for the above symbols.
l

HP Vertica extends support for single-row subqueries as the pattern argument for LIKEB and
ILIKEB; for example:
SELECT * FROM t1 WHERE t1.x LIKEB (SELECT MAX (t2.a)
FROM t2);

Querying Case-Sensitive Data in System Tables
The V_CATALOG.TABLES.TABLE_SCHEMA and TABLE_NAME columns are case sensitive when used
with an equality (=) predicate in queries. For example, given the following sample schema, if you
execute a query using the = predicate, HP Vertica returns 0 rows:
=> CREATE SCHEMA SS;
=> CREATE TABLE SS.TT (c1 int);
=> INSERT INTO ss.tt VALUES (1);
=> SELECT table_schema, table_name FROM v_catalog.tables
WHERE table_schema ='ss';
table_schema | table_name
--------------+-----------(0 rows)

Tip: Use the case-insensitive ILIKE predicate to return the expected results.

=> SELECT table_schema, table_name FROM v_catalog.tables
WHERE table_schema ILIKE 'ss';
table_schema | table_name
-------------+-----------SS
| TT
(1 row)

Examples
'abc' LIKE 'abc' true'abc' LIKE 'a%'
'abc' LIKE '_b_' true
'abc' LIKE 'c'
false
'abc' LIKE 'ABC' false
'abc' ILIKE 'ABC' true
'abc' not like 'abc' false
not 'abc' like 'abc' false

true

The following example illustrates pattern matching in locales.

HP Vertica Analytic Database (7.0.x)

Page 102 of 1539

SQL Reference Manual
SQL Language Elements

\locale default=> CREATE TABLE src(c1 VARCHAR(100));
=> INSERT INTO src VALUES (U&'\00DF'); --The sharp s (ß)
=> INSERT INTO src VALUES ('ss');
=> COMMIT;

Querying the src table in the default locale returns both ss and sharp s.
=> SELECT * FROM src;
c1
---ß
ss
(2 rows)

The following query combines pattern-matching predicates to return the results from column c1:
=> SELECT c1, c1 = 'ss' AS equality, c1 LIKE 'ss'
AS LIKE, c1 ILIKE 'ss' AS ILIKE FROM src;
c1 | equality | LIKE | ILIKE
----+----------+------+------ß | f
| f
| f
ss | t
| t
| t
(2 rows)

The next query specifies unicode format for c1:
=> SELECT c1, c1 = U&'\00DF' AS equality,
c1 LIKE U&'\00DF' AS LIKE,
c1 ILIKE U&'\00DF' AS ILIKE from src;
c1 | equality | LIKE | ILIKE
----+----------+------+------ß | t
| t
| t
ss | f
| f
| f
(2 rows)

Now change the locale to German with a strength of 1 (ignore case and accents):
\locale LDE_S1
=> SELECT c1, c1 = 'ss' AS equality,
c1 LIKE 'ss' as LIKE, c1 ILIKE 'ss' AS ILIKE from src;
c1 | equality | LIKE | ILIKE
----+----------+------+------ß | t
| t
| t
ss | t
| t
| t
(2 rows)

This example illustrates binary data types with pattern-matching predicates:
=> CREATE TABLE t (c BINARY(1));
=> INSERT INTO t values(HEX_TO_BINARY('0x00'));
=> INSERT INTO t values(HEX_TO_BINARY('0xFF'));

HP Vertica Analytic Database (7.0.x)

Page 103 of 1539

SQL Reference Manual
SQL Language Elements

=> SELECT TO_HEX(c) from t;
TO_HEX
-------00
ff
(2 rows)
select * from t;
c
-----\000
\377
(2 rows)
=> SELECT c, c = '\000', c LIKE '\000', c ILIKE '\000' from t;
c
| ?column? | ?column? | ?column?
------+----------+----------+---------\000 | t
| t
| t
\377 | f
| f
| f
(2 rows)
=> SELECT c, c = '\377', c LIKE '\377', c ILIKE '\377' from t;
c
| ?column? | ?column? | ?column?
------+----------+----------+---------\000 | f
| f
| f
\377 | t
| t
| t
(2 rows)

NULL-predicate
Tests for null values.

Syntax
value_expression IS [ NOT ] NULL

Parameters
value_expression

A column name, literal, or function.

Examples
Column name:
=> SELECT date_key FROM date_dimension WHERE date_key IS NOT NULL;
date_key
---------1
366
1462
1097
2
3

HP Vertica Analytic Database (7.0.x)

Page 104 of 1539

SQL Reference Manual
SQL Language Elements

6
7
8
...

Function:
=> SELECT MAX(household_id) IS NULL FROM customer_dimension;
?column?
---------f
(1 row)

Literal:
=> SELECT 'a' IS NOT NULL;
?column?
---------t
(1 row)

See Also
l

NULL Value

HP Vertica Analytic Database (7.0.x)

Page 105 of 1539

SQL Reference Manual
SQL Language Elements

HP Vertica Analytic Database (7.0.x)

Page 106 of 1539

SQL Reference Manual
SQL Data Types

SQL Data Types
The following tables summarize the data types that HP Vertica supports. It also shows the default
placement of null values in projections. The Size column is listed as uncompressed bytes.
Size
(bytes)

Description

NULL
Sorting

BINARY

1 to 65000

Fixed-length binary string

NULLS LAST

VARBINARY

1 to 65000

Variable-length binary string

NULLS LAST

LONG VARBINARY

1 to
Long variable-length binary string
32,000,000

NULLS LAST

BYTEA

1 to 65000

Variable-length binary string (synonym for
VARBINARY)

NULLS LAST

RAW

1 to 65000

Variable-length binary string (synonym for
VARBINARY)

NULLS LAST

1

True or False or NULL

NULLS LAST

CHAR

1 to 65000

Fixed-length character string

NULLS LAST

VARCHAR

1 to 65000

Variable-length character string

NULLS LAST

LONG VARCHAR

1 to
Long variable-length character string
32,000,000

NULLS LAST

DATE

8

Represents a month, day, and year

NULLS FIRST

DATETIME

8

Represents a date and time with or without
timezone (synonym for TIMESTAMP)

NULLS FIRST

SMALLDATETIME

8

Represents a date and time with or without
timezone (synonym for TIMESTAMP)

NULLS FIRST

TIME

8

Represents a time of day without timezone

NULLS FIRST

TIME WITHTIMEZONE

8

Represents a time of day with timezone

NULLS FIRST

TIMESTAMP

8

Represents a date and time without
timezone

NULLS FIRST

Type
Binary types

Boolean types
BOOLEAN

Character types

Date/time types

HP Vertica Analytic Database (7.0.x)

Page 107 of 1539

SQL Reference Manual
SQL Data Types

Type

Size
(bytes)

Description

NULL
Sorting

TIMESTAMP WITHTIMEZONE

8

Represents a date and time with timezone

NULLS FIRST

INTERVAL

8

Measures the difference between two
points in time

NULLS FIRST

Approximate numeric types
DOUBLE PRECISION

8

Signed 64-bit IEEE floating point number,
requiring 8 bytes of storage

NULLS LAST

FLOAT

8

Signed 64-bit IEEE floating point number,
requiring 8 bytes of storage

NULLS LAST

FLOAT(n)

8

Signed 64-bit IEEE floating point number,
requiring 8 bytes of storage

NULLS LAST

FLOAT8

8

Signed 64-bit IEEE floating point number,
requiring 8 bytes of storage

NULLS LAST

REAL

8

Signed 64-bit IEEE floating point number,
requiring 8 bytes of storage

NULLS LAST

INTEGER

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

INT

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

BIGINT

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

INT8

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

SMALLINT

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

TINYINT

8

Signed 64-bit integer, requiring 8 bytes of
storage

NULLS FIRST

DECIMAL

8+

8 bytes for the first 18 digits of precision,
plus 8 bytes for each additional 19 digits

NULLS FIRST

NUMERIC

8+

8 bytes for the first 18 digits of precision,
plus 8 bytes for each additional 19 digits

NULLS FIRST

NUMBER

8+

8 bytes for the first 18 digits of precision,
plus 8 bytes for each additional 19 digits

NULLS FIRST

Exact numeric types

HP Vertica Analytic Database (7.0.x)

Page 108 of 1539

SQL Reference Manual
SQL Data Types

Type

Size
(bytes)

MONEY

8+

Description
8 bytes for the first 18 digits of precision,
plus 8 bytes for each additional 19 digits

NULL
Sorting
NULLS FIRST

Binary Data Types
Store raw-byte data, such as IP addresses, up to 65000 bytes.

Syntax
BINARY ( length ){ VARBINARY | BINARY VARYING | BYTEA | RAW } ( max-length )

Parameters
length | max-length

Specifies the length of the string (column width, declared in bytes (octets),
in CREATE TABLE statements).

Notes
l

BYTEA and RAW are synonyms for VARBINARY.

l

The data types BINARY and BINARY VARYING (VARBINARY) are collectively referred to as binary
string types and the values of binary string types are referred to as binary strings.

l

A binary string is a sequence of octets, or bytes. Binary strings store raw-byte data, while
character strings store text.

l

A binary value value of NULL appears last (largest) in ascending order.

l

The binary data types, BINARY and VARBINARY, are similar to the Character Data Types, CHAR
and VARCHAR, respectively, except that binary data types contain byte strings, rather than
character strings.

l

BINARY—A fixed-width string of length bytes, where the number of bytes is declared as an
optional specifier to the type. If length is omitted, the default is 1. Where necessary, values are
right-extended to the full width of the column with the zero byte. For example:
=> SELECT TO_HEX('ab'::BINARY(4));
to_hex
---------61620000

l

VARBINARY—A variable-width string up to a length of max-length bytes, where the maximum
number of bytes is declared as an optional specifier to the type. The default is the default

HP Vertica Analytic Database (7.0.x)

Page 109 of 1539

SQL Reference Manual
SQL Data Types

attribute size, which is 80, and the maximum length is 65000 bytes. VARBINARY values are not
extended to the full width of the column. For example:
=> SELECT TO_HEX('ab'::VARBINARY(4));
to_hex
-------6162

l

You can use several formats when working with binary values, but the hexadecimal format is
generally the most straightforward and is emphasized in HP Vertica documentation.

l

Binary operands &, ~, | and # have special behavior for binary data types, as described in
Binary Operators.

l

On input, strings are translated from:
n

Hexadecimal representation to a binary value using the HEX_TO_BINARY function

n

Bitstring representation to a binary value using the BITSTRING_TO_BINARY function.

Both functions take a VARCHAR argument and return a VARBINARY value. See the Examples
section below.
l

Binary values can also be represented in octal format by prefixing the value with a backslash
'\'.
Note: If you use vsql, you must use the escape character (\) when you insert another
backslash on input; for example, input '\141' as '\\141'.
You can also input values represented by printable characters. For example, the hexadecimal
value '0x61' can also be represented by the symbol '.
See Bulk Loading Data in the Administrator's Guide.

l

Like the input format the output format is a hybrid of octal codes and printable ASCII characters.
A byte in the range of printable ASCII characters (the range [0x20, 0x7e]) is represented by
the corresponding ASCII character, with the exception of the backslash ('\'), which is escaped
as '\\'. All other byte values are represented by their corresponding octal values. For example,
the bytes {97,92,98,99}, which in ASCII are {a,\,b,c}, are translated to text as 'a\\bc'.

l

The following aggregate functions are supported for binary data types:
n

BIT_AND

n

BIT_OR

n

BIT_XOR

HP Vertica Analytic Database (7.0.x)

Page 110 of 1539

SQL Reference Manual
SQL Data Types

n

MAX

n

MIN

BIT_AND, BIT_OR, and BIT_XOR are bitwise operations that are applied to each non-null value in a
group, while MAX and MIN are bytewise comparisons of binary values.
l

Like their binary operator counterparts, if the values in a group vary in length, the aggregate
functions treat the values as though they are all equal in length by extending shorter values with
zero bytes to the full width of the column. For example, given a group containing the values
'ff', null, and 'f', a binary aggregate ignores the null value and treats the value 'f' as
'f0'. Also, like their binary operator counterparts, these aggregate functions operate on
VARBINARY types explicitly and operate on BINARY types implicitly through casts. See Data Type
Coercion Operators (CAST).

Examples
The following example shows VARBINARY HEX_TO_BINARY(VARCHAR) and VARCHAR TO_HEX
(VARBINARY) usage.
Table t and and its projection are created with binary columns:
=> CREATE TABLE t (c BINARY(1));
=> CREATE PROJECTION t_p (c) AS SELECT c FROM t;

Insert minimum byte and maximum byte values:
=> INSERT INTO t values(HEX_TO_BINARY('0x00'));
=> INSERT INTO t values(HEX_TO_BINARY('0xFF'));

Binary values can then be formatted in hex on output using the TO_HEX function:
=> SELECT TO_HEX(c) FROM t;
to_hex
-------00
ff
(2 rows)

The BIT_AND, BIT_OR, and BIT_XORfunctions are interesting when operating on a group of values.
For example, create a sample table and projections with binary columns:
This example uses the following schema, which creates table t with a single column of VARBINARY
data type:
=>
=>
=>
=>

CREATE
INSERT
INSERT
INSERT

TABLE t ( c VARBINARY(2) );
INTO t values(HEX_TO_BINARY('0xFF00'));
INTO t values(HEX_TO_BINARY('0xFFFF'));
INTO t values(HEX_TO_BINARY('0xF00F'));

HP Vertica Analytic Database (7.0.x)

Page 111 of 1539

SQL Reference Manual
SQL Data Types

Query table t to see column c output:
=> SELECT TO_HEX(c) FROM t;
TO_HEX
-------ff00
ffff
f00f
(3 rows)

Now issue the bitwise AND operation. Because these are aggregate functions, an implicit GROUP
BY operation is performed on results using (ff00&(ffff)&f00f):
=> SELECT TO_HEX(BIT_AND(c)) FROM t;
TO_HEX
-------f000
(1 row)

Issue the bitwise OR operation on (ff00|(ffff)|f00f):
=> SELECT TO_HEX(BIT_OR(c)) FROM t;
TO_HEX
-------ffff
(1 row)

Issue the bitwise XOR operation on (ff00#(ffff)#f00f):
=> SELECT TO_HEX(BIT_XOR(c)) FROM t;
TO_HEX
-------f0f0
(1 row)

See Also
l

BIT_AND

l

BIT_OR

l

BIT_XOR

l

MAX [Aggregate]

l

MIN [Aggregate]

l

Binary Operators

l

COPY

HP Vertica Analytic Database (7.0.x)

Page 112 of 1539

SQL Reference Manual
SQL Data Types

l

Data Type Coercion Operators (CAST)

l

INET_ATON

l

INET_NTOA

l

V6_ATON

l

V6_NTOA

l

V6_SUBNETA

l

V6_SUBNETN

l

V6_TYPE

l

BITCOUNT

l

BITSTRING_TO_BINARY

l

HEX_TO_BINARY

l

LENGTH

l

REPEAT

l

SUBSTRING

l

TO_HEX

l

TO_BITSTRING

Boolean Data Type
HP Vertica provides the standard SQL type BOOLEAN, which has two states: true and false. The
third state in SQL boolean logic is unknown, which is represented by the NULL value.

Syntax
BOOLEAN

Parameters
Valid literal data values for input are:

TRUE

't'

'true'

'y'

'yes'

'1'

1

FALSE

'f'

'false'

'n'

'no'

'0'

0

HP Vertica Analytic Database (7.0.x)

Page 113 of 1539

SQL Reference Manual
SQL Data Types

Notes
l

Do not confuse the BOOLEAN data type with Boolean Operators or the Boolean-Predicate.

l

The keywords TRUE and FALSE are preferred and are SQL-compliant.

l

A Boolean value of NULL appears last (largest) in ascending order.

l

All other values must be enclosed in single quotes.

l

Boolean values are output using the letters t and f.

See Also
l

NULL Value

l

Data Type Coercion Chart

Character Data Types
Stores strings of letters, numbers, and symbols.
Character data can be stored as fixed-length or variable-length strings. Fixed-length strings are
right-extended with spaces on output; variable-length strings are not extended.

Syntax
[ CHARACTER | CHAR ] ( octet_length )[ VARCHAR | CHARACTER VARYING ] ( octet_length )

Parameters
octet_length

Specifies the length of the string (column width, declared in bytes (octets), in
CREATE TABLE statements).

Notes
l

The data types CHARACTER (CHAR) and CHARACTER VARYING (VARCHAR) are collectively referred to
as character string types, and the values of character string types are known as character
strings.

l

CHAR is conceptually a fixed-length, blank-padded string. Any trailing blanks (spaces) are
removed on input, and only restored on output. The default length is 1, and the maximum length
is 65000 octets (bytes).

HP Vertica Analytic Database (7.0.x)

Page 114 of 1539

SQL Reference Manual
SQL Data Types

l

VARCHAR is a variable-length character data type. The default length is 80, and the maximum
length is 65000 octets. Values can include trailing spaces.

l

When you define character columns, specify the maximum size of any string to be stored in a
column. For example, to store strings up to 24 octets in length, use either of the following
definitions:
CHAR(24)

l

/* fixed-length */VARCHAR(24) /* variable-length */

The maximum length parameter for VARCHAR and CHAR data type refers to the number of octets
that can be stored in that field, not the number of characters (Unicode code points). When using
multibyte UTF-8 characters, the fields must be sized to accommodate from 1 to 4 octets per
character, depending on the data. If the data loaded into a VARCHAR/CHAR column exceeds the
specified maximum size for that column, data is truncated on UTF-8 character boundaries to fit
within the specified size. See COPY.
Note: Remember to include the extra octets required for multibyte characters in the columnwidth declaration, keeping in mind the 65000 octet column-width limit.

l

String literals in SQL statements must be enclosed in single quotes.

l

Due to compression in HP Vertica, the cost of overestimating the length of these fields is
incurred primarily at load time and during sorts.

l

NULL appears last (largest) in ascending order. See also GROUP BY Clause for additional
information about NULL ordering.

The Difference Between NULL and NUL
NUL represents a character whose ASCII/Unicode code is 0, sometimes qualified "ASCII NUL".
NULL means no value, and is true of a field (column) or constant, not of a character.
CHAR, LONG VARCHAR, and VARCHAR string data types accept ASCII NULs.
The following example casts the input string containing NUL values to VARCHAR:
=> SELECT 'vert\0ica'::CHARACTER VARYING AS VARCHAR;
VARCHAR
--------vert\0ica
(1 row)

The result contains 9 characters:
=> SELECT LENGTH('vert\0ica'::CHARACTER VARYING);
length

HP Vertica Analytic Database (7.0.x)

Page 115 of 1539

SQL Reference Manual
SQL Data Types

-------9
(1 row)

If you use an extended string literal, the length is 8 characters:
=> SELECT E'vert\0ica'::CHARACTER VARYING AS VARCHAR;
VARCHAR
--------vertica
(1 row)
=> SELECT LENGTH(E'vert\0ica'::CHARACTER VARYING);
LENGTH
-------8
(1 row)

See Also
l

Data Type Coercion

HP Vertica Analytic Database (7.0.x)

Page 116 of 1539

SQL Reference Manual
SQL Data Types

Date/Time Data Types
HP Vertica supports the full set of SQL date and time data types. In most cases, a combination of
DATE, DATETIME, SMALLDATETIME, TIME, TIMESTAMP WITHOUT TIME ZONE, and TIMESTAMP WITH
TIME ZONE, and INTERVAL provides a complete range of date/time functionality required by any
application.
In compliance with the SQL standard, HP Vertica also supports the TIME WITH TIME ZONE data
type.
The following table lists the characteristics about the date/time data types. All these data types
have a size of 8 bytes.

Name

Description

Low Value

High Value

Resolut
ion

DATE

Dates only
(no time of d
ay)

~ 25e+15 BC

~ 25e+15 AD

1 day

TIME [(p]

Time of day o
nly
(no date)

00:00:00.00

23:59:60.999999

1 μs

TIMETZ [(p)]

Time of day o
nly,
with time zon
e

00:00:00.00+14

23:59:59.999999-14

1 μs

TIMESTAMP [(p)]

Both date and
time,
without time
zone

290279-12-22 19:59:05.2241
94 BC

294277-01-09 04:00:54:7758
06 AD

1 μs

TIMESTAMPTZ [(p)]

Both date and
time,
with time zon
e

290279-12-22 19:59:05.2241
94 BC UTC

294277-01-09 04:00:54:7758
06 AD UTC

1 μs

INTERVAL [(p)]DAY T
O SECOND

Time intervals -106751991 days 04:00:54.7
75807

+-106751991 days 04:00:54.
775807

1 μs

INTERVAL [(p)]YEAR
TO MONTH

Time intervals ~ -768e15 yrs

~ 768e15 yrs

1 month

Time Zone Abbreviations for Input
HP Vertica recognizes the files in /opt/vertica/share/timezonesets as date/time input values
and defines the default list of strings accepted in the AT TIME ZONE zone parameter. The names
are not necessarily used for date/time output—output is driven by the official time zone
abbreviations associated with the currently selected time zone parameter setting.

HP Vertica Analytic Database (7.0.x)

Page 117 of 1539

SQL Reference Manual
SQL Data Types

Notes
l

In HP Vertica, TIME ZONE is a synonym for TIMEZONE.

l

HP Vertica uses Julian dates for all date/time calculations, which can correctly predict and
calculate any date more recent than 4713 BC to far into the future, based on the assumption that
the average length of the year is 365.2425 days.

l

All date/time types are stored in eight bytes.

l

A date/time value of NULL appears first (smallest) in ascending order.

l

All the date/time data types accept the special literal value NOW to specify the current date and
time. For example:
=> SELECT TIMESTAMP 'NOW';
?column?
---------------------------2012-03-13 11:42:22.766989
(1 row)

l

In HP Vertica, the INTERVAL data type is SQL:2008 compliant and allows modifiers, called
interval qualifiers, that divide the INTERVAL type into two primary subtypes, DAY TO SECOND
(the default) and YEAR TO MONTH. You use the SET INTERVALSTYLE command to change the
intervalstyle run-time parameter for the current session.
Intervals are represented internally as some number of microseconds and printed as up to 60
seconds, 60 minutes, 24 hours, 30 days, 12 months, and as many years as necessary. Fields
can be positive or negative.

See Also
l

TZ Environment Variable

l

Using Time Zones With HP Vertica

l

Sources for Time Zone and Daylight Saving Time Data

DATE
Consists of a month, day, and year.

Syntax
DATE

HP Vertica Analytic Database (7.0.x)

Page 118 of 1539

SQL Reference Manual
SQL Data Types

Parameters/Limits

Low Value

High Value Resolution

~ 25e+15 BC

~ 25e+15 AD

1 DAY

See SET DATESTYLE for information about ordering.
Example

Description

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

DATETIME
DATETIME is an alias for TIMESTAMP.

HP Vertica Analytic Database (7.0.x)

Page 119 of 1539

SQL Reference Manual
SQL Data Types

INTERVAL
Measures the difference between two points in time. The INTERVAL data type is divided into two
major subtypes:
l

DAY TO SECOND (day/time, in microseconds)

l

YEAR TO MONTH (year/month, in months)

A day/time interval represents a span of days, hours, minutes, seconds, and fractional seconds. A
year/month interval represents a span of years and months. Intervals can be positive or negative.

Syntax
INTERVAL [ (p) ] [ - ] 'Interval-Literal' [ Interval-Qualifier ]

Parameters
(p)

[Optional] Specifies the precision for the number of digits retained in the
seconds field. Enter the precision value in parentheses (). The interval
precision can range from 0 to 6. The default is 6.

-

[Optional] Indicates a negative interval.

'interval-literal'

Indicates a literal character string expressing a specific interval.

interval-qualifier

[Optional] Specifies a range of interval subtypes with optional precision
specifications. If omitted, the default is DAY TO SECOND(6). Sometimes
referred to as subtype in this topic.
Within the single quotes of an interval-literal, units can be plural, but
outside the quotes, the interval-qualifier must be singular.

Limits
Name

Low Value

High Value

Resolution

INTERVAL [(p)] DAY TO SECOND

–106751991 days

+/–106751991 days

1 microsecond

04:00:54.775807

04:00:54.775807

~/ –768e15 yrs

~ 768e15 yrs

INTERVAL [(p)] YEAR TO MONTH

1 month

Displaying or Omitting Interval Units in Output
To display or omit interval units from the output of a SELECT INTERVAL query, use the
INTERVALSTYLE and DATESTYLE settings. These settings affect only the interval output format, not

HP Vertica Analytic Database (7.0.x)

Page 120 of 1539

SQL Reference Manual
SQL Data Types

the interval input format.
To omit interval units from the output, set INTERVALSTYLE to PLAIN. This is the default value, and it
follows the SQL:2008 standard (ISO):
=> SET INTERVALSTYLE TO PLAIN;
SET
=> SELECT INTERVAL '3 2';
?column?
---------3 02:00

When INTERVALSTYLE is set to PLAIN, units are omitted from the output, even if you specify the
units in the query:
=> SELECT INTERVAL '3 days 2 hours';
?column?
---------3 02:00

To display interval units in the output, set INTERVALSTYLE to UNITS:
=> SET INTERVALSTYLE TO UNITS;
SET
=> SELECT INTERVAL '3 2';
?column?
---------------3 days 2 hours

When INTERVALSTYLE is set to UNITS to display units in the result, the DATESTYLE setting controls
the format of the units in the output.
If you set DATESTYLE to SQL, interval units are omitted from the output, even if you set
INTERVALSTYLE to UNITS:
=> SET INTERVALSTYLE TO UNITS;
SET
=> SET DATESTYLE TO SQL;
SET
=> SELECT INTERVAL '3 2';
?column?
---------3 02:00

To display interval units on output, set DATESTYLE to ISO:
=> SET INTERVALSTYLE TO UNITS;
SET
=> SET DATESTYLE TO ISO;
SET
=> SELECT INTERVAL '3 2';
?column?

HP Vertica Analytic Database (7.0.x)

Page 121 of 1539

SQL Reference Manual
SQL Data Types

---------------3 days 2 hours

To check the INTERVALSTYLE or DATESTYLE setting, use the SHOW command:
=> SHOW INTERVALSTYLE;
name
| setting
---------------+--------intervalstyle | units
=> SHOW DATESTYLE;
name
| setting
-----------+---------datestyle | ISO, MDY

Specifying Units on Input
You can specify interval units in the interval-literal:
=> SELECT INTERVAL '3 days 2 hours';
?column?
-------------3 days 2 hours

The following command uses the same interval-literal as the previous example, but specifies a
MINUTE interval-qualifier to so that the results are displayed only in minutes:
=> SELECT INTERVAL '3 days 2 hours' MINUTE;
?column?
----------4440 mins

HP Vertica allows combinations of units in the interval-qualifier, as in the next three examples:
=> SELECT INTERVAL '1 second 1 millisecond' DAY TO SECOND;
?column?
-------------1.001 secs
=> SELECT INTERVAL '28 days 3 hours 65 min' HOUR TO MINUTE;
?column?
----------676 hours 5 mins

Units less than a month are not valid for YEAR TO MONTH interval-qualifiers:
=> SELECT INTERVAL '1 Y 30 DAYS' YEAR TO MONTH;
ERROR: invalid input syntax for type interval year to month: "1 Y 30 DAYS"

If you replace DAYS in the interval-literal with M to represent months, HP Vertica returns the correct
information of 1 year, 3 months:

HP Vertica Analytic Database (7.0.x)

Page 122 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT INTERVAL '1 Y 3 M' YEAR TO MONTH;
?column?
---------1 year 3 months

in the previous example, M was used as the interval-literal, representing months. If you specify a
DAY TO SECOND interval-qualifier, HP Vertica knows that M represents minutes, as in the following
example:
=> SELECT INTERVAL '1 D 3 M' DAY TO SECOND;
?column?
---------1 day 3 mins

The next two examples use units in the input to return microseconds:
=> SELECT INTERVAL '4:5 1 2 34us';
?column?
------------------1 day 04:05:02.000034
=> SELECT INTERVAL '4:5 1d 2 34us' HOUR TO SECOND;
?column?
----------------28 hours 5 mins 2.000034 secs

How the Interval-Qualifier Affects Output Units
The interval-qualifier specifies a range of interval subtypes to apply to the interval-literal. You can
also specify the precision in the interval-qualifier.
If an interval-qualifier is not specified, the default subtype is DAY TO SECOND(6), regardless of what
is inside the quotes. For example, as an extension to SQL:2008, both of the following commands
return 910 days:
=> SELECT INTERVAL '2-6'
; ?column?
----------------910 days
=> SELECT INTERVAL '2 years 6 months';
?column?
----------------910 days

However, if you change the interval-qualifier to YEAR TO MONTH, you get the following results:
=> SELECT INTERVAL '2 years 6 months' YEAR TO MONTH;
?column?
----------------2 years 6 months

HP Vertica Analytic Database (7.0.x)

Page 123 of 1539

SQL Reference Manual
SQL Data Types

An interval-qualifier can extract other values from the input parameters. For example, the following
command extracts the HOUR value from the input parameters:
=> SELECT INTERVAL '3 days 2 hours' HOUR;
?column?
---------74 hours

When specifying intervals that use subtype YEAR TO MONTH, the returned value is kept as months:
=> SELECT INTERVAL '2 years 6 months' YEAR TO MONTH;
?column?
----------2 years 6 months

The primary day/time (DAY TO SECOND) and year/month (YEAR TO MONTH) subtype ranges can be
restricted to more specific range of types by an interval-qualifier. For example, HOUR TO MINUTE is
a limited form of day/time interval, which can be used to express time zone offsets.
=> SELECT INTERVAL '1 3' HOUR to MINUTE;
?column?
--------------01:03

The formats hh:mm:ss and hh:mm are used only when at least two of the fields specified in the
interval-qualifier are non-zero and there are no more than 23 hours or 59 minutes:
=> SELECT INTERVAL '2 days 12 hours 15 mins' DAY TO MINUTE;
?column?
-------------2 days 12:15
=> SELECT INTERVAL '15 mins 20 sec' MINUTE TO SECOND;
?column?
---------00:15:20
=> SELECT INTERVAL '1 hour 15 mins 20 sec' MINUTE TO SECOND;
?column?
----------------75 mins 20 secs

Specifying Precision
SQL:2008 allows you to specify precision for the interval output by entering the precision value in
parentheses after the INTERVAL keyword or the interval-qualifier. HP Vertica rounds the input to the
number of decimal places specified. SECOND(2) and SECOND (2) produce the same result:
If you specify two different precisions, HP Vertica picks the lesser of the two:
=> SELECT INTERVAL(1) '1.2467' SECOND(2);
?column?

HP Vertica Analytic Database (7.0.x)

Page 124 of 1539

SQL Reference Manual
SQL Data Types

---------1.2 secs

When you specify a precision inside an interval-literal, HP Vertica processes the precision by
removing the parentheses. In this example, (3) is processed as 3 minutes, the first omitted field:
=> SELECT INTERVAL '28 days 3 hours 1.234567 second(3)';
?column?
-------------------28 days 03:03:01.234567

The following command specifies that the day field can hold 4 digits, the hour field 2 digits, the
minutes field 2 digits, the seconds field 2 digits, and the fractional seconds field 6 digits:
=> SELECT INTERVAL '1000 12:00:01.123456' DAY(4) TO SECOND(6);
?column?
--------------------------1000 days 12:00:01.123456

AN HP Vertica extension lets you specify the seconds precision on the INTERVAL keyword. The
result is the same:
=> SELECT INTERVAL(6) '1000 12:00:01.123456' DAY(4) TO SECOND;
1000 days 12:00:01.123456

Casting with Intervals
You can cast a string to an interval:
=> SELECT CAST('3700 sec' AS INTERVAL);
?column?
---------01:01:40

You can cast an interval to a string:
=> SELECT CAST((SELECT INTERVAL '3700 seconds') AS VARCHAR(20));
?column?
---------01:01:40

You can cast intervals within the day/time or the year/month subtypes but not between them. Use
CAST to convert interval types:
=> SELECT CAST(INTERVAL '4440' MINUTE as INTERVAL);
?column?
---------3 days 2 hours

HP Vertica Analytic Database (7.0.x)

Page 125 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT CAST(INTERVAL -'01:15' as INTERVAL MINUTE);
?column?
----------75 mins

Processing Signed Intervals
In the SQL:2008 standard, a minus sign before an interval-literal or as the first character of the
interval-literal negates the entire literal, not just the first component. In HP Vertica, a leading minus
sign negates the entire interval, not just the first component. The following commands both return
the same value:
=> SELECT INTERVAL '-1 month - 1 second';
?column?
----------29 days 23:59:59
=> SELECT INTERVAL -'1 month - 1 second';
?column?
----------29 days 23:59:59

Use one of the following commands instead to return the intended result:
=> SELECT INTERVAL -'1 month 1 second';
?column?
----------30 days 1 sec
=> SELECT INTERVAL -'30 00:00:01';
?column?
----------30 days 1 sec

Two negatives together return a positive:
=> SELECT INTERVAL -'-1 month - 1 second';
?column?
---------29 days 23:59:59
=> SELECT INTERVAL -'-1 month 1 second';
?column?
---------30 days 1 sec

You can use the year-month syntax with no spaces. HP Vertica allows the input of negative months
but requires two negatives when paired with years.
=> SELECT INTERVAL '3-3' YEAR TO MONTH;
?column?
----------

HP Vertica Analytic Database (7.0.x)

Page 126 of 1539

SQL Reference Manual
SQL Data Types

3 years 3 months
=> SELECT INTERVAL '3--3' YEAR TO MONTH;
?column?
---------2 years 9 months

When the interval-literal looks like a year/month type, but the type is day/second, or vice versa, HP
Vertica reads the interval-literal from left to right, where number-number is years-months, and
number   is whatever the units specify. HP Vertica processes the
following command as (–) 1 year 1 month = (–) 365 + 30 = –395 days:
=> SELECT INTERVAL '-1-1' DAY TO HOUR;
?column?
----------395 days

If you insert a space in the interval-literal, HP Vertica processes it based on the subtype DAY TO
HOUR: (–) 1 day – 1 hour = (–) 24 – 1 = –23 hours:
=> SELECT INTERVAL '-1 -1' DAY TO HOUR;
?column?
----------23 hours

Two negatives together returns a positive, so HP Vertica processes the following command as (–) 1
year – 1 month = (–) 365 – 30 = –335 days:
=> SELECT INTERVAL '-1--1' DAY TO HOUR;
?column?
----------335 days

If you omit the value after the hyphen, HP Vertica assumes 0 months and processes the following
command as 1 year 0 month –1 day = 365 + 0 – 1 = –364 days:
=> SELECT INTERVAL '1- -1' DAY TO HOUR;
?column?
---------364 days

Processing Interval-Literals Without Units
You can specify quantities of days, hours, minutes, and seconds without explicit units. HP Vertica
recognizes colons in interval-literals as part of the timestamp:
=> SELECT INTERVAL '1 4 5 6';
?column?
------------

HP Vertica Analytic Database (7.0.x)

Page 127 of 1539

SQL Reference Manual
SQL Data Types

1 day 04:05:06
=> SELECT INTERVAL '1 4:5:6';
?column?
-----------1 day 04:05:06
=> SELECT INTERVAL '1 day 4 hour 5 min 6 sec';
?column?
-----------1 day 04:05:06

If HP Vertica cannot determine the units, it applies the quantity to any missing units based on the
interval-qualifier. In the next two examples, HP Vertica uses the default interval-qualifier (DAY TO
SECOND(6)) and assigns the trailing 1 to days, since it has already processed hours, minutes, and
seconds in the output:
=> SELECT INTERVAL '4:5:6 1';
?column?
-----------1 day 04:05:06
=> SELECT INTERVAL '1 4:5:6';
?column?
-----------1 day 04:05:06

In the next two examples, HP Vertica recognizes 4:5 as hours:minutes. The remaining values in
the interval-literal are assigned to the missing units; 1 is assigned to days and 2 is assigned to
seconds:
SELECT INTERVAL '4:5 1 2';
?column?
-----------1 day 04:05:02
=> SELECT INTERVAL '1 4:5 2';
?column?
-----------1 day 04:05:02

Specifying the interval-qualifier can change how HP Vertica interprets 4:5:
=> SELECT INTERVAL '4:5' MINUTE TO SECOND;
?column?
-----------00:04:05

Using INTERVALYM for INTERVAL YEAR TO MONTH
INTERVALYM is an alias for the INTERVAL YEAR TO MONTH subtypes and is used only on input:
=> SELECT INTERVALYM '1 2';
?column?

HP Vertica Analytic Database (7.0.x)

Page 128 of 1539

SQL Reference Manual
SQL Data Types

-----------1 year 2 months

Operations with Intervals
If you divide an interval by an interval, you get a FLOAT:
=> SELECT INTERVAL '28 days 3 hours' HOUR(4) / INTERVAL '27 days 3 hours' HOUR(4);
?column?
-----------1.036866359447

An INTERVAL divided by FLOAT returns an INTERVAL:
=> SELECT INTERVAL '3' MINUTE / 1.5;
?column?
-----------2 mins

INTERVAL MODULO (remainder) INTERVAL returns an INTERVAL:
=> SELECT INTERVAL '28 days 3 hours' HOUR % INTERVAL '27 days 3 hours' HOUR;
?column?
-----------24 hours

If you add INTERVAL and TIME, the result is TIME, modulo 24 hours:
=> SELECT INTERVAL '1' HOUR + TIME '1:30';
?column?
-----------02:30:00

Fractional Seconds in Interval Units
HP Vertica supports intervals in milliseconds (hh:mm:ss:ms), where 01:02:03:25 represents 1
hour, 2 minutes, 3 seconds, and 025 milliseconds. Milliseconds are converted to fractional seconds
as in the following example, which returns 1 day, 2 hours, 3 minutes, 4 seconds, and 25.5
milliseconds:
=> SELECT INTERVAL '1 02:03:04:25.5';
?column?
-----------1 day 02:03:04.0255

HP Vertica allows fractional minutes. The fractional minutes are rounded into seconds:

HP Vertica Analytic Database (7.0.x)

Page 129 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT INTERVAL '10.5 minutes';
?column?
-----------00:10:30
=> select interval '10.659 minutes';
?column?
------------00:10:39.54
=> select interval '10.3333333333333 minutes';
?column?
---------00:10:20

Notes
l

The HP Vertica INTERVAL data type is SQL:2008 compliant, with extensions. On HP Vertica
databases created prior to version 4.0, all INTERVAL columns are interpreted as INTERVAL DAY
TO SECOND, as in the previous releases.

l

An INTERVAL can include only the subset of units that you need; however, year/month intervals
represent calendar years and months with no fixed number of days, so year/month interval
values cannot include days, hours, minutes. When year/month values are specified for day/time
intervals, the intervals extension assumes 30 days per month and 365 days per year. Since the
length of a given month or year varies, day/time intervals are never output as months or years,
only as days, hours, minutes, and so on.

l

Day/time and year/month intervals are logically independent and cannot be combined with or
compared to each other. In the following example, an interval-literal that contains DAYS cannot be
combined with the YEAR TO MONTH type:
=> SELECT INTERVAL '1 2 3' YEAR TO MONTH;
ERROR 3679: Invalid input syntax for interval year to month: "1 2 3"

l

HP Vertica accepts intervals up to 2^63 – 1 microseconds or months (about 18 digits).

l

INTERVAL YEAR TO MONTH can be used in an analytic RANGE window when the ORDER BY
column type is TIMESTAMP/TIMESTAMP WITH TIMEZONE, or DATE. Using TIME/TIME WITH
TIMEZONE are not supported.

l

You can use INTERVAL DAY TO SECOND when the ORDER BY column type is
TIMESTAMP/TIMESTAMP WITH TIMEZONE, DATE, and TIME/TIME WITH TIMEZONE.

Examples
The table in this section contains additional interval examples. The INTERVALSTYLE is set to PLAIN
(omitting units on output) for brevity.

HP Vertica Analytic Database (7.0.x)

Page 130 of 1539

SQL Reference Manual
SQL Data Types

Note: If you omit the Interval-Qualifier, the interval type defaults to DAY TO SECOND(6).
Command

Result

SELECT INTERVAL '00:2500:00';

1 17:40

SELECT INTERVAL '2500' MINUTE TO SECOND;

2500

SELECT INTERVAL '2500' MINUTE;

2500

SELECT INTERVAL '28 days 3 hours' HOUR TO SECOND;

675:00

SELECT INTERVAL(3) '28 days 3 hours';

28 03:00

SELECT INTERVAL(3) '28 days 3 hours 1.234567';

28 03:01:14.0
74

SELECT INTERVAL(3) '28 days 3 hours 1.234567 sec';

28 03:00:01.2
35

SELECT INTERVAL(3) '28 days 3.3 hours' HOUR TO SECOND;

675:18

SELECT INTERVAL(3) '28 days 3.35 hours' HOUR TO SECOND;

675:21

SELECT INTERVAL(3) '28 days 3.37 hours' HOUR TO SECOND;

675:22:12

SELECT INTERVAL '1.234567 days' HOUR TO SECOND;

29:37:46.5888

SELECT INTERVAL '1.23456789 days' HOUR TO SECOND;

29:37:46.6656
96

SELECT INTERVAL(3) '1.23456789 days' HOUR TO SECOND;

29:37:46.666

SELECT INTERVAL(3) '1.23456789 days' HOUR TO SECOND(2);

29:37:46.67

SELECT INTERVAL(3) '01:00:01.234567' as "one hour+";

01:00:01.235

SELECT INTERVAL(3) '01:00:01.234567' = INTERVAL(3) '01:00:01.234567';

t

SELECT INTERVAL(3) '01:00:01.234567' = INTERVAL '01:00:01.234567';

f

SELECT INTERVAL(3) '01:00:01.234567' = INTERVAL '01:00:01.234567' HOUR TO SE
COND(3);

t

SELECT INTERVAL(3) '01:00:01.234567' = INTERVAL '01:00:01.234567'MINUTE TO S
ECOND(3);

t

SELECT INTERVAL '255 1.1111' MINUTE TO SECOND(3);

255:01.111

SELECT INTERVAL '@ - 5 ago';

5

SELECT INTERVAL '@ - 5 minutes ago';

00:05

SELECT INTERVAL '@ 5 minutes ago';

-00:05

SELECT INTERVAL '@ ago -5 minutes';

00:05

SELECT DATE_PART('month', INTERVAL '2-3' YEAR TO MONTH);

3

SELECT FLOOR((TIMESTAMP '2005-01-17 10:00' - TIMESTAMP '2005-01-01') / INTER
VAL '7');

2

HP Vertica Analytic Database (7.0.x)

Page 131 of 1539

SQL Reference Manual
SQL Data Types

See Also
l

Interval Values

l

SET INTERVALSTYLE

l

SET DATESTYLE

l

AGE_IN_MONTHS

l

AGE_IN_YEARS

Interval-Literal
The following table lists the units allowed for the required interval-literal parameter.
Unit

Description

a

Julian year, 365.25 days exactly

ago

Indicates negative time offset

c, cent, century

Century

centuries

Centuries

d, day

Day

days

Days

dec, decade

Decade

decades, decs

Decades

h, hour, hr

Hour

hours, hrs

Hours

ka

Julian kilo-year, 365250 days exactly

m

Minute or month for year/month, depending on context. See
Notes below this table.

microsecond

Microsecond

microseconds

Microseconds

mil, millennium

Millennium

millennia, mils

Millennia

HP Vertica Analytic Database (7.0.x)

Page 132 of 1539

SQL Reference Manual
SQL Data Types

Unit

Description

millisecond

Millisecond

milliseconds

Milliseconds

min, minute, mm

Minute

mins, minutes

Minutes

mon, month

Month

mons, months

Months

ms, msec, millisecond

Millisecond

mseconds, msecs

Milliseconds

q, qtr, quarter

Quarter

qtrs, quarters

Quarters

s, sec, second

Second

seconds, secs

Seconds

us, usec

Microsecond

microseconds, useconds, usecs

Microseconds

w, week

Week

weeks

Weeks

y, year, yr

Year

years, yrs

Years

Processing the Input Unit 'm'
The input unit 'm' can represent either 'months' or 'minutes,' depending on the context. For
instance, the following command creates a one-column table with an interval value:
=> CREATE TABLE int_test(i INTERVAL YEAR TO MONTH);

In the first INSERT statement, the values are inserted as 1 year, six months:
=> INSERT INTO int_test VALUES('1 year 6 months');

The second INSERT statement results in an error from specifying minutes for a YEAR TO MONTH
interval. At runtime, the result will be a NULL:

HP Vertica Analytic Database (7.0.x)

Page 133 of 1539

SQL Reference Manual
SQL Data Types

=> INSERT INTO int_test VALUES('1 year 6 minutes');
ERROR: invalid input syntax for type interval year to month: "1 year 6 minutes"

In the third INSERT statement, the 'm' is processed as months (not minutes), because DAY TO
SECOND is truncated:
=> INSERT INTO int_test VALUES('1 year 6 m');
-- the m counts as months

The table now contains two identical values, with no minutes:
=> SELECT * FROM int_test;
i
----1 year 6 months
1 year 6 months
(2 rows)

In the following command, the 'm' counts as minutes, because the DAY TO SECOND interval-qualifier
extracts day/time values from the input:
=> SELECT INTERVAL '1y6m' DAY TO SECOND;
?column?
----------365 days 6 mins
(1 row)

Interval-Qualifier
The following table lists the optional interval qualifiers. Values in INTERVAL fields, other than
SECOND, are integers with a default precision of 2 when they are not the first field.
You cannot combine day/time and year/month qualifiers. For example, the following intervals are
not allowed:
l

DAY TO YEAR

l

HOUR TO MONTH

Interval
Type
Day/time
intervals

Units

Valid interval-literal entries

DAY

Unconstrained.

DAY TO HOUR

An interval that represents a span of days and hours.

DAY TO MINUTE

An interval that represents a span of days and minutes.

HP Vertica Analytic Database (7.0.x)

Page 134 of 1539

SQL Reference Manual
SQL Data Types

Interval
Type

Units

Valid interval-literal entries

DAY TO SECOND

(Default) interval that represents a span of days, hours,
minutes, seconds, and fractions of a second if subtype
unspecified.

HOUR

Hours within days.

HOUR TO MINUTE

An interval that represents a span of hours and minutes.

HOUR TO SECOND

An interval that represents a span of hours and seconds.

MINUTE

Minutes within hours.

MINUTE TO SECOND

An interval that represents a span of minutes and seconds.

SECOND

Seconds within minutes.
Note: The SECOND field can have an interval fractional seconds
precision, which indicates the number of decimal digits
maintained following the decimal point in the SECONDS value.
When SECOND is not the first field, it has a precision of 2 places
before the decimal point.

Year/month MONTH
intervals

Months within year.

YEAR

Unconstrained.

YEAR TO MONTH

An interval that represents a span of years and months.

SMALLDATETIME
SMALLDATETIME is an alias for TIMESTAMP.

HP Vertica Analytic Database (7.0.x)

Page 135 of 1539

SQL Reference Manual
SQL Data Types

TIME
Consists of a time of day with or without a time zone.

Syntax
TIME [ (p) ] [ { WITH | WITHOUT } TIME ZONE ] | TIMETZ
[ AT TIME ZONE ]

Parameters
p

(Precision) specifies the number of fractional digits retained in the seconds
field. By default, there is no explicit bound on precision. The allowed range 0
to 6.

WITH TIME ZONE

Specifies that valid values must include a time zone

WITHOUT TIME ZONE

Specifies that valid values do not include a time zone (default). If a time zone
is specified in the input it is silently ignored.

TIMETZ

This is the same as TIME WITH TIME ZONE with no precision

Limits
Name

Low Value

High Value

Resolution

TIME [p]

00:00:00.00

23:59:60.999999

1 µs

TIME [p] WITH TIME ZONE

00:00:00.00+14 23:59:59.999999-14 1 µs

Example

Description

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

HP Vertica Analytic Database (7.0.x)

Page 136 of 1539

SQL Reference Manual
SQL Data Types

Example

Description

04:05-08:00

ISO 8601

040506-08

ISO 8601

04:05:06 PST

Time zone specified by name

Notes
l

HP Vertica permits coercion from TIME and TIME WITH TIME ZONE types to TIMESTAMP or
TIMESTAMP WITH TIME ZONE or INTERVAL (Day to Second).

l

HP Vertica supports adding milliseconds to a TIME or TIMETZ value.
=>
=>
=>
=>
=>

CREATE TABLE temp (datecol TIME);
INSERT INTO temp VALUES (TIME '12:47:32.62');
INSERT INTO temp VALUES (TIME '12:55:49.123456');
INSERT INTO temp VALUES (TIME '01:08:15.12374578');
SELECT * FROM temp;
datecol
----------------12:47:32.62
12:55:49.123456
01:08:15.123746
(3 rows)

See Also
l

Data Type Coercion Chart

TIME AT TIME ZONE
The TIME AT TIME ZONE construct converts TIMESTAMP and TIMESTAMP WITH ZONE types to
different time zones.
TIME ZONE is a synonym for TIMEZONE. Both are allowed in HP Vertica syntax.

Syntax
timestamp AT TIME ZONE zone

HP Vertica Analytic Database (7.0.x)

Page 137 of 1539

SQL Reference Manual
SQL Data Types

Parameters
timestamp

zone

TIMESTAMP

Converts UTC to local time in given time
zone

TIMESTAMP WITH TIME ZONE

Converts local time in given time zone to
UTC

TIME WITH TIME ZONE

Converts local time across time zones

Desired time zone specified either as a text string (for example: 'PST') or as an
interval (for example: INTERVAL '-08:00'). In the text case, the available zone
names are abbreviations.
The files in /opt/vertica/share/timezonesets define the default list of strings
accepted in the zone parameter

Examples
The local time zone is PST8PDT. The first example takes a zone-less timestamp and interprets it as
MST time (UTC-7) to produce a UTC timestamp, which is then rotated to PST (UTC-8) for display:
=> SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
timezone
-----------------------2001-02-16 22:38:40-05
(1 row)

The second example takes a timestamp specified in EST (UTC-5) and converts it to local time in
MST (UTC-7):
=> SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
timezone
--------------------2001-02-16 18:38:40
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 138 of 1539

SQL Reference Manual
SQL Data Types

TIMESTAMP
Consists of a date and a time with or without a time zone and with or without a historical epoch (AD
or BC).

Syntax
TIMESTAMP [ (p) ] [ { WITH | WITHOUT } TIME ZONE ] | TIMESTAMPTZ[

AT TIME ZONE

]

Parameters
p

Optional precision value that 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 0 to 6.

WITH TIME ZONE

Specifies that valid values must include a time zone. All TIMESTAMP WITH
TIME ZONE values are stored internally in UTC.
They are converted to local time in the zone specified by the time zone
configuration parameter before being displayed to the client.

WITHOUT TIME ZONE

Specifies that valid values do not include a time zone (default). If a time zone
is specified in the input it is silently ignored.

TIMESTAMPTZ

This is the same as TIMESTAMP WITH TIME ZONE.

Limits
In the following table, values are rounded. See Date/Time Data Types for additional detail.
Name

Low Value High Value Resolution

TIMESTAMP [ (p) ] [ WITHOUT TIME ZONE ]

290279 BC

294277 AD

1 µs

TIMESTAMP [ (p) ] WITH TIME ZONE

290279 BC

294277 AD

1 µs

Notes
l

TIMESTAMP is an alias for DATETIMEand SMALLDATETIME.

l

Valid input for TIMESTAMP types consists of a concatenation of a date and a time, followed by an
optional time zone, followed by an optional AD or BC.

l

AD/BC can appear before the time zone, but this is not the preferred ordering.

l

The SQL standard differentiates TIMESTAMP WITHOUT TIME ZONE and TIMESTAMP WITH TIME

HP Vertica Analytic Database (7.0.x)

Page 139 of 1539

SQL Reference Manual
SQL Data Types

ZONE literals by the existence of a "+"; or "-". Hence, according to the standard:
TIMESTAMP '2004-10-19 10:23:54' is a TIMESTAMP WITHOUT TIME ZONE.
TIMESTAMP '2004-10-19 10:23:54+02' is a TIMESTAMP WITH TIME ZONE.
Note: HP Vertica differs from the standard by requiring that TIMESTAMP WITH TIME ZONE
literals be explicitly typed:
TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
l

If a literal is not explicitly indicated as being of TIMESTAMP WITH TIME ZONE, HP Vertica silently
ignores any time zone indication in the literal. That is, the resulting date/time value is derived
from the date/time fields in the input value, and is not adjusted for time zone.

l

For TIMESTAMP WITH TIME ZONE, the internally stored value is always in UTC. 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 TIME ZONE parameter, and is converted to UTC using the offset for
the TIME ZONE zone.

l

When a TIMESTAMP WITH TIME ZONE value is output, it is always converted from UTC to the
current TIME ZONE zone and displayed as local time in that zone. To see the time in another time
zone, either change TIME ZONE or use the AT TIME ZONE construct.

l

Conversions between TIMESTAMP WITHOUT TIME ZONE and TIMESTAMP WITH TIME ZONE
normally assume that the TIMESTAMP WITHOUT TIME ZONE value are taken or given as TIME
ZONE local time. A different zone reference can be specified for the conversion using AT TIME
ZONE.

l

TIMESTAMPTZ and TIMETZ are not parallel SQL constructs. TIMESTAMPTZ records a time and date
in GMT, converting from the specified TIME ZONE. TIMETZ records the specified time and the
specified time zone, in minutes, from GMT.timezone

l

The following list represents typical date/time input variations:
n

1999-01-08 04:05:06

n

1999-01-08 04:05:06 -8:00

n

January 8 04:05:06 1999 PST

l

HP Vertica supports adding a floating-point (in days) to a TIMESTAMP or TIMESTAMPTZ
value.

l

HP Vertica supports adding milliseconds to a TIMESTAMP or TIMESTAMPTZ value.

l

In HP Vertica, intervals are represented internally as some number of microseconds and printed
as up to 60 seconds, 60 minutes, 24 hours, 30 days, 12 months, and as many years as
necessary. Fields are either positive or negative.

HP Vertica Analytic Database (7.0.x)

Page 140 of 1539

SQL Reference Manual
SQL Data Types

Examples
You can return infinity by specifying 'infinity':
=> SELECT TIMESTAMP 'infinity';
timestamp
----------infinity
(1 row)

To use the minimum TIMESTAMP value lower than the minimum rounded value:
=> SELECT '-infinity'::timestamp;
timestamp
-----------infinity
(1 row)

TIMESTAMP/TIMESTAMPTZ has +/-infinity values.
AD/BC can be placed almost anywhere within the input string; for example:
SELECT TIMESTAMPTZ 'June BC 1, 2000 03:20 PDT';
timestamptz
--------------------------2000-06-01 05:20:00-05 BC
(1 row)

Notice the results are the same if you move the BC after the 1:
SELECT TIMESTAMPTZ 'June 1 BC, 2000 03:20 PDT';
timestamptz
--------------------------2000-06-01 05:20:00-05 BC
(1 row)

And the same if you place the BC in front of the year:
SELECT TIMESTAMPTZ 'June 1, BC 2000 03:20 PDT';
timestamptz
--------------------------2000-06-01 05:20:00-05 BC
(1 row);

The following example returns the year 45 before the Common Era:
=> SELECT TIMESTAMP 'April 1, 45 BC';
timestamp
-----------------------0045-04-01 00:00:00 BC

HP Vertica Analytic Database (7.0.x)

Page 141 of 1539

SQL Reference Manual
SQL Data Types

(1 row)

If you omit the BC from the date input string, the system assumes you want the year 45 in the
current century:
=> SELECT TIMESTAMP 'April 1, 45';
timestamp
--------------------2045-04-01 00:00:00
(1 row)

In the following example, HP Vertica returns results in years, months, and days, whereas other
RDBMS might return results in days only:
=> SELECT TIMESTAMP WITH TIME ZONE '02/02/294276'- TIMESTAMP WITHOUT TIME ZONE '02/20/200
9' AS result;
result
-----------------------------292266 years 11 mons 12 days
(1 row)

To specify a specific time zone, add it to the statement, such as the use of 'ACST' in the following
example:
=> SELECT T1 AT TIME ZONE 'ACST', t2 FROM test;
timezone
| t2
---------------------+------------2009-01-01 04:00:00 | 02:00:00-07
2009-01-01 01:00:00 | 02:00:00-04
2009-01-01 04:00:00 | 02:00:00-06

You can specify a floating point in days:
=> SELECT 'NOW'::TIMESTAMPTZ + INTERVAL '1.5 day' AS '1.5 days from now';
1.5 days from now
------------------------------2009-03-18 21:35:23.633-04
(1 row)

The following example illustrates the difference between TIMESTAMPTZ with and without a
precision specified:
=> SELECT TIMESTAMPTZ(3) 'now', TIMESTAMPTZ 'now';
timestamptz
timestamptz
----------------------------+------------------------------2009-02-24 11:40:26.177-05 | 2009-02-24 11:40:26.177368-05
(1 row)

|

The following statement returns an error because the TIMESTAMP is out of range:

HP Vertica Analytic Database (7.0.x)

Page 142 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT TIMESTAMP '294277-01-09 04:00:54.775808';
ERROR: date/time field value out of range: "294277-01-09 04:00:54.775808"

There is no 0 AD, so be careful when you subtract BC years from AD years:
=> SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
date_part
----------2001
(1 row)

The following commands create a table with a TIMESTAMP column that contains milliseconds:
CREATE TABLE temp (datecol TIMESTAMP);
INSERT INTO temp VALUES (TIMESTAMP '2010-03-25 12:47:32.62');
INSERT INTO temp VALUES (TIMESTAMP '2010-03-25 12:55:49.123456');
INSERT INTO temp VALUES (TIMESTAMP '2010-03-25 01:08:15.12374578');
SELECT * FROM temp;
datecol
---------------------------2010-03-25 12:47:32.62
2010-03-25 12:55:49.123456
2010-03-25 01:08:15.123746
(3 rows)

Additional Examples
Command

Result

select (timestamp '2005-01-17 10:00' - timestamp '2005-01-01');

16 10:10

select (timestamp '2005-01-17 10:00' - timestamp '2005-01-01') / 7;

2 08:17:08.571429

select (timestamp '2005-01-17 10:00' - timestamp '2005-01-01') day;

16

select cast((timestamp '2005-01-17 10:00' - timestamp '2005-01-01') d
ay as integer) / 7;

2

select floor((timestamp '2005-01-17 10:00' - timestamp '2005-01-01')
/ interval '7');

2

select timestamptz '2009-05-29 15:21:00.456789';

2009-05-2915:21:00.4
56789-04

select timestamptz '2009-05-28';

2009-05-2800:00:00-0
4

select timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0528';

1 15:21:00.456789

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28');

1 15:21:00.456789

HP Vertica Analytic Database (7.0.x)

Page 143 of 1539

SQL Reference Manual
SQL Data Types

Command

Result

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28')(3);

1 15:21:00.457

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28')second;

141660.456789

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') year;

0

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2007-0
1-01') month;

28

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2007-0
1-01') year;

2

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2007-0
1-01') year to month;

2-4

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') second(3);

141660.457

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') minute(3);

2361

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') minute;

2361

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') minute to second(3);

2361:00.457

select (timestamptz '2009-05-29 15:21:00.456789'-timestamptz '2009-0
5-28') minute to second;

2361:00.456789

TIMESTAMP AT TIME ZONE
The TIMESTAMP AT TIME ZONE (or TIMEZONE) construct converts TIMESTAMP and TIMESTAMP WITH
TIMEZONE intervals to different time zones.
Note: TIME ZONE is a synonym for TIMEZONE. Both are allowed in HP Vertica syntax.

Syntax
timestamp AT TIME ZONE zone

HP Vertica Analytic Database (7.0.x)

Page 144 of 1539

SQL Reference Manual
SQL Data Types

Parameters
timestamp

zone

TIMESTAMP

Converts UTC to local time in the given
time zone

TIMESTAMP WITH TIME ZONE

Converts local time in given time zone to
UTC

TIME

Converts local time.

TIME WITH TIME ZONE

Converts local time across time zones

Specifies the time zone either as a text string, (such as 'America/Chicago') or as
an interval (INTERVAL '-08:00'). The preferred way to express a time zone is in the
format 'America/Chicago'.
For a list of time zone text strings, see TZ Environment Variable in the Installation
Guide.
To view the default list of acceptable strings for the zone parameter, see the files in:
/opt/vertica/share/timezonesets

Examples
If you indicate a TIME interval timezone (such as America/Chicago in the following example), the
interval function converts the interval to the timezone you specify and includes the UTC offset
value (-05 here):
=> select time '10:00' at time zone 'America/Chicago';
?column?
--------------------09:00:00-05
(1 row)

Casting a TIMESTAMPTZ interval to a TIMESTAMP without a zone depends on the local time
zone.
=> select (varchar '2013-03-31 5:10 AMERICA/CHICAGO')::timestamp;
?column?
--------------------2013-03-31 06:10:00
(1 row)

Note: For a complete list of valid time zone definitions, see Wikipedia - tz database time
zones.
Casting a TIME (or TIMETZ) interval to a TIMESTAMP returns the local date and time, without the
UTC offset:

HP Vertica Analytic Database (7.0.x)

Page 145 of 1539

SQL Reference Manual
SQL Data Types

=> select (time '3:01am')::timestamp;
?column?
--------------------2012-08-30 03:01:00
(1 row)
=> select (timetz '3:01am')::timestamp;
?column?
--------------------2012-08-22 03:01:00
(1 row)

Casting the same interval (TIME or TIMETZ) to a TIMESTAMPTZ returns the local date and time
appended with the UTC offset (-04 here):
=> select (time '3:01am')::timestamptz;
?column?
--------------------2012-08-30 03:01:00-04
(1 row)

Long Data Types
Store data up to 32,000,000 bytes:
l

LONG VARBINARY—Variable-length raw-byte data, such as IP addresses. LONG VARBINARY
values are not extended to the full width of the column.

l

LONG VARCHAR—Variable-length strings of letters, numbers, and symbols. LONG VARCHAR values
are not extended to the full width of the column.

The maximum size for the LONG data types is 32,000,000 bytes. Use the LONG data types only when
you need to store data greater than 65,000 bytes, which is the maximum size for VARBINARY and
VARCHAR data types. Such data might include unstructured data, online comments or posts, or small
log files.

Syntax
LONG VARBINARY ( max_length )
LONG VARCHAR ( octet_length )

Parameters
max_length

Specifies the length of the byte string (column width, declared in bytes (octets)), in
CREATE TABLE statements). Maximum value: 32,000,000.

octet_length

Specifies the length of the string (column width, declared in bytes (octets)), in
CREATE TABLE statements). Maximum value: 32,000,000.

HP Vertica Analytic Database (7.0.x)

Page 146 of 1539

SQL Reference Manual
SQL Data Types

Notes
Data type coercion for the LONG data types is limited. HP Vertica only supports coercion from LONG
VARBINARY to VARCHAR and vice versa. Converting a data type from a shorter type to a longer type is
implicit; to convert from a longer type to a shorter type requires an explicit cast.
For optimal performance of LONG data types, HP Vertica recommends that you:
l

Use the LONG data types as "storage only" containers; HP Vertica does not support operations
on their content.

l

Use the VARBINARY and VARCHAR data types, instead of their LONG counterparts, whenever
possible. The VARBINARY and VARCHAR data types are more flexible and have a wider range of
operations.

l

Use efficient encoding formats for LONG data types, even if the decoded value is less than
32,000,000. For example, HP Vertica returns an error if you attempt to load a 32,000,000-byte
LONG VARBINARY value encoded in octal format, because the octal encoding quadruples the size
of the value; each byte is converted into a backslash followed by three-digit values.

l

Do not sort, segment, or partition projections on LONG data type columns.

l

Do not add constraints, such as primary key, to any LONG VARBINARY or LONG VARCHAR
columns.

l

Do not join or aggregate any LONG data type columns.

Example
The following example creates a table user_comments with a LONG VARCHAR column and inserts
data into it:
=> CREATE TABLE user_comments VALUES
(
id INTEGER,
username VARCHAR(200)
time_posted TIMESTAMP,
comment_text LONG VARCHAR(200000)
);
=> INSERT INTO user_comments VALUES
(
1,
'User1',
TIMESTAMP '2013-06-25 12:47:32.62',
'The weather tomorrow will be cold and rainy and then
on the day after, the sun will come and the temperature
will rise dramatically.'
);
=> INSERT INTO user_comments VALUES
(
2,
'User2',
TIMESTAMP '2013-06-25 12:55:49.123456',

HP Vertica Analytic Database (7.0.x)

Page 147 of 1539

SQL Reference Manual
SQL Data Types

'To get to the main library entrance, take Exit 21,
turn left at the end of the exit ramp onto Rt. 333,
travel four miles, and the parking lot will be on the
left-hand side of the street.'
);
=> INSERT INTO user_comments VALUES (
(
3,
'User3',
TIMESTAMP '2013-06-25 01:08:15.12374578',
'To purchase your tickets for this event, contact
the box office. Tickets will be sold on a first-come,
first-serve basis, and are nonrefundable.'
);

HP Vertica Analytic Database (7.0.x)

Page 148 of 1539

SQL Reference Manual
SQL Data Types

Numeric Data Types
Numeric data types are numbers stored in database columns. These data types are typically
grouped by:
l

Exact numeric types, values where the precision and scale need to be preserved. The exact
numeric types are BIGINT, DECIMAL, INTEGER, NUMERIC, NUMBER, and MONEY.

l

Approximate numeric types, values where the precision needs to be preserved and the scale
can be floating. The approximate numeric types are DOUBLE PRECISION, FLOAT, and REAL.

Implicit casts from INTEGER, FLOAT, and NUMERIC to VARCHAR are not supported. If you need that
functionality, write an explicit cast using one of the following forms:
CAST(x AS data-type-name) or x::data-type-name

The following example casts a float to an integer:
=> SELECT(FLOAT '123.5')::INT;
?column?
---------124
(1 row)

String-to-numeric data type conversions accept formats of quoted constants for scientific notation,
binary scaling, hexadecimal, and combinations of numeric-type literals:
l

Scientific notation:
=> SELECT FLOAT '1e10';
?column?
------------10000000000
(1 row)

l

BINARY scaling:
=> SELECT NUMERIC '1p10';
?column?
---------1024
(1 row)

l

Hexadecimal:
=> SELECT NUMERIC '0x0abc';

HP Vertica Analytic Database (7.0.x)

Page 149 of 1539

SQL Reference Manual
SQL Data Types

?column?
---------2748
(1 row)

DOUBLE PRECISION (FLOAT)
HP Vertica supports the numeric data type DOUBLE PRECISION, which is the IEEE-754 8-byte
floating point type, along with most of the usual floating point operations.

Syntax
[ DOUBLE PRECISION | FLOAT | FLOAT(n) | FLOAT8 | REAL ]

Parameters
Note: On a machine whose floating-point arithmetic does not follow IEEE-754, these values
probably do not work as expected.
Double precision is an inexact, variable-precision numeric type. In other words, some values
cannot be represented exactly and are stored as approximations. Thus, input and output operations
involving double precision might show slight discrepancies.
l

All of the DOUBLE PRECISION data types are synonyms for 64-bit IEEE FLOAT.

l

The n in FLOAT(n) must be between 1 and 53, inclusive, but a 53-bit fraction is always used.
See the IEEE-754 standard for details.

l

For exact numeric storage and calculations (money for example), use NUMERIC.

l

Floating point calculations depend on the behavior of the underlying processor, operating
system, and compiler.

l

Comparing two floating-point values for equality might not work as expected.

Values
COPY accepts floating-point data in the following format:
l

Optional leading white space

l

An optional plus ("+") or minus sign ("-")

l

A decimal number, a hexadecimal number, an infinity, a NAN, or a null value

HP Vertica Analytic Database (7.0.x)

Page 150 of 1539

SQL Reference Manual
SQL Data Types

A decimal number consists of a non-empty sequence of decimal digits possibly containing a radix
character (decimal point "."), optionally followed by a decimal exponent. A decimal exponent
consists of an "E" or "e", followed by an optional plus or minus sign, followed by a non-empty
sequence of decimal digits, and indicates multiplication by a power of 10.
A hexadecimal number consists of a "0x" or "0X" followed by a non-empty sequence of
hexadecimal digits possibly containing a radix character, optionally followed by a binary exponent.
A binary exponent consists of a "P" or "p", followed by an optional plus or minus sign, followed by a
non-empty sequence of decimal digits, and indicates multiplication by a power of 2. At least one of
radix character and binary exponent must be present.
An infinity is either INF or INFINITY, disregarding case.
A NaN (Not A Number) is NAN (disregarding case) optionally followed by a sequence of characters
enclosed in parentheses. The character string specifies the value of NAN in an implementationdependent manner. (The HP Vertica internal representation of NAN is 0xfff8000000000000LL on
x86 machines.)
When writing infinity or NAN values as constants in a SQL statement, enclose them in single
quotes. For example:
=> UPDATE table SET x = 'Infinity'

Note: HP Vertica follows the IEEE definition of NaNs (IEEE 754). The SQL standards do not
specify how floating point works in detail.
IEEE defines NaNs as a set of floating point values where each one is not equal to anything,
even to itself. A NaN is not greater than and at the same time not less than anything, even
itself. In other words, comparisons always return false whenever a NaN is involved.
However, for the purpose of sorting data, NaN values must be placed somewhere in the result.
The value generated 'NaN' appears in the context of a floating point number matches the NaN
value generated by the hardware. For example, Intel hardware generates
(0xfff8000000000000LL), which is technically a Negative, Quiet, Non-signaling NaN.
HP Vertica uses a different NaN value to represent floating point NULL (0x7ffffffffffffffeLL).
This is a Positive, Quiet, Non-signaling NaN and is reserved by HP Vertica
The load file format of a null value is user defined, as described in the COPY command. The HP
Vertica internal representation of a null value is 0x7fffffffffffffffLL. The interactive format is
controlled by the vsql printing option null. For example:
\pset null '(null)'

The default option is not to print anything.

HP Vertica Analytic Database (7.0.x)

Page 151 of 1539

SQL Reference Manual
SQL Data Types

Rules
l

-0 == +0

l

1/0 = Infinity

l

0/0 == Nan

l

NaN != anything (even NaN)

To search for NaN column values, use the following predicate:
... WHERE column != column

This is necessary because WHERE column = 'Nan' cannot be true by definition.

Sort Order (Ascending)
l

NaN

l

-Inf

l

numbers

l

+Inf

l

NULL

Notes
l

NULL appears last (largest) in ascending order.

l

All overflows in floats generate +/-infinity or NaN, per the IEEE floating point standard.

INTEGER
A signed 8-byte (64-bit) data type.

Syntax
[ INTEGER | INT | BIGINT | INT8 | SMALLINT | TINYINT ]

Parameters
INT, INTEGER, INT8, SMALLINT, TINYINT, and BIGINT are all synonyms for the same signed 64-bit
integer data type. Automatic compression techniques are used to conserve disk space in cases
where the full 64 bits are not required.

HP Vertica Analytic Database (7.0.x)

Page 152 of 1539

SQL Reference Manual
SQL Data Types

Notes
l

The range of values is –2^63+1 to 2^63-1.

l

2^63 = 9,223,372,036,854,775,808 (19 digits).

l

The value –2^63 is reserved to represent NULL.

l

NULL appears first (smallest) in ascending order.

l

HP Vertica does not have an explicit 4-byte (32-bit integer) or smaller types. HP Vertica's
encoding and compression automatically eliminate the storage overhead of values that fit in less
than 64 bits.

Restrictions
l

The JDBC type INTEGER is 4 bytes and is not supported by HP Vertica. Use BIGINT instead.

l

HP Vertica does not support the SQL/JDBC types NUMERIC, SMALLINT, or TINYINT.

l

HP Vertica does not check for overflow (positive or negative) except in the aggregate function
SUM(). If you encounter overflow when using SUM, use SUM_FLOAT(), which converts to floating
point.

See Also
Data Type Coercion Chart

NUMERIC
Numeric data types store numeric data. For example, a money value of $123.45 can be stored in a
NUMERIC(5,2) field.

Syntax
NUMERIC | DECIMAL | NUMBER | MONEY [ ( precision [ , scale ] ) ]

Parameters
precision

The total number of significant digits that the data type stores. precision must be
positive and <= 1024. If you assign a value that exceeds the precision value, an error
occurs.

scale

The maximum number of digits to the right of the decimal point that the data type
stores. scale must be non-negative and less than or equal to precision. If you omit the
scale parameter, the scale value is set to 0. If you assign a value with more decimal
digits than scale, the value is rounded to scale digits.

HP Vertica Analytic Database (7.0.x)

Page 153 of 1539

SQL Reference Manual
SQL Data Types

Notes
l

l

NUMERIC, DECIMAL, NUMBER, and MONEY are all synonyms that return NUMERIC types. However,
the default values NUMBER and MONEY are different.
Type

Precision

Scale

NUMERIC

37

15

DECIMAL

37

15

NUMBER

38

0

MONEY

18

4

NUMERIC data types support exact representations of numbers that can be expressed with a
number of digits before and after a decimal point. This contrasts slightly with existing HP Vertica
data types:
n

DOUBLE PRECISION (FLOAT) types support ~15 digits, variable exponent, and represent
numeric values approximately.

n

INTEGER (and similar) types support ~18 digits, whole numbers only.

l

NUMERIC data types are generally called exact numeric data types because they store numbers
of a specified precision and scale. The approximate numeric data types, such as DOUBLE
PRECISION, use floating points and are less precise.

l

Supported numeric operations include the following:
n

Basic math: +, –, *, /

n

Aggregation: SUM, MIN, MAX, COUNT

n

Comparison operators: <, <=, =, <=>, <>, >, >=

l

NUMERIC divide operates directly on numeric values, without converting to floating point. The
result has at least 18 decimal places and is rounded.

l

NUMERIC mod (including %) operates directly on numeric values, without converting to floating
point. The result has the same scale as the numerator and never needs rounding.

l

NULL appears first (smallest) in ascending order.

l

COPY accepts a DECIMAL data type with a decimal point ('.'), prefixed by – or +(optional).

l

LZO, RLE, and BLOCK_DICT are supported encoding types. Anything that can be used on an
INTEGER can also be used on a NUMERIC, as long as the precision is <= 18.

l

The NUMERIC data type is preferred for non-integer constants, because it is always exact. For

HP Vertica Analytic Database (7.0.x)

Page 154 of 1539

SQL Reference Manual
SQL Data Types

example:
=> SELECT 1.1 + 2.2 = 3.3;
?column?
---------t
(1 row)
=> SELECT 1.1::float + 2.2::float = 3.3::float;
?column?
---------f
(1 row)

l

Performance of the NUMERIC data type has been fine tuned for the common case of 18 digits of
precision.

l

Some of the more complex operations used with NUMERIC data types result in an implicit cast to
FLOAT. When using SQRT, STDDEV, transcendental functions such as LOG, and TO_CHAR/TO_
NUMBER formatting, the result is always FLOAT.

Examples
The following series of commands creates a table that contains a NUMERIC data type and then
performs some mathematical operations on the data:
=> CREATE TABLE num1 (id INTEGER, amount NUMERIC(8,2));

Insert some values into the table:
=> INSERT INTO num1 VALUES (1, 123456.78);

Query the table:
=> SELECT * FROM num1;
id | amount
------+----------1 | 123456.78
(1 row)

The following example returns the NUMERIC column, amount, from table num1:
=> SELECT amount FROM num1;
amount
----------123456.78
(1 row)

The following syntax adds one (1) to the amount:

HP Vertica Analytic Database (7.0.x)

Page 155 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT amount+1 AS 'amount' FROM num1;
amount
----------123457.78
(1 row)

The following syntax multiplies the amount column by 2:
=> SELECT amount*2 AS 'amount' FROM num1;
amount
----------246913.56
(1 row)

The following syntax returns a negative number for the amount column:
=> SELECT -amount FROM num1;
?column?
------------123456.78
(1 row)

The following syntax returns the absolute value of the amount argument:
=> SELECT ABS(amount) FROM num1;
ABS
----------123456.78
(1 row)

The following syntax casts the NUMERIC amount as a FLOAT data type:
=> SELECT amount::float FROM num1;
amount
----------123456.78
(1 row)

See Also
Mathematical Functions

Numeric Data Type Overflow
HP Vertica does not check for overflow (positive or negative) except in the aggregate function SUM
(). If you encounter overflow when using SUM, use SUM_FLOAT() which converts to floating point.
Dividing zero by zero returns zero:

HP Vertica Analytic Database (7.0.x)

Page 156 of 1539

SQL Reference Manual
SQL Data Types

=> select 0/0;
?column?
---------------------0.000000000000000000
(1 row)
=> select 0.0/0;
?column?
----------------------0.0000000000000000000
=> select 0 // 0;
?column?
---------0

Dividing zero as a FLOAT by zero returns NaN:
=> select 0.0::float/0;
?column?
---------NaN
=> select 0.0::float//0;
?column?
---------NaN

Dividing a non-zero FLOAT by zero returns Infinity:
=> select 2.0::float/0;
?column?
---------Infinity
=> select 200.0::float//0;
?column?
---------Infinity

All other division-by-zero operations return an error:
=> select 1/0;
ERROR 3117: Division by
=> select 200/0;
ERROR 3117: Division by
=> select 200.0/0;
ERROR 3117: Division by
=> select 116.43 // 0;
ERROR 3117: Division by

zero
zero
zero
zero

Add, subtract, and multiply operations ignore overflow. Sum and average operations use 128-bit
arithmetic internally. SUM() reports an error if the final result overflows, suggesting the use of SUM_
FLOAT(INT), which converts the 128-bit sum to a FLOAT8. For example:
=> CREATE TEMP TABLE t (i INT);

HP Vertica Analytic Database (7.0.x)

Page 157 of 1539

SQL Reference Manual
SQL Data Types

=>
=>
=>
=>
=>
=>

INSERT INTO t VALUES (1<<62);
INSERT INTO t VALUES (1<<62);
INSERT INTO t VALUES (1<<62);
INSERT INTO t VALUES (1<<62);
INSERT INTO t VALUES (1<<62);
SELECT SUM(i) FROM t;
ERROR: sum() overflowed
HINT: try sum_float() instead
=> SELECT SUM_FLOAT(i) FROM t;
sum_float
--------------------2.30584300921369e+19

Data Type Coercion
HP Vertica supports two types of data type casting:
l

Implicit casting—Occurs when the expression automatically converts the data from one type to
another.

l

Explicit casting—Occurs when you write a SQL statement that specifies the target data type for
the conversion.

The ANSI SQL-92 standard supports implicit casting between similar data types:
l

Number types

l

CHAR, VARCHAR, LONG VARCHAR

l

BINARY, VARBINARY, LONG VARBINARY

HP Vertica supports two types of non-standard implicit casts:
l

From CHAR to FLOAT, to match the one from VARCHAR to FLOAT. The following example
converts the CHAR '3' to a FLOAT so it can add the number 334 to the FLOAT result of the
second expression:
=> SELECT '3' + 4.33::NUMERIC(3,2);
?column?
---------7.33
(1 row)

l

Between DATE and TIMESTAMP. The following example DATE to a TIMESTAMP and
calculates the time 6 hours, 6 minutes, and 6 seconds back from 12:00 AM:
=> SELECT DATE('now') - INTERVAL '6:6:6';
?column?

HP Vertica Analytic Database (7.0.x)

Page 158 of 1539

SQL Reference Manual
SQL Data Types

--------------------2013-07-30 17:53:54
(1 row)

When there is no ambiguity about the data type of an expression value, it is implicitly coerced to
match the expected data type. In the following command, the quoted string constant '2' is implicitly
coerced into an INTEGER value so that it can be the operand of an arithmetic operator (addition):
=> SELECT 2 + '2';
?column?
---------4
(1 row)

A concatenate operation explicitly takes arguments of any data type. In the following example, the
concatenate operation implicitly coerces the arithmetic expression 2 + 2 and the INTEGER
constant 2 to VARCHAR values so that they can be concatenated.
=> SELECT 2 + 2 || 2;
?column?
---------42
(1 row)

Another example is to first get today's date:
=> SELECT DATE 'now';
?column?
-----------2013-07-31
(1 row)

The following command converts DATE to a TIMESTAMP and adds a day and a half to the results
by using INTERVAL:
=> SELECT DATE 'now' + INTERVAL '1 12:00:00';
?column?
--------------------2013-07-31 12:00:00
(1 row)

Most implicit casts stay within their relational family and go in one direction, from less detailed to
more detailed. For example:
l

DATE to TIMESTAMP/TZ

l

INTEGER to NUMERIC to FLOAT

l

CHAR to FLOAT

HP Vertica Analytic Database (7.0.x)

Page 159 of 1539

SQL Reference Manual
SQL Data Types

l

CHAR to VARCHAR

l

CHAR and/or VARCHAR to FLOAT

l

CHAR to LONG VARCHAR

l

VARCHAR to LONG VARCHAR

l

BINARY to VARBINARY

l

BINARY to LONG VARBINARY

l

VARBINARY to LONG VARBINARY

More specifically, data type coercion works in this manner in HP Vertica:
Type

Direction Type

Notes

INT8

>

FLOAT8

Implicit, can lose significance

FLOAT8

>

INT8

Explicit, rounds

VARCHAR

<->

CHAR

Implicit, adjusts trailing spaces

VARBINARY <->

BINARY

Implicit, adjusts trailing NULs

VARCHAR

LONG VARCHAR

Implicit, adjusts trailing spaces

>

VARBINARY >

LONG VARBINARY Implicit, adjusts trailing NULs

No other types cast to or from LONGVARBINARY, VARBINARY, or BINARY. In the following list,
 means one these types: INT8, FLOAT8, DATE, TIME, TIMETZ, TIMESTAMP,
TIMESTAMPTZ, INTERVAL.
l

 -> VARCHAR—implicit

l

VARCHAR -> —explicit, except that VARCHAR->FLOAT is implicit

l

 <-> CHAR—explicit

l

DATE -> TIMESTAMP/TZ—implicit

l

TIMESTAMP/TZ -> DATE—explicit, loses time-of-day

l

TIME -> TIMETZ—implicit, adds local timezone

l

TIMETZ -> TIME—explicit, loses timezone

l

TIME -> INTERVAL—implicit, day to second with days=0

l

INTERVAL -> TIME—explicit, truncates non-time parts

HP Vertica Analytic Database (7.0.x)

Page 160 of 1539

SQL Reference Manual
SQL Data Types

l

TIMESTAMP <-> TIMESTAMPTZ—implicit, adjusts to local timezone

l

TIMESTAMP/TZ -> TIME—explicit, truncates non-time parts

l

TIMESTAMPTZ -> TIMETZ—explicit

l

VARBINARY -> LONG VARBINARY—implicit

l

LONG VARBINARY -> VARBINARY—explicit

l

VARCHAR -> LONG VARCHAR—implicit

l

LONG VARCHAR -> VARCHAR—explicit
Important: Implicit casts from INTEGER, FLOAT, and NUMERIC to VARCHAR are not
supported. If you need that functionality, write an explicit cast:
CAST(x AS data-type-name)

or
x::data-type-name

The following example casts a FLOAT to an INTEGER:
=> SELECT(FLOAT '123.5')::INT;
?column?
---------124
(1 row)

String-to-numeric data type conversions accept formats of quoted constants for scientific notation,
binary scaling, hexadecimal, and combinations of numeric-type literals:
l

Scientific notation:
=> SELECT FLOAT '1e10';
?column?
------------10000000000
(1 row)

l

BINARY scaling:
=> SELECT NUMERIC '1p10';
?column?
---------1024
(1 row)

l

Hexadecimal:

HP Vertica Analytic Database (7.0.x)

Page 161 of 1539

SQL Reference Manual
SQL Data Types

=> SELECT NUMERIC '0x0abc';
?column?
---------2748
(1 row)

Examples
The following example casts three strings as NUMERICs:
=> SELECT NUMERIC '12.3e3', '12.3p10'::NUMERIC, CAST('0x12.3p-10e3' AS NUMERIC);
?column? | ?column? |
?column?
----------+----------+------------------12300 | 12595.2 | 17.76123046875000
(1 row)

This example casts a VARBINARY string into a LONG VARBINARY data type:
=> SELECT B'101111000'::LONG VARBINARY;
?column?
---------\001x
(1 row)

The following example concatenates a CHAR with a LONG VARCHAR, resulting in a LONG
VARCHAR:
=> \set s ''''`cat longfile.txt`''''
=> SELECT length ('a' || :s ::LONG VARCHAR);
length
---------65002
(1 row)

The following example casts a combination of NUMERIC and INTEGER data into a NUMERIC
result:
=> SELECT (18. + 3./16)/1024*1000;
?column?
----------------------------------------17.761230468750000000000000000000000000
(1 row)

Note: In SQL expressions, pure numbers between (–2^63–1) and (2^63–1) are INTEGERs.
Numbers with decimal points are NUMERIC.

HP Vertica Analytic Database (7.0.x)

Page 162 of 1539

SQL Reference Manual
SQL Data Types

See Also
l

Data Type Coercion Chart

l

Data Type Coercion Operators (CAST)

Data Type Coercion Chart
Conversion Types
The following table defines all possible type conversions that HP Vertica supports. The values
across the top row are the data types you want, and the values down the first column on the left are
the data types that you have.
Conversion Types

Data Types

Implicit

Explicit

BOOLEAN

Assignment

Assignment
without numeric
meaning

Conversion
without explicit
casting

INTEGER
LONG VARCHAR
VARCHAR
CHAR

INTEGER

BOOLEAN
NUMERIC
FLOAT

INTERVAL
DAY/SECOND
INTERVAL
YEAR/MONTH

LONG VARCHAR
VARCHAR
CHAR

NUMERIC

FLOAT

INTEGER

LONG VARCHAR
VARCHAR
CHAR

INTEGER
NUMERIC

LONG VARCHAR
VARCHAR
CHAR

FLOAT

HP Vertica Analytic Database (7.0.x)

NUMERIC

Page 163 of 1539

SQL Reference Manual
SQL Data Types

Conversion Types
Conversion
without explicit
casting

Data Types

Implicit

Explicit

LONG VARCHAR

FLOAT
CHAR

BOOLEAN
INTEGER
NUMERIC
VARCHAR
TIMESTAMP
TIMESTAMP
WITH TIME
ZONE
DATE
TIME
TIME WITH
TIME ZONE
INTERVAL
DAY/SECOND
INTERVAL
YEAR/MONTH
LONG
VARBINARY

LONG VARCHAR

VARCHAR

FLOAT
LONG VARCHAR
CHAR

BOOLEAN
INTEGER
NUMERIC
TIMESTAMP
TIMESTAMP
WITH TIME
ZONE
DATE
TIME
TIME WITH
TIME ZONE
INTERVAL
DAY/SECOND
INTERVAL
YEAR/MONTH

VARCHAR

CHAR

FLOAT
LONG VARCHAR
VARCHAR

BOOLEAN
INTEGER
NUMERIC
TIMESTAMP
TIMESTAMP
WITH TIME
ZONE
DATE
TIME
TIME WITH
TIME ZONE
INTERVAL
DAY/SECOND
INTERVAL
YEAR/MONTH

CHAR

HP Vertica Analytic Database (7.0.x)

Assignment

Assignment
without numeric
meaning

Page 164 of 1539

SQL Reference Manual
SQL Data Types

Conversion Types

Explicit

Assignment

Assignment
without numeric
meaning

Conversion
without explicit
casting

Data Types

Implicit

TIMESTAMP

TIMESTAMP
WITH TIME
ZONE

LONG CHAR
VARCHAR
CHAR
DATE
TIME

TIMESTAMP

TIMESTAMP
WITH TIME
ZONE

TIMESTAMP

LONG CHAR
VARCHAR
CHAR
DATE
TIME
TIME WITH
TIME ZONE

TIMESTAMP WITH
TIME ZONE

DATE

TIMESTAMP

LONG CHAR
VARCHAR
CHAR
TIMESTAMP
WITH TIME
ZONE

TIME

TIME WITH
TIME ZONE

TIMESTAMP
TIMESTAMP
WITH TIME
ZONE
INTERVAL
DAY/SECOND

LONG CHAR
VARCHAR
CHAR

TIME

TIME WITH
TIME ZONE

TIMESTAMP
TIMESTAMP
WITH TIME
ZONE

LONG CHAR
VARCHAR
CHAR
TIME

TIME WITH TIME
ZONE

INTERVAL
DAY/SECOND

TIME

INTEGER
LONG CHAR
VARCHAR
CHAR

INTERVAL
DAY/SECOND

INTEGER
LONG CHAR
VARCHAR
CHAR

INTERVAL
YEAR/MONTH

INTERVAL
YEAR/MONTH

LONG
VARBINARY

VARBINARY

LONG VARBINARY

VARBINARY

LONG
VARBINARY
BINARY

VARBINARY

BINARY

VARBINARY

BINARY

HP Vertica Analytic Database (7.0.x)

Page 165 of 1539

SQL Reference Manual
SQL Data Types

Notes
l

Implicit conversion converts the source data to the target column's data type when what needs
to be converted is clear. For example, with "INT + NUMERIC -> NUMERIC", the integer is
implicitly cast to numeric(18,0); another precision/scale conversion may occur as part of the
add.

l

In an Assignment conversion, coercion implicitly occurs when values are assigned to database
columns in an INSERT or UPDATE..SET command. For example, in a statement that includes
INSERT ... VALUES('2.5'), where the target column is NUMERIC(18,5), a cast from
VARCHAR to NUMERIC(18,5) is inferred.

l

In Explicit conversion, the source data requires explicit casting to the target column's data type.

l

HP Vertica supports a conversion of data types without explicit casting, such as NUMERIC
(10,6) -> NUMERIC(18,4).

l

In an assignment without numeric meaning, the value is subject to CHAR/VARCHAR/LONG
VARCHAR comparisons.

See Also
l

Data Type Coercion

l

Data Type Coercion Operators (CAST)

HP Vertica Analytic Database (7.0.x)

Page 166 of 1539

SQL Reference Manual
SQL Functions

SQL Functions
Functions return information from the database and are allowed anywhere an expression is allowed.
The exception is HP Vertica-specific functions, which are not allowed everywhere.
Some functions could produce different results on different invocations with the same set of
arguments. The following three categories of functions are defined based on their behavior:
When run with a given set of arguments, immutable functions always produce the same result.
The function is independent of any environment or session settings, such as locale. For example,
2+2 always equals 4. Another immutable function is AVG(). Some immutable functions can take
an optional stable argument; in this case they are treated as stable functions.
l

Immutable (invariant):
When run with a given set of arguments, stable functions produce the same result within a single
query or scan operation. However, a stable function could produce different results when issued
under a different environment, such as a change of locale and time zone. Expressions that could
give different results in the future are also stable, for example SYSDATE() or 'today'.

l

Stable:
Regardless of the arguments or environment, volatile functions can return different results on
multiple invocations. RANDOM() is one example.

l

Volatile:

This chapter describes the functions that HP Vertica supports.
l

Each function is annotated with behavior type as immutable, stable or volatile.

l

All HP Vertica-specific functions can be assumed to be volatile and are not annotated
individually.

HP Vertica Analytic Database (7.0.x)

Page 167 of 1539

SQL Reference Manual
SQL Functions

Aggregate Functions
Note: All functions in this section that have an analytic function counterpart are appended with
[Aggregate] to avoid confusion between the two.
Aggregate functions summarize data over groups of rows from a query result set. The groups are
specified using the GROUP BY clause. They are allowed only in the select list and in the HAVING
and ORDER BY clauses of a SELECT statement (as described in Aggregate Expressions).

Notes
l

Except for COUNT, these functions return a null value when no rows are selected. In particular,
SUM of no rows returns NULL, not zero.

l

In some cases you can replace an expression that includes multiple aggregates with an single
aggregate of an expression. For example SUM(x) + SUM(y) can be expressed as as SUM(x+y)
(where x and y are NOT NULL).

l

HP Vertica does not support nested aggregate functions.

You can also use some of the simple aggregate functions as analytic (window) functions. See
Analytic Functions for details. See also Using SQL Analytics in the Programmer's Guide.

APPROXIMATE_COUNT_DISTINCT
Returns the number of rows in the data set that have distinct non-NULL values.

Behavior Type
Immutable

Syntax
APPROXIMATE_COUNT_DISTINCT ( expr [, error_tolerance ] )

Parameters
expr

Value to be evaluated using any data type that supports equality comparison.

HP Vertica Analytic Database (7.0.x)

Page 168 of 1539

SQL Reference Manual
SQL Functions

error_tolerance

NUMERIC that represents the desired error tolerance, distributed around the
exact COUNT(DISTINCT) value.
l

Default value: 1.0. This value typically gives a 0.4% chance of a getting a
count within three standard deviations of the exact count.

l

Minimum value: 0.078.

l

There is no maximum value, but anything greater than or equal to 5 is
implemented with 5% accuracy.

For detailed information about the error tolerance, see the following Notes
section.

Notes
l

The expected value that APPROXIMATE_COUNT_DISTINCT(x [, error_tolerance]) returns is
equal to COUNT(DISTINCT x), with an error that is lognormally distributed with standard
deviation s. You can control the standard deviation directly by setting the error_tolerance.
The error_tolerance is defined as 2.17 standard deviations, which corresponds to a 97%
confidence interval. For example, setting the error_tolerance to 1% (the default) corresponds to a
standard deviation s = (1 / 100) / 2.17 = 0.0046. If you specify an error_tolerance of 1,
APPROXIMATE_COUNT_DISTINCT(x) returns a value between COUNT(DISTINCT x) / 1.01
and 1.01 * COUNT(DISTINCT x), 97% of the time.
Similarly, specifying error_tolerance = 5 (percent) constrains the value returned by
APPROXIMATE_COUNT_DISTINCT(x) to be between COUNT(DISTINCT x) / 1.05 and 1.05 *
COUNT(DISTINCT x) 97% of the time. The remaining 3% of the time, the errors are larger than
the specified error_tolerance.
A 99% confidence interval corresponds to s = 2.58 standard deviations. To set an error_
tolerance corresponding to a 99% confidence level (instead of a 97% confidence level), multiply
the error_tolerance by 2.17 / 2.58 = 0.841. For example, if you want APPROXIMATE_COUNT_
DISTINCT(x) to return a value between COUNT(DISTINCT x) / 1.05 and 1.05 * COUNT
(DISTINCT x) 99% of the time, specify the error_tolerance as 5 * 0.841 = 4.2.

l

The maximum number of distinct values is in the range of 0 to approximately 2^47, or 1.4*10^14.

l

APPROXIMATE_COUNT_DISTINCT cannot appear in the same query block with DISTINCT
aggregates.

Examples
The following query counts total number of distinct values in the product_key column of the
store.store_sales_fact table:
=> \timing

HP Vertica Analytic Database (7.0.x)

Page 169 of 1539

SQL Reference Manual
SQL Functions

Timing is on.
=> SELECT COUNT(DISTINCT product_key) FROM store.store_sales_fact;
COUNT
------19982
(1 row)
Time: First fetch (1 row): 16.839 ms. All rows formatted: 16.866 ms

The next query counts the approximate number of distinct values in the product_key column with
various error tolerances. The smaller the error_tolerance, the closer the approximation.
=> \timing
Timing is on.
=> SELECT APPROXIMATE_COUNT_DISTINCT(product_key,5) AS five_pct_accuracy,
APPROXIMATE_COUNT_DISTINCT(product_key,1) AS one_pct_accuracy,
APPROXIMATE_COUNT_DISTINCT(product_key,.1) AS point_one_pct_accuracy
FROM store.store_sales_fact;
five_pct_accuracy | one_pct_accuracy | point_one_pct_accuracy
-------------------+------------------+-----------------------19431 |
19921 |
19980
(1 row)
Time: First fetch (1 row): 262.580 ms. All rows formatted: 262.616 ms

The following query counts the distinct values in the date_key and product_key columns.
=> \timing
Timing is on.
=> SELECT COUNT (DISTINCT date_key),
COUNT (DISTINCT product_key)
FROM store.store_sales_fact;
count | count
-------+------1826 | 19982
(1 row)
Time: First fetch (1 row): 207.431 ms. All rows formatted: 207.468 ms

See Also
l

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS

l

APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS

l

COUNT [Aggregate]

APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS
Returns the number of rows in the synopsis object created by APPROXIMATE_COUNT_
DISTINCT_SYNOPSIS that have distinct non-NULL values.

HP Vertica Analytic Database (7.0.x)

Page 170 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS ( expr [, maximum_error_percent ] )

Parameters
expr

Value to be evaluated using any data type that
supports equality comparison.

error_

NUMERIC that represents the desired error tolerance,
distributed around the exact COUNT(DISTINCT)
value.
l

Default value: 1.0. This value typically gives a
0.4% chance of a getting a count within three
standard deviations of the exact count.

l

Minimum value: 0.078.

l

There is no maximum value, but anything greater
than or equal to 5 is implemented with 5%
accuracy.

For detailed information about the error tolerance, see
the following Notes section.

Notes
l

The expected value that APPROXIMATE_COUNT_DISTINCT(x [, error_tolerance]) returns is
equal to COUNT(DISTINCT x), with an error that is lognormally distributed with standard
deviation s. You can control the standard deviation directly by setting the error_tolerance.
The error_tolerance is defined as 2.17 standard deviations, which corresponds to a 97%
confidence interval. For example, setting the error_tolerance to 1% (the default) corresponds to a
standard deviation s = (1 / 100) / 2.17 = 0.0046. If you specify an error_tolerance of 1,
APPROXIMATE_COUNT_DISTINCT(x) returns a value between COUNT(DISTINCT x) / 1.01
and 1.01 * COUNT(DISTINCT x), 97% of the time.
Similarly, specifying error_tolerance = 5 (percent) constrains the value returned by
APPROXIMATE_COUNT_DISTINCT(x) to be between COUNT(DISTINCT x) / 1.05 and 1.05 *

HP Vertica Analytic Database (7.0.x)

Page 171 of 1539

SQL Reference Manual
SQL Functions

COUNT(DISTINCT x) 97% of the time. The remaining 3% of the time, the errors are larger than
the specified error_tolerance.
A 99% confidence interval corresponds to s = 2.58 standard deviations. To set an error_
tolerance corresponding to a 99% confidence level (instead of a 97% confidence level), multiply
the error_tolerance by 2.17 / 2.58 = 0.841. For example, if you want APPROXIMATE_COUNT_
DISTINCT(x) to return a value between COUNT(DISTINCT x) / 1.05 and 1.05 * COUNT
(DISTINCT x) 99% of the time, specify the error_tolerance as 5 * 0.841 = 4.2.
l

The maximum number of distinct values is in the range of 0 to approximately 2^47, or 1.4*10^14.

l

APPROXIMATE_COUNT_DISTINCT cannot appear in the same query block with DISTINCT
aggregates.

Examples
The following example creates the synopsis and then calculates an approximate count of distinct
values in the synopsis.
=> \timing
Timing is on.
=> SELECT product_version,
APPROXIMATE_COUNT_DISTINCT(product_key)
FROM store.store_sales_fact
GROUP BY product_version;
product_version | ApproxCountDistinct
-----------------+--------------------1
|
19921
2
|
15958
3
|
11895
4
|
7935
5
|
3993
(5 rows)
Time: First fetch (5 rows): 2826.318 ms. All rows formatted: 2826.358 ms
=> CREATE TABLE my_summary AS
SELECT product_version,
APPROXIMATE_COUNT_DISTINCT_SYNOPSIS (product_key) syn
FROM store.store_sales_fact
GROUP BY product_version;
CREATE TABLE
=> SELECT APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS
FROM my_summary;
ApproxCountDistinctOfSynopsis
------------------------------19963
(1 row)
Time: First fetch (1 row): 42.994 ms. All rows formatted: 43.021 ms
=>

HP Vertica Analytic Database (7.0.x)

Page 172 of 1539

SQL Reference Manual
SQL Functions

See Also
l

APPROXIMATE_COUNT_DISTINCT

l

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS

l

COUNT [Aggregate]

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS
Returns a subset of the data set, known as a synopsis, as a VARBINARY or LONG VARBINARY.
Save the synopsis as an HP Vertica table for use by APPROXIMATE_COUNT_DISTINCT_OF_
SYNOPSIS.

Behavior Type
Immutable

Syntax
APPROXIMATE_COUNT_DISTINCT_SYNOPSIS ( expr )

Parameters
expr

Value to be evaluated using any data type that supports
equality comparison.

Notes
l

The maximum number of distinct values is in the range of 0 to approximately 2^47, or 1.4*10^14.

l

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS cannot appear in the same query block with
DISTINCT aggregates.

Example
In the following example, the query creates a table that contains the synopsis of the product_key
data. The my_summary table is used in the example for APPROXIMATE_COUNT_DISTINCT_OF_
SYNOPSIS.
=> CREATE TABLE my_summary AS
SELECT tender_type,
APPROXIMATE_COUNT_DISTINCT_SYNOPSIS(product_key) syn
FROM store.store_sales_fact

HP Vertica Analytic Database (7.0.x)

Page 173 of 1539

SQL Reference Manual
SQL Functions

GROUP BY tender_type;
CREATE TABLE
Time: First fetch (0 rows): 3216.056 ms. All rows formatted: 3216.069 ms

See Also
l

APPROXIMATE_COUNT_DISTINCT

l

APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS

l

COUNT [Aggregate]

AVG [Aggregate]
Computes the average (arithmetic mean) of an expression over a group of rows. It returns a DOUBLE
PRECISION value for a floating-point expression. Otherwise, the return value is the same as the
expression data type.

Behavior Type
Immutable

Syntax
AVG ( [ ALL | DISTINCT ] expression )

Parameters
ALL

Invokes the aggregate function for all rows in the group (default).

DISTINCT

Invokes the aggregate function for all distinct non-null values of the expression
found in the group.

expression

The value whose average is calculated over a set of rows. Can be any expression
resulting in DOUBLE PRECISION.

Notes
The AVG() aggregate function is different from the AVG() analytic function, which computes an
average of an expression over a group of rows within a window.

Examples
The following example returns the average income from the customer table:

HP Vertica Analytic Database (7.0.x)

Page 174 of 1539

SQL Reference Manual
SQL Functions

=> SELECT AVG(annual_income) FROM customer_dimension;
avg
-------------2104270.6485
(1 row)

See Also
l

AVG [Analytic]

l

COUNT [Aggregate]

l

SUM [Aggregate]

l

Numeric Data Types

BIT_AND
Takes the bitwise AND of all non-null input values. If the input parameter is NULL, the return value is
also NULL.

Behavior Type
Immutable

Syntax
BIT_AND ( expression )

Parameters
expression

The [BINARY |VARBINARY] input value to be evaluated. BIT_AND() operates on
VARBINARY types explicitly and on BINARY types implicitly through casts.

Notes
l

The function returns the same value as the argument data type.

l

For each bit compared, if all bits are 1, the function returns 1; otherwise it returns 0.

l

If the columns are different lengths, the return values are treated as though they are all equal in
length and are right-extended with zero bytes. For example, given a group containing the hex
values 'ff', null, and 'f', the function ignores the null value and extends the value 'f' to
'f0'..

HP Vertica Analytic Database (7.0.x)

Page 175 of 1539

SQL Reference Manual
SQL Functions

Example
This example uses the following schema, which creates table t with a single column of VARBINARY
data type:
=>
=>
=>
=>

CREATE
INSERT
INSERT
INSERT

TABLE t ( c VARBINARY(2) );
INTO t values(HEX_TO_BINARY('0xFF00'));
INTO t values(HEX_TO_BINARY('0xFFFF'));
INTO t values(HEX_TO_BINARY('0xF00F'));

Query table t to see column c output:
=> SELECT TO_HEX(c) FROM t;
TO_HEX
-------ff00
ffff
f00f
(3 rows)

Query table t to get the AND value for column c:
SELECT TO_HEX(BIT_AND(c)) FROM t;
TO_HEX
-------f000
(1 row)

The function is applied pairwise to all values in the group, resulting in f000, which is determined as
follows:
1. ff00 (record 1) is compared with ffff (record 2), which results in ff00.
2. The result from the previous comparison is compared with f00f (record 3), which results in
f000.

See Also
l

Binary Data Types

BIT_OR
Takes the bitwise OR of all non-null input values. If the input parameter is NULL, the return value is
also NULL.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 176 of 1539

SQL Reference Manual
SQL Functions

Syntax
BIT_OR ( expression )

Parameters
expression

The [BINARY |VARBINARY] input value to be evaluated. BIT_OR() operates on
VARBINARY types explicitly and on BINARY types implicitly through casts.

Notes
l

The function returns the same value as the argument data type.

l

For each bit compared, if any bit is 1, the function returns 1; otherwise it returns 0.

l

If the columns are different lengths, the return values are treated as though they are all equal in
length and are right-extended with zero bytes. For example, given a group containing the hex
values 'ff', null, and 'f', the function ignores the null value and extends the value 'f' to
'f0'.

Example
This example uses the following schema, which creates table t with a single column of VARBINARY
data type:
=>
=>
=>
=>

CREATE
INSERT
INSERT
INSERT

TABLE t ( c VARBINARY(2) );
INTO t values(HEX_TO_BINARY('0xFF00'));
INTO t values(HEX_TO_BINARY('0xFFFF'));
INTO t values(HEX_TO_BINARY('0xF00F'));

Query table t to see column c output:
=> SELECT TO_HEX(c) FROM t;
TO_HEX
-------ff00
ffff
f00f
(3 rows)

Query table t to get the OR value for column c:
SELECT TO_HEX(BIT_OR(c)) FROM t;
TO_HEX
-------ffff
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 177 of 1539

SQL Reference Manual
SQL Functions

The function is applied pairwise to all values in the group, resulting in ffff, which is determined as
follows:
1. ff00 (record 1) is compared with ffff, which results in ffff.
2. The ff00 result from the previous comparison is compared with f00f (record 3), which results
in ffff.

See Also
l

Binary Data Types

BIT_XOR
Takes the bitwise XOR of all non-null input values. If the input parameter is NULL, the return value is
also NULL.

Behavior Type
Immutable

Syntax
BIT_XOR ( expression )

Parameters
expression

The [BINARY | VARBINARY] input value to be evaluated. BIT_XOR() operates on
VARBINARY types explicitly and on BINARY types implicitly through casts.

Notes
l

The function returns the same value as the argument data type.

l

For each bit compared, if there are an odd number of arguments with set bits, the function
returns 1; otherwise it returns 0.

l

If the columns are different lengths, the return values are treated as though they are all equal in
length and are right-extended with zero bytes. For example, given a group containing the hex
values 'ff', null, and 'f', the function ignores the null value and extends the value 'f' to
'f0'.

Example
First create a sample table and projections with binary columns:

HP Vertica Analytic Database (7.0.x)

Page 178 of 1539

SQL Reference Manual
SQL Functions

This example uses the following schema, which creates table t with a single column of VARBINARY
data type:
=>
=>
=>
=>

CREATE
INSERT
INSERT
INSERT

TABLE t ( c VARBINARY(2) );
INTO t values(HEX_TO_BINARY('0xFF00'));
INTO t values(HEX_TO_BINARY('0xFFFF'));
INTO t values(HEX_TO_BINARY('0xF00F'));

Query table t to see column c output:
=> SELECT TO_HEX(c) FROM t;
TO_HEX
-------ff00
ffff
f00f
(3 rows)

Query table t to get the XOR value for column c:
SELECT TO_HEX(BIT_XOR(c)) FROM t;
TO_HEX
-------f0f0
(1 row)

See Also
l

Binary Data Types

CORR
Returns the coefficient of correlation of a set of expression pairs (expression1 and expression2).
The return value is of type DOUBLE PRECISION. The function eliminates expression pairs where
either expression in the pair is NULL. If no rows remain, the function returns NULL.Syntax
SELECT CORR (expression1,expression2)

Parameters
expression1

The dependent expression. Is of type DOUBLE PRECISION.

expression2

The independent expression. Is of type DOUBLE PRECISION.

Example
=> SELECT CORR (Annual_salary, Employee_age) FROM employee_dimension;

HP Vertica Analytic Database (7.0.x)

Page 179 of 1539

SQL Reference Manual
SQL Functions

CORR
----------------------0.00719153413192422
(1 row)

COUNT [Aggregate]
Returns the number of rows in each group of the result set for which the expression is not NULL. The
return value is a BIGINT.
The COUNT() aggregate function is different from the COUNT() analytic function. The COUNT()
analytic function returns the number over a group of rows within a window.
When an approximate count of the number of distinct values is sufficient, use the
APPROXIMATE_COUNT_DISTINCT function. If you want to combine the data in different ways,
use APPROXIMATE_COUNT_DISTINCT_SYNOPSIS together with APPROXIMATE_COUNT_
DISTINCT_OF_SYNOPSIS.

Behavior Type
Immutable

Syntax
COUNT ( [ * ] [ ALL | DISTINCT ] expression )

Parameters
*

Indicates that the count does not apply to any specific column or expression in the
select list. Requires a FROM Clause.

ALL

Invokes the aggregate function for all rows in the group (default).

DISTINCT

Invokes the aggregate function for all distinct non-null values of the expression
found in the group.

expression

Returns the number of rows in each group for which the expression is not null. Can
be any expression resulting in BIGINT.

Examples
The following query returns the number of distinct values in the primary_key column of the date_
dimension table:
=> SELECT COUNT (DISTINCT date_key) FROM date_dimension;
COUNT

HP Vertica Analytic Database (7.0.x)

Page 180 of 1539

SQL Reference Manual
SQL Functions

------1826
(1 row)

This example returns all distinct values of evaluating the expression x+y for all records of fact.
=> SELECT COUNT (DISTINCT date_key + product_key)
FROM inventory_fact;
COUNT
------21560
(1 row)

You can create an equivalent query using the LIMIT keyword to restrict the number of rows
returned:
=> SELECT COUNT(date_key + product_key) FROM inventory_fact
GROUP BY date_key LIMIT 10;
COUNT
------173
31
321
113
286
84
244
238
145
202
(10 rows)

This query returns the number of distinct values of date_key in all records with the specific distinct
product_key value.
=> SELECT product_key, COUNT (DISTINCT date_key)
FROM inventory_fact GROUP BY product_key LIMIT 10;
product_key | count
-------------+------1 |
12
2 |
18
3 |
13
4 |
17
5 |
11
6 |
14
7 |
13
8 |
17
9 |
15
10 |
12
(10 rows)

This query counts each distinct product_key value in inventory_fact table with the constant 1.

HP Vertica Analytic Database (7.0.x)

Page 181 of 1539

SQL Reference Manual
SQL Functions

=> SELECT product_key, COUNT (DISTINCT product_key)
FROM inventory_fact GROUP BY product_key LIMIT 10;
product_key | count
-------------+------1 |
1
2 |
1
3 |
1
4 |
1
5 |
1
6 |
1
7 |
1
8 |
1
9 |
1
10 |
1
(10 rows)

This query selects each distinct date_key value and counts the number of distinct product_key
values for all records with the specific product_key value. It then sums the qty_in_stock values
in all records with the specific product_key value and groups the results by date_key.
=> SELECT date_key, COUNT (DISTINCT product_key),
SUM(qty_in_stock) FROM inventory_fact
GROUP BY date_key LIMIT 10;
date_key | count | sum
----------+-------+-------1 |
173 | 88953
2 |
31 | 16315
3 |
318 | 156003
4 |
113 | 53341
5 |
285 | 148380
6 |
84 | 42421
7 |
241 | 119315
8 |
238 | 122380
9 |
142 | 70151
10 |
202 | 95274
(10 rows)

This query selects each distinct product_key value and then counts the number of distinct date_
key values for all records with the specific product_key value. It also counts the number of distinct
warehouse_key values in all records with the specific product_key value.
=> SELECT product_key, COUNT (DISTINCT date_key),
COUNT (DISTINCT warehouse_key) FROM inventory_fact
GROUP BY product_key LIMIT 15;
product_key | count | count
-------------+-------+------1 |
12 |
12
2 |
18 |
18
3 |
13 |
12
4 |
17 |
18
5 |
11 |
9
6 |
14 |
13
7 |
13 |
13
8 |
17 |
15

HP Vertica Analytic Database (7.0.x)

Page 182 of 1539

SQL Reference Manual
SQL Functions

9
10
11
12
13
14
15

|
|
|
|
|
|
|

15
12
11
13
9
13
18

|
|
|
|
|
|
|

14
12
11
12
7
13
17

(15 rows)

This query selects each distinct product_key value, counts the number of distinct date_key and
warehouse_key values for all records with the specific product_key value, and then sums all qty_
in_stock values in records with the specific product_key value. It then returns the number of
product_version values in records with the specific product_key value.
=> SELECT product_key, COUNT (DISTINCT date_key),
COUNT (DISTINCT warehouse_key),
SUM (qty_in_stock),
COUNT (product_version)
FROM inventory_fact GROUP BY product_key
LIMIT 15;
product_key | count | count | sum | count
-------------+-------+-------+-------+------1 |
12 |
12 | 5530 |
12
2 |
18 |
18 | 9605 |
18
3 |
13 |
12 | 8404 |
13
4 |
17 |
18 | 10006 |
18
5 |
11 |
9 | 4794 |
11
6 |
14 |
13 | 7359 |
14
7 |
13 |
13 | 7828 |
13
8 |
17 |
15 | 9074 |
17
9 |
15 |
14 | 7032 |
15
10 |
12 |
12 | 5359 |
12
11 |
11 |
11 | 6049 |
11
12 |
13 |
12 | 6075 |
13
13 |
9 |
7 | 3470 |
9
14 |
13 |
13 | 5125 |
13
15 |
18 |
17 | 9277 |
18
(15 rows)

The following example returns the number of warehouses from the warehouse dimension table:
=> SELECT COUNT(warehouse_name) FROM warehouse_dimension;
COUNT
------100
(1 row)

This next example returns the total number of vendors:
=> SELECT COUNT(*) FROM vendor_dimension;
COUNT
------50

HP Vertica Analytic Database (7.0.x)

Page 183 of 1539

SQL Reference Manual
SQL Functions

(1 row)

See Also
l

Analytic Functions

l

AVG [Aggregate]

l

SUM [Aggregate]

l

Using SQL Analytics

l

APPROXIMATE_COUNT_DISTINCT

l

APPROXIMATE_COUNT_DISTINCT_SYNOPSIS

l

APPROXIMATE_COUNT_DISTINCT_OF_SYNOPSIS

COVAR_POP
Returns the population covariance for a set of expression pairs (expression1 and expression2). The
return value is of type DOUBLE PRECISION. The function eliminates expression pairs where
either expression in the pair is NULL. If no rows remain, the function returns NULL.

Syntax
SELECT COVAR_POP (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT COVAR_POP (Annual_salary, Employee_age)
FROM employee_dimension;
COVAR_POP
-------------------9032.34810730019
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 184 of 1539

SQL Reference Manual
SQL Functions

COVAR_SAMP
Returns the sample covariance for a set of expression pairs (expression1 and expression2). The
return value is of type DOUBLE PRECISION. The function eliminates expression pairs where
either expression in the pair is NULL. If no rows remain, the function returns NULL.

Syntax
COVAR_SAMP (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT COVAR_SAMP (Annual_salary, Employee_age)
FROM employee_dimension;
COVAR_SAMP
-------------------9033.25143244343
(1 row)

MAX [Aggregate]
Returns the greatest value of an expression over a group of rows. The return value is the same as
the expression data type.

Behavior Type
Immutable

Syntax
MAX ( [ ALL | DISTINCT ] expression )

Parameters
ALL | DISTINCT

These parameters have no meaning in this context.

expression

Any expression for which the maximum value is calculated, typically a column
reference.

HP Vertica Analytic Database (7.0.x)

Page 185 of 1539

SQL Reference Manual
SQL Functions

Notes
The MAX() aggregate function is different from the MAX() analytic function, which returns the
maximum value of an expression over a group of rows within a window.

Example
This example returns the largest value (dollar amount) of the sales_dollar_amount column.
=> SELECT MAX(sales_dollar_amount) AS highest_sale FROM store.store_sales_fact;
highest_sale
-------------600
(1 row)

See Also
l

Analytic Functions

l

MIN [Aggregate]

MIN [Aggregate]
Returns the smallest value of an expression over a group of rows. The return value is the same as
the expression data type.

Behavior Type
Immutable

Syntax
MIN ( [ ALL | DISTINCT ] expression )

Parameters
ALL | DISTINCT

Are meaningless in this context.

expression

Any expression for which the minimum value is calculated, typically a column
reference.

Notes
The MIN() aggregate function is different from the MIN() analytic function, which returns the
minimum value of an expression over a group of rows within a window.

HP Vertica Analytic Database (7.0.x)

Page 186 of 1539

SQL Reference Manual
SQL Functions

Example
This example returns the lowest salary from the employee dimension table.
=> SELECT MIN(annual_salary) AS lowest_paid FROM employee_dimension;
lowest_paid
------------1200
(1 row)

See Also
l

Analytic Functions

l

MAX [Aggregate]

l

Using SQL Analytics

REGR_AVGX
Returns the average of the independent expression in an expression pair (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_AVGX (expression1,expression2)

Parameters
expression1

The dependent expression. Is of type DOUBLE PRECISION.

expression2

The independent expression. Is of type DOUBLE PRECISION.

Example
=> SELECT REGR_AVGX (Annual_salary, Employee_age)
FROM employee_dimension;
REGR_AVGX
----------39.321
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 187 of 1539

SQL Reference Manual
SQL Functions

REGR_AVGY
Returns the average of the dependent expression in an expression pair (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
REGR_AVGY (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_AVGY (Annual_salary, Employee_age)
FROM employee_dimension;
REGR_AVGY
-----------58354.4913
(1 row)

REGR_COUNT
Returns the number of expression pairs (expression1 and expression2). The return value is of type
INTEGER. The function eliminates expression pairs where either expression in the pair is NULL. If
no rows remain, the function returns 0.

Syntax
SELECT REGR_COUNT (expression1, expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

HP Vertica Analytic Database (7.0.x)

Page 188 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT REGR_COUNT (Annual_salary, Employee_age) FROM employee_dimension;
REGR_COUNT
-----------10000
(1 row)

REGR_INTERCEPT
Returns the y-intercept of the regression line determined by a set of expression pairs (expression1
and expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_INTERCEPT (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_INTERCEPT (Annual_salary, Employee_age) FROM employee_dimension;
REGR_INTERCEPT
-----------------59929.5490163437
(1 row)

REGR_R2
Returns the square of the correlation coefficient of a set of expression pairs (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_R2 (expression1,expression2)

HP Vertica Analytic Database (7.0.x)

Page 189 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_R2 (Annual_salary, Employee_age) FROM employee_dimension;
REGR_R2
---------------------5.17181631706311e-05
(1 row)

REGR_SLOPE
Returns the slope of the regression line, determined by a set of expression pairs (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_SLOPE (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_SLOPE (Annual_salary, Employee_age) FROM employee_dimension;
REGR_SLOPE
------------------40.056400303749
(1 row)

REGR_SXX
Returns the sum of squares of the independent expression in an expression pair (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates

HP Vertica Analytic Database (7.0.x)

Page 190 of 1539

SQL Reference Manual
SQL Functions

expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_SXX (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_SXX (Annual_salary, Employee_age) FROM employee_dimension;
REGR_SXX
-----------2254907.59
(1 row)

REGR_SXY
Returns the sum of products of the independent expression multiplied by the dependent expression
in an expression pair (expression1 and expression2). The return value is of type DOUBLE
PRECISION. The function eliminates expression pairs where either expression in the pair is NULL.
If no rows remain, the function returns NULL.

Syntax
SELECT REGR_SXY (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_SXY (Annual_salary, Employee_age) FROM employee_dimension;
REGR_SXY
-------------------90323481.0730019

HP Vertica Analytic Database (7.0.x)

Page 191 of 1539

SQL Reference Manual
SQL Functions

(1 row)

REGR_SYY
Returns the sum of squares of the dependent expression in an expression pair (expression1 and
expression2). The return value is of type DOUBLE PRECISION. The function eliminates
expression pairs where either expression in the pair is NULL. If no rows remain, the function returns
NULL.

Syntax
SELECT REGR_SYY (expression1,expression2)

Parameters
expression1

The dependent expression, type DOUBLE PRECISION.

expression2

The independent expression, type DOUBLE PRECISION.

Example
=> SELECT REGR_SYY (Annual_salary, Employee_age) FROM employee_dimension;
REGR_SYY
-----------------69956728794707.2
(1 row)

STDDEV [Aggregate]
Note: The non-standard function STDDEV() is provided for compatibility with other databases.
It is semantically identical to STDDEV_SAMP().
Evaluates the statistical sample standard deviation for each member of the group. The STDDEV()
return value is the same as the square root of the VAR_SAMP() function:
STDDEV(expression) = SQRT(VAR_SAMP(expression))

When VAR_SAMP() returns NULL, this function returns NULL.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 192 of 1539

SQL Reference Manual
SQL Functions

Syntax
STDDEV ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
The STDDEV() aggregate function is different from the STDDEV() analytic function, which computes
the statistical sample standard deviation of the current row with respect to the group of rows within
a window.

Examples
The following example returns the statistical sample standard deviation for each household ID from
the customer_dimension table of the VMart example database:
=> SELECT STDDEV(household_id) FROM customer_dimension;
STDDEV
----------------8651.5084240071

See Also
l

Analytic Functions

l

STDDEV_SAMP [Aggregate]

l

Using SQL Analytics

STDDEV_POP [Aggregate]
Evaluates the statistical population standard deviation for each member of the group. The STDDEV_
POP() return value is the same as the square root of the VAR_POP() function
STDDEV_POP(expression) = SQRT(VAR_POP(expression))

When VAR_SAMP() returns NULL, this function returns NULL.

HP Vertica Analytic Database (7.0.x)

Page 193 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
STDDEV_POP ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
The STDDEV_POP() aggregate function is different from the STDDEV_POP() analytic function, which
evaluates the statistical population standard deviation for each member of the group of rows within
a window.

Examples
The following example returns the statistical population standard deviation for each household ID in
the customer table.
=> SELECT STDDEV_POP(household_id) FROM customer_dimension;
STDDEV_POP
-----------------8651.41895973367
(1 row)

See Also
l

Analytic Functions

l

Using SQL Analytics

STDDEV_SAMP [Aggregate]
Evaluates the statistical sample standard deviation for each member of the group. The STDDEV_
SAMP() return value is the same as the square root of the VAR_SAMP() function:
STDDEV_SAMP(expression) = SQRT(VAR_SAMP(expression))

When VAR_SAMP() returns NULL, this function returns NULL.

HP Vertica Analytic Database (7.0.x)

Page 194 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
STDDEV_SAMP ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
l

STDDEV_SAMP() is semantically identical to the non-standard function, STDDEV(), which is
provided for compatibility with other databases.

l

The STDDEV_SAMP() aggregate function is different from the STDDEV_SAMP() analytic function,
which computes the statistical sample standard deviation of the current row with respect to the
group of rows within a window.

Examples
The following example returns the statistical sample standard deviation for each household ID from
the customer dimension table.
=> SELECT STDDEV_SAMP(household_id) FROM customer_dimension;
stddev_samp
-----------------8651.50842400771
(1 row)

See Also
l

Analytic Functions

l

STDDEV [Aggregate]

l

Using SQL Analytics

HP Vertica Analytic Database (7.0.x)

Page 195 of 1539

SQL Reference Manual
SQL Functions

SUM [Aggregate]
Computes the sum of an expression over a group of rows. It returns a DOUBLE PRECISION value for
a floating-point expression. Otherwise, the return value is the same as the expression data type.

Behavior Type
Immutable

Syntax
SUM ( [ ALL | DISTINCT ] expression )

Parameters
ALL

Invokes the aggregate function for all rows in the group (default)

DISTINCT

Invokes the aggregate function for all distinct non-null values of the expression
found in the group

expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
l

The SUM() aggregate function is different from the SUM() analytic function, which computes the
sum of an expression over a group of rows within a window.

l

If you encounter data overflow when using SUM(), use SUM_FLOAT() which converts the data to
a floating point.

Example
This example returns the total sum of the product_cost column.
=> SELECT SUM(product_cost) AS cost FROM product_dimension;
cost
--------9042850
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 196 of 1539

SQL Reference Manual
SQL Functions

See Also
l

AVG [Aggregate]

l

COUNT [Aggregate]
Numeric Data Types

l
l

SUM_FLOAT [Aggregate]
Computes the sum of an expression over a group of rows. It returns a DOUBLE PRECISION value for
the expression, regardless of the expression type.

Behavior Type
Immutable

Syntax
SUM_FLOAT ( [ ALL | DISTINCT ] expression )

Parameters
ALL

Invokes the aggregate function for all rows in the group (default).

DISTINCT

Invokes the aggregate function for all distinct non-null values of the expression
found in the group.

expression

Any expression whose result is type DOUBLE PRECISION.

Example
The following example returns the floating-point sum of the average price from the product table:
=> SELECT SUM_FLOAT(average_competitor_price) AS cost FROM product_dimension;
cost
---------18181102
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 197 of 1539

SQL Reference Manual
SQL Functions

VAR_POP [Aggregate]
Evaluates the population variance for each member of the group. This is defined as the sum of
squares of the difference of expression from the mean of expression, divided by the number of rows
remaining.
(SUM(expression*expression) - SUM(expression)*SUM(expression) /COUNT(expression)) / COUNT
(expression)

Behavior Type
Immutable

Syntax
VAR_POP ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
The VAR_POP() aggregate function is different from the VAR_POP() analytic function, which
computes the population variance of the current row with respect to the group of rows within a
window.

Examples
The following example returns the population variance for each household ID in the customer table.
=> SELECT VAR_POP(household_id) FROM customer_dimension;
var_pop
-----------------74847050.0168393
(1 row)

VAR_SAMP [Aggregate]
Evaluates the sample variance for each row of the group. This is defined as the sum of squares of
the difference of expression from the mean of expression, divided by the number of rows remaining
minus 1 (one).

HP Vertica Analytic Database (7.0.x)

Page 198 of 1539

SQL Reference Manual
SQL Functions

(SUM(expression*expression) - SUM(expression) *SUM(expression) /COUNT(expression)) / (COU
NT(expression) -1)

Behavior Type
Immutable

Syntax
VAR_SAMP ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
l

VAR_SAMP() is semantically identical to the non-standard function, VARIANCE(), which is
provided for compatibility with other databases.

l

The VAR_SAMP() aggregate function is different from the VAR_SAMP() analytic function, which
computes the sample variance of the current row with respect to the group of rows within a
window.

Examples
The following example returns the sample variance for each household ID in the customer table.
=> SELECT VAR_SAMP(household_id) FROM customer_dimension;
var_samp
-----------------74848598.0106764
(1 row)

See Also
Analytic Functions

l

VARIANCE [Aggregate]

l
l

HP Vertica Analytic Database (7.0.x)

Page 199 of 1539

SQL Reference Manual
SQL Functions

VARIANCE [Aggregate]
Note: The non-standard function VARIANCE() is provided for compatibility with other
databases. It is semantically identical to VAR_SAMP().
Evaluates the sample variance for each row of the group. This is defined as the sum of squares of
the difference of expression from the mean of expression, divided by the number of rows remaining
minus 1 (one).
(SUM(expression*expression) - SUM(expression) *SUM(expression) /COUNT(expression)) / (COU
NT(expression) -1)

Behavior Type
Immutable

Syntax
VARIANCE ( expression )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

Notes
The VARIANCE() aggregate function is different from the VARIANCE() analytic function, which
computes the sample variance of the current row with respect to the group of rows within a
window.

Examples
The following example returns the sample variance for each household ID in the customer table.
=> SELECT VARIANCE(household_id) FROM customer_dimension;
variance
-----------------74848598.0106764
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 200 of 1539

SQL Reference Manual
SQL Functions

See Also
Analytic Functions

l

VAR_SAMP [Aggregate]

l
l

HP Vertica Analytic Database (7.0.x)

Page 201 of 1539

SQL Reference Manual
SQL Functions

Analytic Functions
Note: All analytic functions in this section that have an aggregate counterpart are appended
with [Analytics] in the heading to avoid confusion between the two.
HP Vertica analytics are SQL functions based on the ANSI 99 standard. These functions handle
complex analysis and reporting tasks such as:
l

Rank the longest-standing customers in a particular state

l

Calculate the moving average of retail volume over a specified time

l

Find the highest score among all students in the same grade

l

Compare the current sales bonus each salesperson received against his or her previous bonus

Analytic functions return aggregate results but they do not group the result set. They return the
group value multiple times, once per record.
You can sort these group values, or partitions, using a window ORDER BY clause, but the order
affects only the function result set, not the entire query result set. This ordering concept is
described more fully later.

Analytic Function Syntax
ANALYTIC_FUNCTION( argument-1, ..., argument-n )
OVER( [ window_partition_clause ]
[ window_order_clause ]
[ window_frame_clause ] )

Analytic Syntactic Construct
ANALYTIC_FUNCTION()

HP Vertica provides a number of analytic functions that allow
advanced data manipulation and analysis. Each of these functions
takes one or more arguments.

OVER(...)

Specifies partitioning, ordering, and window framing for the function—
important elements that determine what data the analytic function
takes as input with respect to the current row. The OVER() clause is
evaluated after the FROM, WHERE, GROUP BY, and HAVING clauses. The
SQL OVER() clause must follow the analytic function.

HP Vertica Analytic Database (7.0.x)

Page 202 of 1539

SQL Reference Manual
SQL Functions

window_partition_clause

Groups the rows in the input table by a given list of columns or
expressions.
The window_partition_clause is optional; if you omit it, the rows are
not grouped, and the analytic function applies to all rows in the input
set as a single partition. See window_partition_clause.

window_order_clause

Sorts the rows specified by the OVER() operator and supplies the
ordered set of rows to the analytic function. If the partition clause is
present, the window_order_clause applies within each partition.
The order clause is optional. If you do not use it, the selection set is
not sorted. See window_order_clause.

window_frame_clause

Used by only some analytic functions. If you include the frame clause
in the OVER() statement, which specifies the beginning and end of the
window relative to the current row, the analytic function applies only to
a subset of the rows defined by the partition clause. This subset
changes as the rows in the partition change (called a moving window).
See window_frame_clause.

Notes
Analytic functions:
l

Require the OVER() clause. However, depending on the function, the window_frame_clause
and window_order_clause might not apply. For example, when used with analytic aggregate
functions like SUM(x), you can use the OVER() clause without supplying any of the windowing
clauses; in this case, the aggregate returns the same aggregated value for each row of the result
set.

l

Are allowed only in the SELECT and ORDER BY clauses.

l

Can be used in a subquery or in the parent query but cannot be nested; for example, the
following query is not allowed:
=> SELECT MEDIAN(RANK() OVER(ORDER BY sal) OVER()).

l

WHERE, GROUP BY and HAVING operators are technically not part of the analytic function;
however, they determine on which rows the analytic functions operate.

See Also
l

Using SQL Analytics

l

Optimizing GROUP BY Queries

HP Vertica Analytic Database (7.0.x)

Page 203 of 1539

SQL Reference Manual
SQL Functions

window_partition_clause
Window partitioning is optional. When specified, the window_partition_clause divides the rows
in the input based on user-provided expressions, such as aggregation functions like SUM(x).
Window partitioning is similar to the GROUP BY clause except that it returns only one result row
per input row. If you omit the window_partition_clause, all input rows are treated as a single
partition.
The analytic function is computed per partition and starts over again (resets) at the beginning of
each subsequent partition. The window_partition_clause is specified within the OVER() clause.

Syntax
OVER ( PARTITION BY expression [ , ... ] )

Parameters
expression

Expression on which to sort the partition on. May involve columns, constants, or an
arbitrary expression formed on columns.

For examples, see Window Partitioning in the Programmer's Guide.

window_order_clause
Sorts the rows specified by the OVER() clause and specifies whether data is sorted in ascending or
descending order as well as the placement of null values. For example:
ORDER BY expr_list [ ASC | DESC ] [ NULLS { FIRST | LAST | AUTO ]

The ordering of the data affects the results.
Using ORDER BY in an OVER clause changes the default window to RANGE UNBOUNDED
PRECEDING AND CURRENT ROW, which is described in the window_frame_clause.
The following table shows the default null placement, with bold clauses to indicate what is implicit:
Ordering

Null placement

ORDER BY column1

ORDER BY a ASC NULLS LAST

ORDER BY column1 ASC

ORDER BY a ASC NULLS LAST

ORDER BY column1 DESC

ORDER BY a DESC NULLS FIRST

Because the window_order_clause is different from a query's final ORDER BY clause, window
ordering might not guarantee the final result order; it specifies only the order within a window result
set, supplying the ordered set of rows to the window_frame_clause (if present), to the analytic
function, or to both. Use the SQL ORDER BY clause to guarantee ordering of the final result set.

HP Vertica Analytic Database (7.0.x)

Page 204 of 1539

SQL Reference Manual
SQL Functions

Syntax
OVER ( ORDER BY expression [ { ASC | DESC } ]
... [ NULLS { FIRST | LAST | AUTO } ] [, expression ...] )

Parameters
expression

Expression on which to sort the partition, which may involve
columns, constants, or an arbitrary expression formed on
columns.

ASC | DESC

Specifies the ordering sequence as ascending (default) or
descending.

NULLS { FIRST | LAST |
AUTO }

Indicates the position of nulls in the ordered sequence as
either first or last. The order makes nulls compare either high
or low with respect to non-null values.
If the sequence is specified as ascending order,
ASC NULLS FIRST implies that nulls are smaller than other
non-null values. ASC NULLS LAST implies thatnulls are larger
than non-null values. The opposite is true for descending order.
If you specify NULLS AUTO, HP vertica chooses the most
efficient placement of nulls (for example, either
NULLS FIRST or NULLS LAST), based on your query. The
default is ASC NULLS LAST and DESC NULLS FIRST. For more
information, see
l

l

"NULL Placement By Analytic Functions" on page 1
"Designing Tables to Minimize Run-Time Sorting of NULL
Values in Analytic Functions" on page 1

The following analytic functions require the window_order_clause:
l

RANK() / DENSE_RANK()

l

LEAD() / LAG()

l

PERCENT_RANK() / CUME_DIST()

l

NTILE()

You can also use the window_order_clause with aggregation functions, such as SUM(x).
The ORDER BY clause is optional for the ROW_NUMBER() function.
The ORDER BY clause is not allowed with the following functions:

HP Vertica Analytic Database (7.0.x)

Page 205 of 1539

SQL Reference Manual
SQL Functions

l

PERCENTILE_CONT() / PERCENTILE_DISC()

l

MEDIAN()

For examples, see Window Ordering in the Programmer's Guide.

window_frame_clause
Allowed for some analytic functions in the analytic OVER() clause, window framing represents a
unique construct, called a moving window. It defines which values in the partition are evaluated
relative to the current row. You specify a window frame in terms of either logical intervals (such as
time) using the RANGE keyword or on a physical number of rows before and/or after the current row
using the ROWS keyword. The CURRENT ROW is the next row for which the analytic function
computes results.
As the current row advances, the window boundaries are recomputed (move) along with it,
determining which rows fall into the current window.
An analytic function with a window frame specification is computed for each row based on the rows
that fall into the window relative to that row.
An analytic function with a window frame specification is computed for each row based on the rows
that fall into the window relative to that row. If you omit the window_frame_clause, the default
window is RANGE UNBOUNDED PRECEDING AND CURRENT ROW.

Syntax
{ ROWS | RANGE }
{
{
BETWEEN
{ UNBOUNDED PRECEDING
| CURRENT ROW
| constant-value { PRECEDING | FOLLOWING }
}
AND
{ UNBOUNDED FOLLOWING
| CURRENT ROW
| constant-value { PRECEDING | FOLLOWING }
}
}
|
{
{ UNBOUNDED PRECEDING
| CURRENT ROW
| constant-value PRECEDING
}
}
}

HP Vertica Analytic Database (7.0.x)

Page 206 of 1539

SQL Reference Manual
SQL Functions

Parameters
ROWS | RANGE

The ROWS and RANGE keywords define the window
frame type.
ROWS specifies a window as a physical offset and
defines the window's start and end point by the
number of rows before or after the current row. The
value can be INTEGER data type only.
RANGE specifies the window as a logical offset, such
as time. The range value must match the window_
order_clause data type, which can be NUMERIC,
DATE/TIME, FLOAT or INTEGER.
Note: The value returned by an analytic function
with a logical offset is always deterministic.
However, the value returned by an analytic
function with a physical offset could produce
nondeterministic results unless the ordering
expression results in a unique ordering. You
might have to specify multiple columns in the
window_order_clause to achieve this unique
ordering.

BETWEEN ... AND

Specifies a start point and end point for the window.
The first expression (before AND) defines the start
point and the second expression (after AND) defines
the end point.
Note: If you use the keyword BETWEEN, you must
also use AND.

UNBOUNDED PRECEDING

Within a partition, indicates that the window frame
starts at the first row of the partition. This start-point
specification cannot be used as an end-point
specification, and the default is RANGE
UNBOUNDED PRECEDING AND CURRENT
ROW

UNBOUNDED FOLLOWING

Within a partition, indicates that the window frame
ends at the last row of the partition. This end-point
specification cannot be used as a start-point
specification.

HP Vertica Analytic Database (7.0.x)

Page 207 of 1539

SQL Reference Manual
SQL Functions

CURRENT ROW

As a start point, CURRENT ROW specifies that the
window begins at the current row or value, depending
on whether you have specified ROW or RANGE,
respectively. In this case, the end point cannot be
constant-value PRECEDING.
As an end point, CURRENT ROW specifies that the
window ends at the current row or value, depending
on whether you have specified ROW or RANGE,
respectively. In this case the start point cannot be
constant-value FOLLOWING.

HP Vertica Analytic Database (7.0.x)

Page 208 of 1539

SQL Reference Manual
SQL Functions

constant-value {PRECEDING | FOLLOWING }

For RANGE or ROW:
l

If constant-value FOLLOWING is the start point, the
end point must be constant-value FOLLOWING.

l

If constant-value PRECEDING is the end point, the
start point must be constant-value PRECEDING.

l

If you specify a logical window that is defined by a
time interval in NUMERIC format, you might need
to use conversion functions.

If you specified ROWS:
l

constant-value is a physical offset. It must be a
constant or expression and must evaluate to an
INTEGER data type value.

l

If constant-value is part of the start point, it must
evaluate to a row before the end point.

If you specified RANGE:
l

constant-value is a logical offset. It must be a
constant or expression that evaluates to a positive
numeric value or an INTERVAL literal.

l

If constant-value evaluates to a NUMERIC value,
the ORDER BY column type must be a NUMERIC
data type..

l

If the constant-value evaluates to an INTERVAL
DAY TO SECOND subtype, the ORDER BY column
type can only be TIMESTAMP, TIME, DATE, or
INTERVAL DAY TO SECOND.

l

If the constant-value evaluates to an INTERVAL
YEAR TO MONTH, the ORDER BY column type can
only be TIMESTAMP, DATE, or INTERVAL YEAR TO
MONTH.

l

You can specify only one expression in the
window_order_clause.

Window Aggregates
Analytic functions that take the window_frame_clause are called window aggregates, and they
return information such as moving averages and cumulative results. To use the following functions

HP Vertica Analytic Database (7.0.x)

Page 209 of 1539

SQL Reference Manual
SQL Functions

as window (analytic) aggregates, instead of basic aggregates, specify both an ORDER BY clause
(window_order_clause) and a moving window (window_frame_clause) in the OVER() clause.
Used by only some analytic functions. If you include the frame clause in the OVER() statement,
which specifies the beginning and end of the window relative to the current row, the analytic
function applies only to a subset of the rows defined by the partition clause. This subset changes as
the rows in the partition change (called a moving window). See window_frame_clause.
Sorts the rows specified by the window_partition_clause and supplies an ordered set of rows to
the window_frame_clause (if present), to the analytic function, or to both. The window_order_
clause specifies whether data is returned in ascending or descending order and specifies where
null values appear in the sorted result as either first or last. The ordering of the data affects the
results.
Note: The window_order_clause does not guarantee the order of the SQL result. Use the SQL
ORDER BY clause to guarantee the ordering of the final result set.
Within a partition, UNBOUNDED PRECEDING/FOLLOWING means beginning/end of partition. If
you omit the window_frame_clause but you specify the window_order_clause, the system
provides the default window of RANGE BETWEEN UNBOUNDED PRECEDING AND
CURRENT ROW.
The following analytic functions take the window_frame_clause:
l

AVG()

l

COUNT()

l

MAX() and MIN()

l

SUM()

l

STDDEV(), STDDEV_POP(), and STDDEV_SAMP()

l

VARIANCE(), VAR_POP(), and VAR_SAMP()
Note: FIRST_VALUE and LAST_VALUE functions also accept the window_frame_clause,
but they are analytic functions only and have no aggregate counterpart. EXPONENTIAL_
MOVING_AVERAGE, LAG, and LEAD analytic functions do not take the window_frame_
clause.

If you use a window aggregate with an empty OVER() clause, there is no moving window, and the
function is used as a reporting function, where the entire input is treated as one partition.
The value returned by an analytic function with a logical offset is always deterministic. However,
the value returned by an analytic function with a physical offset could produce nondeterministic
results unless the ordering expression results in a unique ordering. You might have to specify
multiple columns in the window_order_clause to achieve this unique ordering.
See Window Framing in the Programmer's Guide for examples.

HP Vertica Analytic Database (7.0.x)

Page 210 of 1539

SQL Reference Manual
SQL Functions

named_windows
You can use the WINDOW clause to name your windows and avoid typing long OVER() clause
syntax.
The window_partition_clause is defined in the named window specification, not in the OVER()
clause, and a window definition cannot contain a window_frame_clause.
Each window defined in the window_definition_clause must have a unique name.

Syntax
WINDOW window_name AS ( window_definition_clause );

Parameters
window_name

User-supplied name of the analytics window.

window_definition_clause

[ window_partition_clause ] [ window_order_clause ]

Examples
In the following example, RANK() and DENSE_RANK() use the partitioning and ordering specifications
in the window definition for a window named w:
=> SELECT RANK() OVER w , DENSE_RANK() OVER w
FROM employee_dimension
WINDOW w AS (PARTITION BY employee_region ORDER by annual_salary);

Though analytic functions can reference a named window to inherit the window_partition_clause,
you can use OVER() to define your own window_order_clause, but only if the window_definition_
clause did not already define it. Because ORDER by annual_salary was already defined in the
WINDOW clause in the previous example, the following query would return an error.
=> SELECT RANK() OVER(w ORDER BY annual_salary ASC),
DENSE_RANK() OVER(w ORDER BY annual_salary DESC)
FROM employee_dimension
WINDOW w AS (PARTITION BY employee_region);
ERROR: cannot override ORDER BY clause of window "w"

You can reference window names within their scope only. For example, because named window w1
in the following query is defined before w2, w2 is within the scope of w1:
=> SELECT RANK() OVER(w1 ORDER BY sal DESC), RANK() OVER w2
FROM EMP
WINDOW w1 AS (PARTITION BY deptno), w2 AS (w1 ORDER BY sal);

HP Vertica Analytic Database (7.0.x)

Page 211 of 1539

SQL Reference Manual
SQL Functions

AVG [Analytic]
Computes an average of an expression in a group within a window.

Behavior Type
Immutable

Syntax
AVG
...
...
...

(
[
[
[

expression ) OVER (
window_partition_clause ]
window_order_clause ]
window_frame_clause ] )

Parameters
expression

The value whose average is calculated over a set of rows. Can be any expression
resulting in DOUBLE PRECISION.

OVER(...)

See Analytic Functions.

Notes
AVG() takes as an argument any numeric data type or any non-numeric data type that can be
implicitly converted to a numeric data type. The function returns the same data type as the
argument's numeric data type.

Examples
The following query finds the sales for that calendar month and returns a running/cumulative
average (sometimes called a moving average) using the default window of RANGE UNBOUNDED
PRECEDING AND CURRENT ROW:
=> SELECT calendar_month_number_in_year, SUM(product_price) AS sales,
AVG(SUM(product_price)) OVER (ORDER BY calendar_month_number_in_year)
FROM product_dimension, date_dimension, inventory_fact
WHERE date_dimension.date_key = inventory_fact.date_key
AND product_dimension.product_key = inventory_fact.product_key
GROUP BY calendar_month_number_in_year;
calendar_month_number_in_year | sales
|
?column?
-------------------------------+----------+-----------------1 | 23869547 |
23869547
2 | 19604661 |
21737104
3 | 22877913 | 22117373.6666667
4 | 22901263 |
22313346
5 | 23670676 |
22584812

HP Vertica Analytic Database (7.0.x)

Page 212 of 1539

SQL Reference Manual
SQL Functions

6
7
8
9
10
11
12

|
|
|
|
|
|
|

22507600
21514089
24860684
21687795
23648921
21115910
24708317

|
|
|
|
|
|
|

22571943.3333333
22420821.2857143
22725804.125
22610469.7777778
22714314.9
22569005.3636364
22747281.3333333

(12 rows)

To return a moving average that is not a running (cumulative) average, the window should specify
ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING:
=> SELECT calendar_month_number_in_year, SUM(product_price) AS sales,
AVG(SUM(product_price)) OVER (ORDER BY calendar_month_number_in_year
ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING)
FROM product_dimension, date_dimension, inventory_fact
WHERE date_dimension.date_key = inventory_fact.date_key
AND product_dimension.product_key = inventory_fact.product_key
GROUP BY calendar_month_number_in_year;

See Also
l

AVG [Aggregate]

l

COUNT [Analytic]

l

SUM [Analytic]

l

Using SQL Analytics

CONDITIONAL_CHANGE_EVENT [Analytic]
Assigns an event window number to each row, starting from 0, and increments by 1 when the result
of evaluating the argument expression on the current row differs from that on the previous row.

Behavior Type
Immutable

Syntax
CONDITIONAL_CHANGE_EVENT ( expression ) OVER (
... [ window_partition_clause ]
... window_order_clause )

HP Vertica Analytic Database (7.0.x)

Page 213 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

SQL scalar expression that is evaluated on an input record. The result of expression
can be of any data type.

OVER(...)

See Analytic Functions.

Notes
The analytic window_order_clause is required but the window_partition_clause is optional.

Example
=> SELECT CONDITIONAL_CHANGE_EVENT(bid)
OVER (PARTITION BY symbol ORDER BY ts) AS cce
FROM TickStore;

The system returns an error when no ORDER BY clause is present:
=> SELECT CONDITIONAL_CHANGE_EVENT(bid)
OVER (PARTITION BY symbol) AS cce
FROM TickStore;
ERROR: conditional_change_event must contain an
ORDER BY clause within its analytic clause

For more examples, see Event-Based Windows in the Programmer's Guide.

See Also
l

CONDITIONAL_TRUE_EVENT [Analytic]

l

ROW_NUMBER [Analytic]

l

Using Time Series Analytics

l

Event-Based Windows

CONDITIONAL_TRUE_EVENT [Analytic]
Assigns an event window number to each row, starting from 0, and increments the number by 1
when the result of the boolean argument expression evaluates true. For example, given a sequence
of values for column a, as follows:
( 1, 2, 3, 4, 5, 6 )

CONDITIONAL_TRUE_EVENT(a > 3) returns 0, 0, 0, 1, 2, 3.

HP Vertica Analytic Database (7.0.x)

Page 214 of 1539

SQL Reference Manual
SQL Functions

Behavior Type:
Immutable

Syntax
CONDITIONAL_TRUE_EVENT ( boolean-expression ) OVER
... ( [ window_partition_clause ]
... window_order_clause )

Parameters
boolean-expression

SQL scalar expression that is evaluated on an input record, type
BOOLEAN.

OVER(...)

See Analytic Functions.

Notes
The analytic window_order_clause is required but the window_partition_clause is optional.

Example
> SELECT CONDITIONAL_TRUE_EVENT(bid > 10.6)
OVER(PARTITION BY bid ORDER BY ts) AS cte
FROM Tickstore;

The system returns an error if the ORDER BY clause is omitted:
> SELECT CONDITIONAL_TRUE_EVENT(bid > 10.6)
OVER(PARTITION BY bid) AS cte
FROM Tickstore;
ERROR: conditional_true_event must contain an ORDER BY
clause within its analytic clause

For more examples, see Event-Based Windows in the Programmer's Guide.

See Also
l

CONDITIONAL_CHANGE_EVENT [Analytic]

l

Using Time Series Analytics

l

Event-Based Windows

HP Vertica Analytic Database (7.0.x)

Page 215 of 1539

SQL Reference Manual
SQL Functions

COUNT [Analytic]
Counts occurrences within a group within a window. If you specify * or some non-null constant,
COUNT() counts all rows.

Behavior Type
Immutable

Syntax
COUNT
... [
... [
... [

( expression ) OVER (
window_partition_clause ]
window_order_clause ]
window_frame_clause ] )

Parameters
expression

Returns the number of rows in each group for which the expression is not null. Can
be any expression resulting in BIGINT.

OVER(...)

See Analytic Functions.

Example
Using the schema defined in Window Framing in the Programmer's Guide, the following COUNT
function does not specify an order_clause or a frame_clause; otherwise it would be treated as a
window aggregate. Think of the window of reporting aggregates as UNBOUNDED PRECEDING
and UNBOUNDED FOLLOWING.
=> SELECT deptno, sal, empno, COUNT(sal)
OVER (PARTITION BY deptno) AS count FROM emp;
deptno | sal | empno | count
--------+-----+-------+------10 | 101 |
1 |
2
10 | 104 |
4 |
2
20 | 110 |
10 |
6
20 | 110 |
9 |
6
20 | 109 |
7 |
6
20 | 109 |
6 |
6
20 | 109 |
8 |
6
20 | 109 |
11 |
6
30 | 105 |
5 |
3
30 | 103 |
3 |
3
30 | 102 |
2 |
3

Using ORDER BY sal creates a moving window query with default window: RANGE BETWEEN
UNBOUNDED PRECEDING AND CURRENT ROW.

HP Vertica Analytic Database (7.0.x)

Page 216 of 1539

SQL Reference Manual
SQL Functions

=> SELECT deptno, sal, empno, COUNT(sal)
OVER (PARTITION BY deptno ORDER BY sal) AS count
FROM emp;
deptno | sal | empno | count
--------+-----+-------+------10 | 101 |
1 |
1
10 | 104 |
4 |
2
20 | 100 |
11 |
1
20 | 109 |
7 |
4
20 | 109 |
6 |
4
20 | 109 |
8 |
4
20 | 110 |
10 |
6
20 | 110 |
9 |
6
30 | 102 |
2 |
1
30 | 103 |
3 |
2
30 | 105 |
5 |
3

Using the VMart schema, the following query finds the number of employees who make less than or
equivalent to the hourly rate of the current employee. The query returns a running/cumulative
average (sometimes called a moving average) using the default window of RANGE UNBOUNDED
PRECEDING AND CURRENT ROW:
=> SELECT employee_last_name AS "last_name", hourly_rate, COUNT(*)
OVER (ORDER BY hourly_rate) AS moving_count from employee_dimension;
last_name | hourly_rate | moving_count
------------+-------------+-------------Gauthier
|
6 |
4
Taylor
|
6 |
4
Jefferson |
6 |
4
Nielson
|
6 |
4
McNulty
|
6.01 |
11
Robinson
|
6.01 |
11
Dobisz
|
6.01 |
11
Williams
|
6.01 |
11
Kramer
|
6.01 |
11
Miller
|
6.01 |
11
Wilson
|
6.01 |
11
Vogel
|
6.02 |
14
Moore
|
6.02 |
14
Vogel
|
6.02 |
14
Carcetti
|
6.03 |
19
...

To return a moving average that is not also a running (cumulative) average, the window should
specify ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING:
=> SELECT employee_last_name AS "last_name", hourly_rate, COUNT(*)
OVER (ORDER BY hourly_rate ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING)
AS moving_count from employee_dimension;

HP Vertica Analytic Database (7.0.x)

Page 217 of 1539

SQL Reference Manual
SQL Functions

See Also
l

COUNT [Aggregate]

l

AVG [Analytic]

l

SUM [Analytic]

l

Using SQL Analytics

CUME_DIST [Analytic]
Calculates the cumulative distribution, or relative rank, of the current row with regard to other rows
in the same partition within a window.
CUME_DIST() returns a number greater then 0 and less then or equal to 1, where the number
represents the relative position of the specified row within a group of N rows. For a row x (assuming
ASC ordering), the CUME_DIST of x is the number of rows with values lower than or equal to the value
of x, divided by the number of rows in the partition. In a group of three rows, for example, the
cumulative distribution values returned would be 1/3, 2/3, and 3/3.
Note: Because the result for a given row depends on the number of rows preceding that row in
the same partition, HP recommends that you always specify a window_order_clause when
you call this function.

Behavior Type
Immutable

Syntax
CUME_DIST ( ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
OVER(...)

See Analytic Functions.

Notes
The analytic window_order_clause is required but the window_partition_clause is optional.

HP Vertica Analytic Database (7.0.x)

Page 218 of 1539

SQL Reference Manual
SQL Functions

Examples
The following example returns the cumulative distribution of sales for different transaction types
within each month of the first quarter.
=> SELECT calendar_month_name AS month, tender_type, SUM(sales_quantity),
CUME_DIST()
OVER (PARTITION BY calendar_month_name ORDER BY SUM(sales_quantity)) AS
CUME_DIST
FROM store.store_sales_fact JOIN date_dimension
USING(date_key) WHERE calendar_month_name IN ('January','February','March')
AND tender_type NOT LIKE 'Other'
GROUP BY calendar_month_name, tender_type;

month
| tender_type | SUM
| CUME_DIST
----------+-------------+--------+----------March
| Credit
| 469858 |
0.25
March
| Cash
| 470449 |
0.5
March
| Check
| 473033 |
0.75
March
| Debit
| 475103 |
1
January | Cash
| 441730 |
0.25
January | Debit
| 443922 |
0.5
January | Check
| 446297 |
0.75
January | Credit
| 450994 |
1
February | Check
| 425665 |
0.25
February | Debit
| 426726 |
0.5
February | Credit
| 430010 |
0.75
February | Cash
| 430767 |
1
(12 rows)

See Also
l

PERCENT_RANK [Analytic]

l

PERCENTILE_DISC [Analytic]

l

Using SQL Analytics

DENSE_RANK [Analytic]
Computes the relative rank of each row returned from a query with respect to the other rows, based
on the values of the expressions in the window ORDER BY clause.
The data within a group is sorted by the ORDER BY clause and then a numeric ranking is assigned to
each row in turn starting with 1 and continuing from there. The rank is incremented every time the
values of the ORDER BY expressions change. Rows with equal values receive the same rank (nulls
are considered equal in this comparison). A DENSE_RANK() function returns a ranking number
without any gaps, which is why it is called "DENSE."

HP Vertica Analytic Database (7.0.x)

Page 219 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
DENSE_RANK ( ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
OVER(...)

See Analytic Functions.

Notes
l

The analytic window_order_clause is required but the window_partition_clause is optional.

l

The ranks are consecutive integers beginning with 1. The largest rank value is the number of
unique values returned by the query.

l

The primary difference between DENSE_RANK() and RANK() is that RANK leaves gaps when
ranking records whereas DENSE_RANK leaves no gaps. For example, N records occupy a
particular position (say, a tie for rank X), RANK assigns all those records with rank X and skips
the next N ranks, therefore the next assigned rank is X+N. DENSE_RANK places all the records in
that position only—it does not skip any ranks.
If there is a tie at the third position with two records having the same value, RANK and DENSE_
RANK place both the records in the third position, but RANK places the next record at the fifth
position, while DENSE_RANK places the next record at the fourth position.

l

If you omit NULLS FIRST | LAST | AUTO, the ordering of the NULL values depends on the ASC or
DESC arguments. NULL values are considered larger than any other value. If the ordering
sequence is ASC, then nulls appear last; nulls appear first otherwise. Nulls are considered equal
to other nulls and, therefore, the order in which nulls are presented is non-deterministic.

Example
The following example shows the difference between RANK and DENSE_RANK when ranking
customers by their annual income. Notice that RANK has a tie at 10 and skips 11, while DENSE_RANK
leaves no gaps in the ranking sequence:
=> SELECT customer_name, SUM(annual_income),
RANK () OVER (ORDER BY TO_CHAR(SUM(annual_income),'100000') DESC) rank,
DENSE_RANK () OVER (ORDER BY TO_CHAR(SUM(annual_income),'100000') DESC) dense_rank
FROM customer_dimension GROUP BY customer_name LIMIT 15;

HP Vertica Analytic Database (7.0.x)

Page 220 of 1539

SQL Reference Manual
SQL Functions

customer_name
| sum | rank | dense_rank
---------------------+-------+------+-----------Brian M. Garnett
| 99838 |
1 |
1
Tanya A. Brown
| 99834 |
2 |
2
Tiffany P. Farmer
| 99826 |
3 |
3
Jose V. Sanchez
| 99673 |
4 |
4
Marcus D. Rodriguez | 99631 |
5 |
5
Alexander T. Nguyen | 99604 |
6 |
6
Sarah G. Lewis
| 99556 |
7 |
7
Ruth Q. Vu
| 99542 |
8 |
8
Theodore T. Farmer | 99532 |
9 |
9
Daniel P. Li
| 99497 |
10 |
10
Seth E. Brown
| 99497 |
10 |
10
Matt X. Gauthier
| 99402 |
12 |
11
Rebecca W. Lewis
| 99296 |
13 |
12
Dean L. Wilson
| 99276 |
14 |
13
Tiffany A. Smith
| 99257 |
15 |
14
(15 rows)

See Also
l

RANK [Analytic]

l

Using SQL Analytics

EXPONENTIAL_MOVING_AVERAGE [Analytic]
Calculates the exponential moving average of expression E with smoothing factor X.
The exponential moving average (EMA) is calculated by adding the previous EMA value to the
current data point scaled by the smoothing factor, as in the following formula, where:
l

EMA0 is the previous row's EMA value

l

X is the smoothing factor

l

E is the current data point: EMA = EMA0 + (X * (E - EMA0))

EXPONENTIAL_MOVING_AVERAGE() is different from a simple moving average in that it
provides a more stable picture of changes to data over time.

Behavior Type
Immutable

Syntax
EXPONENTIAL_MOVING_AVERAGE ( E , X ) OVER (
... [ window_partition_clause ]
... window_order_clause )

HP Vertica Analytic Database (7.0.x)

Page 221 of 1539

SQL Reference Manual
SQL Functions

Parameters
E

The value whose average is calculated over a set of rows. Can be INTEGER, FLOAT or
NUMERIC type and must be a constant.

X

A positive FLOAT value between 0 and 1 that is used as the smoothing factor.

OVER(...)

See Analytic Functions.

Notes
l

The analytic window_order_clause is required but the window_partition_clause is optional.

l

There is no [Aggregate] equivalent of this function because of its unique semantics.

l

The EXPONENTIAL_MOVING_AVERAGE() function also works at the row level; for example, EMA
assumes the data in a given column is sampled at uniform intervals. If the users' data points are
sampled at non-uniform intervals, they should run the time series gap filling and interpolation
(GFI) operations before EMA().

Examples
The following example uses time series gap filling and interpolation (GFI) first in a subquery, and
then performs an EXPONENTIAL_MOVING_AVERAGE operation on the subquery result.
Create a simple four-column table:
=> CREATE TABLE ticker(
time TIMESTAMP,
symbol VARCHAR(8),
bid1 FLOAT,
bid2 FLOAT );

Insert some data, including nulls, so GFI can do its interpolation and gap filling:
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>

INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
INSERT INTO
COMMIT;

ticker
ticker
ticker
ticker
ticker
ticker
ticker
ticker
ticker
ticker

VALUES
VALUES
VALUES
VALUES
VALUES
VALUES
VALUES
VALUES
VALUES
VALUES

('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12
('2009-07-12

03:00:00',
03:00:01',
03:00:02',
03:00:03',
03:00:04',
03:00:00',
03:00:01',
03:00:02',
03:00:03',
03:00:04',

'ABC',
'ABC',
'ABC',
'ABC',
'ABC',
'XYZ',
'XYZ',
'XYZ',
'XYZ',
'XYZ',

60.45, 60.44);
60.49, 65.12);
57.78, 59.25);
null, 65.12);
67.88, null);
47.55, 40.15);
44.35, 46.78);
71.56, 75.78);
85.55, 70.21);
45.55, 58.65);

Note: During gap filling and interpolation, HP Vertica takes the closest non null value on either

HP Vertica Analytic Database (7.0.x)

Page 222 of 1539

SQL Reference Manual
SQL Functions

side of the time slice and uses that value. For example, if you use a linear interpolation scheme
and you do not specify IGNORE NULLS, and your data has one real value and one null, the result
is null. If the value on either side is null, the result is null. See When Time Series Data Contains
Nulls in the Programmer's Guide for details.
Query the table that you just created to you can see the output:
=> SELECT * FROM ticker;
time
| symbol | bid1 | bid2
---------------------+--------+-------+------2009-07-12 03:00:00 | ABC
| 60.45 | 60.44
2009-07-12 03:00:01 | ABC
| 60.49 | 65.12
2009-07-12 03:00:02 | ABC
| 57.78 | 59.25
2009-07-12 03:00:03 | ABC
|
| 65.12
2009-07-12 03:00:04 | ABC
| 67.88 |
2009-07-12 03:00:00 | XYZ
| 47.55 | 40.15
2009-07-12 03:00:01 | XYZ
| 44.35 | 46.78
2009-07-12 03:00:02 | XYZ
| 71.56 | 75.78
2009-07-12 03:00:03 | XYZ
| 85.55 | 70.21
2009-07-12 03:00:04 | XYZ
| 45.55 | 58.65
(10 rows)

The following query processes the first and last values that belong to each 2-second time slice in
table trades' column a. The query then calculates the exponential moving average of expression fv
and lv with a smoothing factor of 50%:
=> SELECT symbol, slice_time, fv, lv,
EXPONENTIAL_MOVING_AVERAGE(fv, 0.5)
OVER (PARTITION BY symbol ORDER BY slice_time) AS ema_first,
EXPONENTIAL_MOVING_AVERAGE(lv, 0.5)
OVER (PARTITION BY symbol ORDER BY slice_time) AS ema_last
FROM (
SELECT symbol, slice_time,
TS_FIRST_VALUE(bid1 IGNORE NULLS) as fv,
TS_LAST_VALUE(bid2 IGNORE NULLS) AS lv
FROM ticker TIMESERIES slice_time AS '2 seconds'
OVER (PARTITION BY symbol ORDER BY time) ) AS sq;

symbol |
slice_time
| fv
| lv
| ema_first | ema_last
--------+---------------------+-------+-------+-----------+---------ABC
| 2009-07-12 03:00:00 | 60.45 | 65.12 |
60.45 |
65.12
ABC
| 2009-07-12 03:00:02 | 57.78 | 65.12 |
59.115 |
65.12
ABC
| 2009-07-12 03:00:04 | 67.88 | 65.12 |
63.4975 |
65.12
XYZ
| 2009-07-12 03:00:00 | 47.55 | 46.78 |
47.55 |
46.78
XYZ
| 2009-07-12 03:00:02 | 71.56 | 70.21 |
59.555 |
58.495
XYZ
| 2009-07-12 03:00:04 | 45.55 | 58.65 |
52.5525 | 58.5725
(6 rows)

HP Vertica Analytic Database (7.0.x)

Page 223 of 1539

SQL Reference Manual
SQL Functions

See Also
l

TIMESERIES Clause

l

Using Time Series Analytics

l

Using SQL Analytics

FIRST_VALUE [Analytic]
Allows the selection of the first value of a table or partition without having to use a self-join. If no
window is specified for the current row, the default window is UNBOUNDED PRECEDING AND
CURRENT ROW.

Behavior Type
Immutable

Syntax
FIRST_VALUE ( expression [ IGNORE NULLS ] ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Expression to evaluate; for example, a constant, column, nonanalytic function,
function expression, or expressions involving any of these.

IGNORE NULLS

Specifies to return the first non-null value in the set, or NULL if all values are NULL.

OVER(...)

See Analytic Functions.

Notes
l

The FIRST_VALUE() function lets you select a table's first value (determined by the window_
order_clause) without having to use a self join. This function is useful when you want to use
the first value as a baseline in calculations.

l

HP recommends that you use FIRST_VALUE with the window_order_clause to produce
deterministic results.

l

If the first value in the set is null, then the function returns NULL unless you specify IGNORE
NULLS. If you specify IGNORE NULLS, FIRST_VALUE returns the first non-null value in the set, or
NULL if all values are null.

HP Vertica Analytic Database (7.0.x)

Page 224 of 1539

SQL Reference Manual
SQL Functions

Examples
The following query, which asks for the first value in the partitioned day of week, illustrates the
potential nondeterministic nature of the FIRST_VALUE function:
=> SELECT calendar_year, date_key, day_of_week, full_date_description,
FIRST_VALUE(full_date_description)
OVER(PARTITION BY calendar_month_number_in_year ORDER BY day_of_week)
AS "first_value"
FROM date_dimension
WHERE calendar_year=2003 AND calendar_month_number_in_year=1;

The first value returned is January 31, 2003; however, the next time the same query is run, the first
value could be January 24 or January 3, or the 10th or 17th. The reason is because the analytic
ORDER BY column (day_of_week) returns rows that contain ties (multiple Fridays). These repeated
values make the ORDER BY evaluation result nondeterministic, because rows that contain ties can
be ordered in any way, and any one of those rows qualifies as being the first value of day_of_week.
calendar_year | date_key | day_of_week | full_date_description |first_value
--------------+----------+-------------+-----------------------+----------2003 |
31 | Friday
| January 31, 2003
| January 31,
2003 |
24 | Friday
| January 24, 2003
| January 31,
2003 |
3 | Friday
| January 3, 2003
| January 31,
2003 |
10 | Friday
| January 10, 2003
| January 31,
2003 |
17 | Friday
| January 17, 2003
| January 31,
2003 |
6 | Monday
| January 6, 2003
| January 31,
2003 |
27 | Monday
| January 27, 2003
| January 31,
2003 |
13 | Monday
| January 13, 2003
| January 31,
2003 |
20 | Monday
| January 20, 2003
| January 31,
2003 |
11 | Saturday
| January 11, 2003
| January 31,
2003 |
18 | Saturday
| January 18, 2003
| January 31,
2003 |
25 | Saturday
| January 25, 2003
| January 31,
2003 |
4 | Saturday
| January 4, 2003
| January 31,
2003 |
12 | Sunday
| January 12, 2003
| January 31,
2003 |
26 | Sunday
| January 26, 2003
| January 31,
2003 |
5 | Sunday
| January 5, 2003
| January 31,
2003 |
19 | Sunday
| January 19, 2003
| January 31,
2003 |
23 | Thursday
| January 23, 2003
| January 31,
2003 |
2 | Thursday
| January 2, 2003
| January 31,
2003 |
9 | Thursday
| January 9, 2003
| January 31,
2003 |
16 | Thursday
| January 16, 2003
| January 31,
2003 |
30 | Thursday
| January 30, 2003
| January 31,
2003 |
21 | Tuesday
| January 21, 2003
| January 31,
2003 |
14 | Tuesday
| January 14, 2003
| January 31,
2003 |
7 | Tuesday
| January 7, 2003
| January 31,
2003 |
28 | Tuesday
| January 28, 2003
| January 31,
2003 |
22 | Wednesday
| January 22, 2003
| January 31,
2003 |
29 | Wednesday
| January 29, 2003
| January 31,
2003 |
15 | Wednesday
| January 15, 2003
| January 31,
2003 |
1 | Wednesday
| January 1, 2003
| January 31,
2003 |
8 | Wednesday
| January 8, 2003
| January 31,
(31 rows)

HP Vertica Analytic Database (7.0.x)

2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003
2003

Page 225 of 1539

SQL Reference Manual
SQL Functions

Note: The day_of_week results are returned in alphabetical order because of lexical rules. The
fact that each day does not appear ordered by the 7-day week cycle (for example, starting with
Sunday followed by Monday, Tuesday, and so on) has no affect on results.
To return deterministic results, modify the query so that it performs its analytic ORDER BY operations
on a unique field, such as date_key:
=> SELECT calendar_year, date_key, day_of_week, full_date_description,
FIRST_VALUE(full_date_description) OVER
(PARTITION BY calendar_month_number_in_year ORDER BY date_key) AS "first_value"
FROM date_dimension WHERE calendar_year=2003;

Notice that the results return a first value of January 1 for the January partition and the first value of
February 1 for the February partition. Also, there are no ties in the full_date_description
column:
calendar_year | date_key | day_of_week | full_date_description | first_value
---------------+----------+-------------+-----------------------+-----------2003 |
1 | Wednesday
| January 1, 2003
| January 1, 2003
2003 |
2 | Thursday
| January 2, 2003
| January 1, 2003
2003 |
3 | Friday
| January 3, 2003
| January 1, 2003
2003 |
4 | Saturday
| January 4, 2003
| January 1, 2003
2003 |
5 | Sunday
| January 5, 2003
| January 1, 2003
2003 |
6 | Monday
| January 6, 2003
| January 1, 2003
2003 |
7 | Tuesday
| January 7, 2003
| January 1, 2003
2003 |
8 | Wednesday
| January 8, 2003
| January 1, 2003
2003 |
9 | Thursday
| January 9, 2003
| January 1, 2003
2003 |
10 | Friday
| January 10, 2003
| January 1, 2003
2003 |
11 | Saturday
| January 11, 2003
| January 1, 2003
2003 |
12 | Sunday
| January 12, 2003
| January 1, 2003
2003 |
13 | Monday
| January 13, 2003
| January 1, 2003
2003 |
14 | Tuesday
| January 14, 2003
| January 1, 2003
2003 |
15 | Wednesday
| January 15, 2003
| January 1, 2003
2003 |
16 | Thursday
| January 16, 2003
| January 1, 2003
2003 |
17 | Friday
| January 17, 2003
| January 1, 2003
2003 |
18 | Saturday
| January 18, 2003
| January 1, 2003
2003 |
19 | Sunday
| January 19, 2003
| January 1, 2003
2003 |
20 | Monday
| January 20, 2003
| January 1, 2003
2003 |
21 | Tuesday
| January 21, 2003
| January 1, 2003
2003 |
22 | Wednesday
| January 22, 2003
| January 1, 2003
2003 |
23 | Thursday
| January 23, 2003
| January 1, 2003
2003 |
24 | Friday
| January 24, 2003
| January 1, 2003
2003 |
25 | Saturday
| January 25, 2003
| January 1, 2003
2003 |
26 | Sunday
| January 26, 2003
| January 1, 2003
2003 |
27 | Monday
| January 27, 2003
| January 1, 2003
2003 |
28 | Tuesday
| January 28, 2003
| January 1, 2003
2003 |
29 | Wednesday
| January 29, 2003
| January 1, 2003
2003 |
30 | Thursday
| January 30, 2003
| January 1, 2003
2003 |
31 | Friday
| January 31, 2003
| January 1, 2003
2003 |
32 | Saturday
| February 1, 2003
| February 1, 2003
2003 |
33 | Sunday
| February 2, 2003
| February 1,2003
...
(365 rows)

HP Vertica Analytic Database (7.0.x)

Page 226 of 1539

SQL Reference Manual
SQL Functions

See Also
l

LAST_VALUE [Analytic]

l

TIME_SLICE

l

Using SQL Analytics

LAG [Analytic]
Returns the value of the input expression at the given offset before the current row within a
window.

Behavior Type
Immutable

Syntax
LAG ( expression [, offset ] [, default ] ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
expression

Is the expression to evaluate; for example, a constant, column, non-analytic
function, function expression, or expressions involving any of these.

offset

[Optional] Indicates how great is the lag. The default value is 1 (the previous row).
The offset parameter must be (or can be evaluated to) a constant positive integer.

default

NULL. This optional parameter is the value returned if offset falls outside the bounds
of the table or partition.
Note: The default input argument must be a constant value or an expression
that can be evaluated to a constant; its data type is coercible to that of the first
argument.

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 227 of 1539

SQL Reference Manual
SQL Functions

Notes
l

The analytic window_order_clause is required but the window_partition_clause is optional.

l

The LAG() function returns values from the row before the current row, letting you access more
than one row in a table at the same time. This is useful for comparing values when the relative
positions of rows can be reliably known. It also lets you avoid the more costly self join, which
enhances query processing speed.

l

See LEAD() for how to get the next rows.

l

Analytic functions, such as LAG(), cannot be nested within aggregate functions.

Examples
This example sums the current balance by date in a table and also sums the previous balance from
the last day. Given the inputs that follow, the data satisfies the following conditions:
l

For each some_id, there is exactly 1 row for each date represented by month_date.

l

For each some_id, the set of dates is consecutive; that is, if there is a row for February 24 and a
row for February 26, there would also be a row for February 25.

l

Each some_id has the same set of dates.
=> CREATE TABLE balances (
month_date DATE,
current_bal INT,
some_id INT);
=>
=>
=>
=>
=>
=>
=>
=>
=>

INSERT
INSERT
INSERT
INSERT
INSERT
INSERT
INSERT
INSERT
INSERT

INTO
INTO
INTO
INTO
INTO
INTO
INTO
INTO
INTO

balances
balances
balances
balances
balances
balances
balances
balances
balances

values
values
values
values
values
values
values
values
values

('2009-02-24',
('2009-02-25',
('2009-02-26',
('2009-02-24',
('2009-02-25',
('2009-02-26',
('2009-02-24',
('2009-02-25',
('2009-02-26',

10,
10,
10,
20,
20,
20,
30,
20,
30,

1);
1);
1);
2);
2);
2);
3);
3);
3);

Now run the LAG() function to sum the current balance for each date and sum the previous balance
from the last day:
=> SELECT month_date,
SUM(current_bal) as current_bal_sum,
SUM(previous_bal) as previous_bal_sum FROM
(SELECT month_date, current_bal,
LAG(current_bal, 1, 0) OVER
(PARTITION BY some_id ORDER BY month_date)
AS previous_bal FROM balances) AS subQ

HP Vertica Analytic Database (7.0.x)

Page 228 of 1539

SQL Reference Manual
SQL Functions

GROUP BY month_date ORDER BY month_date;
month_date | current_bal_sum | previous_bal_sum
------------+-----------------+-----------------2009-02-24 |
60 |
0
2009-02-25 |
50 |
60
2009-02-26 |
60 |
50
(3 rows)

Using the same example data, the following query would not be allowed because LAG() is nested
inside an aggregate function:
=> SELECT month_date,
SUM(current_bal) as current_bal_sum,
SUM(LAG(current_bal, 1, 0) OVER
(PARTITION BY some_id ORDER BY month_date)) AS previous_bal_sum
FROM some_table GROUP BY month_date ORDER BY month_date;

In the next example, which uses the VMart example database (see Introducing the VMart Example
Database), the LAG() function first returns the annual income from the previous row, and then it
calculates the difference between the income in the current row from the income in the previous
row. Note: The vmart example database returns over 50,000 rows, so we'll limit the results to 20
records:
=> SELECT occupation, customer_key, customer_name, annual_income,
LAG(annual_income, 1, 0) OVER (PARTITION BY occupation
ORDER BY annual_income) AS prev_income, annual_income LAG(annual_income, 1, 0) OVER (PARTITION BY occupation
ORDER BY annual_income) AS difference
FROM customer_dimension ORDER BY occupation, customer_key LIMIT 20;
occupation | customer_key |
customer_name
| annual_income | prev_income | differe
nce
------------+--------------+----------------------+---------------+-------------+----------Accountant |
15 | Midori V. Peterson
|
692610 |
692535 |
75
Accountant |
43 | Midori S. Rodriguez |
282359 |
280976 |
1
383
Accountant |
93 | Robert P. Campbell
|
471722 |
471355 |
367
Accountant |
102 | Sam T. McNulty
|
901636 |
901561 |
75
Accountant |
134 | Martha B. Overstreet |
705146 |
704335 |
811
Accountant |
165 | James C. Kramer
|
376841 |
376474 |
367
Accountant |
225 | Ben W. Farmer
|
70574 |
70449 |
125
Accountant |
270 | Jessica S. Lang
|
684204 |
682274 |
1
930
Accountant |
273 | Mark X. Lampert
|
723294 |
722737 |
557
Accountant |
295 | Sharon K. Gauthier
|
29033 |
28412 |
621
Accountant |
338 | Anna S. Jackson
|
816858 |
815557 |

HP Vertica Analytic Database (7.0.x)

Page 229 of 1539

SQL Reference Manual
SQL Functions

1301
Accountant
277
Accountant
914
Accountant
226
Accountant
244
Accountant
620
Accountant
707
Accountant
383
Accountant
336
Accountant
662
(20 rows)

|

377 | William I. Jones

|

915149 |

914872 |

|

438 | Joanna A. McCabe

|

147396 |

144482 |

2

|

452 | Kim P. Brown

|

126023 |

124797 |

1

|

467 | Meghan K. Carcetti

|

810528 |

810284 |

|

478 | Tanya E. Greenwood

|

639649 |

639029 |

|

511 | Midori P. Vogel

|

187246 |

185539 |

|

525 | Alexander K. Moore

|

677433 |

677050 |

|

550 | Sam P. Reyes

|

735691 |

735355 |

|

577 | Robert U. Vu

|

616101 |

615439 |

1

Continuing with the Vmart database, the next example uses both LEAD() and LAG() to return the
third row after the salary in the current row and fifth salary before the salary in the current row.
=> SELECT hire_date, employee_key, employee_last_name,
LEAD(hire_date, 1) OVER (ORDER BY hire_date) AS "next_hired" ,
LAG(hire_date, 1) OVER (ORDER BY hire_date) AS "last_hired"
FROM employee_dimension ORDER BY hire_date, employee_key;
hire_date | employee_key | employee_last_name | next_hired | last_hired
------------+--------------+--------------------+------------+-----------1956-04-11 |
2694 | Farmer
| 1956-05-12 |
1956-05-12 |
5486 | Winkler
| 1956-09-18 | 1956-04-11
1956-09-18 |
5525 | McCabe
| 1957-01-15 | 1956-05-12
1957-01-15 |
560 | Greenwood
| 1957-02-06 | 1956-09-18
1957-02-06 |
9781 | Bauer
| 1957-05-25 | 1957-01-15
1957-05-25 |
9506 | Webber
| 1957-07-04 | 1957-02-06
1957-07-04 |
6723 | Kramer
| 1957-07-07 | 1957-05-25
1957-07-07 |
5827 | Garnett
| 1957-11-11 | 1957-07-04
1957-11-11 |
373 | Reyes
| 1957-11-21 | 1957-07-07
1957-11-21 |
3874 | Martin
| 1958-02-06 | 1957-11-11
(10 rows)

The following example specifies arguments that use different data types; for example annual_
income(INT) and occupation(VARCHAR). The query returns an error:
=> SELECT customer_key, customer_name, occupation, annual_income,
LAG (annual_income, 1, occupation) OVER
(PARTITION BY occupation ORDER BY customer_key) LAG1
FROM customer_dimension ORDER BY 3, 1;
ERROR: Third argument of lag could not be converted from type character varying to ty
pe int8
HINT: You may need to add explicit type cast.

HP Vertica Analytic Database (7.0.x)

Page 230 of 1539

SQL Reference Manual
SQL Functions

See Also
l

LEAD [Analytic]

l

Using SQL Analytics

LAST_VALUE [Analytic]
Returns values of the expression from the last row of a window for the current row. If no window is
specified for the current row, the default window is UNBOUNDED PRECEDING AND CURRENT ROW.

Behavior Type
Immutable

Syntax
LAST_VALUE ( expression [ IGNORE NULLS ] ) OVER ( ... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Is the expression to evaluate; for example, a constant, column, nonanalytic
function, function expression, or expressions involving any of these.

IGNORE NULLS

Returns the last non-null value in the set, or NULL if all values are NULL.

OVER(...)

See Analytic Functions.

Notes
l

The LAST_VALUE() function lets you select a window's last value (determined by the window_
order_clause), without having to use a self join. This function is useful when you want to use the
last value as a baseline in calculations.

l

LAST_VALUE() takes the last record from the partition after the analytic window_order_clause.
The expression is then computed against the last record, and results are returned.

l

HP recommends that you use LAST_VALUE with the window_order_clause to produce
deterministic results.
Tip: Due to default window semantics, LAST_VALUE does not always return the last value
of a partition. If you omit the window_frame_clause from the analytic clause, LAST_VALUE

HP Vertica Analytic Database (7.0.x)

Page 231 of 1539

SQL Reference Manual
SQL Functions

operates on this default window. Although results can seem non-intuitive by not returning
the bottom of the current partition, it returns the bottom of the window, which continues to
change along with the current input row being processed. If you want to return the last value
of a partition, use UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING. See
examples below.

l

If the last value in the set is null, then the function returns NULL unless you specify IGNORE
NULLS. If you specify IGNORE NULLS, LAST_VALUE returns the fist non-null value in the set,
or NULL if all values are null.

Example
Using the schema defined in Window Framing in the Programmer's Guide, the following query does
not show the highest salary value by department; instead it shows the highest salary value by
department by salary.
=> SELECT deptno, sal, empno, LAST_VALUE(sal)
OVER (PARTITION BY deptno ORDER BY sal) AS lv
FROM emp;
deptno | sal | empno |
lv
--------+-----+-------+-------10 | 101 |
1 |
101
10 | 104 |
4 |
104
20 | 100 |
11 |
100
20 | 109 |
7 |
109
20 | 109 |
6 |
109
20 | 109 |
8 |
109
20 | 110 |
10 |
110
20 | 110 |
9 |
110
30 | 102 |
2 |
102
30 | 103 |
3 |
103
30 | 105 |
5 |
105

If you include the window_frame clause ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED
FOLLOWING, the LAST_VALUE() function will return the highest salary by department, an accurate
representation of the information.
=> SELECT deptno, sal, empno, LAST_VALUE(sal)
OVER (PARTITION BY deptno ORDER BY sal
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS lv
FROM emp;
deptno | sal | empno |
lv
--------+-----+-------+-------10 | 101 |
1 |
104
10 | 104 |
4 |
104
20 | 100 |
11 |
110
20 | 109 |
7 |
110
20 | 109 |
6 |
110
20 | 109 |
8 |
110
20 | 110 |
10 |
110

HP Vertica Analytic Database (7.0.x)

Page 232 of 1539

SQL Reference Manual
SQL Functions

20
30
30
30

|
|
|
|

110
102
103
105

|
|
|
|

9
2
3
5

|
|
|
|

110
105
105
105

For additional examples, see FIRST_VALUE().

See Also
FIRST_VALUE [Analytic]

l

TIME_SLICE

l
l

LEAD [Analytic]
Returns the value of the input expression at the given offset after the current row within a window.

Behavior Type
Immutable

Syntax
LEAD ( expression [, offset ] [, default ] ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
expression

Is the expression to evaluate; for example, a constant, column, nonanalytic
function, function expression, or expressions involving any of these.

offset

Is an optional parameter that defaults to 1 (the next row). The offset parameter must
be (or can be evaluated to) a constant positive integer.

default

Is NULL. This optional parameter is the value returned if offset falls outside the
bounds of the table or partition.
Note: The third input argument must be a constant value or an expression that
can be evaluated to a constant; its data type is coercible to that of the first
argument.

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 233 of 1539

SQL Reference Manual
SQL Functions

Notes
l

The analytic window_order_clause is required but the window_partition_clause is optional.

l

The LEAD() function returns values from the row after the current row, letting you access more
than one row in a table at the same time. This is useful for comparing values when the relative
positions of rows can be reliably known. It also lets you avoid the more costly self join, which
enhances query processing speed.

l

Analytic functions, such as LEAD(), cannot be nested within aggregate functions.

Examples
In this example, the LEAD() function finds the hire date of the employee hired just after the current
row:
=> SELECT employee_region, hire_date, employee_key, employee_last_name,
LEAD(hire_date, 1) OVER (PARTITION BY employee_region ORDER BY hire_date) AS "next_hir
ed"
FROM employee_dimension ORDER BY employee_region, hire_date, employee_key;
employee_region | hire_date | employee_key | employee_last_name | next_hired
-------------------+------------+--------------+--------------------+-----------East
| 1956-04-08 |
9218 | Harris
| 1957-02-06
East
| 1957-02-06 |
7799 | Stein
| 1957-05-25
East
| 1957-05-25 |
3687 | Farmer
| 1957-06-26
East
| 1957-06-26 |
9474 | Bauer
| 1957-08-18
East
| 1957-08-18 |
570 | Jefferson
| 1957-08-24
East
| 1957-08-24 |
4363 | Wilson
| 1958-02-17
East
| 1958-02-17 |
6457 | McCabe
| 1958-06-26
East
| 1958-06-26 |
6196 | Li
| 1958-07-16
East
| 1958-07-16 |
7749 | Harris
| 1958-09-18
East
| 1958-09-18 |
9678 | Sanchez
| 1958-11-10
(10 rows)

The next example uses both LEAD() and LAG() to return the third row after the salary in the current
row and fifth salary before the salary in the current row.
=> SELECT hire_date, employee_key, employee_last_name,
LEAD(hire_date, 1) OVER (ORDER BY hire_date) AS "next_hired" ,
LAG(hire_date, 1) OVER (ORDER BY hire_date) AS "last_hired"
FROM employee_dimension ORDER BY hire_date, employee_key;
hire_date | employee_key | employee_last_name | next_hired | last_hired
------------+--------------+--------------------+------------+-----------1956-04-11 |
2694 | Farmer
| 1956-05-12 |
1956-05-12 |
5486 | Winkler
| 1956-09-18 | 1956-04-11
1956-09-18 |
5525 | McCabe
| 1957-01-15 | 1956-05-12
1957-01-15 |
560 | Greenwood
| 1957-02-06 | 1956-09-18
1957-02-06 |
9781 | Bauer
| 1957-05-25 | 1957-01-15
1957-05-25 |
9506 | Webber
| 1957-07-04 | 1957-02-06
1957-07-04 |
6723 | Kramer
| 1957-07-07 | 1957-05-25
1957-07-07 |
5827 | Garnett
| 1957-11-11 | 1957-07-04
1957-11-11 |
373 | Reyes
| 1957-11-21 | 1957-07-07

HP Vertica Analytic Database (7.0.x)

Page 234 of 1539

SQL Reference Manual
SQL Functions

1957-11-21 |
(10 rows)

3874 | Martin

| 1958-02-06 | 1957-11-11

The following example returns employee name and salary, along with the next highest and lowest
salaries.
=> SELECT employee_last_name, annual_salary,
NVL(LEAD(annual_salary) OVER (ORDER BY annual_salary),
MIN(annual_salary) OVER()) "Next Highest",
NVL(LAG(annual_salary) OVER (ORDER BY annual_salary),
MAX(annual_salary) OVER()) "Next Lowest"
FROM employee_dimension;
employee_last_name | annual_salary | Next Highest | Next Lowest
--------------------+---------------+--------------+------------Nielson
|
1200 |
1200 |
995533
Lewis
|
1200 |
1200 |
1200
Harris
|
1200 |
1202 |
1200
Robinson
|
1202 |
1202 |
1200
Garnett
|
1202 |
1202 |
1202
Weaver
|
1202 |
1202 |
1202
Nielson
|
1202 |
1202 |
1202
McNulty
|
1202 |
1204 |
1202
Farmer
|
1204 |
1204 |
1202
Martin
|
1204 |
1204 |
1204
(10 rows)

The next example returns, for each assistant director in the employees table, the hire date of the
director hired just after the director on the current row. For example, Jackson was hired on 2007-1228, and the next director hired was Bauer:
=> SELECT employee_last_name, hire_date,
LEAD(hire_date, 1) OVER (ORDER BY hire_date DESC) as "NextHired"
FROM employee_dimension WHERE job_title = 'Assistant Director';
employee_last_name | hire_date | NextHired
--------------------+------------+-----------Jackson
| 2007-12-28 | 2007-12-26
Bauer
| 2007-12-26 | 2007-12-11
Miller
| 2007-12-11 | 2007-12-07
Fortin
| 2007-12-07 | 2007-11-27
Harris
| 2007-11-27 | 2007-11-15
Goldberg
| 2007-11-15 |
(5 rows)

See Also
l

LAG [Analytic]

l

Using SQL Analytics

HP Vertica Analytic Database (7.0.x)

Page 235 of 1539

SQL Reference Manual
SQL Functions

MAX [Analytic]
Returns the maximum value of an expression within a window. The return value is the same as the
expression data type.

Behavior Type
Immutable

Syntax
MAX
...
...
...

(
[
[
[

[ DISTINCT ] expression ) OVER (
window_partition_clause ]
window_order_clause ]
window_frame_clause ] )

Parameters
DISTINCT

This parameter has no meaning in this context.

expression

Any expression for which the maximum value is calculated, typically a column
reference .

OVER(...)

See Analytic Functions.

Example
The following query computes the deviation between the employees' annual salary and the
maximum annual salary in Massachusetts:
=> SELECT employee_state, annual_salary,
MAX(annual_salary)
OVER(PARTITION BY employee_state ORDER BY employee_key) max,
annual_salary- MAX(annual_salary)
OVER(PARTITION BY employee_state ORDER BY employee_key) diff
FROM employee_dimension
WHERE employee_state = 'MA';
employee_state | annual_salary | max
| diff
----------------+---------------+--------+--------MA
|
1918 | 995533 | -993615
MA
|
2058 | 995533 | -993475
MA
|
2586 | 995533 | -992947
MA
|
2500 | 995533 | -993033
MA
|
1318 | 995533 | -994215
MA
|
2072 | 995533 | -993461
MA
|
2656 | 995533 | -992877
MA
|
2148 | 995533 | -993385
MA
|
2366 | 995533 | -993167
MA
|
2664 | 995533 | -992869

HP Vertica Analytic Database (7.0.x)

Page 236 of 1539

SQL Reference Manual
SQL Functions

(10 rows)

See Also
MAX [Aggregate]

l

MIN [Analytic]

l
l

MEDIAN [Analytic]
A numerical value of an expression in a result set within a window, which separates the higher half
of a sample from the lower half. For example, a query can retrieve the median of a finite list of
numbers by arranging all observations from lowest value to highest value and then picking the
middle one.
If there is an even number of observations, then there is no single middle value; thus, the median is
defined to be the mean (average) of the two middle values
MEDIAN() is an alias for 50% PERCENTILE(); for example:
PERCENTILE_CONT(0.5) WITHIN GROUP(ORDER BY expression)

Behavior Type
Immutable

Syntax
MEDIAN ( expression ) OVER ( [ window_partition_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the middle value or an
interpolated value that would be the middle value once the values are sorted. Null
values are ignored in the calculation.

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 237 of 1539

SQL Reference Manual
SQL Functions

Notes
l

For each row, MEDIAN() returns the value that would fall in the middle of a value set within each
partition.

l

HP Vertica determines the argument with the highest numeric precedence, implicitly converts
the remaining arguments to that data type, and returns that data type.

l

MEDIAN() does not allow the window_order_clause or window_frame_clause.

Examples
The following query computes the median annual income for first 500 customers in Wisconsin and
in the District of Columbia. The median is reported for every row in each partitioned result set:
=> SELECT customer_state, annual_income,
MEDIAN(annual_income) OVER (PARTITION BY customer_state) AS MEDIAN
FROM customer_dimension
WHERE customer_state IN ('DC','WI')
ORDER BY customer_state;
customer_state | customer_key | annual_income | MEDIAN
----------------+--------------+---------------+---------DC
|
120 |
299768 |
535413
DC
|
113 |
535413 |
535413
DC
|
130 |
848360 |
535413
---------------------------------------------------------WI
|
372 |
34962 |
668147
WI
|
437 |
47128 |
668147
WI
|
435 |
67770 |
668147
WI
|
282 |
638054 |
668147
WI
|
314 |
668147 |
668147
WI
|
128 |
675608 |
668147
WI
|
179 |
825304 |
668147
WI
|
302 |
827618 |
668147
WI
|
29 |
922760 |
668147
(12 rows)

See Also
l

PERCENTILE_CONT [Analytic]

l

Using SQL Analytics

MIN [Analytic]
Returns the minimum value of an expression within a window. The return value is the same as the
expression data type.

HP Vertica Analytic Database (7.0.x)

Page 238 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
MIN
...
...
...

(
[
[
[

[ DISTINCT ] expression ) OVER (
window_partition_clause ]
window_order_clause ]
window_frame_clause ] )

Parameters
DISTINCT

This parameter has no meaning in this context.

expression

Any expression for which the minimum value is calculated, typically a column
reference.

OVER(...)

See Analytic Functions.

Examples
The following query computes the deviation between the employees' annual salary and the
minimum annual salary in Massachusetts:
=> SELECT employee_state, annual_salary,
MIN(annual_salary)
OVER(PARTITION BY employee_state ORDER BY employee_key) min,
annual_salary- MIN(annual_salary)
OVER(PARTITION BY employee_state ORDER BY employee_key) diff
FROM employee_dimension
WHERE employee_state = 'MA';
employee_state | annual_salary | min | diff
----------------+---------------+------+-----MA
|
1918 | 1204 | 714
MA
|
2058 | 1204 | 854
MA
|
2586 | 1204 | 1382
MA
|
2500 | 1204 | 1296
MA
|
1318 | 1204 | 114
MA
|
2072 | 1204 | 868
MA
|
2656 | 1204 | 1452
MA
|
2148 | 1204 | 944
MA
|
2366 | 1204 | 1162
MA
|
2664 | 1204 | 1460
(10 rows)

HP Vertica Analytic Database (7.0.x)

Page 239 of 1539

SQL Reference Manual
SQL Functions

See Also
l

MIN [Aggregate]

l

MAX [Analytic]

l

Using SQL Analytics

NTILE [Analytic]
Equally divides an ordered data set (partition) into a {value} number of subsets within a window,
with buckets (subsets) numbered 1 through constant-value. For example, if constant-value = 4,
then each row in the partition is assigned a number from 1 to 4. If the partition contains 20 rows, the
first 5 would be assigned 1, the next 5 would be assigned 2, and so on.

Behavior Type
Immutable

Syntax
NTILE ( constant-value ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
constant-value

Represents the number of subsets and must resolve to a positive constant for
each partition.

OVER(...)

See Analytic Functions.

Notes
l

The analytic window_order_clause is required but the window_partition_clause is optional.

l

If the number of subsets is greater than the number of rows, then a number of subsets equal to
the number of rows is filled, and the remaining subsets are empty.

l

In the event the cardinality of the partition is not evenly divisible by the number of subsets, the
rows are distributed so no subset has more than 1 row more then any other subset, and the
lowest subsets are the ones that have extra rows. For example, using constant-value = 4 again
and the number of rows = 21, subset = 1 has 6 rows, subset = 2 has 5, and so on.

l

Analytic functions, such as NTILE(), cannot be nested within aggregate functions.

HP Vertica Analytic Database (7.0.x)

Page 240 of 1539

SQL Reference Manual
SQL Functions

Examples
The following query assigns each month's sales total into one of four subsets:
=> SELECT calendar_month_name AS MONTH, SUM(sales_quantity),
NTILE(4) OVER (ORDER BY SUM(sales_quantity)) AS NTILE
FROM store.store_sales_fact JOIN date_dimension
USING(date_key)
GROUP BY calendar_month_name
ORDER BY NTILE;
MONTH
| SUM | NTILE
-----------+------+------February | 755 |
1
June
| 842 |
1
September | 849 |
1
January
| 881 |
2
May
| 882 |
2
July
| 894 |
2
August
| 921 |
3
April
| 952 |
3
March
| 987 |
3
October
| 1010 |
4
November | 1026 |
4
December | 1094 |
4
(12 rows)

See Also
l

PERCENTILE_CONT [Analytic]

l

WIDTH_BUCKET

l

Using SQL Analytics

PERCENT_RANK [Analytic]
Calculates the relative rank of a row for a given row in a group within a window by dividing that
row’s rank less 1 by the number of rows in the partition, also less 1. This function always returns
values from 0 to 1 inclusive. The first row in any set has a PERCENT_RANK() of 0. The return value is
NUMBER.
( rank - 1 ) / ( [ rows ] - 1 )

In the preceding formula, rank is the rank position of a row in the group and rows is the total number
of rows in the partition defined by the OVER() clause.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 241 of 1539

SQL Reference Manual
SQL Functions

Syntax
PERCENT_RANK ( ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
OVER(...)

See Analytic Functions.

Notes
The window_order_clause is required but the window_partition_clause is optional.

Examples
The following example finds the percent rank of gross profit for different states within each month of
the first quarter:
=> SELECT calendar_month_name AS MONTH, store_state,
SUM(gross_profit_dollar_amount),
PERCENT_RANK() OVER (PARTITION BY calendar_month_name
ORDER BY SUM(gross_profit_dollar_amount)) AS PERCENT_RANK
FROM store.store_sales_fact JOIN date_dimension
USING(date_key)
JOIN store.store_dimension
USING (store_key)
WHERE calendar_month_name IN ('January','February','March')
AND store_state IN ('OR','IA','DC','NV','WI')
GROUP BY calendar_month_name, store_state
ORDER BY calendar_month_name, PERCENT_RANK;
MONTH
| store_state | SUM |
PERCENT_RANK
----------+-------------+------+------------------February | OR
|
16 |
0
February | IA
|
47 |
0.25
February | DC
|
94 |
0.5
February | NV
| 113 |
0.75
February | WI
| 119 |
1
January | IA
| -263 |
0
January | OR
|
91 | 0.333333333333333
January | NV
| 372 | 0.666666666666667
January | DC
| 497 |
1
March
| NV
| -141 |
0
March
| OR
| 224 |
1
(11 rows)

The following example calculates, for each employee, the percent rank of the employee's salary by
their job title:
=> SELECT job_title, employee_last_name, annual_salary,

HP Vertica Analytic Database (7.0.x)

Page 242 of 1539

SQL Reference Manual
SQL Functions

PERCENT_RANK()
OVER (PARTITION BY job_title ORDER BY annual_salary DESC) AS percent_rank
FROM employee_dimension
ORDER BY percent_rank, annual_salary;
job_title
| employee_last_name | annual_salary |
PERCENT_RANK
--------------------+--------------------+---------------+--------------------CEO
| Campbell
|
963914 |
0
Co-Founder
| Nguyen
|
968625 |
0
Founder
| Overstreet
|
995533 |
0
Greeter
| Peterson
|
3192 | 0.00113895216400911
Greeter
| Greenwood
|
3192 | 0.00113895216400911
Customer Service
| Peterson
|
3190 | 0.00121065375302663
Delivery Person
| Rodriguez
|
3192 | 0.00121065375302663
Shelf Stocker
| Martin
|
3194 | 0.00125786163522013
Shelf Stocker
| Vu
|
3194 | 0.00125786163522013
Marketing
| Li
|
99711 | 0.00190114068441065
Assistant Director | Sanchez
|
99913 | 0.00190839694656489
Branch Manager
| Perkins
|
99901 | 0.00192307692307692
Advertising
| Lampert
|
99809 | 0.00204918032786885
Sales
| Miller
|
99727 | 0.00211416490486258
Shift Manager
| King
|
99904 | 0.00215982721382289
Custodian
| Bauer
|
3196 | 0.00235849056603774
Custodian
| Goldberg
|
3196 | 0.00235849056603774
Customer Service
| Fortin
|
3184 | 0.00242130750605327
Delivery Person
| Greenwood
|
3186 | 0.00242130750605327
Cashier
| Overstreet
|
3178 | 0.00243605359317905
Regional Manager
| McCabe
|
199688 | 0.00306748466257669
VP of Sales
| Li
|
199309 | 0.00313479623824451
Director of HR
| Goldberg
|
199592 | 0.00316455696202532
Head of Marketing | Stein
|
199941 | 0.00317460317460317
VP of Advertising | Goldberg
|
199036 | 0.00323624595469256
Head of PR
| Stein
|
199767 | 0.00323624595469256
Customer Service
| Rodriguez
|
3180 | 0.0036319612590799
Delivery Person
| King
|
3184 | 0.0036319612590799
Cashier
| Dobisz
|
3174 | 0.00365408038976857
Cashier
| Miller
|
3174 | 0.00365408038976857
Marketing
| Dobisz
|
99655 | 0.00380228136882129
Branch Manager
| Gauthier
|
99082 |
0.025
Branch Manager
| Moore
|
98415 |
0.05
...

See Also
l

CUME_DIST [Analytic]

l

Using SQL Analytics

PERCENTILE_CONT [Analytic]
An inverse distribution function where, for each row, PERCENTILE_CONT() returns the value that
would fall into the specified percentile among a set of values in each partition within a window. For
example, if the argument to the function is 0.5, the result of the function is the median of the data
set (the 50th percentile). PERCENTILE_CONT() assumes a continuous distribution data model. Nulls
are ignored.

HP Vertica Analytic Database (7.0.x)

Page 243 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
PERCENTILE_CONT ( %_number ) WITHIN GROUP (
... ORDER BY expression [ ASC | DESC ] ) OVER (
... [ window_partition_clause ] )

Parameters
%_number

Percentile value, which must be a FLOAT constant ranging
from 0 to 1 (inclusive).

WITHIN GROUP(ORDER BYexpression)

Specifies how the data is sorted within each group. ORDER
BY takes only one column/expression that must be INTEGER,
FLOAT, INTERVAL, or NUMERIC data type. Nulls are discarded.
Note: The WITHIN GROUP(ORDER BY) clause does not
guarantee the order of the SQL result. Use the SQL ORDER
BY clause to guarantee the ordering of the final result set.

ASC | DESC

Specifies the ordering sequence as ascending (default) or
descending.

OVER(...)

See Analytic Functions.

Notes
l

HP Vertica computes the percentile by first computing the row number where the percentile row
would exist; for example:
ROW_NUMBER = 1 + PERCENTILE_VALUE * (NUMBER_OF_ROWS_IN_PARTITION -1)

If the CEILING(ROW_NUMBER) = FLOOR(ROW_NUMBER), then the percentile is the value at the
ROW_NUMBER. Otherwise, there is an even number of rows, and HP Vertica must interpolate the
value between the rows. In this case, the percentile CEILING_VAL = the value at the CEILING
(ROW_NUMBER) and FLOOR_VAL = the value at FLOOR(ROW_NUMBER). The interpolation is
determined by (CEILING(ROW_NUMBER) - ROW_NUMBER) * CEILING_VAL + (ROW_NUMBER FLOOR(ROW_NUMBER) * FLOOR_VAL.
If CEIL(num) = FLOOR(num) = num, retrieve the value in that row. Otherwise compute values
at [ CEIL(num) + FLOOR(num) ] / 2

HP Vertica Analytic Database (7.0.x)

Page 244 of 1539

SQL Reference Manual
SQL Functions

l

Specifying ASC or DESC in the WITHIN GROUP clause affects results as long as the percentile
parameter is not .5.

l

The MEDIAN() function is a specific case of PERCENTILE_CONT()where the percentile value
defaults to 0.5. For more information, see MEDIAN().

Examples
This query computes the median annual income per group for the first 500 customers in Wisconsin
and the District of Columbia.
=> SELECT customer_state, customer_key, annual_income,
PERCENTILE_CONT(.5) WITHIN GROUP(ORDER BY annual_income)
OVER (PARTITION BY customer_state) AS PERCENTILE_CONT
FROM customer_dimension
WHERE customer_state IN ('DC','WI')
AND customer_key < 300
ORDER BY customer_state, customer_key;
customer_state | customer_key | annual_income | PERCENTILE_CONT
----------------+--------------+---------------+----------------DC
|
104 |
658383 |
658383
DC
|
168 |
417092 |
658383
DC
|
245 |
670205 |
658383
WI
|
106 |
227279 |
458607
WI
|
127 |
703889 |
458607
WI
|
209 |
458607 |
458607
(6 rows)

The median value for DC is 65838, and the median value for WI is 458607. With a %_number of 0.5
in the above query, PERCENTILE_CONT() returns the same result as MEDIAN() in the following
query:
=> SELECT customer_state, customer_key, annual_income,
MEDIAN(annual_income)
OVER (PARTITION BY customer_state) AS MEDIAN
FROM customer_dimension
WHERE customer_state IN ('DC','WI')
AND customer_key < 300
ORDER BY customer_state, customer_key;
customer_state | customer_key | annual_income | MEDIAN
----------------+--------------+---------------+-------DC
|
104 |
658383 | 658383
DC
|
168 |
417092 | 658383
DC
|
245 |
670205 | 658383
WI
|
106 |
227279 | 458607
WI
|
127 |
703889 | 458607
WI
|
209 |
458607 | 458607
(6 rows)

HP Vertica Analytic Database (7.0.x)

Page 245 of 1539

SQL Reference Manual
SQL Functions

See Also
l

MEDIAN [Analytic]

l

Using SQL Analytics

PERCENTILE_DISC [Analytic]
An inverse distribution function where, for each row, PERCENTILE_DISC() returns the value that
would fall into the specified percentile among a set of values in each partition within a window.
PERCENTILE_DISC() assumes a discrete distribution data model. Nulls are ignored.

Behavior Type
Immutable

Syntax
PERCENTILE_DISC ( %_number ) WITHIN GROUP (
... ORDER BY expression [ ASC | DESC ] ) OVER (
... [ window_partition_clause ] )

Parameters
%_number

Percentile value, which must be a FLOAT constant ranging
from 0 to 1 (inclusive).

WITHIN GROUP(ORDER BYexpression)

Specifies how the data is sorted within each group. ORDER
BY takes only one column/expression that must be INTEGER,
FLOAT, INTERVAL, or NUMERIC data type. Nulls are
discarded.
Note: The WITHIN GROUP(ORDER BY) clause does not
guarantee the order of the SQL result. Use the SQL
ORDER BY clause to guarantee the ordering of the final
result set.

ASC | DESC

Specifies the ordering sequence as ascending (default) or
descending.

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 246 of 1539

SQL Reference Manual
SQL Functions

Notes
l

PERCENTILE_DISC(%_number) examines the cumulative distribution values in each group until it
finds one that is greater than or equal to %_number.

l

HP Vertica computes the percentile where, for each row, PERCENTILE_DISC outputs the first
value of the WITHIN GROUP(ORDER BY) column whose CUME_DIST (cumulative distribution)
value is >= the argument FLOAT value (for example, 0.4). Specifically:
PERCENTILE_DIST(.4) WITHIN GROUP (ORDER BY salary) OVER(PARTITION By deptno) ...

If you write, for example:
SELECT CUME_DIST() OVER(ORDER BY salary) FROM table;

The smallest CUME_DIST value that is greater than 0.4 is also the PERCENTILE_DISC.

Example
This query computes the 20th percentile annual income by group for first 500 customers in
Wisconsin and the District of Columbia.
=> SELECT customer_state, customer_key, annual_income,
PERCENTILE_DISC(.2) WITHIN GROUP(ORDER BY annual_income)
OVER (PARTITION BY customer_state) AS PERCENTILE_DISC
FROM customer_dimension
WHERE customer_state IN ('DC','WI')
AND customer_key < 300
ORDER BY customer_state, customer_key;
customer_state | customer_key | annual_income | PERCENTILE_DISC
----------------+--------------+---------------+----------------DC
|
104 |
658383 |
417092
DC
|
168 |
417092 |
417092
DC
|
245 |
670205 |
417092
WI
|
106 |
227279 |
227279
WI
|
127 |
703889 |
227279
WI
|
209 |
458607 |
227279
(6 rows)

See Also
l

CUME_DIST [Analytic]

l

PERCENTILE_CONT [Analytic]

l

Using SQL Analytics

HP Vertica Analytic Database (7.0.x)

Page 247 of 1539

SQL Reference Manual
SQL Functions

RANK [Analytic]
Assigns a rank to each row returned from a query with respect to the other ordered rows, based on
the values of the expressions in the window ORDER BY clause. The data within a group is sorted by
the ORDER BY clause and then a numeric ranking is assigned to each row in turn, starting with 1, and
continuing up. Rows with the same values of the ORDER BY expressions receive the same rank;
however, if two rows receive the same rank (a tie), RANK() skips the ties. If, for example, two rows
are numbered 1, RANK() skips number 2 and assigns 3 to the next row in the group. This is in
contrast to DENSE_RANK(), which does not skip values.

Behavior Type
Immutable

Syntax
RANK ( ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
OVER(...)

See Analytic Functions.

Notes
l

Ranking functions return a rank value for each row in a result set based on the order specified in
the query. For example, a territory sales manager might want to identify the top or bottom
ranking sales associates in a department or the highest/lowest-performing sales offices by
region.

l

RANK() requires an OVER() clause. The window_partition_clause is optional.

l

In ranking functions, OVER() specifies the measures expression on which ranking is done and
defines the order in which rows are sorted in each group (or partition). Once the data is sorted
within each partition, ranks are given to each row starting from 1.

l

The primary difference between RANK and DENSE_RANK is that RANK leaves gaps when ranking
records; DENSE_RANK leaves no gaps. For example, if more than one record occupies a particular
position (a tie), RANK places all those records in that position and it places the next record after a
gap of the additional records (it skips one). DENSE_RANK places all the records in that position
only—it does not leave a gap for the next rank.
If there is a tie at the third position with two records having the same value, RANK and DENSE_
RANK place both the records in the third position only, but RANK has the next record at the fifth

HP Vertica Analytic Database (7.0.x)

Page 248 of 1539

SQL Reference Manual
SQL Functions

position—leaving a gap of 1 position—while DENSE_RANK places the next record at the forth
position (no gap).
l

If you omit NULLS FIRST | LAST | AUTO, the ordering of the null values depends on the ASC or
DESC arguments. Null values are considered larger than any other values. If the ordering
sequence is ASC, then nulls appear last; nulls appear first otherwise. Nulls are considered equal
to other nulls and, therefore, the order in which nulls are presented is non-deterministic.

Examples
This example ranks the longest standing customers in Massachusetts. The query first computes
the customer_since column by region, and then partitions the results by customers with
businesses in MA. Then within each region, the query ranks customers over the age of 70.
=> SELECT customer_type, customer_name,
RANK() OVER (PARTITION BY customer_region
ORDER BY customer_since) as rank
FROM customer_dimension
WHERE customer_state = 'MA'
AND customer_age > '70';

customer_type | customer_name | rank
---------------+---------------+-----Company
| Virtadata
|
1
Company
| Evergen
|
2
Company
| Infocore
|
3
Company
| Goldtech
|
4
Company
| Veritech
|
5
Company
| Inishop
|
6
Company
| Intracom
|
7
Company
| Virtacom
|
8
Company
| Goldcom
|
9
Company
| Infostar
|
10
Company
| Golddata
|
11
Company
| Everdata
|
12
Company
| Goldcorp
|
13
(13 rows)

The following example shows the difference between RANK and DENSE_RANK when ranking
customers by their annual income. RANK has a tie at 10 and skips 11, while DENSE_RANK leaves no
gaps in the ranking sequence:
=> SELECT customer_name, SUM(annual_income),
RANK () OVER (ORDER BY TO_CHAR(SUM(annual_income),'100000') DESC) rank,
DENSE_RANK () OVER (ORDER BY TO_CHAR(SUM(annual_income),'100000') DESC) dense_rank
FROM customer_dimension
GROUP BY customer_name
LIMIT 15;
customer_name
| sum | rank | dense_rank
---------------------+-------+------+-----------Brian M. Garnett
| 99838 |
1 |
1

HP Vertica Analytic Database (7.0.x)

Page 249 of 1539

SQL Reference Manual
SQL Functions

Tanya A. Brown
Tiffany P. Farmer
Jose V. Sanchez
Marcus D. Rodriguez
Alexander T. Nguyen
Sarah G. Lewis
Ruth Q. Vu
Theodore T. Farmer
Daniel P. Li
Seth E. Brown
Matt X. Gauthier
Rebecca W. Lewis
Dean L. Wilson
Tiffany A. Smith
(15 rows)

|
|
|
|
|
|
|
|
|
|
|
|
|
|

99834
99826
99673
99631
99604
99556
99542
99532
99497
99497
99402
99296
99276
99257

|
|
|
|
|
|
|
|
|
|
|
|
|
|

2
3
4
5
6
7
8
9
10
10
12
13
14
15

|
|
|
|
|
|
|
|
|
|
|
|
|
|

2
3
4
5
6
7
8
9
10
10
11
12
13
14

See Also
l

DENSE_RANK [Analytic]

l

Using SQL Analytics

ROW_NUMBER [Analytic]
Assigns a unique number, sequentially, starting from 1, to each row in a partition within a window.

Behavior Type
Immutable

Syntax
ROW_NUMBER ( ) OVER (
... [ window_partition_clause ]
... window_order_clause )

Parameters
OVER(...)

See Analytic Functions.

Notes
l

ROW_NUMBER() is an HP Vertica extension, not part of the SQL-99 standard. It requires an OVER
() clause. The window_partition_clause is optional.

l

You can use the optional partition clause to group data into partitions before operating on it; for

HP Vertica Analytic Database (7.0.x)

Page 250 of 1539

SQL Reference Manual
SQL Functions

example:
SUM OVER (PARTITION BY col1, col2, ...)

l

You can substitute any RANK() example for ROW_NUMBER(). The difference is that ROW_
NUMBERassigns a unique ordinal number, starting with 1, to each row in the ordered set.

Examples
The following query first partitions customers in the customer_dimension table by occupation and
then ranks those customers based on the ordered set specified by the analytic partition_clause.
=> SELECT occupation, customer_key, customer_since, annual_income,
ROW_NUMBER() OVER (PARTITION BY occupation) AS customer_since_row_num
FROM public.customer_dimension
ORDER BY occupation, customer_since_row_num;
occupation
| customer_key | customer_since | annual_income | customer_since_row_
num
--------------------+--------------+----------------+---------------+----------------------Accountant
|
19453 | 1973-11-06
|
602460 |
1
Accountant
|
42989 | 1967-07-09
|
850814 |
2
Accountant
|
24587 | 1995-05-18
|
180295 |
3
Accountant
|
26421 | 2001-10-08
|
126490 |
4
Accountant
|
37783 | 1993-03-16
|
790282 |
5
Accountant
|
39170 | 1980-12-21
|
823917 |
6
Banker
|
13882 | 1998-04-10
|
15134 |
1
Banker
|
14054 | 1989-03-16
|
961850 |
2
Banker
|
15850 | 1996-01-19
|
262267 |
3
Banker
|
29611 | 2004-07-14
|
739016 |
4
Doctor
|
261 | 1969-05-11
|
933692 |
1
Doctor
|
1264 | 1981-07-19
|
593656 |
2
Psychologist
|
5189 | 1999-05-04
|
397431 |
1
Psychologist
|
5729 | 1965-03-26
|
339319 |
2
Software Developer |
2513 | 1996-09-22
|
920003 |
1
Software Developer |
5927 | 2001-03-12
|
633294 |
2

HP Vertica Analytic Database (7.0.x)

Page 251 of 1539

SQL Reference Manual
SQL Functions

Software Developer
3
Software Developer
4
Software Developer
5
Software Developer
6
Software Developer
7
Software Developer
8
Software Developer
9
Software Developer
10
Software Developer
11
Stock Broker
1
Stock Broker
2
Stock Broker
3
Stock Broker
4
Stock Broker
5
Writer
1
Writer
2
Writer
3
Writer
4
Writer
5
Writer
6
(39 rows)

|

9125 | 1971-10-06

|

198953 |

|

16097 | 1968-09-02

|

748371 |

|

23137 | 1988-12-07

|

92578 |

|

24495 | 1989-04-16

|

149371 |

|

24548 | 1994-09-21

|

743788 |

|

33744 | 2005-12-07

|

735003 |

|

9684 | 1970-05-20

|

246000 |

|

24278 | 2001-11-14

|

122882 |

|

27122 | 1994-02-05

|

810044 |

|

5950 | 1965-01-20

|

752120 |

|

12517 | 2003-06-13

|

380102 |

|

33010 | 1984-05-07

|

384463 |

|

46196 | 1972-11-28

|

497049 |

|

8710 | 2005-02-11

|

79387 |

|

3149 | 1998-11-17

|

643972 |

|

17124 | 1965-01-18

|

444747 |

|

20100 | 1994-08-13

|

106097 |

|

23317 | 2003-05-27

|

511750 |

|

42845 | 1967-10-23

|

433483 |

|

47560 | 1997-04-23

|

515647 |

See Also
RANK [Analytic]

l
l

STDDEV [Analytic]
Note: The non-standard function STDDEV() is provided for compatibility with other databases.
It is semantically identical to STDDEV_SAMP().

HP Vertica Analytic Database (7.0.x)

Page 252 of 1539

SQL Reference Manual
SQL Functions

Computes the statistical sample standard deviation of the current row with respect to the group
within a window. The STDDEV_SAMP() return value is the same as the square root of the variance
defined for the VAR_SAMP() function:
STDDEV(expression) = SQRT(VAR_SAMP(expression))

When VAR_SAMP() returns null, this function returns null.

Behavior Type
Immutable

Syntax
STDDEV ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

OVER(...)

See Analytic Functions.

Example
The following example returns the standard deviations of salaries in the employee dimension table
by job title Assistant Director:
=> SELECT employee_last_name, annual_salary,
STDDEV(annual_salary) OVER (ORDER BY hire_date) as "stddev"
FROM employee_dimension
WHERE job_title = 'Assistant Director';
employee_last_name | annual_salary |
stddev
--------------------+---------------+-----------------Goldberg
|
61859 |
NaN
Miller
|
79582 | 12532.0534829692
Goldberg
|
74236 | 9090.97147357388
Campbell
|
66426 | 7909.9541665339
Moore
|
66630 | 7068.30282316761
Nguyen
|
53530 | 9154.14713486005
Harris
|
74115 | 8773.54346886142
Lang
|
59981 | 8609.60471031374
Farmer
|
60597 | 8335.41158418579
Nguyen
|
78941 | 8812.87941405456
Smith
|
55018 | 9179.7672390773

HP Vertica Analytic Database (7.0.x)

Page 253 of 1539

SQL Reference Manual
SQL Functions

...

See Also
l

STDDEV [Aggregate]

l

STDDEV_SAMP [Aggregate]
STDDEV_SAMP [Analytic]

l
l

STDDEV_POP [Analytic]
Computes the statistical population standard deviation and returns the square root of the population
variance within a window. The STDDEV_POP() return value is the same as the square root of the
VAR_POP() function:
STDDEV_POP(expression) = SQRT(VAR_POP(expression))

When VAR_POP returns null, STDDEV_POP returns null.

Behavior Type
Immutable

Syntax
STDDEV_POP ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

OVER(...)

See Analytic Functions.

Examples
The following example returns the population standard deviations of salaries in the employee
dimension table by job title Assistant Director:

HP Vertica Analytic Database (7.0.x)

Page 254 of 1539

SQL Reference Manual
SQL Functions

=> SELECT employee_last_name, annual_salary,
STDDEV_POP(annual_salary) OVER (ORDER BY hire_date) as "stddev_pop"
FROM employee_dimension WHERE job_title = 'Assistant Director';
employee_last_name | annual_salary |
stddev_pop
--------------------+---------------+-----------------Goldberg
|
61859 |
0
Miller
|
79582 |
8861.5
Goldberg
|
74236 | 7422.74712548456
Campbell
|
66426 | 6850.22125098891
Moore
|
66630 | 6322.08223926257
Nguyen
|
53530 | 8356.55480080699
Harris
|
74115 | 8122.72288970008
Lang
|
59981 | 8053.54776538731
Farmer
|
60597 | 7858.70140687825
Nguyen
|
78941 | 8360.63150784682

See Also
STDDEV_POP [Aggregate]

l
l

STDDEV_SAMP [Analytic]
Computes the statistical sample standard deviation of the current row with respect to the group
within a window. The STDDEV_SAMP() return value is the same as the square root of the variance
defined for the VAR_SAMP() function:
STDDEV(expression) = SQRT(VAR_SAMP(expression))

When VAR_SAMP() returns null, STDDEV_SAMP returns null.

Behavior Type
Immutable

Syntax
STDDEV_SAMP ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument..

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 255 of 1539

SQL Reference Manual
SQL Functions

Notes
STDDEV_SAMP() is semantically identical to the non-standard function, STDDEV().

Examples
The following example returns the sample standard deviations of salaries in the employee
dimension table by job title Assistant Director:
=> SELECT employee_last_name, annual_salary,
STDDEV(annual_salary) OVER (ORDER BY hire_date) as "stddev_samp"
FROM employee_dimension WHERE job_title = 'Assistant Director';
employee_last_name | annual_salary |
stddev_samp
--------------------+---------------+-----------------Goldberg
|
61859 |
NaN
Miller
|
79582 | 12532.0534829692
Goldberg
|
74236 | 9090.97147357388
Campbell
|
66426 | 7909.9541665339
Moore
|
66630 | 7068.30282316761
Nguyen
|
53530 | 9154.14713486005
Harris
|
74115 | 8773.54346886142
Lang
|
59981 | 8609.60471031374
Farmer
|
60597 | 8335.41158418579
Nguyen
|
78941 | 8812.87941405456
...

See Also
l

Analytic Functions

l

STDDEV [Analytic]

l

STDDEV [Aggregate]
STDDEV_SAMP [Aggregate]

l
l

SUM [Analytic]
Computes the sum of an expression over a group of rows within a window. It returns a DOUBLE
PRECISION value for a floating-point expression. Otherwise, the return value is the same as the
expression data type.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 256 of 1539

SQL Reference Manual
SQL Functions

Syntax
SUM
...
...
...

(
[
[
[

expression ) OVER (
window_partition_clause ]
window_order_clause ]
window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

OVER(...)

See Analytic Functions.

Notes
l

If you encounter data overflow when using SUM(), use SUM_FLOAT() which converts data to a
floating point.

l

SUM() returns the sum of values of an expression.

Examples
The following query returns the cumulative sum all of the returns made to stores in January:
=> SELECT calendar_month_name AS month, transaction_type, sales_quantity,
SUM(sales_quantity)
OVER (PARTITION BY calendar_month_name ORDER BY date_dimension.date_key) AS SUM
FROM store.store_sales_fact JOIN date_dimension
USING(date_key) WHERE calendar_month_name IN ('January')
AND transaction_type= 'return';
month | transaction_type | sales_quantity | SUM
---------+------------------+----------------+-----January | return
|
4 | 2338
January | return
|
3 | 2338
January | return
|
1 | 2338
January | return
|
5 | 2338
January | return
|
8 | 2338
January | return
|
3 | 2338
January | return
|
5 | 2338
January | return
|
10 | 2338
January | return
|
9 | 2338
January | return
|
10 | 2338
(10 rows)

HP Vertica Analytic Database (7.0.x)

Page 257 of 1539

SQL Reference Manual
SQL Functions

See Also
SUM [Aggregate]

l

Numeric Data Types

l
l

VAR_POP [Analytic]
Returns the statistical population variance of a non-null set of numbers (nulls are ignored) in a group
within a window. Results are calculated by the sum of squares of the difference of expression from
the mean of expression, divided by the number of rows remaining:
(SUM(expression*expression) - SUM(expression)*SUM(expression) /
UNT(expression)

COUNT(expression)) / CO

Behavior Type
Immutable

Syntax
VAR_POP ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument

OVER(...)

See Analytic Functions.

Examples
The following example calculates the cumulative population in the store orders fact table of sales in
December 2007:
=> SELECT date_ordered,
VAR_POP(SUM(total_order_cost))
OVER (ORDER BY date_ordered) "var_pop"
FROM store.store_orders_fact s

HP Vertica Analytic Database (7.0.x)

Page 258 of 1539

SQL Reference Manual
SQL Functions

WHERE date_ordered BETWEEN '2007-12-01' AND '2007-12-31'
GROUP BY s.date_ordered;
date_ordered |
var_pop
--------------+-----------------2007-12-01
|
0
2007-12-02
|
1129564881
2007-12-03
| 1206008121.55542
2007-12-04
| 26353624176.1875
2007-12-05
| 21315288023.4402
2007-12-06
| 21619271028.3333
2007-12-07
| 19867030477.6328
2007-12-08
|
19197735288.5
2007-12-09
| 19100157155.2097
2007-12-10
| 19369222968.0896
(10 rows)

See Also
VAR_POP [Aggregate]

l
l

VAR_SAMP [Analytic]
Returns the sample variance of a non-null set of numbers (nulls in the set are ignored) for each row
of the group within a window. Results are calculated by the sum of squares of the difference of
expression from the mean of expression, divided by the number of rows remaining minus 1:
(SUM(expression*expression) - SUM(expression)*SUM(expression) /
COUNT(expression)) / (COUNT(expression) - 1)

Behavior Type
Immutable

Syntax
VAR_SAMP ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument

OVER(...)

See Analytic Functions.

HP Vertica Analytic Database (7.0.x)

Page 259 of 1539

SQL Reference Manual
SQL Functions

Notes
l

VAR_SAMP() returns the sample variance of a set of numbers after it discards the nulls in the set.

l

If the function is applied to an empty set, then it returns null.

l

This function is similar to VARIANCE(), except that given an input set of one element, VARIANCE
() returns 0 and VAR_SAMP() returns null.

Examples
The following example calculates the sample variance in the store orders fact table of sales in
December 2007:
=> SELECT date_ordered,
VAR_SAMP(SUM(total_order_cost))
OVER (ORDER BY date_ordered) "var_samp"
FROM store.store_orders_fact s
WHERE date_ordered BETWEEN '2007-12-01' AND '2007-12-31'
GROUP BY s.date_ordered;
date_ordered |
var_samp
--------------+-----------------2007-12-01
|
NaN
2007-12-02
|
2259129762
2007-12-03
| 1809012182.33301
2007-12-04
|
35138165568.25
2007-12-05
| 26644110029.3003
2007-12-06
|
25943125234
2007-12-07
| 23178202223.9048
2007-12-08
| 21940268901.1431
2007-12-09
| 21487676799.6108
2007-12-10
| 21521358853.4331
(10 rows)

See Also
VARIANCE [Analytic]

l

VAR_SAMP [Aggregate]

l
l

VARIANCE [Analytic]
Note: The non-standard function VARIANCE() is provided for compatibility with other
databases. It is semantically identical to VAR_SAMP().

HP Vertica Analytic Database (7.0.x)

Page 260 of 1539

SQL Reference Manual
SQL Functions

Returns the sample variance of a non-null set of numbers (nulls in the set are ignored) for each row
of the group within a window. Results are calculated by the sum of squares of the difference of
expression from the mean of expression, divided by the number of rows remaining minus 1:
(SUM(expression*expression) - SUM(expression)*SUM(expression) /
OUNT(expression) - 1)

COUNT(expression)) / (C

Behavior Type
Immutable

Syntax
VAR_SAMP ( expression ) OVER (
... [ window_partition_clause ]
... [ window_order_clause ]
... [ window_frame_clause ] )

Parameters
expression

Any NUMERIC data type or any non-numeric data type that can be implicitly
converted to a numeric data type. The function returns the same data type as the
numeric data type of the argument.

OVER(...)

See Analytic Functions.

Notes
l

VARIANCE() returns the variance of expression.

l

The variance of expression is calculated as follows:
n

0 if the number of rows in expression = 1

n

VAR_SAMP() if the number of rows in expression > 1

Examples
The following example calculates the cumulative variance in the store orders fact table of sales in
December 2007:
=> SELECT date_ordered,
VARIANCE(SUM(total_order_cost))
OVER (ORDER BY date_ordered) "variance"
FROM store.store_orders_fact s
WHERE date_ordered BETWEEN '2007-12-01' AND '2007-12-31'
GROUP BY s.date_ordered;

HP Vertica Analytic Database (7.0.x)

Page 261 of 1539

SQL Reference Manual
SQL Functions

date_ordered |
variance
--------------+-----------------2007-12-01
|
NaN
2007-12-02
|
2259129762
2007-12-03
| 1809012182.33301
2007-12-04
|
35138165568.25
2007-12-05
| 26644110029.3003
2007-12-06
|
25943125234
2007-12-07
| 23178202223.9048
2007-12-08
| 21940268901.1431
2007-12-09
| 21487676799.6108
2007-12-10
| 21521358853.4331
(10 rows)

See Also
l

VAR_SAMP [Analytic]

l

VARIANCE [Aggregate]
VAR_SAMP [Aggregate]

l
l

HP Vertica Analytic Database (7.0.x)

Page 262 of 1539

SQL Reference Manual
SQL Functions

Date/Time Functions
Date and time functions perform conversion, extraction, or manipulation operations on date and
time data types and can return date and time information.

Usage
Functions that take TIME or TIMESTAMP inputs come in two variants:
l

TIME WITH TIME ZONE or TIMESTAMP WITH TIME ZONE

l

TIME WITHOUT TIME ZONE or TIMESTAMP WITHOUT TIME ZONE

For brevity, these variants are not shown separately.
The + and * operators come in commutative pairs; for example, both DATE + INTEGER and INTEGER
+ DATE. We show only one of each such pair.

Daylight Savings Time Considerations
When adding an INTERVAL value to (or subtracting an INTERVAL value from) a TIMESTAMP WITH
TIME ZONE value, the days component advances (or decrements) the date of the TIMESTAMP WITH
TIME ZONE by the indicated number of days. Across daylight saving time changes (with the session
time zone set to a time zone that recognizes DST), this means INTERVAL '1 day' does not
necessarily equal INTERVAL '24 hours'.
For example, with the session time zone set to CST7CDT:
TIMESTAMP WITH TIME ZONE '2005-04-02 12:00-07' + INTERVAL '1 day'

produces
TIMESTAMP WITH TIME ZONE '2005-04-03 12:00-06'

Adding INTERVAL '24 hours' to the same initial TIMESTAMP WITH TIME ZONE produces
TIMESTAMP WITH TIME ZONE '2005-04-03 13:00-06',

This result occurs because there is a change in daylight saving time at 2005-04-03 02:00 in time
zone CST7CDT.

Date/Time Functions in Transactions
CURRENT_TIMESTAMP() and related functions return the start time of the current transaction; their
values do not change during the transaction. 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

HP Vertica Analytic Database (7.0.x)

Page 263 of 1539

SQL Reference Manual
SQL Functions

bear the same timestamp. However, TIMEOFDAY() returns the wall-clock time and advances during
transactions.

See Also
Template Patterns for Date/Time Formatting

l

ADD_MONTHS
Takes a DATE, TIMESTAMP, or TIMESTAMPTZ argument and a number of months and returns a
date. TIMESTAMPTZ arguments are implicitly cast to TIMESTAMP.

Behavior Type
Immutable if called with DATE or TIMESTAMP but stable with TIMESTAMPTZ in that its results
can change based on TIMEZONE settings

Syntax
ADD_MONTHS ( d , n );

Parameters
d

The incoming DATE, TIMESTAMP, or TIMESTAMPTZ. If the start date falls on the last day
of the month, or if the resulting month has fewer days than the given day of the month, then
the result is the last day of the resulting month. Otherwise, the result has the same start day.

n

Any INTEGER.

Examples
The following example's results include a leap year:
SELECT ADD_MONTHS('31-Jan-08', 1) "Months";
Months
-----------2008-02-29
(1 row)

The next example adds four months to January and returns a date in May:
SELECT ADD_MONTHS('31-Jan-08', 4) "Months";
Months
-----------2008-05-31
(1 row)

This example subtracts four months from January, returning a date in September:

HP Vertica Analytic Database (7.0.x)

Page 264 of 1539

SQL Reference Manual
SQL Functions

SELECT ADD_MONTHS('31-Jan-08', -4) "Months";
Months
-----------2007-09-30
(1 row)

Because the following example specifies NULL, the result set is empty:
SELECT ADD_MONTHS('31-Jan-03', NULL) "Months";
Months
-------(1 row)

This example provides no date argument, so even though the number of months specified is 1, the
result set is empty:
SELECT ADD_MONTHS(NULL, 1) "Months";
Months
-------(1 row)

In this example, the date field defaults to a timestamp, so the PST is ignored. Even though it is
already the next day in Pacific time, the result falls on the same date in New York (two years later):
SET TIME ZONE 'America/New_York';
SELECT ADD_MONTHS('2008-02-29 23:30 PST', 24);
add_months
-----------2010-02-28
(1 row)

The next example specifies a timestamp with time zone, so the PST is taken into account:
SET TIME ZONE 'America/New_York';
SELECT ADD_MONTHS('2008-02-29 23:30 PST'::TIMESTAMPTZ, 24);
add_months
-----------2010-03-01
(1 row)

AGE_IN_MONTHS
Returns an INTEGER value representing the difference in months between two TIMESTAMP,
DATE or TIMESTAMPTZ values.

HP Vertica Analytic Database (7.0.x)

Page 265 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Stable if second argument is omitted or if either argument is TIMESTAMPTZ. Immutable
otherwise.

Syntax
AGE_IN_MONTHS ( expression1 [ , expression2 ] )

Parameters
expression1

Specifies the beginning of the period.

expression2

Specifies the end of the period. The default is the CURRENT_DATE.

Notes
The inputs can be TIMESTAMP, TIMESTAMPTZ, or DATE.

Examples
The following example returns the age in months of a person born on March 2, 1972 on the date
June 21, 1990, with a time elapse of 18 years, 3 months, and 19 days:
SELECT AGE_IN_MONTHS(TIMESTAMP '1990-06-21', TIMESTAMP '1972-03-02');
AGE_IN_MONTHS
--------------219
(1 row)

The next example shows the age in months of the same person (born March 2, 1972) as of March
16, 2010:
SELECT AGE_IN_MONTHS(TIMESTAMP 'March 16, 2010', TIMESTAMP '1972-03-02');
AGE_IN_MONTHS
--------------456
(1 row)

This example returns the age in months of a person born on November 21, 1939:
SELECT AGE_IN_MONTHS(TIMESTAMP '1939-11-21');
AGE_IN_MONTHS
--------------844
(1 row)

In the above form, the result changes as time goes by.

HP Vertica Analytic Database (7.0.x)

Page 266 of 1539

SQL Reference Manual
SQL Functions

See Also
l

AGE_IN_YEARS

l

INTERVAL

AGE_IN_YEARS
Returns an INTEGER value representing the difference in years between two TIMESTAMP, DATE
or TIMESTAMPTZ values.

Behavior Type
Stable if second argument is omitted or if either argument is TIMESTAMPTZ. Immutable
otherwise.

Syntax
AGE_IN_YEARS ( expression1 [ , expression2 ] )

Parameters
expression1

Specifies the beginning of the period.

expression2

Specifies the end of the period. The default is the CURRENT_DATE.

Notes
l

The AGE_IN_YEARS() function was previously called AGE. AGE() is not supported.

l

Inputs can be TIMESTAMP, TIMESTAMPTZ, or DATE.

Examples
The following example returns the age in years of a person born on March 2, 1972 on the date June
21, 1990, with a time elapse of 18 years, 3 months, and 19 days:
SELECT AGE_IN_YEARS(TIMESTAMP '1990-06-21', TIMESTAMP '1972-03-02');
AGE_IN_YEARS
-------------18
(1 row)

The next example shows the age in years of the same person (born March 2, 1972) as of February
24, 2009:

HP Vertica Analytic Database (7.0.x)

Page 267 of 1539

SQL Reference Manual
SQL Functions

SELECT AGE_IN_YEARS(TIMESTAMP '2009-02-24', TIMESTAMP '1972-03-02');
AGE_IN_YEARS
-------------36
(1 row)

This example returns the age in years of a person born on November 21, 1939:
SELECT AGE_IN_YEARS(TIMESTAMP '1939-11-21');
AGE_IN_YEARS
-------------70
(1 row)

See Also
l

AGE_IN_MONTHS

l

INTERVAL

CLOCK_TIMESTAMP
Returns a value of type TIMESTAMP WITH TIMEZONE representing the current system-clock
time.

Behavior Type
Volatile

Syntax
CLOCK_TIMESTAMP()

Notes
This function uses the date and time supplied by the operating system on the server to which you
are connected, which should be the same across all servers. The value changes each time you call
it.

Examples
The following command returns the current time on your system:
SELECT CLOCK_TIMESTAMP() "Current Time";
Current Time
------------------------------

HP Vertica Analytic Database (7.0.x)

Page 268 of 1539

SQL Reference Manual
SQL Functions

2010-09-23 11:41:23.33772-04
(1 row)

Each time you call the function, you get a different result. The difference in this example is in
microseconds:
SELECT CLOCK_TIMESTAMP() "Time 1", CLOCK_TIMESTAMP() "Time 2";
Time 1
|
Time 2
-------------------------------+------------------------------2010-09-23 11:41:55.369201-04 | 2010-09-23 11:41:55.369202-04
(1 row)

See Also
l

STATEMENT_TIMESTAMP

l

TRANSACTION_TIMESTAMP

CURRENT_DATE
Returns the date (date-type value) on which the current transaction started.

Behavior Type
Stable

Syntax
CURRENT_DATE

Notes
The CURRENT_DATE function does not require parentheses.

Examples
SELECT CURRENT_DATE;
?column?
-----------2010-09-23
(1 row)

CURRENT_TIME
Returns a value of type TIME WITH TIMEZONE representing the time of day.

HP Vertica Analytic Database (7.0.x)

Page 269 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Stable

Syntax
CURRENT_TIME [ ( precision ) ]

Parameters
precision

(INTEGER) causes the result to be rounded to the specified number of fractional
digits in the seconds field.

Notes
l

This function returns the start time of the current transaction; the value does not change during
the transaction. 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
timestamp.

l

The CURRENT_TIME function does not require parentheses.

Examples
SELECT CURRENT_TIME "Current Time";
Current Time
-------------------12:45:12.186089-05
(1 row)

CURRENT_TIMESTAMP
Returns a value of type TIMESTAMP WITH TIME ZONE representing the start of the current
transaction.

Behavior Type
Stable

Syntax
CURRENT_TIMESTAMP [ ( precision ) ]

HP Vertica Analytic Database (7.0.x)

Page 270 of 1539

SQL Reference Manual
SQL Functions

Parameters
precision

(INTEGER) causes the result to be rounded to the specified number of fractional
digits in the seconds field. Range of INTEGER is 0-6.

Notes
This function returns the start time of the current transaction; the value does not change during the
transaction. 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 timestamp.

Examples
SELECT CURRENT_TIMESTAMP;
?column?
------------------------------2010-09-23 11:37:22.354823-04
(1 row)
SELECT CURRENT_TIMESTAMP(2);
?column?
--------------------------2010-09-23 11:37:22.35-04
(1 row)

DATE_PART
Is modeled on the traditional Ingres equivalent to the SQL-standard function EXTRACT. Internally
DATE_PART is used by the EXTRACT function.

Behavior Type
Stable when source is of type TIMESTAMPTZ, Immutable otherwise.

Syntax
DATE_PART ( field , source )

HP Vertica Analytic Database (7.0.x)

Page 271 of 1539

SQL Reference Manual
SQL Functions

CENTURY

The century number.
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. This definition applies to all
Gregorian calendar countries. There is no century number 0, you go from –1 to
1.
DAY

The day (of the month) field (1–31).
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT EXTRACT(DAY FROM DATE '2001-02-16');
Result: 16

DECADE

The year field divided by 10.
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200
SELECT EXTRACT(DECADE FROM DATE '2001-02-16');
Result: 200

DOQ

The day within the current quarter.
SELECT EXTRACT(DOQ FROM CURRENT_DATE);
Result: 89

The result is calculated as follows: Current date = June 28, current quarter = 2
(April, May, June). 30 (April) + 31 (May) + 28 (June current day) = 89.
DOQ recognizes leap year days.
DOW

The day of the week (0–6; Sunday is 0).
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5
SELECT EXTRACT(DOW FROM DATE '2001-02-16');
Result: 5

EXTRACT's day of the week numbering is different from that of the TO_CHAR
function.
DOY

The day of the year (1–365/366)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47
SELECT EXTRACT(DOY FROM DATE '2001-02-16');
Result: 5

HP Vertica Analytic Database (7.0.x)

Page 272 of 1539

SQL Reference Manual
SQL Functions

EPOCH

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-0
8');
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 timestamp:
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
HOUR

The hour field (0–23).
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20
SELECT EXTRACT(HOUR FROM TIME '13:45:59');
Result: 13

ISODOW

The ISO day of the week (1–7; Monday is 1).
By definition, the ISO-8601 week starts on Monday, and the first week of a year
contains January 4 of that year. In other words, the first Thursday of a year is in
week 1 of that year.
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(ISODOW FROM DATE '2010-09-27');
Result: 1

ISOWEEK

The ISO week, which consists of 7 days starting on Monday and ending on
Sunday. The first week of the year is the week that contains January 4.

ISOYEAR

The ISO year, which is 52 or 53 weeks (Monday–Sunday).
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
Result: 2005
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
Result: 2006
SELECT EXTRACT(ISOYEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

MICROSECONDS

The seconds field, including fractional parts, multiplied by 1,000,000. This
includes full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
Result: 28500000

MILLENNIUM

The millennium number.
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.

HP Vertica Analytic Database (7.0.x)

Page 273 of 1539

SQL Reference Manual
SQL Functions

MILLISECONDS

The seconds field, including fractional parts, multiplied by 1000. This includes
full seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
Result: 28500

MINUTE

The minutes field (0 - 59).
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38
SELECT EXTRACT(MINUTE FROM TIME '13:45:59');
Result: 45

MONTH

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

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

The seconds field, including fractional parts (0–59) (60 if leap seconds are
implemented by the operating system).
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

TIME ZONE

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

The minute component of the time zone offset.

WEEK

The number of the week of the calendar year that the day is in.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7
SELECT EXTRACT(WEEK FROM DATE '2001-02-16');
Result: 7

YEAR

The year field. Keep in mind there is no 0 AD, so subtract BC years from AD
years with care.
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

HP Vertica Analytic Database (7.0.x)

Page 274 of 1539

SQL Reference Manual
SQL Functions

Parameters

field

Single-quoted string value that specifies the field to extract. You must enter the constant
field values (for example, CENTURY, DAY, etc). when specifying the field.
Note: The field parameter values are the same for the EXTRACT function.

source

A date/time expression

Field Values
CENTURY

The century number.
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. This definition applies to all
Gregorian calendar countries. There is no century number 0, you go from –1 to
1.
DAY

The day (of the month) field (1–31).
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT EXTRACT(DAY FROM DATE '2001-02-16');
Result: 16

DECADE

The year field divided by 10.
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200
SELECT EXTRACT(DECADE FROM DATE '2001-02-16');
Result: 200

DOQ

The day within the current quarter.
SELECT EXTRACT(DOQ FROM CURRENT_DATE);
Result: 89

The result is calculated as follows: Current date = June 28, current quarter = 2
(April, May, June). 30 (April) + 31 (May) + 28 (June current day) = 89.
DOQ recognizes leap year days.

HP Vertica Analytic Database (7.0.x)

Page 275 of 1539

SQL Reference Manual
SQL Functions

DOW

The day of the week (0–6; Sunday is 0).
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5
SELECT EXTRACT(DOW FROM DATE '2001-02-16');
Result: 5

EXTRACT's day of the week numbering is different from that of the TO_CHAR
function.
DOY

The day of the year (1–365/366)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47
SELECT EXTRACT(DOY FROM DATE '2001-02-16');
Result: 5

EPOCH

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-0
8');
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 timestamp:
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
HOUR

The hour field (0–23).
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20
SELECT EXTRACT(HOUR FROM TIME '13:45:59');
Result: 13

ISODOW

The ISO day of the week (1–7; Monday is 1).
By definition, the ISO-8601 week starts on Monday, and the first week of a year
contains January 4 of that year. In other words, the first Thursday of a year is in
week 1 of that year.
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(ISODOW FROM DATE '2010-09-27');
Result: 1

ISOWEEK

The ISO week, which consists of 7 days starting on Monday and ending on
Sunday. The first week of the year is the week that contains January 4.

HP Vertica Analytic Database (7.0.x)

Page 276 of 1539

SQL Reference Manual
SQL Functions

ISOYEAR

The ISO year, which is 52 or 53 weeks (Monday–Sunday).
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
Result: 2005
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
Result: 2006
SELECT EXTRACT(ISOYEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

MICROSECONDS

The seconds field, including fractional parts, multiplied by 1,000,000. This
includes full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
Result: 28500000

MILLENNIUM

The millennium number.
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

The seconds field, including fractional parts, multiplied by 1000. This includes
full seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
Result: 28500

MINUTE

The minutes field (0 - 59).
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38
SELECT EXTRACT(MINUTE FROM TIME '13:45:59');
Result: 45

MONTH

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

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

The seconds field, including fractional parts (0–59) (60 if leap seconds are
implemented by the operating system).
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

HP Vertica Analytic Database (7.0.x)

Page 277 of 1539

SQL Reference Manual
SQL Functions

TIME ZONE

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

The minute component of the time zone offset.

WEEK

The number of the week of the calendar year that the day is in.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7
SELECT EXTRACT(WEEK FROM DATE '2001-02-16');
Result: 7

YEAR

The year field. Keep in mind there is no 0 AD, so subtract BC years from AD
years with care.
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

Examples
The following example extracts the day value from the input parameters:
SELECT DATE_PART('day', TIMESTAMP '2009-02-24 20:38:40') "Day";
Day
----24
(1 row)

The following example extracts the month value from the input parameters:
SELECT DATE_PART('month', TIMESTAMP '2009-02-24 20:38:40') "Month";
Month
------2
(1 row)

The following example extracts the year value from the input parameters:
SELECT DATE_PART('year', TIMESTAMP '2009-02-24 20:38:40') "Year";
Year
-----2009
(1 row)

The following example extracts the hours from the input parameters:
SELECT DATE_PART('hour', TIMESTAMP '2009-02-24 20:38:40') "Hour";
Hour

HP Vertica Analytic Database (7.0.x)

Page 278 of 1539

SQL Reference Manual
SQL Functions

-----20
(1 row)

The following example extracts the minutes from the input parameters:
SELECT DATE_PART('minutes', TIMESTAMP '2009-02-24 20:38:40') "Minutes";
Minutes
--------38
(1 row)

The following example extracts the seconds from the input parameters:
SELECT DATE_PART('seconds', TIMESTAMP '2009-02-24 20:38:40') "Seconds";
Seconds
--------40
(1 row)

The following example extracts the day of quarter (DOQ) from the input parameters:
SELECT DATE_PART('DOQ', TIMESTAMP '2009-02-24 20:38:40') "DOQ";
DOQ
----55
(1 row)

SELECT DATE_PART('day', INTERVAL '29 days 23 hours');
date_part
----------29
(1 row)

Notice what happens to the above query if you add an hour:
SELECT DATE_PART('day', INTERVAL '29 days 24 hours');
date_part
----------30
(1 row)

The following example returns 0 because an interval in hours is up to 24 only:
SELECT DATE_PART('hour', INTERVAL '24 hours 45 minutes');
date_part
----------0
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 279 of 1539

SQL Reference Manual
SQL Functions

See Also
EXTRACT

l

DATE
Converts a TIMESTAMP, TIMESTAMPTZ, DATE, or VARCHAR to a DATE. You can also use
this function to convert an INTEGER to a DATE. In this case, the resulting date reflects the int
number of days after 0001 AD. (Day 1 is January 1, 0001.)

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
DATE ( d | n )

Parameters
d

TIMESTAMP, TIMESTAMPTZ, VARCHAR, or DATE input value.

n

Integer you want to convert to a DATE.

Examples
=> SELECT DATE (1);
DATE
-----------0001-01-01
(1 row)
=> SELECT DATE (734260);
DATE
-----------2011-05-03
(1 row)
=> SELECT DATE ('TODAY');
DATE
-----------2011-05-31
(1 row)

DATE_TRUNC
Truncates date and time values as indicated. The return value is of type TIME or TIMETZ with all
fields that are less significant than the selected one set to zero (or one, for day and month).

HP Vertica Analytic Database (7.0.x)

Page 280 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Stable.

Syntax
DATE_TRUNC ( field , source )

Parameters
field

String constant that selects the precision to which truncate the input value.

source

Value expression of type TIME or TIMETZ.

Field Values
CENTURY

The century number.
The first century starts at 0001-01-01 00:00:00 AD. This definition applies to all
Gregorian calendar countries. There is no century number 0, you go from –1 to 1.

DAY

The day (of the month) field (1–31).

DECADE

The year field divided by 10.

HOUR

The hour field (0–23).

MICROSECONDS

The seconds field, including fractional parts, multiplied by 1,000,000. This
includes full seconds.

MILLENNIUM

The millennium number.
Years in the 1900s are in the second millennium. The third millennium starts
January 1, 2001.

MILLISECONDS

The seconds field, including fractional parts, multiplied by 1000. Note that this
includes full seconds.

MINUTE

The minutes field (0–59).

MONTH

For timestamp values, the number of the month within the year (1–12) ; for
interval values the number of months, modulo 12 (0–11).

SECOND

The seconds field, including fractional parts (0–59) (60 if leap seconds are
implemented by the operating system).

HP Vertica Analytic Database (7.0.x)

Page 281 of 1539

SQL Reference Manual
SQL Functions

WEEK

By definition, the ISO-8601 week starts on Monday, and the first week of a year
contains January 4 of that year. In other words, the first Thursday of a year is in
week 1 of that year.
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.
The number of the week of the year that the day is in.

YEAR

The year field. Keep in mind there is no 0 AD, so subtract BC years from AD years
with care.

Examples
The following example sets the field value as hour and returns the hour, truncating the minutes and
seconds:
VMart=> select date_trunc('hour', timestamp '2012-02-24 13:38:40') as hour;
hour
--------------------2012-02-24 13:00:00
(1 row)

The following example returns the year from the input timestamptz '2012-02-24 13:38:40'. The
function also defaults the month and day to January 1, truncates the hour:minute:second of the
timestamp, and appends the time zone (-05):
VMart=> select date_trunc('year', timestamptz '2012-02-24 13:38:40') as year;
year
-----------------------2012-01-01 00:00:00-05
(1 row)

The following example returns the year and month and defaults day of month to 1, truncating the
rest of the string:
VMart=> select date_trunc('month', timestamp '2012-02-24 13:38:40') as year;
year
--------------------2012-02-01 00:00:00
(1 row)

DATEDIFF
Returns the difference between two date or time values, based on the specified start and end
arguments.

HP Vertica Analytic Database (7.0.x)

Page 282 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax 1
DATEDIFF ( datepart , startdate , enddate);

Syntax 2
DATEDIFF ( datepart , starttime , endtime);

Parameters

datepart

Returns the number of specified datepart boundaries between the specified
startdate and enddate.
Can be an unquoted identifier, a quoted string, or an expression in parentheses,
which evaluates to the datepart as a character string.
The following table lists the valid datepartarguments.

startdate

datepart

Abbreviation

year

yy, yyyy

quarter

qq, q

month

mm, m

day

dd, d, dy, dayofyear, y

week

wk, ww

hour

hh

minute

mi, n

second

ss, s

millisecond

ms

microsecond

mcs, us

Start date for the calculation and is an expression that returns a TIMESTAMP,
DATE, or TIMESTAMPTZ value.
The startdate value is not included in the count.

HP Vertica Analytic Database (7.0.x)

Page 283 of 1539

SQL Reference Manual
SQL Functions

enddate

End date for the calculation and is an expression that returns a TIMESTAMP, DATE,
or TIMESTAMPTZ value.
The enddate value is included in the count.

starttime

endtime

Start time for the calculation and is an expression that returns an INTERVAL or TIME
data type.
l

The starttime value is not included in the count.

l

Year, quarter, or month dateparts are not allowed.

End time for the calculation and is an expression that returns an INTERVAL or TIME
data type.
l

The endtime value is included in the count.

l

Year, quarter, or month dateparts are not allowed.

Notes
l

DATEDIFF() is an immutable function with a default type of TIMESTAMP. It also takes DATE.
If TIMESTAMPTZ is specified, the function is stable.

l

HP Vertica accepts statements written in any of the following forms:
=> DATEDIFF(year, s, e);
=> DATEDIFF('year', s, e);

If you use an expression, the expression must be enclosed in parentheses:
=> DATEDIFF((expression), s, e);

l

Starting arguments are not included in the count, but end arguments are included.

The Datepart Boundaries
DATEDIFF calculates results according to ticks—or boundaries—within the date range or time
range. Results are calculated based on the specified datepart. Examine the following statement
and its results:
SELECT DATEDIFF('year', TO_DATE('01-01-2005','MM-DD-YYYY'), TO_DATE('12-31-2008','MM-DD-Y
YYY'));
datediff
---------3
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 284 of 1539

SQL Reference Manual
SQL Functions

The previous example specified a datepart of year, a startdate of January 1, 2005 and an
enddate of December 31, 2008. DATEDIFF returns 3 by counting the year intervals as follows:
[1] January 1, 2006 + [2] January 1, 2007 + [3] January 1, 2008 = 3

The function returns 3, and not 4, because startdate (January 1, 2005) is not counted in the
calculation. DATEDIFF also ignores the months between January 1, 2008 and December 31, 2008
because the datepart specified is year and only the start of each year is counted.
Sometimes the enddate occurs earlier in the ending year than the startdate in the starting year.
For example, assume a datepart of year, a startdate of August 15, 2005, and an enddate of
January 1, 2009. In this scenario, less than three years have elapsed, but DATEDIFF counts the
same way it did in the previous example, returning 3 because it returns the number of January 1s
between the limits:
[1] January 1, 2006 + [2] January 1, 2007 + [3] January 1, 2008 = 3

In the following query, HP Vertica recognizes the full year 2005 as the starting year and 2009 as the
ending year.
SELECT DATEDIFF('year', TO_DATE('08-15-2005','MM-DD-YYYY'), TO_DATE('01-01-2009','MM-DD-Y
YYY'));

The count occurs as follows:
[1] January 1, 2006 + [2] January 1, 2007 + [3] January 1, 2008 + [4] January 1, 2009 =
4

Even though August 15 has not yet occurred in the enddate, the function counts the entire enddate
year as one tick or boundary because of the year datepart.

Examples
Year: In this example, the startdateand enddateare adjacent. The difference between the dates
is one time boundary (second) of its datepart, so the result set is 1.
SELECT DATEDIFF('year', TIMESTAMP '2008-12-31 23:59:59',
'2009-01-01 00:00:00');
datediff
---------1
(1 row)

Quarters start on January, April, July, and October.
In the following example, the result is 0 because the difference from January to February in the
same calendar year does not span a quarter:
SELECT DATEDIFF('qq', TO_DATE('01-01-1995','MM-DD-YYYY'),

HP Vertica Analytic Database (7.0.x)

Page 285 of 1539

SQL Reference Manual
SQL Functions

TO_DATE('02-02-1995','MM-DD-YYYY'));
datediff
---------0
(1 row)

The next example, however, returns eight quarters because the difference spans two full years. The
extra month is ignored:
SELECT DATEDIFF('quarter', TO_DATE('01-01-1993','MM-DD-YYYY'),
TO_DATE('02-02-1995','MM-DD-YYYY'));
datediff
---------8
(1 row)

Months are based on real calendar months.
The following statement returns 1 because there is a one-month difference between January and
February in the same calendar year:
SELECT DATEDIFF('mm', TO_DATE('01-01-2005','MM-DD-YYYY'),
TO_DATE('02-02-2005','MM-DD-YYYY'));
datediff
---------1
(1 row)

The next example returns a negative value of 1:
SELECT DATEDIFF('month', TO_DATE('02-02-1995','MM-DD-YYYY'),
TO_DATE('01-01-1995','MM-DD-YYYY'));
datediff
----------1
(1 row)

And this third example returns 23 because there are 23 months difference between
SELECT DATEDIFF('m', TO_DATE('02-02-1993','MM-DD-YYYY'),
TO_DATE('01-01-1995','MM-DD-YYYY'));
datediff
---------23
(1 row)

Weeks start on Sunday at midnight.
The first example returns 0 because, even though the week starts on a Sunday, it is not a full
calendar week:

HP Vertica Analytic Database (7.0.x)

Page 286 of 1539

SQL Reference Manual
SQL Functions

SELECT DATEDIFF('ww', TO_DATE('02-22-2009','MM-DD-YYYY'),
TO_DATE('02-28-2009','MM-DD-YYYY'));
datediff
---------0
(1 row)

The following example returns 1 (week); January 1, 2000 fell on a Saturday.
SELECT DATEDIFF('week', TO_DATE('01-01-2000','MM-DD-YYYY'),
TO_DATE('01-02-2000','MM-DD-YYYY'));
datediff
---------1
(1 row)

In the next example, DATEDIFF() counts the weeks between January 1, 1995 and February 2,
1995 and returns 4 (weeks):
SELECT DATEDIFF('wk', TO_DATE('01-01-1995','MM-DD-YYYY'),
TO_DATE('02-02-1995','MM-DD-YYYY'));
datediff
---------4
(1 row)

The next example returns a difference of 100 weeks:
SELECT DATEDIFF('ww', TO_DATE('02-02-2006','MM-DD-YYYY'),
TO_DATE('01-01-2008','MM-DD-YYYY'));
datediff
---------100
(1 row)

Days are based on real calendar days.
The first example returns 31, the full number of days in the month of July 2008.
SELECT DATEDIFF('day', 'July 1, 2008', 'Aug 1, 2008'::date);
datediff
---------31
(1 row)

Just over two years of days:
SELECT DATEDIFF('d', TO_TIMESTAMP('01-01-1993','MM-DD-YYYY'),
TO_TIMESTAMP('02-02-1995','MM-DD-YYYY'));
datediff
----------

HP Vertica Analytic Database (7.0.x)

Page 287 of 1539

SQL Reference Manual
SQL Functions

762
(1 row)

Hours, minutes, and seconds are based on clock time.
The first example counts backwards from March 2 to February 14 and returns –384 hours:
SELECT DATEDIFF('hour', TO_DATE('03-02-2009','MM-DD-YYYY'),
TO_DATE('02-14-2009','MM-DD-YYYY'));
datediff
----------384
(1 row)

Another hours example:
SELECT DATEDIFF('hh', TO_TIMESTAMP('01-01-1993','MM-DD-YYYY'),
TO_TIMESTAMP('02-02-1995','MM-DD-YYYY'));
datediff
---------18288
(1 row)

This example counts the minutes backwards:
SELECT DATEDIFF('mi', TO_TIMESTAMP('01-01-1993 03:00:45','MM-DD-YYYY HH:MI:SS'),
TO_TIMESTAMP('01-01-1993 01:30:21',' MM-DD-YYYY HH:MI:SS'));
datediff
----------90
(1 row)

And this example counts the minutes forward:
SELECT DATEDIFF('minute', TO_DATE('01-01-1993','MM-DD-YYYY'),
TO_DATE('02-02-1995','MM-DD-YYYY'));
datediff
---------1097280
(1 row)

In the following example, the query counts the difference in seconds, beginning at a start time of
4:44 and ending at 5:55 with an interval of two days:
SELECT DATEDIFF('ss', TIME '04:44:42.315786',
INTERVAL '2 05:55:52.963558');
datediff
---------177070
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 288 of 1539

SQL Reference Manual
SQL Functions

See Also
Date/Time Expressions

l

DAY
Extracts the day of the month from a TIMESTAMP, TIMESTAMPTZ, INTEGER, VARCHAR, or
INTERVAL input value. The return value is of type INTEGER.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
DAY (d )

Parameters
d

TIMESTAMP, TIMESTAMPTZ, INTERVAL, VARCHAR, or INTEGER input value.

Examples
=> SELECT
DAY
----6
(1 row)
=> SELECT
DAY
----22
(1 row)
=> SELECT
DAY
----22
(1 row)
=> SELECT
DAY
----35
(1 row)

DAY (6);

DAY(TIMESTAMP 'sep 22, 2011 12:34');

DAY('sep 22, 2011 12:34');

DAY(INTERVAL '35 12:34');

HP Vertica Analytic Database (7.0.x)

Page 289 of 1539

SQL Reference Manual
SQL Functions

DAYOFMONTH
Returns an integer representing the day of the month based on a VARCHAR, DATE, TIMESTAMP,
OR TIMESTAMPTZ input value.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
DAYOFMONTH ( d )

Parameters
d

VARCHAR, DATE, TIMESTAMP, or TIMESTAMPTZ input value.

Example
=> SELECT DAYOFMONTH (TIMESTAMP 'sep 22, 2011 12:34');
DAYOFMONTH
-----------22
(1 row)

DAYOFWEEK
Returns an INTEGER representing the day of the week based on a TIMESTAMP, TIMESTAMPTZ,
VARCHAR, or DATE input value. Valid return values are:
Integer Week Day
1

Sunday

2

Monday

3

Tuesday

4

Wednesday

5

Thursday

6

Friday

7

Saturday

HP Vertica Analytic Database (7.0.x)

Page 290 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
DAYOFWEEK ( d )

Parameters
d

TIMESTAMP, TIMESTAMPTZ, VARCHAR, or DATE input value.

Example
=> SELECT DAYOFWEEK (TIMESTAMP 'sep 17, 2011 12:34');
DAYOFWEEK
----------7
(1 row)

DAYOFWEEK_ISO
Returns an INTEGER representing the ISO 8061 day of the week based on a VARCHAR, DATE,
TIMESTAMP, or TIMESTAMPTZ input value. Valid return values are:
Integer Week Day
1

Monday

2

Tuesday

3

Wednesday

4

Thursday

5

Friday

6

Saturday

7

Sunday

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

HP Vertica Analytic Database (7.0.x)

Page 291 of 1539

SQL Reference Manual
SQL Functions

Syntax
DAYOFWEEK_ISO ( d )

Parameters
d

VARCHAR, DATE, TIMESTAMP, or TIMESTAMPTZ input value.

Examples
=> SELECT DAYOFWEEK_ISO(TIMESTAMP 'Sep 22, 2011 12:34');
DAYOFWEEK_ISO
--------------4
(1 row)

The following example shows how to combine the DAYOFWEEK_ISO, WEEK_ISO, and YEAR_
ISO functions to find the ISO day of the week, week, and year:
=> SELECT DAYOFWEEK_ISO('Jan 1, 2000'), WEEK_ISO('Jan 1, 2000'),YEAR_ISO('Jan1,2000');
DAYOFWEEK_ISO | WEEK_ISO | YEAR_ISO
---------------+----------+---------6 |
52 |
1999
(1 row)

See Also
l

WEEK_ISO

l

DAYOFWEEK_ISO

l

http://en.wikipedia.org/wiki/ISO_8601

DAYOFYEAR
Returns an INTEGER representing the day of the year based on a TIMESTAMP, TIMESTAMPTZ ,
VARCHAR, or DATE input value. (January 1 is day 1.)

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
DAYOFYEAR ( d )

HP Vertica Analytic Database (7.0.x)

Page 292 of 1539

SQL Reference Manual
SQL Functions

Parameters
d

TIMESTAMP, TIMESTAMPTZ, VARCHAR, OR DATE input value.

Example
=> SELECT DAYOFYEAR (TIMESTAMP 'SEPT 22,2011 12:34');
DAYOFYEAR
----------265
(1 row)

DAYS
Converts a DATE, VARCHAR, TIMESTAMP, or TIMESTAMPTZ to an INTEGER, reflecting the
number of days after 0001 AD.

Behavior Type
Immutable

Syntax
DAYS( DATE d )

Parameters
DATE d

VARCHAR, DATE, TIMESTAMP, or TIMESTAMPTZ input value.

Example
=> SELECT DAYS (DATE '2011-01-22');
DAYS
-------734159
(1 row)
=> SELECT DAYS ('1999-12-31');
DAYS
-------730119
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 293 of 1539

SQL Reference Manual
SQL Functions

EXTRACT
Retrieves subfields such as year or hour from date/time values and returns values of type
NUMERIC. EXTRACT is primarily intended for computational processing, rather than for
formatting date/time values for display.
Internally EXTRACT uses the DATE_PART function.

Behavior Type
Stable when source is of type TIMESTAMPTZ, Immutable otherwise.

Syntax
EXTRACT ( field FROM source )
CENTURY

The century number.
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. This definition applies to all
Gregorian calendar countries. There is no century number 0, you go from –1 to
1.
DAY

The day (of the month) field (1–31).
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT EXTRACT(DAY FROM DATE '2001-02-16');
Result: 16

DECADE

The year field divided by 10.
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200
SELECT EXTRACT(DECADE FROM DATE '2001-02-16');
Result: 200

DOQ

The day within the current quarter.
SELECT EXTRACT(DOQ FROM CURRENT_DATE);
Result: 89

The result is calculated as follows: Current date = June 28, current quarter = 2
(April, May, June). 30 (April) + 31 (May) + 28 (June current day) = 89.
DOQ recognizes leap year days.

HP Vertica Analytic Database (7.0.x)

Page 294 of 1539

SQL Reference Manual
SQL Functions

DOW

The day of the week (0–6; Sunday is 0).
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5
SELECT EXTRACT(DOW FROM DATE '2001-02-16');
Result: 5

EXTRACT's day of the week numbering is different from that of the TO_CHAR
function.
DOY

The day of the year (1–365/366)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47
SELECT EXTRACT(DOY FROM DATE '2001-02-16');
Result: 5

EPOCH

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-0
8');
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 timestamp:
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
HOUR

The hour field (0–23).
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20
SELECT EXTRACT(HOUR FROM TIME '13:45:59');
Result: 13

ISODOW

The ISO day of the week (1–7; Monday is 1).
By definition, the ISO-8601 week starts on Monday, and the first week of a year
contains January 4 of that year. In other words, the first Thursday of a year is in
week 1 of that year.
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(ISODOW FROM DATE '2010-09-27');
Result: 1

ISOWEEK

The ISO week, which consists of 7 days starting on Monday and ending on
Sunday. The first week of the year is the week that contains January 4.

HP Vertica Analytic Database (7.0.x)

Page 295 of 1539

SQL Reference Manual
SQL Functions

ISOYEAR

The ISO year, which is 52 or 53 weeks (Monday–Sunday).
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
Result: 2005
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
Result: 2006
SELECT EXTRACT(ISOYEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

MICROSECONDS

The seconds field, including fractional parts, multiplied by 1,000,000. This
includes full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
Result: 28500000

MILLENNIUM

The millennium number.
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

The seconds field, including fractional parts, multiplied by 1000. This includes
full seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
Result: 28500

MINUTE

The minutes field (0 - 59).
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38
SELECT EXTRACT(MINUTE FROM TIME '13:45:59');
Result: 45

MONTH

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

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

The seconds field, including fractional parts (0–59) (60 if leap seconds are
implemented by the operating system).
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

HP Vertica Analytic Database (7.0.x)

Page 296 of 1539

SQL Reference Manual
SQL Functions

TIME ZONE

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

The minute component of the time zone offset.

WEEK

The number of the week of the calendar year that the day is in.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7
SELECT EXTRACT(WEEK FROM DATE '2001-02-16');
Result: 7

YEAR

The year field. Keep in mind there is no 0 AD, so subtract BC years from AD
years with care.
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

Parameters
field

Identifier or string that selects what field to extract from the source value. You must
enter the constant field values (i.e. CENTURY, DAY, etc). when specifying the field.
Note: The field parameter is the same for the DATE_PART() function.

source

Expression of type DATE, TIMESTAMP, TIME, or INTERVAL.
Note: Expressions of type DATE are cast to TIMESTAMP.

Field Values
CENTURY

The century number.
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. This definition applies to all
Gregorian calendar countries. There is no century number 0, you go from –1 to
1.
DAY

The day (of the month) field (1–31).
SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 16
SELECT EXTRACT(DAY FROM DATE '2001-02-16');
Result: 16

HP Vertica Analytic Database (7.0.x)

Page 297 of 1539

SQL Reference Manual
SQL Functions

DECADE

The year field divided by 10.
SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 200
SELECT EXTRACT(DECADE FROM DATE '2001-02-16');
Result: 200

DOQ

The day within the current quarter.
SELECT EXTRACT(DOQ FROM CURRENT_DATE);
Result: 89

The result is calculated as follows: Current date = June 28, current quarter = 2
(April, May, June). 30 (April) + 31 (May) + 28 (June current day) = 89.
DOQ recognizes leap year days.
DOW

The day of the week (0–6; Sunday is 0).
SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 5
SELECT EXTRACT(DOW FROM DATE '2001-02-16');
Result: 5

EXTRACT's day of the week numbering is different from that of the TO_CHAR
function.
DOY

The day of the year (1–365/366)
SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 47
SELECT EXTRACT(DOY FROM DATE '2001-02-16');
Result: 5

EPOCH

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-0
8');
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 timestamp:
SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
HOUR

The hour field (0–23).
SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20
SELECT EXTRACT(HOUR FROM TIME '13:45:59');
Result: 13

HP Vertica Analytic Database (7.0.x)

Page 298 of 1539

SQL Reference Manual
SQL Functions

ISODOW

The ISO day of the week (1–7; Monday is 1).
By definition, the ISO-8601 week starts on Monday, and the first week of a year
contains January 4 of that year. In other words, the first Thursday of a year is in
week 1 of that year.
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(ISODOW FROM DATE '2010-09-27');
Result: 1

ISOWEEK

The ISO week, which consists of 7 days starting on Monday and ending on
Sunday. The first week of the year is the week that contains January 4.

ISOYEAR

The ISO year, which is 52 or 53 weeks (Monday–Sunday).
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
Result: 2005
SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
Result: 2006
SELECT EXTRACT(ISOYEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

MICROSECONDS

The seconds field, including fractional parts, multiplied by 1,000,000. This
includes full seconds.
SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
Result: 28500000

MILLENNIUM

The millennium number.
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

The seconds field, including fractional parts, multiplied by 1000. This includes
full seconds.
SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
Result: 28500

MINUTE

The minutes field (0 - 59).
SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 38
SELECT EXTRACT(MINUTE FROM TIME '13:45:59');
Result: 45

HP Vertica Analytic Database (7.0.x)

Page 299 of 1539

SQL Reference Manual
SQL Functions

MONTH

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

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

The seconds field, including fractional parts (0–59) (60 if leap seconds are
implemented by the operating system).
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

TIME ZONE

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

The minute component of the time zone offset.

WEEK

The number of the week of the calendar year that the day is in.
SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 7
SELECT EXTRACT(WEEK FROM DATE '2001-02-16');
Result: 7

YEAR

The year field. Keep in mind there is no 0 AD, so subtract BC years from AD
years with care.
SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
Result: 2001

Examples
=> SELECT EXTRACT (DAY FROM DATE '2008-12-25');
date_part
----------25
(1 row)
=> SELECT EXTRACT (MONTH FROM DATE '2008-12-25');
date_part
-----------

HP Vertica Analytic Database (7.0.x)

Page 300 of 1539

SQL Reference Manual
SQL Functions

12
(1 row
SELECT EXTRACT(DOQ FROM CURRENT_DATE);
date_part
----------89
(1 row)

Remember that internally EXTRACT() uses the DATE_PART() function:
=> SELECT EXTRACT(EPOCH FROM AGE_IN_YEARS(TIMESTAMP '2009-02-24',
2') :: INTERVAL year);
date_part
----------1136073600
(1 row)

TIMESTAMP '1972-03-0

In the above example, AGE_IN_YEARS is 36. The UNIX epoch uses 365.25 days per year:
=> SELECT 1136073600.0/36/(24*60*60);
?column?
---------365.25
(1 row)

You can extract the timezone hour from TIMETZ:
=> SELECT EXTRACT(timezone_hour FROM TIMETZ '10:30+13:30');
date_part
----------13
(1 row)

See Also
l

DATE_PART

GETDATE
Returns the current system date and time as a TIMESTAMP value.

Behavior Type
Stable

Syntax
GETDATE();

HP Vertica Analytic Database (7.0.x)

Page 301 of 1539

SQL Reference Manual
SQL Functions

Notes
l

GETDATE is a stable function that requires parentheses but accepts no arguments.

l

This function uses the date and time supplied by the operating system on the server to which
you are connected, which is the same across all servers.

l

GETDATE internally converts STATEMENT_TIMESTAMP() from TIMESTAMPTZ to
TIMESTAMP.

l

This function is identical to SYSDATE().

Example
=> SELECT GETDATE();
GETDATE
---------------------------2011-03-07 13:21:29.497742
(1 row)

See Also
l

Date/Time Expressions

GETUTCDATE
Returns the current system date and time as a TIMESTAMP value relative to UTC.

Behavior Type
Stable

Syntax
GETUTCDATE();

Notes
l

GETUTCDATE is a stable function that requires parentheses but accepts no arguments.

l

This function uses the date and time supplied by the operating system on the server to which
you are connected, which is the same across all servers.

l

GETUTCDATE is internally converted to STATEMENT_TIMESTAMP() at TIME ZONE 'UTC'.

HP Vertica Analytic Database (7.0.x)

Page 302 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT GETUTCDATE();
GETUTCDATE
---------------------------2011-03-07 20:20:26.193052
(1 row)

See Also
Date/Time Expressions

l

HOUR
Extracts the hour from a DATE, TIMESTAMP, TIMESTAMPTZ, VARCHAR, or INTERVAL value.
The return value is of type INTEGER. (Hour 0 is midnight to 1 a.m.)

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
HOUR ( d )

Parameters
d

Incoming DATE, TIMESTAMP, TIMESTAMPTZ, VARCHAR, or INTERVAL value.

Examples
=> SELECT HOUR (TIMESTAMP 'sep 22, 2011 12:34');
HOUR
-----12
(1 row)
=> SELECT HOUR (INTERVAL '35 12:34');
HOUR
-----12
(1 row)
=> SELECT HOUR ('12:34');
HOUR
-----12

HP Vertica Analytic Database (7.0.x)

Page 303 of 1539

SQL Reference Manual
SQL Functions

(1 row)

ISFINITE
Tests for the special TIMESTAMP constant INFINITY and returns a value of type BOOLEAN.

Behavior Type
Immutable

Syntax
ISFINITE ( timestamp )

Parameters
timestamp

Expression of type TIMESTAMP

Examples
SELECT ISFINITE(TIMESTAMP '2009-02-16 21:28:30');
isfinite
---------t
(1 row)
SELECT ISFINITE(TIMESTAMP 'INFINITY');
isfinite
---------f
(1 row)

JULIAN_DAY
Returns an INTEGER representing the Julian day based on an input TIMESTAMP,
TIMESTAMPTZ, VARCHAR, or DATE value.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
JULIAN_DAY ( d )

HP Vertica Analytic Database (7.0.x)

Page 304 of 1539

SQL Reference Manual
SQL Functions

Parameters
d

Is the TIMESTAMP, TIMESTAMPTZ, VARCHAR, or DATE input value.

Example
=> SELECT JULIAN_DAY(TIMESTAMP 'sep 22, 2011 12:34');
JULIAN_DAY
-----------2455827
(1 row)

LAST_DAY
Returns the last day of the month based on a TIMESTAMP. The TIMESTAMP can be supplied as a
DATE or a TIMESTAMPTZ data type.

Behavior Type
Immutable, unless called with TIMESTAMPTZ, in which case it is Stable.

Syntax
LAST_DAY ( date );

Examples
The following example returns the last day of the month, February, as 29 because 2008 was a leap
year:
SELECT LAST_DAY('2008-02-28 23:30 PST') "Last";
Last
-----------2008-02-29
(1 row)

The following example returns the last day of the month in March, after converting the string value
to the specified DATE type:
SELECT LAST_DAY('2003/03/15') "Last";
Last
-----------2003-03-31
(1 row)

The following example returns the last day of February in the specified year (not a leap year):

HP Vertica Analytic Database (7.0.x)

Page 305 of 1539

SQL Reference Manual
SQL Functions

SELECT LAST_DAY('2003/02/03') "Last";
Last
-----------2003-02-28
(1 row)

LOCALTIME
Returns a value of type TIME representing the time of day.

Behavior Type
Stable

Syntax
LOCALTIME [ ( precision ) ]

Parameters
precision

Causes the result to be rounded to the specified number of fractional digits in the
seconds field.

Notes
This function returns the start time of the current transaction; the value does not change during the
transaction. 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 timestamp.

Example
SELECT LOCALTIME;
time
----------------16:16:06.790771
(1 row)

LOCALTIMESTAMP
Returns a value of type TIMESTAMP that represents today's date and time of day.

Behavior Type
Stable

HP Vertica Analytic Database (7.0.x)

Page 306 of 1539

SQL Reference Manual
SQL Functions

Syntax
LOCALTIMESTAMP [ ( precision ) ]

Parameters
precision

Causes the result to be rounded to the specified number of fractional digits in the
seconds field.

Notes
This function returns the start time of the current transaction; the value does not change during the
transaction. 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 timestamp.

Example
SELECT LOCALTIMESTAMP;
timestamp
-------------------------2009-02-24 14:47:48.5951
(1 row)

MICROSECOND
Returns an INTEGER representing the microsecond portion of an input DATE, VARCHAR,
TIMESTAMP, TIMESTAMPTZ, or INTERVAL value.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
MICROSECOND ( d )

Parameters
d

DATE, VARCHAR, TIMESTAMP, TIMESTAMPTZ, or INTERVAL input value.

HP Vertica Analytic Database (7.0.x)

Page 307 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT MICROSECOND (TIMESTAMP 'Sep 22, 2011 12:34:01.123456');
MICROSECOND
------------123456
(1 row)

MIDNIGHT_SECONDS
Returns an INTEGER that represents the number of seconds between midnight and the input
value. The input value can be of type VARCHAR, TIME, TIMESTAMP, or TIMESTAMPTZ.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
MIDNIGHT_SECONDS ( d )

Parameters
d

VARCHAR, TIME, TIMESTAMP, or TIMESTAMPTZ input value.

Example
=> SELECT MIDNIGHT_SECONDS('12:34:00.987654');
MIDNIGHT_SECONDS
-----------------45240
(1 row)
=> SELECT MIDNIGHT_SECONDS(TIME '12:34:00.987654');
MIDNIGHT_SECONDS
-----------------45240
(1 row)
=> SELECT MIDNIGHT_SECONDS (TIMESTAMP 'sep 22, 2011 12:34');
MIDNIGHT_SECONDS
-----------------45240
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 308 of 1539

SQL Reference Manual
SQL Functions

MINUTE
Returns an INTEGER that represents the minute value of the input value. The input value can be of
type VARCHAR, DATE, TIMESTAMP, TIMESTAMPTZ, or INTERVAL.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
MINUTE ( d )

Parameters
d

VARCHAR, DATE, TIMESTAMP, TIMESTAMPTZ, or INTERVAL input value.

Example
=> SELECT MINUTE('12:34:03.456789');
MINUTE
-------34
(1 row)
=>SELECT MINUTE (TIMESTAMP 'sep 22, 2011 12:34');
MINUTE
-------34
(1 row)
=> SELECT MINUTE(INTERVAL '35 12:34:03.456789');
MINUTE
-------34
(1 row)

MONTH
Returns an INTEGER that represents the month portion of the input value. The input value can be
of type VARCHAR, DATE, TIMESTAMP, TIMESTAMPTZ, or INTERVAL.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

HP Vertica Analytic Database (7.0.x)

Page 309 of 1539

SQL Reference Manual
SQL Functions

Syntax
MONTH( d )

Parameters
d

Incoming VARCHAR, DATE, TIMESTAMP, TIMESTAMPTZ, or INTERVAL value.

Examples
=> SELECT MONTH('6-9');
MONTH
------9
(1 row)
=> SELECT MONTH (TIMESTAMP 'sep 22, 2011 12:34');
MONTH
------9
(1 row)
=> SELECT MONTH(INTERVAL '2-35' year to month);
MONTH
------11
(1 row)

MONTHS_BETWEEN
Returns the number of months between date1 and date2 as a FLOAT8, where the input arguments
can be of TIMESTAMP, DATE, or TIMESTAMPTZ type.

Behavior Type
Immutable for TIMESTAMP and DATE, Stable for TIMESTAMPTZ

Syntax
MONTHS_BETWEEN ( date1 , date2 );

HP Vertica Analytic Database (7.0.x)

Page 310 of 1539

SQL Reference Manual
SQL Functions

Parameters
date1, date2

If date1 is later than date2, the result is positive. If date1 is earlier than date2,
then the result is negative.
If date1 and date2 are either the same days of the month or both are the last days
of their respective month, then the result is always an integer. Otherwise
MONTHS_BETWEEN returns a FLOAT8 result based on a 31-day month, which
considers the difference between date1 and date2.

Examples
The following result is an integral number of days because the dates are on the same day of the
month:
=> SELECT MONTHS_BETWEEN('2009-03-07 16:00'::TIMESTAMP,
'2009-04-07 15:00'::TIMESTAMP);
MONTHS_BETWEEN
----------------1
(1 row)

The result from the next example returns an integral number of days because the days fall on the
last day of their respective months:
=> SELECT MONTHS_BETWEEN('29Feb2000', '30Sep2000') "Months";
MONTHS
----------------7
(1 row)

In the next example, and in the example that immediately follows it, MONTHS_BETWEEN() returns the
number of months between date1 and date2 as a fraction because the days do not fall on the same
day or on the last day of their respective months:
=> SELECT MONTHS_BETWEEN(TO_DATE('02-02-1995','MM-DD-YYYY'),
TO_DATE('01-01-1995','MM-DD-YYYY') ) "Months";
Months
-----------------1.03225806451613
(1 row)
=> SELECT MONTHS_BETWEEN(TO_DATE ('2003/01/01', 'yyyy/mm/dd'),
TO_DATE ('2003/03/14', 'yyyy/mm/dd') ) "Months";
Months
-------------------2.41935483870968
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 311 of 1539

SQL Reference Manual
SQL Functions

The following two examples use the same date1 and date2 strings, but they are cast to a different
data types (TIMESTAMP and TIMESTAMPTZ). The result is the same for both statements:
SELECT MONTHS_BETWEEN('2008-04-01'::timestamp, '2008-02-29'::timestamp);
months_between
-----------------1.09677419354839
(1 row)
SELECT MONTHS_BETWEEN('2008-04-01'::timestamptz, '2008-02-29'::timestamptz);
months_between
-----------------1.09677419354839
(1 row)

The following two examples show alternate inputs:
SELECT MONTHS_BETWEEN('2008-04-01'::date, '2008-02-29'::timestamp);
months_between
-----------------1.09677419354839
(1 row)
SELECT MONTHS_BETWEEN('2008-02-29'::timestamptz, '2008-04-01'::date);
months_between
-------------------1.09677419354839
(1 row)

NEW_TIME
Converts a TIMESTAMP value between time zones. Intervals are not permitted.

Behavior Type
Immutable

Syntax
NEW_TIME( 'timestamp' , 'timezone1' , 'timezone2')

Returns
TIMESTAMP

HP Vertica Analytic Database (7.0.x)

Page 312 of 1539

SQL Reference Manual
SQL Functions

Parameters
timestamp

The TIMESTAMP (or a TIMESTAMPTZ, DATE, or character string which can be
converted to a TIMESTAMP) representing a TIMESTAMP in timezone1 that returns
the equivalent timestamp in timezone2.

timezone1

VARCHAR string of the form required by the TIMESTAMP AT TIMEZONE 'zone'
clause. timezone1 indicates the time zone from which you want to convert
timestamp. It must be a valid timezone, as listed in the field for timezone2 below.

timezone2

VARCHAR string of the form required by the TIMESTAMP AT TIMEZONE 'zone'
clause. timezone2 indicates the time zone into which you want to convert timestamp.

Notes
The timezone arguments are character strings of the form required by the TIMESTAMP AT
TIMEZONE 'zone' clause; for example:
AST, ADT

Atlantic Standard Time or Daylight Time

BST, BDT

Bering Standard Time or Daylight Time

CST, CDT

Central Standard Time or Daylight Time

EST, EDT

Eastern Standard Time or Daylight Time

GMT

Greenwich Mean Time

HST

Alaska-Hawaii Standard Time

MST, MDT

Mountain Standard Time or Daylight Time

NST

Newfoundland Standard Time

PST, PDT

Pacific Standard Time or Daylight Time

Examples
The following command converts the specified time from Eastern Standard Time to Pacific
Standard Time:
=> SELECT NEW_TIME('05-24-12 13:48:00', 'EST', 'PST');
NEW_TIME
--------------------2012-05-24 10:48:00
(1 row)

This command converts the time on January 1 from Eastern Standard Time to Pacific Standard
Time. Notice how the time rolls back to the previous year:

HP Vertica Analytic Database (7.0.x)

Page 313 of 1539

SQL Reference Manual
SQL Functions

=> SELECT NEW_TIME('01-01-12 01:00:00', 'EST', 'PST');
NEW_TIME
--------------------2011-12-31 22:00:00
(1 row)

Query the current system time:
=> SELECT NOW();
now
------------------------------2012-05-24 08:28:10.155887-04
(1 row)
=> SELECT NEW_TIME('NOW', 'EDT', 'CDT');
NEW_TIME
---------------------------2012-05-24 07:28:10.155887
(1 row)

The following example returns the year 45 before the Common Era in Greenwich Mean Time and
converts it to Newfoundland Standard Time:
=>

SELECT NEW_TIME('April 1, 45 BC', 'GMT', 'NST');
NEW_TIME
-----------------------0045-03-31 20:30:00 BC
(1 row)
=> SELECT NEW_TIME('April 1 2011', 'EDT', 'PDT');
NEW_TIME
--------------------2011-03-31 21:00:00
(1 row)
=> SELECT NEW_TIME('May 24, 2012 10:00', 'Pacific/Kiritamati', 'EDT');
NEW_TIME
--------------------2011-05-23 16:00:00
(1 row)

NEXT_DAY
Returns the date of the first instance of a particular day of the week that follows the specified date.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
NEXT_DAY( 'date', 'DOW')

HP Vertica Analytic Database (7.0.x)

Page 314 of 1539

SQL Reference Manual
SQL Functions

Parameters
date

VARCHAR, TIMESTAMP, TIMESTAMPTZ, or DATE. Only standard English day-names
and day-name abbreviations are accepted.

DOW

Day of week, type CHAR/VARCHAR string or character constant. DOW is not case
sensitive and trailing spaces are ignored.

Examples
The following example returns the date of the next Friday following the specified date. All are
variations on the same query, and all return the same result:
=> SELECT NEXT_DAY('28-MAR-2011','FRIDAY') "NEXT DAY" FROM DUAL;
NEXT DAY
-----------2011-04-01
(1 row)
=> SELECT NEXT_DAY('March 28 2011','FRI') "NEXT DAY" FROM DUAL;
NEXT DAY
-----------2011-04-01
(1 row)
=> SELECT NEXT_DAY('3-29-11','FRI') "NEXT DAY" FROM DUAL;
NEXT DAY
-----------2011-04-01
(1 row)

NOW [Date/Time]
Returns a value of type TIMESTAMP WITH TIME ZONE representing the start of the current
transaction. NOW is equivalent to CURRENT_TIMESTAMP except that it does not accept a
precision parameter.

Behavior Type
Stable

Syntax
NOW()

Notes
This function returns the start time of the current transaction; the value does not change during the
transaction. The intent is to allow a single transaction to have a consistent notion of the "current"

HP Vertica Analytic Database (7.0.x)

Page 315 of 1539

SQL Reference Manual
SQL Functions

time, so that multiple modifications within the same transaction bear the same timestamp.

Example
SELECT NOW();
NOW
------------------------------2010-04-01 15:31:12.144584-04
(1 row)

See Also
l

CURRENT_TIMESTAMP

OVERLAPS
Returns true when two time periods overlap, false when they do not overlap.

Behavior Type
Stable when TIMESTAMP and TIMESTAMPTZ are both used, or when TIMESTAMPTZ is used
with INTERVAL, Immutable otherwise.

Syntax
( start, end ) OVERLAPS ( start, end )
( start, interval ) OVERLAPS ( start, interval )

Parameters
start

DATE, TIME, or TIME STAMP value that specifies the beginning of a time period.

end

DATE, TIME, or TIME STAMP value that specifies the end of a time period.

interval

Value that specifies the length of the time period.

Examples
The first command returns true for an overlap in date range of 2007-02-16 through 2007-12-21 with
2007-10-30 through 2008-10-30.
SELECT (DATE '2007-02-16', DATE '2007-12-21')
OVERLAPS (DATE '2007-10-30', DATE '2008-10-30');
OVERLAPS
---------t

HP Vertica Analytic Database (7.0.x)

Page 316 of 1539

SQL Reference Manual
SQL Functions

(1 row)

The next command returns false for an overlap in date range of 2007-02-16 through 2007-12-21 with
2008-10-30 through 2008-10-30.
SELECT (DATE '2007-02-16', DATE '2007-12-21')
OVERLAPS (DATE '2008-10-30', DATE '2008-10-30');
OVERLAPS
---------f
(1 row)

The next command returns false for an overlap in date range of 2007-02-16, 22 hours ago with 200710-30, 22 hours ago.
SELECT (DATE '2007-02-16', INTERVAL '1 12:59:10')
OVERLAPS (DATE '2007-10-30', INTERVAL '1 12:59:10');
overlaps
---------f
(1 row)

QUARTER
Returns an INTEGER representing calendar quarter into which the input value falls. The input value
can be of type VARCHAR, DATE, TIMESTAMP or TIMESTAMPTZ.

Syntax
QUARTER( d )

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

DATE, VARCHAR, TIMESTAMP, or TIMESTAMPTZ input value.

Example
=> SELECT QUARTER (TIMESTAMP 'sep 22, 2011 12:34');
QUARTER
--------3

HP Vertica Analytic Database (7.0.x)

Page 317 of 1539

SQL Reference Manual
SQL Functions

(1 row)

ROUND [Date/Time]
Rounds a TIMESTAMP, TIMESTAMPTZ, or DATE. The return value is of type TIMESTAMP.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
ROUND([TIMESTAMP | DATE] , format )

Parameters
TIMESTAMP | DATE

TIMESTAMP or DATE input value.

HP Vertica Analytic Database (7.0.x)

Page 318 of 1539

SQL Reference Manual
SQL Functions

format

A string constant that selects the precision to which truncate the
input value. Valid values are:
Precision

Valid values

Century

CC, SCC

Year

SYYY, YYYY, YEAR,
YYY, YY,Y

ISO Year

IYYY, IYY, IY, I

Quarter

Q

Month

MONTH, MON, MM,
RM

Same day of the week as the first day
of the year

WW

Same day of the week as the first day
of the ISO year

IW

Same day of the week as the first day
of the month

W

Day

DDD, DD, J

Starting day of the week

DAY, DY, D

Hour

HH, HH12, HH24

Minute

MI

Second

SS

Example
=> SELECT ROUND(TIMESTAMP 'sep 22, 2011 12:34:00', 'dy');
ROUND
--------------------2011-09-18 00:00:00
(1 row)

SECOND
Returns an INTEGER representing the second portion of the input value. The input value can be of
type VARCHAR, TIMESTAMP, TIMESTAMPTZ, or INTERVAL.

HP Vertica Analytic Database (7.0.x)

Page 319 of 1539

SQL Reference Manual
SQL Functions

Syntax
SECOND( d )

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

VARCHAR, TIMESTAMP, TIMESTAMPTZ, or INTERVAL input value.

Examples
=> SELECT SECOND ('23:34:03.456789');
SECOND
-------3
(1 row)
=> SELECT SECOND (TIMESTAMP 'sep 22, 2011 12:34');
SECOND
-------0
(1 row)
=> SELECT SECOND (INTERVAL '35 12:34:03.456789');
SECOND
-------3
(1 row)

STATEMENT_TIMESTAMP
Is similar to TRANSACTION_TIMESTAMP. It returns a value of type TIMESTAMP WITH TIME
ZONE representing the start of the current statement.

Behavior Type
Stable

Syntax
STATEMENT_TIMESTAMP()

HP Vertica Analytic Database (7.0.x)

Page 320 of 1539

SQL Reference Manual
SQL Functions

Notes
This function returns the start time of the current statement; the value does not change during the
statement. The intent is to allow a single statement to have a consistent notion of the "current"
time, so that multiple modifications within the same statement bear the same timestamp.

Example
SELECT STATEMENT_TIMESTAMP();
STATEMENT_TIMESTAMP
------------------------------2010-04-01 15:40:42.223736-04
(1 row)

See Also
l

CLOCK_TIMESTAMP

l

TRANSACTION_TIMESTAMP

SYSDATE
Returns the current system date and time as a TIMESTAMP value.

Behavior Type
Stable

Syntax
SYSDATE();

Notes
l

SYSDATE is a stable function (called once per statement) that requires no arguments.
Parentheses are optional.

l

This function uses the date and time supplied by the operating system on the server to which
you are connected, which must be the same across all servers.

l

In implementation, SYSDATE converts STATEMENT_TIMESTAMP from TIMESTAMPTZ to
TIMESTAMP.

l

This function is identical to GETDATE().

HP Vertica Analytic Database (7.0.x)

Page 321 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT SYSDATE();
sysdate
---------------------------2011-03-07 13:22:28.295802
(1 row)

See Also
l

Date/Time Expressions

TIME_SLICE
Aggregates data by different fixed-time intervals and returns a rounded-up input TIMESTAMP value
to a value that corresponds with the start or end of the time slice interval.
Given an input TIMESTAMP value, such as '2000-10-28 00:00:01', the start time of a 3-second time
slice interval is '2000-10-28 00:00:00', and the end time of the same time slice is '2000-10-28
00:00:03'.

Behavior Type
Immutable

Syntax
TIME_SLICE(expression, slice_length,
[ time_unit = 'SECOND' ],
[ start_or_end = 'START' ] )

Parameters
expression

Can be either a column of type TIMESTAMP or a (string) constant that can be
parsed into a TIMESTAMP value, such as '2004-10-19 10:23:54'.
HP Vertica evaluates expression on each row.

slice_length

Length of the slice specified in integers. Input must be a positive integer.

time_unit

Time unit of the slice with a default of SECOND.
Domain of possible values: { HOUR, MINUTE, SECOND, MILLISECOND,
MICROSECOND }.

HP Vertica Analytic Database (7.0.x)

Page 322 of 1539

SQL Reference Manual
SQL Functions

start_or_end

Indicates whether the returned value corresponds to the start or end time of the
time slice interval. The default is START.
Domain of possible values: { START, END }.

Notes
l

The returned value's data type is TIMESTAMP.

l

The corresponding SQL data type for TIMESTAMP is TIMESTAMP WITHOUT TIME ZONE.
HP Vertica supports TIMESTAMP for TIME_SLICE instead of DATE and TIME data types.

l

TIME_SLICE exhibits the following behavior around nulls:
n

The system returns an error when any one of slice_length, time_unit, or start_or_end
parameters is null.

n

When slice_length, time_unit, and start_or_end contain legal values, and expression is null,
the system returns a NULL value, instead of an error.

Usage
The following command returns the (default) start time of a 3-second time slice:
SELECT TIME_SLICE('2009-09-19 00:00:01', 3);
time_slice
--------------------2009-09-19 00:00:00
(1 row)

The following command returns the end time of a 3-second time slice:
SELECT TIME_SLICE('2009-09-19 00:00:01', 3, 'SECOND', 'END');
time_slice
--------------------2009-09-19 00:00:03
(1 row)

This command returns results in milliseconds, using a 3-second time slice:
SELECT TIME_SLICE('2009-09-19 00:00:01', 3, 'ms');
time_slice
------------------------2009-09-19 00:00:00.999
(1 row)

This command returns results in microseconds, using a 9-second time slice:

HP Vertica Analytic Database (7.0.x)

Page 323 of 1539

SQL Reference Manual
SQL Functions

SELECT TIME_SLICE('2009-09-19 00:00:01', 3, 'us');
time_slice
---------------------------2009-09-19 00:00:00.999999
(1 row)

The next example uses a 3-second interval with an input value of '00:00:01'. To focus specifically
on seconds, the example omits date, though all values are implied as being part of the timestamp
with a given input of '00:00:01':
l

'00:00:00' is the start of the 3-second time slice

l

'00:00:03' is the end of the 3-second time slice.

l

'00:00:03' is also the start of the second 3-second time slice. In time slice boundaries, the end
value of a time slice does not belong to that time slice; it starts the next one.

When the time slice interval is not a factor of 60 seconds, such as a given slice length of 9 in the
following example, the slice does not always start or end on 00 seconds:
SELECT TIME_SLICE('2009-02-14 20:13:01', 9);
time_slice
--------------------2009-02-14 20:12:54
(1 row)

This is expected behavior, as the following properties are true for all time slices:
l

Equal in length

l

Consecutive (no gaps between them)

l

Non-overlapping

HP Vertica Analytic Database (7.0.x)

Page 324 of 1539

SQL Reference Manual
SQL Functions

To force the above example ('2009-02-14 20:13:01') to start at '2009-02-14 20:13:00', adjust the
output timestamp values so that the remainder of 54 counts up to 60:
SELECT TIME_SLICE('2009-02-14 20:13:01', 9 )+'6 seconds'::INTERVAL AS time;
time
--------------------2009-02-14 20:13:00
(1 row)

Alternatively, you could use a different slice length, which is divisible by 60, such as 5:
SELECT TIME_SLICE('2009-02-14 20:13:01', 5);
time_slice
--------------------2009-02-14 20:13:00
(1 row)

A TIMESTAMPTZ value is implicitly cast to TIMESTAMP. For example, the following two
statements have the same effect.
SELECT TIME_SLICE('2009-09-23 11:12:01'::timestamptz, 3);
TIME_SLICE
--------------------2009-09-23 11:12:00
(1 row)
SELECT TIME_SLICE('2009-09-23 11:12:01'::timestamptz::timestamp, 3);
TIME_SLICE
--------------------2009-09-23 11:12:00
(1 row)

Examples
You can use the SQL analytic functions FIRST_VALUE and LAST_VALUE to find the first/last
price within each time slice group (set of rows belonging to the same time slice). This structure
could be useful if you want to sample input data by choosing one row from each time slice group.
SELECT date_key, transaction_time, sales_dollar_amount,TIME_SLICE(DATE '2000-01-01' + dat
e_key + transaction_time, 3),
FIRST_VALUE(sales_dollar_amount)
OVER (PARTITION BY TIME_SLICE(DATE '2000-01-01' + date_key + transaction_time, 3)
ORDER BY DATE '2000-01-01' + date_key + transaction_time) AS first_value
FROM store.store_sales_fact
LIMIT 20;
date_key | transaction_time | sales_dollar_amount |
time_slice
| first_value
----------+------------------+---------------------+---------------------+------------1 | 00:41:16
|
164 | 2000-01-02 00:41:15 |
164
1 | 00:41:33
|
310 | 2000-01-02 00:41:33 |
310
1 | 15:32:51
|
271 | 2000-01-02 15:32:51 |
271
1 | 15:33:15
|
419 | 2000-01-02 15:33:15 |
419

HP Vertica Analytic Database (7.0.x)

Page 325 of 1539

SQL Reference Manual
SQL Functions

1
1
1
2
3
3
3
3
3
3
4
4
4
4
4
5
(20 rows)

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

15:33:44
16:36:29
16:36:44
03:11:28
03:55:15
11:58:05
11:58:24
11:58:52
19:01:21
22:15:05
13:36:57
13:37:24
13:37:54
13:38:04
13:38:31
10:21:24

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

193
466
250
39
375
369
174
449
201
156
-125
-251
353
426
209
488

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

2000-01-02
2000-01-02
2000-01-02
2000-01-03
2000-01-04
2000-01-04
2000-01-04
2000-01-04
2000-01-04
2000-01-04
2000-01-05
2000-01-05
2000-01-05
2000-01-05
2000-01-05
2000-01-06

15:33:42
16:36:27
16:36:42
03:11:27
03:55:15
11:58:03
11:58:24
11:58:51
19:01:21
22:15:03
13:36:57
13:37:24
13:37:54
13:38:03
13:38:30
10:21:24

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

193
466
250
39
375
369
174
449
201
156
-125
-251
353
426
209
488

TIME_SLICE rounds the transaction time to the 3-second slice length.
The following example uses the analytic (window) OVER() clause to return the last trading price
(the last row ordered by TickTime) in each 3-second time slice partition:
SELECT DISTINCT TIME_SLICE(TickTime, 3), LAST_VALUE(price)OVER (PARTITION BY TIME_SLICE(T
ickTime, 3)
ORDER BY TickTime ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING);

Note: If you omit the windowing clause from an analytic clause, LAST_VALUE defaults to
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW. Results can
seem non-intuitive, because instead of returning the value from the bottom of the current
partition, the function returns the bottom of the window, which continues to change along with
the current input row that is being processed. For more information, see Using Time Series
Analytics and Using SQL Analytics in the Programmer's Guide.
In the next example, FIRST_VALUE is evaluated once for each input record and the data is sorted
by ascending values. Use SELECT DISTINCT to remove the duplicates and return only one output
record per TIME_SLICE:
SELECT DISTINCT TIME_SLICE(TickTime, 3), FIRST_VALUE(price)OVER (PARTITION BY TIME_SLICE(
TickTime, 3)
ORDER BY TickTime ASC)
FROM tick_store;
TIME_SLICE
| ?column?
---------------------+---------2009-09-21 00:00:06 |
20.00
2009-09-21 00:00:09 |
30.00
2009-09-21 00:00:00 |
10.00
(3 rows)

The information output by the above query can also return MIN, MAX, and AVG of the trading prices
within each time slice.

HP Vertica Analytic Database (7.0.x)

Page 326 of 1539

SQL Reference Manual
SQL Functions

SELECT DISTINCT TIME_SLICE(TickTime, 3),FIRST_VALUE(Price) OVER (PARTITION BY TIME_SLICE(
TickTime, 3)
ORDER BY TickTime ASC),
MIN(price) OVER (PARTITION BY TIME_SLICE(TickTime, 3)),
MAX(price) OVER (PARTITION BY TIME_SLICE(TickTime, 3)),
AVG(price) OVER (PARTITION BY TIME_SLICE(TickTime, 3))
FROM tick_store;

See Also
l

Aggregate Functions

l

FIRST_VALUE [Analytic]

l

LAST_VALUE [Analytic]

l

TIMESERIES Clause

l

TS_FIRST_VALUE
TS_LAST_VALUE

l
l

TIMEOFDAY
Returns a text string representing the time of day.

Behavior Type
Volatile

Syntax
TIMEOFDAY()

Notes
TIMEOFDAY() returns the wall-clock time and advances during transactions.

Example
SELECT TIMEOFDAY();
TIMEOFDAY
------------------------------------Thu Apr 01 15:42:04.483766 2010 EDT

HP Vertica Analytic Database (7.0.x)

Page 327 of 1539

SQL Reference Manual
SQL Functions

(1 row)

TIMESTAMPADD
Adds a specified number of intervals to a TIMESTAMP or TIMESTAMPTZ. The return value
depends on the input, as follows:
l

If starttimestamp is TIMESTAMP, the return value is of type TIMESTAMP.

l

If starttimestampis TIMESTAMPTZ, the return value is of type TIMESTAMPTZ.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
TIMESTAMPADD ( datepart ,interval, starttimestamp );

HP Vertica Analytic Database (7.0.x)

Page 328 of 1539

SQL Reference Manual
SQL Functions

Parameters
datepart

(VARCHAR) Returns the number of specified datepart boundaries between
the specified startdate and enddate.
Can be an unquoted identifier, a quoted string, or an expression in parentheses,
which evaluates to the datepart as a character string.
The following table lists the valid datepartarguments.
datepart*

Abbreviation

YEAR

yy, yyyy

QUARTER

qq, q

MONTH

mm, m

DAY

dd, d, dy, dayofyear, y

WEEK

wk, ww

HOUR

hh

MINUTE

mi, n

SECOND

ss, s

MILLISECOND

ms

MICROSECOND

mcs, us

* Each of these dateparts can be prefixed with SQL_TSI_ (i.e. SQL_TSI_
YEAR, SQL_TSI_DAY, and so forth.)
starttimestamp

Start TIMESTAMP or TIMESTAMPTZ for the calculation.

Notes
l

TIMESTAMPDIFF() is an immutable function with a default type of TIMESTAMP. If
TIMESTAMPTZ is specified, the function is stable.

l

HP Vertica accepts statements written in any of the following forms:
TIMESTAMPDIFF(year, s, e);
TIMESTAMPDIFF('year', s, e);

If you use an expression, the expression must be enclosed in parentheses:

HP Vertica Analytic Database (7.0.x)

Page 329 of 1539

SQL Reference Manual
SQL Functions

DATEDIFF((expression), s, e);

l

Starting arguments are not included in the count, but end arguments are included.

Example
=> SELECT TIMESTAMPADD (SQL_TSI_MONTH, 2, ('jan 1, 2006'));
TIMESTAMPADD
-----------------------2006-03-01 00:00:00-05
(1 row)

See Also
l

Date/Time Expressions

TIMESTAMPDIFF
Returns the difference between two TIMESTAMP or TIMESTAMPTZ values, based on the
specified start and end arguments.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
TIMESTAMPDIFF ( datepart , starttimestamp , endtimestamp );

Parameters

HP Vertica Analytic Database (7.0.x)

Page 330 of 1539

SQL Reference Manual
SQL Functions

datepart

(VARCHAR) Returns the number of specified datepart boundaries between
the specified startdate and enddate.
Can be an unquoted identifier, a quoted string, or an expression in parentheses,
which evaluates to the datepart as a character string.
The following table lists the valid datepartarguments.
datepart

Abbreviation

year

yy, yyyy

quarter

qq, q

month

mm, m

day

dd, d, dy, dayofyear, y

week

wk, ww

hour

hh

minute

mi, n

second

ss, s

millisecond

ms

microsecond

mcs, us

starttimestamp

Start TIMESTAMP for the calculation.

endtimestamp

End TIMESTAMP for the calculation.

Notes
l

TIMESTAMPDIFF() is an immutable function with a default type of TIMESTAMP. If
TIMESTAMPTZ is specified, the function is stable.

l

HP Vertica accepts statements written in any of the following forms:
TIMESTAMPDIFF(year, s, e);
TIMESTAMPDIFF('year', s, e);

If you use an expression, the expression must be enclosed in parentheses:
TIMESTAMPDIFF((expression), s, e);

l

Starting arguments are not included in the count, but end arguments are included.

HP Vertica Analytic Database (7.0.x)

Page 331 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT TIMESTAMPDIFF ('YEAR',('jan 1, 2006 12:34:00'), ('jan 1, 2008 12:34:00'));
TIMESTAMPDIFF
--------------2
(1 row)

See Also
l

Date/Time Expressions

TIMESTAMP_ROUND
Rounds a TIMESTAMP to a specified format. The return value is of type TIMESTAMP.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
TIMESTAMP_ROUND ( timestamp, format )

Parameters
timestamp

TIMESTAMP or TIMESTAMPTZ input value.

HP Vertica Analytic Database (7.0.x)

Page 332 of 1539

SQL Reference Manual
SQL Functions

format

String constant that selects the precision to which truncate the input value. Valid
values for format are:
Precision

Valid values

Century

CC, SCC

Year

SYYY, YYYY, YEAR, YYY,
YY,Y

ISO Year

IYYY, IYY, IY, I

Quarter

Q

Month

MONTH, MON, MM, RM

Same day of the week as the first day of the year WW
Same day of the week as the first day of the ISO
year

IW

Same day of the week as the first day of the
month

W

Day

DDD, DD, J

Starting day of the week

DAY, DY, D

Hour

HH, HH12, HH24

Minute

MI

Second

SS

Examples
b=> SELECT TIMESTAMP_ROUND('sep 22, 2011 12:34:00', 'dy');
TIMESTAMP_ROUND
--------------------2011-09-18 00:00:00
(1 row)

TIMESTAMP_TRUNC
Truncates a TIMESTAMP. The return value is of type TIMESTAMP.

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

HP Vertica Analytic Database (7.0.x)

Page 333 of 1539

SQL Reference Manual
SQL Functions

Syntax
TIMESTAMP_TRUNC ( timestamp, format )

Parameters
timestamp

TIMESTAMP or TIMESTAMPTZ input value.

format

String constant that selects the precision to which truncate the input value. Valid
values for format are:
Precision

Valid values

Century

CC, SCC

Year

SYYY, YYYY, YEAR, YYY,
YY,Y

ISO Year

IYYY, IYY, IY, I

Quarter

Q

Month

MONTH, MON, MM, RM

Same day of the week as the first day of the year WW
Same day of the week as the first day of the ISO
year

IW

Same day of the week as the first day of the
month

W

Day

DDD, DD, J

Starting day of the week

DAY, DY, D

Hour

HH, HH12, HH24

Minute

MI

Second

SS

Examples
=> SELECT TIMESTAMP_TRUNC('sep 22, 2011 12:34:00');
TIMESTAMP_TRUNC
--------------------2011-09-22 00:00:00
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 334 of 1539

SQL Reference Manual
SQL Functions

=> SELECT TIMESTAMP_TRUNC('sep 22, 2011 12:34:00', 'dy');
TIMESTAMP_TRUNC
--------------------2011-09-18 00:00:00
(1 row)

TRANSACTION_TIMESTAMP
Returns a value of type TIMESTAMP WITH TIME ZONE representing the start of the current
transaction. TRANSACTION_TIMESTAMP is equivalent to CURRENT_TIMESTAMP except that
it does not accept a precision parameter.

Behavior Type
Stable

Syntax
TRANSACTION_TIMESTAMP()

Notes
This function returns the start time of the current transaction; the value does not change during the
transaction. 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 timestamp.

Example
SELECT TRANSACTION_TIMESTAMP();
TRANSACTION_TIMESTAMP
------------------------------2010-04-01 15:31:12.144584-04
(1 row)

See Also
l

CLOCK_TIMESTAMP

l

STATEMENT_TIMESTAMP

TRUNC [Date/Time]
Truncates a TIMESTAMP, TIMESTAMPTZ, or DATE. The return value is of type TIMESTAMP.

HP Vertica Analytic Database (7.0.x)

Page 335 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Syntax
TRUNC ([TIMESTAMP | DATE] , format )

Parameters
TIMESTAMP | DATE

TIMESTAMP or DATE input value.

format

A string constant that selects the precision to which truncate the input value.
Valid values for format are:
Precision

Valid values

Century

CC, SCC

Year

SYYY, YYYY, YEAR,
YYY, YY,Y

ISO Year

IYYY, IYY, IY, I

Quarter

Q

Month

MONTH, MON, MM, RM

Same day of the week as the first day of the WW
year
Same day of the week as the first day of the IW
ISO year
Same day of the week as the first day of the W
month
Day

DDD, DD, J

Starting day of the week

DAY, DY, D

Hour

HH, HH12, HH24

Minute

MI

Second

SS

HP Vertica Analytic Database (7.0.x)

Page 336 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT TRUNC(TIMESTAMP 'sep 22, 2011 12:34:00', 'dy');
TRUNC
--------------------2011-09-18 00:00:00
(1 row)

WEEK
Returns an INTEGER representing the week of the year into which the input value falls. A week
starts on Sunday. January 1 is always in the first week of the year.

Syntax
WEEK ( d )

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

VARCHAR, DATE, TIMESTAMP, TIMESTAMPTZ input value.

Example
=> SELECT WEEK (TIMESTAMP 'sep 22, 2011 12:34');
WEEK
-----39
(1 row)

WEEK_ISO
Returns an INTEGER from 1–53 that represents the week of the year into which the input value
falls. The return value is based on the ISO 8061 standard.
The ISO week consists of 7 days starting on Monday and ending on Sunday. The first week of the
year is the week that contains January 4.

Syntax
WEEK_ISO ( d )

HP Vertica Analytic Database (7.0.x)

Page 337 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

VARCHAR, DATE, TIMESTAMP, or TIMESTAMPTZ input value.

Examples
The following examples illustrate the different results returned by WEEK_ISO. The first shows that
December 28, 2011 falls within week 52 of the ISO calendar:
=> SELECT WEEK_ISO (TIMESTAMP 'Dec 28, 2011 10:00:00');
WEEK_ISO
---------52
(1 row)

The second example shows WEEK_ISO results for January 1, 2012. Note that, since this date falls
on a Sunday, it falls within week 52 of the ISO year:
=> SELECT WEEK_ISO (TIMESTAMP 'Jan 1, 2012 10:00:00');
WEEK_ISO
---------52
(1 row)

The third example shows WEEK_ISO results for January 2, 2012, which occurs on a Monday. This
is the first week of the year that contains a Thursday and contains January 4. The function returns
week 1.
=> SELECT WEEK_ISO (TIMESTAMP 'Jan 2, 2012 10:00:00');
WEEK_ISO
---------1

The last example shows how to combine the DAYOFWEEK_ISO, WEEK_ISO, and YEAR_ISO
functions to find the ISO day of the week, week, and year:
=> SELECT DAYOFWEEK_ISO('Jan 1, 2000'), WEEK_ISO('Jan 1, 2000'),YEAR_ISO('Jan1,2000');
DAYOFWEEK_ISO | WEEK_ISO | YEAR_ISO
---------------+----------+---------6 |
52 |
1999
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 338 of 1539

SQL Reference Manual
SQL Functions

See Also
l

YEAR_ISO

l

DAYOFWEEK_ISO

l

http://en.wikipedia.org/wiki/ISO_8601

YEAR
Returns an INTEGER representing the year portion of the input value.

Syntax
YEAR( d )

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

VARCHAR, TIMESTAMP, TIMESTAMPTZ, or INTERVAL input value.

Examples
=> SELECT YEAR ('6-9');
YEAR
-----6
(1 row)
=> SELECT YEAR (TIMESTAMP 'sep 22, 2011 12:34');
YEAR
-----2011
(1 row)
=> SELECT YEAR (INTERVAL '2-35' year to month);
YEAR
-----4
(1 row)

YEAR_ISO
Returns an INTEGER representing the year portion of the input value. The return value is based on
the ISO 8061 standard.

HP Vertica Analytic Database (7.0.x)

Page 339 of 1539

SQL Reference Manual
SQL Functions

The first week of the ISO year is the week that contains January 4.

Syntax
YEAR_ISO( d )

Behavior Type
Immutable, except for TIMESTAMPTZ arguments where it is Stable.

Parameters
d

VARCHAR, DATE, TIMESTAMP, or TIMESTAMPTZ input value.

Examples
=> SELECT YEAR_ISO (TIMESTAMP 'sep 22, 2011 12:34');
YEAR_ISO
---------2011
(1 row)

The following example shows how to combine the DAYOFWEEK_ISO, WEEK_ISO, and YEAR_
ISO functions to find the ISO day of the week, week, and year:
=> SELECT DAYOFWEEK_ISO('Jan 1, 2000'), WEEK_ISO('Jan 1, 2000'),YEAR_ISO('Jan1,2000');
DAYOFWEEK_ISO | WEEK_ISO | YEAR_ISO
---------------+----------+---------6 |
52 |
1999
(1 row)

See Also
l

WEEK_ISO

l

DAYOFWEEK_ISO

l

http://en.wikipedia.org/wiki/ISO_8601

HP Vertica Analytic Database (7.0.x)

Page 340 of 1539

SQL Reference Manual
SQL Functions

Formatting Functions
Formatting functions provide a powerful tool set for converting various data types (DATE/TIME,
INTEGER, FLOATING POINT) to formatted strings and for converting from formatted strings to
specific data types.
These functions all use a common calling convention:
l

The first argument is the value to be formatted.

l

The second argument is a template that defines the output or input format.
Note: The TO_TIMESTAMP function can take a single double precision argument.

TO_BITSTRING
Returns a VARCHAR that represents the given VARBINARY value in bitstring format.

Behavior Type
Immutable

Syntax
TO_BITSTRING ( expression )

Parameters
expression

(VARCHAR) is the string to return.

Notes
VARCHAR TO_BITSTRING(VARBINARY) converts data from binary type to character type
(where the character representation is the bitstring format). This function is the inverse of
BITSTRING_TO_BINARY:
TO_BITSTRING(BITSTRING_TO_BINARY(x)) = x)
BITSTRING_TO_BINARY(TO_BITSTRING(x)) = x)

Examples
SELECT TO_BITSTRING('ab'::BINARY(2));

HP Vertica Analytic Database (7.0.x)

Page 341 of 1539

SQL Reference Manual
SQL Functions

to_bitstring
-----------------0110000101100010
(1 row)

SELECT TO_BITSTRING(HEX_TO_BINARY('0x10'));
to_bitstring
-------------00010000
(1 row)
SELECT TO_BITSTRING(HEX_TO_BINARY('0xF0'));
to_bitstring
-------------11110000
(1 row)

See Also
l

BITCOUNT

l

BITSTRING_TO_BINARY

TO_CHAR
Converts various date/time and numeric values into text strings.

Behavior Type
Stable

Syntax
TO_CHAR ( expression [, pattern ] )

Parameters
expression

(TIMESTAMP, TIMESTAMPTZ, TIME, TIMETZ, INTERVAL, INTEGER,
DOUBLE PRECISION) specifies the value to convert.

pattern

[Optional] (CHAR or VARCHAR) specifies an output pattern string using the
Template Patterns for Date/Time Formatting and and/or Template Patterns for
Numeric Formatting.

HP Vertica Analytic Database (7.0.x)

Page 342 of 1539

SQL Reference Manual
SQL Functions

Notes
l

TO_CHAR(any) casts any type, except BINARY/VARBINARY, to VARCHAR.
The following example returns an error if you attempt to cast TO_CHAR to a binary data type:
=> SELECT TO_CHAR('abc'::VARBINARY);
ERROR: cannot cast type varbinary to varchar

l

TO_CHAR accepts TIME and TIMETZ data types as inputs if you explicitly cast TIME to
TIMESTAMP and TIMETZ to TIMESTAMPTZ.
=> SELECT TO_CHAR(TIME '14:34:06.4','HH12:MI am');
=> SELECT TO_CHAR(TIMETZ '14:34:06.4+6','HH12:MI am');

You can extract the timezone hour from TIMETZ:
SELECT EXTRACT(timezone_hour FROM TIMETZ '10:30+13:30');
date_part
----------13
(1 row)

l

Ordinary text is allowed in to_char templates and is output literally. You can put a substring in
double quotes to force it to be interpreted as literal text even if it contains pattern key words. For
example, in '"Hello Year "YYYY', the YYYY is replaced by the year data, but the single Y in
Year is not.

l

The TO_CHAR function's day-of-the-week numbering (see the 'D' template pattern) is different
from that of the EXTRACT function.

l

Given an INTERVAL type, TO_CHAR formats HH and HH12 as hours in a single day, while
HH24 can output hours exceeding a single day, for example, >24.

l

To use a double quote character in the output, precede it with a double backslash. This is
necessary because the backslash already has a special meaning in a string constant. For
example: '\\"YYYY Month\\"'

l

TO_CHAR does not support the use of V combined with a decimal point. For example: 99.9V99
is not allowed.

Examples
Expression
SELECT TO_CHAR(CURRENT_TIMESTAMP, 'Day, DD

HP Vertica Analytic Database (7.0.x)

Result
HH12:MI:SS');

'Tuesday , 06

05:39:18'

Page 343 of 1539

SQL Reference Manual
SQL Functions

SELECT TO_CHAR(CURRENT_TIMESTAMP, 'FMDay, FMDD

HH12:MI:SS');

'Tuesday, 6

SELECT TO_CHAR(TIMEtz '14:34:06.4+6','HH12:MI am'); TO_CHAR

04:34 am

SELECT TO_CHAR(-0.1, '99.99');

'

SELECT TO_CHAR(-0.1, 'FM9.99');

'-.1'

SELECT TO_CHAR(0.1, '0.9');

' 0.1'

SELECT TO_CHAR(12, '9990999.9');

'

SELECT TO_CHAR(12, 'FM9990999.9');

'0012.'

SELECT TO_CHAR(485, '999');

' 485'

SELECT TO_CHAR(-485, '999');

'-485'

SELECT TO_CHAR(485, '9 9 9');

' 4 8 5'

SELECT TO_CHAR(1485, '9,999');

' 1,485'

SELECT TO_CHAR(1485, '9G999');

' 1 485'

SELECT TO_CHAR(148.5, '999.999');

' 148.500'

SELECT TO_CHAR(148.5, 'FM999.999');

'148.5'

SELECT TO_CHAR(148.5, 'FM999.990');

'148.500'

SELECT TO_CHAR(148.5, '999D999');

' 148,500'

SELECT TO_CHAR(3148.5, '9G999D999');

' 3 148,500'

SELECT TO_CHAR(-485, '999S');

'485-'

SELECT TO_CHAR(-485, '999MI');

'485-'

SELECT TO_CHAR(485, '999MI');

'485 '

SELECT TO_CHAR(485, 'FM999MI');

'485'

SELECT TO_CHAR(485, 'PL999');

'+485'

SELECT TO_CHAR(485, 'SG999');

'+485'

SELECT TO_CHAR(-485, 'SG999');

'-485'

SELECT TO_CHAR(-485, '9SG99');

'4-85'

SELECT TO_CHAR(-485, '999PR');

'<485>'

SELECT TO_CHAR(485, 'L999');

'DM 485

SELECT TO_CHAR(485, 'RN');

'

SELECT TO_CHAR(485, 'FMRN');

'CDLXXXV'

SELECT TO_CHAR(5.2, 'FMRN');

'V'

SELECT TO_CHAR(482, '999th');

' 482nd'

HP Vertica Analytic Database (7.0.x)

05:39:18'

-.10'

0012.0'

CDLXXXV'

Page 344 of 1539

SQL Reference Manual
SQL Functions

SELECT TO_CHAR(485, '"Good number:"999');

'Good number: 485'

SELECT TO_CHAR(485.8, '"Pre:"999" Post:" .999');

'Pre: 485 Post: .800'

SELECT TO_CHAR(12, '99V999');

' 12000'

SELECT TO_CHAR(12.4, '99V999');

' 12400'

SELECT TO_CHAR(12.45, '99V9');

' 125'

SELECT TO_CHAR(-1234.567);

-1234.567

SELECT TO_CHAR('1999-12-25'::DATE);

1999-12-25

SELECT TO_CHAR('1999-12-25 11:31'::TIMESTAMP);

1999-12-25 11:31:00

SELECT TO_CHAR('1999-12-25 11:31 EST'::TIMESTAMPTZ);

1999-12-25 11:31:00-05

SELECT TO_CHAR('3 days 1000.333 secs'::INTERVAL);

3 days 00:16:40.333

TO_DATE
Converts a string value to a DATE type.

Behavior Type
Stable

Syntax
TO_DATE ( expression , pattern )

Parameters
expression

(CHAR or VARCHAR) specifies the value to convert.

pattern

(CHAR or VARCHAR) specifies an output pattern string using the Template
Patterns for Date/Time Formatting and/or Template Patterns for Numeric
Formatting.

Input Value Considerations
The TO_DATE function requires a CHAR or VARCHAR expression. For other input types, use
TO_CHAR to perform an explicit cast to a CHAR or VARCHAR before using this function.

Notes
l

To use a double quote character in the output, precede it with a double backslash. This is
necessary because the backslash already has a special meaning in a string constant. For

HP Vertica Analytic Database (7.0.x)

Page 345 of 1539

SQL Reference Manual
SQL Functions

example: '\\"YYYY Month\\"'
n

n

TO_TIMESTAMP, TO_TIMESTAMP_TZ, and TO_DATE skip multiple blank spaces in the
input string if the FX option is not used. FX must be specified as the first item in the template.
For example:
o

For example TO_TIMESTAMP('2000

JUN', 'YYYY MON') is correct.

o

TO_TIMESTAMP('2000 JUN', 'FXYYYY MON') returns an error, because TO_
TIMESTAMP expects one space only.

The YYYY conversion from string to TIMESTAMP or DATE has a restriction if you use a year
with more than four digits. You must use a non-digit character or template after YYYY,
otherwise the year is always interpreted as four digits. For example (with the year 20000):
TO_DATE('200001131', 'YYYYMMDD') is interpreted as a four-digit year
Instead, use a non-digit separator after the year, such as TO_DATE('20000-1131', 'YYYYMMDD') or TO_DATE('20000Nov31', 'YYYYMonDD').

n

In conversions from string to TIMESTAMP or DATE, the CC field is ignored if there is a YYY,
YYYY or Y,YYY field. If CC is used with YY or Y then the year is computed as (CC–1)
*100+YY.

Examples
SELECT TO_DATE('13 Feb 2000', 'DD Mon YYYY');
to_date
-----------2000-02-13
(1 row)

See Also
l

Template Pattern Modifiers for Date/Time Formatting

TO_HEX
Returns a VARCHAR or VARBINARY representing the hexadecimal equivalent of a number.

Behavior Type
Immutable

Syntax
TO_HEX ( number )

HP Vertica Analytic Database (7.0.x)

Page 346 of 1539

SQL Reference Manual
SQL Functions

Parameters
number

(INTEGER) is the number to convert to hexadecimal

Notes
VARCHAR TO_HEX(INTEGER) and VARCHAR TO_HEX(VARBINARY) are similar. The
function converts data from binary type to character type (where the character representation is in
hexadecimal format). This function is the inverse of HEX_TO_BINARY.
TO_HEX(HEX_TO_BINARY(x)) = x);
HEX_TO_BINARY(TO_HEX(x)) = x);

Examples
SELECT TO_HEX(123456789);
TO_HEX
--------75bcd15
(1 row)

For VARBINARY inputs, the returned value is not preceded by "0x". For example:
SELECT TO_HEX('ab'::binary(2));
TO_HEX
-------6162
(1 row)

TO_TIMESTAMP
Converts a string value or a UNIX/POSIX epoch value to a TIMESTAMP type.

Behavior Type
Stable

Syntax
TO_TIMESTAMP ( expression, pattern )TO_TIMESTAMP ( unix-epoch )

HP Vertica Analytic Database (7.0.x)

Page 347 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

(CHAR or VARCHAR) is the string to convert

pattern

(CHAR or VARCHAR) specifies an output pattern string using the Template
Patterns for Date/Time Formatting and/or Template Patterns for Numeric
Formatting.

unix-epoch

(DOUBLE PRECISION) specifies some number of seconds elapsed since midnight
UTC of January 1, 1970, not counting leap seconds. INTEGER values are implicitly
cast to DOUBLE PRECISION.

Notes
l

For more information about UNIX/POSIX time, see Wikipedia.

l

Millisecond (MS) and microsecond (US) values in a conversion from string to TIMESTAMP are
used as part of the seconds after the decimal point. For example TO_TIMESTAMP('12:3',
'SS:MS') is not 3 milliseconds, but 300, because the conversion counts it as 12 + 0.3 seconds.
This means for the format SS:MS, the input values 12:3, 12:30, and 12:300 specify the same
number of milliseconds. To get three milliseconds, use 12:003, which the conversion counts as
12 + 0.003 = 12.003 seconds.
Here is a more complex example: TO_TIMESTAMP('15:12:02.020.001230',
'HH:MI:SS.MS.US') is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230
microseconds = 2.021230 seconds.

l

To use a double quote character in the output, precede it with a double backslash. This is
necessary because the backslash already has a special meaning in a string constant. For
example: '\\"YYYY Month\\"'

l

TZ/tz are not supported patterns for the TO_TIMESTAMP function; for example, the following
command returns an error:
SELECT TO_TIMESTAMP('01-01-01 01:01:01+03:00','DD-MM-YY HH24:MI:SSTZ');
ERROR: "TZ"/"tz" not supported

n

n

TO_TIMESTAMP, TO_TIMESTAMP_TZ, and TO_DATE skip multiple blank spaces in the
input string if the FX option is not used. FX must be specified as the first item in the template.
For example:
o

For example TO_TIMESTAMP('2000

JUN', 'YYYY MON') is correct.

o

TO_TIMESTAMP('2000 JUN', 'FXYYYY MON') returns an error, because TO_
TIMESTAMP expects one space only.

The YYYY conversion from string to TIMESTAMP or DATE has a restriction if you use a year

HP Vertica Analytic Database (7.0.x)

Page 348 of 1539

SQL Reference Manual
SQL Functions

with more than four digits. You must use a non-digit character or template after YYYY,
otherwise the year is always interpreted as four digits. For example (with the year 20000):
TO_DATE('200001131', 'YYYYMMDD') is interpreted as a four-digit year
Instead, use a non-digit separator after the year, such as TO_DATE('20000-1131', 'YYYYMMDD') or TO_DATE('20000Nov31', 'YYYYMonDD').
n

In conversions from string to TIMESTAMP or DATE, the CC field is ignored if there is a YYY,
YYYY or Y,YYY field. If CC is used with YY or Y then the year is computed as (CC–1)
*100+YY.

Examples
=> SELECT TO_TIMESTAMP('13 Feb 2009', 'DD Mon YYY');
TO_TIMESTAMP
--------------------1200-02-13 00:00:00
(1 row)
=> SELECT TO_TIMESTAMP(200120400);
TO_TIMESTAMP
--------------------1976-05-05 01:00:00
(1 row)

See Also
l

Template Pattern Modifiers for Date/Time Formatting

TO_TIMESTAMP_TZ
Converts a string value or a UNIX/POSIX epoch value to a TIMESTAMP WITH TIME ZONE type.

Behavior Type
Immutable if single argument form, Stable otherwise.

Syntax
TO_TIMESTAMP_TZ ( expression, pattern )TO_TIMESTAMP ( unix-epoch )

Parameters
expression

(CHAR or VARCHAR) is the string to convert

HP Vertica Analytic Database (7.0.x)

Page 349 of 1539

SQL Reference Manual
SQL Functions

pattern

(CHAR or VARCHAR) specifies an output pattern string using the Template
Patterns for Date/Time Formatting and/or Template Patterns for Numeric
Formatting.

unix-epoch

(DOUBLE PRECISION) specifies some number of seconds elapsed since midnight
UTC of January 1, 1970, not counting leap seconds. INTEGER values are implicitly
cast to DOUBLE PRECISION.

Notes
l

For more information about UNIX/POSIX time, see Wikipedia.

l

Millisecond (MS) and microsecond (US) values in a conversion from string to TIMESTAMP are
used as part of the seconds after the decimal point. For example TO_TIMESTAMP('12:3',
'SS:MS') is not 3 milliseconds, but 300, because the conversion counts it as 12 + 0.3 seconds.
This means for the format SS:MS, the input values 12:3, 12:30, and 12:300 specify the same
number of milliseconds. To get three milliseconds, use 12:003, which the conversion counts as
12 + 0.003 = 12.003 seconds.
Here is a more complex example: TO_TIMESTAMP('15:12:02.020.001230',
'HH:MI:SS.MS.US') is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230
microseconds = 2.021230 seconds.

l

To use a double quote character in the output, precede it with a double backslash. This is
necessary because the backslash already has a special meaning in a string constant. For
example: '\\"YYYY Month\\"'
n

n

TO_TIMESTAMP, TO_TIMESTAMP_TZ, and TO_DATE skip multiple blank spaces in the
input string if the FX option is not used. FX must be specified as the first item in the template.
For example:
o

For example TO_TIMESTAMP('2000

JUN', 'YYYY MON') is correct.

o

TO_TIMESTAMP('2000 JUN', 'FXYYYY MON') returns an error, because TO_
TIMESTAMP expects one space only.

The YYYY conversion from string to TIMESTAMP or DATE has a restriction if you use a year
with more than four digits. You must use a non-digit character or template after YYYY,
otherwise the year is always interpreted as four digits. For example (with the year 20000):
TO_DATE('200001131', 'YYYYMMDD') is interpreted as a four-digit year
Instead, use a non-digit separator after the year, such as TO_DATE('20000-1131', 'YYYYMMDD') or TO_DATE('20000Nov31', 'YYYYMonDD').

n

In conversions from string to TIMESTAMP or DATE, the CC field is ignored if there is a YYY,
YYYY or Y,YYY field. If CC is used with YY or Y then the year is computed as (CC–1)
*100+YY.

HP Vertica Analytic Database (7.0.x)

Page 350 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT TO_TIMESTAMP_TZ('13 Feb 2009', 'DD Mon YYY');
TO_TIMESTAMP_TZ
-----------------------1200-02-13 00:00:00-05
(1 row)
=> SELECT TO_TIMESTAMP_TZ(200120400);
TO_TIMESTAMP_TZ
-----------------------1976-05-05 01:00:00-04
(1 row)

See Also
l

Template Pattern Modifiers for Date/Time Formatting

TO_NUMBER
Converts a string value to DOUBLE PRECISION.

Behavior Type
Stable

Syntax
TO_NUMBER ( expression, [ pattern ] )

Parameters
expression

(CHAR or VARCHAR) specifies the string to convert.

pattern

(CHAR or VARCHAR) Optional parameter specifies an output pattern string using
the Template Patterns for Date/Time Formatting and/or Template Patterns for
Numeric Formatting. If omitted, function returns a floating point.

Notes
To use a double quote character in the output, precede it with a double backslash. This is
necessary because the backslash already has a special meaning in a string constant. For example:
'\\"YYYY Month\\"'

HP Vertica Analytic Database (7.0.x)

Page 351 of 1539

SQL Reference Manual
SQL Functions

Examples
SELECT TO_CHAR(2009, 'rn'), TO_NUMBER('mmix', 'rn');
TO_CHAR
| TO_NUMBER
-----------------+----------mmix |
2009
(1 row)

It the pattern parameter is omitted, the function returns a floating point.
SELECT TO_NUMBER('-123.456e-01');
TO_NUMBER
-----------12.3456

HP Vertica Analytic Database (7.0.x)

Page 352 of 1539

SQL Reference Manual
SQL Functions

Template Patterns for Date/Time Formatting
In an output template string (for TO_CHAR), there are certain patterns that are recognized and
replaced with appropriately-formatted data from the value to be formatted. Any text that is not a
template pattern is copied verbatim. Similarly, in an input template string (for anything other than
TO_CHAR), template patterns identify the parts of the input data string to be looked at and the values
to be found there.
Note: HP Vertica uses the ISO 8601:2004 style for date/time fields in HP Vertica *.log files.
For example,
2008-09-16 14:40:59.123 TM Moveout:0x2aaaac002180 [Txn] 
Certain modifiers can be applied to any template pattern to alter its behavior as described in
Template Pattern Modifiers for Date/Time Formatting.
Pattern

Description

HH

Hour of day (00-23)

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)

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

HP Vertica Analytic Database (7.0.x)

Page 353 of 1539

SQL Reference Manual
SQL Functions

Pattern

Description

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)

Mon

Abbreviated mixed-case month name (3 chars)

mon

Abbreviated lowercase month name (3 chars)

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)

Dy

Abbreviated mixed-case day name (3 chars)

dy

Abbreviated lowercase day name (3 chars)

DDD

Day of year (001-366)

DD

Day of month (01-31) for TIMESTAMP
Note: For INTERVAL, DD is day of year (001-366) because day
of month is undefined.

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)

HP Vertica Analytic Database (7.0.x)

Page 354 of 1539

SQL Reference Manual
SQL Functions

Pattern

Description

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)

Template Pattern Modifiers for Date/Time Formatting
Certain modifiers can be applied to any template pattern to alter its behavior. For example, FMMonth
is the Month pattern with the FM modifier.
Modifier

Description

AM

Time is before 12:00

AT

Ignored

JULIAN, JD, J

Next field is Julian Day

FM prefix

Fill mode (suppress padding blanks and zeros)
For example: FMMonth
Note: The FM modifier suppresses leading zeros and trailing blanks that would
otherwise be added to make the output of a pattern fixed width.

FX prefix

Fixed format global option
For example: FX Month DD Day

ON

Ignored

PM

Time is on or after 12:00

T

Next field is time

TH suffix

Uppercase ordinal number suffix
For example: DDTH

th suffix

Lowercase ordinal number suffix
For example: DDth

TM prefix

Translation mode (print localized day and month names based on lc_messages).
For example: TMMonth

HP Vertica Analytic Database (7.0.x)

Page 355 of 1539

SQL Reference Manual
SQL Functions

Template Patterns for Numeric Formatting
Pattern

Description

9

Value with the specified number of digits

0

Value with leading zeros

. (period)

Decimal point

, (comma) Group (thousand) separator
PR

Negative value in angle brackets

S

Sign anchored to number (uses locale)

L

Currency symbol (uses locale)

D

Decimal point (uses locale)

G

Group separator (uses locale)

MI

Minus sign in specified position (if number < 0)

PL

Plus sign in specified position (if number > 0)

SG

Plus/minus sign in specified position

RN

Roman numeral (input between 1 and 3999)

TH or th

Ordinal number suffix

V

Shift specified number of digits (see notes)

EEEE

Scientific notation (not implemented yet)

Usage
l

A sign formatted using SG, PL, or MI is not anchored to the number; for example:
n

TO_CHAR(-12, 'S9999') produces ' -12'

n

TO_CHAR(-12, 'MI9999') produces '- 12'

l

9 results in a value with the same number of digits as there are 9s. If a digit is not available it
outputs a space.

l

TH does not convert values less than zero and does not convert fractional numbers.

l

V effectively multiplies the input values by 10^n, where n is the number of digits following V.
TO_CHAR does not support the use of V combined with a decimal point. For example: 99.9V99
is not allowed.

HP Vertica Analytic Database (7.0.x)

Page 356 of 1539

SQL Reference Manual
SQL Functions

Geospatial Package SQL Functions
The HP Vertica Geospatial package contains a suite of geospatial SQL functions you can install to
report on and analyze geographic location data.

To Install the Geospatial package:
Run the install.sh script that appears in the /opt/vertica/packages/geospatial directory.
Note: If you choose to install the Geospatial package in a directory other than the default, be
sure to set the GEOSPATIAL_HOME environment variable to reflect the correct directory.

Contents of the Geospatial Package
When you installed HP Vertica, the RPM saved the Geospatial package files here:
/opt/vertica/packages/geospatial
This directory contains these files:
install.sh Installs the Geospatial package.
readme.txt Contains instructions for installing the package.
This directory also contains these directories:
/src

Contains this file:
l

geospatial.sql—This file contains all the functions that are installed with the
package. The file describes the calculations used for each function, and
provides examples. This file also contains links to helpful sites that provide more
information about standards and calculations.

/examples Contains this file:
l

regions_demo.sql—This file is a demo, intended to illustrate a simple use
case: determine the New England state in which a given point lies.

Using Geospatial Package SQL Functions
For high-level descriptions of all of the functions included in the package, see Geospatial SQL
Functions. For more detailed information about each function and for links to other useful
information, see /opt/vertica/packages/geospatial/src/geospatial.sql.

HP Vertica Analytic Database (7.0.x)

Page 357 of 1539

SQL Reference Manual
SQL Functions

Using Built-In HP Vertica Functions for Geospatial
Analysis
Four mathematical functions, automatically installed with HP Vertica, perform geospatial
operations:
l

DEGREES

l

DISTANCE

l

DISTANCEV

l

RADIANS

These functions are not part of the Vertica Geospatial Package; they are installed with HP Vertica.

Geospatial SQL Functions
With the Geospatial Package, HP Vertica provides SQL functions that let you find geographic
constants to use in your calculations and analysis. These functions appear in the file
/opt/vertica/packages/geospatial/src/geospatial.sql.
You can use these functions as they are supplied; you can also edit the geospatial.sql file to
change the calculations according to your needs. If you do modify the geospatial functions, be sure
to save a copy of your changes in a private location so that your changes are not lost if you upgrade
your HP Vertica installation. Note that an upgrade does not overwrite any functions already loaded
in your database; the upgrade only overwrites only the .sql file containing the function definitions.
These functions measure distances in kilometers and angles in fractional degrees, unless stated
otherwise.
Of the several possible definitions of latitude, the geodetic latitude is most commonly used; and this
is what the HP Vertica Geospatial Package uses. Latitude goes from +90 degrees at the North Pole
to –90 at the South Pole. Longitude 0 is near Greenwich, England. It increases going east to +180
degrees, and decreases going west to –180 degrees. True bearings are measured clockwise from
north. For more information, see: http://en.wikipedia.org/wiki/Latitude.

WGS-84 SQL Functions
The following functions return constants determined by the World Geodetic System (WGS)
standard, WGS-84.
l

WGS84_a()

l

WGS84_b()

l

WGS84_e2()

HP Vertica Analytic Database (7.0.x)

Page 358 of 1539

SQL Reference Manual
SQL Functions

l

WGS84_f()

l

WGS84_if()

Earth Radius, Radius of Curvature, and Bearing SQL
Functions
These functions return the earth's radius, radius of curvature, and bearing values.
l

RADIUS_r(lat)

l

WGS84_r1()

l

RADIUS_SI()

l

RADIUS_M(lat)

l

RADIUS_N (lat)

l

RADIUS_Ra (lat)

l

RADIUS_Rv (lat)

l

RADIUS_Rc (lat,bearing)

l

BEARING (lat1,lon1,lat2,lon2)

l

RADIUS_LON (lat)

ECEF Conversion SQL Functions
The following functions convert values to Earth-Centered, Earth-Fixed (ECEF) values. The ECEF
system represents positions on x, y, and z axes in meters. (0,0,0) is the center of the earth; x is
toward latitude 0, longitude 0; y is toward latitude 0, longitude 90 degrees; and z is toward the North
Pole. The height above mean sea level (h) is also in meters.
l

ECEF_x (lat,lon,h)

l

ECEF_y (lat,lon,h)

l

ECEF_z (lat,lon,h)

l

ECEF_chord (lat1,lon1,h1,lat2,lon2,h2)

l

CHORD_TO_ARC (chord)

HP Vertica Analytic Database (7.0.x)

Page 359 of 1539

SQL Reference Manual
SQL Functions

Bounding Box SQL Functions
These functions determine whether points are within a bounding box, a rectangular area whose
edges are latitude and longitude lines. Bounding box methods allow you to narrow your focus, and
they work best on HP Vertica projections that are sorted by latitude, or by region (such as swtate)
and then by latitude. These methods also work on projections sorted by longitude.
l

BB_WITHIN (lat,lon,llat,llon,ulat,rlon)

l

LAT_WITHIN (lat,lat0,d)

l

LON_WITHIN (lon,lat0,lon0,d)

l

LL_WITHIN (lat,lon,lat0,lon0,d)

l

DWITHIN (lat,lon,lat0,lon0,d)

l

LLD_WITHIN (lat,lon,lat0,lon0,d)

l

ISLEFT (x0,y0,x1,y1,x2,y2)

l

RAYCROSSING (x0,y0,x1,y1,x2,y2)

Miles/Kilometer Conversion SQL Functions
These functions convert miles to kilometers and kilometers to miles:
l

MILES2KM (miles)

l

KM2MILES (km)

BB_WITHIN
Determines whether a point (lat, lon) falls within a bounding box defined by its lower-left and upperright corners. The return value has the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
BB_WITHIN (lat,lon,llat,llon,ulat,rlon)

HP Vertica Analytic Database (7.0.x)

Page 360 of 1539

SQL Reference Manual
SQL Functions

Parameters
lat

A value of type DOUBLE PRECISION indicating the latitude of a given point.

lon

A value of type DOUBLE PRECISION indicating the longitude of a given point.

llat

A value of type DOUBLE PRECISION indicating the latitude used to define the lower-left
corner of the bounding box.

llon

A value of type DOUBLE PRECISION indicating the longitude used to define the lowerleft corner of the bounding box.

ulat

A value of type DOUBLE PRECISION indicating the latitude used to define the upper-right
corner of the bounding box.

rlon

A value of type DOUBLE PRECISION indicating the longitude used in defining the upperright corner of the bounding box.

Example
The following example determines that the point (14,30) is not contained in the bounding box
defined by (23.0,45) and (13,37):
=> SELECT BB_WITHIN(14,30,23.0,45,13,37);
BB_WITHIN
----------f
(1 row)

The following example determines that the point (14,30) is contained in the bounding box defined by
(13.0,45) and (23,37).
=> SELECT BB_WITHIN(14,30,13.0,45,23,37);
BB_WITHIN
----------t
(1 row)

BEARING
Returns the approximate bearing from a starting point to an ending point, in degrees. It assumes a
flat earth and is useful only for short distances. The return value has the type DOUBLE
PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

HP Vertica Analytic Database (7.0.x)

Page 361 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
BEARING (lat1,lon1,lat2,lon2)

Parameters
lat1

A value of type DOUBLE PRECISION indicating latitude of the starting point.

lon1

A value of type DOUBLE PRECISION indicating longitude of the starting point.

lat2

A value of type DOUBLE PRECISION indicating latitude of the ending point.

lon2

A value of type DOUBLE PRECISION indicating longitude of the ending point.

Example
The following examples calculate the bearing, in degrees, from point (45,13) to (33,3) and from point
(33,3) to (45,13):
=> SELECT BEARING(45,13,33,3);
BEARING
-------------------140.194428907735
(1 row)
=> SELECT BEARING(33,3,45,13);
BEARING
-----------------39.8055710922652
(1 row)

CHORD_TO_ARC
Converts a chord (the straight line between two points) in meters to a geodesic arc length, also in
meters. The return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 362 of 1539

SQL Reference Manual
SQL Functions

Syntax
CHORD_TO_ARC (chord)

Parameters
chord

A value of type DOUBLE PRECISION indicating chord length (in meters)

Example
The following examples convert the length of a chord to the length of its geodesic arc:
=> SELECT CHORD_TO_ARC(120);
CHORD_TO_ARC
-----------------120.000000001774
(1 row)
=> SELECT CHORD_TO_ARC(12000);
CHORD_TO_ARC
-----------------12000.0017738474
(1 row)
=> SELECT CHORD_TO_ARC(1200000);
CHORD_TO_ARC
-----------------1201780.96402514
(1 row)

DWITHIN
Determines whether a point (lat,lon) is within a circle of radius d kilometers centered at a given point
(lat0,lon0). The return value has the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
DWITHIN (lat,lon,lat0,lon0,d)

HP Vertica Analytic Database (7.0.x)

Page 363 of 1539

SQL Reference Manual
SQL Functions

Parameters
lat

A value of type DOUBLE PRECISION indicating a given latitude.

lon

A value of type DOUBLE PRECISION indicating a given longitude.

lat0

A value of type DOUBLE PRECISION indicating the latitude of the center point of a circle.

lon0

A value of type DOUBLE PRECISION indicating the longitude of the center point of a
circle.

d

A value of type DOUBLE PRECISION indicating the radius of the circle (in kilometers).

Example
The following examples determine that the point (13.6,43.5) is within 3880–3890 kilometers of the
radius of a circle centered at (48.5,45.5):
=> SELECT DWITHIN(13.6,43.5,48.5,45.5,3880);
DWITHIN
--------f
(1 row)
=> SELECT DWITHIN(13.6,43.5,48.5,45.5,3890);
DWITHIN
--------t
(1 row)

ECEF_CHORD
Calculates the distance in meters between two ECEF coordinates. The return value has the type
DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
ECEF_CHORD (lat1,lon1,h1,lat2,lon2,h2)

HP Vertica Analytic Database (7.0.x)

Page 364 of 1539

SQL Reference Manual
SQL Functions

Parameters
lat

A value of type DOUBLE PRECISION indicating the latitude of one end point of the line.

lon1

A value of type DOUBLE PRECISION indicating the longitude of one end point of the line.

h1

A value of type DOUBLE PRECISION indicating the height above sea level (in meters) of
one end point of the line.

lat2

A value of type DOUBLE PRECISION indicating the latitude of one end point of the line.

lon2

A value of type DOUBLE PRECISION indicating the longitude of one end point of the line.

h2

A value of type DOUBLE PRECISION indicating the height of one end point of the line.

Example
The following example calculates the distance in meters between the ECEF coordinates (12,10.0,14) and (12,-10,17):
=> SELECT ECEF_chord (-12,10.0,14,12,-10,17);
ECEF_chord
-----------------3411479.93992789
(1 row)

ECEF_x
Converts a given latitude, longitude, and height into the ECEF x coordinate in meters. The return
value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
ECEF_x (lat,lon,h)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude.

HP Vertica Analytic Database (7.0.x)

Page 365 of 1539

SQL Reference Manual
SQL Functions

lon

A value of type DOUBLE PRECISION indicating longitude.

h

A value of type DOUBLE PRECISION indicating height.

Example
The following example calculates the ECEF x coordinate in meters for the point (-12,13.2,0):
=> SELECT ECEF_x(-12,13.2,0);
ECEF_x
-----------------6074803.56179976
(1 row)

ECEF_y
Converts a given latitude, longitude, and height into the ECEF y coordinate in meters. The return
value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
ECEF_y (lat,lon,h)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude.

lon

A value of type DOUBLE PRECISION indicating longitude.

h

A value of type DOUBLE PRECISION indicating height.

Example
The following example calculates the ECEF y coordinate in meters for the point (12.0,-14.2,12):
=> SELECT ECEF_y(12.0,-14.2,12);
ECEF_y
-------------------

HP Vertica Analytic Database (7.0.x)

Page 366 of 1539

SQL Reference Manual
SQL Functions

-1530638.12327962
(1 row)

ECEF_z
Converts a given latitude, longitude, and height into the ECEF z coordinate in meters. The return
value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
ECEF_Z (lat,lon,h)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude.

lon

A value of type DOUBLE PRECISION indicating longitude.

h

A value of type DOUBLE PRECISION indicating height.

Example
The following example calculates the ECEF z coordinate in meters for the point (12.0,-14.2,12):
=> SELECT ECEF_z(12.0,-14.2,12);
ECEF_z
-----------------1317405.02616989
(1 row)

ISLEFT
Determines whether a given point is anywhere to the left of a directed line that goes though two
specified points. The return value has the type FLOAT and has the following possible values:
l

> 0: The point is to the left of the line.

l

= 0: The point is on the line.

HP Vertica Analytic Database (7.0.x)

Page 367 of 1539

SQL Reference Manual
SQL Functions

l

< 0: The point is to the right of the line.

This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
ISLEFT (x0,y0,x1,y1,x2,y2)

Parameters
x0

A value of type DOUBLE PRECISION indicating the latitude of the first point through which
the directed line passes.

y0

A value of type DOUBLE PRECISION indicating the longitude of the the first point through
which the directed line passes.

x1

A value of type DOUBLE PRECISION indicating the latitude of the second point through
which the directed line passes.

y1

A value of type DOUBLE PRECISION indicating the longitude of the the second point
through which the directed line passes.

x2

A value of type DOUBLE PRECISION indicating the latitude of the point whose position you
are evaluating.

y2

A value of type DOUBLE PRECISION indicating the longitude of a whose position you are
evaluating.

Example
The following example determines that (0,0) is to the left of the line that passes through (1,1) and
(2,3):
=> SELECT ISLEFT(1,1,2,3,0,0);
ISLEFT
-------1
(1 row)

KM2MILES
Converts a value from kilometers to miles. The return value is of type DOUBLE PRECISION.

HP Vertica Analytic Database (7.0.x)

Page 368 of 1539

SQL Reference Manual
SQL Functions

This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
KM2MILES (km)

Parameters
km

A value of type DOUBLE PRECISION indicating the number of kilometers you want to
convert.

Example
The following example converts 1.0 kilometers to miles:
=> SELECT KM2MILES(1.0);
KM2MILES
------------------0.621371192237334
(1 row)

LAT_WITHIN
Determines whether a certain latitude (lat) is within d kilometers of another latitude point (lat0),
independent of longitude. The return value has the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
LAT_WITHIN (lat,lat0,d)

HP Vertica Analytic Database (7.0.x)

Page 369 of 1539

SQL Reference Manual
SQL Functions

Parameters
lat

A value of type DOUBLE PRECISION indicating a given latitude.

lat0

A value of type DOUBLE PRECISION indicating the latitude of the point to which you are
comparing the first latitude.

d

A value of type DOUBLE PRECISION indicating the number of kilometers that
determines the range you are evaluating.

Example
The following examples determine that latitude 12 is between 220 and 230 kilometers of latitude
14.0:
=> SELECT LAT_WITHIN(12,14.0,220);
LAT_WITHIN
-----------f
(1 row)
=> SELECT LAT_WITHIN(12,14.0,230);
LAT_WITHIN
-----------t
(1 row)

LL_WITHIN
Determines whether a point (lat, lon) is within a bounding box whose sides are 2d kilometers long,
centered at a given point (lat0, lon0). The return value has the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
LL_WITHIN (lat,lon,lat0,lon0,d);

Parameters
lat

A value of type DOUBLE PRECISION indicating a given latitude.

HP Vertica Analytic Database (7.0.x)

Page 370 of 1539

SQL Reference Manual
SQL Functions

lon

A value of type DOUBLE PRECISION indicating a given longitude.

lat0

A value of type DOUBLE PRECISION indicating the latitude of the center point of the
bounding box.

lon0

A value of type DOUBLE PRECISION indicating the longitude of the center point of the
bounding box.

d

A value of type DOUBLE PRECISION indicating the length of half the side of the box.

Example
The following examples determine that the point (16,15) is within a bounding box centered at (12,13)
whose sides are between 880 and 890 kilometers long:
=> SELECT LL_WITHIN(16,15,12,13.0,440);
LL_WITHIN
----------f
(1 row)
=> SELECT LL_WITHIN(16,15,12,13.0,445);
LL_WITHIN
----------t
(1 row)

LLD_WITHIN
Determines whether a point (lat,lon) is within a circle of radius d kilometers centered at a given point
(lat0,lon0). LLD_WITHIN is a faster, but less accurate version of DWITHIN. The return value has
the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
LLD_WITHIN (lat,lon,lat0,lon0,d)

Parameters
lat

A value of type DOUBLE PRECISION indicating a given latitude.

HP Vertica Analytic Database (7.0.x)

Page 371 of 1539

SQL Reference Manual
SQL Functions

lon

A value of type DOUBLE PRECISION indicating a given longitude.

lat0

A value of type DOUBLE PRECISION indicating the latitude of the center point of a circle.

lon0

A value of type DOUBLE PRECISION indicating the longitude of the center point of a
circle.

d

A value of type DOUBLE PRECISION indicating the radius of the circle (in kilometers).

Example
The following examples determine that the point (13.6,43.5) is within a circle centered at (48.5,45.5)
whose radius is between 3800 and 3900 kilometers long:
=> SELECT LLD_WITHIN(13.6,43.5,48.5,45.5,3800);
LLD_WITHIN
-----------f
(1 row)
=> SELECT LLD_WITHIN(13.6,43.5,48.5,45.5,3900);
LLD_WITHIN
-----------t
(1 row)

LON_WITHIN
Determines whether a longitude (lon) is within d kilometers of a given point (lat0, lon0). The return
value has the type BOOLEAN.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
LON_WITHIN (lon,lat0,lon0,d)

Parameters
lon

A value of type DOUBLE PRECISION indicating a given longitude.

lat0

A value of type DOUBLE PRECISION indicating the latitude of the point to which you
want to compare the lon value.

HP Vertica Analytic Database (7.0.x)

Page 372 of 1539

SQL Reference Manual
SQL Functions

lon0

A value of type DOUBLE PRECISION indicating the longitude of the point to which you
want to compare the lon value.

d

A value of type DOUBLE PRECISION indicating the distance, in kilometers, that defines
your range.

Example
The following examples determine that the longitude 15 is between 1600 and 1700 kilometers from
the point (16,0):
=> SELECT LON_WITHIN(15,16,0,1600);
LON_WITHIN
-----------f
(1 row)
=> SELECT LON_WITHIN(15,16,0,1700);
LON_WITHIN
-----------t
(1 row)

MILES2KM
Converts a value from miles to kilometers. The return value is of type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
MILES2KM (miles)

Parameters
miles

A value of type DOUBLE PRECISION indicating the number of miles you want to
convert.

Example
The following example converts 1.0 miles to kilometers:

HP Vertica Analytic Database (7.0.x)

Page 373 of 1539

SQL Reference Manual
SQL Functions

=> SELECT MILES2KM(1.0);
MILES2KM
---------1.609344
(1 row)

RADIUS_LON
Returns the radius of the circle of longitude in kilometers at a given latitude. The return value has
the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_LON (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
radius.

Example
The following example calculates the circle of longitude in kilometers at a latitude of 45:
=> SELECT RADIUS_LON(45);
RADIUS_LON
--------------------4517.59087884893
(1 row)

RADIUS_M
Returns the earth's radius of curvature in kilometers along the meridian at the given latitude. The
return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

HP Vertica Analytic Database (7.0.x)

Page 374 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
RADIUS_M (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
radius of curvature.

Example
The following example calculates the earth's radius of curvature in kilometers along the meridian at
latitude –90 (the South Pole):
=> SELECT RADIUS_M(-90);
RADIUS_M
----------------6399.5936257585
(1 row)

RADIUS_N
Returns the earth's radius of curvature in kilometer normal to the meridian at a given latitude. The
return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_N (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
radius of curvature.

HP Vertica Analytic Database (7.0.x)

Page 375 of 1539

SQL Reference Manual
SQL Functions

Example
The following example calculates the earth's radius of curvature in kilometers normal to the
meridian at latitude –90 (the South Pole):
=> SELECT RADIUS_N(-90);
RADIUS_N
-----------------6399.59362575849
(1 row)

RADIUS_R
Returns the WGS-84 radius of the earth (to the center of mass) in kilometers at a given latitude. The
return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_R (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
earth's radius.

Example
The following example calculates the WGS-84 radius of the earth in kilometers at latitude –90 (the
South Pole):
=> SELECT RADIUS_R(-90);
RADIUS_R
-----------------6356.75231424518
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 376 of 1539

SQL Reference Manual
SQL Functions

RADIUS_Ra
Returns the earth's average radius of curvature in kilometers at a given latitude. This function is the
geometric mean of RADIUS_M and RADIUS_N. (RADIUS_Rv is a faster approximation of this
function.)
The return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_Ra (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
radius of curvature.

Example
The following example calculates the earth's average radius of curvature in kilometers at latitude –
90 (the South Pole):
=> SELECT RADIUS_Ra(-90);
RADIUS_Ra
-----------------6399.59362575849
(1 row)

RADIUS_Rc
Returns the earth's radius of curvature in kilometers at a given bearing measured clockwise from
north. The return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 377 of 1539

SQL Reference Manual
SQL Functions

Syntax
RADIUS_Rc (lat, bearing)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to
measure the radius of curvature.

bearing

A value of type DOUBLE PRECISION indicating a given bearing.

Example
The following example measures the earth's radius of curvature in kilometers at latitude 45, with a
bearing of 45 measured clockwise from north:
=> SELECT RADIUS_Rc(45,45);
RADIUS_Rc
-----------------6378.09200754445
(1 row)

RADIUS_Rv
Returns the earth's average radius of curvature in kilometers at a given latitude. This value is the
geometric mean of RADIUS_M and RADIUS_N. This function is a fast approximation of RADIUS_
Ra. The return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_Rv (lat)

Parameters
lat

A value of type DOUBLE PRECISION indicating latitude at which you want to measure the
radius of curvature.

HP Vertica Analytic Database (7.0.x)

Page 378 of 1539

SQL Reference Manual
SQL Functions

Example
The following example calculates the earth's average radius of curvature in kilometers at latitude –
90 (the South Pole):
=> SELECT RADIUS_Rv(-90);
RADIUS_Rv
-----------------6399.59362575849
(1 row)

RADIUS_SI
Returns the International System of Units (SI) radius based on the nautical mile. (A nautical mile is
a unit of length about one minute of arc of latitude measured along any meridian, or about one
minute of arc of longitude measured at the equator.) The return value has the type NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RADIUS_SI ()

Example
The following example calculates the SI radius based on the nautical mile:
=> SELECT RADIUS_SI();
RADIUS_SI
--------------------6366.70701949370750
(1 row)

RAYCROSSING
Determines whether a ray traveling to the right from point (x2,y2), in the direction of increasing x,
intersects a directed line segment that starts at point (x0,y0) and ends at point (x1,y1).
This function returns:

HP Vertica Analytic Database (7.0.x)

Page 379 of 1539

SQL Reference Manual
SQL Functions

l

0 if the ray does not intersect the directed line segment.

l

1 if the ray intersects the line and y1 is above y0.

l

–1 if the ray intersects the line and y1 is below or equal to y0.

The return value has the type DOUBLE PRECISION.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
RAYCROSSING (x0,y0,x1,y1,x2,y2)

Parameters
x0

A value of type DOUBLE PRECISION indicating the latitude of the starting point of the line
segment.

y0

A value of type DOUBLE PRECISION indicating the longitude of the starting point of the
line segment

x1

A value of type DOUBLE PRECISION indicating the latitude of the ending point of the line
segment.

y1

A value of type DOUBLE PRECISION indicating the longitude of the the ending point of the
line segment.

x2

A value of type DOUBLE PRECISION indicating the latitude of the point from which the ray
starts.

y2 A value of type DOUBLE PRECISION indicating the longitude of the point from which the
ray starts.

Example
The following example checks if a line traveling to the right from the point (0,0) intersects the line
from (1,1) to (2,3):
=> SELECT RAYCROSSING(1,1,2,3,0,0);
RAYCROSSING
-------------

HP Vertica Analytic Database (7.0.x)

Page 380 of 1539

SQL Reference Manual
SQL Functions

0
(1 row)

The following example checks if a line traveling to the right from the point (0,2) intersects the line
from (1,1) to (2,3):
=> SELECT RAYCROSSING(1,1,2,3,0,2);
RAYCROSSING
------------1
(1 row)

The following example checks if a line traveling to the right from the point (0,2) intersects the line
from (1,3) to (2,1):
=> SELECT RAYCROSSING(1,3,2,1,0,2);
RAYCROSSING
-------------1
(1 row)

WGS84_a
Returns the length, in kilometers, of the earth's semi-major axis. The return value is of type
NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_a ()

Example
=> SELECT WGS84_a();
wgs84_a
------------6378.137000
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 381 of 1539

SQL Reference Manual
SQL Functions

WGS84_b
Returns the WGS-84 semi-minor axis length value in kilometers. The return value is of type
NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_b ()

Example
=> SELECT WGS84_b();
WGS84_b
--------------------6356.75231424517950
(1 row)

WGS84_e2
Returns the WGS-84 eccentricity squared value. The return value is of type NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_e2 ()

Example
=> SELECT WGS84_e2();
WGS84_e2
----------------------.00669437999014131700

HP Vertica Analytic Database (7.0.x)

Page 382 of 1539

SQL Reference Manual
SQL Functions

(1 row)

WGS84_f
Returns the WGS-84 flattening value. The return value is of type NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_f ()

Example
=> SELECT WGS84_f();
WGS84_f
----------------------.00335281066474748072
(1 row)

WGS84_if
Returns the WGS-84 inverse flattening value. The return value is of type NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_if ()

Example
=> SELECT WGS84_if();
WGS84_if

HP Vertica Analytic Database (7.0.x)

Page 383 of 1539

SQL Reference Manual
SQL Functions

--------------298.257223563
(1 row)

WGS84_r1
Returns the International Union of Geodesy and Geophysics (IUGG) mean radius of the earth, in
kilometers. The return value is of type NUMERIC.
This function is available only if you install the HP Vertica Geospatial Package. See Geospatial
Package SQL Functions for information on installing the package.

Behavior Type
Immutable

Syntax
WGS84_r1 ()

Example
=> SELECT WGS84_r1();
WGS84_r1
--------------------6371.00877141505983
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 384 of 1539

SQL Reference Manual
SQL Functions

IP Conversion Functions
IP functions perform conversion, calculation, and manipulation operations on IP, network, and
subnet addresses.

INET_ATON
Returns an integer that represents the value of the address in host byte order, given the dotted-quad
representation of a network address as a string.

Behavior Type
Immutable

Syntax
INET_ATON ( expression )

Parameters
expression

(VARCHAR) is the string to convert.

Notes
The following syntax converts an IPv4 address represented as the string A to an integer I. INET_
ATON trims any spaces from the right of A, calls the Linux function inet_pton, and converts the result
from network byte order to host byte order using ntohl.
INET_ATON(VARCHAR A) -> INT8 I

If A is NULL, too long, or inet_pton returns an error, the result is NULL.

Examples
The generated number is always in host byte order. In the following example, the number is
calculated as 209×256^3 + 207×256^2 + 224×256 + 40.
> SELECT INET_ATON('209.207.224.40');
inet_aton
-----------3520061480
(1 row)
> SELECT INET_ATON('1.2.3.4');

HP Vertica Analytic Database (7.0.x)

Page 385 of 1539

SQL Reference Manual
SQL Functions

inet_aton
----------16909060
(1 row)
> SELECT TO_HEX(INET_ATON('1.2.3.4'));
to_hex
--------1020304
(1 row)

See Also
l

INET_NTOA

INET_NTOA
Returns the dotted-quad representation of the address as a VARCHAR, given a network address as
an integer in network byte order.

Behavior Type
Immutable

Syntax
INET_NTOA ( expression )

Parameters
expression

(INTEGER) is the network address to convert.

Notes
The following syntax converts an IPv4 address represented as integer I to a string A.
INET_NTOA converts I from host byte order to network byte order using htonl, and calls the Linux
function inet_ntop.
INET_NTOA(INT8 I) -> VARCHAR A

If I is NULL, greater than 2^32 or negative, the result is NULL.

HP Vertica Analytic Database (7.0.x)

Page 386 of 1539

SQL Reference Manual
SQL Functions

Examples
> SELECT INET_NTOA(16909060);
inet_ntoa
----------1.2.3.4
(1 row)
> SELECT INET_NTOA(03021962);
inet_ntoa
------------0.46.28.138
(1 row)

See Also
l

INET_ATON

V6_ATON
Converts an IPv6 address represented as a character string to a binary string.

Behavior Type
Immutable

Syntax
V6_ATON ( expression )

Parameters
expression

(VARCHAR) is the string to convert.

Notes
The following syntax converts an IPv6 address represented as the character string A to a binary
string B.
V6_ATON trims any spaces from the right of A and calls the Linux function inet_pton.
V6_ATON(VARCHAR A) -> VARBINARY(16) B

If A has no colons it is prepended with '::ffff:'. If A is NULL, too long, or if inet_pton returns an error,
the result is NULL.

HP Vertica Analytic Database (7.0.x)

Page 387 of 1539

SQL Reference Manual
SQL Functions

Examples
SELECT V6_ATON('2001:DB8::8:800:200C:417A');
v6_aton
-----------------------------------------------------\001\015\270\000\000\000\000\000\010\010\000 \014Az
(1 row)
SELECT V6_ATON('1.2.3.4');
v6_aton
-----------------------------------------------------------------\000\000\000\000\000\000\000\000\000\000\377\377\001\002\003\004
(1 row)
SELECT TO_HEX(V6_ATON('2001:DB8::8:800:200C:417A'));
to_hex
---------------------------------20010db80000000000080800200c417a
(1 row)
SELECT V6_ATON('::1.2.3.4');
v6_aton
-----------------------------------------------------------------\000\000\000\000\000\000\000\000\000\000\000\000\001\002\003\004
(1 row)

See Also
l

V6_NTOA

V6_NTOA
Converts an IPv6 address represented as varbinary to a character string.

Behavior Type
Immutable

Syntax
V6_NTOA ( expression )

Parameters
expression

(VARBINARY) is the binary string to convert.

Notes
The following syntax converts an IPv6 address represented as VARBINARY B to a string A.

HP Vertica Analytic Database (7.0.x)

Page 388 of 1539

SQL Reference Manual
SQL Functions

V6_NTOA right-pads B to 16 bytes with zeros, if necessary, and calls the Linux function inet_ntop.
V6_NTOA(VARBINARY B) -> VARCHAR A

If B is NULL or longer than 16 bytes, the result is NULL.
HP Vertica automatically converts the form '::ffff:1.2.3.4' to '1.2.3.4'.

Examples
> SELECT V6_NTOA(' \001\015\270\000\000\000\000\000\010\010\000 \014Az');
v6_ntoa
--------------------------2001:db8::8:800:200c:417a
(1 row)
> SELECT V6_NTOA(V6_ATON('1.2.3.4'));
v6_ntoa
--------1.2.3.4
(1 row)
> SELECT V6_NTOA(V6_ATON('::1.2.3.4'));
v6_ntoa
----------::1.2.3.4
(1 row)

See Also
l

V6_ATON

V6_SUBNETA
Calculates a subnet address in CIDR (Classless Inter-Domain Routing) format from a binary or
alphanumeric IPv6 address.

Behavior Type
Immutable

Syntax
V6_SUBNETA ( expression1, expression2 )

Parameters
expression1

(VARBINARY or VARCHAR) is the string to calculate.

expression2

(INTEGER) is the size of the subnet.

HP Vertica Analytic Database (7.0.x)

Page 389 of 1539

SQL Reference Manual
SQL Functions

Notes
The following syntax calculates a subnet address in CIDR format from a binary or varchar IPv6
address.
V6_SUBNETA masks a binary IPv6 address B so that the N leftmost bits form a subnet address,
while the remaining rightmost bits are cleared. It then converts to an alphanumeric IPv6 address,
appending a slash and N.
V6_SUBNETA(BINARY B, INT8 N) -> VARCHAR C

The following syntax calculates a subnet address in CIDR format from an alphanumeric IPv6
address.
V6_SUBNETA(VARCHAR A, INT8 N) -> V6_SUBNETA(V6_ATON(A), N) -> VARCHAR C

Examples
> SELECT V6_SUBNETA(V6_ATON('2001:db8::8:800:200c:417a'), 28);
v6_subneta
--------------2001:db0::/28
(1 row)

See Also
l

V6_SUBNETN

V6_SUBNETN
Calculates a subnet address in CIDR (Classless Inter-Domain Routing) format from a varbinary or
alphanumeric IPv6 address.

Behavior Type
Immutable

Syntax
V6_SUBNETN ( expression1, expression2 )

HP Vertica Analytic Database (7.0.x)

Page 390 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression1

(VARBINARY or VARCHAR) is the string to calculate.
Notes:
l

V6_SUBNETN(, ) returns VARBINARY.
OR

l

expression2

V6_SUBNETN(, ) returns VARBINARY, after using V6_ATON
to convert the  string to .

(INTEGER) is the size of the subnet.

Notes
The following syntax masks a BINARY IPv6 address B so that the N left-most bits of S form a
subnet address, while the remaining right-most bits are cleared.
V6_SUBNETN right-pads B to 16 bytes with zeros, if necessary and masks B, preserving its N-bit
subnet prefix.
V6_SUBNETN(VARBINARY B, INT8 N) -> VARBINARY(16) S

If B is NULL or longer than 16 bytes, or if N is not between 0 and 128 inclusive, the result is NULL.
S = [B]/N in Classless Inter-Domain Routing notation (CIDR notation).
The following syntax masks an alphanumeric IPv6 address A so that the N leftmost bits form a
subnet address, while the remaining rightmost bits are cleared.
V6_SUBNETN(VARCHAR A, INT8 N) -> V6_SUBNETN(V6_ATON(A), N) -> VARBINARY(16) S

Example
This example returns VARBINARY, after using V6_ATON to convert the VARCHAR string to VARBINARY:
> SELECT V6_SUBNETN(V6_ATON('2001:db8::8:800:200c:417a'), 28);
v6_subnetn
--------------------------------------------------------------\001\015\260\000\000\000\000\000\000\000\000\000\000\000\000

HP Vertica Analytic Database (7.0.x)

Page 391 of 1539

SQL Reference Manual
SQL Functions

See Also
l

V6_ATON

l

V6_SUBNETA

V6_TYPE
Characterizes a binary or alphanumeric IPv6 address B as an integer type.

Behavior Type
Immutable

Syntax
V6_TYPE ( expression )

Parameters
expression

(VARBINARY or VARCHAR) is the type to convert.

Notes
V6_TYPE(VARBINARY B) returns INT8 T.
V6_TYPE(VARCHAR A) -> V6_TYPE(V6_ATON(A)) -> INT8 T

The IPv6 types are defined in the Network Working Group's IP Version 6 Addressing Architecture
memo.
GLOBAL = 0
LINKLOCAL = 1
LOOPBACK = 2
UNSPECIFIED = 3
MULTICAST = 4

Global unicast addresses
Link-Local unicast (and Private-Use) addresses
Loopback
Unspecified
Multicast

IPv4-mapped and IPv4-compatible IPv6 addresses are also interpreted, as specified in IPv4 Global
Unicast Address Assignments.
l

For IPv4, Private-Use is grouped with Link-Local.

l

If B is VARBINARY, it is right-padded to 16 bytes with zeros, if necessary.

l

If B is NULL or longer than 16 bytes, the result is NULL.

HP Vertica Analytic Database (7.0.x)

Page 392 of 1539

SQL Reference Manual
SQL Functions

Details
IPv4 (either kind):
0.0.0.0/8
127.0.0.0/8
169.254.0.0/16
172.16.0.0/12
192.168.0.0/16
224.0.0.0/4
others

UNSPECIFIED
LOOPBACK
LINKLOCAL
LINKLOCAL
LINKLOCAL
MULTICAST
GLOBAL

10.0.0.0/8

::0/128
fe80::/10
ff00::/8
others

UNSPECIFIED
LINKLOCAL
MULTICAST
GLOBAL

::1/128

LINKLOCAL

IPv6:
LOOPBACK

Examples
> SELECT V6_TYPE(V6_ATON('192.168.2.10'));
v6_type
--------1
(1 row)
> SELECT V6_TYPE(V6_ATON('2001:db8::8:800:200c:417a'));
v6_type
--------0
(1 row)

See Also
l

INET_ATON

l

IP Version 6 Addressing Architecture

l

IPv4 Global Unicast Address Assignments

HP Vertica Analytic Database (7.0.x)

Page 393 of 1539

SQL Reference Manual
SQL Functions

Mathematical Functions
Some of these functions are provided in multiple forms with different argument types. Except where
noted, any given form of a function returns the same data type as its argument. The functions
working with DOUBLE PRECISION data could vary in accuracy and behavior in boundary cases
depending on the host system.

See Also
l

Template Pattern Modifiers for Date/Time Formatting

ABS
Returns the absolute value of the argument. The return value has the same data type as the
argument..

Behavior Type
Immutable

Syntax
ABS ( expression )

Parameters

expression

Is a value of type INTEGER or DOUBLE PRECISION

Examples
SELECT ABS(-28.7);
abs
-----28.7
(1 row)

ACOS
Returns a DOUBLE PRECISION value representing the trigonometric inverse cosine of the
argument.

HP Vertica Analytic Database (7.0.x)

Page 394 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
ACOS ( expression )

Parameters

expression

Is a value of type DOUBLE PRECISION

Example
SELECT ACOS (1);
acos
-----0
(1 row)

ASIN
Returns a DOUBLE PRECISION value representing the trigonometric inverse sine of the
argument.

Behavior Type
Immutable

Syntax
ASIN ( expression )

Parameters

expression

Is a value of type DOUBLE PRECISION

HP Vertica Analytic Database (7.0.x)

Page 395 of 1539

SQL Reference Manual
SQL Functions

Example
SELECT ASIN(1);
asin
----------------1.5707963267949
(1 row)

ATAN
Returns a DOUBLE PRECISION value representing the trigonometric inverse tangent of the
argument.

Behavior Type
Immutable

Syntax
ATAN ( expression )

Parameters

expression

Is a value of type DOUBLE PRECISION

Example
SELECT ATAN(1);
atan
------------------0.785398163397448
(1 row)

ATAN2
Returns a DOUBLE PRECISION value representing the trigonometric inverse tangent of the
arithmetic dividend of the arguments.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 396 of 1539

SQL Reference Manual
SQL Functions

Syntax
ATAN2 ( quotient, divisor )

Parameters
quotient

Is an expression of type DOUBLE PRECISION representing the quotient

divisor

Is an expression of type DOUBLE PRECISION representing the divisor

Example
SELECT ATAN2(2,1);
ATAN2
-----------------1.10714871779409
(1 row)

CBRT
Returns the cube root of the argument. The return value has the type DOUBLE PRECISION.

Behavior Type
Immutable

Syntax
CBRT ( expression )

Parameters
expression

Value of type DOUBLE PRECISION

Examples
SELECT CBRT(27.0);
cbrt
-----3
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 397 of 1539

SQL Reference Manual
SQL Functions

CEILING (CEIL)
Rounds the returned value up to the next whole number. Any expression that contains even a slight
decimal is rounded up.

Behavior Type
Immutable

Syntax
CEILING ( expression )CEIL ( expression )

Parameters
expression

Is a value of type INTEGER or DOUBLE PRECISION

Notes
CEILING is the opposite of FLOOR, which rounds the returned value down:
=> SELECT CEIL(48.01) AS ceiling, FLOOR(48.01) AS floor;
ceiling | floor
---------+------49 |
48
(1 row)

Examples
=> SELECT CEIL(-42.8);
CEIL
------42
(1 row)
SELECT CEIL(48.01);
CEIL
-----49
(1 row)

COS
Returns a DOUBLE PRECISION value representing the trigonometric cosine of the argument.

HP Vertica Analytic Database (7.0.x)

Page 398 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
COS ( expression )

Parameters
expression

Is a value of type DOUBLE PRECISION

Example
SELECT COS(-1);
cos
-----------------0.54030230586814
(1 row)

COT
Returns a DOUBLE PRECISION value representing the trigonometric cotangent of the argument.

Behavior Type
Immutable

Syntax
COT ( expression )

Parameters
expression

Is a value of type DOUBLE PRECISION

Example
SELECT COT(1);
cot
------------------0.642092615934331

HP Vertica Analytic Database (7.0.x)

Page 399 of 1539

SQL Reference Manual
SQL Functions

(1 row)

DEGREES
Converts an expression from RADIANS to fractional degrees, or from degrees, minutes, and
seconds to fractional degrees. The return value has the type DOUBLE PRECISION.

Behavior Type
Immutable

Syntax 1
DEGREES (radians)

Syntax 2
DEGREES (degrees, minutes, seconds)

Parameters
radians

A unit of angular measure, 2π radians is equal to a full rotation.

degrees

A unit of angular measure, equal to 1/360 of a full rotation.

minutes

A unit of angular measurement, representing 1/60 of a degree.

seconds

A unit of angular measurement, representing 1/60 of a minute.

Examples
SELECT DEGREES(0.5);
DEGREES
-----------------28.6478897565412
(1 row)
SELECT DEGREES(1,2,3);
DEGREES
-----------------1.03416666666667
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 400 of 1539

SQL Reference Manual
SQL Functions

DISTANCE
Returns the distance (in kilometers) between two points. You specify the latitude and longitude of
both the starting point and the ending point. You can also specify the radius of curvature for greater
accuracy when using an ellipsoidal model.

Behavior Type
Immutable

Syntax
DISTANCE ( lat0, lon0, lat1, lon1, radius_of_curvature )

Parameters
lat0

Specifies the latitude of the starting point.

lon0

Specifies the longitude of the starting point.

lat1

Specifies the latitude of the ending point

lon1

Specifies the longitude of the ending point.

radius_of_curvature

Specifies the radius of the curvature of the earth at the midpoint between
the starting and ending points. This parameter allows for greater accuracy
when using an ellipsoidal earth model. If you do not specify this parameter,
it defaults to the WGS-84 average r1 radius, about 6371.009 km.

Example
This example finds the distance in kilometers for 1 degree of longitude at latitude 45 degrees,
assuming earth is spherical.
SELECT DISTANCE(45,0, 45,1);
DISTANCE
---------------------78.6262959272162
(1 row)

DISTANCEV
Returns the distance (in kilometers) between two points using the Vincenty formula. Because the
Vincenty formula includes the parameters of the WGS-84 ellipsoid model, you need not specify a
radius of curvature. You specify the latitude and longitude of both the starting point and the ending
point. This function is more accurate, but will be slower, than the DISTANCE function.

HP Vertica Analytic Database (7.0.x)

Page 401 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
DISTANCEV (lat0, lon0, lat1, lon1);

Parameters
lat0

Specifies the latitude of the starting point.

lon0 Specifies the longitude of the starting point.
lat1

Specifies the latitude of the ending point.

lon1 Specifies the longitude of the ending point.

Example
This example finds the distance in kilometers for 1 degree of longitude at latitude 45 degrees,
assuming earth is ellipsoidal.
SELECT DISTANCEV(45,0, 45,1);
distanceV
-----------------78.8463347095916
(1 row)

EXP
Returns the exponential function, e to the power of a number. The return value has the same data
type as the argument.

Behavior Type
Immutable

Syntax
EXP ( exponent )

Parameters
exponent

Is an expression of type INTEGER or DOUBLE PRECISION

HP Vertica Analytic Database (7.0.x)

Page 402 of 1539

SQL Reference Manual
SQL Functions

Example
SELECT EXP(1.0);
exp
-----------------2.71828182845905
(1 row)

FLOOR
Rounds the returned value down to the next whole number. For example, each of these functions
evaluates to 5:
floor(5.01)
floor(5.5)
floor(5.99)

Behavior Type
Immutable

Syntax
FLOOR ( expression )

Parameters
expression

Is an expression of type INTEGER or DOUBLE PRECISION.

Notes
FLOOR is the opposite of CEILING, which rounds the returned value up:
=> SELECT FLOOR(48.01) AS floor, CEIL(48.01) AS ceiling;
floor | ceiling
-------+--------48 |
49
(1 row)

Examples
=> SELECT FLOOR((TIMESTAMP '2005-01-17 10:00' - TIMESTAMP '2005-01-01') / INTERVAL '7');

HP Vertica Analytic Database (7.0.x)

Page 403 of 1539

SQL Reference Manual
SQL Functions

FLOOR
------2
(1 row)
=> SELECT FLOOR(-42.8);
FLOOR
-------43
(1 row)
=> SELECT FLOOR(42.8);
FLOOR
------42
(1 row)

Although the following example looks like an INTEGER, the number on the left is 2^49 as an
INTEGER, but the number on the right is a FLOAT:
=> SELECT 1<<49, FLOOR(1 << 49);
?column?
|
floor
-----------------+----------------562949953421312 | 562949953421312
(1 row)

Compare the above example to:
=> SELECT 1<<50, FLOOR(1 << 50);
?column?
|
floor
------------------+---------------------1125899906842624 | 1.12589990684262e+15
(1 row)

HASH
Calculates a hash value over its arguments, producing a value in the range 0 <= x < 263 (two to the
sixty-third power or 2^63).

Behavior Type
Immutable

Syntax
HASH ( expression [ ,... ] )

Parameters
expression

Is an expression of any data type. For the purpose of hash segmentation, each
expression is a column reference .

HP Vertica Analytic Database (7.0.x)

Page 404 of 1539

SQL Reference Manual
SQL Functions

Notes
l

The HASH() function is used to provide projection segmentation over a set of nodes in a cluster
and takes up to 32 arguments, usually column names, and selects a specific node for each row
based on the values of the columns for that row. HASH (Col1, Col2).

l

If your data is fairly regular and you want more even distribution than you get with HASH,
consider using MODULARHASH() for project segmentation.

Examples
SELECT HASH(product_price, product_cost) FROM product_dimension
WHERE product_price = '11';
hash
--------------------4157497907121511878
1799398249227328285
3250220637492749639
(3 rows)

See Also
l

MODULARHASH

LN
Returns the natural logarithm of the argument. The return data type is the same as the argument.

Behavior Type
Immutable

Syntax
LN ( expression )

Parameters
expression

Is an expression of type INTEGER or DOUBLE PRECISION

Example
SELECT LN(2);

HP Vertica Analytic Database (7.0.x)

Page 405 of 1539

SQL Reference Manual
SQL Functions

ln
------------------0.693147180559945
(1 row)

LOG
Returns the logarithm to the specified base of the argument. The return data type is the same as the
argument.

Behavior Type
Immutable

Syntax
LOG ( [ base, ] expression )

Parameters
base

Specifies the base (default is base 10)

expression

Is an expression of type INTEGER or DOUBLE PRECISION

Examples
SELECT LOG(2.0, 64);
log
----6
(1 row)
SELECT LOG(100);
log
----2
(1 row)

MOD
Returns the remainder of a division operation. MOD is also called modulo.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 406 of 1539

SQL Reference Manual
SQL Functions

Syntax
MOD( expression1, expression2 )

Parameters
expression1

Specifies the dividend (INTEGER, NUMERIC, or FLOAT)

expression2

Specifies the divisor (type same as dividend)

Notes
When computing mod(N,M), the following rules apply:
l

If either N or M is the null value, then the result is the null value.

l

If M is zero, then an exception condition is raised: data exception — division by zero.

l

Otherwise, the result is the unique exact numeric value R with scale 0 (zero) such that all of the
following are true:
n

R has the same sign as N.

n

The absolute value of R is less than the absolute value of M.

n

N = M * K + R for some exact numeric value K with scale 0 (zero).

Examples
SELECT MOD(9,4);
mod
----1
(1 row)
SELECT MOD(10,3);
mod
----1
(1 row)
SELECT MOD(-10,3);
mod
-----1
(1 row)
SELECT MOD(-10,-3);
mod
-----

HP Vertica Analytic Database (7.0.x)

Page 407 of 1539

SQL Reference Manual
SQL Functions

-1
(1 row)
SELECT MOD(10,-3);
mod
----1
(1 row)

MOD(, 0) gives an error:
=> SELECT MOD(6.2,0);
ERROR: numeric division by zero

MODULARHASH
Calculates a hash value over its arguments for the purpose of projection segmentation. In all other
uses, returns 0.
If you can hash segment your data using a column with a regular pattern, such as a sequential
unique identifier, MODULARHASH distributes the data more evenly than HASH, which distributes
data using a normal statistical distribution.

Behavior Type
Immutable

Syntax
MODULARHASH ( expression [ ,... ] )

Parameters
expression

Is a column reference of any data type.

Notes
The MODULARHASH() function takes up to 32 arguments, usually column names, and selects a
specific node for each row based on the values of the columns for that row.

Example
CREATE PROJECTION fact_ts_2 (f_price, f_cid, f_tid, f_cost, f_date)
AS (SELECT price, cid, tid, cost, dwdate
FROM fact)

HP Vertica Analytic Database (7.0.x)

Page 408 of 1539

SQL Reference Manual
SQL Functions

SEGMENTED BY MODULARHASH(dwdate)
ALL NODES OFFSET 2;

See Also
l

HASH

PI
Returns the constant pi (Π), the ratio of any circle's circumference to its diameter in Euclidean
geometry The return type is DOUBLE PRECISION.

Behavior Type
Immutable

Syntax
PI()

Examples
SELECT PI();
pi
-----------------3.14159265358979
(1 row)

POWER (or POW)
Returns a DOUBLE PRECISION value representing one number raised to the power of another
number. You can use either POWER or POW as the function name.

Behavior Type
Immutable

Syntax
POWER ( expression1, expression2 )

HP Vertica Analytic Database (7.0.x)

Page 409 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression1

Is an expression of type DOUBLE PRECISION that represents the base

expression2

Is an expression of type DOUBLE PRECISION that represents the exponent

Example
SELECT POWER(9.0, 3.0);
power
------729
(1 row)

RADIANS
Returns a DOUBLE PRECISION value representing an angle expressed in radians. You can
express the input angle in DEGREES, and optionally include minutes and seconds.

Behavior Type
Immutable

Syntax
RADIANS (degrees [, minutes, seconds])

Parameters
degrees

A unit of angular measurement, representing 1/360 of a full rotation.

minutes

A unit of angular measurement, representing 1/60 of a degree.

seconds

A unit of angular measurement, representing 1/60 of a minute.

Examples
SELECT RADIANS(45);
RADIANS
------------------0.785398163397448
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 410 of 1539

SQL Reference Manual
SQL Functions

SELECT RADIANS (1,2,3);
RADIANS
------------------0.018049613347708
(1 row)

RANDOM
Returns a uniformly-distributed random number x, where 0 <= x < 1.

Behavior Type
Volatile

Syntax
RANDOM()

Parameters
RANDOM has no arguments. Its result is a FLOAT8 data type (also called DOUBLE PRECISION).

Notes
Typical pseudo-random generators accept a seed, which is set to generate a reproducible pseudorandom sequence. HP Vertica, however, distributes SQL processing over a cluster of nodes, where
each node generates its own independent random sequence.
Results depending on RANDOM are not reproducible because the work might be divided differently
across nodes. Therefore, HP Vertica automatically generates truly random seeds for each node
each time a request is executed and does not provide a mechanism for forcing a specific seed.

Examples
In the following example, the result is a float, which is >= 0 and < 1.0:
SELECT RANDOM();
random
------------------0.211625560652465
(1 row)

RANDOMINT
Returns an INT8 value, and accepts a positive integer (n). RANDOMINT(n) returns one of the n
integers from 0 through n – 1.

HP Vertica Analytic Database (7.0.x)

Page 411 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Volatile

Syntax
RANDOMINT ( n )

Example
In the following example, the result is an INT8, which is >= 0 and < n, randomly chosen from the set
{0,1,2,3,4}.
SELECT RANDOMINT(5);
RANDOMINT
---------3
(1 row)

Following are other examples of using this function:
dbt=> select randomint (-2);
ERROR 4163: Non-positive value supplied to randomint: -2 dbt=> select randomint(0);
dbt=> select randomint(1);
0
dbt=> select randomint(21);
randomint
----------15
(1 row)
dbt=> select randomint(233333333333321);
randomint
---------------21875589868430
(1 row)

ROUND
Rounds a value to a specified number of decimal places, retaining the original scale and precision.
Fractions greater than or equal to .5 are rounded up. Fractions less than .5 are rounded down
(truncated).

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 412 of 1539

SQL Reference Manual
SQL Functions

Syntax
ROUND ( expression [ , decimal-places ] )

Parameters
expression

Is an expression of type NUMERIC.

decimal-places

If positive, specifies the number of decimal places to display to the right of the
decimal point; if negative, specifies the number of decimal places to display to
the left of the decimal point.

Notes
NUMERIC ROUND() returns NUMERIC, retaining the original scale and precision:
=> SELECT ROUND(3.5);
ROUND
------4.0
(1 row)

The internal floating-point representation used to compute the ROUND function causes the fraction
to be evaluated as 3.5, which is rounded up.

Examples
SELECT ROUND(2.0, 1.0 ) FROM dual;
round
------2
(1 row)
SELECT ROUND(12.345, 2.0 );
round
------12.35
(1 row)
SELECT ROUND(3.444444444444444);
ROUND
------------------3.000000000000000
(1 row)
SELECT ROUND(3.14159, 3);
ROUND
---------

HP Vertica Analytic Database (7.0.x)

Page 413 of 1539

SQL Reference Manual
SQL Functions

3.14200
(1 row)
SELECT ROUND(1234567, -3);
round
--------1235000
(1 row)
SELECT ROUND(3.4999, -1);
ROUND
------.0000
(1 row)
SELECT employee_last_name, ROUND(annual_salary,4) FROM employee_dimension;
employee_last_name | ROUND
--------------------+-------Li
|
1880
Rodriguez
|
1704
Goldberg
|
2282
Meyer
|
1628
Pavlov
|
3168
McNulty
|
1516
Dobisz
|
3006
Pavlov
|
2142
Goldberg
|
2268
Pavlov
|
1918
Robinson
|
2366
...

SIGN
Returns a DOUBLE PRECISION value of -1, 0, or 1 representing the arithmetic sign of the
argument.

Behavior Type
Immutable

Syntax
SIGN ( expression )

Parameters
expression

Is an expression of type DOUBLE PRECISION

HP Vertica Analytic Database (7.0.x)

Page 414 of 1539

SQL Reference Manual
SQL Functions

Examples
SELECT SIGN(-8.4);
sign
------1
(1 row)

SIN
Returns a DOUBLE PRECISION value representing the trigonometric sine of the argument.

Behavior Type
Immutable

Syntax
SIN ( expression )

Parameters
expression

Is an expression of type DOUBLE PRECISION

Example
SELECT SIN(30 * 2 * 3.14159 / 360);
sin
------------------0.499999616987256
(1 row)

SQRT
Returns a DOUBLE PRECISION value representing the arithmetic square root of the argument.

Behavior Type
Immutable

Syntax
SQRT ( expression )

HP Vertica Analytic Database (7.0.x)

Page 415 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

Is an expression of type DOUBLE PRECISION

Examples
SELECT SQRT(2);
sqrt
----------------1.4142135623731
(1 row)

TAN
Returns a DOUBLE PRECISION value representing the trigonometric tangent of the argument.

Behavior Type
Immutable

Syntax
TAN ( expression )

Parameters
expression

Is an expression of type DOUBLE PRECISION

Example
SELECT TAN(30);
tan
-------------------6.40533119664628
(1 row)

TRUNC
Returns a value representing the argument fully truncated (toward zero) or truncated to a specific
number of decimal places, retaining the original scale and precision.

HP Vertica Analytic Database (7.0.x)

Page 416 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
TRUNC ( expression [ , places ]

Parameters
expression

Is an expression of type INTEGER or DOUBLE PRECISION that represents the
number to truncate

places

Is an expression of type INTEGER that specifies the number of decimal places to
return

Notes
NUMERIC TRUNC() returns NUMERIC, retaining the original scale and precision:
=> SELECT TRUNC(3.5);
TRUNC
------3.0
(1 row)

Examples
=> SELECT TRUNC(42.8);
TRUNC
------42.0
(1 row)
=> SELECT TRUNC(42.4382, 2);
TRUNC
--------42.4300
(1 row)

WIDTH_BUCKET
Constructs equiwidth histograms, in which the histogram range is divided into intervals (buckets)
of identical sizes. In addition, values below the low bucket return 0, and values above the high
bucket return bucket_count +1. Returns an integer value.

HP Vertica Analytic Database (7.0.x)

Page 417 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
WIDTH_BUCKET ( expression, hist_min, hist_max, bucket_count )

Parameters
expression

The expression for which the histogram is created. This expression must evaluate
to a numeric or datetime value or to a value that can be implicitly converted to a
numeric or datetime value. If expression evaluates to null, then the expression
returns null.

hist_min

An expression that resolves to the low boundary of bucket 1. Must also evaluate
to numeric or datetime values and cannot evaluate to null.

hist_max

An expression that resolves to the high boundary of bucket bucket_count. Must
also evaluate to a numeric or datetime value and cannot evaluate to null.

bucket_count

An expression that resolves to a constant, indicating the number of buckets. This
expression always evaluates to a positive INTEGER.

Notes
l

WIDTH_BUCKET divides a data set into buckets of equal width. For example, Age = 0–20, 20–
40, 40–60, 60–80. This is known as an equiwidth histogram.

l

When using WIDTH_BUCKET pay attention to the minimum and maximum boundary values.
Each bucket contains values equal to or greater than the base value of that bucket, so that age
ranges of 0–20, 20–40, and so on, are actually 0–19.99 and 20–39.999.

l

WIDTH_BUCKET accepts the following data types: (FLOAT and/or INT), (TIMESTAMP and/or
DATE and/or TIMESTAMPTZ), or (INTERVAL and/or TIME).

Examples
The following example returns five possible values and has three buckets: 0 [Up to 100), 1 [100–
300), 2 [300–500), 3 [500–700), and 4 [700 and up):
SELECT product_description, product_cost, WIDTH_BUCKET(product_cost, 100, 700, 3);

The following example creates a nine-bucket histogram on the annual_income column for
customers in Connecticut who are female doctors. The results return the bucket number to an
“Income” column, divided into eleven buckets, including an underflow and an overflow. Note that if

HP Vertica Analytic Database (7.0.x)

Page 418 of 1539

SQL Reference Manual
SQL Functions

customers had an annual incomes greater than the maximum value, they would be assigned to an
overflow bucket, 10:
SELECT customer_name, annual_income, WIDTH_BUCKET (annual_income, 100000, 1000000, 9) AS
"Income"
FROM public.customer_dimension WHERE customer_state='CT'
AND title='Dr.' AND customer_gender='Female' AND household_id < '1000'
ORDER BY "Income";

In the following result set, the reason there is a bucket 0 is because buckets are numbered from 1 to
bucket_count. Anything less than the given value of hist_min goes in bucket 0, and anything
greater than the given value of hist_max goes in the bucket bucket_count+1. In this example,
bucket 9 is empty, and there is no overflow. The value 12,283 is less than 100,000, so it goes into
the underflow bucket.
customer_name
| annual_income | Income
--------------------+---------------+-------Joanna A. Nguyen
|
12283 |
0
Amy I. Nguyen
|
109806 |
1
Juanita L. Taylor |
219002 |
2
Carla E. Brown
|
240872 |
2
Kim U. Overstreet |
284011 |
2
Tiffany N. Reyes
|
323213 |
3
Rebecca V. Martin |
324493 |
3
Betty . Roy
|
476055 |
4
Midori B. Young
|
462587 |
4
Martha T. Brown
|
687810 |
6
Julie D. Miller
|
616509 |
6
Julie Y. Nielson
|
894910 |
8
Sarah B. Weaver
|
896260 |
8
Jessica C. Nielson |
861066 |
8
(14 rows)

See Also
l

NTILE [Analytic]

HP Vertica Analytic Database (7.0.x)

Page 419 of 1539

SQL Reference Manual
SQL Functions

NULL-handling Functions
NULL-handling functions take arguments of any type, and their return type is based on their
argument types.

COALESCE
Returns the value of the first non-null expression in the list. If all expressions evaluate to null, then
the COALESCE function returns null.

Behavior Type
Immutable

Syntax
COALESCE ( expression1, expression2 );
COALESCE ( expression1, expression2, ...
expression-n );

Parameters
l

COALESCE (expression1, expression2) is equivalent to the following CASE expression:
CASE WHEN expression1 IS NOT NULL THEN expression1 ELSE
expression2 END;

l

COALESCE (expression1, expression2, ... expression-n), for n >= 3, is equivalent to the
following CASE expression:
CASE WHEN expression1 IS NOT NULL THEN expression1ELSE
COALESCE (expression2, . . . , expression-n) END;

Notes
COALESCE is an ANSI standard function (SQL-92).

Example
SELECT product_description,
COALESCE(lowest_competitor_price,
highest_competitor_price,

HP Vertica Analytic Database (7.0.x)

Page 420 of 1539

SQL Reference Manual
SQL Functions

average_competitor_price) AS price
FROM product_dimension;
product_description
| price
------------------------------------+------Brand #54109 kidney beans
|
264
Brand #53364 veal
|
139
Brand #50720 ice cream sandwiches |
127
Brand #48820 coffee cake
|
174
Brand #48151 halibut
|
353
Brand #47165 canned olives
|
250
Brand #39509 lamb
|
306
Brand #36228 tuna
|
245
Brand #34156 blueberry muffins
|
183
Brand #31207 clams
|
163
(10 rows)

See Also
l

CASE Expressions

l

ISNULL

IFNULL
Returns the value of the first non-null expression in the list.
IFNULL is an alias of NVL.

Behavior Type
Immutable

Syntax
IFNULL ( expression1 , expression2 );

Parameters
l

If expression1 is null, then IFNULL returns expression2.

l

If expression1 is not null, then IFNULL returns expression1.

Notes
l

COALESCE is the more standard, more general function.

l

IFNULL is equivalent to ISNULL.

HP Vertica Analytic Database (7.0.x)

Page 421 of 1539

SQL Reference Manual
SQL Functions

l

IFNULL is equivalent to COALESCE except that IFNULL is called with only two arguments.

l

ISNULL(a,b) is different from x IS NULL.

l

The arguments can have any data type supported by HP Vertica.

l

Implementation is equivalent to the CASE expression. For example:
CASE WHEN expression1 IS NULL THEN expression2
ELSE expression1 END;

l

The following statement returns the value 140:
SELECT IFNULL(NULL, 140) FROM employee_dimension;

l

The following statement returns the value 60:
SELECT IFNULL(60, 90) FROM employee_dimension;

Examples
=> SELECT IFNULL (SCORE, 0.0) FROM TESTING;
IFNULL
-------100.0
87.0
.0
.0
.0
(5 rows)

See Also
l

CASE Expressions

l

COALESCE

l

NVL

l

ISNULL

ISNULL
Returns the value of the first non-null expression in the list.
ISNULL is an alias of NVL.

HP Vertica Analytic Database (7.0.x)

Page 422 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
ISNULL ( expression1 , expression2 );

Parameters
l

If expression1 is null, then ISNULL returns expression2.

l

If expression1 is not null, then ISNULL returns expression1.

Notes
l

COALESCE is the more standard, more general function.

l

ISNULL is equivalent to COALESCE except that ISNULL is called with only two arguments.

l

ISNULL(a,b) is different from x IS NULL.

l

The arguments can have any data type supported by HP Vertica.

l

Implementation is equivalent to the CASE expression. For example:
CASE WHEN expression1 IS NULL THEN expression2
ELSE expression1 END;

l

The following statement returns the value 140:
SELECT ISNULL(NULL, 140) FROM employee_dimension;

l

The following statement returns the value 60:
SELECT ISNULL(60, 90) FROM employee_dimension;

Examples
SELECT product_description, product_price,
ISNULL(product_cost, 0.0) AS cost
FROM product_dimension;
product_description
| product_price | cost

HP Vertica Analytic Database (7.0.x)

Page 423 of 1539

SQL Reference Manual
SQL Functions

--------------------------------+---------------+-----Brand #59957 wheat bread
|
405 | 207
Brand #59052 blueberry muffins |
211 | 140
Brand #59004 english muffins
|
399 | 240
Brand #53222 wheat bread
|
323 |
94
Brand #52951 croissants
|
367 | 121
Brand #50658 croissants
|
100 |
94
Brand #49398 white bread
|
318 |
25
Brand #46099 wheat bread
|
242 |
3
Brand #45283 wheat bread
|
111 | 105
Brand #43503 jelly donuts
|
259 |
19
(10 rows)

See Also
l

CASE Expressions

l

COALESCE

l

NVL

NULLIF
Compares two expressions. If the expressions are not equal, the function returns the first
expression (expression1). If the expressions are equal, the function returns null.

Behavior Type
Immutable

Syntax
NULLIF( expression1, expression2 )

Parameters

expression1

Is a value of any data type.

expression2

Must have the same data type as expr1 or a type that can be implicitly cast to
match expression1. The result has the same type as expression1.

Examples
The following series of statements illustrates one simple use of the NULLIF function.
Creates a single-column table t and insert some values:

HP Vertica Analytic Database (7.0.x)

Page 424 of 1539

SQL Reference Manual
SQL Functions

CREATE TABLE t (x TIMESTAMPTZ);
INSERT INTO t VALUES('2009-09-04 09:14:00-04');
INSERT INTO t VALUES('2010-09-04 09:14:00-04');

Issue a select statement:
SELECT x, NULLIF(x, '2009-09-04 09:14:00 EDT') FROM t;
x
|
nullif
------------------------+-----------------------2009-09-04 09:14:00-04 |
2010-09-04 09:14:00-04 | 2010-09-04 09:14:00-04
SELECT NULLIF(1, 2);
NULLIF
-------1
(1 row)
SELECT NULLIF(1, 1);
NULLIF
-------(1 row)
SELECT NULLIF(20.45, 50.80);
NULLIF
-------20.45
(1 row)

NULLIFZERO
Evaluates to NULL if the value in the column is 0.

Syntax
NULLIFZERO(expression)

Parameters
expression

(INTEGER, DOUBLE PRECISION, INTERVAL, or NUMERIC) Is the string to
evaluate for 0 values.

Example
The TESTING table below shows the test scores for 5 students. Note that test scores are missing
for S. Robinson and K. Johnson (NULL values appear in the Score column.)
=> SELECT * FROM TESTING;
Name
| Score
-------------+------J. Doe
|
100

HP Vertica Analytic Database (7.0.x)

Page 425 of 1539

SQL Reference Manual
SQL Functions

R. Smith
L. White
S. Robinson
K. Johnson
(5 rows)

|
|
|
|

87
0

The SELECT statement below specifies that HP Vertica should return any 0 values in the Score
column as Null. In the results, you can see that HP Vertica returns L. White's 0 score as Null.
=> SELECT Name, NULLIFZERO(Score) FROM TESTING;
Name
| NULLIFZERO
-------------+-----------J. Doe
|
100
R. Smith
|
87
L. White
|
S. Robinson |
K. Johnson |
(5 rows)

NVL
Returns the value of the first non-null expression in the list.

Behavior Type
Immutable

Syntax
NVL ( expression1 , expression2 );

Parameters
l

If expression1 is null, then NVL returns expression2.

l

If expression1 is not null, then NVL returns expression1.

Notes
l

COALESCE is the more standard, more general function.

l

NVL is equivalent to COALESCE except that NVL is called with only two arguments.

l

The arguments can have any data type supported by HP Vertica.

l

Implementation is equivalent to the CASE expression:

HP Vertica Analytic Database (7.0.x)

Page 426 of 1539

SQL Reference Manual
SQL Functions

CASE WHEN expression1 IS NULL THEN expression2
ELSE expression1 END;

Examples
expression1 is not null, so NVL returns expression1:
SELECT NVL('fast', 'database');
nvl
-----fast
(1 row)

expression1 is null, so NVL returns expression2:
SELECT NVL(null, 'database');
nvl
---------database
(1 row)

expression2 is null, so NVL returns expression1:
SELECT NVL('fast', null);
nvl
-----fast
(1 row)

In the following example, expression1 (title) contains nulls, so NVL returns expression2 and
substitutes 'Withheld' for the unknown values:
SELECT customer_name, NVL(title, 'Withheld') as title
FROM customer_dimension
ORDER BY title;
customer_name
| title
------------------------+------Alexander I. Lang
| Dr.
Steve S. Harris
| Dr.
Daniel R. King
| Dr.
Luigi I. Sanchez
| Dr.
Duncan U. Carcetti
| Dr.
Meghan K. Li
| Dr.
Laura B. Perkins
| Dr.
Samantha V. Robinson
| Dr.
Joseph P. Wilson
| Mr.
Kevin R. Miller
| Mr.
Lauren D. Nguyen
| Mrs.
Emily E. Goldberg
| Mrs.
Darlene K. Harris
| Ms.

HP Vertica Analytic Database (7.0.x)

Page 427 of 1539

SQL Reference Manual
SQL Functions

Meghan J. Farmer
Bettercare
Ameristar
Initech
(17 rows)

|
|
|
|

Ms.
Withheld
Withheld
Withheld

See Also
l

CASE Expressions

l

COALESCE

l

ISNULL

l

NVL2

NVL2
Takes three arguments. If the first argument is not NULL, it returns the second argument, otherwise
it returns the third argument. The data types of the second and third arguments are implicitly cast to
a common type if they don't agree, similar to COALESCE.

Behavior Type
Immutable

Syntax
NVL2 ( expression1 , expression2 , expression3 );

Parameters
l

If expression1 is not null, then NVL2 returns expression2.

l

If expression1 is null, then NVL2 returns expression3.

Notes
Arguments two and three can have any data type supported by HP Vertica.
Implementation is equivalent to the CASE expression:
CASE WHEN expression1 IS NOT NULL THEN expression2 ELSE expression3 END;

Examples
In this example, expression1 is not null, so NVL2 returns expression2:

HP Vertica Analytic Database (7.0.x)

Page 428 of 1539

SQL Reference Manual
SQL Functions

SELECT NVL2('very', 'fast', 'database');
nvl2
-----fast
(1 row)

In this example, expression1 is null, so NVL2 returns expression3:
SELECT NVL2(null, 'fast', 'database');
nvl2
---------database
(1 row)

In the following example, expression1 (title) contains nulls, so NVL2 returns expression3
('Withheld') and also substitutes the non-null values with the expression 'Known':
SELECT customer_name, NVL2(title, 'Known', 'Withheld')
as title
FROM customer_dimension
ORDER BY title;
customer_name
| title
------------------------+------Alexander I. Lang
| Known
Steve S. Harris
| Known
Daniel R. King
| Known
Luigi I. Sanchez
| Known
Duncan U. Carcetti
| Known
Meghan K. Li
| Known
Laura B. Perkins
| Known
Samantha V. Robinson
| Known
Joseph P. Wilson
| Known
Kevin R. Miller
| Known
Lauren D. Nguyen
| Known
Emily E. Goldberg
| Known
Darlene K. Harris
| Known
Meghan J. Farmer
| Known
Bettercare
| Withheld
Ameristar
| Withheld
Initech
| Withheld
(17 rows)

See Also
l

CASE Expressions

l

COALESCE

l

COALESCE

ZEROIFNULL
Evaluates to 0 if the column is NULL.

HP Vertica Analytic Database (7.0.x)

Page 429 of 1539

SQL Reference Manual
SQL Functions

Syntax
ZEROIFNULL(expression)

Parameters
expression

(INTEGER, DOUBLE PRECISION, INTERVAL, or NUMERIC) Is the string to
evaluate for NULL values.

Example
The TESTING table below shows the test scores for 5 students. Note that L. White's score is 0,
and that scores are missing for S. Robinson and K. Johnson.
=> SELECT * FROM TESTING;
Name
| Score
-------------+------J. Doe
|
100
R. Smith
|
87
L. White
|
0
S. Robinson |
K. Johnson |
(5 rows)

The next SELECT statement specifies that HP Vertica should return any Null values in the Score
column as 0s. In the results, you can see that HP Vertica returns a 0 score for S. Robinson and K.
Johnson.
=> SELECT Name, ZEROIFNULL (Score) FROM TESTING;
Name
| ZEROIFNULL
-------------+-----------J. Doe
|
100
R. Smith
|
87
L. White
|
0
S. Robinson |
0
K. Johnson |
0
(5 rows)

HP Vertica Analytic Database (7.0.x)

Page 430 of 1539

SQL Reference Manual
SQL Functions

Pattern Matching Functions
Used with the MATCH Clause, the HP Vertica pattern matching functions return additional data
about the patterns found/output. For example, you can use these functions to return values
representing the name of the event or pattern that matched the input row, the sequential number of
the match, or a partition-wide unique identifier for the instance of the pattern that matched.
Pattern matching is particularly useful for clickstream analysis where you might want to identify
users' actions based on their Web browsing behavior (page clicks). A typical online clickstream
funnel is:
Company home page -> product home page -> search -> results -> purchase online
Using the above clickstream funnel, you can search for a match on the user's sequence of web
clicks and identify that the user:
l

Landed on the company home page.

l

Navigated to the product page.

l

Ran a search.

l

Clicked a link from the search results.

l

Made a purchase.

For examples that use this clickstream model, see Event Series Pattern Matching in the
Programmer's Guide.

See Also
MATCH Clause

l
l

EVENT_NAME
Returns a VARCHAR value representing the name of the event that matched the row.

Syntax
EVENT_NAME()

Notes
Pattern matching functions must be used in MATCH Clause syntax; for example, if you call
EVENT_NAME() on its own, HP Vertica returns the following error message:

HP Vertica Analytic Database (7.0.x)

Page 431 of 1539

SQL Reference Manual
SQL Functions

=> SELECT event_name();
ERROR: query with pattern matching function event_name must include a MATCH clause

Example
Note: This example uses the schema defined in Event Series Pattern Matching in the
Programmer's Guide. For a more detailed example, see that topic.
The following statement analyzes users' browsing history on website2.com and identifies patterns
where the user landed on website2.com from another Web site (Entry) and browsed to any number
of other pages (Onsite) before making a purchase (Purchase). The query also outputs the values for
EVENT_NAME(), which is the name of the event that matched the row.
SELECT uid,
sid,
ts,
refurl,
pageurl,
action,
event_name()
FROM clickstream_log
MATCH
(PARTITION BY uid, sid ORDER BY ts
DEFINE
Entry
AS RefURL NOT ILIKE '%website2.com%' AND PageURL ILIKE '%website2.com%',
Onsite
AS PageURL ILIKE
'%website2.com%' AND Action='V',
Purchase AS PageURL ILIKE
'%website2.com%' AND Action = 'P'
PATTERN
P AS (Entry Onsite* Purchase)
RESULTS ALL ROWS);
uid | sid |
ts
|
refurl
|
pageurl
| action | event_name
-----+-----+----------+----------------------+----------------------+--------+----------1 | 100 | 12:00:00 | website1.com
| website2.com/home
| V
| Entry
1 | 100 | 12:01:00 | website2.com/home
| website2.com/floby
| V
| Onsite
1 | 100 | 12:02:00 | website2.com/floby
| website2.com/shamwow | V
| Onsite
1 | 100 | 12:03:00 | website2.com/shamwow | website2.com/buy
| P
| Purchase
2 | 100 | 12:10:00 | website1.com
| website2.com/home
| V
| Entry
2 | 100 | 12:11:00 | website2.com/home
| website2.com/forks
| V
| Onsite
2 | 100 | 12:13:00 | website2.com/forks
| website2.com/buy
| P
| Purchase
(7 rows)

See Also
l

MATCH Clause

l

MATCH_ID
PATTERN_ID

l
l

HP Vertica Analytic Database (7.0.x)

Page 432 of 1539

SQL Reference Manual
SQL Functions

MATCH_ID
Returns a successful pattern match as an INTEGER value. The returned value is the ordinal
position of a match within a partition.

Syntax
MATCH_ID()

Notes
Pattern matching functions must be used in MATCH Clause syntax; for example, if you call
MATCH_ID() on its own, HP Vertica returns the following error message:
=> SELECT match_id();
ERROR: query with pattern matching function match_id must include a MATCH clause

Example
Note: This example uses the schema defined in Event Series Pattern Matching in the
Programmer's Guide. For a more detailed example, see that topic.
The following statement analyzes users' browsing history on a site called website2.com and
identifies patterns where the user reached website2.com from another Web site (Entry in the
MATCH clause) and browsed to any number of other pages (Onsite) before making a purchase
(Purchase). The query also outputs values for the MATCH_ID(), which represents a sequential
number of the match.
SELECT uid,
sid,
ts,
refurl,
pageurl,
action,
match_id()
FROM clickstream_log
MATCH
(PARTITION BY uid, sid ORDER BY ts
DEFINE
Entry
AS RefURL NOT ILIKE '%website2.com%' AND PageURL ILIKE '%website2.com%',
Onsite
AS PageURL ILIKE
'%website2.com%' AND Action='V',
Purchase AS PageURL ILIKE
'%website2.com%' AND Action = 'P'
PATTERN
P AS (Entry Onsite* Purchase)
RESULTS ALL ROWS);
uid | sid |
ts
|
refurl
|
pageurl
| action | match_id
-----+-----+----------+----------------------+----------------------+--------+----------

HP Vertica Analytic Database (7.0.x)

Page 433 of 1539

SQL Reference Manual
SQL Functions

2 | 100
2 | 100
2 | 100
1 | 100
1 | 100
1 | 100
1 | 100
(7 rows)

|
|
|
|
|
|
|

12:10:00
12:11:00
12:13:00
12:00:00
12:01:00
12:02:00
12:03:00

|
|
|
|
|
|
|

website1.com
website2.com/home
website2.com/forks
website1.com
website2.com/home
website2.com/floby
website2.com/shamwow

|
|
|
|
|
|
|

website2.com/home
website2.com/forks
website2.com/buy
website2.com/home
website2.com/floby
website2.com/shamwow
website2.com/buy

|
|
|
|
|
|
|

V
V
P
V
V
V
P

|
|
|
|
|
|
|

1
2
3
1
2
3
4

See Also
l

MATCH Clause

l

EVENT_NAME
PATTERN_ID

l
l

PATTERN_ID
Returns an integer value that is a partition-wide unique identifier for the instance of the pattern that
matched.

Syntax
PATTERN_ID()

Notes
Pattern matching functions must be used in MATCH Clause syntax; for example, if call
PATTERN_ID() on its own, HP Vertica returns the following error message:
=> SELECT pattern_id();
ERROR: query with pattern matching function pattern_id must include a MATCH clause

Example
Note: This example uses the schema defined in Event Series Pattern Matching in the
Programmer's Guide. For a more detailed example, see that topic.
The following statement analyzes users' browsing history on website2.com and identifies patterns
where the user landed on website2.com from another Web site (Entry) and browsed to any number
of other pages (Onsite) before making a purchase (Purchase). The query also outputs values for
PATTERN_ID(), which represents the partition-wide identifier for the instance of the pattern that
matched.

HP Vertica Analytic Database (7.0.x)

Page 434 of 1539

SQL Reference Manual
SQL Functions

SELECT uid,
sid,
ts,
refurl,
pageurl,
action,
pattern_id()
FROM clickstream_log
MATCH
(PARTITION BY uid, sid ORDER BY ts
DEFINE
Entry
AS RefURL NOT ILIKE '%website2.com%' AND PageURL ILIKE '%website2.com%',
Onsite
AS PageURL ILIKE
'%website2.com%' AND Action='V',
Purchase AS PageURL ILIKE
'%website2.com%' AND Action = 'P'
PATTERN
P AS (Entry Onsite* Purchase)
RESULTS ALL ROWS);
uid | sid |
ts
|
refurl
|
pageurl
| action | pattern_id
-----+-----+----------+----------------------+----------------------+--------+----------2 | 100 | 12:10:00 | website1.com
| website2.com/home
| V
|
1
2 | 100 | 12:11:00 | website2.com/home
| website2.com/forks
| V
|
1
2 | 100 | 12:13:00 | website2.com/forks
| website2.com/buy
| P
|
1
1 | 100 | 12:00:00 | website1.com
| website2.com/home
| V
|
1
1 | 100 | 12:01:00 | website2.com/home
| website2.com/floby
| V
|
1
1 | 100 | 12:02:00 | website2.com/floby
| website2.com/shamwow | V
|
1
1 | 100 | 12:03:00 | website2.com/shamwow | website2.com/buy
| P
|
1
(7 rows)

See Also
l

MATCH Clause

l

EVENT_NAME
MATCH_ID

l
l

HP Vertica Analytic Database (7.0.x)

Page 435 of 1539

SQL Reference Manual
SQL Functions

Regular Expression Functions
A regular expression lets you perform pattern matching on strings of characters. The regular
expression syntax allows you to very precisely define the pattern used to match strings, giving you
much greater control than the wildcard matching used in the LIKE predicate. HP Vertica's regular
expression functions let you perform tasks such as determining if a string value matches a pattern,
extracting a portion of a string that matches a pattern, or counting the number of times a string
matches a pattern.
HP Vertica uses the Perl Compatible Regular Expression library (PCRE) to evaluate regular
expressions. As its name implies, PCRE's regular expression syntax is compatible with the syntax
used by the Perl 5 programming language. You can read PCRE's documentation on its regular
expression syntax. However, you might find the Perl Regular Expressions Documentation to be a
better introduction, especially if you are unfamiliar with regular expressions.
Note: The regular expression functions only operate on valid UTF-8 strings. If you attempt to
use a regular expression function on a string that is not valid UTF-8, then the query fails with an
error. To prevent an error from occurring, you can use the ISUTF8 function as a clause in the
statement to ensure the strings you want to pass to the regular expression functions are
actually valid UTF-8 strings, or you can use the 'b' argument to treat the strings as binary
octets rather than UTF-8 encoded strings.

ISUTF8
Tests whether a string is a valid UTF-8 string. Returns true if the string conforms to UTF-8
standards, and false otherwise. This function is useful to test strings for UTF-8 compliance before
passing them to one of the regular expression functions, such as REGEXP_LIKE, which expect
UTF-8 characters by default.
ISUTF8 checks for invalid UTF8 byte sequences, according to UTF-8 rules:
l

invalid bytes

l

an unexpected continuation byte

l

a start byte not followed by enough continuation bytes

l

an Overload Encoding

The presence of an invalid UTF8 byte sequence results in a return value of false.

Syntax
ISUTF8( string );

Parameters
string

The string to test for UTF-8 compliance.

HP Vertica Analytic Database (7.0.x)

Page 436 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT ISUTF8(E'\xC2\xBF'); -- UTF-8 INVERTED QUESTION MARK ISUTF8
-------t
(1 row)
=> SELECT ISUTF8(E'\xC2\xC0'); -- UNDEFINED UTF-8 CHARACTER
ISUTF8
-------f
(1 row)

REGEXP_COUNT
Returns the number times a regular expression matches a string.

Syntax
REGEXP_COUNT( string, pattern [, position [, regexp_modifier ] ] )

Parameters
string

The string to be searched for matches.

pattern

The regular expression to search for within the string. The syntax of the regular
expression is compatible with the Perl 5 regular expression syntax. See the
Perl Regular Expressions Documentation for details.

position

The number of characters from the start of the string where the function should
start searching for matches. The default value, 1, means to start searching for
a match at the first (leftmost) character. Setting this parameter to a value
greater than 1 starts searching for a match to the pattern that many characters
into the string.

HP Vertica Analytic Database (7.0.x)

Page 437 of 1539

SQL Reference Manual
SQL Functions

regexp_modifier

A string containing one or more single-character flags that change how the
regular expression is matched against the string:
b

Treat strings as binary octets rather than UTF-8 characters.

c

Forces the match to be case sensitive (the default).

i

Forces the match to be case insensitive.

m

Treats the string being matched as multiple lines. With this modifier, the
start of line (^) and end of line ($) regular expression operators match line
breaks (\n) within the string. Ordinarily, these operators only match the
start and end of the string.

n

Allows the single character regular expression operator (.) to match a
newline (\n). Normally, the . operator will match any character except a
newline.

x

Allows you to document your regular expressions. It causes all
unescaped space characters and comments in the regular expression to
be ignored. Comments start with a hash character (#) and end with a
newline. All spaces in the regular expression that you want to be
matched in strings must be escaped with a backslash (\) character.

Notes
This function operates on UTF-8 strings using the default locale, even if the locale has been set to
something else.
If you are porting a regular expression query from an Oracle database, remember that Oracle
considers a zero-length string to be equivalent to NULL, while HP Vertica does not.

Examples
Count the number of occurrences of the substring "an" in the string "A man, a plan, a canal,
Panama."
=> SELECT REGEXP_COUNT('a man, a plan, a canal: Panama', 'an');
REGEXP_COUNT
-------------4
(1 row)

Find the number of occurrences of the substring "an" in the string "a man, a plan, a canal: Panama"
starting with the fifth character.
=> SELECT REGEXP_COUNT('a man, a plan, a canal: Panama', 'an',5);
REGEXP_COUNT

HP Vertica Analytic Database (7.0.x)

Page 438 of 1539

SQL Reference Manual
SQL Functions

-------------3
(1 row)

Find the number of occurrences of a substring containing a lower-case character followed by "an."
In the first example, the query does not have a modifier. In the second example, the "i" query
modifier is used to force the regular expression to ignore case.
=> SELECT REGEXP_COUNT('a man, a plan, a canal: Panama', '[a-z]an');
REGEXP_COUNT
-------------3
(1 row)
=> SELECT REGEXP_COUNT('a man, a plan, a canal: Panama', '[a-z]an', 1, 'i');
REGEXP_COUNT
-------------4

REGEXP_INSTR
Returns the starting or ending position in a string where a regular expression matches. This function
returns 0 if no match for the regular expression is found in the string.

Syntax
REGEXP_INSTR( string, pattern [, position [, occurrence ... [, return_position [, regexp_modif
ier ]
... [, captured_subexp ] ] ] ] )

Parameters
string

The string to search for the pattern.

pattern

The regular expression to search for within the string. The syntax of the regular
expression is compatible with the Perl 5 regular expression syntax. See the
Perl Regular Expressions Documentation for details.

position

The number of characters from the start of the string where the function should
start searching for matches. The default value, 1, means to start searching for
a match at the first (leftmost) character. Setting this parameter to a value
greater than 1 starts searching for a match to the pattern that many characters
into the string.

HP Vertica Analytic Database (7.0.x)

Page 439 of 1539

SQL Reference Manual
SQL Functions

occurrence

Controls which occurrence of a match between the string and the pattern is
returned. With the default value (1), the function returns the position of the first
substring that matches the pattern. You can use this parameter to find the
position of additional matches between the string and the pattern. For example,
set this parameter to 3 to find the position of the third substring that matched
the pattern.

return_position

Sets the position within the string that is returned. When set to the default
value (0), this function returns the position in the string of the first character of
the substring that matched the pattern. If you set this value to 1, the function
returns the position of the first character after the end of the matching
substring.

regexp_modifier

A string containing one or more single-character flags that change how the
regular expression is matched against the string:

captured_subexp

b

Treat strings as binary octets rather than UTF-8 characters.

c

Forces the match to be case sensitive (the default).

i

Forces the match to be case insensitive.

m

Treats the string being matched as multiple lines. With this modifier, the
start of line (^) and end of line ($) regular expression operators match line
breaks (\n) within the string. Ordinarily, these operators only match the
start and end of the string.

n

Allows the single character regular expression operator (.) to match a
newline (\n). Normally, the . operator will match any character except a
newline.

x

Allows you to document your regular expressions. It causes all
unescaped space characters and comments in the regular expression to
be ignored. Comments start with a hash character (#) and end with a
newline. All spaces in the regular expression that you want to be
matched in strings must be escaped with a backslash (\) character.

The captured subexpression whose position should be returned. If omitted or
set to 0, the function returns the position of the first character in the entire
string that matched the regular expression. If set to 1 through 9, the function
returns the subexpression captured by the corresponding set of parentheses in
the regular expression. For example, setting this value to 3 returns the
substring captured by the third set of parentheses in the regular expression.
Note: The subexpressions are numbered left to right, based on the
appearance of opening parenthesis, so nested regular expressions . For
example, in the regular expression \s*(\w+\s+(\w+)), subexpression 1
is the one that captures everything but any leading whitespaces.

HP Vertica Analytic Database (7.0.x)

Page 440 of 1539

SQL Reference Manual
SQL Functions

Notes
This function operates on UTF-8 strings using the default locale, even if the locale has been set to
something else.
If you are porting a regular expression query from an Oracle database, remember that Oracle
considers a zero-length string to be equivalent to NULL, while HP Vertica does not.

Examples
Find the first occurrence of a sequence of letters starting with the letter e and ending with the letter y
in the phrase "easy come, easy go."
=> SELECT REGEXP_INSTR('easy come, easy go','e\w*y'); REGEXP_INSTR
-------------1
(1 row)

Find the first occurrence of a sequence of letters starting with the letter e and ending with the letter y
starting at the second character in the string "easy come, easy go."
=> SELECT REGEXP_INSTR('easy come, easy go','e\w*y',2); REGEXP_INSTR
-------------12
(1 row)

Find the second sequence of letters starting with the letter e and ending with the letter y in the string
"easy come, easy go" starting at the first character.
=> SELECT REGEXP_INSTR('easy come, easy go','e\w*y',1,2); REGEXP_INSTR
-------------12
(1 row)

Find the position of the first character after the first whitespace in the string "easy come, easy go."
=> SELECT REGEXP_INSTR('easy come, easy go','\s',1,1,1); REGEXP_INSTR
-------------6
(1 row)

Find the position of the start of the third word in a string by capturing each word as a subexpression,
and returning the third subexpression's start position.
=> SELECT REGEXP_INSTR('one two three','(\w+)\s+(\w+)\s+(\w+)', 1,1,0,'',3); REGEXP_INSTR
-------------9
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 441 of 1539

SQL Reference Manual
SQL Functions

REGEXP_LIKE
Returns true if the string matches the regular expression. This function is similar to the LIKEpredicate, except that it uses regular expressions rather than simple wildcard character matching.

Syntax
REGEXP_LIKE( string, pattern [, modifiers ] )

Parameters
string

The string to match against the regular expression.

pattern

A string containing the regular expression to match against the string. The syntax of
the regular expression is compatible with the Perl 5 regular expression syntax. See
the Perl Regular Expressions Documentation for details.

modifiers

A string containing one or more single-character flags that change how the regular
expression is matched against the string:
b

Treat strings as binary octets rather than UTF-8 characters.

c

Forces the match to be case sensitive (the default).

i

Forces the match to be case insensitive.

m

Treats the string being matched as multiple lines. With this modifier, the start of
line (^) and end of line ($) regular expression operators match line breaks (\n)
within the string. Ordinarily, these operators only match the start and end of the
string.

n

Allows the single character regular expression operator (.) to match a newline
(\n). Normally, the . operator will match any character except a newline.

x

Allows you to document your regular expressions. It causes all unescaped
space characters and comments in the regular expression to be ignored.
Comments start with a hash character (#) and end with a newline. All spaces in
the regular expression that you want to be matched in strings must be escaped
with a backslash (\) character.

Notes
This function operates on UTF-8 strings using the default locale, even if the locale has been set to
something else.
If you are porting a regular expression query from an Oracle database, remember that Oracle
considers a zero-length string to be equivalent to NULL, while HP Vertica does not.

HP Vertica Analytic Database (7.0.x)

Page 442 of 1539

SQL Reference Manual
SQL Functions

Examples
This example creates a table containing several strings to demonstrate regular expressions.
=> CREATE TABLE t (v VARCHAR);
CREATE TABLE
=> CREATE PROJECTION t1 AS SELECT * FROM t;
CREATE PROJECTION
=> COPY t FROM stdin;
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> aaa
>> Aaa
>> abc
>> abc1
>> 123
>> \.
=> SELECT * FROM t;
v
------aaa
Aaa
abc
abc1
123
(5 rows)

Select all records in the table that contain the letter "a."
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'a');
v
-----Aaa
aaa
abc
abc1
(4 rows)

Select all of the rows in the table that start with the letter "a."
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'^a');
v
-----aaa
abc
abc1
(3 rows)

Select all rows that contain the substring "aa."
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'aa');
v

HP Vertica Analytic Database (7.0.x)

Page 443 of 1539

SQL Reference Manual
SQL Functions

----Aaa
aaa
(2 rows)

Select all rows that contain a digit.
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'\d');
v
-----123
abc1
(2 rows)

Select all rows that contain the substring "aaa."
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'aaa');
v
----aaa
(1 row)

Select all rows that contain the substring "aaa" using case insensitive matching.
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'aaa', 'i');
v
----Aaa
aaa
(2 rows)

Select rows that contain the substring "a b c."
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'a b c');
v
--(0 rows)

Select rows that contain the substring "a b c" ignoring space within the regular expression.
=> SELECT v FROM t WHERE REGEXP_LIKE(v,'a b c','x');
v
-----abc
abc1
(2 rows)

Add multi-line rows to demonstrate using the "m" modifier.
=> COPY t FROM stdin RECORD TERMINATOR '!';

HP Vertica Analytic Database (7.0.x)

Page 444 of 1539

SQL Reference Manual
SQL Functions

Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> Record 1 line 1
>> Record 1 line 2
>> Record 1 line 3!
>> Record 2 line 1
>> Record 2 line 2
>> Record 2 line 3!
>> \.

Select rows that start with the substring "Record" and end with the substring "line 2."
=> SELECT v from t WHERE REGEXP_LIKE(v,'^Record.*line 2$'); v
--(0 rows)

Select rows that start with the substring "Record" and end with the substring "line 2," treating
multiple lines as separate strings.
=> SELECT v from t WHERE REGEXP_LIKE(v,'^Record.*line 2$','m');
v
-------------------------------------------------Record 2
Record 2
Record 2
Record 1
Record 1
Record 1
(2 rows)

line
line
line
line
line
line

1
2
3
1
2
3

REGEXP_REPLACE
Replace all occurrences of a substring that match a regular expression with another substring. It is
similar to the REPLACE function, except it uses a regular expression to select the substring to be
replaced.

Syntax
REGEXP_REPLACE( string, target [, replacement [, position [, occurrence ... [, regexp_modifier
s ] ] ] ] )

Parameters
string

The string whose to be searched and replaced.

target

The regular expression to search for within the string. The syntax of the regular
expression is compatible with the Perl 5 regular expression syntax. See the
Perl Regular Expressions Documentation for details.

HP Vertica Analytic Database (7.0.x)

Page 445 of 1539

SQL Reference Manual
SQL Functions

replacement

The string to replace matched substrings. If not supplied, the matched
substrings are deleted. This string can contain baccalaureates for substrings
captured by the regular expression. The first captured substring is inserted into
the replacement string using \1, the second \2, and so on.

position

The number of characters from the start of the string where the function should
start searching for matches. The default value, 1, means to start searching for
a match at the first (leftmost) character. Setting this parameter to a value
greater than 1 starts searching for a match to the pattern that many characters
into the string.

occurrence

Controls which occurrence of a match between the string and the pattern is
replaced. With the default value (0), the function replaces all matching
substrings with the replacement string. For any value above zero, the function
replaces just a single occurrence. For example, set this parameter to 3 to
replace the third substring that matched the pattern.

regexp_modifier

A string containing one or more single-character flags that change how the
regular expression is matched against the string:
b

Treat strings as binary octets rather than UTF-8 characters.

c

Forces the match to be case sensitive (the default).

i

Forces the match to be case insensitive.

m

Treats the string being matched as multiple lines. With this modifier, the
start of line (^) and end of line ($) regular expression operators match line
breaks (\n) within the string. Ordinarily, these operators only match the
start and end of the string.

n

Allows the single character regular expression operator (.) to match a
newline (\n). Normally, the . operator will match any character except a
newline.

x

Allows you to document your regular expressions. It causes all
unescaped space characters and comments in the regular expression to
be ignored. Comments start with a hash character (#) and end with a
newline. All spaces in the regular expression that you want to be
matched in strings must be escaped with a backslash (\) character.

Notes
This function operates on UTF-8 strings using the default locale, even if the locale has been set to
something else.
If you are porting a regular expression query from an Oracle database, remember that Oracle
considers a zero-length string to be equivalent to NULL, while HP Vertica does not.

HP Vertica Analytic Database (7.0.x)

Page 446 of 1539

SQL Reference Manual
SQL Functions

Another key difference between Oracle and HP Vertica is that HP Vertica can handle an unlimited
number of captured subexpressions where Oracle is limited to nine. In HP Vertica, you are able to
use \10 in the replacement pattern to access the substring captured by the tenth set of parentheses
in the regular expression. In Oracle, \10 is treated as the substring captured by the first set of
parentheses followed by a zero. To force the same behavior in HP Vertica, use the \g
backreference with the number of the captured subexpression enclosed in curly braces. For
example, \g{1}0 is the substring captured by the first set of parentheses followed by a zero. You
can also name your captured subexpressions, to make your regular expressions less ambiguous.
See the PCRE documentation for details.

Examples
Find groups of "word characters" (letters, numbers and underscore) ending with "thy" in the string
"healthy, wealthy, and wise" and replace them with nothing.
=> SELECT REGEXP_REPLACE('healthy, wealthy, and wise','\w+thy');
REGEXP_REPLACE
---------------, , and wise
(1 row)

Find groups of word characters ending with "thy" and replace with the string "something."
=> SELECT REGEXP_REPLACE('healthy, wealthy, and wise','\w+thy', 'something');
REGEXP_REPLACE
-------------------------------something, something, and wise
(1 row)

Find groups of word characters ending with "thy" and replace with the string "something" starting at
the third character in the string.
=> SELECT REGEXP_REPLACE('healthy, wealthy, and wise','\w+thy', 'something', 3);
REGEXP_REPLACE
---------------------------------hesomething, something, and wise
(1 row)

Replace the second group of word characters ending with "thy" with the string "something."
=> SELECT REGEXP_REPLACE('healthy, wealthy, and wise','\w+thy', 'something', 1, 2);
REGEXP_REPLACE
-----------------------------healthy, something, and wise
(1 row)

Find groups of word characters ending with "thy" capturing the letters before the "thy", and replace
with the captured letters plus the letters "ish."
=> SELECT REGEXP_REPLACE('healthy, wealthy, and wise','(\w+)thy', '\1ish');

HP Vertica Analytic Database (7.0.x)

Page 447 of 1539

SQL Reference Manual
SQL Functions

REGEXP_REPLACE
---------------------------healish, wealish, and wise
(1 row)

Create a table to demonstrate replacing strings in a query.
=> CREATE TABLE customers (name varchar(50), phone varchar(11));
CREATE TABLE
=> CREATE PROJECTION customers1 AS SELECT * FROM customers;
CREATE PROJECTION
=> COPY customers FROM stdin;
Enter data to be copied followed by a newline.
End with a backslash and a period on a line by itself.
>> Able, Adam|17815551234
>> Baker,Bob|18005551111
>> Chu,Cindy|16175559876
>> Dodd,Dinara|15083452121
>> \.

Query the customers, using REGEXP_REPLACE to format the phone numbers.
=> SELECT name, REGEXP_REPLACE(phone, '(\d)(\d{3})(\d{3})(\d{4})', '\1-(\2) \3-\4') as ph
one FROM customers;
name
|
phone
-------------+-----------------Able, Adam | 1-(781) 555-1234
Baker,Bob
| 1-(800) 555-1111
Chu,Cindy
| 1-(617) 555-9876
Dodd,Dinara | 1-(508) 345-2121
(4 rows)

REGEXP_SUBSTR
Returns the substring that matches a regular expression within a string. If no matches are found,
this function returns NULL. This is different than an empty string, which can be returned by this
function if the regular expression matches a zero-length string.

Syntax
REGEXP_SUBSTR( string, pattern [, position [,
d_subexp ] ] ] )

occurrence ... [, regexp_modifier ] [, capture

Parameters
string

The string to search for the pattern.

pattern

The regular expression to find the substring to be extracted. The syntax of the
regular expression is compatible with the Perl 5 regular expression syntax.
See the Perl Regular Expressions Documentation for details.

HP Vertica Analytic Database (7.0.x)

Page 448 of 1539

SQL Reference Manual
SQL Functions

position

The character in the string where the search for a match should start. The
default value, 1, starts the search at the beginning of the string. If you supply
a value larger than 1 for this parameter, the function will start searching that
many characters into the string.

occurrence

Controls which matching substring is returned by the function. When given
the default value (1), the function will return the first matching substring it
finds in the string. By setting this value to a number greater than 1, this
function will return subsequent matching substrings. For example, setting this
parameter to 3 will return the third substring that matches the regular
expression within the string.

regexp_modifier

A string containing one or more single-character flags that change how the
regular expression is matched against the string:

captured_subexp

b

Treat strings as binary octets rather than UTF-8 characters.

c

Forces the match to be case sensitive (the default).

i

Forces the match to be case insensitive.

m

Treats the string being matched as multiple lines. With this modifier, the
start of line (^) and end of line ($) regular expression operators match
line breaks (\n) within the string. Ordinarily, these operators only match
the start and end of the string.

n

Allows the single character regular expression operator (.) to match a
newline (\n). Normally, the . operator will match any character except a
newline.

x

Allows you to document your regular expressions. It causes all
unescaped space characters and comments in the regular expression to
be ignored. Comments start with a hash character (#) and end with a
newline. All spaces in the regular expression that you want to be
matched in strings must be escaped with a backslash (\) character.

The captured subexpression whose contents should be returned. If omitted or
set to 0, the function returns the entire string that matched the regular
expression. If set to 1 through 9, the function returns the subexpression
captured by the corresponding set of parentheses in the regular expression.
For example, setting this value to 3 returns the substring captured by the third
set of parentheses in the regular expression.
Note: The subexpressions are numbered left to right, based on the
appearance of opening parenthesis, so nested regular expressions . For
example, in the regular expression \s*(\w+\s+(\w+)), subexpression 1
is the one that captures everything but any leading whitespaces.

HP Vertica Analytic Database (7.0.x)

Page 449 of 1539

SQL Reference Manual
SQL Functions

Notes
This function operates on UTF-8 strings using the default locale, even if the locale has been set to
something else.
If you are porting a regular expression query from an Oracle database, remember that Oracle
considers a zero-length string to be equivalent to NULL, while HP Vertica does not.

Examples
Select the first substring of letters that end with "thy."
=> SELECT REGEXP_SUBSTR('healthy, wealthy, and wise','\w+thy');
REGEXP_SUBSTR
--------------healthy
(1 row)

Select the first substring of letters that ends with "thy" starting at the second character in the string.
=> SELECT REGEXP_SUBSTR('healthy, wealthy, and wise','\w+thy',2);
REGEXP_SUBSTR
--------------ealthy
(1 row)

Select the second substring of letters that ends with "thy."
=> SELECT REGEXP_SUBSTR('healthy, wealthy, and wise','\w+thy',1,2);
REGEXP_SUBSTR
--------------wealthy
(1 row)

Return the contents of the third captured subexpression, which captures the third word in the string.
=> SELECT REGEXP_SUBSTR('one two three', '(\w+)\s+(\w+)\s+(\w+)', 1, 1, '', 3);
REGEXP_SUBSTR
--------------three
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 450 of 1539

SQL Reference Manual
SQL Functions

Sequence Functions
The sequence functions provide simple, multiuser-safe methods for obtaining successive
sequence values from sequence objects.

NEXTVAL
Returns the next value in a sequence. Calling NEXTVAL after creating a sequence initializes the
sequence with its default value, incrementing a positive value for ascending sequences, and
decrementing a negative value for descending sequences. Thereafter, calling NEXTVAL
increments the sequence value. NEXTVAL is used in INSERT, COPY, and SELECT statements
to create unique values.

Behavior Type
Volatile

Syntax
[[db-name.]schema.]sequence_name.NEXTVALNEXTVAL('[[db-name.]schema.]sequence_name')

Parameters

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

sequence_name

Identifies the sequence for which to determine the next value.

HP Vertica Analytic Database (7.0.x)

Page 451 of 1539

SQL Reference Manual
SQL Functions

Permissions
l

SELECT privilege on sequence

l

USAGE privilege on sequence schema

Examples
The following example creates an ascending sequence called my_seq, starting at 101:
CREATE SEQUENCE my_seq START 101;

The following command generates the first number in the sequence:
SELECT NEXTVAL('my_seq');
nextval
--------101
(1 row)

The following command generates the next number in the sequence:
SELECT NEXTVAL('my_seq');
nextval
--------102
(1 row)

The following command illustrates how NEXTVAL is evaluated on a per-row basis, so in this
example, both calls to NEXTVAL yield the same result:
SELECT NEXTVAL('my_seq'), NEXTVAL('my_seq');
nextval | nextval
---------+--------103 |
103
(1 row)

The following example illustrates how the NEXTVAL is always evaluated first (and here, increments
the my_seq sequence from its previous value), even when CURRVAL precedes NEXTVAL:
SELECT CURRVAL('my_seq'), NEXTVAL('my_seq');
currval | nextval
---------+--------104 |
104
(1 row)

The following example shows how to use NEXTVAL in a table SELECT statement. Notice that the
nextval column is incremented by 1 again:

HP Vertica Analytic Database (7.0.x)

Page 452 of 1539

SQL Reference Manual
SQL Functions

SELECT NEXTVAL('my_seq'), product_description FROM product_dimension LIMIT 10;
nextval |
product_description
---------+-----------------------------105 | Brand #2 bagels
106 | Brand #1 butter
107 | Brand #6 chicken noodle soup
108 | Brand #5 golf clubs
109 | Brand #4 brandy
110 | Brand #3 lamb
111 | Brand #11 vanilla ice cream
112 | Brand #10 ground beef
113 | Brand #9 camera case
114 | Brand #8 halibut
(10 rows)

See Also
l

ALTER SEQUENCE

l

CREATE SEQUENCE

l

CURRVAL

l

DROP SEQUENCE

l

Using Named Sequences

l

Sequence Privileges

CURRVAL
For a sequence generator, returns the LAST value across all nodes returned by a previous
invocation of NEXTVAL in the same session. If there were no calls to NEXTVAL after the
sequence was created, an error is returned.

Behavior Type
Volatile

Syntax
[[db-name.]schema.]sequence_name.CURRVALCURRVAL('[[db-name.]schema.]sequence_name')

HP Vertica Analytic Database (7.0.x)

Page 453 of 1539

SQL Reference Manual
SQL Functions

Parameters
[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

sequence_name

Identifies the sequence for which to return the current value.

Permissions
l

SELECT privilege on sequence

l

USAGE privilege on sequence schema

Examples
The following example creates an ascending sequence called sequential, starting at 101:
CREATE SEQUENCE seq2 START 101;

You cannot call CURRVAL until after you have initiated the sequence with NEXTVAL or the
system returns an error:
SELECT CURRVAL('seq2');
ERROR: Sequence seq2 has not been accessed in the session

Use the NEXTVAL function to generate the first number for this sequence:
SELECT NEXTVAL('seq2');
nextval
--------101
(1 row)

Now you can use CURRVAL to return the current number from this sequence:

HP Vertica Analytic Database (7.0.x)

Page 454 of 1539

SQL Reference Manual
SQL Functions

SELECT CURRVAL('seq2');
currval
--------101
(1 row)

The following command shows how to use CURRVAL in a SELECT statement:
CREATE TABLE customer3 (
lname VARCHAR(25),
fname VARCHAR(25),
membership_card INTEGER,
ID INTEGER
);
INSERT INTO customer3 VALUES ('Brown' ,'Sabra', 072753, CURRVAL('my_seq'));
SELECT CURRVAL('seq2'), lname FROM customer3;
CURRVAL | lname
---------+------101 | Brown
(1 row)

The following example illustrates how the NEXTVAL is always evaluated first (and here,
increments the my_seq sequence from its previous value), even when CURRVAL precedes
NEXTVAL:
SELECT CURRVAL('my_seq'), NEXTVAL('my_seq');
currval | nextval
---------+--------102 |
102
(1 row)

See Also
l

ALTER SEQUENCE

l

CREATE SEQUENCE

l

DROP SEQUENCE
NEXTVAL

l
l

l

LAST_INSERT_ID
Returns the last value of a column whose value is automatically incremented through the AUTO_
INCREMENT or IDENTITY Column-Constraint. If multiple sessions concurrently load the same

HP Vertica Analytic Database (7.0.x)

Page 455 of 1539

SQL Reference Manual
SQL Functions

table, the returned value is the last value generated for an AUTO_INCREMENT column by an
insert in that session.

Behavior Type
Volatile

Syntax
LAST_INSERT_ID()

Privileges
l

Table owner

l

USAGE privileges on schema

Notes
l

This function works only with AUTO_INCREMENT and IDENTITY columns. See columnconstraints for the CREATE TABLE statement.

l

LAST_INSERT_ID does not work with sequence generators created through the CREATE
SEQUENCE statement.

Examples
Create a sample table called customer4.
=> CREATE TABLE customer4(
ID IDENTITY(2,2),
lname VARCHAR(25),
fname VARCHAR(25),
membership_card INTEGER
);
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Gupta', 'Saleem', 475987);

Notice that the IDENTITY column has a seed of 2, which specifies the value for the first row loaded
into the table, and an increment of 2, which specifies the value that is added to the IDENTITY value
of the previous row.
Query the table you just created:
=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 456 of 1539

SQL Reference Manual
SQL Functions

Insert some additional values:
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Lee', 'Chen', 598742);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------4
(1 row)

Query the table again:
=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
(2 rows)

Add another row:
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Davis', 'Bill', 469543);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------6
(1 row)

Query the table again:
=> SELECT * FROM customer4; ID | lname | fname
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
6 | Davis | Bill
|
469543
(3 rows)

| membership_card

See Also
l

ALTER SEQUENCE

l

CREATE SEQUENCE

HP Vertica Analytic Database (7.0.x)

Page 457 of 1539

SQL Reference Manual
SQL Functions

l

DROP SEQUENCE

l

SEQUENCES

l

Using Named Sequences

l

Sequence Privileges

HP Vertica Analytic Database (7.0.x)

Page 458 of 1539

SQL Reference Manual
SQL Functions

String Functions
String functions perform conversion, extraction, or manipulation operations on strings, or return
information about strings.
This section describes functions and operators for examining and manipulating string values.
Strings in this context include values of the types CHAR, VARCHAR, BINARY, and
VARBINARY.
Unless otherwise noted, all of the functions listed in this section work on all four data types. As
opposed to some other SQL implementations, HP Vertica keeps CHAR strings unpadded
internally, padding them only on final output. So converting a CHAR(3) 'ab' to VARCHAR(5)
results in a VARCHAR of length 2, not one with length 3 including a trailing space.
Some of the functions described here also work on data of non-string types by converting that data
to a string representation first. Some functions work only on character strings, while others work
only on binary strings. Many work for both. BINARY and VARBINARY functions ignore multibyte
UTF-8 character boundaries.
Non-binary character string functions handle normalized multibyte UTF-8 characters, as specified
by the Unicode Consortium. Unless otherwise specified, those character string functions for which
it matters can optionally specify whether VARCHAR arguments should be interpreted as octet
(byte) sequences, or as (locale-aware) sequences of UTF-8 characters. This is accomplished by
adding "USING OCTETS" or "USING CHARACTERS" (default) as a parameter to the function.
Some character string functions are stable because in general UTF-8 case-conversion, searching
and sorting can be locale dependent. Thus, LOWER is stable, while LOWERB is immutable. The
USING OCTETS clause converts these functions into their "B" forms, so they become immutable.
If the locale is set to collation=binary, which is the default, all string functions—except CHAR_
LENGTH/CHARACTER_LENGTH, LENGTH, SUBSTR, and OVERLAY—are converted to their
"B" forms and so are immutable.
BINARY implicitly converts to VARBINARY, so functions that take VARBINARY arguments work
with BINARY.

ASCII
Converts the first octet of a VARCHAR to an INTEGER.

Behavior Type
Immutable

Syntax
ASCII ( expression )

HP Vertica Analytic Database (7.0.x)

Page 459 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

(VARCHAR) is the string to convert.

Notes
l

ASCII is the opposite of the CHR function.

l

ASCII operates on UTF-8 characters, not only on single-byte ASCII characters. It continues to
get the same results for the ASCII subset of UTF-8.

Examples
Expression

Result

SELECT ASCII('A');

65

SELECT ASCII('ab');

97

SELECT ASCII(null);
SELECT ASCII('');

BIT_LENGTH
Returns the length of the string expression in bits (bytes * 8) as an INTEGER.

Behavior Type
Immutable

Syntax
BIT_LENGTH ( expression )

Parameters
expression

(CHAR or VARCHAR or BINARY or VARBINARY) is the string to convert.

Notes
BIT_LENGTH applies to the contents of VARCHAR and VARBINARY fields.

HP Vertica Analytic Database (7.0.x)

Page 460 of 1539

SQL Reference Manual
SQL Functions

Examples
Expression

Result

SELECT BIT_LENGTH('abc'::varbinary);

24

SELECT BIT_LENGTH('abc'::binary);

8

SELECT BIT_LENGTH(''::varbinary);

0

SELECT BIT_LENGTH(''::binary);

8

SELECT BIT_LENGTH(null::varbinary);
SELECT BIT_LENGTH(null::binary);
SELECT BIT_LENGTH(VARCHAR 'abc');

24

SELECT BIT_LENGTH(CHAR 'abc');

24

SELECT BIT_LENGTH(CHAR(6) 'abc');

48

SELECT BIT_LENGTH(VARCHAR(6) 'abc');

24

SELECT BIT_LENGTH(BINARY(6) 'abc');

48

SELECT BIT_LENGTH(BINARY 'abc');

24

SELECT BIT_LENGTH(VARBINARY 'abc');

24

SELECT BIT_LENGTH(VARBINARY(6) 'abc');

24

See Also
l

CHARACTER_LENGTH

l

LENGTH

l

OCTET_LENGTH

BITCOUNT
Returns the number of one-bits (sometimes referred to as set-bits) in the given VARBINARY value.
This is also referred to as the population count.

Behavior Type
Immutable

Syntax
BITCOUNT ( expression )

HP Vertica Analytic Database (7.0.x)

Page 461 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

(BINARY or VARBINARY) is the string to return.

Examples
SELECT BITCOUNT(HEX_TO_BINARY('0x10'));
bitcount
---------1
(1 row)
SELECT BITCOUNT(HEX_TO_BINARY('0xF0'));
bitcount
---------4
(1 row)
SELECT BITCOUNT(HEX_TO_BINARY('0xAB'))
bitcount
---------5
(1 row)

BITSTRING_TO_BINARY
Translates the given VARCHAR bitstring representation into a VARBINARY value.

Behavior Type
Immutable

Syntax
BITSTRING_TO_BINARY ( expression )

Parameters
expression

(VARCHAR) is the string to return.

Notes
VARBINARY BITSTRING_TO_BINARY(VARCHAR) converts data from character type (in
bitstring format) to binary type. This function is the inverse of TO_BITSTRING.
BITSTRING_TO_BINARY(TO_BITSTRING(x)) = x

HP Vertica Analytic Database (7.0.x)

Page 462 of 1539

SQL Reference Manual
SQL Functions

TO_BITSTRING(BITSTRING_TO_BINARY(x)) = x

Examples
If there are an odd number of characters in the hex value, the first character is treated as the low
nibble of the first (furthest to the left) byte.
SELECT BITSTRING_TO_BINARY('0110000101100010');
bitstring_to_binary
--------------------ab
(1 row)

If an invalid bitstring is supplied, the system returns an error:
SELECT BITSTRING_TO_BINARY('010102010');
ERROR: invalid bitstring "010102010"

BTRIM
Removes the longest string consisting only of specified characters from the start and end of a
string.

Behavior Type
Immutable

Syntax
BTRIM ( expression [ , characters-to-remove ] )

Parameters
expression

(CHAR or VARCHAR) is the string to modify

characters-to-remove

(CHAR or VARCHAR) specifies the characters to remove. The default is
the space character.

Example
SELECT BTRIM('xyxtrimyyx', 'xy');
btrim
------trim

HP Vertica Analytic Database (7.0.x)

Page 463 of 1539

SQL Reference Manual
SQL Functions

(1 row)

See Also
l

LTRIM

l

RTRIM

l

TRIM

CHARACTER_LENGTH
The CHARACTER_LENGTH() function:
l

Returns the string length in UTF-8 characters for CHAR and VARCHAR columns

l

Returns the string length in bytes (octets) for BINARY and VARBINARY columns

l

Strips the padding from CHAR expressions but not from VARCHAR expressions

l

Is identical to LENGTH() for CHAR and VARCHAR. For binary types, CHARACTER_LENGTH
() is identical to OCTET_LENGTH().

Behavior Type
Immutable if USING OCTETS, stable otherwise.
Syntax
[ CHAR_LENGTH | CHARACTER_LENGTH ] ( expression , ... [ USING { CHARACTERS | OCTETS } ] )

Parameters
expression

(CHAR or VARCHAR) is the string to measure

USING CHARACTERS | OCTETS

Determines whether the character length is expressed in characters
(the default) or octets.

Examples
SELECT CHAR_LENGTH('1234
char_length
------------4
(1 row)

'::CHAR(10), USING OCTETS);

HP Vertica Analytic Database (7.0.x)

Page 464 of 1539

SQL Reference Manual
SQL Functions

SELECT CHAR_LENGTH('1234
char_length
------------6
(1 row)

'::VARCHAR(10));

SELECT CHAR_LENGTH(NULL::CHAR(10)) IS NULL;
?column?
---------t
(1 row)

See Also
l

BIT_LENGTH

CHR
Converts the first octet of an INTEGER to a VARCHAR.

Behavior Type
Immutable

Syntax
CHR ( expression )

Parameters
expression

(INTEGER) is the string to convert and is masked to a single octet.

Notes
l

CHR is the opposite of the ASCII function.

l

CHR operates on UTF-8 characters, not only on single-byte ASCII characters. It continues to
get the same results for the ASCII subset of UTF-8.

Examples
Expression

Result

SELECT CHR(65);

A

HP Vertica Analytic Database (7.0.x)

Page 465 of 1539

SQL Reference Manual
SQL Functions

SELECT CHR(65+32);

a

SELECT CHR(null);

CONCAT
Used to concatenate two or more VARBINARY strings. The return value is of type VARBINARY.

Syntax
CONCAT ('a','b')

Behavior Type
Immutable

Parameters
a

First VARBINARY string.

b

Second VARBINARY string.

Example
=> SELECT CONCAT ('A','B'); CONCAT
-------AB
(1 row)

DECODE
Compares expression to each search value one by one. If expression is equal to a search, the
function returns the corresponding result. If no match is found, the function returns default. If default
is omitted, the function returns null.

Behavior Type
Immutable

Syntax
DECODE ( expression, search, result [ , search, result ]...[, default ] );

HP Vertica Analytic Database (7.0.x)

Page 466 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

The value to compare.

search

The value compared against expression.

result

The value returned, if expression is equal to search.

default

Optional. If no matches are found, DECODE returns default. If default is omitted,
then DECODE returns NULL (if no matches are found).

Notes
DECODE is similar to the IF-THEN-ELSE and CASE expression:
CASE expressionWHEN search THEN result
[WHEN search THEN result]
[ELSE default];

The arguments can have any data type supported by HP Vertica. The result types of individual
results are promoted to the least common type that can be used to represent all of them. This leads
to a character string type, an exact numeric type, an approximate numeric type, or a DATETIME
type, where all the various result arguments must be of the same type grouping.

Example
The following example converts numeric values in the weight column from the product_dimension
table to descriptive values in the output.
SELECT
2,
50,
71,
99,

product_description, DECODE(weight,
'Light',
'Medium',
'Heavy',
'Call for help',
'N/A')
FROM product_dimension
WHERE category_description = 'Food'
AND department_description = 'Canned Goods'
AND sku_number BETWEEN 'SKU-#49750' AND 'SKU-#49999'
LIMIT 15;
product_description
|
case
-----------------------------------+--------------Brand #499 canned corn
| N/A
Brand #49900 fruit cocktail
| Medium
Brand #49837 canned tomatoes
| Heavy
Brand #49782 canned peaches
| N/A
Brand #49805 chicken noodle soup | N/A
Brand #49944 canned chicken broth | N/A
Brand #49819 canned chili
| N/A
Brand #49848 baked beans
| N/A

HP Vertica Analytic Database (7.0.x)

Page 467 of 1539

SQL Reference Manual
SQL Functions

Brand #49989 minestrone soup
Brand #49778 canned peaches
Brand #49770 canned peaches
Brand #4977 fruit cocktail
Brand #49933 canned olives
Brand #49750 canned olives
Brand #49777 canned tomatoes
(15 rows)

|
|
|
|
|
|
|

N/A
N/A
N/A
N/A
N/A
Call for help
N/A

GREATEST
Returns the largest value in a list of expressions.

Behavior Type
Stable

Syntax
GREATEST ( expression1, expression2, ... expression-n );

Parameters
expression1, expression2, and expression-n are the expressions to be evaluated.

Notes
l

Works for all data types, and implicitly casts similar types. See Examples.

l

A NULL value in any one of the expressions returns NULL.

l

Depends on the collation setting of the locale.

Examples
This example returns 9 as the greatest in the list of expressions:

SELECT GREATEST(7, 5, 9);
greatest
---------9
(1 row)

Note that putting quotes around the integer expressions returns the same result as the first
example:

HP Vertica Analytic Database (7.0.x)

Page 468 of 1539

SQL Reference Manual
SQL Functions

SELECT GREATEST('7', '5', '9');
greatest
---------9
(1 row)

The next example returns FLOAT 1.5 as the greatest because the integer is implicitly cast to float:
SELECT GREATEST(1, 1.5);
greatest
---------1.5
(1 row)

The following example returns 'vertica' as the greatest:
SELECT GREATEST('vertica', 'analytic', 'database');
greatest
---------vertica
(1 row)

Notice this next command returns NULL:
SELECT GREATEST('vertica', 'analytic', 'database', null);
greatest
---------(1 row)

And one more:
SELECT GREATEST('sit', 'site', 'sight');
greatest
---------site
(1 row)

See Also
l

LEAST

GREATESTB
Returns its greatest argument, using binary ordering, not UTF-8 character ordering.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 469 of 1539

SQL Reference Manual
SQL Functions

Syntax
GREATESTB ( expression1, expression2, ... expression-n );

Parameters
expression1, expression2, and expression-n are the expressions to be evaluated.

Notes
l

Works for all data types, and implicitly casts similar types. See Examples.

l

A NULL value in any one of the expressions returns NULL.

l

Depends on the collation setting of the locale.

Examples
The following command selects straße as the greatest in the series of inputs:
SELECT GREATESTB('straße', 'strasse');
GREATESTB
----------straße
(1 row)

This example returns 9 as the greatest in the list of expressions:
SELECT GREATESTB(7, 5, 9);
GREATESTB
----------9
(1 row)

Note that putting quotes around the integer expressions returns the same result as the first
example:
GREATESTB
----------9
(1 row)

The next example returns FLOAT 1.5 as the greatest because the integer is implicitly cast to float:
SELECT GREATESTB(1, 1.5);
GREATESTB
----------1.5

HP Vertica Analytic Database (7.0.x)

Page 470 of 1539

SQL Reference Manual
SQL Functions

(1 row)

The following example returns vertica as the greatest:
SELECT GREATESTB('vertica', 'analytic', 'database');
GREATESTB
----------vertica
(1 row)

Notice this next command returns NULL:
SELECT GREATESTB('vertica', 'analytic', 'database', null);
GREATESTB
----------(1 row)

And one more:
SELECT GREATESTB('sit', 'site', 'sight');
GREATESTB
----------site
(1 row)

See Also
l

LEASTB

HEX_TO_BINARY
Translates the given VARCHAR hexadecimal representation into a VARBINARY value.

Behavior Type
Immutable

Syntax
HEX_TO_BINARY ( [ 0x ] expression )

Parameters
expression

(BINARY or VARBINARY) String to translate.

0x

Optional prefix.

HP Vertica Analytic Database (7.0.x)

Page 471 of 1539

SQL Reference Manual
SQL Functions

Notes
VARBINARY HEX_TO_BINARY(VARCHAR) converts data from character type in hexadecimal
format to binary type. This function is the inverse of TO_HEX.
HEX_TO_BINARY(TO_HEX(x)) = x)
TO_HEX(HEX_TO_BINARY(x)) = x)

If there are an odd number of characters in the hexadecimal value, the first character is treated as
the low nibble of the first (furthest to the left) byte.

Examples
If the given string begins with "0x" the prefix is ignored. For example:
=> SELECT HEX_TO_BINARY('0x6162') AS hex1, HEX_TO_BINARY('6162') AS hex2;
hex1 | hex2
------+-----ab
| ab
(1 row)

If an invalid hex value is given, HP Vertica returns an “invalid binary representation" error; for
example:
=> SELECT HEX_TO_BINARY('0xffgf');
ERROR: invalid hex string "0xffgf"

See Also
l

TO_HEX

HEX_TO_INTEGER
Translates the given VARCHAR hexadecimal representation into an INTEGER value.
HP Vertica completes this conversion as follows:
l

Adds the 0x prefix if it is not specified in the input

l

Casts the VARCHAR string to a NUMERIC

l

Casts the NUMERIC to an INTEGER

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 472 of 1539

SQL Reference Manual
SQL Functions

Syntax
HEX_TO_INTEGER ( [ 0x ] expression )

Parameters
expression

VARCHAR is the string to translate.

0x

Is the optional prefix.

Examples
You can enter the string with or without the Ox prefix. For example:
=> SELECT HEX_TO_INTEGER ('0aedc')
AS hex1,HEX_TO_INTEGER ('aedc') AS hex2;
hex1 | hex2
-------+------44764 | 44764
(1 row)

If you pass the function an invalid hex value, HP Vertica returns an invalid input syntax error;
for example:
=> SELECT HEX_TO_INTEGER ('0xffgf');
ERROR 3691: Invalid input syntax for numeric: "0xffgf"

See Also
l

TO_HEX

l

HEX_TO_BINARY

INET_ATON
Returns an integer that represents the value of the address in host byte order, given the dotted-quad
representation of a network address as a string.

Behavior Type
Immutable

Syntax
INET_ATON ( expression )

HP Vertica Analytic Database (7.0.x)

Page 473 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression

(VARCHAR) is the string to convert.

Notes
The following syntax converts an IPv4 address represented as the string A to an integer I. INET_
ATON trims any spaces from the right of A, calls the Linux function inet_pton, and converts the result
from network byte order to host byte order using ntohl.
INET_ATON(VARCHAR A) -> INT8 I

If A is NULL, too long, or inet_pton returns an error, the result is NULL.

Examples
The generated number is always in host byte order. In the following example, the number is
calculated as 209×256^3 + 207×256^2 + 224×256 + 40.
> SELECT INET_ATON('209.207.224.40');
inet_aton
-----------3520061480
(1 row)
> SELECT INET_ATON('1.2.3.4');
inet_aton
----------16909060
(1 row)
> SELECT TO_HEX(INET_ATON('1.2.3.4'));
to_hex
--------1020304
(1 row)

See Also
l

INET_NTOA

INET_NTOA
Returns the dotted-quad representation of the address as a VARCHAR, given a network address as
an integer in network byte order.

HP Vertica Analytic Database (7.0.x)

Page 474 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
INET_NTOA ( expression )

Parameters
expression

(INTEGER) is the network address to convert.

Notes
The following syntax converts an IPv4 address represented as integer I to a string A.
INET_NTOA converts I from host byte order to network byte order using htonl, and calls the Linux
function inet_ntop.
INET_NTOA(INT8 I) -> VARCHAR A

If I is NULL, greater than 2^32 or negative, the result is NULL.

Examples
> SELECT INET_NTOA(16909060);
inet_ntoa
----------1.2.3.4
(1 row)
> SELECT INET_NTOA(03021962);
inet_ntoa
------------0.46.28.138
(1 row)

See Also
l

INET_ATON

INITCAP
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the

HP Vertica Analytic Database (7.0.x)

Page 475 of 1539

SQL Reference Manual
SQL Functions

encoding. Prior to Release 5.1, the behavior type of this function was stable.
Capitalizes first letter of each alphanumeric word and puts the rest in lowercase.

Behavior Type
Immutable

Syntax
INITCAP ( expression )

Parameters
expression

(VARCHAR) is the string to format.

Notes
l

Depends on collation setting of the locale.

l

INITCAP is restricted to 32750 octet inputs, since it is possible for the UTF-8 representation of
result to double in size.

Examples
Expression

Result

SELECT INITCAP('high speed database');

High Speed Database

SELECT INITCAP('LINUX TUTORIAL');

Linux Tutorial

SELECT INITCAP('abc DEF 123aVC 124Btd,lAsT');

Abc Def 123Avc 124Btd,Last

SELECT INITCAP('');
SELECT INITCAP(null);

INITCAPB
Capitalizes first letter of each alphanumeric word and puts the rest in lowercase. Multibyte
characters are not converted and are skipped.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 476 of 1539

SQL Reference Manual
SQL Functions

Syntax
INITCAPB ( expression )

Parameters
expression

(VARCHAR) is the string to format.

Notes
Depends on collation setting of the locale.

Examples
Expression

Result

SELECT INITCAPB('étudiant');

éTudiant

SELECT INITCAPB('high speed database');

High Speed Database

SELECT INITCAPB('LINUX TUTORIAL');

Linux Tutorial

SELECT INITCAPB('abc DEF 123aVC 124Btd,lAsT');

Abc Def 123Avc 124Btd,Last

SELECT INITCAPB('');
SELECT INITCAPB(null);

INSERT
Inserts a character string into a specified location in another character string.

Syntax
INSERT( 'string1', n, m, 'string2');

Behavior Type
Immutable

Parameters
string1

(VARCHAR) Is the string in which to insert the new string.

HP Vertica Analytic Database (7.0.x)

Page 477 of 1539

SQL Reference Manual
SQL Functions

n

A character of type INTEGER that represents the starting point for the insertion within
string1. You specify the number of characters from the first character in string1 as the
starting point for the insertion. For example, to insert characters before "c", in the string
"abcdef," enter 3.

m

A character of type INTEGER that represents the the number of characters in string1 (if
any) that should be replaced by the insertion. For example,if you want the insertion to
replace the letters "cd" in the string "abcdef, " enter 2.

string2

(VARCHAR) Is the string to be inserted.

Example
The following example changes the string Warehouse to Storehouse using the INSERT function:
=> SELECT INSERT ('Warehouse',1,3,'Stor');
INSERT
-----------Storehouse
(1 row)

INSTR
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Searches string for substring and returns an integer indicating the position of the character in string
that is the first character of this occurrence. The return value is based on the character position of
the identified character.

Behavior Type
Immutable

Syntax
INSTR ( string , substring [, position [, occurrence ] ] )

Parameters
string

(CHAR or VARCHAR, or BINARY or VARBINARY) Text expression to search.

substring

(CHAR or VARCHAR, or BINARY or VARBINARY) String to search for.

HP Vertica Analytic Database (7.0.x)

Page 478 of 1539

SQL Reference Manual
SQL Functions

position

Nonzero integer indicating the character of string where HP Vertica begins the
search. If position is negative, then HP Vertica counts backward from the end of
string and then searches backward from the resulting position. The first character
of string occupies the default position 1, and position cannot be 0.

occurrence

Integer indicating which occurrence of string HP Vertica searches. The value of
occurrence must be positive (greater than 0), and the default is 1.

Notes
Both position and occurrence must be of types that can resolve to an integer. The default values of
both parameters are 1, meaning HP Vertica begins searching at the first character of string for the
first occurrence of substring. The return value is relative to the beginning of string, regardless of the
value of position, and is expressed in characters.
If the search is unsuccessful (that is, if substring does not appear occurrence times after the
position character of string, the return value is 0.

Examples
The first example searches forward in string ‘abc’ for substring ‘b’. The search returns the position in
‘abc’ where ‘b’ occurs, or position 2. Because no position parameters are given, the default search
starts at ‘a’, position 1.
SELECT INSTR('abc', 'b');
INSTR
------2
(1 row)

The following three examples use character position to search backward to find the position of a
substring.
Note: Although it might seem intuitive that the function returns a negative integer, the position
of n occurrence is read left to right in the sting, even though the search happens in reverse
(from the end—or right side—of the string).
In the first example, the function counts backward one character from the end of the string, starting
with character ‘c’. The function then searches backward for the first occurrence of ‘a’, which it finds
it in the first position in the search string.
SELECT INSTR('abc', 'a', -1);
INSTR
------1
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 479 of 1539

SQL Reference Manual
SQL Functions

In the second example, the function counts backward one byte from the end of the string, starting
with character ‘c’. The function then searches backward for the first occurrence of ‘a’, which it finds
it in the first position in the search string.
SELECT INSTR(VARBINARY 'abc', VARBINARY 'a', -1);
INSTR
------1
(1 row)

In the third example, the function counts backward one character from the end of the string, starting
with character ‘b’, and searches backward for substring ‘bc’, which it finds in the second position of
the search string.
SELECT INSTR('abcb', 'bc', -1);
INSTR
------2
(1 row)

In the fourth example, the function counts backward one character from the end of the string,
starting with character ‘b’, and searches backward for substring ‘bcef’, which it does not find. The
result is 0.
SELECT INSTR('abcb', 'bcef', -1);
INSTR
------0
(1 row)

In the fifth example, the function counts backward one byte from the end of the string, starting with
character ‘b’, and searches backward for substring ‘bcef’, which it does not find. The result is 0.
SELECT INSTR(VARBINARY 'abcb', VARBINARY 'bcef', -1);
INSTR
------0
(1 row)

Multibyte characters are treated as a single character:
dbadmin=> SELECT INSTR('aébc', 'b');
INSTR
------3
(1 row)

Use INSTRB to treat multibyte characters as binary:
dbadmin=> SELECT INSTRB('aébc', 'b');

HP Vertica Analytic Database (7.0.x)

Page 480 of 1539

SQL Reference Manual
SQL Functions

INSTRB
-------4
(1 row)

INSTRB
Searches string for substring and returns an integer indicating the octet position within string that is
the first occurrence. The return value is based on the octet position of the identified byte.

Behavior Type
Immutable

Syntax
INSTRB ( string , substring [, position [, occurrence ] ] )

Parameters
string

Is the text expression to search.

substring

Is the string to search for.

position

Is a nonzero integer indicating the character of string where HP Vertica begins the
search. If position is negative, then HP Vertica counts backward from the end of
string and then searches backward from the resulting position. The first byte of
string occupies the default position 1, and position cannot be 0.

occurrence

Is an integer indicating which occurrence of string HP Vertica searches. The value
of occurrence must be positive (greater than 0), and the default is 1.

Notes
Both position and occurrence must be of types that can resolve to an integer. The default values of
both parameters are 1, meaning HP Vertica begins searching at the first byte of string for the first
occurrence of substring. The return value is relative to the beginning of string, regardless of the
value of position, and is expressed in octets.
If the search is unsuccessful (that is, if substring does not appear occurrence times after the
position character of string, then the return value is 0.

Example
SELECT INSTRB('straße', 'ß');

HP Vertica Analytic Database (7.0.x)

Page 481 of 1539

SQL Reference Manual
SQL Functions

INSTRB
-------5
(1 row)

See Also
l

INSTR

ISUTF8
Tests whether a string is a valid UTF-8 string. Returns true if the string conforms to UTF-8
standards, and false otherwise. This function is useful to test strings for UTF-8 compliance before
passing them to one of the regular expression functions, such as REGEXP_LIKE, which expect
UTF-8 characters by default.
ISUTF8 checks for invalid UTF8 byte sequences, according to UTF-8 rules:
l

invalid bytes

l

an unexpected continuation byte

l

a start byte not followed by enough continuation bytes

l

an Overload Encoding

The presence of an invalid UTF8 byte sequence results in a return value of false.

Syntax
ISUTF8( string );

Parameters
string

The string to test for UTF-8 compliance.

Examples
=> SELECT ISUTF8(E'\xC2\xBF'); -- UTF-8 INVERTED QUESTION MARK ISUTF8
-------t
(1 row)
=> SELECT ISUTF8(E'\xC2\xC0'); -- UNDEFINED UTF-8 CHARACTER
ISUTF8
-------f

HP Vertica Analytic Database (7.0.x)

Page 482 of 1539

SQL Reference Manual
SQL Functions

(1 row)

LEAST
Returns the smallest value in a list of expressions.

Behavior Type
Stable

Syntax
LEAST ( expression1, expression2, ... expression-n );

Parameters
expression1, expression2, and expression-n are the expressions to be evaluated.

Notes
l

Works for all data types, and implicitly casts similar types. See Examples below.

l

A NULL value in any one of the expressions returns NULL.

Examples
This example returns 5 as the least:
SELECT LEAST(7, 5, 9);
least
------5
(1 row)

Putting quotes around the integer expressions returns the same result as the first example:
SELECT LEAST('7', '5', '9');
least
------5
(1 row)

In the above example, the values are being compared as strings, so '10' would be less than '2'.
The next example returns 1.5, as INTEGER 2 is implicitly cast to FLOAT:

HP Vertica Analytic Database (7.0.x)

Page 483 of 1539

SQL Reference Manual
SQL Functions

SELECT LEAST(2, 1.5);
least
------1.5
(1 row)

The following example returns 'analytic' as the least:
SELECT LEAST('vertica', 'analytic', 'database');
least
---------analytic
(1 row)

Notice this next command returns NULL:
SELECT LEAST('vertica', 'analytic', 'database', null);
least
------(1 row)

And one more:
SELECT LEAST('sit', 'site', 'sight');
least
------sight
(1 row)

See Also
l

GREATEST

LEASTB
Returns the function's least argument, using binary ordering, not UTF-8 character ordering.

Behavior Type
Immutable

Syntax
LEASTB ( expression1, expression2, ... expression-n );

HP Vertica Analytic Database (7.0.x)

Page 484 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression1, expression2, and expression-n are the expressions to be evaluated.

Notes
l

Works for all data types, and implicitly casts similar types. See Examples below.

l

A NULL value in any one of the expressions returns NULL.

Examples
The following command selects strasse as the least in the series of inputs:
SELECT LEASTB('straße', 'strasse');
LEASTB
--------strasse
(1 row)

This example returns 5 as the least:
SELECT LEASTB(7, 5, 9);
LEASTB
-------5
(1 row)

Putting quotes around the integer expressions returns the same result as the first example:
SELECT LEASTB('7', '5', '9');
LEASTB
-------5
(1 row)

In the above example, the values are being compared as strings, so '10' would be less than '2'.
The next example returns 1.5, as INTEGER 2 is implicitly cast to FLOAT:
SELECT LEASTB(2, 1.5);
LEASTB
-------1.5
(1 row)

The following example returns 'analytic' as the least in the series of inputs:
SELECT LEASTB('vertica', 'analytic', 'database');

HP Vertica Analytic Database (7.0.x)

Page 485 of 1539

SQL Reference Manual
SQL Functions

LEASTB
---------analytic
(1 row)

Notice this next command returns NULL:
SELECT LEASTB('vertica', 'analytic', 'database', null);
LEASTB
-------(1 row)

See Also
l

GREATESTB

LEFT
Returns the specified characters from the left side of a string.

Behavior Type
Immutable

Syntax
LEFT ( string , length )

Parameters
string

(CHAR or VARCHAR) is the string to return.

length

Is an INTEGER value that specifies the count of characters to return.

Examples
SELECT LEFT('vertica', 3);
left
-----ver
(1 row)
SELECT LEFT('straße', 5);
LEFT
-------

HP Vertica Analytic Database (7.0.x)

Page 486 of 1539

SQL Reference Manual
SQL Functions

straß
(1 row)

See Also
l

SUBSTR

LENGTH
The LENGTH() function:
l

Returns the string length in UTF-8 characters for CHAR and VARCHAR columns

l

Returns the string length in bytes (octets) for BINARY and VARBINARY columns

l

Strips the padding from CHAR expressions but not from VARCHAR expressions

l

Is is identical to CHARACTER_LENGTH for CHAR and VARCHAR. For binary types,
LENGTH() is identical to OCTET_LENGTH.

Behavior Type
Immutable

Syntax
LENGTH ( expression )

Parameters
expression

(CHAR or VARCHAR or BINARY or VARBINARY) String to measure

Examples
Expression

Result

SELECT LENGTH('1234

'::CHAR(10));

4

SELECT LENGTH('1234

'::VARCHAR(10));

6

SELECT LENGTH('1234

'::BINARY(10));

10

SELECT LENGTH('1234

'::VARBINARY(10));

6

SELECT LENGTH(NULL::CHAR(10)) IS NULL;

HP Vertica Analytic Database (7.0.x)

t

Page 487 of 1539

SQL Reference Manual
SQL Functions

See Also
l

BIT_LENGTH

LOWER
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Returns a VARCHAR value containing the argument converted to lowercase letters.

Behavior Type
Immutable

Syntax
LOWER ( expression )

Parameters
expression

(CHAR or VARCHAR) String to convert

Notes
LOWER is restricted to 32750 octet inputs, since it is possible for the UTF-8 representation of
result to double in size.

Examples
SELECT LOWER('AbCdEfG');
lower
---------abcdefg
(1 row)
SELECT LOWER('The Cat In The Hat');
lower
-------------------the cat in the hat
(1 row)
dbadmin=> SELECT LOWER('ÉTUDIANT');
LOWER
----------

HP Vertica Analytic Database (7.0.x)

Page 488 of 1539

SQL Reference Manual
SQL Functions

étudiant
(1 row)

LOWERB
Returns a character string with each ASCII character converted to lowercase. Multibyte characters
are not converted and are skipped.

Behavior Type
Immutable

Syntax
LOWERB ( expression )

Parameters
expression

(CHAR or VARCHAR) is the string to convert

Examples
In the following example, the multibyte UTF-8 character É is not converted to lowercase:
SELECT LOWERB('ÉTUDIANT');
LOWERB
---------Étudiant
(1 row)
SELECT LOWER('ÉTUDIANT');
LOWER
---------étudiant
(1 row)
SELECT LOWERB('AbCdEfG'); LOWERB
--------abcdefg
(1 row)
SELECT LOWERB('The Vertica Database');
LOWERB
---------------------the vertica database
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 489 of 1539

SQL Reference Manual
SQL Functions

LPAD
Returns a VARCHAR value representing a string of a specific length filled on the left with specific
characters.

Behavior Type
Immutable

Syntax
LPAD ( expression , length [ , fill ] )

Parameters
expression

(CHAR OR VARCHAR) specifies the string to fill

length

(INTEGER) specifies the number of characters to return

fill

(CHAR OR VARCHAR) specifies the repeating string of characters with which to
fill the output string. The default is the space character.

Examples
SELECT LPAD('database', 15, 'xzy');
lpad
----------------xzyxzyxdatabase
(1 row)

If the string is already longer than the specified length it is truncated on the right:
SELECT LPAD('establishment', 10, 'abc');
lpad
-----------establishm
(1 row)

LTRIM
Returns a VARCHAR value representing a string with leading blanks removed from the left side
(beginning).

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 490 of 1539

SQL Reference Manual
SQL Functions

Syntax
LTRIM ( expression [ , characters ] )

Parameters
expression

(CHAR or VARCHAR) is the string to trim

characters

(CHAR or VARCHAR) specifies the characters to remove from the left side of
expression. The default is the space character.

Examples
SELECT LTRIM('zzzyyyyyyxxxxxxxxtrim', 'xyz');
LTRIM
------trim
(1 row)

See Also
l

BTRIM

l

RTRIM

l

TRIM

MD5
Calculates the MD5 hash of string, returning the result as a VARCHAR string in hexadecimal.

Behavior Type
Immutable

Syntax
MD5 ( string )

Parameters
string

Is the argument string.

HP Vertica Analytic Database (7.0.x)

Page 491 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT MD5('123');
md5
---------------------------------202cb962ac59075b964b07152d234b70
(1 row)
=> SELECT MD5('Vertica'::bytea);
md5
---------------------------------fc45b815747d8236f9f6fdb9c2c3f676
(1 row)

OCTET_LENGTH
Takes one argument as an input and returns the string length in octets for all string types.

Behavior Type
Immutable

Syntax
OCTET_LENGTH ( expression )

Parameters
expression

(CHAR or VARCHAR or BINARY or VARBINARY) is the string to measure.

Notes
l

If the data type of expression is a CHAR, VARCHAR or VARBINARY, the result is the same as
the actual length of expression in octets. For CHAR, the length does not include any trailing
spaces.

l

If the data type of expression is BINARY, the result is the same as the fixed-length of
expression.

l

If the value of expression is NULL, the result is NULL.

Examples
Expression

HP Vertica Analytic Database (7.0.x)

Result

Page 492 of 1539

SQL Reference Manual
SQL Functions

SELECT OCTET_LENGTH(CHAR(10) '1234

');

4

SELECT OCTET_LENGTH(CHAR(10) '1234');

4

SELECT OCTET_LENGTH(CHAR(10) '

6

1234');

SELECT OCTET_LENGTH(VARCHAR(10) '1234

');

6

SELECT OCTET_LENGTH(VARCHAR(10) '1234 ');

5

SELECT OCTET_LENGTH(VARCHAR(10) '1234');

4

SELECT OCTET_LENGTH(VARCHAR(10) '

7

1234');

SELECT OCTET_LENGTH('abc'::VARBINARY);

3

SELECT OCTET_LENGTH(VARBINARY 'abc');

3

SELECT OCTET_LENGTH(VARBINARY 'abc

5

');

SELECT OCTET_LENGTH(BINARY(6) 'abc');

6

SELECT OCTET_LENGTH(VARBINARY '');

0

SELECT OCTET_LENGTH(''::BINARY);

1

SELECT OCTET_LENGTH(null::VARBINARY);
SELECT OCTET_LENGTH(null::BINARY);

See Also
l

BIT_LENGTH

l

CHARACTER_LENGTH

l

LENGTH

OVERLAY
Returns a VARCHAR value representing a string having had a substring replaced by another string.

Behavior Type
Immutable if using OCTETS, Stable otherwise

Syntax
OVERLAY ( expression1 PLACING expression2 FROM position
... [ FOR extent ]
... [ USING { CHARACTERS | OCTETS } ] )

HP Vertica Analytic Database (7.0.x)

Page 493 of 1539

SQL Reference Manual
SQL Functions

Parameters
expression1

(CHAR or VARCHAR) is the string to process

expression2

(CHAR or VARCHAR) is the substring to overlay

position

(INTEGER) is the character or octet position (counting from one) at
which to begin the overlay

extent

(INTEGER) specifies the number of characters or octets to replace
with the overlay

USING CHARACTERS | OCTETS

Determines whether OVERLAY uses characters (the default) or
octets

Examples
SELECT OVERLAY('123456789' PLACING 'xxx' FROM 2);
OVERLAY
----------1xxx56789
(1 row)
SELECT OVERLAY('123456789' PLACING 'XXX' FROM 2 USING OCTETS);
OVERLAY
----------1XXX56789
(1 row)
SELECT OVERLAY('123456789' PLACING 'xxx' FROM 2 FOR 4);
OVERLAY
---------1xxx6789
(1 row)
SELECT OVERLAY('123456789' PLACING 'xxx' FROM 2 FOR 5);
OVERLAY
--------1xxx789
(1 row)
SELECT OVERLAY('123456789' PLACING 'xxx' FROM 2 FOR 6);
OVERLAY
--------1xxx89
(1 row)

OVERLAYB
Returns an octet value representing a string having had a substring replaced by another string.

HP Vertica Analytic Database (7.0.x)

Page 494 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
OVERLAYB ( expression1, expression2, position [ , extent ] )

Parameters
expression1

(CHAR or VARCHAR) is the string to process

expression2

(CHAR or VARCHAR) is the substring to overlay

position

(INTEGER) is the octet position (counting from one) at which to begin the overlay

extent

(INTEGER) specifies the number of octets to replace with the overlay

Notes
The OVERLAYB function treats the multibyte character string as a string of octets (bytes) and use
octet numbers as incoming and outgoing position specifiers and lengths. The strings themselves
are type VARCHAR, but they treated as if each byte was a separate character.

Examples
SELECT OVERLAYB('123456789', 'ééé', 2);
OVERLAYB
---------1ééé89
(1 row)
SELECT OVERLAYB('123456789', 'ßßß', 2);
OVERLAYB
---------1ßßß89
(1 row)
SELECT OVERLAYB('123456789', 'xxx', 2);
OVERLAYB
----------1xxx56789
(1 row)
SELECT OVERLAYB('123456789', 'xxx', 2, 4);
OVERLAYB
---------1xxx6789
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 495 of 1539

SQL Reference Manual
SQL Functions

SELECT OVERLAYB('123456789', 'xxx', 2, 5);
OVERLAYB
--------1xxx789
(1 row)
SELECT OVERLAYB('123456789', 'xxx', 2, 6);
OVERLAYB
--------1xxx89
(1 row)

POSITION
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Returns an INTEGER value representing the character location of a specified substring with a
string (counting from one).

Behavior Type
Immutable

Syntax 1
POSITION ( substring IN string [ USING { CHARACTERS | OCTETS } ] )

Parameters
substring

(CHAR or VARCHAR) is the substring to locate

string

(CHAR or VARCHAR) is the string in which to locate the substring

USING CHARACTERS | OCTETS

Determines whether the position is reported by using characters (the
default) or octets.

Syntax 2
POSITION ( substring IN string )

Parameters
substring

(VARBINARY) is the substring to locate

string

(VARBINARY) is the string in which to locate the substring

HP Vertica Analytic Database (7.0.x)

Page 496 of 1539

SQL Reference Manual
SQL Functions

Notes
l

When the string and substring are CHAR or VARCHAR, the return value is based on either the
character or octet position of the substring.

l

When the string and substring are VARBINARY, the return value is always based on the octet
position of the substring.

l

The string and substring must be consistent. Do not mix VARBINARY with CHAR or
VARCHAR.

Examples
SELECT POSITION('é' IN 'étudiant' USING CHARACTERS);
position
---------1
(1 row)
SELECT POSITION('ß' IN 'straße' USING OCTETS);
position
---------5
(1 row)
SELECT POSITION('c' IN 'abcd' USING CHARACTERS);
position
---------3
(1 row)
SELECT POSITION(VARBINARY '456' IN VARBINARY '123456789');
position
---------4
(1 row)
SELECT POSITION('n' in 'León') as 'default',
POSITIONB('León', 'n') as 'POSITIONB',
POSITION('n' in 'León' USING CHARACTERS) as 'pos_chars',
POSITION('n' in 'León' USING OCTETS) as 'pos_oct',INSTR('León','n'),
INSTRB('León','n'),REGEXP_INSTR('León','n');
-[ RECORD 1 ]+-default
| 4
POSITIONB
| 5
pos_chars
| 4
pos_oct
| 5
INSTR
| 4
INSTRB
| 5
REGEXP_INSTR | 4

HP Vertica Analytic Database (7.0.x)

Page 497 of 1539

SQL Reference Manual
SQL Functions

POSITIONB
Returns an INTEGER value representing the octet location of a specified substring with a string
(counting from one).

Behavior Type
Immutable

Syntax
POSITIONB ( string, substring )

Parameters
string

(CHAR or VARCHAR) is the string in which to locate the substring

substring

(CHAR or VARCHAR) is the substring to locate

Examples
SELECT POSITIONB('straße', 'ße');
POSITIONB
----------5
(1 row)
SELECT POSITIONB('étudiant', 'é');
position
---------1
(1 row)

QUOTE_IDENT
Returns the given string, suitably quoted, to be used as an identifier in a SQL statement string.
Quotes are added only if necessary; that is, if the string contains non-identifier characters, is a SQL
keyword, such as '1time', 'Next week' and 'Select'. Embedded double quotes are doubled.

Behavior Type
Immutable

Syntax
QUOTE_IDENT( string )

HP Vertica Analytic Database (7.0.x)

Page 498 of 1539

SQL Reference Manual
SQL Functions

Parameters
string

Is the argument string.

Notes
l

SQL identifiers, such as table and column names, are stored as created, and references to them
are resolved using case-insensitive compares. Thus, you do not need to double-quote mixedcase identifiers.

l

HP Vertica quotes all currently-reserved keywords, even those not currently being used.

Examples
Quoted identifiers are case-insensitive, and HP Vertica does not supply the quotes:
SELECT QUOTE_IDENT('VErtIcA');
QUOTE_IDENT
------------VErtIcA
(1 row)
SELECT QUOTE_IDENT('Vertica database');
QUOTE_IDENT
-------------------"Vertica database"
(1 row)

Embedded double quotes are doubled:
SELECT QUOTE_IDENT('Vertica "!" database');
QUOTE_IDENT
------------------------"Vertica ""!"" database"
(1 row)

The following example uses the SQL keyword, SELECT; results are double quoted:
SELECT QUOTE_IDENT('select');
QUOTE_IDENT
------------"select"
(1 row)

QUOTE_LITERAL
Returns the given string, suitably quoted, to be used as a string literal in a SQL statement string.
Embedded single quotes and backslashes are doubled.

HP Vertica Analytic Database (7.0.x)

Page 499 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
QUOTE_LITERAL ( string )

Parameters
string

Is the argument string.

Notes
HP Vertica recognizes two consecutive single quotes within a string literal as one single quote
character. For example, 'You''re here!'. This is the SQL standard representation and is
preferred over the form, 'You\'re here!', as backslashes are not parsed as before.

Examples
SELECT QUOTE_LITERAL('You''re here!');
QUOTE_LITERAL
----------------'You''re here!'
(1 row)
SELECT QUOTE_LITERAL('You\'re here!');
WARNING: nonstandard use of \' in a string literal at character 22
HINT: Use '' to write quotes in strings, or use the escape string syntax (E'\'').

See Also
l

Character String Literals

REPEAT
Returns a VARCHAR or VARBINARY value that repeats the given value COUNT times, given a
value and a count this function.
If the return value is truncated the given value might not be repeated count times, and the last
occurrence of the given value might be truncated.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 500 of 1539

SQL Reference Manual
SQL Functions

Syntax
REPEAT ( string , repetitions )

Parameters
string

(CHAR or VARCHAR or BINARY or VARBINARY) is the string to repeat

repetitions

(INTEGER) is the number of times to repeat the string

Notes
If the repetitions field depends on the contents of a column (is not a constant), then the repeat
operator maximum length is 65000 bytes. You can add a cast of the repeat to cast the result down
to a size big enough for your purposes (reflects the actual maximum size) so you can do other
things with the result.
REPEAT () and || check for result strings longer than 65000. REPEAT () silently truncates to 65000
octets, and || reports an error (including the octet length).

Examples
The following example repeats vmart three times:
SELECT REPEAT ('vmart', 3);
repeat
----------------vmartvmartvmart
(1 row)

If you run the following example, you get an error message:
SELECT '123456' || REPEAT('a', colx);
ERROR: Operator || may give a 65006-byte Varchar result; the limit is 65000 bytes.

If you know that colx can never be greater than 3, the solution is to add a cast (::VARCHAR(3)):
SELECT '123456' || REPEAT('a', colx)::VARCHAR(3);

If colx is greater than 3, the repeat is truncated to exactly three instalnce of a.

REPLACE
Replaces all occurrences of characters in a string with another set of characters.

HP Vertica Analytic Database (7.0.x)

Page 501 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
REPLACE ( string , target , replacement )

Parameters
string

(CHAR OR VARCHAR) is the string to which to perform the replacement

target

(CHAR OR VARCHAR) is the string to replace

replacement

(CHAR OR VARCHAR) is the string with which to replace the target

Examples
SELECT REPLACE('Documentation%20Library', '%20', ' ');
replace
----------------------Documentation Library
(1 row)
SELECT REPLACE('This & That', '&', 'and');
replace
--------------This and That
(1 row)
SELECT REPLACE('straße', 'ß', 'ss');
REPLACE
--------strasse
(1 row)

RIGHT
Returns the specified characters from the right side of a string.

Behavior Type
Immutable

Syntax
RIGHT ( string , length )

HP Vertica Analytic Database (7.0.x)

Page 502 of 1539

SQL Reference Manual
SQL Functions

Parameters
string

(CHAR or VARCHAR) is the string to return.

length

Is an INTEGER value that specifies the count of characters to return.

Examples
The following command returns the last three characters of the string 'vertica':
SELECT RIGHT('vertica', 3);|
right
------ica
(1 row)

The following command returns the last two characters of the string 'straße':
SELECT RIGHT('straße', 2);
RIGHT
------ße
(1 row)

See Also
l

SUBSTR

RPAD
Returns a VARCHAR value representing a string of a specific length filled on the right with specific
characters.

Behavior Type
Immutable

Syntax
RPAD ( expression , length [ , fill ] )

Parameters
expression

(CHAR OR VARCHAR) specifies the string to fill

HP Vertica Analytic Database (7.0.x)

Page 503 of 1539

SQL Reference Manual
SQL Functions

length

(INTEGER) specifies the number of characters to return

fill

(CHAR OR VARCHAR) specifies the repeating string of characters with which to
fill the output string. The default is the space character.

Examples
SELECT RPAD('database', 15, 'xzy');
rpad
----------------databasexzyxzyx
(1 row)

If the string is already longer than the specified length it is truncated on the right:
SELECT RPAD('database', 6, 'xzy');
rpad
-------databa
(1 row)

RTRIM
Returns a VARCHAR value representing a string with trailing blanks removed from the right side
(end).

Behavior Type
Immutable

Syntax
RTRIM ( expression [ , characters ] )

Parameters
expression

(CHAR or VARCHAR) is the string to trim

characters

(CHAR or VARCHAR) specifies the characters to remove from the right side of
expression. The default is the space character.

Examples
SELECT RTRIM('trimzzzyyyyyyxxxxxxxx', 'xyz');

HP Vertica Analytic Database (7.0.x)

Page 504 of 1539

SQL Reference Manual
SQL Functions

ltrim
------trim
(1 row)

See Also
l

BTRIM

l

LTRIM

l

TRIM

SPACE
Inserts blank spaces into a specified location within a character string.

Behavior Type
Immutable

Syntax
SELECT INSERT( 'string1', || SPACE (n) || 'string2');

Parameters
string1

(VARCHAR) Is the string after which to insert the space.

n

A character of type INTEGER that represents the number of spaces to insert.

string2

( VARCHAR) Is the remainder of the string that appears after the inserted spaces

Example
The following example inserts 10 spaces between the strings 'x' and 'y':
SELECT 'x' || SPACE(10) || 'y';
?column?
-------------x
y
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 505 of 1539

SQL Reference Manual
SQL Functions

SPLIT_PART
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Splits string on the delimiter and returns the location of the beginning of the given field (counting
from one).

Behavior Type
Immutable

Syntax
SPLIT_PART ( string , delimiter , field )

Parameters
string

Is the argument string.

delimiter

Is the given delimiter.

field

(INTEGER) is the number of the part to return.

Notes
Use this with the character form of the subfield.

Examples
The specified integer of 2 returns the second string, or def.
SELECT SPLIT_PART('abc~@~def~@~ghi', '~@~', 2);
SPLIT_PART
-----------def
(1 row)

In the next example, specify 3, which returns the third string, or 789.
SELECT SPLIT_PART('123~|~456~|~789', '~|~', 3);
SPLIT_PART
-----------789
(1 row)

The tildes are for readability only. Omitting them returns the same results:

HP Vertica Analytic Database (7.0.x)

Page 506 of 1539

SQL Reference Manual
SQL Functions

SELECT SPLIT_PART('123|456|789', '|', 3);
SPLIT_PART
-----------789
(1 row)

See what happens if you specify an integer that exceeds the number of strings: No results.
SELECT SPLIT_PART('123|456|789', '|', 4);
SPLIT_PART
-----------(1 row)

The previous result is not null, it is an empty string.
SELECT SPLIT_PART('123|456|789', '|', 4) IS NULL;
?column?
---------f
(1 row)

If SPLIT_PART had returned NULL, LENGTH would have returned null.
SELECT LENGTH (SPLIT_PART('123|456|789', '|', 4));
LENGTH
-------0
(1 row)

SPLIT_PARTB
Splits string on the delimiter and returns the location of the beginning of the given field (counting
from one). The VARCHAR arguments are treated as octets rather than UTF-8 characters.

Behavior Type
Immutable

Syntax
SPLIT_PARTB ( string , delimiter , field )

Parameters
string

(VARCHAR) Is the argument string.

delimiter

(VARCHAR) Is the given delimiter.

field

(INTEGER) is the number of the part to return.

HP Vertica Analytic Database (7.0.x)

Page 507 of 1539

SQL Reference Manual
SQL Functions

Notes
Use this function with the character form of the subfield.

Examples
The specified integer of 3 returns the third string, or soupçon.
SELECT SPLIT_PARTB('straße~@~café~@~soupçon', '~@~', 3);
SPLIT_PARTB
------------soupçon
(1 row)

The tildes are for readability only. Omitting them returns the same results:
SELECT SPLIT_PARTB('straße @ café @ soupçon', '@', 3);
SPLIT_PARTB
------------soupçon
(1 row)

See what happens if you specify an integer that exceeds the number of strings: No results.
SELECT SPLIT_PARTB('straße @ café @ soupçon', '@', 4);
SPLIT_PARTB
------------(1 row)

The above result is not null, it is an empty string.
SELECT SPLIT_PARTB('straße @ café @ soupçon', '@', 4) IS NULL;
?column?
---------f
(1 row)

STRPOS
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Returns an INTEGER value representing the character location of a specified substring within a
string (counting from one).

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 508 of 1539

SQL Reference Manual
SQL Functions

Syntax
STRPOS ( string , substring )

Parameters
string

(CHAR or VARCHAR) is the string in which to locate the substring

substring

(CHAR or VARCHAR) is the substring to locate

Notes
STRPOS is identical to POSITION except for the order of the arguments.

Examples
SELECT STRPOS('abcd','c');
strpos
-------3
(1 row)

STRPOSB
Returns an INTEGER value representing the location of a specified substring within a string,
counting from one, where each octet in the string is counted (as opposed to characters).

Behavior Type
Immutable

Syntax
STRPOSB ( string , substring )

Parameters
string

(CHAR or VARCHAR) is the string in which to locate the substring

substring

(CHAR or VARCHAR) is the substring to locate

Notes
STRPOSB is identical to POSITIONB except for the order of the arguments.

HP Vertica Analytic Database (7.0.x)

Page 509 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT STRPOSB('straße', 'e');
STRPOSB
--------7
(1 row)
=> SELECT STRPOSB('étudiant', 'tud');
STRPOSB
--------3
(1 row)

SUBSTR
Returns VARCHAR or VARBINARY value representing a substring of a specified string.

Behavior Type
Immutable

Syntax
SUBSTR ( string , position [ , extent ] )

Parameters
string

(CHAR/VARCHAR or BINARY/VARBINARY) is the string from which to extract a
substring.

position

(INTEGER or DOUBLE PRECISION) is the starting position of the substring
(counting from one by characters).

extent

(INTEGER or DOUBLE PRECISION) is the length of the substring to extract (in
characters). The default is the end of the string.

Notes
SUBSTR truncates DOUBLE PRECISION input values.

Examples
=> SELECT SUBSTR('abc'::binary(3),1);

HP Vertica Analytic Database (7.0.x)

Page 510 of 1539

SQL Reference Manual
SQL Functions

substr
-------abc
(1 row)
=> SELECT SUBSTR('123456789', 3, 2);
substr
-------34
(1 row)
=> SELECT SUBSTR('123456789', 3);
substr
--------3456789
(1 row)
=> SELECT SUBSTR(TO_BITSTRING(HEX_TO_BINARY('0x10')), 2, 2);
substr
-------00
(1 row)
=> SELECT SUBSTR(TO_HEX(10010), 2, 2);
substr
-------71
(1 row)

SUBSTRB
Returns an octet value representing the substring of a specified string.

Behavior Type
Immutable

Syntax
SUBSTRB ( string , position [ , extent ] )

Parameters
string

(CHAR/VARCHAR) is the string from which to extract a substring.

position

(INTEGER or DOUBLE PRECISION) is the starting position of the substring
(counting from one in octets).

extent

(INTEGER or DOUBLE PRECISION) is the length of the substring to extract (in
octets). The default is the end of the string

HP Vertica Analytic Database (7.0.x)

Page 511 of 1539

SQL Reference Manual
SQL Functions

Notes
l

This function treats the multibyte character string as a string of octets (bytes) and uses octet
numbers as incoming and outgoing position specifiers and lengths. The strings themselves are
type VARCHAR, but they treated as if each octet were a separate character.

l

SUBSTRB truncates DOUBLE PRECISION input values.

Examples
=> SELECT SUBSTRB('soupçon', 5);
SUBSTRB
--------çon
(1 row)
=> SELECT SUBSTRB('soupçon', 5, 2);
SUBSTRB
--------ç
(1 row)

HP Vertica returns the following error message if you use BINARY/VARBINARY:
=>SELECT SUBSTRB('abc'::binary(3),1);
ERROR: function substrb(binary, int) does not exist, or permission is denied for substrb(
binary, int)
HINT: No function matches the given name and argument types. You may need to add explicit
type casts.

SUBSTRING
Returns a value representing a substring of the specified string at the given position, given a value,
a position, and an optional length.

Behavior Type
Immutable if USING OCTETS, stable otherwise.

Syntax
SUBSTRING ( string , position [ , length ]
... [USING {CHARACTERS | OCTETS } ] )
SUBSTRING ( string FROM position [ FOR length ]
... [USING { CHARACTERS | OCTETS } ] )

HP Vertica Analytic Database (7.0.x)

Page 512 of 1539

SQL Reference Manual
SQL Functions

Parameters
string

(CHAR/VARCHAR or BINARY/VARBINARY) is the string from
which to extract a substring

position

(INTEGER or DOUBLE PRECISION) is the starting position of the
substring (counting from one by either characters or octets). (The
default is characters.) If position is greater than the length of the
given value, an empty value is returned.

length

(INTEGER or DOUBLE PRECISION) is the length of the substring
to extract in either characters or octets. (The default is characters.)
The default is the end of the string.If a length is given the result is at
most that many bytes. The maximum length is the length of the
given value less the given position. If no length is given or if the
given length is greater than the maximum length then the length is
set to the maximum length.

USING CHARACTERS | OCTETS

Determines whether the value is expressed in characters (the
default) or octets.

Notes
l

SUBSTRING truncates DOUBLE PRECISION input values.

l

Neither length nor position can be negative, and the position cannot be zero because it is one
based. If these forms are violated, the system returns an error:
SELECT SUBSTRING('ab'::binary(2), -1, 2);
ERROR: negative or zero substring start position not allowed

Examples
=> SELECT SUBSTRING('abc'::binary(3),1);
SUBSTRING
----------abc
(1 row)
=> SELECT SUBSTRING('soupçon', 5, 2 USING CHARACTERS);
SUBSTRING
----------ço
(1 row)
=> SELECT SUBSTRING('soupçon', 5, 2 USING OCTETS);
SUBSTRB
--------ç

HP Vertica Analytic Database (7.0.x)

Page 513 of 1539

SQL Reference Manual
SQL Functions

(1 row)

TO_BITSTRING
Returns a VARCHAR that represents the given VARBINARY value in bitstring format.

Behavior Type
Immutable

Syntax
TO_BITSTRING ( expression )

Parameters
expression

(VARCHAR) is the string to return.

Notes
VARCHAR TO_BITSTRING(VARBINARY) converts data from binary type to character type
(where the character representation is the bitstring format). This function is the inverse of
BITSTRING_TO_BINARY:
TO_BITSTRING(BITSTRING_TO_BINARY(x)) = x)
BITSTRING_TO_BINARY(TO_BITSTRING(x)) = x)

Examples
SELECT TO_BITSTRING('ab'::BINARY(2));
to_bitstring
-----------------0110000101100010
(1 row)

SELECT TO_BITSTRING(HEX_TO_BINARY('0x10'));
to_bitstring
-------------00010000
(1 row)
SELECT TO_BITSTRING(HEX_TO_BINARY('0xF0'));
to_bitstring
--------------

HP Vertica Analytic Database (7.0.x)

Page 514 of 1539

SQL Reference Manual
SQL Functions

11110000
(1 row)

See Also
l

BITCOUNT

l

BITSTRING_TO_BINARY

TO_HEX
Returns a VARCHAR or VARBINARY representing the hexadecimal equivalent of a number.

Behavior Type
Immutable

Syntax
TO_HEX ( number )

Parameters
number

(INTEGER) is the number to convert to hexadecimal

Notes
VARCHAR TO_HEX(INTEGER) and VARCHAR TO_HEX(VARBINARY) are similar. The
function converts data from binary type to character type (where the character representation is in
hexadecimal format). This function is the inverse of HEX_TO_BINARY.
TO_HEX(HEX_TO_BINARY(x)) = x);
HEX_TO_BINARY(TO_HEX(x)) = x);

Examples
SELECT TO_HEX(123456789);
TO_HEX
--------75bcd15
(1 row)

For VARBINARY inputs, the returned value is not preceded by "0x". For example:

HP Vertica Analytic Database (7.0.x)

Page 515 of 1539

SQL Reference Manual
SQL Functions

SELECT TO_HEX('ab'::binary(2));
TO_HEX
-------6162
(1 row)

TRANSLATE
Replaces individual characters in string_to_replace with other characters.

Behavior Type
Immutable

Syntax
TRANSLATE ( string_to_replace , from_string , to_string );

Parameters
string_to_replace

String to be translated.

from_string

Contains characters that should be replaced in string_to_replace.

to_string

Any character in string_to_replace that matches a character in from_string is
replaced by the corresponding character in to_string.

Example
SELECT TRANSLATE('straße', 'ß', 'ss');
TRANSLATE
----------strase
(1 row)

TRIM
Combines the BTRIM, LTRIM, and RTRIM functions into a single function.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 516 of 1539

SQL Reference Manual
SQL Functions

Syntax
TRIM ( [ [ LEADING | TRAILING | BOTH ] characters FROM ] expression )

Parameters
LEADING

Removes the specified characters from the left side of the string

TRAILING

Removes the specified characters from the right side of the string

BOTH

Removes the specified characters from both sides of the string (default)

characters

(CHAR or VARCHAR) specifies the characters to remove from expression. The
default is the space character.

expression

(CHAR or VARCHAR) is the string to trim

Examples
SELECT '-' || TRIM(LEADING 'x' FROM 'xxdatabasexx') || '-';
?column?
--------------databasexx(1 row)
SELECT '-' || TRIM(TRAILING 'x' FROM 'xxdatabasexx') || '-';
?column?
--------------xxdatabase(1 row)
SELECT '-' || TRIM(BOTH 'x' FROM 'xxdatabasexx') || '-';
?column?
------------database(1 row)
SELECT '-' || TRIM('x' FROM 'xxdatabasexx') || '-';
?column?
------------database(1 row)
SELECT '-' || TRIM(LEADING FROM '
?column?
--------------database (1 row)
SELECT '-' || TRIM('
?column?
------------database(1 row)

database

HP Vertica Analytic Database (7.0.x)

database

') || '-';

') || '-';

Page 517 of 1539

SQL Reference Manual
SQL Functions

See Also
l

BTRIM

l

LTRIM

l

RTRIM

UPPER
Starting in Release 5.1, this function treats the string argument as a UTF-8 encoded string, rather
than depending on the collation setting of the locale (for example, collation=binary) to identify the
encoding. Prior to Release 5.1, the behavior type of this function was stable.
Returns a VARCHAR value containing the argument converted to uppercase letters.

Behavior Type
Immutable

Syntax
UPPER ( expression )

Parameters
expression

(CHAR or VARCHAR) is the string to convert

Notes
UPPER is restricted to 32750 octet inputs, since it is possible for the UTF-8 representation of result
to double in size.

Examples
=> SELECT UPPER('AbCdEfG');
UPPER
---------ABCDEFG
(1 row)
=> SELECT UPPER('étudiant');
UPPER
---------ÉTUDIANT
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 518 of 1539

SQL Reference Manual
SQL Functions

UPPERB
Returns a character string with each ASCII character converted to uppercase. Multibyte characters
are not converted and are skipped.

Behavior Type
Immutable

Syntax
UPPERB ( expression )

Parameters
expression

(CHAR or VARCHAR) is the string to convert

Examples
In the following example, the multibyte UTF-8 character é is not converted to uppercase:
=> SELECT UPPERB('étudiant');
UPPERB
---------éTUDIANT
(1 row)
=> SELECT UPPERB('AbCdEfG');
UPPERB
--------ABCDEFG
(1 row)
=> SELECT UPPERB('The Vertica Database');
UPPERB
---------------------THE VERTICA DATABASE
(1 row)

V6_ATON
Converts an IPv6 address represented as a character string to a binary string.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 519 of 1539

SQL Reference Manual
SQL Functions

Syntax
V6_ATON ( expression )

Parameters
expression

(VARCHAR) is the string to convert.

Notes
The following syntax converts an IPv6 address represented as the character string A to a binary
string B.
V6_ATON trims any spaces from the right of A and calls the Linux function inet_pton.
V6_ATON(VARCHAR A) -> VARBINARY(16) B

If A has no colons it is prepended with '::ffff:'. If A is NULL, too long, or if inet_pton returns an error,
the result is NULL.

Examples
SELECT V6_ATON('2001:DB8::8:800:200C:417A');
v6_aton
-----------------------------------------------------\001\015\270\000\000\000\000\000\010\010\000 \014Az
(1 row)
SELECT V6_ATON('1.2.3.4');
v6_aton
-----------------------------------------------------------------\000\000\000\000\000\000\000\000\000\000\377\377\001\002\003\004
(1 row)
SELECT TO_HEX(V6_ATON('2001:DB8::8:800:200C:417A'));
to_hex
---------------------------------20010db80000000000080800200c417a
(1 row)
SELECT V6_ATON('::1.2.3.4');
v6_aton
-----------------------------------------------------------------\000\000\000\000\000\000\000\000\000\000\000\000\001\002\003\004
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 520 of 1539

SQL Reference Manual
SQL Functions

See Also
l

V6_NTOA

V6_NTOA
Converts an IPv6 address represented as varbinary to a character string.

Behavior Type
Immutable

Syntax
V6_NTOA ( expression )

Parameters
expression

(VARBINARY) is the binary string to convert.

Notes
The following syntax converts an IPv6 address represented as VARBINARY B to a string A.
V6_NTOA right-pads B to 16 bytes with zeros, if necessary, and calls the Linux function inet_ntop.
V6_NTOA(VARBINARY B) -> VARCHAR A

If B is NULL or longer than 16 bytes, the result is NULL.
HP Vertica automatically converts the form '::ffff:1.2.3.4' to '1.2.3.4'.

Examples
> SELECT V6_NTOA(' \001\015\270\000\000\000\000\000\010\010\000 \014Az');
v6_ntoa
--------------------------2001:db8::8:800:200c:417a
(1 row)
> SELECT V6_NTOA(V6_ATON('1.2.3.4'));
v6_ntoa
--------1.2.3.4
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 521 of 1539

SQL Reference Manual
SQL Functions

> SELECT V6_NTOA(V6_ATON('::1.2.3.4'));
v6_ntoa
----------::1.2.3.4
(1 row)

See Also
l

V6_ATON

V6_SUBNETA
Calculates a subnet address in CIDR (Classless Inter-Domain Routing) format from a binary or
alphanumeric IPv6 address.

Behavior Type
Immutable

Syntax
V6_SUBNETA ( expression1, expression2 )

Parameters
expression1

(VARBINARY or VARCHAR) is the string to calculate.

expression2

(INTEGER) is the size of the subnet.

Notes
The following syntax calculates a subnet address in CIDR format from a binary or varchar IPv6
address.
V6_SUBNETA masks a binary IPv6 address B so that the N leftmost bits form a subnet address,
while the remaining rightmost bits are cleared. It then converts to an alphanumeric IPv6 address,
appending a slash and N.
V6_SUBNETA(BINARY B, INT8 N) -> VARCHAR C

The following syntax calculates a subnet address in CIDR format from an alphanumeric IPv6
address.
V6_SUBNETA(VARCHAR A, INT8 N) -> V6_SUBNETA(V6_ATON(A), N) -> VARCHAR C

HP Vertica Analytic Database (7.0.x)

Page 522 of 1539

SQL Reference Manual
SQL Functions

Examples
> SELECT V6_SUBNETA(V6_ATON('2001:db8::8:800:200c:417a'), 28);
v6_subneta
--------------2001:db0::/28
(1 row)

See Also
l

V6_SUBNETN

V6_SUBNETN
Calculates a subnet address in CIDR (Classless Inter-Domain Routing) format from a varbinary or
alphanumeric IPv6 address.

Behavior Type
Immutable

Syntax
V6_SUBNETN ( expression1, expression2 )

Parameters
expression1

(VARBINARY or VARCHAR) is the string to calculate.
Notes:
l

V6_SUBNETN(, ) returns VARBINARY.
OR

l

expression2

V6_SUBNETN(, ) returns VARBINARY, after using V6_ATON
to convert the  string to .

(INTEGER) is the size of the subnet.

Notes
The following syntax masks a BINARY IPv6 address B so that the N left-most bits of S form a
subnet address, while the remaining right-most bits are cleared.

HP Vertica Analytic Database (7.0.x)

Page 523 of 1539

SQL Reference Manual
SQL Functions

V6_SUBNETN right-pads B to 16 bytes with zeros, if necessary and masks B, preserving its N-bit
subnet prefix.
V6_SUBNETN(VARBINARY B, INT8 N) -> VARBINARY(16) S

If B is NULL or longer than 16 bytes, or if N is not between 0 and 128 inclusive, the result is NULL.
S = [B]/N in Classless Inter-Domain Routing notation (CIDR notation).
The following syntax masks an alphanumeric IPv6 address A so that the N leftmost bits form a
subnet address, while the remaining rightmost bits are cleared.
V6_SUBNETN(VARCHAR A, INT8 N) -> V6_SUBNETN(V6_ATON(A), N) -> VARBINARY(16) S

Example
This example returns VARBINARY, after using V6_ATON to convert the VARCHAR string to VARBINARY:
> SELECT V6_SUBNETN(V6_ATON('2001:db8::8:800:200c:417a'), 28);
v6_subnetn
--------------------------------------------------------------\001\015\260\000\000\000\000\000\000\000\000\000\000\000\000

See Also
l

V6_ATON

l

V6_SUBNETA

V6_TYPE
Characterizes a binary or alphanumeric IPv6 address B as an integer type.

Behavior Type
Immutable

Syntax
V6_TYPE ( expression )

Parameters
expression

(VARBINARY or VARCHAR) is the type to convert.

HP Vertica Analytic Database (7.0.x)

Page 524 of 1539

SQL Reference Manual
SQL Functions

Notes
V6_TYPE(VARBINARY B) returns INT8 T.
V6_TYPE(VARCHAR A) -> V6_TYPE(V6_ATON(A)) -> INT8 T

The IPv6 types are defined in the Network Working Group's IP Version 6 Addressing Architecture
memo.
GLOBAL = 0
LINKLOCAL = 1
LOOPBACK = 2
UNSPECIFIED = 3
MULTICAST = 4

Global unicast addresses
Link-Local unicast (and Private-Use) addresses
Loopback
Unspecified
Multicast

IPv4-mapped and IPv4-compatible IPv6 addresses are also interpreted, as specified in IPv4 Global
Unicast Address Assignments.
l

For IPv4, Private-Use is grouped with Link-Local.

l

If B is VARBINARY, it is right-padded to 16 bytes with zeros, if necessary.

l

If B is NULL or longer than 16 bytes, the result is NULL.

Details
IPv4 (either kind):
0.0.0.0/8
127.0.0.0/8
169.254.0.0/16
172.16.0.0/12
192.168.0.0/16
224.0.0.0/4
others

UNSPECIFIED
LOOPBACK
LINKLOCAL
LINKLOCAL
LINKLOCAL
MULTICAST
GLOBAL

10.0.0.0/8

::0/128
fe80::/10
ff00::/8
others

UNSPECIFIED
LINKLOCAL
MULTICAST
GLOBAL

::1/128

LINKLOCAL

IPv6:
LOOPBACK

Examples
> SELECT V6_TYPE(V6_ATON('192.168.2.10'));
v6_type

HP Vertica Analytic Database (7.0.x)

Page 525 of 1539

SQL Reference Manual
SQL Functions

--------1
(1 row)
> SELECT V6_TYPE(V6_ATON('2001:db8::8:800:200c:417a'));
v6_type
--------0
(1 row)

See Also
l

INET_ATON

l

IP Version 6 Addressing Architecture

l

IPv4 Global Unicast Address Assignments

HP Vertica Analytic Database (7.0.x)

Page 526 of 1539

SQL Reference Manual
SQL Functions

System Information Functions
These functions provide system information regarding user sessions. A superuser has unrestricted
access to all system information, but users can view only information about their own, current
sessions.

CURRENT_DATABASE
Returns a VARCHAR value containing the name of the database to which you are connected.

Behavior Type
Immutable

Syntax
CURRENT_DATABASE()

Notes
l

The parentheses following the CURRENT_DATABASE function are optional.

l

This function is equivalent to DBNAME.

Examples
SELECT CURRENT_DATABASE();
CURRENT_DATABASE
-----------------VMart
(1 row)

The following command returns the same results without the parentheses:
SELECT CURRENT_DATABASE;
CURRENT_DATABASE
-----------------VMart
(1 row)

CURRENT_SCHEMA
Returns the name of the current schema.

HP Vertica Analytic Database (7.0.x)

Page 527 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Stable

Syntax
CURRENT_SCHEMA()

Privileges
None

Notes
The CURRENT_SCHEMA function does not require parentheses.

Examples
The following command returns the name of the current schema:
=> SELECT CURRENT_SCHEMA();
current_schema
---------------public
(1 row)

The following command returns the same results without the parentheses:
=> SELECT CURRENT_SCHEMA;
current_schema
---------------public
(1 row)

The following command shows the current schema, listed after the current user, in the search path:
=> SHOW SEARCH_PATH;
name
|
setting
-------------+--------------------------------------------------search_path | "$user", public, v_catalog, v_monitor, v_internal
(1 row)

See Also
l

SET SEARCH_PATH

HP Vertica Analytic Database (7.0.x)

Page 528 of 1539

SQL Reference Manual
SQL Functions

CURRENT_USER
Returns a VARCHAR containing the name of the user who initiated the current database
connection.

Behavior Type
Stable

Syntax
CURRENT_USER()

Notes
l

The CURRENT_USER function does not require parentheses.

l

This function is useful for permission checking.

l

CURRENT_USER is equivalent to SESSION_USER, USER, and USERNAME.

Examples
SELECT CURRENT_USER();
CURRENT_USER
-------------dbadmin
(1 row)

The following command returns the same results without the parentheses:
SELECT CURRENT_USER;
CURRENT_USER
-------------dbadmin
(1 row)

DBNAME (function)
Returns a VARCHAR value containing the name of the database to which you are connected.
DBNAME is equivalent to CURRENT_DATABASE.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 529 of 1539

SQL Reference Manual
SQL Functions

Syntax
DBNAME()

Examples
SELECT DBNAME();
dbname
-----------------VMart
(1 row)

HAS_TABLE_PRIVILEGE
Indicates whether a user can access a table in a particular way. The function returns a true (t) or
false (f) value.
A superuser can check all other user's table privileges.
Users without superuser privileges can use HAS_TABLE_PRIVILEGE to check:
l

Any tables they own.

l

Tables in a schema to which they have been granted USAGE privileges, and at least one other
table privilege, as described in GRANT (Table).

Behavior Type
Stable

Syntax
HAS_TABLE_PRIVILEGE ( [ user, ] [[db-name.]schema-name.]table , privilege )

Parameters
user

Specifies the name or OID of a database user. The default is the
CURRENT_USER.

HP Vertica Analytic Database (7.0.x)

Page 530 of 1539

SQL Reference Manual
SQL Functions

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

table

privilege

Specifies the name or OID of a table in the logical schema. If necessary,
specify the database and schema, as noted above.
l

SELECT Allows the user to SELECT from any column of the specified
table.

l

INSERT Allows the user to INSERT records into the specified table and
to use the COPY command to load the table.

l

UPDATE Allows the user to UPDATE records in the specified table.

l

DELETE Allows the user to delete a row from the specified table.

l

REFERENCES Allows the user to create a foreign key constraint
(privileges required on both the referencing and referenced tables).

Examples
SELECT HAS_TABLE_PRIVILEGE('store.store_dimension', 'SELECT');
HAS_TABLE_PRIVILEGE
--------------------t
(1 row)
SELECT HAS_TABLE_PRIVILEGE('release', 'store.store_dimension', 'INSERT');
HAS_TABLE_PRIVILEGE
--------------------t
(1 row)
SELECT HAS_TABLE_PRIVILEGE('store.store_dimension', 'UPDATE');
HAS_TABLE_PRIVILEGE
--------------------t
(1 row)
SELECT HAS_TABLE_PRIVILEGE('store.store_dimension', 'REFERENCES');
HAS_TABLE_PRIVILEGE

HP Vertica Analytic Database (7.0.x)

Page 531 of 1539

SQL Reference Manual
SQL Functions

--------------------t
(1 row)
SELECT HAS_TABLE_PRIVILEGE(45035996273711159, 45035996273711160, 'select');
HAS_TABLE_PRIVILEGE
--------------------t
(1 row)

SESSION_USER
Returns a VARCHAR containing the name of the user who initiated the current database session.

Behavior Type
Stable

Syntax
SESSION_USER()

Notes
l

The SESSION_USER function does not require parentheses.

l

SESSION_USER is equivalent to CURRENT_USER, USER, and USERNAME.

Examples
SELECT SESSION_USER();
session_user
-------------dbadmin
(1 row)

The following command returns the same results without the parentheses:
SELECT SESSION_USER;
session_user
-------------dbadmin
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 532 of 1539

SQL Reference Manual
SQL Functions

USER
Returns a VARCHAR containing the name of the user who initiated the current database
connection.

Behavior Type
Stable

Syntax
USER()

Notes
l

The USER function does not require parentheses.

l

USER is equivalent to CURRENT_USER, SESSION_USER, and USERNAME.

Examples
SELECT USER();
current_user
-------------dbadmin
(1 row)

The following command returns the same results without the parentheses:
SELECT USER;
current_user
-------------dbadmin
(1 row)

USERNAME
Returns a VARCHAR containing the name of the user who initiated the current database
connection.

Behavior Type
Stable

HP Vertica Analytic Database (7.0.x)

Page 533 of 1539

SQL Reference Manual
SQL Functions

Syntax
USERNAME()

Notes
l

This function is useful for permission checking.

l

USERNAME is equivalent to CURRENT_USER, SESSION_USER and USER.

Examples
SELECT USERNAME();
username
-------------dbadmin
(1 row)

VERSION
Returns a VARCHAR containing an HP Vertica node's version information.

Behavior Type
Stable

Syntax
VERSION()

Examples
SELECT VERSION();
VERSION
-------------------------------------------------Vertica Analytic Database v4.0.12-20100513010203
(1 row)

The parentheses are required. If you omit them, the system returns an error:
SELECT VERSION;
ERROR: column "version" does not exist

HP Vertica Analytic Database (7.0.x)

Page 534 of 1539

SQL Reference Manual
SQL Functions

Timeseries Functions
Timeseries aggregate functions evaluate the values of a given set of variables over time and group
those values into a window for analysis and aggregation.
One output row is produced per time slice—or per partition per time slice—if partition expressions
are present.

See Also
l

TIMESERIES Clause

l

CONDITIONAL_CHANGE_EVENT [Analytic]
CONDITIONAL_TRUE_EVENT [Analytic]

l
l

TS_FIRST_VALUE
Processes the data that belongs to each time slice. A time series aggregate (TSA) function, TS_
FIRST_VALUE returns the value at the start of the time slice, where an interpolation scheme is
applied if the timeslice is missing, in which case the value is determined by the values
corresponding to the previous (and next) timeslices based on the interpolation scheme of const
(linear). There is one value per time slice per partition.

Behavior Type
Immutable

Syntax
TS_FIRST_VALUE ( expression [ IGNORE NULLS ]
... [, { 'CONST' | 'LINEAR' }
] )

Parameters
expression

Argument expression on which to aggregate and interpolate.
expression is data type INTEGER or FLOAT.

IGNORE NULLS

The IGNORE NULLS behavior changes depending on a CONST or LINEAR
interpolation scheme. See When Time Series Data Contains Nulls in the
Programmer's Guide for details.

HP Vertica Analytic Database (7.0.x)

Page 535 of 1539

SQL Reference Manual
SQL Functions

'CONST' | 'LINEAR'

(Default CONST) Optionally specifies the interpolation value as either
constant or linear.
l

CONST—New value are interpolated based on previous input records.

l

LINEAR—Values are interpolated in a linear slope based on the specified
time slice.

Notes
l

The function returns one output row per time slice or one output row per partition per time slice if
partition expressions are specified.

l

Multiple time series aggregate functions can exists in the same query. They share the same
gap-filling policy as defined by the TIMESERIES Clause; however, each time series aggregate
function can specify its own interpolation policy. For example:
SELECT slice_time, symbol,
TS_FIRST_VALUE(bid, 'const') fv_c,
TS_FIRST_VALUE(bid, 'linear') fv_l,
TS_LAST_VALUE(bid, 'const') lv_c
FROM TickStore
TIMESERIES slice_time AS '3 seconds'
OVER(PARTITION BY symbol ORDER BY ts);

You must use an ORDER BY clause with a TIMESTAMP column.

l

Example
For detailed examples, see Gap Filling and Interpolation in the Programmer's Guide.

See Also
TIMESERIES Clause

l

TS_LAST_VALUE

l
l

TS_LAST_VALUE
Processes the data that belongs to each time slice. A time series aggregate (TSA) function, TS_
LAST_VALUE returns the value at the end of the time slice, where an interpolation scheme is
applied if the timeslice is missing, in which case the value is determined by the values
corresponding to the previous (and next) timeslices based on the interpolation scheme of const
(linear). There is one value per time slice per partition.

HP Vertica Analytic Database (7.0.x)

Page 536 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
TS_LAST_VALUE ( expression [ IGNORE NULLS ]
... [, { 'CONST' | 'LINEAR' }
] )

Parameters
expression

Argument expression on which to aggregate and interpolate.
expression is data type INTEGER or FLOAT.

IGNORE NULLS

The IGNORE NULLS behavior changes depending on a CONST or LINEAR
interpolation scheme. See When Time Series Data Contains Nulls in the
Programmer's Guide for details.

'CONST' | 'LINEAR'

(Default CONST) Optionally specifies the interpolation value as either
constant or linear.
l

CONST—New value are interpolated based on previous input records.

l

LINEAR—Values are interpolated in a linear slope based on the specified
time slice.

Notes
l

The function returns one output row per time slice or one output row per partition per time slice if
partition expressions are specified.

l

Multiple time series aggregate functions can exists in the same query. They share the same
gap-filling policy as defined by the TIMESERIES Clause; however, each time series aggregate
function can specify its own interpolation policy. For example:
SELECT slice_time, symbol,
TS_FIRST_VALUE(bid, 'const') fv_c,
TS_FIRST_VALUE(bid, 'linear') fv_l,
TS_LAST_VALUE(bid, 'const') lv_c
FROM TickStore
TIMESERIES slice_time AS 3 seconds
OVER(PARTITION BY symbol ORDER BY ts);

l

You must use the ORDER BY clause with a TIMESTAMP column.

HP Vertica Analytic Database (7.0.x)

Page 537 of 1539

SQL Reference Manual
SQL Functions

Example
For detailed examples, see Gap Filling and Interpolation in the Programmer's Guide.

See Also
TIMESERIES Clause

l

TS_FIRST_VALUE

l
l

HP Vertica Analytic Database (7.0.x)

Page 538 of 1539

SQL Reference Manual
SQL Functions

URI Encode/Decode Functions
The functions in this section follow the RFC 3986 standard for percent-encoding a Universal
Resource Identifier (URI).

URI_PERCENT_DECODE
Decodes a percent-encoded Universal Resource Identifier (URI) according to the RFC 3986
standard.

Syntax
URI_PERCENT_DECODE (expression)

Behavior Type
Immutable

Parameters
expression

(VARCHAR) is the string to convert.

Examples
The following example invokes uri_percent_decode on the Websites column of the URI table and
returns a decoded URI:
=> SELECT URI_PERCENT_DECODE(Websites) from URI;
URI_PERCENT_DECODE
----------------------------------------------http://www.faqs.org/rfcs/rfc3986.html x xj%a%
(1 row)

The following example returns the original URI in the Websites column and its decoded version:
=> SELECT Websites, URI_PERCENT_DECODE (Websites) from URI;
Websites
|
URI_PERCENT_DECODE
---------------------------------------------------+-------------------------------------------http://www.faqs.org/rfcs/rfc3986.html+x%20x%6a%a% | http://www.faqs.org/rfcs/rfc3986.htm
l x xj%a%
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 539 of 1539

SQL Reference Manual
SQL Functions

URI_PERCENT_ENCODE
Encodes a Universal Resource Identifier (URI) according to the RFC 3986 standard for percent
encoding. In addition, for compatibility with older encoders this function converts '+' to space;
space is converted to %20 by uri_percent_encode.

Syntax
URI_PERCENT_ENCODE (expression)

Behavior Type
Immutable

Parameters
expression

(VARCHAR) is the string to convert.

Examples
The following example shows how the uri_percent_encode function is invoked on a the Websites
column of the URI table and returns an encoded URI:
=> SELECT URI_PERCENT_ENCODE(Websites) from URI;
URI_PERCENT_ENCODE
-----------------------------------------http%3A%2F%2Fexample.com%2F%3F%3D11%2F15
(1 row)

The following example returns the original URI in the Websites column and it's encoded form:
=> SELECT Websites, URI_PERCENT_ENCODE(Websites) from URI;
Websites
URI_PERCENT_ENCODE
----------------------------+-----------------------------------------http://example.com/?=11/15 | http%3A%2F%2Fexample.com%2F%3F%3D11%2F15
(1 row)

HP Vertica Analytic Database (7.0.x)

|

Page 540 of 1539

SQL Reference Manual
SQL Functions

HP Vertica Meta-Functions
HP Vertica built-in (meta) functions access the internal state of HP Vertica and are used in
SELECT queries with the function name and an argument (where required). These functions are not
part of the SQL standard and take the following form:
SELECT ();

Note: The query cannot contain other clauses, such as FROM or WHERE.
The behavior type of HP Vertica meta-functions is immutable.

HP Vertica Analytic Database (7.0.x)

Page 541 of 1539

SQL Reference Manual
SQL Functions

Alphabetical List of HP Vertica Meta-Functions
This section contains the HP Vertica meta-functions, listed alphabetically. These functions are also
grouped into their appropriate category.

ADD_LOCATION
Adds a storage location to the cluster. Use this function to add a new location, optionally with a
location label. You can also add a location specifically for user access, and then grant one or more
users access to the location.

Syntax
ADD_LOCATION ( 'path'

[, 'node' , 'usage', 'location_label' ] )

Parameters
path

[Required] Specifies where the storage location is mounted. Path must be an
empty directory with write permissions for user, group, or all.

node

[Optional] Indicates the cluster node on which a storage location resides. If you
omit this parameter, the function adds the location to only the initiator node.
Specifying the node parameter as an empty string ('') adds a storage location
to all cluster nodes in a single transaction.
Note: If you specify a node, you must also add a usage parameter.

HP Vertica Analytic Database (7.0.x)

Page 542 of 1539

SQL Reference Manual
SQL Functions

usage

[Optional] Specifies what the storage location will be used for:
l

DATA: Stores only data files. Use this option for labeled storage locations.

l

TEMP: Stores only temporary files, created during loads or queries.

l

DATA,TEMP: Stores both types of files in the location.

l

USER: Allows non-dbadmin users access to the storage location for data
files (not temp files), once they are granted privileges. DO NOT create a
storage location for later use in a storage policy. Storage locations with
policies must be for DATA usage. Also, note that this keyword is orthogonal
to DATA and TEMP, and does not specify a particular usage, other than
being accessible to non-dbadmin users with assigned privileges. You cannot
alter a storage location to or from USER usage.

NOTE: You can use this parameter only in conjunction with the node option. If
you omit the usage parameter, the default is DATA,TEMP.
location_label

[Optional] Specifies a location label as a string, for example, SSD. Labeling a
storage location lets you use the location label to create storage policies and as
part of a multi-tenanted storage scheme.

Privileges
Must be a superuser.

Storage Location Subdirectories
You cannot create a storage location in a subdirectory of an existing location. For example, if you
create a storage location at one location, you cannot add a second storage location in a
subdirectory of the first:
dbt=> select add_location ('/myvertica/Test/KMM','','DATA','SSD');
add_location
-----------------------------------------/myvertica/Test/KMM added.
(1 row)
dbt=> select add_location ('/myvertica/Test/KMM/SSD','','DATA','SSD');
ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert
ica/Test/KMM] on node v_node0001
ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert
ica/Test/KMM] on node v_node0002
ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert
ica/Test/KMM] on node v_node0003

Example
This example adds a location that stores data and temporary files on the initiator node:

HP Vertica Analytic Database (7.0.x)

Page 543 of 1539

SQL Reference Manual
SQL Functions

=> SELECT ADD_LOCATION('/secondverticaStorageLocation/');

This example adds a location to store data on v_vmartdb_node0004:
=> SELECT ADD_LOCATION('/secondverticaStorageLocation/' , 'v_vmartdb_node0004' , 'DATA');

This example adds a new DATA storage location with a label, SSD. The label identifies the location
when you create storage policies. Specifying the node parameter as an empty string adds the
storage location to all cluster nodes in a single transaction:
VMART=> select add_location ('home/dbadmin/SSD/schemas', '', 'DATA', 'SSD');
add_location
--------------------------------home/dbadmin/SSD/schemas added.
(1 row)

See Also
l

l

ALTER_LOCATION_USE

l

DROP_LOCATION

l

RESTORE_LOCATION

l

RETIRE_LOCATION

l

GRANT (Storage Location)

l

REVOKE (Storage Location)

ADVANCE_EPOCH
Manually closes the current epoch and begins a new epoch.

Syntax
ADVANCE_EPOCH ( [ integer ] )

Parameters
integer

Specifies the number of epochs to advance.

HP Vertica Analytic Database (7.0.x)

Page 544 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Notes
This function is primarily maintained for backward compatibility with earlier versions of HP Vertica.

Example
The following command increments the epoch number by 1:
=> SELECT ADVANCE_EPOCH(1);

See Also
l

ALTER PROJECTION RENAME

ALTER_LOCATION_USE
Alters the type of files that can be stored at the specified storage location.

Syntax
ALTER_LOCATION_USE ( 'path' , [ 'node' ] , 'usage' )

Parameters
path

Specifies where the storage location is mounted.

node

[Optional] The HP Vertica node with the storage location. Specifying the node parameter
as an empty string ('') alters the location across all cluster nodes in a single transaction.
If you omit this parameter, node defaults to the initiator.

usage

Is one of the following:
l

DATA: The storage location stores only data files. This is the supported use for both a
USER storage location, and a labeled storage location.

l

TEMP: The location stores only temporary files that are created during loads or
queries.

l

DATA,TEMP: The location can store both types of files.

HP Vertica Analytic Database (7.0.x)

Page 545 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

USER Storage Location Restrictions
You cannot change a storage location from a USER usage type if you created the location that way,
or to a USER type if you did not. You can change a USER storage location to specify DATA
(storing TEMP files is not supported). However, doing so does not affect the primary objective of a
USER storage location, to be accessible by non-dbadmin users with assigned privileges.

Monitoring Storage Locations
Disk storage information that the database uses on each node is available in the V_
MONITOR.DISK_STORAGE system table.

Example
The following example alters the storage location across all cluster nodes to store only data:
=> SELECT ALTER_LOCATION_USE ('/thirdVerticaStorageLocation/' , '' , 'DATA');

See Also
l

l

ADD_LOCATION

l

DROP_LOCATION

l

RESTORE_LOCATION

l

RETIRE_LOCATION

l

GRANT (Storage Location)

l

REVOKE (Storage Location)

ALTER_LOCATION_LABEL
Alters the location label. Use this function to add, change, or remove a location label. You change a
location label only if it is not currently in use as part of a storage policy.

HP Vertica Analytic Database (7.0.x)

Page 546 of 1539

SQL Reference Manual
SQL Functions

You can use this function to remove a location label. However, you cannot remove a location label if
the name being removed is used in a storage policy, and the location from which you are removing
the label is the last available storage for its associated objects.
Note: If you label an existing storage location that already contains data, and then include the
labeled location in one or more storage policies, existing data could be moved. If the ATM
determines data stored on a labeled location does not comply with a storage policy, the ATM
moves the data elsewhere.

Syntax
ALTER_LOCATION_LABEL ( 'path' , 'node' , 'location_label' )

Parameters
path

Specifies the path of the storage location.

node

The HP Vertica node for the storage location.
If you enter node as an empty string (''), the function performs a cluster-wide
label change to all nodes. Any node that is unavailable generates an error.

location_label

Specifies a storage label as a string, for instance SSD. You can change an
existing label assigned to a storage location, or add a new label. Specifying an
empty string ('') removes an existing label.

Privileges
Must be a superuser.

Example
The following example alters (or adds) the label SSD to the storage location at the given path on all
cluster nodes:
VMART=> select alter_location_label('/home/dbadmin/SSD/tables','', 'SSD');
alter_location_label
--------------------------------------/home/dbadmin/SSD/tables label changed.
(1 row)

See Also
l

HP Vertica Analytic Database (7.0.x)

Page 547 of 1539

SQL Reference Manual
SQL Functions

l

CLEAR_OBJECT_STORAGE_POLICY

l

SET_OBJECT_STORAGE_POLICY

ANALYZE_CONSTRAINTS
Analyzes and reports on constraint violations within the current schema search path, or external to
that path if you specify a database name (noted in the syntax statement and parameter table).
You can check for constraint violations by passing arguments to the function as follows:
l

An empty argument (' '), which returns violations on all tables within the current schema

l

One argument, referencing a table

l

Two arguments, referencing a table name and a column or list of columns

Syntax
ANALYZE_CONSTRAINTS [ ( '' )
... | ( '[[db-name.]schema.]table [.column_name]' )
... | ( '[[db-name.]schema.]table' , 'column' ) ]

Parameters
('')

Analyzes and reports on all tables within the current schema search path.

[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table

Analyzes and reports on all constraints referring to the specified table.

column

Analyzes and reports on all constraints referring to the specified table that
contains the column.

Privileges
l

SELECT privilege on table

l

USAGE privilege on schema

HP Vertica Analytic Database (7.0.x)

Page 548 of 1539

SQL Reference Manual
SQL Functions

Notes
ANALYZE_CONSTRAINTS() performs a lock in the same way that SELECT * FROM t1 holds a
lock on table t1. See LOCKS for additional information.

Detecting Constraint Violations During a Load Process
HP Vertica checks for constraint violations when queries are run, not when data is loaded. To
detect constraint violations as part of the load process, use a COPY statement with the NO
COMMIT option. By loading data without committing it, you can run a post-load check of your data
using the ANALYZE_CONSTRAINTS function. If the function finds constraint violations, you can
roll back the load because you have not committed it.
If ANALYZE_CONSTRAINTS finds violations, such as when you insert a duplicate value into a
primary key, you can correct errors using the following functions. Effects last until the end of the
session only:
l

SELECT DISABLE_DUPLICATE_KEY_ERROR

l

SELECT REENABLE_DUPLICATE_KEY_ERROR

Return Values
ANALYZE_CONSTRAINTS returns results in a structured set (see table below) that lists the
schema name, table name, column name, constraint name, constraint type, and the column values
that caused the violation.
If the result set is empty, then no constraint violations exist; for example:
> SELECT ANALYZE_CONSTRAINTS ('public.product_dimension', 'product_key');
Schema Name | Table Name | Column Names | Constraint Name | Constraint Type | Column Valu
es
-------------+------------+--------------+-----------------+-----------------+-------------(0 rows)

The following result set shows a primary key violation, along with the value that caused the
violation ('10'):
=> SELECT ANALYZE_CONSTRAINTS ('');
Schema Name | Table Name | Column Names | Constraint Name | Constraint Type | Column Valu
es
-------------+------------+--------------+-----------------+-----------------+-------------store
t1
c1
pk_t1
PRIMARY
('10')
(1 row)

The result set columns are described in further detail in the following table:

HP Vertica Analytic Database (7.0.x)

Page 549 of 1539

SQL Reference Manual
SQL Functions

Column Name Data Type

Description

Schema Name

VARCHAR

The name of the schema.

Table Name

VARCHAR

The name of the table, if specified.

Column Names

VARCHAR

Names of columns containing constraints. Multiple columns are
in a comma-separated list:
store_key, store_key, date_key,

Constraint Name

VARCHAR

The given name of the primary key, foreign key, unique, or not
null constraint, if specified.

Constraint Type

VARCHAR

Identified by one of the following strings: 'PRIMARY KEY',
'FOREIGN KEY', 'UNIQUE', or 'NOT NULL'.

Column Values

VARCHAR

Value of the constraint column, in the same order in which
Column Names contains the value of that column in the violating
row.
When interpreted as SQL, the value of this column forms a list of
values of the same type as the columns in Column Names; for
example:
('1'), ('1', 'z')

Understanding Function Failures
If ANALYZE_CONSTRAINTS() fails, HP Vertica returns an error identifying the failure condition,
such as if there are insufficient resources for the database to perform constraint checks.
If you specify the wrong table, the system returns an error message:
> SELECT ANALYZE_CONSTRAINTS('abc');
ERROR 2069: 'abc' is not a table in the current search_path

If you run the function on a table that has no constraints declared (even if duplicates are present),
the system returns an error message:
> SELECT ANALYZE_CONSTRAINTS('source');
ERROR 4072: No constraints defined

If you run the function with incorrect syntax, the system returns an error message with a hint; for
example, if you run one of the following:
l

ANALYZE ALL CONSTRAINT;

l

ANALYZE CONSTRAINT abc;

The system returns an informative error with hint:

HP Vertica Analytic Database (7.0.x)

Page 550 of 1539

SQL Reference Manual
SQL Functions

ERROR: ANALYZE CONSTRAINT is not supported.
HINT: You may consider using analyze_constraints().

If you run ANALYZE_CONSTRAINTS from a non-default locale, the function returns an error with a
hint:
> \locale LENINFO 2567: Canonical locale: 'en'
Standard collation: 'LEN'
English
> SELECT ANALYZE_CONSTRAINTS('t1');
ERROR: ANALYZE_CONSTRAINTS is currently not supported in
non-default locales
HINT: Set the locale in this session to
en_US@collation=binary using the command
"\locale en_US@collation=binary"

Examples
Given the following inputs, HP Vertica returns one row, indicating one violation, because the same
primary key value (10) was inserted into table t1 twice:
CREATE TABLE t1(c1 INT);
ALTER TABLE t1 ADD CONSTRAINT pk_t1 PRIMARY KEY (c1);
CREATE PROJECTION t1_p (c1) AS SELECT *
FROM t1 UNSEGMENTED ALL NODES;
INSERT INTO t1 values (10);
INSERT INTO t1 values (10); --Duplicate primary key value
\x
Expanded display is on.
SELECT ANALYZE_CONSTRAINTS('t1');
-[ RECORD 1 ]---+-------Schema Name
| public
Table Name
| t1
Column Names
| c1
Constraint Name | pk_t1
Constraint Type | PRIMARY
Column Values
| ('10')

If the second INSERT statement above had contained any different value, the result would have
been 0 rows (no violations).
In the following example, create a table that contains three integer columns, one a unique key and
one a primary key:
CREATE TABLE table_1(
a INTEGER,
b_UK INTEGER UNIQUE,
c_PK INTEGER PRIMARY KEY
);

HP Vertica Analytic Database (7.0.x)

Page 551 of 1539

SQL Reference Manual
SQL Functions

Issue a command that refers to a nonexistent table and column:
SELECT ANALYZE_CONSTRAINTS('a_BB');
ERROR: 'a_BB' is not a table name in the current search path

Issue a command that refers to a nonexistent column:
SELECT ANALYZE_CONSTRAINTS('table_1','x');
ERROR 41614: Nonexistent columns: 'x '

Insert some values into table table_1 and commit the changes:
INSERT INTO table_1 values (1, 1, 1);
COMMIT;

Run ANALYZE_CONSTRAINTS on table table_1. No constraint violations are reported:
SELECT ANALYZE_CONSTRAINTS('table_1');
(No rows)

Insert duplicate unique and primary key values and run ANALYZE_CONSTRAINTS on table
table_1 again. The system shows two violations: one against the primary key and one against the
unique key:
INSERT INTO table_1 VALUES (1, 1, 1);
COMMIT;
SELECT ANALYZE_CONSTRAINTS('table_1');

-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| b_UK
Constraint Name | C_UNIQUE
Constraint Type | UNIQUE
Column Values
| ('1')
-[ RECORD 2 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')

The following command looks for constraint validations on only the unique key in the table table_1,
qualified with its schema name:
=> SELECT ANALYZE_CONSTRAINTS('public.table_1', 'b_UK');
-[ RECORD 1 ]---+--------Schema Name
| public

HP Vertica Analytic Database (7.0.x)

Page 552 of 1539

SQL Reference Manual
SQL Functions

Table Name
Column Names
Constraint Name
Constraint Type
Column Values

|
|
|
|
|

table_1
b_UK
C_UNIQUE
UNIQUE
('1')

(1 row)

The following example shows that you can specify the same column more than once; ANALYZE_
CONSTRAINTS, however, returns the violation only once:
SELECT ANALYZE_CONSTRAINTS('table_1', 'c_PK, C_PK');
-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')

The following example creates a new table, table_2, and inserts a foreign key and different
(character) data types:
CREATE TABLE table_2 (
x VARCHAR(3),
y_PK VARCHAR(4),
z_FK INTEGER REFERENCES table_1(c_PK));

Alter the table to create a multicolumn unique key and multicolumn foreign key and create
superprojections:
ALTER TABLE table_2
ADD CONSTRAINT table_2_multiuk PRIMARY KEY (x, y_PK);
WARNING 2623: Column "x" definition changed to NOT NULL
WARNING 2623: Column "y_PK" definition changed to NOT NULL

The following command inserts a missing foreign key (0) into table dim_1 and commits the
changes:
INSERT INTO table_2 VALUES ('r1', 'Xpk1', 0);
COMMIT;

Checking for constraints on the table table_2 in the public schema detects a foreign key
violation:
=> SELECT ANALYZE_CONSTRAINTS('public.table_2');
-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_2

HP Vertica Analytic Database (7.0.x)

Page 553 of 1539

SQL Reference Manual
SQL Functions

Column Names
Constraint Name
Constraint Type
Column Values

|
|
|
|

z_FK
C_FOREIGN
FOREIGN
('0')

Now add a duplicate value into the unique key and commit the changes:
INSERT INTO table_2 VALUES ('r2', 'Xpk1', 1);
INSERT INTO table_2 VALUES ('r1', 'Xpk1', 1);
COMMIT;

Checking for constraint violations on table table_2 detects the duplicate unique key error:
SELECT ANALYZE_CONSTRAINTS('table_2');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| z_FK
Constraint Name | C_FOREIGN
Constraint Type | FOREIGN
Column Values
| ('0')
-[ RECORD 2 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| x, y_PK
Constraint Name | table_2_multiuk
Constraint Type | PRIMARY
Column Values
| ('r1', 'Xpk1')

Create a table with multicolumn foreign key and create the superprojections:
CREATE TABLE table_3(
z_fk1 VARCHAR(3),
z_fk2 VARCHAR(4));
ALTER TABLE table_3
ADD CONSTRAINT table_3_multifk FOREIGN KEY (z_fk1, z_fk2)
REFERENCES table_2(x, y_PK);

Insert a foreign key that matches a foreign key in table table_2 and commit the changes:
INSERT INTO table_3 VALUES ('r1', 'Xpk1');
COMMIT;

Checking for constraints on table table_3 detects no violations:
SELECT ANALYZE_CONSTRAINTS('table_3');
(No rows)

Add a value that does not match and commit the change:
INSERT INTO table_3 VALUES ('r1', 'NONE');

HP Vertica Analytic Database (7.0.x)

Page 554 of 1539

SQL Reference Manual
SQL Functions

COMMIT;

Checking for constraints on table dim_2 detects a foreign key violation:
SELECT ANALYZE_CONSTRAINTS('table_3');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_3
Column Names
| z_fk1, z_fk2
Constraint Name | table_3_multifk
Constraint Type | FOREIGN
Column Values
| ('r1', 'NONE')

Analyze all constraints on all tables:
SELECT ANALYZE_CONSTRAINTS('');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_3
Column Names
| z_fk1, z_fk2
Constraint Name | table_3_multifk
Constraint Type | FOREIGN
Column Values
| ('r1', 'NONE')
-[ RECORD 2 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| x, y_PK
Constraint Name | table_2_multiuk
Constraint Type | PRIMARY
Column Values
| ('r1', 'Xpk1')
-[ RECORD 3 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| z_FK
Constraint Name | C_FOREIGN
Constraint Type | FOREIGN
Column Values
| ('0')
-[ RECORD 4 ]---+---------------Schema Name
| public
Table Name
| t1
Column Names
| c1
Constraint Name | pk_t1
Constraint Type | PRIMARY
Column Values
| ('10')
-[ RECORD 5 ]---+---------------Schema Name
| public
Table Name
| table_1
Column Names
| b_UK
Constraint Name | C_UNIQUE
Constraint Type | UNIQUE
Column Values
| ('1')
-[ RECORD 6 ]---+---------------Schema Name
| public
Table Name
| table_1

HP Vertica Analytic Database (7.0.x)

Page 555 of 1539

SQL Reference Manual
SQL Functions

Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')
-[ RECORD 7 ]---+---------------Schema Name
| public
Table Name
| target
Column Names
| a
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')
(5 rows)

To quickly clean up your database, issue the following command:
DROP TABLE table_1 CASCADE;
DROP TABLE table_2 CASCADE;
DROP TABLE table_3 CASCADE;

To learn how to remove violating rows, see the DISABLE_DUPLICATE_KEY_ERROR function.

ANALYZE_CORRELATIONS
Analyzes the specified tables for columns that are strongly correlated. In addition, ANALYZE_
CORRELATIONS also collects statistics.
For example, state name and country name columns are strongly correlated because the city name
usually, but perhaps not always, identifies the state name. The city of Conshohoken is uniquely
associated with Pennsylvania, whereas the city of Boston exists in Georgia, Indiana, Kentucky,
New York, Virginia, and Massachusetts. In this case, city name is strongly correlated with state
name.
For Database Designer to take advantage of these correlations, run Database Designer
programmatically. Use DESIGNER_SET_ANALYZE_CORRELATIONS_MODE to specify that
Database Designer should consider existing column correlations. Make sure to specify that
Database Designer not analyze statistics so that Database Designer does not override the existing
statistics.

Behavior Type
Immutable

Syntax
ANALYZE_CORRELATIONS (
'[database_name.][schema_name.]table_name',
[recalculate] )

HP Vertica Analytic Database (7.0.x)

Page 556 of 1539

SQL Reference Manual
SQL Functions

Parameters
database_name

Specifies the table(s) for which to analyze correlated columns, type VARCHAR.

schema_name
table_name
recalculate

Specifies to analyze the correlated columns, even if they have been analyzed
before, type BOOLEAN. Default: 'false'.

Permissions
l

To run ANALYZE_CORRELATIONS on a table, you must be a superuser, or a user w USAGE
privilege on the design schema.

Notes
l

Column correlation analysis typically needs to be done only once.

l

Currently, ANALYZE_CORRELATIONS can analyze only pairwise single-column correlations.

l

Projections do not change based on the analysis results. To implement the results of
ANALYZE_CORRELATIONS, you must run Database Designer.

Example
In the following example, ANALYZE_CORRELATIONS analyzes column correlations for all tables
in the public schema,even if they currently exist. The correlations that ANALYZE_
CORRELATIONS finds are saved so that Database Designer can use them the next time it runs on
the VMart database:
=> SELECT ANALYZE_CORRELATIONS (
'public.*',
'true');
ANALYZE_CORRELATIONS
---------------------0
(1 row)

See Also
l

DESIGNER_SET_ANALYZE_CORRELATIONS_MODE

HP Vertica Analytic Database (7.0.x)

Page 557 of 1539

SQL Reference Manual
SQL Functions

ANALYZE_HISTOGRAM
Collects and aggregates data samples and storage information from all nodes that store projections
associated with the specified table or column.
If the function returns successfully (0), HP Vertica writes the returned statistics to the catalog. The
query optimizer uses this collected data to recommend the best possible plan to execute a query.
Without analyzing table statistics, the query optimizer would assume uniform distribution of data
values and equal storage usage for all projections.
ANALYZE_HISTOGRAM is a DDL operation that auto-commits the current transaction, if any. The
ANALYZE_HISTOGRAM function reads a variable amount of disk contents to aggregate sample
data for statistical analysis. Use the function's percent float parameter to specify the total disk
space from which HP Vertica collects sample data. The ANALYZE_STATISTICS function returns
similar data, but uses a fixed disk space amount (10 percent). Analyzing more than 10 percent disk
space takes proportionally longer to process, but produces a higher level of sampling accuracy.
ANALYZE_HISTOGRAM is supported on local temporary tables, but not on global temporary
tables.

Syntax
ANALYZE_HISTOGRAM ('') ... | ( '[ [ db-name.]schema.]table [.column-name ]' [, percent ] )

Return Value
0 - For success. If an error occurs, refer to vertica.log for details.

Parameters
''

Empty string. Collects statistics for all tables.

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

HP Vertica Analytic Database (7.0.x)

Page 558 of 1539

SQL Reference Manual
SQL Functions

table

Specifies the name of the table and collects statistics for all projections of
that table. If you are using more than one schema, specify the schema that
contains the projection, as noted in the [[db-name.]schema.] entry.

[.column-name]

[Optional] Specifies the name of a single column, typically a predicate
column. Using this option with a table specification lets you collect
statistics for only that column.
Note: If you alter a table to add or drop a column, or add a new column
to a table and populate its contents with either default or other values,
HP Vertica recommends calling this function on the new table column
to get the most current statistics.

percent

[Optional] Specifies what percentage of data to read from disk (not the
amount of data to analyze). Specify a float from 1 – 100, such as 33.3. By
default, the function reads 10% of the table data from disk.
For more information, see Collecting Statistics in the Administrator's
Guide.

Privileges
l

Any INSERT/UPDATE/DELETE privilege on table

l

USAGE privilege on schema that contains the table

Use the HP Vertica statistics functions as follows:
Use this
function...
ANALYZE_
STATISTICS

To obtain...
A fixed-size statistical data sampling (10 percent per disk). This function returns
results quickly, but is less accurate than using ANALYZE_HISTOGRAM to get
a larger sampling of disk data.

ANALYZE_
A specified percentage of disk data sampling (from 1–100). If you analyze more
HISTOGRAM than 10 percent data per disk, this function is more accurate than ANALYZE_
STATISTICS, but requires proportionately longer to return statistics.

Analyzing Results
To retrieve hints about under-performing queries and the associated root causes, use the
ANALYZE_WORKLOAD function. This function runs the Workload Analyzer and returns tuning
recommendations, such as "run analyze_statistics on schema.table.column". You or your
database administrator should act upon the tuning recommendations.
You can also find database tuning recommendations on the Management Console.

HP Vertica Analytic Database (7.0.x)

Page 559 of 1539

SQL Reference Manual
SQL Functions

Canceling ANALYZE_HISTOGRAM
You can cancel this function mid-analysis by issuing CTRL-C in a vsql shell or by invoking the
INTERRUPT_STATEMENT() function.

Notes
By default, HP Vertica analyzes more than one column (subject to resource limits) in a single-query
execution plan to:
l

Reduce plan execution latency

l

Help speed up analysis of relatively small tables that have a large number of columns

Examples
In this example, the ANALYZE_STATISTICS() function reads 10 percent of the disk data. This is
the static default value for this function. The function returns 0 for success:
=> SELECT ANALYZE_STATISTICS('shipping_dimension.shipping_key');
ANALYZE_STATISTICS
-------------------0
(1 row)

This example uses ANALYZE_HISTOGRAM () without specifying a percentage value. Since this
function has a default value of 10 percent, it returns the identical data as the ANALYZE_
STATISTICS() function, and returns 0 for success:
=> SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key');
ANALYZE_HISTOGRAM
------------------0
(1 row)

This example uses ANALYZE_HISTOGRAM (), specifying its percent parameter as 100, indicating
it will read the entire disk to gather data. After the function performs a full column scan, it returns 0
for success:
=> SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key', 100);
ANALYZE_HISTOGRAM
------------------0
(1 row)

In this command, only 0.1% (1/1000) of the disk is read:

HP Vertica Analytic Database (7.0.x)

Page 560 of 1539

SQL Reference Manual
SQL Functions

=> SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key', 0.1);
ANALYZE_HISTOGRAM
------------------0
(1 row)

See Also
l

ANALYZE_STATISTICS

l

ANALYZE_WORKLOAD

l

DROP_STATISTICS

l

EXPORT_STATISTICS

l

IMPORT_STATISTICS
INTERRUPT_STATEMENT

l
l

ANALYZE_STATISTICS
Collects and aggregates data samples and storage information from all nodes that store projections
associated with the specified table or column.
If the function returns successfully (0), HP Vertica writes the returned statistics to the catalog. The
query optimizer uses this collected data to recommend the best possible plan to execute a query.
Without analyzing table statistics, the query optimizer would assume uniform distribution of data
values and equal storage usage for all projections.
ANALYZE_STATISTICS is a DDL operation that auto-commits the current transaction, if any. The
ANALYZE_STATISTICS function reads a fixed, 10 percent of disk contents to aggregate sample
data for statistical analysis. To obtain a larger (or smaller) data sampling, use the ANALYZE_
HISTOGRAM function, which lets you specify the percent of disk to read. Analyzing more that 10
percent disk space takes proportionally longer to process, but results in a higher level of sampling
accuracy. ANALYZE_STATISTICS is supported on local temporary tables, but not on global
temporary tables.

Syntax
ANALYZE_STATISTICS [ ('') ... | ( '[ [ db-name.]schema.]table [.column-name ]' ) ]

Return value
0 - For success.
If an error occurs, refer to vertica.log for details.

HP Vertica Analytic Database (7.0.x)

Page 561 of 1539

SQL Reference Manual
SQL Functions

Parameters
''

Empty string. Collects statistics for all tables.

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

table

Specifies the name of the table and collects statistics for all projections of
that table.
Note: If you are using more than one schema, specify the schema
that contains the projection, as noted as noted in the [[db-name.]
schema.] entry.

[.column-name]

[Optional] Specifies the name of a single column, typically a predicate
column. Using this option with a table specification lets you collect
statistics for only that column.
Note: If you alter a table to add or drop a column, or add a new column
to a table and populate its contents with either default or other values,
HP Vertica recommends calling this function on the new table column
to get the most current statistics.

Privileges
l

Any INSERT/UPDATE/DELETE privilege on table

l

USAGE privilege on schema that contains the table

Use the HP Vertica statistics functions as follows:

HP Vertica Analytic Database (7.0.x)

Page 562 of 1539

SQL Reference Manual
SQL Functions

Use this
function...
ANALYZE_
STATISTICS

To obtain...
A fixed-size statistical data sampling (10 percent per disk). This function returns
results quickly, but is less accurate than using ANALYZE_HISTOGRAM to get
a larger sampling of disk data.

ANALYZE_
A specified percentage of disk data sampling (from 1–100). If you analyze more
HISTOGRAM than 10 percent data per disk, this function is more accurate than ANALYZE_
STATISTICS, but requires proportionately longer to return statistics.

Analyzing results
To retrieve hints about under-performing queries and the associated root causes, use the
ANALYZE_WORKLOAD function. This function runs the Workload Analyzer and returns tuning
recommendations, such as "run analyze_statistics on schema.table.column". You or your
database administrator should act upon the tuning recommendations.
You can also find database tuning recommendations on the Management Console.

Canceling this function
You can cancel statistics analysis by issuing CTRL+C in a vsql shell or by invoking the
INTERRUPT_STATEMENT() function.

Notes
l

Always run ANALYZE_STATISTICS on a table or column rather than a projection.

l

By default, HP Vertica analyzes more than one column (subject to resource limits) in a singlequery execution plan to:

l

n

Reduce plan execution latency

n

Help speed up analysis of relatively small tables that have a large number of columns

Pre-join projection statistics are updated on any pre-joined tables.

Examples
Computes statistics on all projections in the VMart database and returns 0 (success):
=> SELECT ANALYZE_STATISTICS ('');
analyze_statistics
-------------------0
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 563 of 1539

SQL Reference Manual
SQL Functions

Computes statistics on a single table (shipping_dimension) and returns 0 (success):
=> SELECT ANALYZE_STATISTICS ('shipping_dimension');
analyze_statistics
-------------------0
(1 row)

Computes statistics on a single column (shipping_key) across all projections for the shipping_
dimension table and returns 0 (success):
=> SELECT ANALYZE_STATISTICS('shipping_dimension.shipping_key');
analyze_statistics
-------------------0
(1 row)

For use cases, see Collecting Statistics in the Administrator's Guide

See Also
l

ANALYZE_HISTOGRAM

l

ANALYZE_WORKLOAD

l

DROP_STATISTICS

l

EXPORT_STATISTICS

l

IMPORT_STATISTICS

l

INTERRUPT_STATEMENT

ANALYZE_WORKLOAD
Runs the Workload Analyzer (WLA), a utility that analyzes system information held in system
tables.
The Workload Analyzer intelligently monitors the performance of SQL queries and workload history,
resources, and configurations to identify the root causes for poor query performance. Calling the
ANALYZE_WORKLOAD function returns tuning recommendations for all events within the scope
and time that you specify.
Tuning recommendations are based on a combination of statistics, system and data collector
events, and database-table-projection design. WLA's recommendations let database
administrators quickly and easily tune query performance without needing sophisticated skills.
See Understanding WLA Triggering Conditions in the Administrator's Guide for the most common
triggering conditions and recommendations.

HP Vertica Analytic Database (7.0.x)

Page 564 of 1539

SQL Reference Manual
SQL Functions

Syntax 1
ANALYZE_WORKLOAD ( 'scope' , 'since_time' );

Syntax 2
ANALYZE_WORKLOAD ( 'scope' , [ true ] );

Parameters
scope

Specifies which HP Vertica catalog objects to analyze.
Can be one of:

sinc
e_tim
e

l

An empty string ('') returns recommendations for all database objects

l

'table_name' returns all recommendations related to the specified table

l

'schema_name' returns recommendations on all database objects in the specified
schema

Limits the recommendations from all events that you specified in 'scope' since the
specified time in this argument, up to the current system status. If you omit the since_
time parameter, ANALYZE_WORKLOAD returns recommendations on events since the
last recorded time that you called this function.
Note: You must explicitly cast strings that you use for the since_time parameter to
TIMESTAMP or TIMESTAMPTZ. For example:
SELECT ANALYZE_WORKLOAD('T1', '2010-10-04 11:18:15'::TIMESTAMPTZ);SELECT ANALYZE_WO
RKLOAD('T1', TIMESTAMPTZ '2010-10-04 11:18:15');

true

[Optional] Tells HP Vertica to record this particular call of WORKLOAD_ANALYZER() in
the system. The default value is false (do not record). If recorded, subsequent calls to
ANALYZE_WORKLOAD analyze only the events that have occurred since this recorded
time, ignoring all prior events.

Return Value
Column

Data type

Description

observation_coun
t

INTEGER

Integer for the total number of events observed for this tuning
recommendation. For example, if you see a return value of 1,
WLA is making its first tuning recommendation for the event
in 'scope'.

HP Vertica Analytic Database (7.0.x)

Page 565 of 1539

SQL Reference Manual
SQL Functions

Column

Data type

Description

first_observatio
n_time

TIMESTAM
PTZ

Timestamp when the event first occurred. If this column
returns a null value, the tuning recommendation is from the
current status of the system instead of from any prior event.

last_observatio
n_time

TIMESTAM
PTZ

Timestamp when the event last occurred. If this column
returns a null value, the tuning recommendation is from the
current status of the system instead of from any prior event.

tuning_parameter

VARCHAR

Objects on which you should perform a tuning action. For
example, a return value of:

tuning_descripti
on

VARCHAR

HP Vertica Analytic Database (7.0.x)

l

public.t informs the DBA to run Database Designer on
table t in the public schema

l

bsmith notifies a DBA to set a password for user bsmith

Textual description of the tuning recommendation from the
Workload Analyzer to perform on the tuning_parameter
object. Examples of some of the returned values include, but
are not limited to:
l

Run database designer on table schema.table

l

Create replicated projection for table schema.table

l

Consider incremental design on query

l

Reset configuration parameter with SELECT set_config_
parameter('parameter', 'new_value')

l

Re-segment projection projection-name on highcardinality column(s)

l

Drop the projection projection-name

l

Alter a table's partition expression

l

Reorganize data in partitioned table

l

Decrease the MoveOutInterval configuration parameter
setting

Page 566 of 1539

SQL Reference Manual
SQL Functions

Column

Data type

Description

tuning_command

VARCHAR

Command string if tuning action is a SQL command. For
example, the following example statements recommend that
the DBA:
Update statistics on a particular schema's table.column:
SELECT ANALYZE_STATISTICS('public.table.column');

Resolve mismatched configuration parameter 'LockTimeout':
SELECT * FROM CONFIGURATION_PARAMETERSWHERE parameter_name
= 'LockTimeout';

Set the password for user bsmith:
ALTER USER (user) IDENTIFIED BY ('new_password');
tuning_cost

VARCHAR

Cost is based on the type of tuning recommendation and is
one of:
l

LOW—minimal impact on resources from running the
tuning command

l

MEDIUM—moderate impact on resources from running
the tuning command

l

HIGH—maximum impact on resources from running the
tuning command

Depending on the size of your database or table, consider
running high-cost operations after hours instead of during
peak load times.
ANALYZE_WORKLOAD() returns aggregated tuning recommendations, as described in the
TUNING_RECOMMENDATIONS table.

Privileges
Must be a superuser.

Examples
See Analyzing Workloads through an API in the Administrator's Guide for examples.

HP Vertica Analytic Database (7.0.x)

Page 567 of 1539

SQL Reference Manual
SQL Functions

See Also
TUNING_RECOMMENDATIONS

l
l

l

AUDIT
Estimates the raw data size of a database, a schema, a projection, or a table as it is counted in an
audit of the database size.
The AUDIT function estimates the size using the same data sampling method as the audit that HP
Vertica performs to determine if a database is compliant with the database size allowances in its
license. The results of this function are not considered when HP Vertica determines whether the
size of the database complies with the HP Vertica license's data allowance. See How HP Vertica
Calculates Database Size in the Administrator's Guide for details.
Note: This function can only audit the size of tables, projections, schemas, and databases
which the user has permission to access. If a non-superuser attempts to audit the entire
database, the audit will only estimate the size of the data that the user is allowed to read.

Syntax
AUDIT([name] [, granularity] [, error_tolerance [, confidence_level]])

Parameters
name

Specifies the schema, projection, or table to audit. Enter name as a string, in
single quotes (''). If the name string is empty (''), the entire database is
audited.

HP Vertica Analytic Database (7.0.x)

Page 568 of 1539

SQL Reference Manual
SQL Functions

granularity

Indicates the level at which the audit reports its results. The recognized levels
are:
l

'schema'

l

'table'

l

'projection'

By default, the granularity is the same level as name. For example, if name is a
schema, then the size of the entire schema is reported. If you instead specify
'table' as the granularity, AUDIT reports the size of each table in the
schema. The granularity must be finer than that of object: specifying
'schema' for an audit of a table has no effect.
The results of an audit with a granularity are reported in the V_
CATALOG.USER_AUDITS system table.
error_tolerance

Specifies the percentage margin of error allowed in the audit estimate. Enter
the tolerance value as a decimal number, between 0 and 100. The default
value is 5, for a 5% margin of error.
Note: The lower this value is, the more resources the audit uses since it will
perform more data sampling. Setting this value to 0 results in a full audit of the
database, which is very resource intensive, as all of the data in the database
is analyzed. Doing a full audit of the database significantly impacts
performance and is not recommended on a production database.

confidence_level

Specifies the statistical confidence level percentage of the estimate. Enter
the confidence value as a decimal number, between 0 and 100. The default
value is 99, indicating a confidence level of 99%.
Note: The higher the confidence value, the more resources the function
uses since it will perform more data sampling. Setting this value to 1
results in a full audit of the database, which is very resource intensive, as
all of the database is analyzed. Doing a full audit of the database
significantly impacts performance and is not recommended on a
production database.

Permissions
l

SELECT privilege on table

l

USAGE privilege on schema
Note: AUDIT() works only on the tables where the user calling the function has SELECT
permissions.

HP Vertica Analytic Database (7.0.x)

Page 569 of 1539

SQL Reference Manual
SQL Functions

Notes
Due to the iterative sampling used in the auditing process, making the error tolerance a small
fraction of a percent (0.00001, for example) can cause the AUDIT function to run for a longer period
than a full database audit.

Examples
To audit the entire database:
=> SELECT AUDIT('');
AUDIT
---------76376696
(1 row)

To audit the database with a 25% error tolerance:
=> SELECT AUDIT('',25);
AUDIT
---------75797126
(1 row)

To audit the database with a 25% level of tolerance and a 90% confidence level:
=> SELECT AUDIT('',25,90);
AUDIT
---------76402672
(1 row)

To audit just the online_sales schema in the VMart example database:
VMart=> SELECT AUDIT('online_sales');
AUDIT
---------35716504
(1 row)

To audit the online_sales schema and report the results by table:
=> SELECT AUDIT('online_sales','table');
AUDIT
-----------------------------------------------------------------See table sizes in v_catalog.user_audits for schema
online_sales
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 570 of 1539

SQL Reference Manual
SQL Functions

=> \x
Expanded display is on.
=> SELECT * FROM user_audits WHERE object_schema =
'online_sales';
-[ RECORD 1 ]-------------------------+-----------------------------size_bytes
| 64960
user_id
| 45035996273704962
user_name
| dbadmin
object_id
| 45035996273717636
object_type
| TABLE
object_schema
| online_sales
object_name
| online_page_dimension
audit_start_timestamp
| 2011-04-05 09:24:48.224081-04
audit_end_timestamp
| 2011-04-05 09:24:48.337551-04
confidence_level_percent
| 99
error_tolerance_percent
| 5
used_sampling
| f
confidence_interval_lower_bound_bytes | 64960
confidence_interval_upper_bound_bytes | 64960
sample_count
| 0
cell_count
| 0
-[ RECORD 2 ]-------------------------+-----------------------------size_bytes
| 20197
user_id
| 45035996273704962
user_name
| dbadmin
object_id
| 45035996273717640
object_type
| TABLE
object_schema
| online_sales
object_name
| call_center_dimension
audit_start_timestamp
| 2011-04-05 09:24:48.340206-04
audit_end_timestamp
| 2011-04-05 09:24:48.365915-04
confidence_level_percent
| 99
error_tolerance_percent
| 5
used_sampling
| f
confidence_interval_lower_bound_bytes | 20197
confidence_interval_upper_bound_bytes | 20197
sample_count
| 0
cell_count
| 0
-[ RECORD 3 ]-------------------------+-----------------------------size_bytes
| 35614800
user_id
| 45035996273704962
user_name
| dbadmin
object_id
| 45035996273717644
object_type
| TABLE
object_schema
| online_sales
object_name
| online_sales_fact
audit_start_timestamp
| 2011-04-05 09:24:48.368575-04
audit_end_timestamp
| 2011-04-05 09:24:48.379307-04
confidence_level_percent
| 99
error_tolerance_percent
| 5
used_sampling
| t
confidence_interval_lower_bound_bytes | 34692956
confidence_interval_upper_bound_bytes | 36536644
sample_count
| 10000
cell_count
| 9000000

HP Vertica Analytic Database (7.0.x)

Page 571 of 1539

SQL Reference Manual
SQL Functions

AUDIT_FLEX
Estimates the ROS size of one or more flexible tables contained in a database, schema, or
projection. Use this function for flex tables only. Invoking audit_flex() with a columnar table
results in an error.
The audit_flex() function measures encoded, compressed data stored in ROS containers for the
__raw__ column of one or more flexible tables. The function does not audit other flex table columns
that are created as, or promoted to, real columns. Temporary flex tables are not included in the
audit.
Each time a user calls audit_flex(), HP Vertica stores the results in the V_CATALOG.USER_
AUDITS system table.

Syntax
AUDIT_FLEX (name)

Parameters
name

Specifies what database entity to audit. Enter the entity name as a string in single quotes
(''), as follows:
l

Empty string ('') — Return the size of the ROS containers for all flexible tables in the
database. You cannot enter the database name.

l

Schema name ('schema_name') — Return the size of all __raw__ columns of flexible
tables in schema_name.

l

A projection name ('proj_name') — Return the ROS size of a projection for a __raw__
column.

l

A flex table name ('flex_table_name') — Return the ROS size of a flex table's __
raw__ column.

Permissions
l

SELECT privilege on table

l

USAGE privilege on schema
Note: AUDIT_FLEX() works only on the flexible tables, projections, schemas, and databases
to which the user has permissions.

HP Vertica Analytic Database (7.0.x)

Page 572 of 1539

SQL Reference Manual
SQL Functions

Examples
To audit the flex tables in the database:
dbs=> select audit_flex('');
audit_flex
-----------8567679
(1 row)

To audit the flex tables in a specific schema, such as public:
dbs=> select audit_flex('public');
audit_flex
-----------8567679
(1 row)

To audit the flex tables in a specific projection, such as bakery_b0:
dbs=> select audit_flex('bakery_b0');
audit_flex
-----------8566723
(1 row)

To audit a flex table, such as bakery:
dbs=> select audit_flex('bakery');
audit_flex
-----------8566723
(1 row)

To report the results of all audits saved in the USER_AUDITS, the following shows part of an
extended display from the system table showing an audit run on a schema called test, and the
entire database, dbs:
dbs=> \x
Expanded display is on.
dbs=> select * from user_audits;
-[ RECORD 1 ]-------------------------+-----------------------------size_bytes
| 0
user_id
| 45035996273704962
user_name
| release
object_id
| 45035996273736664
object_type
| SCHEMA
object_schema
|
object_name
| test

HP Vertica Analytic Database (7.0.x)

Page 573 of 1539

SQL Reference Manual
SQL Functions

audit_start_timestamp
| 2014-02-04 14:52:15.126592-05
audit_end_timestamp
| 2014-02-04 14:52:15.139475-05
confidence_level_percent
| 99
error_tolerance_percent
| 5
used_sampling
| f
confidence_interval_lower_bound_bytes | 0
confidence_interval_upper_bound_bytes | 0
sample_count
| 0
cell_count
| 0
-[ RECORD 2 ]-------------------------+-----------------------------size_bytes
| 38051
user_id
| 45035996273704962
user_name
| release
object_id
| 45035996273704974
object_type
| DATABASE
object_schema
|
object_name
| dbs
audit_start_timestamp
| 2014-02-05 13:44:41.11926-05
audit_end_timestamp
| 2014-02-05 13:44:41.227035-05
confidence_level_percent
| 99
error_tolerance_percent
| 5
used_sampling
| f
confidence_interval_lower_bound_bytes | 38051
confidence_interval_upper_bound_bytes | 38051
sample_count
| 0
cell_count
| 0
-[ RECORD 3 ]-------------------------+-----------------------------.
.
.

AUDIT_LICENSE_SIZE
Triggers an immediate audit of the database size to determine if it is in compliance with the raw data
storage allowance included in your HP Vertica license. The audit is performed in the background, so
this function call returns immediately. To see the results of the audit when it is done, use the GET_
COMPLIANCE_STATUS function.

Syntax
AUDIT_LICENSE_SIZE()

Privileges
Must be a superuser.

Example
=> SELECT audit_license_size();

HP Vertica Analytic Database (7.0.x)

Page 574 of 1539

SQL Reference Manual
SQL Functions

audit_license_size
-------------------Service hurried
(1 row)

AUDIT_LICENSE_TERM
Triggers an immediate audit to determine if the HP Vertica license has expired. The audit happens
in the background, so this function returns immediately. To see the result of the audit, use the GET_
COMPLIANCE_STATUS function.

Syntax
AUDIT_LICENSE_TERM()

Privileges
Must be a superuser.

Example
=> SELECT AUDIT_LICENSE_TERM();
AUDIT_LICENSE_TERM
-------------------Service hurried
(1 row)

BUILD_FLEXTABLE_VIEW
Creates, or recreates, a view for a default or user-defined _keys table. If you do not specify a view_
name argument, the default name is the flex table name with a _view suffix. For example, if you
specify the table darkdata as the sole argument to this function, the default view is called
darkdata_view.
You cannot specify a custom view name with the same name as the default view flex_table_
view, unless you first do the following:
1. Drop the default-named view
2. Create your own view of the same name

Usage
build_flextable_view('flex_table' [ [,'view_name'] [,'user_keys_table'] ])

HP Vertica Analytic Database (7.0.x)

Page 575 of 1539

SQL Reference Manual
SQL Functions

Arguments
flex_table

The flex table name. By default, this function builds or
rebuilds a view for the input table with the current contents of
the associated flex_table_keys table.

view_name

[Optional] A custom view name. Use this option to build or
rebuild a new or existing view of your choice for the input
table with the current contents of the associated flex_
table_keys table, rather than the default view ( flex_
table_view).

user_keys_
table

[Optional] Specifies a keys table from which to create a view.
Use this option if you created a custom user_keys table for
keys of interest from the flex table map data, rather than the
default flex_table_keys table. The function builds a view
from the keys in user_keys table, rather than from the flex_
table_keys table.

Examples
Following are examples of calling build_flextable_view with 1, 2, or 3 arguments.

Creating a Default View
To create, or recreate, a default view:
1. Call the function with a single argument of a flex table, darkdata, in this example:
kdb=> select build_flextable_view('darkdata');
build_flextable_view
----------------------------------------------------The view public.darkdata_view is ready for querying
(1 row)

The function creates a view from the darkdata_keys table.
2. Query from the default view name (darkdata_view):
kdb=> select "user.id" from darkdata_view;
user.id
----------340857907
727774963
390498773
288187825

HP Vertica Analytic Database (7.0.x)

Page 576 of 1539

SQL Reference Manual
SQL Functions

164464905
125434448
601328899
352494946
(12 rows)

Creating a Custom Name View
To create, or recreate, a default view with a custom name:
1. Call the function with two arguments, a flex table, darkdata, and the name of the view to
create, dd_view, in this example:
kdb=> select build_flextable_view('darkdata', 'dd_view');
build_flextable_view
----------------------------------------------The view public.dd_view is ready for querying
(1 row)

2. Query from the custom view name (dd_view):
kdb=> select "user.lang" from dd_view;
user.lang
----------tr
en
es
en
en
it
es
en
(12 rows)

Creating a View From a Custom Keys Table
To create a view from a custom _keys table with build_flextable_view, the table must already
exist. The custom table must have the same schema and table definition as the default table
(darkdata_keys).
Following are a couple of ways to create a custom keys table:
1. Create a table with the all keys from the keys table:
kdb=> create table new_darkdata_keys as select * from darkdata_keys;

HP Vertica Analytic Database (7.0.x)

Page 577 of 1539

SQL Reference Manual
SQL Functions

CREATE TABLE

2. Alternatively, create a table based on the default keys table, but without content:
kdb=> create table new_darkdata_keys as select * from darkdata_keys LIMIT 0;
CREATE TABLE
kdb=> select * from new_darkdata_keys;
key_name | frequency | data_type_guess
----------+-----------+----------------(0 rows)

3. Given an existing table (or creating one with no data), insert one or more keys:
kdb=> create table dd_keys as select * from darkdata_keys limit 0;
CREATE TABLE
kdb=> insert into dd_keys (key_name) values ('user.lang');
OUTPUT
-------1
(1 row)
kdb=> insert into dd_keys (key_name) values ('user.name');
OUTPUT
-------1
(1 row)
kdb=> select * from dd_keys;
key_name | frequency | data_type_guess
-----------+-----------+----------------user.lang |
|
user.name |
|
(2 rows)

Continue once your custom keys table exists.
1. Call the function with all arguments, a flex table, the name of the view to create, and the
custom keys table:
kdb=> select build_flextable_view('darkdata', 'dd_view', 'new_darkdata_keys');
build_flextable_view
----------------------------------------------The view public.dd_view is ready for querying
(1 row)

2. Query the new view:
SELECT * from dd_view;

HP Vertica Analytic Database (7.0.x)

Page 578 of 1539

SQL Reference Manual
SQL Functions

See Also
l

COMPUTE_FLEXTABLE_KEYS

l

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

l

MATERIALIZE_FLEXTABLE_COLUMNS

l

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

CANCEL_REBALANCE_CLUSTER
Stops any rebalance task currently in progress.

Syntax
CANCEL_REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT CANCEL_REBALANCE_CLUSTER();
CANCEL_REBALANCE_CLUSTER
-------------------------CANCELED
(1 row)

See Also
l

START_REBALANCE_CLUSTER

l

REBALANCE_CLUSTER

CANCEL_REFRESH
Cancels refresh-related internal operations initiated by START_REFRESH().

Syntax
CANCEL_REFRESH()

HP Vertica Analytic Database (7.0.x)

Page 579 of 1539

SQL Reference Manual
SQL Functions

Privileges
None

Notes
l

Refresh tasks run in a background thread in an internal session, so you cannot use
INTERRUPT_STATEMENT to cancel those statements. Instead, use CANCEL_REFRESH to
cancel statements that are run by refresh-related internal sessions.

l

Run CANCEL_REFRESH() on the same node on which START_REFRESH() was initiated.

l

CANCEL_REFRESH() cancels the refresh operation running on a node, waits for the
cancelation to complete, and returns SUCCESS.

l

Only one set of refresh operations runs on a node at any time.

Example
Cancel a refresh operation executing in the background.
t=> SELECT START_REFRESH();
START_REFRESH
---------------------------------------Starting refresh background process.
(1 row)
=> SELECT CANCEL_REFRESH();
CANCEL_REFRESH
---------------------------------------Stopping background refresh process.
(1 row)

See Also
l

INTERRUPT_STATEMENT

l

SESSIONS

l

START_REFRESH

l

PROJECTION_REFRESHES

CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY
Changes the run-time priority of a query that is actively running.

HP Vertica Analytic Database (7.0.x)

Page 580 of 1539

SQL Reference Manual
SQL Functions

Syntax
CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY(TRANSACTION_ID, 'value')

Parameters
TRANSACTION_ID

An identifier for the transaction within the session.
TRANSACTION_ID cannot be NULL.
You can find the transaction ID in the Sessions table.

'value'

The RUNTIMEPRIORITY value. Can be HIGH, MEDIUM, or LOW.

Privileges
No special privileges required. However, non-super users can change the run-time priority of their
own queries only. In addition, non-superusers can never raise the run-time priority of a query to a
level higher than that of the resource pool.

Example
=> SELECT CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY(45035996273705748, 'low');

CHANGE_RUNTIME_PRIORITY
Changes the run-time priority of a query that is actively running. Note that, while this function is still
valid, you should instead use CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY to change run-time
priority. CHANGE_RUNTIME_PRIORITY will be deprecated in a future release of Vertica.

Syntax
CHANGE_RUNTIME_PRIORITY(TRANSACTION_ID,STATEMENT_ID, 'value')

Parameters
TRANSACTION_ID

An identifier for the transaction within the session.
TRANSACTION_ID cannot be NULL.
You can find the transaction ID in the Sessions table.

HP Vertica Analytic Database (7.0.x)

Page 581 of 1539

SQL Reference Manual
SQL Functions

STATEMENT_ID

A unique numeric ID assigned by the HP Vertica catalog, which identifies the
currently executing statement.
You can find the statement ID in the Sessions table.
You can specify NULL to change the run-time priority of the currently running
query within the transaction.

'value'

The RUNTIMEPRIORITY value. Can be HIGH, MEDIUM, or LOW.

Privileges
No special privileges required. However, non-super users can change the run-time priority of their
own queries only. In addition, non-superusers can never raise the run-time priority of a query to a
level higher than that of the resource pool.

Example
=> SELECT CHANGE_RUNTIME_PRIORITY(45035996273705748, NULL, 'low');

CLEAR_CACHES
Clears the HP Vertica internal cache files.

Syntax
CLEAR_CACHES ( )

Privileges
Must be a superuser.

Notes
If you want to run benchmark tests for your queries, in addition to clearing the internal HP Vertica
cache files, clear the Linux file system cache. The kernel uses unallocated memory as a cache to
hold clean disk blocks. If you are running version 2.6.16 or later of Linux and you have root access,
you can clear the kernel filesystem cache as follows:
1. Make sure that all data is the cache is written to disk:
# sync

HP Vertica Analytic Database (7.0.x)

Page 582 of 1539

SQL Reference Manual
SQL Functions

2. Writing to the drop_caches file causes the kernel to drop clean caches, dentries, and inodes
from memory, causing that memory to become free, as follows:
n

To clear the page cache:
# echo 1 > /proc/sys/vm/drop_caches

n

To clear the dentries and inodes:
# echo 2 > /proc/sys/vm/drop_caches

n

To clear the page cache, dentries, and inodes:
# echo 3 > /proc/sys/vm/drop_caches

Example
The following example clears the HP Vertica internal cache files:
=> CLEAR_CACHES();
CLEAR_CACHES
-------------Cleared
(1 row)

CLEAR_DATA_COLLECTOR
Clears all memory and disk records on the Data Collector tables and functions and resets collection
statistics in the V_MONITOR.DATA_COLLECTOR system table. A superuser can clear Data
Collector data for all components or specify an individual component
After you clear the Data Collector log, the information is no longer available for querying.

Syntax
CLEAR_DATA_COLLECTOR( [ 'component' ] )

HP Vertica Analytic Database (7.0.x)

Page 583 of 1539

SQL Reference Manual
SQL Functions

Parameters
component

Clears memory and disk records for the specified component only. If you provide no
argument, the function clears all Data Collector memory and disk records for all
components.
For the current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table.

Privileges
Must be a superuser.

Examples
The following command clears memory and disk records for the ResourceAcquisitions component:
=> SELECT clear_data_collector('ResourceAcquisitions');
clear_data_collector
---------------------CLEAR
(1 row)

The following command clears data collection for all components on all nodes:
=> SELECT clear_data_collector();
clear_data_collector
---------------------CLEAR
(1 row)

See Also
DATA_COLLECTOR

l
l

CLEAR_PROFILING
HP Vertica stores profiled data is in memory, so depending on how much data you collect, profiling
could be memory intensive. You can use this function to clear profiled data from memory.

Syntax
CLEAR_PROFILING( 'profiling-type' )

HP Vertica Analytic Database (7.0.x)

Page 584 of 1539

SQL Reference Manual
SQL Functions

Parameters
profiling-type

The type of profiling data you want to clear. Can be one of:
l

session—clears profiling for basic session parameters and lock time out
data

l

query—clears profiling for general information about queries that ran, such as
the query strings used and the duration of queries

l

ee—clears profiling for information about the execution run of each query

Example
The following statement clears profiled data for queries:
=> SELECT CLEAR_PROFILING('query');

See Also
l

DISABLE_PROFILING

l

ENABLE_PROFILING

l

Profiling Database Performance

CLEAR_PROJECTION_REFRESHES
Triggers HP Vertica to clear information about refresh operations for projections immediately.

Syntax
CLEAR_PROJECTION_REFRESHES()

Notes
Information about a refresh operation—whether successful or unsuccessful—is maintained in the
PROJECTION_REFRESHES system table until either the CLEAR_PROJECTION_
REFRESHES() function is executed or the storage quota for the table is exceeded. The
PROJECTION_REFRESHES.IS_EXECUTING column returns a boolean value that indicates whether the
refresh is currently running (t) or occurred in the past (f).

HP Vertica Analytic Database (7.0.x)

Page 585 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Example
To immediately purge projection refresh history, use the CLEAR_PROJECTION_REFRESHES()
function:
=> SELECT CLEAR_PROJECTION_REFRESHES();
CLEAR_PROJECTION_REFRESHES
---------------------------CLEAR
(1 row)

Only the rows where the PROJECTION_REFRESHES.IS_EXECUTING column equals false are cleared.

See Also
l

PROJECTION_REFRESHES

l

REFRESH
START_REFRESH

l
l

CLEAR_RESOURCE_REJECTIONS
Clears the content of the RESOURCE_REJECTIONS and DISK_RESOURCE_REJECTIONS
system tables. Normally, these tables are only cleared during a node restart. This function lets you
clear the tables whenever you need. For example, you might want to clear the system tables after
you resolved a disk space issue that was causing disk resource rejections.

Syntax
CLEAR_RESOURCE_REJECTIONS();

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 586 of 1539

SQL Reference Manual
SQL Functions

Example
The following command clears the content of the RESOURCE_REJECTIONS and DISK_
RESOURCE_REJECTIONS system tables:
=> SELECT clear_resource_rejections();
clear_resource_rejections
--------------------------OK
(1 row)

See Also
l

DISK_RESOURCE_REJECTIONS

l

RESOURCE_REJECTIONS

CLEAR_OBJECT_STORAGE_POLICY
Removes an existing storage policy. The specified object will no longer use a default storage
location. Any existing data stored currently at the labeled location in the object's storage policy is
moved to default storage during the next TM moveout operation.

Syntax
CLEAR_OBJECT_STORAGE_POLICY ( 'object_name' , [', key_min, key_max '])

Parameters
object_name

Specifies the database object with a storage policy to clear.

key_min, key_max

Specifies the table partition key value ranges stored at the labeled location.
These parameters are applicable only when object_name is a table.

Privileges
Must be a superuser.

Example
This example clears the storage policy for the object lineorder:
release=> select clear_object_storage_policy('lineorder');

HP Vertica Analytic Database (7.0.x)

Page 587 of 1539

SQL Reference Manual
SQL Functions

clear_object_storage_policy
----------------------------------Default storage policy cleared.
(1 row)

See Also
l

Clearing Storage Policies

l

ALTER_LOCATION_LABEL

l

SET_OBJECT_STORAGE_POLICY

CLOSE_SESSION
Interrupts the specified external session, rolls back the current transaction, if any, and closes the
socket.

Syntax
CLOSE_SESSION ( 'sessionid' )

Parameters
sessionid

A string that specifies the session to close. This identifier is unique within the cluster
at any point in time but can be reused when the session closes.

Privileges
None; however, a non-superuser can only close his or her own session.

Notes
l

Closing of the session is processed asynchronously. It could take some time for the session to
be closed. Check the SESSIONS table for the status.

l

Database shutdown is prevented if new sessions connect after the CLOSE_SESSION()
command is invoked (and before the database is actually shut down. See Controlling
Sessions below.

Messages
The following are the messages you could encounter:

HP Vertica Analytic Database (7.0.x)

Page 588 of 1539

SQL Reference Manual
SQL Functions

l

For a badly formatted sessionID
close_session | Session close command sent. Check SESSIONS for progress.Error: invalid
Session ID format

l

For an incorrect sessionID parameter
Error: Invalid session ID or statement key

Examples
User session opened. RECORD 2 shows the user session running COPY DIRECT statement.
=> SELECT * FROM sessions;
-[ RECORD 1 ]--------------+----------------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin
client_hostname
| 127.0.0.1:52110
client_pid
| 4554
login_timestamp
| 2011-01-03 14:05:40.252625-05
session_id
| stress04-4325:0x14
client_label
|
transaction_start
| 2011-01-03 14:05:44.325781
transaction_id
| 45035996273728326
transaction_description
| user dbadmin (SELECT * FROM sessions;)
statement_start
| 2011-01-03 15:36:13.896288
statement_id
| 10
last_statement_duration_us | 14978
current_statement
| select * from sessions;
ssl_state
| None
authentication_method
| Trust
-[ RECORD 2 ]--------------+----------------------------------------------node_name
| v_vmartdb_node0002
user_name
| dbadmin
client_hostname
| 127.0.0.1:57174
client_pid
| 30117
login_timestamp
| 2011-01-03 15:33:00.842021-05
session_id
| stress05-27944:0xc1a
client_label
|
transaction_start
| 2011-01-03 15:34:46.538102
transaction_id
| -1
transaction_description
| user dbadmin (COPY ClickStream_Fact FROM
'/data/clickstream/1g/ClickStream_Fact.tbl'
DELIMITER '|' NULL '\\n' DIRECT;)
statement_start
| 2011-01-03 15:34:46.538862
statement_id
|
last_statement_duration_us | 26250
current_statement
| COPY ClickStream_Fact FROM '/data/clickstream
/1g/ClickStream_Fact.tbl' DELIMITER '|' NULL
'\\n' DIRECT;
ssl_state
| None

HP Vertica Analytic Database (7.0.x)

Page 589 of 1539

SQL Reference Manual
SQL Functions

authentication_method

| Trust

Close user session stress05-27944:0xc1a
=> \xExpanded display is off.
=> SELECT CLOSE_SESSION('stress05-27944:0xc1a');
CLOSE_SESSION
-------------------------------------------------------------------Session close command sent. Check v_monitor.sessions for progress.
(1 row)

Query the sessions table again for current status, and you can see that the second session has
been closed:
=> SELECT * FROM SESSIONS;
-[ RECORD 1 ]--------------+-------------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin
client_hostname
| 127.0.0.1:52110
client_pid
| 4554
login_timestamp
| 2011-01-03 14:05:40.252625-05
session_id
| stress04-4325:0x14
client_label
|
transaction_start
| 2011-01-03 14:05:44.325781
transaction_id
| 45035996273728326
transaction_description
| user dbadmin (select * from SESSIONS;)
statement_start
| 2011-01-03 16:12:07.841298
statement_id
| 20
last_statement_duration_us | 2099
current_statement
| SELECT * FROM SESSIONS;
ssl_state
| None
authentication_method
| Trust

Controlling Sessions
The database administrator must be able to disallow new incoming connections in order to shut
down the database. On a busy system, database shutdown is prevented if new sessions connect
after the CLOSE_SESSION or CLOSE_ALL_SESSIONS() command is invoked—and before the
database actually shuts down.
One option is for the administrator to issue the SHUTDOWN('true') command, which forces the
database to shut down and disallow new connections. See SHUTDOWN in the SQL Reference
Manual.
Another option is to modify the MaxClientSessions parameter from its original value to 0, in order
to prevent new non-dbadmin users from connecting to the database.
1. Determine the original value for the MaxClientSessions parameter by querying the V_
MONITOR.CONFIGURATIONS_PARAMETERS system table:

HP Vertica Analytic Database (7.0.x)

Page 590 of 1539

SQL Reference Manual
SQL Functions

=> SELECT CURRENT_VALUE FROM CONFIGURATION_PARAMETERS WHERE parameter_name='MaxClient
Sessions';
CURRENT_VALUE
--------------50
(1 row)

2. Set the MaxClientSessions parameter to 0 to prevent new non-dbadmin connections:
=> SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 0);

Note: The previous command allows up to five administrators to log in.
3. Issue the CLOSE_ALL_SESSIONS() command to remove existing sessions:
=> SELECT CLOSE_ALL_SESSIONS();

4. Query the SESSIONS table:
=> SELECT * FROM SESSIONS;

When the session no longer appears in the SESSIONS table, disconnect and run the Stop
Database command.
5. Restart the database.
6. Restore the MaxClientSessions parameter to its original value:
=> SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 50);

See Also
l

CLOSE_ALL_SESSIONS

l

CONFIGURATION_PARAMETERS

l

SESSIONS
SHUTDOWN

l
l

l

HP Vertica Analytic Database (7.0.x)

Page 591 of 1539

SQL Reference Manual
SQL Functions

CLOSE_ALL_SESSIONS
Closes all external sessions except the one issuing the CLOSE_ALL_SESSIONS functions.

Syntax
CLOSE_ALL_SESSIONS()

Privileges
None; however, a non-superuser can only close his or her own session.

Notes
Closing of the sessions is processed asynchronously. It might take some time for the session to be
closed. Check the SESSIONS table for the status.
Database shutdown is prevented if new sessions connect after the CLOSE_SESSION or CLOSE_
ALL_SESSIONS() command is invoked (and before the database is actually shut down). See
Controlling Sessions below.

Message
close_all_sessions | Close all sessions command sent. Check SESSIONS for progress.

Examples
Two user sessions opened, each on a different node:
vmartdb=> SELECT * FROM sessions;
-[ RECORD 1 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin
client_hostname
| 127.0.0.1:52110
client_pid
| 4554
login_timestamp
| 2011-01-03 14:05:40.252625-05
session_id
| stress04-4325:0x14
client_label
|
transaction_start
| 2011-01-03 14:05:44.325781
transaction_id
| 45035996273728326
transaction_description
| user dbadmin (select * from sessions;)
statement_start
| 2011-01-03 15:36:13.896288
statement_id
| 10
last_statement_duration_us | 14978
current_statement
| select * from sessions;
ssl_state
| None
authentication_method
| Trust

HP Vertica Analytic Database (7.0.x)

Page 592 of 1539

SQL Reference Manual
SQL Functions

-[ RECORD 2 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0002
user_name
| dbadmin
client_hostname
| 127.0.0.1:57174
client_pid
| 30117
login_timestamp
| 2011-01-03 15:33:00.842021-05
session_id
| stress05-27944:0xc1a
client_label
|
transaction_start
| 2011-01-03 15:34:46.538102
transaction_id
| -1
transaction_description
| user dbadmin (COPY Mart_Fact FROM '/data/mart_Fact.tbl'
DELIMITER '|' NULL '\\n';)
statement_start
| 2011-01-03 15:34:46.538862
statement_id
|
last_statement_duration_us | 26250
current_statement
| COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|'
NULL '\\n';
ssl_state
| None
authentication_method
| Trust
-[ RECORD 3 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0003
user_name
| dbadmin
client_hostname
| 127.0.0.1:56367
client_pid
| 1191
login_timestamp
| 2011-01-03 15:31:44.939302-05
session_id
| stress06-25663:0xbec
client_label
|
transaction_start
| 2011-01-03 15:34:51.05939
transaction_id
| 54043195528458775
transaction_description
| user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl'
DELIMITER '|' NULL '\\n' DIRECT;)
statement_start
| 2011-01-03 15:35:46.436748
statement_id
|
last_statement_duration_us | 1591403
current_statement
| COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|'
NULL '\\n' DIRECT;
ssl_state
| None
authentication_method
| Trust

Close all sessions:
vmartdb=> \xExpanded display is off.
vmartdb=> SELECT CLOSE_ALL_SESSIONS();
CLOSE_ALL_SESSIONS
------------------------------------------------------------------------Close all sessions command sent. Check v_monitor.sessions for progress.
(1 row)

Session contents after issuing the CLOSE_ALL_SESSIONS() command:
=> SELECT * FROM SESSIONS;-[ RECORD 1 ]--------------+--------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin
client_hostname
| 127.0.0.1:52110

HP Vertica Analytic Database (7.0.x)

Page 593 of 1539

SQL Reference Manual
SQL Functions

client_pid
login_timestamp
session_id
client_label
transaction_start
transaction_id
transaction_description
statement_start
statement_id
last_statement_duration_us
current_statement
ssl_state
authentication_method

|
|
|
|
|
|
|
|
|
|
|
|
|

4554
2011-01-03 14:05:40.252625-05
stress04-4325:0x14
2011-01-03 14:05:44.325781
45035996273728326
user dbadmin (SELECT * FROM sessions;)
2011-01-03 16:19:56.720071
25
15605
SELECT * FROM SESSIONS;
None
Trust

Controlling Sessions
The database administrator must be able to disallow new incoming connections in order to shut
down the database. On a busy system, database shutdown is prevented if new sessions connect
after the CLOSE_SESSION or CLOSE_ALL_SESSIONS() command is invoked—and before the
database actually shuts down.
One option is for the administrator to issue the SHUTDOWN('true') command, which forces the
database to shut down and disallow new connections. See SHUTDOWN in the SQL Reference
Manual.
Another option is to modify the MaxClientSessions parameter from its original value to 0, in order
to prevent new non-dbadmin users from connecting to the database.
1. Determine the original value for the MaxClientSessions parameter by querying the V_
MONITOR.CONFIGURATIONS_PARAMETERS system table:
=> SELECT CURRENT_VALUE FROM CONFIGURATION_PARAMETERS WHERE parameter_name='MaxClient
Sessions';
CURRENT_VALUE
--------------50
(1 row)

2. Set the MaxClientSessions parameter to 0 to prevent new non-dbadmin connections:
=> SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 0);

Note: The previous command allows up to five administrators to log in.
3. Issue the CLOSE_ALL_SESSIONS() command to remove existing sessions:

HP Vertica Analytic Database (7.0.x)

Page 594 of 1539

SQL Reference Manual
SQL Functions

=> SELECT CLOSE_ALL_SESSIONS();

4. Query the SESSIONS table:
=> SELECT * FROM SESSIONS;

When the session no longer appears in the SESSIONS table, disconnect and run the Stop
Database command.
5. Restart the database.
6. Restore the MaxClientSessions parameter to its original value:
=> SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 50);

See Also
l

CLOSE_SESSION

l

CONFIGURATION_PARAMETERS

l

SHUTDOWN
SESSIONS

l
l

l

COMPUTE_FLEXTABLE_KEYS
Computes the virtual columns (keys and values) from the map data of a flex table and repopulates
the associated _keys table. The keys table has the following columns:
l

key_name

l

frequency

l

data_type_guess

This function sorts the keys table by frequency and key_name.
Use this function to compute keys without creating an associated table view. To build a view as
well, use COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW.

HP Vertica Analytic Database (7.0.x)

Page 595 of 1539

SQL Reference Manual
SQL Functions

Usage
compute_flextable_keys('flex_table')

Arguments
flex_table The name of the flex table.

Examples
During execution, this function determines a data type for each virtual column, casting the values it
computes to VARCHAR, LONG VARCHAR, or LONG VARBINARY, depending on the length of the key, and
whether the key includes nested maps.
The following examples illustrate this function and the results of populating the _keys table, once
you've created a flex table (darkdata1) and loaded data:
kdb=> create flex table darkdata1();
CREATE TABLE
kdb=> copy darkdata1 from '/test/flextable/DATA/tweets_12.json' parser fjsonparser();
Rows Loaded
------------12
(1 row)
kdb=> select compute_flextable_keys('darkdata1');
compute_flextable_keys
-------------------------------------------------Please see public.darkdata1_keys for updated keys
(1 row)
kdb=> select * from darkdata1_keys;
key_name
| frequency |
data_type_guess
----------------------------------------------------------+-----------+--------------------contributors
|
8 | varchar(20)
coordinates
|
8 | varchar(20)
created_at
|
8 | varchar(60)
entities.hashtags
|
8 | long varbinary(18
6)
entities.urls
|
8 | long varbinary(3
2)
entities.user_mentions
|
8 | long varbinary(67
4)
.
.
.
retweeted_status.user.time_zone
|
1 | varchar(20)
retweeted_status.user.url
|
1 | varchar(68)
retweeted_status.user.utc_offset
|
1 | varchar(20)
retweeted_status.user.verified
|
1 | varchar(20)
(125 rows)

The flex keys table has these columns:

HP Vertica Analytic Database (7.0.x)

Page 596 of 1539

SQL Reference Manual
SQL Functions

Column

Description

key_name

The name of the virtual column (key).

frequency The number of times the virtual column occurs in the map.
data_
type_
guess

The data type for each virtual column, cast to VARCHAR, LONG VARCHAR or LONG
VARBINARY, depending on the length of the key, and whether the key includes one or
more nested maps.
In the _keys table output, the data_type_guess column values are also followed by
a value in parentheses, such as varchar(20). The value indicates the padded
width of the key column, as calculated by the longest field, multiplied by the
FlexTableDataTypeGuessMultiplier configuration parameter value. For more
information, see Setting Flex Table Parameters.

See Also
l

BUILD_FLEXTABLE_VIEW

l

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

l

MATERIALIZE_FLEXTABLE_COLUMNS

l

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW
Combines the functionality of BUILD_FLEXTABLE_VIEW and COMPUTE_FLEXTABLE_KEYS
to compute virtual columns (keys) from the map data of a flex table , and construct a view. If you
don't need to perform both operations together, use one of the single-operation functions.

Usage
compute_flextable_keys_and_build_view('flex_table')

Arguments
flex_table The name of a flex table.

Examples
The following example calls the function for the darkdata flex table.
kdb=> select compute_flextable_keys_and_build_view('darkdata');

HP Vertica Analytic Database (7.0.x)

Page 597 of 1539

SQL Reference Manual
SQL Functions

compute_flextable_keys_and_build_view
----------------------------------------------------------------------Please see public.darkdata_keys for updated keys
The view public.darkdata_view is ready for querying
(1 row)

See Also
l

BUILD_FLEXTABLE_VIEW

l

COMPUTE_FLEXTABLE_KEYS

l

MATERIALIZE_FLEXTABLE_COLUMNS

l

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

CURRENT_SCHEMA
Returns the name of the current schema.

Behavior Type
Stable

Syntax
CURRENT_SCHEMA()

Privileges
None

Notes
The CURRENT_SCHEMA function does not require parentheses.

Examples
The following command returns the name of the current schema:
=> SELECT CURRENT_SCHEMA();
current_schema
---------------public

HP Vertica Analytic Database (7.0.x)

Page 598 of 1539

SQL Reference Manual
SQL Functions

(1 row)

The following command returns the same results without the parentheses:
=> SELECT CURRENT_SCHEMA;
current_schema
---------------public
(1 row)

The following command shows the current schema, listed after the current user, in the search path:
=> SHOW SEARCH_PATH;
name
|
setting
-------------+--------------------------------------------------search_path | "$user", public, v_catalog, v_monitor, v_internal
(1 row)

See Also
l

SET SEARCH_PATH

DATA_COLLECTOR_HELP
Returns online usage instructions about the Data Collector, the DATA_COLLECTOR system table, and
the Data Collector control functions.

Syntax
DATA_COLLECTOR_HELP()

Privileges
None

Returns
The DATA_COLLECTOR_HELP() function returns the following information:
=> SELECT DATA_COLLECTOR_HELP();
----------------------------------------------------------------------------Usage Data Collector
The data collector retains history of important system activities.
This data can be used as a reference of what actions have been taken

HP Vertica Analytic Database (7.0.x)

Page 599 of 1539

SQL Reference Manual
SQL Functions

by users, but it can also be used to locate performance bottlenecks,
or identify potential improvements to the Vertica configuration.
This data is queryable via Vertica system tables.
Acccess a list of data collector components, and some statistics, by running:
SELECT * FROM v_monitor.data_collector;
The amount of data retained by size and time can be controlled with several
functions.
To just set the size amount:
set_data_collector_policy(,
,
);
To set both the size and time amounts (the smaller one will dominate):
set_data_collector_policy(,
,
,
);
To set just the time amount:
set_data_collector_time_policy(,
);
To set the time amount for all tables:
set_data_collector_time_policy();
The current retention policy for a component can be queried with:
get_data_collector_policy();
Data on disk is kept in the "DataCollector" directory under the Vertica
\catalog path. This directory also contains instructions on how to load
the monitoring data into another Vertica database.
To move the data collector logs and instructions to other storage locations,
create labeled storage locations using add_location and then use:
set_data_collector_storage_location();
Additional commands can be used to configure the data collection logs.
The log can be cleared with:
clear_data_collector([]);
The log can be synchronized with the disk storage using:
flush_data_collector([]);

See Also
l

DATA_COLLECTOR

l

TUNING_RECOMMENDATIONS

HP Vertica Analytic Database (7.0.x)

Page 600 of 1539

SQL Reference Manual
SQL Functions

l

Analyzing Workloads

l

Retaining Monitoring Information

DISABLE_DUPLICATE_KEY_ERROR
Disables error messaging when HP Vertica finds duplicate PRIMARY KEY/UNIQUE KEY values
at run time. Queries execute as though no constraints are defined on the schema. Effects are
session scoped.
Caution: When called, DISABLE_DUPLICATE_KEY_ERROR() suppresses data integrity
checking and can lead to incorrect query results. Use this function only after you insert
duplicate primary keys into a dimension table in the presence of a pre-join projection. Then
correct the violations and turn integrity checking back on with REENABLE_DUPLICATE_
KEY_ERROR().

Syntax
DISABLE_DUPLICATE_KEY_ERROR();

Privileges
Must be a superuser.

Examples
The following series of commands create a table named dim and the corresponding projection:
CREATE TABLE dim (pk INTEGER PRIMARY KEY, x INTEGER);
CREATE PROJECTION dim_p (pk, x) AS SELECT * FROM dim ORDER BY x UNSEGMENTED ALL NODES;

The next two statements create a table named fact and the pre-join projection that joins fact to
dim.
CREATE TABLE fact(fk INTEGER REFERENCES dim(pk));
CREATE PROJECTION prejoin_p (fk, pk, x) AS SELECT * FROM fact, dim WHERE pk=fk ORDER BY x
;

The following statements load values into table dim. The last statement inserts a duplicate primary
key value of 1:
INSERT INTO dim values (1,1);INSERT INTO dim values (2,2);
INSERT INTO dim values (1,2); --Constraint violation
COMMIT;

HP Vertica Analytic Database (7.0.x)

Page 601 of 1539

SQL Reference Manual
SQL Functions

Table dim now contains duplicate primary key values, but you cannot delete the violating row
because of the presence of the pre-join projection. Any attempt to delete the record results in the
following error message:
ROLLBACK: Duplicate primary key detected in FK-PK join Hash-Join (x dim_p), value 1

In order to remove the constraint violation (pk=1), use the following sequence of commands, which
puts the database back into the state just before the duplicate primary key was added.
To remove the violation:
1. Save the original dim rows that match the duplicated primary key:
CREATE TEMP TABLE dim_temp(pk integer, x integer);
INSERT INTO dim_temp SELECT * FROM dim WHERE pk=1 AND x=1; -- original dim row

2. Temporarily disable error messaging on duplicate constraint values:
SELECT DISABLE_DUPLICATE_KEY_ERROR();

Caution: Remember that running the DISABLE_DUPLICATE_KEY_ERROR function
suppresses the enforcement of data integrity checking.
3. Remove the original row that contains duplicate values:
DELETE FROM dim WHERE pk=1;

4. Allow the database to resume data integrity checking:
SELECT REENABLE_DUPLICATE_KEY_ERROR();

5. Reinsert the original values back into the dimension table:
INSERT INTO dim SELECT * from dim_temp;COMMIT;

6. Validate your dimension and fact tables.
If you receive the following error message, it means that the duplicate records you want to
delete are not identical. That is, the records contain values that differ in at least one column
that is not a primary key; for example, (1,1) and (1,2).
ROLLBACK: Delete: could not find a data row to delete (data integrity violation?)

HP Vertica Analytic Database (7.0.x)

Page 602 of 1539

SQL Reference Manual
SQL Functions

The difference between this message and the rollback message in the previous example is that
a fact row contains a foreign key that matches the duplicated primary key, which has been
inserted. A row with values from the fact and dimension table is now in the pre-join projection.
In order for the DELETE statement (Step 3 in the following example) to complete successfully,
extra predicates are required to identify the original dimension table values (the values that are
in the pre-join).
This example is nearly identical to the previous example, except that an additional INSERT
statement joins the fact table to the dimension table by a primary key value of 1:
INSERT INTO dim values (1,1);INSERT INTO dim values (2,2);
INSERT INTO fact values (1);
-- New insert statement joins fact with dim on primar
y key value=1
INSERT INTO dim values (1,2); -- Duplicate primary key value=1
COMMIT;

To remove the violation:
1. Save the original dim and fact rows that match the duplicated primary key:
CREATE TEMP TABLE dim_temp(pk integer, x integer);CREATE TEMP TABLE fact_temp(fk inte
ger);
INSERT INTO dim_temp SELECT * FROM dim WHERE pk=1 AND x=1; -- original dim row
INSERT INTO fact_temp SELECT * FROM fact WHERE fk=1;

2. Temporarily suppresses the enforcement of data integrity checking:
SELECT DISABLE_DUPLICATE_KEY_ERROR();

3. Remove the duplicate primary keys. These steps also implicitly remove all fact rows with the
matching foreign key.
4. Remove the original row that contains duplicate values:
DELETE FROM dim WHERE pk=1 AND x=1;

Note: The extra predicate (x=1) specifies removal of the original (1,1) row, rather than the
newly inserted (1,2) values that caused the violation.
5. Remove all remaining rows:
DELETE FROM dim WHERE pk=1;

HP Vertica Analytic Database (7.0.x)

Page 603 of 1539

SQL Reference Manual
SQL Functions

6. Reenable integrity checking:
SELECT REENABLE_DUPLICATE_KEY_ERROR();

7. Reinsert the original values back into the fact and dimension table:
INSERT INTO dim SELECT * from dim_temp;
INSERT INTO fact SELECT * from fact_temp;
COMMIT;

8. Validate your dimension and fact tables.

See Also
l

ANALYZE_CONSTRAINTS

l

REENABLE_DUPLICATE_KEY_ERROR

DISABLE_ELASTIC_CLUSTER
Disables elastic cluster scaling, which prevents HP Vertica from bundling data into chunks that are
easily transportable to other nodes when performing cluster resizing. The main reason to disable
elastic clustering is if you find that the slightly unequal data distribution in your cluster caused by
grouping data into discrete blocks results in performance issues.

Syntax
DISABLE_ELASTIC_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT DISABLE_ELASTIC_CLUSTER();
DISABLE_ELASTIC_CLUSTER
------------------------DISABLED
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 604 of 1539

SQL Reference Manual
SQL Functions

See Also
l

ENABLE_ELASTIC_CLUSTER

DISABLE_LOCAL_SEGMENTS
Disable local data segmentation, which breaks projections segments on nodes into containers that
can be easily moved to other nodes. See Local Data Segmentation in the Administrator's Guide for
details.

Syntax
DISABLE_LOCAL_SEGMENTS()

Privileges
Must be a superuser.

Example
=> SELECT DISABLE_LOCAL_SEGMENTS();
DISABLE_LOCAL_SEGMENTS
-----------------------DISABLED
(1 row)

DISABLE_PROFILING
Disables profiling for the profiling type you specify.

Syntax
DISABLE_PROFILING( 'profiling-type' )

HP Vertica Analytic Database (7.0.x)

Page 605 of 1539

SQL Reference Manual
SQL Functions

Parameters
profiling-type

The type of profiling data you want to disable. Can be one of:
l

session—disables profiling for basic session parameters and lock time out
data

l

query—disables profiling for general information about queries that ran, such
as the query strings used and the duration of queries

l

ee—disables profiling for information about the execution run of each query

Example
The following statement disables profiling on query execution runs:
=> SELECT DISABLE_PROFILING('ee');
DISABLE_PROFILING
----------------------EE Profiling Disabled
(1 row)

See Also
l

CLEAR_PROFILING

l

ENABLE_PROFILING

l

Profiling Database Performance

DISPLAY_LICENSE
Returns the terms of your HP Vertica license. The information this function displays is:
l

The start and end dates for which the license is valid (or "Perpetual" if the license has no
expiration).

l

The number of days you are allowed to use HP Vertica after your license term expires (the grace
period)

l

The amount of data your database can store, if your license includes a data allowance.

Syntax
DISPLAY_LICENSE()

HP Vertica Analytic Database (7.0.x)

Page 606 of 1539

SQL Reference Manual
SQL Functions

Privileges
None

Examples
=> SELECT DISPLAY_LICENSE();
DISPLAY_LICENSE
---------------------------------------------------HP Vertica Systems, Inc.
1/1/2011
12/31/2011
30
50TB
(1 row)

DO_TM_TASK
Runs a Tuple Mover operation on one or more projections defined on the specified table.
Tip: You do not need to stop the Tuple Mover to run this function.

Syntax
DO_TM_TASK ( 'task' [ , '[[db-name.]schema.]table' |
'[[db-name.]schema.]projection' ] )

Parameters
task

Is one of the following tuple mover operations:
l

'moveout' — Moves out all projections on the specified table (if a
particular projection is not specified) from WOS to ROS.

l

'mergeout' — Consolidates ROS containers and purges deleted
records.

l

'analyze_row_count' — Automatically collects the number of rows
in a projection every 60 seconds and aggregates row counts calculated
during loads.

HP Vertica Analytic Database (7.0.x)

Page 607 of 1539

SQL Reference Manual
SQL Functions

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

table

Runs a tuple mover operation for all projections within the specified table.
When using more than one schema, specify the schema that contains the
table with the projections you want to affect, as noted above.

projection

If projection is not passed as an argument, all projections in the system are
used. If projection is specified, DO_TM_TASK looks for a projection of
that name and, if found, uses it; if a named projection is not found, the
function looks for a table with that name and, if found, moves out all
projections on that table.

Privileges
l

Any INSERT/UPDATE/DELETE privilege on table

l

USAGE privileges on schema

Notes
DO_TM_TASK() is useful for moving out all projections from a table or database without having to
name each projection individually.

Examples
The following example performs a moveout of all projections for table t1:
=> SELECT DO_TM_TASK('moveout', 't1');

The following example performs a moveout for projection t1_proj:
=> SELECT DO_TM_TASK('moveout', 't1_proj')

HP Vertica Analytic Database (7.0.x)

Page 608 of 1539

SQL Reference Manual
SQL Functions

See Also
l

COLUMN_STORAGE

l

DROP_PARTITION

l

DUMP_PARTITION_KEYS

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS
PARTITION_PROJECTION

l
l

l

DROP_LICENSE
Drops a Flex Zone license key from the global catalog.

Syntax
DROP_LICENSE( 'license name' )

Parameters
license name

The name of the license to drop. The name can be found in the licenses table.

Privileges
Must be a superuser.

Notes
For more information about license keys, see Managing Licenses in the Administrator's Guide.

Examples
=> SELECT DROP_LICENSE('/tmp/vlicense.dat');

HP Vertica Analytic Database (7.0.x)

Page 609 of 1539

SQL Reference Manual
SQL Functions

DROP_LOCATION
Removes the specified storage location.

Syntax
DROP_LOCATION ( 'path' , 'node' )

Parameters
path

Specifies where the storage location to drop is mounted.

node

Is the HP Vertica node where the location is available.

Privileges
Must be a superuser.

Retiring or Dropping a Storage Location
Dropping a storage location is a permanent operation and cannot be undone. Therefore, HP
recommends that you retire a storage location before dropping it. Retiring a storage location lets you
verify that you do not need the storage before dropping it. Additionally, you can easily restore a
retired storage location if you determine it is still in use.

Storage Locations with Temp and Data Files
Dropping storage locations is limited to storage locations that contain only temp files.
If you use a storage location to store data and then alter it to store only temp files, the location can
still contain data files. HP Vertica does not let you drop a storage location containing data files. You
can manually merge out the data files from the storage location, and then wait for the ATM to
mergeout the data files automatically, or, you can drop partitions. Deleting data files does not work.

Example
The following example drops a storage location on node3 that was used to store temp files:
=> SELECT DROP_LOCATION('/secondHP VerticaStorageLocation/' , 'node3');

HP Vertica Analytic Database (7.0.x)

Page 610 of 1539

SQL Reference Manual
SQL Functions

See Also
l

l

l

ADD_LOCATION

l

ALTER_LOCATION_USE

l

RESTORE_LOCATION

l

RETIRE_LOCATION

l

GRANT (Storage Location)

l

REVOKE (Storage Location)

DROP_PARTITION
Forces the partition of projections (if needed) and then drops the specified partition.

Syntax
DROP_PARTITION ( table_name , partition_value [ , ignore_moveout_errors, reorganize_data ])

Parameters
table-name

Specifies the name of the table.
Note: The table_name argument cannot be used as a dimension table in
a pre-joined projection and cannot contain projections that are not up to
date (have not been refreshed).

partition_value

The key of the partition to drop. For example: DROP_PARTITION
('trade', 2006);

HP Vertica Analytic Database (7.0.x)

Page 611 of 1539

SQL Reference Manual
SQL Functions

ignore_moveout_errors

Optional Boolean, defaults to false.
l

true—Ignores any WOS moveout errors and forces the operation to
continue. Set this parameter to true only if there is no WOS data for
the partition.

l

false (or omit)—Displays any moveout errors and aborts the
operation on error.

Note: If you set this parameter to true and the WOS includes data for
the partition in WOS, partition data in WOS is not dropped.
reorganize_data

Optional Boolean, defaults to false.
l

true—Reorganizes the data if it is not organized, and then drops the
partition.

l

false—Does not attempt to reorganize the data before dropping the
partition. If this parameter is false and the function encounters a
ROS without partition keys, an error occurs.

Permissions
l

Table owner

l

USAGE privilege on schema that contains the table

Notes and Restrictions
The results of a DROP_PARTITION call go into effect immediately. If you drop a partition using
DROP_PARTITION and then try to add data to a partition with the same name, HP Vertica creates
a new partition.
If the operation cannot obtain an O Lock on the table(s), HP Vertica attempts to close any internal
Tuple Mover (TM) sessions running on the same table(s) so that the operation can proceed. Explicit
TM operations that are running in user sessions are not closed. If an explicit TM operation is running
on the table, then the operation cannot proceed until the explicit TM operation completes.
In general, if a ROS container has data that belongs to n+1 partitions and you want to drop a
specific partition, the DROP_PARTITION operation:
1. Forces the partition of data into two containers where
n

One container holds the data that belongs to the partition that is to be dropped.

n

Another container holds the remaining n partitions.

2. Drops the specified partition.
DROP_PARTITION forces a moveout if there is data in the WOS (WOS is not partition aware).

HP Vertica Analytic Database (7.0.x)

Page 612 of 1539

SQL Reference Manual
SQL Functions

DROP_PARTITION acquires an exclusive lock on the table to prevent DELETE | UPDATE |
INSERT | COPY statements from affecting the table, as well as any SELECT statements issued at
SERIALIZABLE isolation level.
You cannot perform a DROP_PARTITION operation on tables with projections that are not up to
date (have not been refreshed).
DROP_PARTITION fails if you do not set the optional third parameter to true and the function
encounters ROS's that do not have partition keys.

Examples
Using the example schema in Defining Partitions, the following command explicitly drops the 2009
partition key from table trade:
SELECT DROP_PARTITION('trade', 2009);
DROP_PARTITION
------------------Partition dropped
(1 row)

Here, the partition key is specified:
SELECT DROP_PARTITION('trade', EXTRACT('year' FROM '2009-01-01'::date));
DROP_PARTITION
------------------Partition dropped
(1 row)

The following example creates a table called dates and partitions the table by year:
CREATE TABLE dates (year INTEGER NOT NULL,
month VARCHAR(8) NOT NULL)
PARTITION BY year * 12 + month;

The following statement drops the partition using a constant for Oct 2010 (2010*12 + 10 = 24130):
SELECT DROP_PARTITION('dates', '24130');
DROP_PARTITION
------------------Partition dropped
(1 row)

Alternatively, the expression can be placed in line: SELECT DROP_PARTITION('dates', 2010*12
+ 10);
The following command first reorganizes the data if it is unpartitioned and then explicitly drops the
2009 partition key from table trade:
SELECT DROP_PARTITION('trade', 2009, false, true);

HP Vertica Analytic Database (7.0.x)

Page 613 of 1539

SQL Reference Manual
SQL Functions

DROP_PARTITION
------------------Partition dropped
(1 row)

See Also
l

Dropping Partitions

l

ADVANCE_EPOCH

l

ALTER PROJECTION RENAME

l

COLUMN_STORAGE

l

CREATE TABLE

l

DO_TM_TASK

l

DUMP_PARTITION_KEYS

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

MERGE_PARTITIONS

l

PARTITION_PROJECTION

l

PARTITION_TABLE

l

PROJECTIONS

DROP_STATISTICS
Removes statistics for the specified table and lets you optionally specify the category of statistics
to drop.

Syntax
DROP_STATISTICS { ('') | ('[[db-name.]schema-name.]table'
[, {'BASE' | 'HISTOGRAMS' | 'ALL'} ])};

Return Value
0 - If successful, DROP_STATISTICS always returns 0. If the command fails, DROP_
STATISTICS displays an error message. See vertica.log for message details.

HP Vertica Analytic Database (7.0.x)

Page 614 of 1539

SQL Reference Manual
SQL Functions

Parameters
''

Empty string. Drops statistics for all projections.

[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table

Drops statistics for all projections within the specified table. When using
more than one schema, specify the schema that contains the table with
the projections you want to delete, as noted in the syntax.

CATEGORY

Specifies the category of statistics to drop for the named [db-name.]
schema-name.]table:
l

'BASE' (default) drops histograms and row counts (min/max column
values, histogram.

l

'HISTOGRAMS' drops only the histograms. Row counts statistics
remain.

l

'ALL' drops all statistics.

Privileges
l

INSERT/UPDATE/DELETE privilege on table

l

USAGE privilege on schema that contains the table

Notes
Once dropped, statistics can be time consuming to regenerate.

Examples
The following command analyzes all statistics on the VMart schema database:
=> SELECT ANALYZE_STATISTICS('');
ANALYZE_STATISTICS
-------------------0

HP Vertica Analytic Database (7.0.x)

Page 615 of 1539

SQL Reference Manual
SQL Functions

(1 row)

This command drops base statistics for table store_sales_fact in the store schema:
=> SELECT DROP_STATISTICS('store.store_sales_fact', 'BASE');
DROP_STATISTICS
----------------0
(1 row)

Note that this command works the same as the previous command:
=> SELECT DROP_STATISTICS('store.store_sales_fact');
DROP_STATISTICS
----------------0
(1 row)

This command also drops statistics for all table projections:
=> SELECT DROP_STATISTICS ('');
DROP_STATISTICS
----------------0
(1 row)

For use cases, see Collecting Statistics in the Administrator's Guide

See Also
l

ANALYZE_STATISTICS

l

EXPORT_STATISTICS

l

IMPORT_STATISTICS

DUMP_CATALOG
Returns an internal representation of the HP Vertica catalog. This function is used for diagnostic
purposes.

Syntax
DUMP_CATALOG()

Privileges
None; however, function dumps only the objects visible to the user.

HP Vertica Analytic Database (7.0.x)

Page 616 of 1539

SQL Reference Manual
SQL Functions

Notes
To obtain an internal representation of the HP Vertica catalog for diagnosis, run the query:
=> SELECT DUMP_CATALOG();

The output is written to the specified file:
\o /tmp/catalog.txtSELECT DUMP_CATALOG();
\o

DUMP_LOCKTABLE
Returns information about deadlocked clients and the resources they are waiting for.

Syntax
DUMP_LOCKTABLE()

Privileges
None

Notes
Use DUMP_LOCKTABLE if HP Vertica becomes unresponsive:
1. Open an additional vsql connection.
2. Execute the query:
=> SELECT DUMP_LOCKTABLE();

The output is written to vsql. See Monitoring the Log Files.
You can also see who is connected using the following command:
=> SELECT * FROM SESSIONS;

Close all sessions using the following command:
=>SELECT CLOSE_ALL_SESSIONS();

Close a single session using the following command:

HP Vertica Analytic Database (7.0.x)

Page 617 of 1539

SQL Reference Manual
SQL Functions

=> SELECT CLOSE_SESSION('session_id');

You get the session_id value from the V_MONITOR.SESSIONS system table.

See Also
l

CLOSE_ALL_SESSIONS

l

CLOSE_SESSION

l

LOCKS

l

SESSIONS

DUMP_PARTITION_KEYS
Dumps the partition keys of all projections in the system.

Syntax
DUMP_PARTITION_KEYS( )

Note: The ROS objects of partitioned tables without partition keys are ignored by the tuple
mover and are not merged during automatic tuple mover operations.

Privileges
None; however function dumps only the tables for which user has SELECT privileges.

Example
=> SELECT DUMP_PARTITION_KEYS( );
Partition keys on node v_vmart_node0001
Projection 'states_b0'
Storage [ROS container]
No of partition keys: 1
Partition keys: NH
Storage [ROS container]
No of partition keys: 1
Partition keys: MA
Projection 'states_b1'
Storage [ROS container]
No of partition keys: 1
Partition keys: VT
Storage [ROS container]
No of partition keys: 1

HP Vertica Analytic Database (7.0.x)

Page 618 of 1539

SQL Reference Manual
SQL Functions

Partition keys: ME
Storage [ROS container]
No of partition keys: 1
Partition keys: CT

See Also
l

DO_TM_TASK

l

DROP_PARTITION

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_PROJECTION

l

PARTITION_TABLE

l

PARTITIONS

l

Working with Table Partitions

DUMP_PROJECTION_PARTITION_KEYS
Dumps the partition keys of the specified projection.

Syntax
DUMP_PROJECTION_PARTITION_KEYS(

'projection_name' )

Parameters
projection_name

Specifies the name of the projection.

Privileges
l

SELECT privilege on table

l

USAGE privileges on schema

Example
The following example creates a simple table called states and partitions the data by state:

HP Vertica Analytic Database (7.0.x)

Page 619 of 1539

SQL Reference Manual
SQL Functions

=> CREATE TABLE states (year INTEGER NOT NULL,
state VARCHAR NOT NULL)
PARTITION BY state;
=> CREATE PROJECTION states_p (state, year)
AS SELECT * FROM states
ORDER BY state, year UNSEGMENTED ALL NODES;

Now dump the partition key of the specified projection:
=> SELECT DUMP_PROJECTION_PARTITION_KEYS( 'states_p_node0001' );
Partition keys on node helios_node0001
Projection 'states_p_node0001'
No of partition keys: 1
Partition keys on node helios_node0002
...
(1 row)

See Also
l

DO_TM_TASK

l

DROP_PARTITION

l

DUMP_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_PROJECTION

l

PARTITION_TABLE

l

PROJECTIONS

l

Working with Table Partitions

DUMP_TABLE_PARTITION_KEYS
Dumps the partition keys of all projections anchored on the specified table.

Syntax
DUMP_TABLE_PARTITION_KEYS ( 'table_name' )

Parameters
table_name

Specifies the name of the table.

HP Vertica Analytic Database (7.0.x)

Page 620 of 1539

SQL Reference Manual
SQL Functions

Privilege
l

SELECT privilege on table

l

USAGE privileges on schema

Examples
The following example creates a simple table called states and partitions the data by state:
=> CREATE TABLE states (year INTEGER NOT NULL,
state VARCHAR NOT NULL)
PARTITION BY state;
=> CREATE PROJECTION states_p (state, year) AS
SELECT * FROM states
ORDER BY state, year UNSEGMENTED ALL NODES;

Now dump the partition keys of all projections anchored on table states:
=> SELECT DUMP_TABLE_PARTITION_KEYS( 'states' );
Partition keys on helios_node0001
Projection 'states_p_node0004'
No of partition keys: 1
Projection 'states_p_node0003'
No of partition keys: 1
Projection 'states_p_node0002'
No of partition keys: 1
Projection 'states_p_node0001'
No of partition keys: 1
Partition keys on helios_node0002
...
(1 row)

See Also
l

DO_TM_TASK

l

DROP_PARTITION

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_PROJECTION

l

PARTITION_TABLE

l

Working with Table Partitions

HP Vertica Analytic Database (7.0.x)

Page 621 of 1539

SQL Reference Manual
SQL Functions

ENABLE_ELASTIC_CLUSTER
Enables elastic cluster scaling, which makes enlarging or reducing the size of your database
cluster more efficient by segmenting a node's data into chunks that can be easily moved to other
hosts.
Note: Databases created using HP Vertica Version 5.0 and later have elastic cluster enabled
by default. You need to use this function on databases created before version 5.0 in order for
them to use the elastic clustering feature.

Syntax
ENABLE_ELASTIC_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT ENABLE_ELASTIC_CLUSTER();
ENABLE_ELASTIC_CLUSTER
-----------------------ENABLED
(1 row)

See Also
l

DISABLE_ELASTIC_CLUSTER

ENABLE_LOCAL_SEGMENTS
Enables local storage segmentation, which breaks projections segments on nodes into containers
that can be easily moved to other nodes. See Local Data Segmentation in the Administrator's Guide
for more information.

Syntax
ENABLE_LOCAL_SEGMENTS()

HP Vertica Analytic Database (7.0.x)

Page 622 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Example
=> SELECT ENABLE_LOCAL_SEGMENTS();
ENABLE_LOCAL_SEGMENTS
----------------------ENABLED
(1 row)

ENABLE_PROFILING
Enables profiling for the profiling type you specify.
Note: HP Vertica stores profiled data is in memory, so depending on how much data you
collect, profiling could be memory intensive.

Syntax
ENABLE_PROFILING( 'profiling-type' )

Parameters
profiling-type

The type of profiling data you want to enable. Can be one of:
l

session—enables profiling for basic session parameters and lock time out
data

l

query—enables profiling for general information about queries that ran, such
as the query strings used and the duration of queries

l

ee—enables profiling for information about the execution run of each query

Example
The following statement enables profiling on query execution runs:
=> SELECT ENABLE_PROFILING('ee');
ENABLE_PROFILING
----------------------

HP Vertica Analytic Database (7.0.x)

Page 623 of 1539

SQL Reference Manual
SQL Functions

EE Profiling Enabled
(1 row)

See Also
l

CLEAR_PROFILING

l

DISABLE_PROFILING

l

Profiling Database Performance

EVALUATE_DELETE_PERFORMANCE
Evaluates projections for potential DELETE performance issues. If there are issues found, a
warning message is displayed. For steps you can take to resolve delete and update performance
issues, see Optimizing Deletes and Updates for Performance in the Administrator's Guide. This
function uses data sampling to determine whether there are any issues with a projection. Therefore,
it does not generate false-positives warnings, but it can miss some cases where there are
performance issues.
Note: Optimizing for delete performance is the same as optimizing for update performance.
So, you can use this function to help optimize a projection for updates as well as deletes.

Syntax
EVALUATE_DELETE_PERFORMANCE ( 'target' )

Parameters
target

The name of a projection or table. If you supply the name of a projection, only that
projection is evaluated for DELETE performance issues. If you supply the name of a
table, then all of the projections anchored to the table will be evaluated for issues.
If you do not provide a projection or table name, EVALUATE_DELETE_
PERFORMANCE examines all of the projections that you can access for DELETE
performance issues. Depending on the size you your database, this may take a long
time.

Privileges
None

HP Vertica Analytic Database (7.0.x)

Page 624 of 1539

SQL Reference Manual
SQL Functions

Notes
When evaluating multiple projections, EVALUATE_DELETE_PERFORMANCE reports up to ten
projections that have issues, and refers you to a table that contains the full list of issues it has
found.

Example
The following example demonstrates how you can use EVALUATE_DELETE_PERFORMANCE
to evaluate your projections for slow DELETE performance.
=> create table example (A int, B int,C int);
CREATE TABLE
=> create projection one_sort (A,B,C) as (select A,B,C from example) order by A;
CREATE PROJECTION
=> create projection two_sort (A,B,C) as (select A,B,C from example) order by A,B;
CREATE PROJECTION
=> select evaluate_delete_performance('one_sort');
evaluate_delete_performance
--------------------------------------------------No projection delete performance concerns found.
(1 row)
=> select evaluate_delete_performance('two_sort');
evaluate_delete_performance
--------------------------------------------------No projection delete performance concerns found.
(1 row)

The previous example showed that there was no structural issue with the projection that would
cause poor DELETE performance. However, the data contained within the projection can create
potential delete issues if the sorted columns do not uniquely identify a row or small number of rows.
In the following example, Perl is used to populate the table with data using a nested series of loops.
The inner loop populates column C, the middle loop populates column B, and the outer loop
populates column A. The result is column A contains only three distinct values (0, 1, and 2), while
column B slowly varies between 20 and 0 and column C changes in each row. EVALUATE_
DELETE_PERFORMANCE is run against the projections again to see if the data within the
projections causes any potential DELETE performance issues.
=> \! perl -e 'for ($i=0; $i<3; $i++) { for ($j=0; $j<21; $j++) { for ($k=0; $k<19; $k++)
{ printf "%d,%d,%d\n", $i,$j,$k;}}}' | /opt/vertica/bin/vsql -c "copy example from stdin
delimiter ',' direct;"
Password:
=> select * from example;
A | B | C
---+----+---0 | 20 | 18
0 | 20 | 17
0 | 20 | 16
0 | 20 | 15
0 | 20 | 14

HP Vertica Analytic Database (7.0.x)

Page 625 of 1539

SQL Reference Manual
SQL Functions

0 | 20 | 13
0 | 20 | 12
0 | 20 | 11
0 | 20 | 10
0 | 20 | 9
0 | 20 | 8
0 | 20 | 7
0 | 20 | 6
0 | 20 | 5
0 | 20 | 4
0 | 20 | 3
0 | 20 | 2
0 | 20 | 1
0 | 20 | 0
0 | 19 | 18
1157 rows omitted
2 | 1 | 0
2 | 0 | 18
2 | 0 | 17
2 | 0 | 16
2 | 0 | 15
2 | 0 | 14
2 | 0 | 13
2 | 0 | 12
2 | 0 | 11
2 | 0 | 10
2 | 0 | 9
2 | 0 | 8
2 | 0 | 7
2 | 0 | 6
2 | 0 | 5
2 | 0 | 4
2 | 0 | 3
2 | 0 | 2
2 | 0 | 1
2 | 0 | 0
=> SELECT COUNT (*) FROM example;
COUNT
------1197
(1 row)
=> SELECT COUNT (DISTINCT A) FROM example;
COUNT
------3
(1 row)
=> select evaluate_delete_performance('one_sort');
evaluate_delete_performance
--------------------------------------------------Projection exhibits delete performance concerns.
(1 row)
release=> select evaluate_delete_performance('two_sort');
evaluate_delete_performance
--------------------------------------------------No projection delete performance concerns found.
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 626 of 1539

SQL Reference Manual
SQL Functions

The one_sort projection has potential delete issues since it only sorts on column A which has few
distinct values. This means that each value in the sort column corresponds to many rows in the
projection, which negatively impacts DELETE performance. Since the two_sort projection is sorted
on columns A and B, each combination of values in the two sort columns identifies just a few rows,
allowing deletes to be performed faster.
Not supplying a projection name results in all of the projections you can access being evaluated for
DELETE performance issues.
=> select evaluate_delete_performance();
evaluate_delete_performance
--------------------------------------------------------------------------The following projection exhibits delete performance concerns:
"public"."one_sort"
See v_catalog.projection_delete_concerns for more details.
(1 row)

EXPORT_CATALOG
Generates a SQL script that you can use to recreate a physical schema design in its current state
on a different cluster. This function always attempts to recreate projection statements with KSAFE
clauses, if they exist in the original definitions, or OFFSET clauses if they do not.

Syntax
EXPORT_CATALOG ( [ 'destination' ] , [ 'scope' ] )

Parameters
destination

Specifies the path and name of the SQL output file. An empty string (''), which is
the default, outputs the script to standard output. The function writes the script to
the catalog directory if no destination is specified.
If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents.

scope

Determines what to export:
l

DESIGN—Exports schemas, tables, constraints, views, and projections to
which the user has access. This is the default value.

l

DESIGN_ALL—Exports all the design objects plus system objects created in
Database Designer (for example, design contexts and their tables). The objects
that are exported are those to which the user has access.

l

TABLES—Exports all tables, constraints, and projections for for which the user
has permissions. See also EXPORT_TABLES.

HP Vertica Analytic Database (7.0.x)

Page 627 of 1539

SQL Reference Manual
SQL Functions

Privileges
None. However:
l

EXPORT_CATALOG exports only the objects visible to the user .

l

Only a superuser can export output to a file.

Example
The following example exports the design to standard output:
=> SELECT EXPORT_CATALOG('','DESIGN');

See Also
EXPORT_OBJECTS

l

EXPORT_TABLES

l
l

EXPORT_OBJECTS
Generates a SQL script you can use to recreate catalog objects on a different cluster. The
generated script includes only the non-virtual objects to which the user has access. The function
exports catalog objects in order dependency for correct recreation. Running the generated SQL
script on another cluster then creates all referenced objects before their dependent objects.
The EXPORT_OBJECTS function always attempts to recreate projection statements with KSAFE
clauses, if they existed in the original definitions, or OFFSET clauses, if they did not.
None of the EXPORT_OBJECTS parameters accepts a NULL value as input. EXPORT_
OBJECTS returns an error if an explicitly-specified object does not exist, or the user does not have
access to the object.

Syntax
EXPORT_OBJECTS( [ 'destination' ] , [ 'scope' ] , [ 'ksafe' ] )

HP Vertica Analytic Database (7.0.x)

Page 628 of 1539

SQL Reference Manual
SQL Functions

Parameters
destination

Specifies the path and name of the SQL output file. The default empty string ('')
outputs the script to standard output. The function writes the script to the catalog
directory if no destination is specified.
If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents.

scope

ksafe

Determines the scope of the catalog objects to export:
l

An empty string (' ')—exports all non-virtual objects to which the user has
access, including constraints. (Note that constraints are not objects that can be
passed as individual arguments.) An empty string is the default scope value if
you do not limit the export.

l

A comma-delimited list of catalog objects to export, which can include the
following:
n

' [dbname.]schema.object '—matches each named schema object. You can
optionally qualify the schema with a database prefix. A named schema
object can be a table, projection, view, sequence, or user-defined SQL
function.

n

' [dbname.]schema—matches the named schema, which you can optionally
qualify with a database prefix. For a schema, HP Vertica exports all nonvirtual objects that the user has access to within the schema. If a schema
and table have the same name, the schema takes precedence.

Determines if the statistics are regenerated before loading them into the design
context
Specifies whether to incorporate a MARK_DESIGN_KSAFE statement with the
correct K-safe value for the database:
l

true—adds the MARK_DESIGN_KSAFE statement to the end of the output
script. This is the default value.

l

false—omits the MARK_DESIGN_KSAFE statement from the script.

Privileges
None. However:
l

EXPORT_OBJECTS exports only the objects visible to the user .

l

Only a superuser can export output to a file.

HP Vertica Analytic Database (7.0.x)

Page 629 of 1539

SQL Reference Manual
SQL Functions

Example
The following example exports all the non-virtual objects to which the user has access to standard
output. The example uses false for the last parameter, indicating that the file will not include the
MARK_DESIGN_KSAFE statement at the end.
=> SELECT EXPORT_OBJECTS(' ',' ',false);

See Also
l

EXPORT_CATALOG

l

EXPORT_TABLES

l

Exporting Objects

EXPORT_STATISTICS
Generates an XML file that contains statistics for the database. You can optionally export statistics
on a single database object (table, projection, or table column).
Before you export statistics for the database, run ANALYZE_STATISTICS() to automatically
collect the most up to date statistics information.
Note: Use the second argument only if statistics in the database do not match the statistics of
data.

Syntax
EXPORT_STATISTICS [ ( 'destination' )
... | ( '[ [ db-name.]schema.]table [.column-name ]' ) ]

Parameters
destination

Specifies the path and name of the XML output file. An empty string
returns the script to the screen.

HP Vertica Analytic Database (7.0.x)

Page 630 of 1539

SQL Reference Manual
SQL Functions

[[db-name.]schema.]

[Optional] Specifies the schema name. Using a schema identifies objects
that are not unique within the current search path (see Setting Schema
Search Paths).
You can optionally precede a schema with a database name, but you must
be connected to the database you specify. You cannot make changes to
objects in other databases.
The ability to specify different database objects (from database and
schemas to tables and columns) lets you qualify database objects as
explicitly as required. For example, use a table and column
(mytable.column1), a schema, table, and column
(myschema.mytable.column1), and, as full qualification, a database,
schema, table, and column (mydb.myschema.mytable.column1).

table

Specifies the name of the table and exports statistics for all projections of
that table.
Note: If you are using more than one schema, specify the schema
that contains the projection, as noted as noted in the [[db-name.]
schema.] entry.

[.column-name]

[Optional] Specifies the name of a single column, typically a predicate
column. Using this option with a table specification lets you export
statistics for only that column.

Privileges
Must be a superuser.

Examples
The following command exports statistics on the VMart example database to a file:
vmart=> SELECT EXPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/vmart_stats.xml');
EXPORT_STATISTICS
----------------------------------Statistics exported successfully
(1 row)

The next statement exports statistics on a single column (price) from a table called food:
=> SELECT EXPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/price.xml', 'food.pric
e');

HP Vertica Analytic Database (7.0.x)

Page 631 of 1539

SQL Reference Manual
SQL Functions

See Also
l

ANALYZE_STATISTICS

l

DROP_STATISTICS

l

IMPORT_STATISTICS

l

Collecting Database Statistics

EXPORT_TABLES
Generates a SQL script that can be used to recreate a logical schema (schemas, tables,
constraints, and views) on a different cluster.

Syntax
EXPORT_TABLES ( [ 'destination' ] , [ 'scope' ] )

Parameters
destination

Specifies the path and name of the SQL output file. An empty string (''), which is
the default, outputs the script to standard output. The function writes the script to
the catalog directory if no destination is specified.
If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents.

scope

Determines the tables to export. Specify the scope as follows:
l

An empty string (' ')—exports all non-virtual table objects to which the user has
access, including table schemas, sequences, and constraints. Exporting all
non-virtual objects is the default scope, and what the function exports if you do
not specify a scope.

l

A comma-delimited list of objects, which can include the following:
n

' [dbname.][schema.]object '—matches the named objects, which can be
schemas, tables, or views, in the schema. You can optionally qualify a
schema with a database prefix, and objects with a schema. You cannot pass
constraints as individual arguments.

n

' [dbname.]object '—matches a named object, which can be a schema, table,
or view. You can optionally qualify a schema with a database prefix, and an
object with its schema. For a schema, HP Vertica exports all non-virtual
objects to which the user has access within the schema. If a schema and
table both have the same name, the schema takes precedence.

HP Vertica Analytic Database (7.0.x)

Page 632 of 1539

SQL Reference Manual
SQL Functions

Privileges
None; however:
l

Function exports only the objects visible to the user

l

Only a superuser can export output to file

Example
The following example exports the store_orders_fact table of the store schema (in the current
database) to standard output:
=> SELECT EXPORT_TABLES(' ','store.store_orders_fact');

EXPORT_TABLES returns an error if:
l

You explicitly specify an object that does not exist

l

The current user does not have access to a specified object

See Also
EXPORT_CATALOG

l

EXPORT_OBJECTS

l
l

FLUSH_DATA_COLLECTOR
Waits until memory logs are moved to disk and then flushes the Data Collector, synchronizing the
log with the disk storage. A superuser can flush Data Collector information for an individual
component or for all components.

Syntax
FLUSH_DATA_COLLECTOR( [ 'component' ] )

HP Vertica Analytic Database (7.0.x)

Page 633 of 1539

SQL Reference Manual
SQL Functions

Parameters
component

Flushes the specified component. If you provide no argument, the function flushes
the Data Collector in full.
For the current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table.

Privileges
Must be a superuser.

Examples
The following command flushes the Data Collector for the ResourceAcquisitions component:
=> SELECT flush_data_collector('ResourceAcquisitions');
flush_data_collector
---------------------FLUSH
(1 row)

The following command flushes data collection for all components:
=> SELECT flush_data_collector();
flush_data_collector
---------------------FLUSH
(1 row)

See Also
DATA_COLLECTOR

l
l

GET_AHM_EPOCH
Returns the number of the epoch in which the Ancient History Mark is located. Data deleted up to
and including the AHM epoch can be purged from physical storage.

Syntax
GET_AHM_EPOCH()

HP Vertica Analytic Database (7.0.x)

Page 634 of 1539

SQL Reference Manual
SQL Functions

Note: The AHM epoch is 0 (zero) by default (purge is disabled).

Privileges
None

Examples
SELECT GET_AHM_EPOCH();
GET_AHM_EPOCH
---------------------Current AHM epoch: 0
(1 row)

GET_AHM_TIME
Returns a TIMESTAMP value representing the Ancient History Mark. Data deleted up to and
including the AHM epoch can be purged from physical storage.

Syntax
GET_AHM_TIME()

Privileges
None

Examples
SELECT GET_AHM_TIME();
GET_AHM_TIME
------------------------------------------------Current AHM Time: 2010-05-13 12:48:10.532332-04
(1 row)

See Also
l

SET DATESTYLE

l

TIMESTAMP

HP Vertica Analytic Database (7.0.x)

Page 635 of 1539

SQL Reference Manual
SQL Functions

GET_AUDIT_TIME
Reports the time when the automatic audit of database size occurs. HP Vertica performs this audit
if your HP Vertica license includes a data size allowance. For details of this audit, see Managing
Your License Key in the Administrator's Guide. To change the time the audit runs, use the SET_
AUDIT_TIME function.

Syntax
GET_AUDIT_TIME()

Privileges
None

Example
=> SELECT get_audit_time();
get_audit_time
----------------------------------------------------The audit is scheduled to run at 11:59 PM each day.
(1 row)

GET_COMPLIANCE_STATUS
Displays whether your database is in compliance with your HP Vertica license agreement. This
information includes the results of HP Vertica's most recent audit of the database size (if your
license has a data allowance as part of its terms), and the license term (if your license has an end
date).
The information displayed by GET_COMPLIANCE_STATUS includes:
l

The estimated size of the database (see How HP Vertica Calculates Database Size in the
Administrator's Guide for an explanation of the size estimate).

l

The raw data size allowed by your HP Vertica license.

l

The percentage of your allowance that your database is currently using.

l

The date and time of the last audit.

l

Whether your database complies with the data allowance terms of your license agreement.

l

The end date of your license.

l

How many days remain until your license expires.

HP Vertica Analytic Database (7.0.x)

Page 636 of 1539

SQL Reference Manual
SQL Functions

Note: If your license does not have a data allowance or end date, some of the values may not
appear in the output for GET_COMPLIANCE_STATUS.
If the audit shows your license is not in compliance with your data allowance, you should either
delete data to bring the size of the database under the licensed amount, or upgrade your license. If
your license term has expired, you should contact HP immediately to renew your license. See
Managing Your License Key in the Administrator's Guide for further details.

Syntax
GET_COMPLIANCE_STATUS()

Privileges
None

Example
GET_COMPLIANCE_STATUS
--------------------------------------------------------------------------------Raw Data Size: 2.00GB +/- 0.003GB
License Size : 4.000GB
Utilization : 50%
Audit Time
: 2011-03-09 09:54:09.538704+00
Compliance Status : The database is in compliance with respect to raw data size.
License End Date: 04/06/2011
Days Remaining: 28.59
(1 row)

GET_CURRENT_EPOCH
The epoch into which data (COPY, INSERT, UPDATE, and DELETE operations) is currently being
written. The current epoch advances automatically every three minutes.
Returns the number of the current epoch.

Syntax
GET_CURRENT_EPOCH()

Privileges
None

HP Vertica Analytic Database (7.0.x)

Page 637 of 1539

SQL Reference Manual
SQL Functions

Examples
SELECT GET_CURRENT_EPOCH();
GET_CURRENT_EPOCH
------------------683
(1 row)

GET_DATA_COLLECTOR_POLICY
Retrieves a brief statement about the retention policy for the specified component.

Syntax
GET_DATA_COLLECTOR_POLICY( 'component' )

Parameters
component

Returns the retention policy for the specified component.
For a current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table

Privileges
None

Example
The following query returns the history of all resource acquisitions by specifying the
ResourceAcquisitions component:
=> SELECT get_data_collector_policy('ResourceAcquisitions');
get_data_collector_policy
---------------------------------------------1000KB kept in memory, 10000KB kept on disk.
(1 row)

See Also
DATA_COLLECTOR

l
l

HP Vertica Analytic Database (7.0.x)

Page 638 of 1539

SQL Reference Manual
SQL Functions

GET_LAST_GOOD_EPOCH
A term used in manual recovery, LGE (Last Good Epoch) refers to the most recent epoch that can
be recovered.
Returns the number of the last good epoch.

Syntax
GET_LAST_GOOD_EPOCH()

Privileges
None

Examples
SELECT GET_LAST_GOOD_EPOCH();
GET_LAST_GOOD_EPOCH
--------------------682
(1 row)

GET_NUM_ACCEPTED_ROWS
Returns the number of rows loaded into the database for the last completed load for the current
session. GET_NUM_ACCEPTED_ROWS is a meta-function. Do not use it as a value in an
INSERT query.
The number of accepted rows is not available for a load that is currently in process. Check the
LOAD_STREAMS system table for its status.
Also, this meta-function supports only loads from STDIN or a single file on the initiator. You cannot
use GET_NUM_ACCEPTED_ROWS for multi-node loads.

Syntax
GET_NUM_ACCEPTED_ROWS();

Privileges
None
Note: The data regarding accepted rows from the last load during the current session does not

HP Vertica Analytic Database (7.0.x)

Page 639 of 1539

SQL Reference Manual
SQL Functions

persist, and is lost when you initiate a new load.

See Also
l

GET_NUM_REJECTED_ROWS

GET_NUM_REJECTED_ROWS
Returns the number of rows that were rejected during the last completed load for the current
session. GET_NUM_REJECTED_ROWS is a meta-function. Do not use it as a value in an
INSERT query.
Rejected row information is unavailable for a load that is currently running. The number of rejected
rows is not available for a load that is currently in process. Check the LOAD_STREAMS system
table for its status.
Also, this meta-function supports only loads from STDIN or a single file on the initiator. You cannot
use GET_NUM_REJECTED_ROWS for multi-node loads.

Syntax
GET_NUM_REJECTED_ROWS();

Privileges
None
Note: The data regarding rejected rows from the last load during the current session does not
persist, and is dropped when you initiate a new load.

See Also
l

GET_NUM_ACCEPTED_ROWS

GET_PROJECTION_STATUS
Returns information relevant to the status of a projection.

Syntax
GET_PROJECTION_STATUS ( '[[db-name.]schema-name.]projection' );

HP Vertica Analytic Database (7.0.x)

Page 640 of 1539

SQL Reference Manual
SQL Functions

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

projection

Is the name of the projection for which to display status. When using more
than one schema, specify the schema that contains the projection, as
noted above.

Privileges
None

Description
GET_PROJECTION_STATUS returns information relevant to the status of a projection:
l

The current K-safety status of the database

l

The number of nodes in the database

l

Whether the projection is segmented

l

The number and names of buddy projections

l

Whether the projection is safe

l

Whether the projection is up-to-date

l

Whether statistics have been computed for the projection

Notes
l

You can use GET_PROJECTION_STATUS to monitor the progress of a projection data
refresh. See ALTER PROJECTION.

l

To view a list of the nodes in a database, use the View Database Command in the
Administration Tools.

HP Vertica Analytic Database (7.0.x)

Page 641 of 1539

SQL Reference Manual
SQL Functions

Examples
=> SELECT GET_PROJECTION_STATUS('public.customer_dimension_site01');
GET_PROJECTION_STATUS
---------------------------------------------------------------------------------------------Current system K is 1.
# of Nodes: 4.
public.customer_dimension_site01 [Segmented: No] [Seg Cols: ] [K: 3] [public.customer_dim
ension_site04, public.customer_dimension_site03,
public.customer_dimension_site02]
[Safe: Yes] [UptoDate: Yes][Stats: Yes]

See Also
l

ALTER PROJECTION RENAME

l

GET_PROJECTIONS, GET_TABLE_PROJECTIONS

GET_PROJECTIONS, GET_TABLE_PROJECTIONS
Note: This function was formerly named GET_TABLE_PROJECTIONS(). HP Vertica still
supports the former function name.
Returns information relevant to the status of a table:
l

The current K-safety status of the database

l

The number of sites (nodes) in the database

l

The number of projections for which the specified table is the anchor table

l

For each projection:
n

The projection's buddy projections

n

Whether the projection is segmented

n

Whether the projection is safe

n

Whether the projection is up-to-date

Syntax
GET_PROJECTIONS ( '[[db-name.]schema-name.]table' )

HP Vertica Analytic Database (7.0.x)

Page 642 of 1539

SQL Reference Manual
SQL Functions

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table

Is the name of the table for which to list projections. When using more than
one schema, specify the schema that contains the table.

Privileges
None

Notes
l

You can use GET_PROJECTIONS to monitor the progress of a projection data refresh. See
ALTER PROJECTION.

l

To view a list of the nodes in a database, use the View Database Command in the
Administration Tools.

Examples
The following example gets information about the store_dimension table in the VMart schema:
=> SELECT GET_PROJECTIONS('store.store_dimension');
-------------------------------------------------------------------------------------Current system K is 1.
# of Nodes: 4.
Table store.store_dimension has 4 projections.
Projection Name: [Segmented] [Seg Cols] [# of Buddies] [Buddy Projections] [Safe] [UptoDa
te]
---------------------------------------------------------store.store_dimension_node0004 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio
n_node0003, store.store_dimension_node0002, store.store_dimension_node0001]
[Safe: Yes] [UptoDate: Yes][Stats: Yes]
store.store_dimension_node0003 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio
n_node0004, store.store_dimension_node0002, store.store_dimension_node0001]
[Safe: Yes] [UptoDate: Yes][Stats: Yes]
store.store_dimension_node0002 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio
n_node0004, store.store_dimension_node0003, store.store_dimension_node0001]
[Safe: Yes] [UptoDate: Yes][Stats: Yes]

HP Vertica Analytic Database (7.0.x)

Page 643 of 1539

SQL Reference Manual
SQL Functions

store.store_dimension_node0001 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio
n_node0004, store.store_dimension_node0003, store.store_dimension_node0002]
[Safe: Yes] [UptoDate: Yes][Stats: Yes]
(1 row)

See Also
l

ALTER PROJECTION RENAME

l

GET_PROJECTION_STATUS

HAS_ROLE
Indicates, with a Boolean value, whether a role has been assigned to a user. This function is useful
for letting you check your own role membership.

Behavior Type
Stable

Syntax 1
HAS_ROLE( [ 'user_name' ,] 'role_name' );

Syntax 2
HAS_ROLE( 'role_name' );

Parameters
user_name

[Optional] The name of a user to look up. Currently, only a superuser can supply the
user_name argument.

role_name

The name of the role you want to verify has been granted.

Privileges
Users can check their own role membership by calling HAS_ROLE('role_name'), but only a
superuser can look up other users' memberships using the optional user_name parameter.

HP Vertica Analytic Database (7.0.x)

Page 644 of 1539

SQL Reference Manual
SQL Functions

Notes
You can query V_CATALOG system tables ROLES, GRANTS, and USERS to show any directlyassigned roles; however, these tables do not indicate whether a role is available to a user when
roles may be available through other roles (indirectly).

Examples
User Bob wants to see if he has been granted the commentor role:
=> SELECT HAS_ROLE('commentor');

Output t for true indicates that Bob has been assigned the commentor role:
HAS_ROLE
---------t
(1 row)

In the following function call, a superuser checks if the logadmin role has been granted to user Bob:
=> SELECT HAS_ROLE('Bob', 'logadmin');
HAS_ROLE
---------t
(1 row)

To view the names of all roles users can access, along with any roles that have been assigned to
those roles, query the V_CATALOG.ROLES system table. An asterisk in the output means role
granted WITH ADMIN OPTION.
=> SELECT * FROM roles;
role_id
|
name
| assigned_roles
-------------------+-----------------+---------------45035996273704964 | public
|
45035996273704966 | dbduser
|
45035996273704968 | dbadmin
| dbduser*
45035996273704972 | pseudosuperuser | dbadmin*
45035996273704974 | logreader
|
45035996273704976 | logwriter
|
45035996273704978 | logadmin
| logreader,
logwriter
(7 rows)

HP Vertica Analytic Database (7.0.x)

Page 645 of 1539

SQL Reference Manual
SQL Functions

See Also
l

GRANTS

l

ROLES

l

USERS

l

Managing Users and Privileges

l

Viewing a user's Role

IMPORT_STATISTICS
Imports statistics from the XML file generated by the EXPORT_STATISTICS command.

Syntax
IMPORT_STATISTICS ( 'destination' )

Parameters
destination

Specifies the path and name of the XML input file (which is the output of EXPORT_
STATISTICS function).

Privileges
Must be a superuser.

Notes
l

Imported statistics override existing statistics for all projections on the specified table.

l

For use cases, see Collecting Statistics in the Administrator's Guide

Example
Import the statistics for the VMart database that EXPORT_STATISTICS saved.
-> SELECT IMPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/vmart_stats.xml');
IMPORT_STATISTICS

HP Vertica Analytic Database (7.0.x)

Page 646 of 1539

SQL Reference Manual
SQL Functions

---------------------------------------------------------------------------Importing statistics for projection date_dimension_super column date_key failure (stats d
id not contain row counts)
Importing statistics for projection date_dimension_super column date failure (stats did n
ot contain row counts)
Importing statistics for projection date_dimension_super column full_date_description fai
lure (stats did not contain row counts)
...
(1 row)
VMart=>

See Also
l

ANALYZE_STATISTICS

l

DROP_STATISTICS

l

EXPORT_STATISTICS

INTERRUPT_STATEMENT
Interrupts the specified statement (within an external session), rolls back the current transaction,
and writes a success or failure message to the log file.

Syntax
INTERRUPT_STATEMENT( 'session_id ', statement_id )

Parameters
session_id

Specifies the session to interrupt. This identifier is unique within the cluster at
any point in time.

statement_id

Specifies the statement to interrupt

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 647 of 1539

SQL Reference Manual
SQL Functions

Notes
l

Only statements run by external sessions can be interrupted.

l

Sessions can be interrupted during statement execution.

l

If the statement_id is valid, the statement is interruptible. The command is successfully sent
and returns a success message. Otherwise the system returns an error.

Messages
The following list describes messages you might encounter:
Message

Meaning

Statement interrupt sent. Check SESSIONS for progress.

This message
indicates
success.

Session  could not be successfully interrupted: session not found.

The session ID
argument to the
interrupt
command does
not match a
running session.

Session  could not be successfully interrupted: statement not found.

The statement ID
does not match (or
no longer
matches) the ID of
a running
statement (if any).

No interruptible statement running

The statement is
DDL or otherwise
non-interruptible.

Internal (system) sessions cannot be interrupted.

The session is
internal, and only
statements run by
external sessions
can be interrupted.

Examples
Two user sessions are open. RECORD 1 shows user session running SELECT FROM SESSION, and
RECORD 2 shows user session running COPY DIRECT:

HP Vertica Analytic Database (7.0.x)

Page 648 of 1539

SQL Reference Manual
SQL Functions

=> SELECT * FROM SESSIONS;
-[ RECORD 1 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin
client_hostname
| 127.0.0.1:52110
client_pid
| 4554
login_timestamp
| 2011-01-03 14:05:40.252625-05
session_id
| stress04-4325:0x14
client_label
|
transaction_start
| 2011-01-03 14:05:44.325781
transaction_id
| 45035996273728326
transaction_description
| user dbadmin (select * from sessions;)
statement_start
| 2011-01-03 15:36:13.896288
statement_id
| 10
last_statement_duration_us | 14978
current_statement
| select * from sessions;
ssl_state
| None
authentication_method
| Trust
-[ RECORD 2 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0003
user_name
| dbadmin
client_hostname
| 127.0.0.1:56367
client_pid
| 1191
login_timestamp
| 2011-01-03 15:31:44.939302-05
session_id
| stress06-25663:0xbec
client_label
|
transaction_start
| 2011-01-03 15:34:51.05939
transaction_id
| 54043195528458775
transaction_description
| user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl'
DELIMITER '|' NULL '\\n' DIRECT;)
statement_start
| 2011-01-03 15:35:46.436748
statement_id
| 5
last_statement_duration_us | 1591403
current_statement
| COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|'
NULL '\\n' DIRECT;
ssl_state
| None
authentication_method
| Trust

Interrupt the COPY DIRECT statement running in stress06-25663:0xbec:
=> \xExpanded display is off.
=> SELECT INTERRUPT_STATEMENT('stress06-25663:0x1537', 5);
interrupt_statement
-----------------------------------------------------------------Statement interrupt sent. Check v_monitor.sessions for progress.
(1 row)

Verify that the interrupted statement is no longer active by looking at the current_statement column
in the SESSIONS system table. This column becomes blank when the statement has been
interrupted:
=> SELECT * FROM SESSIONS;
-[ RECORD 1 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0001
user_name
| dbadmin

HP Vertica Analytic Database (7.0.x)

Page 649 of 1539

SQL Reference Manual
SQL Functions

client_hostname
| 127.0.0.1:52110
client_pid
| 4554
login_timestamp
| 2011-01-03 14:05:40.252625-05
session_id
| stress04-4325:0x14
client_label
|
transaction_start
| 2011-01-03 14:05:44.325781
transaction_id
| 45035996273728326
transaction_description
| user dbadmin (select * from sessions;)
statement_start
| 2011-01-03 15:36:13.896288
statement_id
| 10
last_statement_duration_us | 14978
current_statement
| select * from sessions;
ssl_state
| None
authentication_method
| Trust
-[ RECORD 2 ]--------------+---------------------------------------------------node_name
| v_vmartdb_node0003
user_name
| dbadmin
client_hostname
| 127.0.0.1:56367
client_pid
| 1191
login_timestamp
| 2011-01-03 15:31:44.939302-05
session_id
| stress06-25663:0xbec
client_label
|
transaction_start
| 2011-01-03 15:34:51.05939
transaction_id
| 54043195528458775
transaction_description
| user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl'
DELIMITER '|' NULL '\\n' DIRECT;)
statement_start
| 2011-01-03 15:35:46.436748
statement_id
| 5
last_statement_duration_us | 1591403
current_statement
|
ssl_state
| None
authentication_method
| Trust

See Also
l

SESSIONS

l

Managing Sessions

l

Configuration Parameters

INSTALL_LICENSE
Installs the license key in the global catalog.

Syntax
INSTALL_LICENSE( 'filename' )

Parameters
filename

specifies the absolute pathname of a valid license file.

HP Vertica Analytic Database (7.0.x)

Page 650 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Notes
For more information about license keys, see Managing Your License Key in the Administrator's
Guide.

Examples
=> SELECT INSTALL_LICENSE('/tmp/vlicense.dat');

LAST_INSERT_ID
Returns the last value of a column whose value is automatically incremented through the AUTO_
INCREMENT or IDENTITY Column-Constraint. If multiple sessions concurrently load the same
table, the returned value is the last value generated for an AUTO_INCREMENT column by an
insert in that session.

Behavior Type
Volatile

Syntax
LAST_INSERT_ID()

Privileges
l

Table owner

l

USAGE privileges on schema

Notes
l

This function works only with AUTO_INCREMENT and IDENTITY columns. See columnconstraints for the CREATE TABLE statement.

l

LAST_INSERT_ID does not work with sequence generators created through the CREATE
SEQUENCE statement.

HP Vertica Analytic Database (7.0.x)

Page 651 of 1539

SQL Reference Manual
SQL Functions

Examples
Create a sample table called customer4.
=> CREATE TABLE customer4(
ID IDENTITY(2,2),
lname VARCHAR(25),
fname VARCHAR(25),
membership_card INTEGER
);
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Gupta', 'Saleem', 475987);

Notice that the IDENTITY column has a seed of 2, which specifies the value for the first row loaded
into the table, and an increment of 2, which specifies the value that is added to the IDENTITY value
of the previous row.
Query the table you just created:
=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
(1 row)

Insert some additional values:
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Lee', 'Chen', 598742);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------4
(1 row)

Query the table again:
=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
(2 rows)

Add another row:

HP Vertica Analytic Database (7.0.x)

Page 652 of 1539

SQL Reference Manual
SQL Functions

=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Davis', 'Bill', 469543);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------6
(1 row)

Query the table again:
=> SELECT * FROM customer4; ID | lname | fname
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
6 | Davis | Bill
|
469543
(3 rows)

| membership_card

See Also
l

ALTER SEQUENCE

l

CREATE SEQUENCE

l

DROP SEQUENCE

l

SEQUENCES

l

Using Named Sequences

l

Sequence Privileges

MAKE_AHM_NOW
Sets the Ancient History Mark (AHM) to the greatest allowable value, and lets you drop any
projections that existed before the issue occurred.
Caution: This function is intended for use by Administrators only.

Syntax
MAKE_AHM_NOW ( [ true ] )

HP Vertica Analytic Database (7.0.x)

Page 653 of 1539

SQL Reference Manual
SQL Functions

Parameters
true

[Optional] Allows AHM to advance when nodes are down. Note: If the AHM is advanced
after the last good epoch of the failed nodes, those nodes must recover all data from
scratch. Use with care.

Privileges
Must be a superuser.

Notes
l

l

The MAKE_AHM_NOW function performs the following operations:
n

Advances the epoch.

n

Performs a moveout operation on all projections.

n

Sets the AHM to LGE — at least to the current epoch at the time MAKE_AHM_NOW() was
issued.

All history is lost and you cannot perform historical queries prior to the current epoch.

Example
=> SELECT MAKE_AHM_NOW();
MAKE_AHM_NOW
-----------------------------AHM set (New AHM Epoch: 683)
(1 row)

The following command allows the AHM to advance, even though node 2 is down:
=> SELECT
WARNING:
WARNING:
WARNING:

MAKE_AHM_NOW(true);
Received no response from v_vmartdb_node0002 in get cluster LGE
Received no response from v_vmartdb_node0002 in get cluster LGE
Received no response from v_vmartdb_node0002 in set AHM
MAKE_AHM_NOW
-----------------------------AHM set (New AHM Epoch: 684)
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 654 of 1539

SQL Reference Manual
SQL Functions

See Also
l

DROP PROJECTION

l

MARK_DESIGN_KSAFE

l

SET_AHM_EPOCH

l

SET_AHM_TIME

MARK_DESIGN_KSAFE
Enables or disables high availability in your environment, in case of a failure. Before enabling
recovery, MARK_DESIGN_KSAFE queries the catalog to determine whether a cluster's physical
schema design meets the following requirements:
l

Small, unsegmented tables are replicated on all nodes.

l

Large table superprojections are segmented with each segment on a different node.

l

Each large table projection has at least one buddy projection for K-safety=1 (or two buddy
projections for K-safety=2).
Buddy projections are also segmented across database nodes, but the distribution is modified
so that segments that contain the same data are distributed to different nodes. See High
Availability Through Projections in the Concepts Guide.
Note: Projections are considered to be buddies if they contain the same columns and have
the same segmentation. They can have different sort orders.

MARK_DESIGN_KSAFE does not change the physical schema in any way.

Syntax
MARK_DESIGN_KSAFE ( k )

Parameters
k

2 enables high availability if the schema design meets requirements for K-safety=2
1 enables high availability if the schema design meets requirements for K-safety=1
0 disables high availability

If you specify a k value of one (1) or two (2), HP Vertica returns one of the following messages.
Success:

HP Vertica Analytic Database (7.0.x)

Page 655 of 1539

SQL Reference Manual
SQL Functions

Marked design n-safe

Failure:
The schema does not meet requirements for K=n.
Fact table projection projection-name
has insufficient "buddy" projections.

n in the message is 1 or 2 and represents the k value.

Privileges
Must be a superuser.

Notes
l

The database's internal recovery state persists across database restarts but it is not checked at
startup time.

l

If a database has automatic recovery enabled, you must temporarily disable automatic recovery
before creating a new table.

l

When one node fails on a system marked K-safe=1, the remaining nodes are available for DML
operations.

Examples
=> SELECT MARK_DESIGN_KSAFE(1);
mark_design_ksafe
---------------------Marked design 1-safe
(1 row)

If the physical schema design is not K-Safe, messages indicate which projections do not have a
buddy:
=> SELECT MARK_DESIGN_KSAFE(1);
The given K value is not correct;
the schema is 0-safe
Projection pp1 has 0 buddies,
which is smaller that the given K of 1
Projection pp2 has 0 buddies,
which is smaller that the given K of 1
.
.
.
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 656 of 1539

SQL Reference Manual
SQL Functions

See Also
l

SYSTEM

l

High Availability and Recovery

l

HP Vertica System Tables

l

Avoiding Resegmentation During Joins

l

Failure Recovery

MATERIALIZE_FLEXTABLE_COLUMNS
Materializes virtual columns that are listed as key_names in the flextable_keys table. You can
optionally indicate the number of columns to materialize, and use a keys table other than the
default. If you do not specify the number of columns, the function materializes up to 50 virtual
column key names. Calling this function requires that you first compute flex table keys using either
COMPUTE_FLEXTABLE_KEYS or COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW .
Note: Materializing any virtual column into a real column with this function affects data storage
limits. Each materialized column counts against the data storage limit of your HP Vertica
Enterprise Edition (EE) license. This increase is reflected when HP Vertica next performs a
license compliance audit. To manually check your EE license compliance, call the audit()
function, described in the SQL Reference Manual.

Usage
materialize_flextable_columns('flex_table' [, n-columns [, keys_table_name] ])

Arguments
flex_table

The name of the flex table with columns to materialize. Specifying only
the flex table name attempts to materialize up to 50 columns of key
names in the default flex_table_keys table, skipping any columns
already materialized. To materialize a specific number of columns, use
the optional parameter n_columns, described next.

HP Vertica Analytic Database (7.0.x)

Page 657 of 1539

SQL Reference Manual
SQL Functions

n-columns

[Optional ] The number of columns to materialize. The function
attempts to materialize the number of columns from the flex_table_
keys table, skipping any columns already materialized.
HP VERTICA tables support a total of 1600 columns, which is the
greatest value you can specify for n-columns. The function orders the
materialized results by frequency, descending, key_namewhen
materializing the first n columns.

keys_table_name

[Optional] The name of a flex_keys_table from which to materialize
columns. The function attempts to materialize the number of columns
(value of n-columns) from keys_table_name, skipping any columns
already materialized. The function orders the materialized results by
frequency, descending, key_namewhen materializing the first n
columns.

Examples
The following example loads a sample file of tweets (tweets_10000.json) into the flex table
twitter_r.
After loading data and computing keys for the sample flex table, the example calls materialize_
flextable_columns to materialize the first four columns:
dbt=> copy twitter_r from '/home/release/KData/tweets_10000.json' parser fjsonparser();
Rows Loaded
------------10000
(1 row)
dbt=> select compute_flextable_keys ('twitter_r');
compute_flextable_keys
--------------------------------------------------Please see public.twitter_r_keys for updated keys
(1 row)
dbt=> select materialize_flextable_columns('twitter_r', 4);
materialize_flextable_columns
------------------------------------------------------------------------------The following columns were added to the table public.twitter_r:
contributors
entities.hashtags
entities.urls
For more details, run the following query:
SELECT * FROM v_catalog.materialize_flextable_columns_results WHERE table_schema = 'publi
c' and table_name = 'twitter_r';
(1 row)

The last message in the example recommends querying the materialize_flextable_columns_
results system table for the results of materializing the columns. Following is an example of
running that query:

HP Vertica Analytic Database (7.0.x)

Page 658 of 1539

SQL Reference Manual
SQL Functions

dbt=> SELECT * FROM v_catalog.materialize_flextable_columns_results WHERE table_schema =
'public' and table_name = 'twitter_r';
table_id
| table_schema | table_name |
creation_time
|
key_name
| status |
message
-------------------+--------------+------------+------------------------------+-------------------+--------+-------------------------------------------------------45035996273733172 | public
| twitter_r | 2013-11-20 17:00:27.945484-05
| contributors
| ADDED | Added successfully
45035996273733172 | public
| twitter_r | 2013-11-20 17:00:27.94551-05
| entities.hashtags | ADDED | Added successfully
45035996273733172 | public
| entities.urls
| ADDED

| twitter_r | 2013-11-20 17:00:27.945519-05
| Added successfully

45035996273733172 | public
| twitter_r | 2013-11-20 17:00:27.945532-05
| created_at
| EXISTS | Column of same name already exists in table definition
(4 rows)

See the MATERIALIZE_FLEXTABLE_COLUMNS_RESULTS system table in the SQL Reference
Manual.

See Also
l

BUILD_FLEXTABLE_VIEW

l

COMPUTE_FLEXTABLE_KEYS

l

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

l

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW

MEASURE_LOCATION_PERFORMANCE
Measures disk performance for the location specified.

Syntax
MEASURE_LOCATION_PERFORMANCE ( 'path'

, 'node' )

Parameters
path

Specifies where the storage location to measure is mounted.

node

Is the HP Vertica node where the location to be measured is available.

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 659 of 1539

SQL Reference Manual
SQL Functions

Notes
l

To get a list of all node names on your cluster, query the V_MONITOR.DISK_STORAGE
system table:
=> SELECT node_name from DISK_STORAGE;
node_name
------------------v_vmartdb_node0004
v_vmartdb_node0004
v_vmartdb_node0005
v_vmartdb_node0005
v_vmartdb_node0006
v_vmartdb_node0006
(6 rows)

l

If you intend to create a tiered disk architecture in which projections, columns, and partitions are
stored on different disks based on predicted or measured access patterns, you need to measure
storage location performance for each location in which data is stored. You do not need to
measure storage location performance for temp data storage locations because temporary files
are stored based on available space.

l

The method of measuring storage location performance applies only to configured clusters. If
you want to measure a disk before configuring a cluster see Measuring Storage Performance.

l

Storage location performance equates to the amount of time it takes to read and write 1MB of
data from the disk. This time equates to:
IO time = Time to read/write 1MB + Time to seek = 1/Throughput + 1/Latency
Throughput is the average throughput of sequential reads/writes (units in MB per second)
Latency is for random reads only in seeks (units in seeks per second)
Note: The IO time of a faster storage location is less than a slower storage location.

Example
The following example measures the performance of a storage location on v_vmartdb_node0004:
=> SELECT MEASURE_LOCATION_PERFORMANCE('/secondVerticaStorageLocation/' , 'v_vmartdb_node
0004');
WARNING: measure_location_performance can take a long time. Please check logs for progre
ss
measure_location_performance
-------------------------------------------------Throughput : 122 MB/sec. Latency : 140 seeks/sec

HP Vertica Analytic Database (7.0.x)

Page 660 of 1539

SQL Reference Manual
SQL Functions

See Also
l

ADD_LOCATION

l

ALTER_LOCATION_USE

l

RESTORE_LOCATION

l

RETIRE_LOCATION

l

Measuring Storage Performance

MERGE_PARTITIONS
Merges ROS containers that have data belonging to partitions in a specified partition key range:
partitionKeyFromto partitionKeyTo.
Note: This function is deprecated in HP Vertica 7.0.

Syntax
MERGE_PARTITIONS ( table_name , partition_key_from , partition_key_to )

Parameters
table_name

Specifies the name of the table

partition_key_from

Specifies the start point of the partition

partition_key_to

Specifies the end point of the partition

Privileges
l

Table owner

l

USAGE privilege on schema that contains the table

Notes
l

You cannot run MERGE_PARTITIONS() on a table with data that is not reorganized. You must
reorganize the data first using ALTER_TABLE table REORGANIZE, or PARTITION_TABLE(table).

HP Vertica Analytic Database (7.0.x)

Page 661 of 1539

SQL Reference Manual
SQL Functions

l

The edge values are included in the range, and partition_key_from must be less than or equal
to partition_key_to.

l

Inclusion of partitions in the range is based on the application of less than (<)/greater than (>)
operators of the corresponding data type.
Note: No restrictions are placed on a partition key's data type.

l

If partition_key_from is the same as partition_key_to, all ROS containers of the partition
key are merged into one ROS.

Examples
=>
=>
=>
=>
=>
=>
=>
=>

SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT

MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',
MERGE_PARTITIONS('T1',

'200', '400');
'800', '800');
'CA', 'MA');
'false', 'true');
'06/06/2008', '06/07/2008');
'02:01:10', '04:20:40');
'06/06/2008 02:01:10', '06/07/2008 02:01:10');
'8 hours', '1 day 4 hours 20 seconds');

MOVE_PARTITIONS_TO_TABLE
Moves partitions from a source table to a target table. The target table must have the same
projection column definitions, segmentation, and partition expressions as the source table. If the
target table does not exist, the function creates a new table based on the source definition. The
function requires both minimum and maximum range values, indicating what partition values to
move.

Syntax
MOVE_PARTITIONS_TO_TABLE ( '[[db-name.]schema.]source_table', 'min_range_value',
'max_range_value', '[[db-name.]schema.]target_table' )

Parameters
[[db-name.]schema.]source_table

The source table (optionally qualified), from which you want to
move partitions.

min_range_value

The minimum value in the partition to move.

max_range_value

The maximum value of the partition being moved.

target_table

The table to which the partitions are being moved.

HP Vertica Analytic Database (7.0.x)

Page 662 of 1539

SQL Reference Manual
SQL Functions

Privileges
l

Table owner

l

If target table is created as part of moving partitions, the new table has the same owner as the
target. If the target table exists, user must have own the target table, and have ability to call this
function.

Example
If you call MOVE_PARTITIONS_TO_TABLE and the destination table does not exist, the function will
create the table automatically:
VMART=> SELECT MOVE_PARTITIONS_TO_TABLE (
'prod_trades',
'200801',
'200801',
'partn_backup.trades_200801');
MOVE_PARTITIONS_TO_TABLE
--------------------------------------------------------------------------1 distinct partition values moved at epoch 15. Effective move epoch: 14.
(1 row)

See Also
l

DROP_PARTITION

l

DUMP_PARTITION_KEYS

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_PROJECTION

l

Moving Partitions

l

Creating a Table Like Another

PARTITION_PROJECTION
Forces a split of ROS containers of the specified projection.

Syntax
PARTITION_PROJECTION ( '[[db-name.]schema.]projection_name' )

HP Vertica Analytic Database (7.0.x)

Page 663 of 1539

SQL Reference Manual
SQL Functions

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

projection_name

Specifies the name of the projection.

Privileges
l

Table owner

l

USAGE privilege on schema

Notes
Partitioning expressions take immutable functions only, in order that the same information be
available across all nodes.
PARTITION_PROJECTION() is similar to PARTITION_TABLE(), except that PARTITION_
PROJECTION works only on the specified projection, instead of the table.
Users must have USAGE privilege on schema that contains the table.
PARTITION_PROJECTION() purges data while partitioning ROS containers if deletes were
applied before the AHM epoch.

Example
The following command forces a split of ROS containers on the states_p_node01 projection:
=> SELECT PARTITION_PROJECTION ('states_p_node01');
partition_projection
-----------------------Projection partitioned
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 664 of 1539

SQL Reference Manual
SQL Functions

See Also
l

DO_TM_TASK

l

DROP_PARTITION

l

DUMP_PARTITION_KEYS

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_TABLE

l

Working with Table Partitions

PARTITION_TABLE
Forces the system to break up any ROS containers that contain multiple distinct values of the
partitioning expression. Only ROS containers with more than one distinct value participate in the
split.

Syntax
PARTITION_TABLE ( '[[db-name.]schema.]table_name' )

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table_name

Specifies the name of the table.

Privileges
l

Table owner

l

USAGE privilege on schema

HP Vertica Analytic Database (7.0.x)

Page 665 of 1539

SQL Reference Manual
SQL Functions

Notes
PARTITION_TABLE is similar to PARTITION_PROJECTION, except that PARTITION_TABLE
works on the specified table.
Users must have USAGE privilege on schema that contains the table.
Partitioning functions take immutable functions only, in order that the same information be
available across all nodes.

Example
The following example creates a simple table called states and partitions data by state.
=> CREATE TABLE states (year INTEGER NOT NULL,
state VARCHAR NOT NULL)
PARTITION BY state;
=> CREATE PROJECTION states_p (state, year) AS
SELECT * FROM states
ORDER BY state, year UNSEGMENTED ALL NODES;

Now call the PARTITION_TABLE function to partition table states:
=> SELECT PARTITION_TABLE('states');
PARTITION_TABLE
------------------------------------------------------partition operation for projection 'states_p_node0004'
partition operation for projection 'states_p_node0003'
partition operation for projection 'states_p_node0002'
partition operation for projection 'states_p_node0001'
(1 row)

See Also
l

DO_TM_TASK

l

DROP_PARTITION

l

DUMP_PARTITION_KEYS

l

DUMP_PROJECTION_PARTITION_KEYS

l

DUMP_TABLE_PARTITION_KEYS

l

PARTITION_PROJECTION

l

Working with Table Partitions

HP Vertica Analytic Database (7.0.x)

Page 666 of 1539

SQL Reference Manual
SQL Functions

PURGE
Permanently removes deleted data from physical storage so that the disk space can be reused.
You can purge historical data up to and including the epoch in which the Ancient History Mark is
contained.
Purges all projections in the physical schema. PURGE does not delete temporary tables.

Syntax
PURGE()

Privileges
l

Table owner

l

USAGE privilege on schema

Notes
l

PURGE() was formerly named PURGE_ALL_PROJECTIONS. HP Vertica supports both
function calls.
Caution: PURGE could temporarily take up significant disk space while the data is being
purged.

See Also
l

MERGE_PARTITIONS

l

PARTITION_TABLE

l

PURGE_PROJECTION

l

PURGE_TABLE

l

STORAGE_CONTAINERS

l

Purging Deleted Data

PURGE_PARTITION
Purges a table partition of deleted rows. Similar to PURGE() and PURGE_PROJECTION(), this function
removes deleted data from physical storage so you can reuse the disk space. PURGE_PARTITION()
removes data from the AHM epoch and earlier only.

HP Vertica Analytic Database (7.0.x)

Page 667 of 1539

SQL Reference Manual
SQL Functions

Syntax
PURGE_PARTITION ( '[[db_name.]schema_name.]table_name', partition_key )

Parameters
[[db_name.]schema_name.]

[Optional] Specifies the database name and optional schema name.
Using a database name identifies objects that are not unique within
the current search path (see Setting Search Paths). You must be
connected to the database you specify, and you cannot change
objects in other databases.
Specifying different database objects lets you qualify database
objects as explicitly as required. For example, you can use a
database and a schema name (mydb.myschema).

table_name

The name of the partitioned table

partition_key

The key of the partition to be purged of deleted rows

Privileges
l

Table owner

l

USAGE privilege on schema

Example
The following example lists the count of deleted rows for each partition in a table, then calls PURGE_
PARTITION() to purge the deleted rows from the data.
=> SELECT partition_key,table_schema,projection_name,sum(deleted_row_count)
AS deleted_row_count FROM partitions
GROUP BY partition_key,table_schema,projection_name
ORDER BY partition_key;
partition_key | table_schema | projection_name | deleted_row_count
---------------+--------------+-----------------+------------------0
| public
| t_super
|
2
1
| public
| t_super
|
2
2
| public
| t_super
|
2
3
| public
| t_super
|
2
4
| public
| t_super
|
2
5
| public
| t_super
|
2
6
| public
| t_super
|
2
7
| public
| t_super
|
2
8
| public
| t_super
|
2
9
| public
| t_super
|
1

HP Vertica Analytic Database (7.0.x)

Page 668 of 1539

SQL Reference Manual
SQL Functions

(10 rows)
=> SELECT PURGE_PARTITION('t',5); -- Purge partition with key 5.
purge_partition
-----------------------------------------------------------------------Task: merge partitions
(Table: public.t) (Projection: public.t_super)
(1 row)
=> SELECT partition_key,table_schema,projection_name,sum(deleted_row_count)
AS deleted_row_count FROM partitions
GROUP BY partition_key,table_schema,projection_name
ORDER BY partition_key;

partition_key | table_schema | projection_name | deleted_row_count
---------------+--------------+-----------------+------------------0
| public
| t_super
|
2
1
| public
| t_super
|
2
2
| public
| t_super
|
2
3
| public
| t_super
|
2
4
| public
| t_super
|
2
5
| public
| t_super
|
0
6
| public
| t_super
|
2
7
| public
| t_super
|
2
8
| public
| t_super
|
2
9
| public
| t_super
|
1
(10 rows)

See Also
l

MERGE_PARTITIONS

l

PURGE

l

PURGE_PROJECTION

l

PURGE_TABLE

l

STORAGE_CONTAINERS

PURGE_PROJECTION
Permanently removes deleted data from physical storage so that the disk space can be reused.
You can purge historical data up to and including the epoch in which the Ancient History Mark is
contained.
Purges the specified projection.
Caution: PURGE_PROJECTION could temporarily take up significant disk space while
purging the data.

HP Vertica Analytic Database (7.0.x)

Page 669 of 1539

SQL Reference Manual
SQL Functions

Syntax
PURGE_PROJECTION ( '[[db-name.]schema.]projection_name' )

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

projection_name

Identifies the projection name. When using more than one schema,
specify the schema that contains the projection, as noted above.

Privileges
l

Table owner

l

USAGE privilege on schema

Notes
See PURGE for notes about the outcome of purge operations.

See Also
l

PURGE_TABLE

l

STORAGE_CONTAINERS

l

Purging Deleted Data

PURGE_TABLE
Note: This function was formerly named PURGE_TABLE_PROJECTIONS(). HP Vertica still
supports the former function name.
Permanently removes deleted data from physical storage so that the disk space can be reused.
You can purge historical data up to and including the epoch in which the Ancient History Mark is
contained.

HP Vertica Analytic Database (7.0.x)

Page 670 of 1539

SQL Reference Manual
SQL Functions

Purges all projections of the specified table. You cannot use this function to purge temporary tables.

Syntax
PURGE_TABLE ( '[[db-name.]schema.]table_name' )

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table_name

Specifies the table to purge.

Privileges
l

Table owner

l

USAGE privilege on schema
Caution: PURGE_TABLE could temporarily take up significant disk space while the data is
being purged.

Example
The following example purges all projections for the store sales fact table located in the Vmart
schema:
=> SELECT PURGE_TABLE('store.store_sales_fact');

See Also
l

PURGE

l

PURGE_TABLE

l

STORAGE_CONTAINERS

l

Purging Deleted Data

HP Vertica Analytic Database (7.0.x)

Page 671 of 1539

SQL Reference Manual
SQL Functions

REALIGN_CONTROL_NODES
Chooses control nodes (spread hosts) from all cluster nodes and assigns the rest of the nodes in
the cluster to a control node. Calling this function respects existing fault groups, which you can
view by querying the V_CATALOG.CLUSTER_LAYOUT system table. This view also lets you see the
proposed new layout for nodes in the cluster.
Note: You use this function with other cluster management functions. For details, see Defining
and Realigning Control Nodes on an Existing Cluster in the Administrator's Guide.

Syntax
REALIGN_CONTROL_NODES()

Privileges
Must be a superuser.

Example
The following command chooses control nodes from all cluster nodes and assigns the rest of the
nodes in the cluster to a control node:
=> SELECT realign_control_nodes();

See Also
Cluster Management Functions
V_CATALOG.CLUSTER_LAYOUT
Large Cluster in the Administrator's Guide

REBALANCE_CLUSTER
Call this function to begin rebalancing data in the cluster synchronously.
A rebalance operation performs the following tasks:
l

Distributes data based on user-defined fault groups, if specified, or based on large cluster
automatic fault groups

l

Redistributes the database projections' data across all nodes

HP Vertica Analytic Database (7.0.x)

Page 672 of 1539

SQL Reference Manual
SQL Functions

l

Refreshes projections

l

Sets the Ancient History Mark

l

Drops projections that are no longer needed

When to rebalance the cluster
Rebalancing is useful (or necessary) after you:
l

Mark one or more nodes as ephemeral in preparation of removing them from the cluster

l

Add one or more nodes to the cluster so HP Vertica can populate the empty nodes with data

l

Remove one or more nodes from the cluster so HP Vertica can redistribute the data among the
remaining nodes

l

Change the scaling factor of an elastic cluster, which determines the number of storage
containers used to store a projection across the database

l

Set the control node size or realign control nodes on a large cluster layout

l

Specify more than 120 nodes in your initial HP Vertica cluster configuration

l

Add nodes to or remove nodes from a fault group

Because this function runs the rebalance task synchronously, it does not return until the data has
been rebalanced. Closing or dropping the session cancels the rebalance task.
Important: On large cluster arrangements, you typically use this function in a flow, described
Defining and Realigning Control Nodes in the Administrator's Guide. After you change the
number and distribution of control nodes (spread hosts), you must run REBALANCE_CLUSTER()
for fault tolerance to be realized.

Syntax
REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
The following command rebalances data across the cluster.

HP Vertica Analytic Database (7.0.x)

Page 673 of 1539

SQL Reference Manual
SQL Functions

=> SELECT REBALANCE_CLUSTER();
REBALANCE_CLUSTER
------------------REBALANCED
(1 row)

See Also
START_REBALANCE_CLUSTER
CANCEL_REBALANCE_CLUSTER
Rebalancing Data Across Nodes in the Administrator's Guide

REENABLE_DUPLICATE_KEY_ERROR
Restores the default behavior of error reporting by reversing the effects of DISABLE_DUPLICATE_
KEY_ERROR. Effects are session scoped.

Syntax
REENABLE_DUPLICATE_KEY_ERROR();

Privileges
Must be a superuser.

Examples
For examples and usage, see DISABLE_DUPLICATE_KEY_ERROR.

See Also
l

ANALYZE_CONSTRAINTS

REFRESH
Performs a synchronous, optionally-targeted refresh of a specified table's projections.
Information about a refresh operation—whether successful or unsuccessful—is maintained in the
PROJECTION_REFRESHES system table until either the CLEAR_PROJECTION_
REFRESHES() function is executed or the storage quota for the table is exceeded. The
PROJECTION_REFRESHES.IS_EXECUTING column returns a boolean value that indicates whether the
refresh is currently running (t) or occurred in the past (f).

HP Vertica Analytic Database (7.0.x)

Page 674 of 1539

SQL Reference Manual
SQL Functions

Syntax
REFRESH ( '[[db-name.]schema.]table_name [ , ... ]' )

Parameters
[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table_name

Specifies the name of a specific table containing the projections to be
refreshed. The REFRESH() function attempts to refresh all the tables
provided as arguments in parallel. Such calls will be part of the Database
Designer deployment (and deployment script).
When using more than one schema, specify the schema that contains the
table, as noted above.

Returns
Column Name Description
Projection Name

The name of the projection that is targeted for refresh.

Anchor Table

The name of the projection's associated anchor table.

Status

The status of the projection:
l

Queued—Indicates that a projection is queued for refresh.

l

Refreshing—Indicates that a refresh for a projection is in process.

l

Refreshed—Indicates that a refresh for a projection has successfully
completed.

l

Failed—Indicates that a refresh for a projection did not successfully
complete.

HP Vertica Analytic Database (7.0.x)

Page 675 of 1539

SQL Reference Manual
SQL Functions

Refresh Method

The method used to refresh the projection:
l

Buddy—Uses the contents of a buddy to refresh the projection. This
method maintains historical data. This enables the projection to be used for
historical queries.

l

Scratch—Refreshes the projection without using a buddy. This method
does not generate historical data. This means that the projection cannot
participate in historical queries from any point before the projection was
refreshed.

Error Count

The number of times a refresh failed for the projection.

Duration (sec)

The length of time that the projection refresh ran in seconds.

Privileges
REFRESH() works only if invoked on tables owned by the calling user.

Notes
l

Unlike START_REFRESH(), which runs in the background, REFRESH() runs in the foreground
of the caller's session.

l

The REFRESH() function refreshes only the projections in the specified table.

l

If you run REFRESH() without arguments, it refreshes all non up-to-date projections. If the
function returns a header string with no results, then no projections needed refreshing.

Examples
The following example refreshes the projections in tables t1 and t2:
=> SELECT REFRESH('t1, t2');
REFRESH
---------------------------------------------------------------------------------------Refresh completed with the following outcomes:
Projection Name: [Anchor Table] [Status] [Refresh Method] [Error Count] [Duration (sec)]
---------------------------------------------------------------------------------------"public"."t1_p": [t1] [refreshed] [scratch] [0] [0]"public"."t2_p": [t2] [refreshed] [scr
atch] [0] [0]

This next example shows that only the projection on table t was refreshed:
=> SELECT REFRESH('allow, public.deny, t');

HP Vertica Analytic Database (7.0.x)

Page 676 of 1539

SQL Reference Manual
SQL Functions

REFRESH
---------------------------------------------------------------------------------------Refresh completed with the following outcomes:
Projection Name: [Anchor Table] [Status] [Refresh Method] [Error Count] [Duration (sec)]
---------------------------------------------------------------------------------------"n/a"."n/a": [n/a] [failed: insufficient permissions on table "allow"] [] [1] [0]
"n/a"."n/a": [n/a] [failed: insufficient permissions on table "public.deny"] [] [1] [0]
"public"."t_p1": [t] [refreshed] [scratch] [0] [0]

See Also
l

CLEAR_PROJECTION_REFRESHES

l

PROJECTION_REFRESHES

l

START_REFRESH

l

Clearing PROJECTION_REFRESHES History

RELEASE_ALL_JVM_MEMORY
Forces all sessions to release the memory consumed by their Java Virtual Machines (JVM).

Syntax
RELEASE_ALL_JVM_MEMORY();

Permissions
Must be a superuser.

Example
The following example demonstrates viewing the JVM memory use in all open sessions, then
calling RELEASE_ALL_JVM_MEMORY() to release the memory:
=> select user_name,jvm_memory_kb FROM V_MONITOR.SESSIONS;
user_name | jvm_memory_kb
-----------+--------------dbadmin
|
79705
(1 row)
=> SELECT RELEASE_ALL_JVM_MEMORY();
RELEASE_ALL_JVM_MEMORY
-----------------------------------------------------------------------------

HP Vertica Analytic Database (7.0.x)

Page 677 of 1539

SQL Reference Manual
SQL Functions

Close all JVM sessions command sent. Check v_monitor.sessions for progress.
(1 row)
=> SELECT user_name,jvm_memory_kb FROM V_MONITOR.SESSIONS;
user_name | jvm_memory_kb
-----------+--------------dbadmin
|
0
(1 row)

See Also
l

RELEASE_JVM_MEMORY

RELEASE_JVM_MEMORY
Terminates a Java Virtual Machine (JVM), making available the memory the JVM was using.

Syntax
RELEASE_JVM_MEMORY();

Privileges
None.

Examples
User session opened. RECORD 2 shows the user session running COPY DIRECT statement.
=> SELECT RELEASE_JVM_MEMORY();
release_jvm_memory
----------------------------------------Java process killed and memory released
(1 row)

See Also
l

RELEASE_ALL_JVM_MEMORY

RELOAD_SPREAD
Calling this function with the required true argument updates cluster changes (such as new or realigned control nodes spread hosts or fault groups or new/dropped cluster nodes), to the catalog's
spread configuration file.

HP Vertica Analytic Database (7.0.x)

Page 678 of 1539

SQL Reference Manual
SQL Functions

Important: This function is often used in a multi-step process for large and elastic cluster
arrangements. Calling RELOAD_SPREAD(true) might require that you restart the database,
which you do using the Administration Tools. You must then rebalance the cluster for fault
tolerance to be realized. See Defining and Realigning Control Nodes in the Administrator's
Guide for more information.

Syntax
RELOAD_SPREAD(true)

Parameters
true

Updates cluster changes related to control
message responsibilities to the spread
configuration file.

Privileges
Must be a superuser.

Example
The following command updates the cluster with changes to control messaging:
=> SELECT reload_spread(true);
reload_spread
--------------reloaded
(1 row)

See Also
Cluster Management Functions
REBALANCE_CLUSTER
V_CATALOG.CLUSTER_LAYOUT
Large Cluster in the Administrator's Guide

HP Vertica Analytic Database (7.0.x)

Page 679 of 1539

SQL Reference Manual
SQL Functions

RESET_LOAD_BALANCE_POLICY
Resets the counter each host in the cluster maintains to track which host it will refer a client to
when the native connection load balancing scheme is set to ROUNDROBIN.

Syntax
RESET_LOAD_BALANCE_POLICY()

Notes
This function only has an effect if the current native connection load balancing scheme is
ROUNDROBIN.

Permissions
This function can be called only by a superuser .

Example
The following example demonstrates calling RESET_LOAD_BALANCE_POLICY:
=> SELECT RESET_LOAD_BALANCE_POLICY();
RESET_LOAD_BALANCE_POLICY
------------------------------------------------------------------------Successfully reset stateful client load balance policies: "roundrobin".
(1 row)

RESTORE_LOCATION
Restores a storage location that was previously retired with RETIRE_LOCATION.

Syntax
RESTORE_LOCATION ( 'path', 'node' )

Parameters
path

Specifies where the retired storage location is mounted.

node

Is the HP Vertica node where the retired location is available.

HP Vertica Analytic Database (7.0.x)

Page 680 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Effects of Restoring a Previously Retired Location
After restoring a storage location, HP Vertica re-ranks all of the cluster storage locations and uses
the newly-restored location to process queries as determined by its rank.

Monitoring Storage Locations
Disk storage information that the database uses on each node is available in the V_
MONITOR.DISK_STORAGE system table.

Example
The following example restores the retired storage location on node3:
=> SELECT RESTORE_LOCATION ('/thirdHP VerticaStorageLocation/' , 'v_vmartdb_node0004');

See Also
l

Altering Storage Location Use

l

ADD_LOCATION

l

ALTER_LOCATION_USE

l

DROP_LOCATION

l

RETIRE_LOCATION

l

GRANT (Storage Location)

l

REVOKE (Storage Location)

RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_
VIEW
Restores the _keys table and the _view, linking them with their associated flex table if either is
dropped. This function notes whether it restores one or both.

HP Vertica Analytic Database (7.0.x)

Page 681 of 1539

SQL Reference Manual
SQL Functions

Usage
restore_flextable_default_keys_table_and_view('flex_table')

Arguments
flex_table The name of the flex table .

Examples
This example invokes the function with an existing flex table, restoring both the _keys table and _
view:
kdb=> select restore_flextable_default_keys_table_and_view('darkdata');
restore_flextable_default_keys_table_and_view
---------------------------------------------------------------------------------The keys table public.darkdata_keys was restored successfully.
The view public.darkdata_view was restored successfully.
(1 row)

This example shows the function restoring darkdata_view, but noting that darkdata_keys does
not need restoring:
kdb=> select restore_flextable_default_keys_table_and_view('darkdata');
restore_flextable_default_keys_table_and_view
-----------------------------------------------------------------------------------------------The keys table public.darkdata_keys already exists and is linked to darkdata.
The view public.darkdata_view was restored successfully.
(1 row)

The _keys table has no content after it is restored:
kdb=> select * from darkdata_keys;
key_name | frequency | data_type_guess
----------+-----------+----------------(0 rows)

See Also
l

BUILD_FLEXTABLE_VIEW

l

COMPUTE_FLEXTABLE_KEYS

HP Vertica Analytic Database (7.0.x)

Page 682 of 1539

SQL Reference Manual
SQL Functions

l

COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW

l

MATERIALIZE_FLEXTABLE_COLUMNS

RETIRE_LOCATION
Makes the specified storage location inactive.

Syntax
RETIRE_LOCATION ( 'path', 'node' )

Parameters
path

Specifies where the storage location to retire is mounted.

node

Is the HP Vertica node where the location is available.

Privileges
Must be a superuser.

Effects of Retiring a Storage Location
When you use this function, HP Vertica checks that the location is not the only storage for data and
temp files. At least one location must exist on each node to store data and temp files, though you
can store both sorts of files in either the same location, or separate locations.
Note: You cannot retire a location if it is used in a storage policy, and is the last available
storage for its associated objects.
When you retire a storage location:
l

No new data is stored at the retired location, unless you first restore it with the RESTORE_
LOCATION() function.

l

If the storage location being retired contains stored data, the data is not moved, so you cannot
drop the storage location. Instead, HP Vertica removes the stored data through one or more
mergeouts.

l

If the storage location being retired was used only for temp files, you can drop the location. See
Dropping Storage Locations in the Administrators Guide and the DROP_LOCATION() function.

HP Vertica Analytic Database (7.0.x)

Page 683 of 1539

SQL Reference Manual
SQL Functions

Monitoring Storage Locations
Disk storage information that the database uses on each node is available in the V_
MONITOR.DISK_STORAGE system table.

Example
The following example retires a storage location:
=> SELECT RETIRE_LOCATION ('/secondVerticaStorageLocation/' , 'v_vmartdb_node0004');

See Also
l

Retiring Storage Locations

l

ADD_LOCATION

l

ALTER_LOCATION_USE

l

DROP_LOCATION

l

RESTORE_LOCATION

l

GRANT (Storage Location)

l

REVOKE (Storage Location)

SET_AHM_EPOCH
Sets the Ancient History Mark (AHM) to the specified epoch. This function allows deleted data up
to and including the AHM epoch to be purged from physical storage.
SET_AHM_EPOCH is normally used for testing purposes. Consider SET_AHM_TIME instead,
which is easier to use.

Syntax
SET_AHM_EPOCH ( epoch, [ true ] )

HP Vertica Analytic Database (7.0.x)

Page 684 of 1539

SQL Reference Manual
SQL Functions

Parameters
epoch

true

Specifies one of the following:
l

The number of the epoch in which to set the AHM

l

Zero (0) (the default) disables PURGE

Optionally allows the AHM to advance when nodes are down.
Note: If the AHM is advanced after the last good epoch of the failed nodes, those
nodes must recover all data from scratch. Use with care.

Privileges
Must be a superuser.

Notes
If you use SET_AHM_EPOCH , the number of the specified epoch must be:
l

Greater than the current AHM epoch

l

Less than the current epoch

l

Less than or equal to the cluster last good epoch (the minimum of the last good epochs of the
individual nodes in the cluster)

l

Less than or equal to the cluster refresh epoch (the minimum of the refresh epochs of the
individual nodes in the cluster)

Use the SYSTEM table to see current values of various epochs related to the AHM; for example:
=> SELECT * from SYSTEM;
-[ RECORD 1 ]------------+--------------------------current_timestamp
| 2009-08-11 17:09:54.651413
current_epoch
| 1512
ahm_epoch
| 961
last_good_epoch
| 1510
refresh_epoch
| -1
designed_fault_tolerance | 1
node_count
| 4
node_down_count
| 0
current_fault_tolerance | 1
catalog_revision_number | 1590
wos_used_bytes
| 0
wos_row_count
| 0

HP Vertica Analytic Database (7.0.x)

Page 685 of 1539

SQL Reference Manual
SQL Functions

ros_used_bytes
ros_row_count
total_used_bytes
total_row_count

|
|
|
|

41490783
1298104
41490783
1298104

All nodes must be up. You cannot use SET_AHM_EPOCH when any node in the cluster is down,
except by using the optional true parameter.
When a node is down and you issue SELECT MAKE_AHM_NOW(), the following error is printed to the
vertica.log:
Some nodes were excluded from setAHM. If their LGE is before the AHM they will perform fu
ll recovery.

Examples
The following command sets the AHM to a specified epoch of 12:
=> SELECT SET_AHM_EPOCH(12);

The following command sets the AHM to a specified epoch of 2 and allows the AHM to advance
despite a failed node:
=> SELECT SET_AHM_EPOCH(2, true);

See Also
l

MAKE_AHM_NOW

l

SET_AHM_TIME

l

SYSTEM

SET_AHM_TIME
Sets the Ancient History Mark (AHM) to the epoch corresponding to the specified time on the
initiator node. This function allows historical data up to and including the AHM epoch to be purged
from physical storage.

Syntax
SET_AHM_TIME ( time , [ true ] )

HP Vertica Analytic Database (7.0.x)

Page 686 of 1539

SQL Reference Manual
SQL Functions

Parameters
time

Is a TIMESTAMP value that is automatically converted to the appropriate epoch number.

true

[Optional] Allows the AHM to advance when nodes are down.
Note: If the AHM is advanced after the last good epoch of the failed nodes, those nodes
must recover all data from scratch.

Privileges
Must be a superuser.

Notes
l

SET_AHM_TIME returns a TIMESTAMP WITH TIME ZONE value representing the end point of
the AHM epoch.

l

You cannot change the AHM when any node in the cluster is down, except by using the optional
true parameter.

l

When a node is down and you issue SELECT MAKE_AHM_NOW(), the following error is printed to
the vertica.log:
Some nodes were excluded from setAHM. If their LGE is before the AHM they will perform
full recovery.

Examples
Epochs depend on a configured epoch advancement interval. If an epoch includes a three-minute
range of time, the purge operation is accurate only to within minus three minutes of the specified
timestamp:
=> SELECT SET_AHM_TIME('2008-02-27 18:13');
set_ahm_time
-----------------------------------AHM set to '2008-02-27 18:11:50-05'
(1 row)

Note: The –05 part of the output string is a time zone value, an offset in hours from UTC
(Universal Coordinated Time, traditionally known as Greenwich Mean Time, or GMT).
In the previous example, the actual AHM epoch ends at 18:11:50, roughly one minute before the
specified timestamp. This is because SET_AHM_TIME selects the epoch that ends at or before

HP Vertica Analytic Database (7.0.x)

Page 687 of 1539

SQL Reference Manual
SQL Functions

the specified timestamp. It does not select the epoch that ends after the specified timestamp
because that would purge data deleted as much as three minutes after the AHM.
For example, using only hours and minutes, suppose that epoch 9000 runs from 08:50 to 11:50 and
epoch 9001 runs from 11:50 to 15:50. SET_AHM_TIME('11:51') chooses epoch 9000 because it
ends roughly one minute before the specified timestamp.
In the next example, if given an environment variable set as date =`date`; the following
command fails if a node is down:
=> SELECT SET_AHM_TIME('$date');

In order to force the AHM to advance, issue the following command instead:
=> SELECT SET_AHM_TIME('$date', true);

See Also
l

MAKE_AHM_NOW

l

SET_AHM_EPOCH

l

SET DATESTYLE

l

TIMESTAMP

SET_AUDIT_TIME
Sets the time that HP Vertica performs automatic database size audit to determine if the size of the
database is compliant with the raw data allowance in your HP Vertica license. Use this function if
the audits are currently scheduled to occur during your database's peak activity time. This is
normally not a concern, since the automatic audit has little impact on database performance.
Audits are scheduled by the preceding audit, so changing the audit time does not affect the next
scheduled audit. For example, if your next audit is scheduled to take place at 11:59PM and you use
SET_AUDIT_TIME to change the audit schedule 3AM, the previously scheduled 11:59PM audit
still runs. As that audit finishes, it schedules the next audit to occur at 3AM.
If you want to prevent the next scheduled audit from running at its scheduled time, you can change
the scheduled time using SET_AUDIT_TIME then manually trigger an audit to run immediately
using AUDIT_LICENSE_SIZE. As the manually-triggered audit finishes, it schedules the next audit
to occur at the time you set using SET_AUDIT_TIME (effectively overriding the previously
scheduled audit).

Syntax
SET_AUDIT_TIME(time)
time

A string containing the time in 'HH:MM AM/PM' format (for example, '1:00 AM') when the
audit should run daily.

HP Vertica Analytic Database (7.0.x)

Page 688 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Example
=> SELECT SET_AUDIT_TIME('3:00 AM');
SET_AUDIT_TIME
----------------------------------------------------------------------The scheduled audit time will be set to 3:00 AM after the next audit.
(1 row)

SET_CONTROL_SET_SIZE
For existing database clusters, use this function to specify the number of cluster nodes on which
you want to deploy control messaging (spread). The SET_CONTROL_SET_SIZE() function works the
same as the install_vertica --large cluster  option.
You can run SET_CONTROL_SET_SIZE()after the database cluster is already defined, but before you
call this function, the database must be up.
Note: You use this function with other cluster management functions. For details, see Defining
and Realigning Control Nodes on an Existing Cluster in the Administrator's Guide.

Syntax
SET_CONTROL_SET_SIZE(integer)

Parameters
integer

Specifies the number of cluster hosts from the
database cluster on which spread runs.

Privileges
Must be a superuser.

Note
To see if the current spread hosts and the control designations in the Catalog match, query the V_
CATALOG.LARGE_CLUSTER_CONFIGURATION_STATUS system table.

HP Vertica Analytic Database (7.0.x)

Page 689 of 1539

SQL Reference Manual
SQL Functions

Example
The following command tells HP Vertica that you want to run spread on two cluster nodes:
=> SELECT set_control_set_size(2);
SET_CONTROL_SET_SIZE
---------------------Control size set
(1 row)

See Also
Cluster Management Functions
V_CATALOG.CLUSTER_LAYOUT
Large Cluster in the Administrator's Guide

SET_DATA_COLLECTOR_POLICY
Sets a size restraint (memory and disk space in kilobytes) for the specified Data Collector table on
all nodes. If nodes are down, the failed nodes receive the setting when they rejoin the cluster.
You can use this function to set a size restraint only, or you can include the optional interval
argument to set disk capacity for both size and time in a single command.
If you specify interval, HP Vertica enforces the setting that is exceeded first (size or time).
Before you include a time restraint, be sure the disk size capacity is sufficiently large.
If you want to specify just a time restraint, or you want to turn off a time restraint you set using this
function, see SET_DATA_COLLECTOR_TIME_POLICY().

Syntax
SET_DATA_COLLECTOR_POLICY('component', 'memoryKB', 'diskKB' [,'interval']

)

Parameters
component

Configures the retention policy for the specified component.

memoryKB

Specifies the memory size to retain in kilobytes.

diskKB

Specifies the disk size in kilobytes.

HP Vertica Analytic Database (7.0.x)

Page 690 of 1539

SQL Reference Manual
SQL Functions

interval

[Default off] Takes an optional interval argument to specify how long to retain the
specified component on disk. To disable a time restraint, set interval to -1.
Note: Any negative input will turn off the time restraint

Privileges
Must be a superuser.

Notes
l

Before you change a retention policy, view its current setting by calling the GET_DATA_
COLLECTOR_POLICY() function.

l

If you don't know the name of a component, query the V_MONITOR.DATA_COLLECTOR system
table for a list; for example:
=> SELECT DISTINCT component, description FROM data_collector
ORDER BY 1 ASC;

Examples
The following command returns the retention policy for the ResourceAcquisitions component:
=> SELECT get_data_collector_policy('ResourceAcquisitions');
get_data_collector_policy
---------------------------------------------1000KB kept in memory, 10000KB kept on disk.
(1 row)

This command changes the memory and disk setting for ResourceAcquisitions from its current
setting of 1,000 KB memory and 10,000 KB disk space to 1500 KB and 25000 KB, respectively:
=> SELECT set_data_collector_policy('ResourceAcquisitions', '1500', '25000');
set_data_collector_policy
--------------------------SET
(1 row)

This command sets the RequestsIssued component to 1500 KB memory and 11000 KB on disk,
and includes a 3-minute time restraint:
=> SELECT set_data_collector_policy('RequestsIssued', '1500', '11000', '3 minutes'::inter
val);
set_data_collector_policy

HP Vertica Analytic Database (7.0.x)

Page 691 of 1539

SQL Reference Manual
SQL Functions

--------------------------SET
(1 row)

The following command disables the 3-minute retention policy for the RequestsIssued component:
=> SELECT set_data_collector_policy('RequestsIssued', '-1');
set_data_collector_policy
--------------------------SET
(1 row)

See Also
l

GET_DATA_COLLECTOR_POLICY

l

SET_DATA_COLLECTOR_TIME_POLICY()

l

DATA_COLLECTOR

l

Retaining Monitoring Information in the Administrator's Guide

SET_DATA_COLLECTOR_TIME_POLICY
Sets a time capacity for individual Data Collector tables on all nodes. If nodes are down, the failed
nodes receive the setting when they rejoin the cluster.
If you want to configure both time and size restraints at the same time, see SET_DATA_COLLECTOR_
POLICY().

Syntax
SET_DATA_COLLECTOR_TIME_POLICY( ['component',] 'interval' )

Parameters
component

[Optional] Configures the time retention policy for the specified component. If you
omit the component argument, HP Vertica sets the specified time capacity for all
Data Collector tables.

interval

Specifies the time restraint on disk using an INTERVAL type. To disable a time
restraint, set interval to -1.
Note: Any negative input turns off the time restraint

HP Vertica Analytic Database (7.0.x)

Page 692 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Notes
l

Before you change a retention policy, view its current setting by calling the GET_DATA_
COLLECTOR_POLICY() function.

l

If you don't know the name of a component, query the V_MONITOR.DATA_COLLECTOR system
table for a list. For example:
=> SELECT DISTINCT component, description FROM data_collector
ORDER BY 1 ASC;

Setting time interval for system tables
You can also use the interval argument to query system tables the same way you query Data
Collector tables; for example:
set_data_collector_time_policy('', <'interval'>);

To illustrate, the following command in the left column is equivalent to running the series of
commands on the right:
Run one command

Instead of a series of commands

SELECT set_data_collector_time_policy
('v_monitor.query_requests',
'3 minutes'::interval);

SELECT set_data_collector_time_policy
('RequestsIssued',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('RequestsCompleted',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('Errors',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('ResourceAcquisitions',
'3 minutes'::interval);

The SET_DATA_COLLECTOR_TIME_POLICY() function updates the time capacity for all Data
Collector tables in the V_MONITOR.QUERY_REQUESTS view. The new setting overrides any previous
settings for every Data Collector table in that view.

HP Vertica Analytic Database (7.0.x)

Page 693 of 1539

SQL Reference Manual
SQL Functions

Examples
The following command configures the Backups component to be retained on disk for 1 day:
=> SELECT set_data_collector_time_policy('Backups', '1 day'::interval);
set_data_collector_time_policy
-------------------------------SET
(1 row)

This command disables the 1-day restraint for the Backups component:
=> SELECT set_data_collector_time_policy('Backups', '-1');
set_data_collector_time_policy
-------------------------------SET
(1 row)

This command sets a 30-minute time capacity for all Data Collector tables in a single command:
=> SELECT set_data_collector_time_policy('30 minutes'::interval);
set_data_collector_time_policy
-------------------------------SET
(1 row)

To view current retention policy settings for each Data Collector table, call the GET_DATA_
COLLECTION_POLICY() function. In the next example, the time restraint is included.
=> SELECT get_data_collector_policy('RequestsIssued');
get_data_collector_policy
----------------------------------------------------------------------------2000KB kept in memory, 50000KB kept on disk. 2 years 3 days 15:08 hours kept
on disk.
(1 row)

If the time policy setting is disabled, the output of GET_DATA_COLLECTION_POLICY() returns "Time
based retention disabled."
2000KB kept in memory, 50000KB kept on disk. Time based retention disabled.

See Also
l

GET_DATA_COLLECTOR_POLICY

l

SET_DATA_COLLECTOR_POLICY

HP Vertica Analytic Database (7.0.x)

Page 694 of 1539

SQL Reference Manual
SQL Functions

l

DATA_COLLECTOR

SET_LOAD_BALANCE_POLICY
Sets how native connection load balancing chooses a host to handle a client connection. See About
Native Connection Load Balancing in the Administrator's Guide for more information.

Syntax
SET_LOAD_BALANCE_POLICY('policy')

Parameters
policy

The name of the load balancing policy to use. Can be one of the following:
l

NONE: Disables native connection load balancing. This is the default setting.

l

ROUNDROBIN: Chooses the next host from a circular list of currently up hosts in
the database (i.e. node #1, node #2, node #3, etc. until it wraps back to node #1
again). Each host in the cluster maintains its own pointer to the next host in the
circular list, rather than there being a single cluster-wide state.

l

RANDOM: Chooses a host at random from the list of currently up hosts in the
cluster.

Notes
Even if the load balancing policy is set to something other than NONE on the server, clients must
indicate they want their connections to be load balanced by setting a connection property.

Permissions
Can only be used by a superuser .

Example
The following example demonstrates enabling native connection load balancing on the server by
setting the load balancing scheme to ROUNDROBIN:
=> SELECT SET_LOAD_BALANCE_POLICY('ROUNDROBIN');
SET_LOAD_BALANCE_POLICY
-------------------------------------------------------------------------------Successfully changed the client initiator load balancing policy to: roundrobin
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 695 of 1539

SQL Reference Manual
SQL Functions

SET_LOCATION_PERFORMANCE
Sets disk performance for the location specified.

Syntax
SET_LOCATION_PERFORMANCE ( 'path' , 'node' , 'throughput' , 'average_latency' )

Parameters
path

Specifies where the storage location to set is mounted.

node

Is the HP Vertica node where the location to be set is available.
If this parameter is omitted, node defaults to the initiator.

throughput

Specifies the throughput for the location, which must be 1 or more.

average_latency

Specifies the average latency for the location. The average_latency must be 1
or more.

Privileges
Must be a superuser.

Notes
To obtain the throughput and average latency for the location, run the MEASURE_LOCATION_
PERFORMANCE() function before you attempt to set the location's performance.

Example
The following example sets the performance of a storage location on node2 to a throughput of 122
megabytes per second and a latency of 140 seeks per second.
=> SELECT SET_LOCATION_PERFORMANCE('/secondVerticaStorageLocation/','node2','122','140');

See Also
l

ADD_LOCATION

l

MEASURE_LOCATION_PERFORMANCE

HP Vertica Analytic Database (7.0.x)

Page 696 of 1539

SQL Reference Manual
SQL Functions

l

Measuring Storage Performance

l

Setting Storage Performance

SET_SCALING_FACTOR
Sets the scaling factor that determines the size of the storage containers used when rebalancing
the database and when using local data segmentation is enabled. See Cluster Scaling for details.

Syntax
SET_SCALING_FACTOR(factor)

Parameters
factor

An integer value between 1 and 32. HP Vertica uses this value to calculate the number
of storage containers each projection is broken into when rebalancing or when local data
segmentation is enabled.

Note: Setting the scaling factor value too high can cause nodes to create too many small
container files, greatly reducing efficiency and potentially causing a "Too many
ROS containers" error (also known as "ROS pushback"). The scaling factor should be set high
enough so that rebalance can transfer local segments to satisfy the skew threshold, but small
enough that the number of storage containers does not exceed ROS pushback. The number of
storage containers should be greater than or equal to the number of partitions multiplied by the
number local of segments (# storage containers >= # partitions * # local segments).

Privileges
Must be a superuser.

Example
=> SELECT SET_SCALING_FACTOR(12);
SET_SCALING_FACTOR
-------------------SET
(1 row)

SET_OBJECT_STORAGE_POLICY
Creates or changes an object storage policy by associating a database object with a labeled
storage location.

HP Vertica Analytic Database (7.0.x)

Page 697 of 1539

SQL Reference Manual
SQL Functions

Note: You cannot create a storage policy on a USER type storage location.

Syntax
SET_OBJECT_STORAGE_POLICY ( 'object_name', 'location_label' [, 'key_min, key_max'] [, 'enforc
e_storage_move' ] )

Parameters
object_name

Identifies the database object assigned to a labeled storage location.
The object_name can resolve to a database, schema, or table.

location_label

The label of the storage location with which object_name is being
associated.

key_min, key_max

Applicable only when object_name is a table, key_min and key_max
specify the table partition key value range to be stored at the location.

enforce_storage_move=
{true | false}

[Optional] Applicable only when setting a storage policy for an object
that has data stored at another labeled location. Specify this parameter
as true to move all existing storage data to the target location within this
function's transaction.

Privileges
Must be the object owner to set the storage policy, and have access to the storage location.

New Storage Policy
If an object does not have a storage policy, this function creates a new policy. The labeled location
is then used as the default storage location during TM operations, such as moveout and mergeout.

Existing Storage Policy
If the object already has an active storage policy, calling this function changes the default storage
for the object to the new labeled location. Any existing data stored on the previous storage location
is marked to move to the new location during the next TM moveout operations, unless you use the
enforce_storage_move option.

Forcing Existing Data Storage to a New Storage Location
You can optionally use this function to move existing data storage to a new location as part of
completing the current transaction, by specifying the last parameter as true.

HP Vertica Analytic Database (7.0.x)

Page 698 of 1539

SQL Reference Manual
SQL Functions

To move existing data as part of the next TM moveout, either omit the parameter, or specify its
value as false.
Note: Specifying the parameter as true performs a cluster-wide operation. If an error occurs
on any node, the function displays a warning message, skips the offending node, and
continues execution on the remaining nodes.

Example
This example sets a storage policy for the table states to use the storage labeled SSD as its default
location:
VMART=> select set_object_storage_policy ('states', 'SSD');
set_object_storage_policy
----------------------------------Default storage policy set.
(1 row)

See Also
l

ALTER_LOCATION_LABEL

l

CLEAR_OBJECT_STORAGE_POLICY

l

Creating Storage Policies

l

Moving Data Storage Locations

SHUTDOWN
Forces a database to shut down, even if there are users connected.

Syntax
SHUTDOWN ( [ 'false' | 'true' ] )

Parameters
false

[Default] Returns a message if users are connected. Has the same effect as supplying
no parameters.

true

Performs a moveout operation and forces the database to shut down, disallowing further
connections.

HP Vertica Analytic Database (7.0.x)

Page 699 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Notes
l

Quotes around the true or false arguments are optional.

l

Issuing the shutdown command without arguments or with the default (false) argument returns a
message if users are connected, and the shutdown fails. If no users are connected, the
database performs a moveout operation and shuts down.

l

Issuing the SHUTDOWN('true') command forces the database to shut down whether users are
connected or not.

l

You can check the status of the shutdown operation in the vertica.log file:
2010-03-09 16:51:52.625 unknown:0x7fc6d6d2e700
[Init]  Shutdown complete. Exiting.

l

As an alternative to SHUTDOWN(), you can also temporarily set MaxClientSessions to 0 and
then use CLOSE_ALL_SESSIONS(). New client connections cannot connect unless they
connect using the dbadmin account. See CLOSE_ALL_SESSIONS for details.

Examples
The following command attempts to shut down the database. Because users are connected, the
command fails:
=> SELECT SHUTDOWN('false');
NOTICE: Cannot shut down while users are connected
SHUTDOWN
----------------------------Shutdown: aborting shutdown
(1 row)

SHUTDOWN() and SHUTDOWN('false') perform the same operation:
=> SELECT SHUTDOWN();
NOTICE: Cannot shut down while users are connected
SHUTDOWN
----------------------------Shutdown: aborting shutdown
(1 row)

Using the 'true' parameter forces the database to shut down, even though clients might be
connected:

HP Vertica Analytic Database (7.0.x)

Page 700 of 1539

SQL Reference Manual
SQL Functions

=> SELECT SHUTDOWN('true');
SHUTDOWN
---------------------------Shutdown: moveout complete
(1 row)

See Also
l

SESSIONS

SLEEP
Waits a specified number of seconds before executing another statement or command.

Syntax
SLEEP( seconds )

Parameters
seconds

The wait time, specified in one or more seconds (0 or higher) expressed as a positive
integer. Single quotes are optional; for example, SLEEP(3) is the same as SLEEP
('3').

Notes
l

This function returns value 0 when successful; otherwise it returns an error message due to
syntax errors.

l

You cannot cancel a sleep operation.

l

Be cautious when using SLEEP() in an environment with shared resources, such as in
combination with transactions that take exclusive locks.

Example
The following command suspends execution for 100 seconds:
=> SELECT SLEEP(100);
sleep
------0
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 701 of 1539

SQL Reference Manual
SQL Functions

START_REBALANCE_CLUSTER
A rebalance operation performs the following tasks:
l

Distributes data based on user-defined fault groups, if specified, or based on large cluster
automatic fault groups

l

Redistributes the database projections' data across all nodes

l

Refreshes projections

l

Sets the Ancient History Mark

l

Drops projections that are no longer needed

When to rebalance the cluster
Rebalancing is useful (or necessary) after you:
l

Mark one or more nodes as ephemeral in preparation of removing them from the cluster

l

Add one or more nodes to the cluster so HP Vertica can populate the empty nodes with data

l

Remove one or more nodes from the cluster so HP Vertica can redistribute the data among the
remaining nodes

l

Change the scaling factor of an elastic cluster, which determines the number of storage
containers used to store a projection across the database

l

Set the control node size or realign control nodes on a large cluster layout

l

Specify more than 120 nodes in your initial HP Vertica cluster configuration

l

Add nodes to or remove nodes from a fault group

Asynchronously starts a data rebalance task. Since this function starts the rebalance task in the
background, it returns immediately after the task has started. Since it is a background task,
rebalancing will continue even if the session that started it is closed. It even continues after a
cluster recovery if the database shuts down while it is in progress. The only way to stop the task is
by the CANCEL_REBALANCE_CLUSTER function.

Syntax
START_REBALANCE_CLUSTER()

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 702 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT START_REBALANCE_CLUSTER();
START_REBALANCE_CLUSTER
------------------------REBALANCING
(1 row)

See Also
l

Rebalancing Data Across Nodes

l

CANCEL_REBALANCE_CLUSTER

l

REBALANCE_CLUSTER

START_REFRESH
Transfers data to projections that are not able to participate in query execution due to missing or
out-of-date data.

Syntax
START_REFRESH()

Notes
l

When a design is deployed through the Database Designer, it is automatically refreshed. See
Deploying a Design in the Administrator's Guide.

l

All nodes must be up in order to start a refresh.

l

START_REFRESH() has no effect if a refresh is already running.

l

A refresh is run asynchronously.

l

Shutting down the database ends the refresh.

l

To view the progress of the refresh, see the PROJECTION_REFRESHES and
PROJECTIONS system tables.

l

If a projection is updated from scratch, the data stored in the projection represents the table
columns as of the epoch in which the refresh commits. As a result, the query optimizer might not
choose the new projection for AT EPOCH queries that request historical data at epochs older

HP Vertica Analytic Database (7.0.x)

Page 703 of 1539

SQL Reference Manual
SQL Functions

than the refresh epoch of the projection. Projections refreshed from buddies retain history and
can be used to answer historical queries.

Privileges
None

Example
The following command starts the refresh operation:
=> SELECT START_REFRESH();
start_refresh
---------------------------------------Starting refresh background process.

See Also
l

CLEAR_PROJECTION_REFRESHES

l

MARK_DESIGN_KSAFE

l

PROJECTION_REFRESHES

l

PROJECTIONS

l

Clearing PROJECTION_REFRESHES History

SYNCH_WITH_HCATALOG_SCHEMA
Copies the structure of a Hive database schema available through the HCatalog Connector to an
Vertica Analytic Database schema.

Syntax
SYNC_WITH_HCATALOG_SCHEMA( local_schema, hcatalog_schema, [drop_tables] )

Parameters
local_schema The existing Vertica Analytic Database schema to store the copied HCatalog
schema's metadata

HP Vertica Analytic Database (7.0.x)

Page 704 of 1539

SQL Reference Manual
SQL Functions

hcatalog_
schema

The HCatalog schema to copy

[drop_
tables]

Drop any tables in local_schema that do not correspond to a table in hcatalog_
schema

Notes
You should always create an empty schema for the local_schema parameter. Tables in the
hcatalog_schema overwrite any identically named table in local_schema, which can lead to data
loss.

Permissions
The user must have CREATE privileges on local_schema and USAGE permissions on hcatalog_
schema.

Example
The following example shows using SYNCH_WITH_HCATALOG_SCHEMA to copy the metadata
from an HCatalog schema named hcat to an Vertica Analytic Database schema named hcat_local:
=> CREATE SCHEMA hcat_local;
CREATE SCHEMA
=> SELECT sync_with_hcatalog_schema('hcat_local', 'hcat');
sync_with_hcatalog_schema
---------------------------------------Schema hcat_local synchronized with hcat
tables in hcat = 56
tables altered in hcat_local = 0
tables created in hcat_local = 56
stale tables in hcat_local = 0
table changes erred in hcat_local = 0
(1 row)
=> -- Use vsql's \d command to describe a table in the synced schema
=> \d hcat_local.messages
List of Fields by Tables
Schema
|
Table | Column |
Type
| Size | Default | Not Null | Primary K
ey | Foreign Key
-----------+----------+---------+----------------+-------+---------+----------+------------+------------hcat_local | messages | id
| int
|
8 |
| f
| f
|
hcat_local | messages | userid | varchar(65000) | 65000 |
| f
| f
|
hcat_local | messages | "time" | varchar(65000) | 65000 |
| f
| f
|
hcat_local | messages | message | varchar(65000) | 65000 |
| f
| f

HP Vertica Analytic Database (7.0.x)

Page 705 of 1539

SQL Reference Manual
SQL Functions

|
(4 rows)

HP Vertica Analytic Database (7.0.x)

Page 706 of 1539

SQL Reference Manual
SQL Functions

Catalog Management Functions
This section contains catalog management functions specific to HP Vertica.

DROP_LICENSE
Drops a Flex Zone license key from the global catalog.

Syntax
DROP_LICENSE( 'license name' )

Parameters
license name

The name of the license to drop. The name can be found in the licenses table.

Privileges
Must be a superuser.

Notes
For more information about license keys, see Managing Licenses in the Administrator's Guide.

Examples
=> SELECT DROP_LICENSE('/tmp/vlicense.dat');

DUMP_CATALOG
Returns an internal representation of the HP Vertica catalog. This function is used for diagnostic
purposes.

Syntax
DUMP_CATALOG()

Privileges
None; however, function dumps only the objects visible to the user.

HP Vertica Analytic Database (7.0.x)

Page 707 of 1539

SQL Reference Manual
SQL Functions

Notes
To obtain an internal representation of the HP Vertica catalog for diagnosis, run the query:
=> SELECT DUMP_CATALOG();

The output is written to the specified file:
\o /tmp/catalog.txtSELECT DUMP_CATALOG();
\o

EXPORT_CATALOG
Generates a SQL script that you can use to recreate a physical schema design in its current state
on a different cluster. This function always attempts to recreate projection statements with KSAFE
clauses, if they exist in the original definitions, or OFFSET clauses if they do not.

Syntax
EXPORT_CATALOG ( [ 'destination' ] , [ 'scope' ] )

Parameters
destination

Specifies the path and name of the SQL output file. An empty string (''), which is
the default, outputs the script to standard output. The function writes the script to
the catalog directory if no destination is specified.
If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents.

scope

Determines what to export:
l

DESIGN—Exports schemas, tables, constraints, views, and projections to
which the user has access. This is the default value.

l

DESIGN_ALL—Exports all the design objects plus system objects created in
Database Designer (for example, design contexts and their tables). The objects
that are exported are those to which the user has access.

l

TABLES—Exports all tables, constraints, and projections for for which the user
has permissions. See also EXPORT_TABLES.

Privileges
None. However:

HP Vertica Analytic Database (7.0.x)

Page 708 of 1539

SQL Reference Manual
SQL Functions

l

EXPORT_CATALOG exports only the objects visible to the user .

l

Only a superuser can export output to a file.

Example
The following example exports the design to standard output:
=> SELECT EXPORT_CATALOG('','DESIGN');

See Also
EXPORT_OBJECTS

l

EXPORT_TABLES

l
l

EXPORT_OBJECTS
Generates a SQL script you can use to recreate catalog objects on a different cluster. The
generated script includes only the non-virtual objects to which the user has access. The function
exports catalog objects in order dependency for correct recreation. Running the generated SQL
script on another cluster then creates all referenced objects before their dependent objects.
The EXPORT_OBJECTS function always attempts to recreate projection statements with KSAFE
clauses, if they existed in the original definitions, or OFFSET clauses, if they did not.
None of the EXPORT_OBJECTS parameters accepts a NULL value as input. EXPORT_
OBJECTS returns an error if an explicitly-specified object does not exist, or the user does not have
access to the object.

Syntax
EXPORT_OBJECTS( [ 'destination'

] , [ 'scope'

] , [

'ksafe' ] )

Parameters
destination

Specifies the path and name of the SQL output file. The default empty string ('')
outputs the script to standard output. The function writes the script to the catalog
directory if no destination is specified.
If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents.

HP Vertica Analytic Database (7.0.x)

Page 709 of 1539

SQL Reference Manual
SQL Functions

scope

ksafe

Determines the scope of the catalog objects to export:
l

An empty string (' ')—exports all non-virtual objects to which the user has
access, including constraints. (Note that constraints are not objects that can be
passed as individual arguments.) An empty string is the default scope value if
you do not limit the export.

l

A comma-delimited list of catalog objects to export, which can include the
following:
n

' [dbname.]schema.object '—matches each named schema object. You can
optionally qualify the schema with a database prefix. A named schema
object can be a table, projection, view, sequence, or user-defined SQL
function.

n

' [dbname.]schema—matches the named schema, which you can optionally
qualify with a database prefix. For a schema, HP Vertica exports all nonvirtual objects that the user has access to within the schema. If a schema
and table have the same name, the schema takes precedence.

Determines if the statistics are regenerated before loading them into the design
context
Specifies whether to incorporate a MARK_DESIGN_KSAFE statement with the
correct K-safe value for the database:
l

true—adds the MARK_DESIGN_KSAFE statement to the end of the output
script. This is the default value.

l

false—omits the MARK_DESIGN_KSAFE statement from the script.

Privileges
None. However:
l

EXPORT_OBJECTS exports only the objects visible to the user .

l

Only a superuser can export output to a file.

Example
The following example exports all the non-virtual objects to which the user has access to standard
output. The example uses false for the last parameter, indicating that the file will not include the
MARK_DESIGN_KSAFE statement at the end.
=> SELECT EXPORT_OBJECTS(' ',' ',false);

HP Vertica Analytic Database (7.0.x)

Page 710 of 1539

SQL Reference Manual
SQL Functions

See Also
l

EXPORT_CATALOG

l

EXPORT_TABLES

l

Exporting Objects

INSTALL_LICENSE
Installs the license key in the global catalog.

Syntax
INSTALL_LICENSE( 'filename' )

Parameters
filename

specifies the absolute pathname of a valid license file.

Privileges
Must be a superuser.

Notes
For more information about license keys, see Managing Your License Key in the Administrator's
Guide.

Examples
=> SELECT INSTALL_LICENSE('/tmp/vlicense.dat');

MARK_DESIGN_KSAFE
Enables or disables high availability in your environment, in case of a failure. Before enabling
recovery, MARK_DESIGN_KSAFE queries the catalog to determine whether a cluster's physical
schema design meets the following requirements:
l

Small, unsegmented tables are replicated on all nodes.

l

Large table superprojections are segmented with each segment on a different node.

HP Vertica Analytic Database (7.0.x)

Page 711 of 1539

SQL Reference Manual
SQL Functions

l

Each large table projection has at least one buddy projection for K-safety=1 (or two buddy
projections for K-safety=2).
Buddy projections are also segmented across database nodes, but the distribution is modified
so that segments that contain the same data are distributed to different nodes. See High
Availability Through Projections in the Concepts Guide.
Note: Projections are considered to be buddies if they contain the same columns and have
the same segmentation. They can have different sort orders.

MARK_DESIGN_KSAFE does not change the physical schema in any way.

Syntax
MARK_DESIGN_KSAFE ( k )

Parameters
k

2 enables high availability if the schema design meets requirements for K-safety=2
1 enables high availability if the schema design meets requirements for K-safety=1
0 disables high availability

If you specify a k value of one (1) or two (2), HP Vertica returns one of the following messages.
Success:
Marked design n-safe

Failure:
The schema does not meet requirements for K=n.
Fact table projection projection-name
has insufficient "buddy" projections.

n in the message is 1 or 2 and represents the k value.

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 712 of 1539

SQL Reference Manual
SQL Functions

Notes
l

The database's internal recovery state persists across database restarts but it is not checked at
startup time.

l

If a database has automatic recovery enabled, you must temporarily disable automatic recovery
before creating a new table.

l

When one node fails on a system marked K-safe=1, the remaining nodes are available for DML
operations.

Examples
=> SELECT MARK_DESIGN_KSAFE(1);
mark_design_ksafe
---------------------Marked design 1-safe
(1 row)

If the physical schema design is not K-Safe, messages indicate which projections do not have a
buddy:
=> SELECT MARK_DESIGN_KSAFE(1);
The given K value is not correct;
the schema is 0-safe
Projection pp1 has 0 buddies,
which is smaller that the given K of 1
Projection pp2 has 0 buddies,
which is smaller that the given K of 1
.
.
.
(1 row)

See Also
l

SYSTEM

l

High Availability and Recovery

l

HP Vertica System Tables

l

Avoiding Resegmentation During Joins

l

Failure Recovery

HP Vertica Analytic Database (7.0.x)

Page 713 of 1539

SQL Reference Manual
SQL Functions

SYNCH_WITH_HCATALOG_SCHEMA
Copies the structure of a Hive database schema available through the HCatalog Connector to an
Vertica Analytic Database schema.

Syntax
SYNC_WITH_HCATALOG_SCHEMA( local_schema, hcatalog_schema, [drop_tables] )

Parameters
local_schema The existing Vertica Analytic Database schema to store the copied HCatalog
schema's metadata
hcatalog_
schema

The HCatalog schema to copy

[drop_
tables]

Drop any tables in local_schema that do not correspond to a table in hcatalog_
schema

Notes
You should always create an empty schema for the local_schema parameter. Tables in the
hcatalog_schema overwrite any identically named table in local_schema, which can lead to data
loss.

Permissions
The user must have CREATE privileges on local_schema and USAGE permissions on hcatalog_
schema.

Example
The following example shows using SYNCH_WITH_HCATALOG_SCHEMA to copy the metadata
from an HCatalog schema named hcat to an Vertica Analytic Database schema named hcat_local:
=> CREATE SCHEMA hcat_local;
CREATE SCHEMA
=> SELECT sync_with_hcatalog_schema('hcat_local', 'hcat');
sync_with_hcatalog_schema
---------------------------------------Schema hcat_local synchronized with hcat
tables in hcat = 56
tables altered in hcat_local = 0
tables created in hcat_local = 56

HP Vertica Analytic Database (7.0.x)

Page 714 of 1539

SQL Reference Manual
SQL Functions

stale tables in hcat_local = 0
table changes erred in hcat_local = 0
(1 row)
=> -- Use vsql's \d command to describe a table in the synced schema
=> \d hcat_local.messages
List of Fields by Tables
Schema
|
Table | Column |
Type
| Size | Default | Not Null | Primary K
ey | Foreign Key
-----------+----------+---------+----------------+-------+---------+----------+------------+------------hcat_local | messages | id
| int
|
8 |
| f
| f
|
hcat_local | messages | userid | varchar(65000) | 65000 |
| f
| f
|
hcat_local | messages | "time" | varchar(65000) | 65000 |
| f
| f
|
hcat_local | messages | message | varchar(65000) | 65000 |
| f
| f
|
(4 rows)

Client Connection Management Functions
This section contains client connection management functions specific to HP Vertica.

SET_LOAD_BALANCE_POLICY
Sets how native connection load balancing chooses a host to handle a client connection. See About
Native Connection Load Balancing in the Administrator's Guide for more information.

Syntax
SET_LOAD_BALANCE_POLICY('policy')

Parameters
policy

The name of the load balancing policy to use. Can be one of the following:
l

NONE: Disables native connection load balancing. This is the default setting.

l

ROUNDROBIN: Chooses the next host from a circular list of currently up hosts in
the database (i.e. node #1, node #2, node #3, etc. until it wraps back to node #1
again). Each host in the cluster maintains its own pointer to the next host in the
circular list, rather than there being a single cluster-wide state.

l

RANDOM: Chooses a host at random from the list of currently up hosts in the
cluster.

HP Vertica Analytic Database (7.0.x)

Page 715 of 1539

SQL Reference Manual
SQL Functions

Notes
Even if the load balancing policy is set to something other than NONE on the server, clients must
indicate they want their connections to be load balanced by setting a connection property.

Permissions
Can only be used by a superuser .

Example
The following example demonstrates enabling native connection load balancing on the server by
setting the load balancing scheme to ROUNDROBIN:
=> SELECT SET_LOAD_BALANCE_POLICY('ROUNDROBIN');
SET_LOAD_BALANCE_POLICY
-------------------------------------------------------------------------------Successfully changed the client initiator load balancing policy to: roundrobin
(1 row)

RESET_LOAD_BALANCE_POLICY
Resets the counter each host in the cluster maintains to track which host it will refer a client to
when the native connection load balancing scheme is set to ROUNDROBIN.

Syntax
RESET_LOAD_BALANCE_POLICY()

Notes
This function only has an effect if the current native connection load balancing scheme is
ROUNDROBIN.

Permissions
This function can be called only by a superuser .

Example
The following example demonstrates calling RESET_LOAD_BALANCE_POLICY:

HP Vertica Analytic Database (7.0.x)

Page 716 of 1539

SQL Reference Manual
SQL Functions

=> SELECT RESET_LOAD_BALANCE_POLICY();
RESET_LOAD_BALANCE_POLICY
------------------------------------------------------------------------Successfully reset stateful client load balance policies: "roundrobin".
(1 row)

Cluster Management Functions
This section contains functions that manage spread deployment on large, distributed database
clusters.

SET_CONTROL_SET_SIZE
For existing database clusters, use this function to specify the number of cluster nodes on which
you want to deploy control messaging (spread). The SET_CONTROL_SET_SIZE() function works the
same as the install_vertica --large cluster  option.
You can run SET_CONTROL_SET_SIZE()after the database cluster is already defined, but before you
call this function, the database must be up.
Note: You use this function with other cluster management functions. For details, see Defining
and Realigning Control Nodes on an Existing Cluster in the Administrator's Guide.

Syntax
SET_CONTROL_SET_SIZE(integer)

Parameters
integer

Specifies the number of cluster hosts from the
database cluster on which spread runs.

Privileges
Must be a superuser.

Note
To see if the current spread hosts and the control designations in the Catalog match, query the V_
CATALOG.LARGE_CLUSTER_CONFIGURATION_STATUS system table.

Example
The following command tells HP Vertica that you want to run spread on two cluster nodes:

HP Vertica Analytic Database (7.0.x)

Page 717 of 1539

SQL Reference Manual
SQL Functions

=> SELECT set_control_set_size(2);
SET_CONTROL_SET_SIZE
---------------------Control size set
(1 row)

See Also
Cluster Management Functions
V_CATALOG.CLUSTER_LAYOUT
Large Cluster in the Administrator's Guide

REALIGN_CONTROL_NODES
Chooses control nodes (spread hosts) from all cluster nodes and assigns the rest of the nodes in
the cluster to a control node. Calling this function respects existing fault groups, which you can
view by querying the V_CATALOG.CLUSTER_LAYOUT system table. This view also lets you see the
proposed new layout for nodes in the cluster.
Note: You use this function with other cluster management functions. For details, see Defining
and Realigning Control Nodes on an Existing Cluster in the Administrator's Guide.

Syntax
REALIGN_CONTROL_NODES()

Privileges
Must be a superuser.

Example
The following command chooses control nodes from all cluster nodes and assigns the rest of the
nodes in the cluster to a control node:
=> SELECT realign_control_nodes();

See Also
Cluster Management Functions
V_CATALOG.CLUSTER_LAYOUT

HP Vertica Analytic Database (7.0.x)

Page 718 of 1539

SQL Reference Manual
SQL Functions

Large Cluster in the Administrator's Guide

RELOAD_SPREAD
Calling this function with the required true argument updates cluster changes (such as new or realigned control nodes spread hosts or fault groups or new/dropped cluster nodes), to the catalog's
spread configuration file.
Important: This function is often used in a multi-step process for large and elastic cluster
arrangements. Calling RELOAD_SPREAD(true) might require that you restart the database,
which you do using the Administration Tools. You must then rebalance the cluster for fault
tolerance to be realized. See Defining and Realigning Control Nodes in the Administrator's
Guide for more information.

Syntax
RELOAD_SPREAD(true)

Parameters
true

Updates cluster changes related to control
message responsibilities to the spread
configuration file.

Privileges
Must be a superuser.

Example
The following command updates the cluster with changes to control messaging:
=> SELECT reload_spread(true);
reload_spread
--------------reloaded
(1 row)

See Also
Cluster Management Functions
REBALANCE_CLUSTER
V_CATALOG.CLUSTER_LAYOUT

HP Vertica Analytic Database (7.0.x)

Page 719 of 1539

SQL Reference Manual
SQL Functions

Large Cluster in the Administrator's Guide

REBALANCE_CLUSTER
Call this function to begin rebalancing data in the cluster synchronously.
A rebalance operation performs the following tasks:
l

Distributes data based on user-defined fault groups, if specified, or based on large cluster
automatic fault groups

l

Redistributes the database projections' data across all nodes

l

Refreshes projections

l

Sets the Ancient History Mark

l

Drops projections that are no longer needed

When to rebalance the cluster
Rebalancing is useful (or necessary) after you:
l

Mark one or more nodes as ephemeral in preparation of removing them from the cluster

l

Add one or more nodes to the cluster so HP Vertica can populate the empty nodes with data

l

Remove one or more nodes from the cluster so HP Vertica can redistribute the data among the
remaining nodes

l

Change the scaling factor of an elastic cluster, which determines the number of storage
containers used to store a projection across the database

l

Set the control node size or realign control nodes on a large cluster layout

l

Specify more than 120 nodes in your initial HP Vertica cluster configuration

l

Add nodes to or remove nodes from a fault group

Because this function runs the rebalance task synchronously, it does not return until the data has
been rebalanced. Closing or dropping the session cancels the rebalance task.
Important: On large cluster arrangements, you typically use this function in a flow, described
Defining and Realigning Control Nodes in the Administrator's Guide. After you change the
number and distribution of control nodes (spread hosts), you must run REBALANCE_CLUSTER()
for fault tolerance to be realized.

HP Vertica Analytic Database (7.0.x)

Page 720 of 1539

SQL Reference Manual
SQL Functions

Syntax
REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
The following command rebalances data across the cluster.
=> SELECT REBALANCE_CLUSTER();
REBALANCE_CLUSTER
------------------REBALANCED
(1 row)

See Also
START_REBALANCE_CLUSTER
CANCEL_REBALANCE_CLUSTER
Rebalancing Data Across Nodes in the Administrator's Guide

HP Vertica Analytic Database (7.0.x)

Page 721 of 1539

SQL Reference Manual
SQL Functions

Cluster Scaling Functions
This section contains functions that control how the cluster organizes data for rebalancing.

CANCEL_REBALANCE_CLUSTER
Stops any rebalance task currently in progress.

Syntax
CANCEL_REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT CANCEL_REBALANCE_CLUSTER();
CANCEL_REBALANCE_CLUSTER
-------------------------CANCELED
(1 row)

See Also
l

START_REBALANCE_CLUSTER

l

REBALANCE_CLUSTER

DISABLE_ELASTIC_CLUSTER
Disables elastic cluster scaling, which prevents HP Vertica from bundling data into chunks that are
easily transportable to other nodes when performing cluster resizing. The main reason to disable
elastic clustering is if you find that the slightly unequal data distribution in your cluster caused by
grouping data into discrete blocks results in performance issues.

Syntax
DISABLE_ELASTIC_CLUSTER()

HP Vertica Analytic Database (7.0.x)

Page 722 of 1539

SQL Reference Manual
SQL Functions

Privileges
Must be a superuser.

Example
=> SELECT DISABLE_ELASTIC_CLUSTER();
DISABLE_ELASTIC_CLUSTER
------------------------DISABLED
(1 row)

See Also
l

ENABLE_ELASTIC_CLUSTER

DISABLE_LOCAL_SEGMENTS
Disable local data segmentation, which breaks projections segments on nodes into containers that
can be easily moved to other nodes. See Local Data Segmentation in the Administrator's Guide for
details.

Syntax
DISABLE_LOCAL_SEGMENTS()

Privileges
Must be a superuser.

Example
=> SELECT DISABLE_LOCAL_SEGMENTS();
DISABLE_LOCAL_SEGMENTS
-----------------------DISABLED
(1 row)

ENABLE_ELASTIC_CLUSTER
Enables elastic cluster scaling, which makes enlarging or reducing the size of your database
cluster more efficient by segmenting a node's data into chunks that can be easily moved to other
hosts.

HP Vertica Analytic Database (7.0.x)

Page 723 of 1539

SQL Reference Manual
SQL Functions

Note: Databases created using HP Vertica Version 5.0 and later have elastic cluster enabled
by default. You need to use this function on databases created before version 5.0 in order for
them to use the elastic clustering feature.

Syntax
ENABLE_ELASTIC_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT ENABLE_ELASTIC_CLUSTER();
ENABLE_ELASTIC_CLUSTER
-----------------------ENABLED
(1 row)

See Also
l

DISABLE_ELASTIC_CLUSTER

ENABLE_LOCAL_SEGMENTS
Enables local storage segmentation, which breaks projections segments on nodes into containers
that can be easily moved to other nodes. See Local Data Segmentation in the Administrator's Guide
for more information.

Syntax
ENABLE_LOCAL_SEGMENTS()

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 724 of 1539

SQL Reference Manual
SQL Functions

Example
=> SELECT ENABLE_LOCAL_SEGMENTS();
ENABLE_LOCAL_SEGMENTS
----------------------ENABLED
(1 row)

REBALANCE_CLUSTER
Call this function to begin rebalancing data in the cluster synchronously.
A rebalance operation performs the following tasks:
l

Distributes data based on user-defined fault groups, if specified, or based on large cluster
automatic fault groups

l

Redistributes the database projections' data across all nodes

l

Refreshes projections

l

Sets the Ancient History Mark

l

Drops projections that are no longer needed

When to rebalance the cluster
Rebalancing is useful (or necessary) after you:
l

Mark one or more nodes as ephemeral in preparation of removing them from the cluster

l

Add one or more nodes to the cluster so HP Vertica can populate the empty nodes with data

l

Remove one or more nodes from the cluster so HP Vertica can redistribute the data among the
remaining nodes

l

Change the scaling factor of an elastic cluster, which determines the number of storage
containers used to store a projection across the database

l

Set the control node size or realign control nodes on a large cluster layout

l

Specify more than 120 nodes in your initial HP Vertica cluster configuration

l

Add nodes to or remove nodes from a fault group

Because this function runs the rebalance task synchronously, it does not return until the data has
been rebalanced. Closing or dropping the session cancels the rebalance task.

HP Vertica Analytic Database (7.0.x)

Page 725 of 1539

SQL Reference Manual
SQL Functions

Important: On large cluster arrangements, you typically use this function in a flow, described
Defining and Realigning Control Nodes in the Administrator's Guide. After you change the
number and distribution of control nodes (spread hosts), you must run REBALANCE_CLUSTER()
for fault tolerance to be realized.

Syntax
REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
The following command rebalances data across the cluster.
=> SELECT REBALANCE_CLUSTER();
REBALANCE_CLUSTER
------------------REBALANCED
(1 row)

See Also
START_REBALANCE_CLUSTER
CANCEL_REBALANCE_CLUSTER
Rebalancing Data Across Nodes in the Administrator's Guide

SET_SCALING_FACTOR
Sets the scaling factor that determines the size of the storage containers used when rebalancing
the database and when using local data segmentation is enabled. See Cluster Scaling for details.

Syntax
SET_SCALING_FACTOR(factor)

Parameters
factor

An integer value between 1 and 32. HP Vertica uses this value to calculate the number
of storage containers each projection is broken into when rebalancing or when local data
segmentation is enabled.

HP Vertica Analytic Database (7.0.x)

Page 726 of 1539

SQL Reference Manual
SQL Functions

Note: Setting the scaling factor value too high can cause nodes to create too many small
container files, greatly reducing efficiency and potentially causing a "Too many
ROS containers" error (also known as "ROS pushback"). The scaling factor should be set high
enough so that rebalance can transfer local segments to satisfy the skew threshold, but small
enough that the number of storage containers does not exceed ROS pushback. The number of
storage containers should be greater than or equal to the number of partitions multiplied by the
number local of segments (# storage containers >= # partitions * # local segments).

Privileges
Must be a superuser.

Example
=> SELECT SET_SCALING_FACTOR(12);
SET_SCALING_FACTOR
-------------------SET
(1 row)

START_REBALANCE_CLUSTER
A rebalance operation performs the following tasks:
l

Distributes data based on user-defined fault groups, if specified, or based on large cluster
automatic fault groups

l

Redistributes the database projections' data across all nodes

l

Refreshes projections

l

Sets the Ancient History Mark

l

Drops projections that are no longer needed

When to rebalance the cluster
Rebalancing is useful (or necessary) after you:
l

Mark one or more nodes as ephemeral in preparation of removing them from the cluster

l

Add one or more nodes to the cluster so HP Vertica can populate the empty nodes with data

l

Remove one or more nodes from the cluster so HP Vertica can redistribute the data among the
remaining nodes

HP Vertica Analytic Database (7.0.x)

Page 727 of 1539

SQL Reference Manual
SQL Functions

l

Change the scaling factor of an elastic cluster, which determines the number of storage
containers used to store a projection across the database

l

Set the control node size or realign control nodes on a large cluster layout

l

Specify more than 120 nodes in your initial HP Vertica cluster configuration

l

Add nodes to or remove nodes from a fault group

Asynchronously starts a data rebalance task. Since this function starts the rebalance task in the
background, it returns immediately after the task has started. Since it is a background task,
rebalancing will continue even if the session that started it is closed. It even continues after a
cluster recovery if the database shuts down while it is in progress. The only way to stop the task is
by the CANCEL_REBALANCE_CLUSTER function.

Syntax
START_REBALANCE_CLUSTER()

Privileges
Must be a superuser.

Example
=> SELECT START_REBALANCE_CLUSTER();
START_REBALANCE_CLUSTER
------------------------REBALANCING
(1 row)

See Also
l

Rebalancing Data Across Nodes

l

CANCEL_REBALANCE_CLUSTER

l

REBALANCE_CLUSTER

HP Vertica Analytic Database (7.0.x)

Page 728 of 1539

SQL Reference Manual
SQL Functions

Constraint Management Functions
This section contains constraint management functions specific to HP Vertica.
See also SQL system table V_CATALOG.TABLE_CONSTRAINTS

ANALYZE_CONSTRAINTS
Analyzes and reports on constraint violations within the current schema search path, or external to
that path if you specify a database name (noted in the syntax statement and parameter table).
You can check for constraint violations by passing arguments to the function as follows:
l

An empty argument (' '), which returns violations on all tables within the current schema

l

One argument, referencing a table

l

Two arguments, referencing a table name and a column or list of columns

Syntax
ANALYZE_CONSTRAINTS [ ( '' )
... | ( '[[db-name.]schema.]table [.column_name]' )
... | ( '[[db-name.]schema.]table' , 'column' ) ]

Parameters
('')

Analyzes and reports on all tables within the current schema search path.

[[db-name.]schema.]

[Optional] Specifies the database name and optional schema name. Using
a database name identifies objects that are not unique within the current
search path (see Setting Search Paths). You must be connected to the
database you specify, and you cannot change objects in other databases.
Specifying different database objects lets you qualify database objects as
explicitly as required. For example, you can use a database and a schema
name (mydb.myschema).

table

Analyzes and reports on all constraints referring to the specified table.

column

Analyzes and reports on all constraints referring to the specified table that
contains the column.

HP Vertica Analytic Database (7.0.x)

Page 729 of 1539

SQL Reference Manual
SQL Functions

Privileges
l

SELECT privilege on table

l

USAGE privilege on schema

Notes
ANALYZE_CONSTRAINTS() performs a lock in the same way that SELECT * FROM t1 holds a
lock on table t1. See LOCKS for additional information.

Detecting Constraint Violations During a Load Process
HP Vertica checks for constraint violations when queries are run, not when data is loaded. To
detect constraint violations as part of the load process, use a COPY statement with the NO
COMMIT option. By loading data without committing it, you can run a post-load check of your data
using the ANALYZE_CONSTRAINTS function. If the function finds constraint violations, you can
roll back the load because you have not committed it.
If ANALYZE_CONSTRAINTS finds violations, such as when you insert a duplicate value into a
primary key, you can correct errors using the following functions. Effects last until the end of the
session only:
l

SELECT DISABLE_DUPLICATE_KEY_ERROR

l

SELECT REENABLE_DUPLICATE_KEY_ERROR

Return Values
ANALYZE_CONSTRAINTS returns results in a structured set (see table below) that lists the
schema name, table name, column name, constraint name, constraint type, and the column values
that caused the violation.
If the result set is empty, then no constraint violations exist; for example:
> SELECT ANALYZE_CONSTRAINTS ('public.product_dimension', 'product_key');
Schema Name | Table Name | Column Names | Constraint Name | Constraint Type | Column Valu
es
-------------+------------+--------------+-----------------+-----------------+-------------(0 rows)

The following result set shows a primary key violation, along with the value that caused the
violation ('10'):
=> SELECT ANALYZE_CONSTRAINTS ('');

HP Vertica Analytic Database (7.0.x)

Page 730 of 1539

SQL Reference Manual
SQL Functions

Schema Name | Table Name | Column Names | Constraint Name | Constraint Type | Column Valu
es
-------------+------------+--------------+-----------------+-----------------+-------------store
t1
c1
pk_t1
PRIMARY
('10')
(1 row)

The result set columns are described in further detail in the following table:
Column Name Data Type

Description

Schema Name

VARCHAR

The name of the schema.

Table Name

VARCHAR

The name of the table, if specified.

Column Names

VARCHAR

Names of columns containing constraints. Multiple columns are
in a comma-separated list:
store_key, store_key, date_key,

Constraint Name

VARCHAR

The given name of the primary key, foreign key, unique, or not
null constraint, if specified.

Constraint Type

VARCHAR

Identified by one of the following strings: 'PRIMARY KEY',
'FOREIGN KEY', 'UNIQUE', or 'NOT NULL'.

Column Values

VARCHAR

Value of the constraint column, in the same order in which
Column Names contains the value of that column in the violating
row.
When interpreted as SQL, the value of this column forms a list of
values of the same type as the columns in Column Names; for
example:
('1'), ('1', 'z')

Understanding Function Failures
If ANALYZE_CONSTRAINTS() fails, HP Vertica returns an error identifying the failure condition,
such as if there are insufficient resources for the database to perform constraint checks.
If you specify the wrong table, the system returns an error message:
> SELECT ANALYZE_CONSTRAINTS('abc');
ERROR 2069: 'abc' is not a table in the current search_path

If you run the function on a table that has no constraints declared (even if duplicates are present),
the system returns an error message:
> SELECT ANALYZE_CONSTRAINTS('source');
ERROR 4072: No constraints defined

HP Vertica Analytic Database (7.0.x)

Page 731 of 1539

SQL Reference Manual
SQL Functions

If you run the function with incorrect syntax, the system returns an error message with a hint; for
example, if you run one of the following:
l

ANALYZE ALL CONSTRAINT;

l

ANALYZE CONSTRAINT abc;

The system returns an informative error with hint:
ERROR: ANALYZE CONSTRAINT is not supported.
HINT: You may consider using analyze_constraints().

If you run ANALYZE_CONSTRAINTS from a non-default locale, the function returns an error with a
hint:
> \locale LENINFO 2567: Canonical locale: 'en'
Standard collation: 'LEN'
English
> SELECT ANALYZE_CONSTRAINTS('t1');
ERROR: ANALYZE_CONSTRAINTS is currently not supported in
non-default locales
HINT: Set the locale in this session to
en_US@collation=binary using the command
"\locale en_US@collation=binary"

Examples
Given the following inputs, HP Vertica returns one row, indicating one violation, because the same
primary key value (10) was inserted into table t1 twice:
CREATE TABLE t1(c1 INT);
ALTER TABLE t1 ADD CONSTRAINT pk_t1 PRIMARY KEY (c1);
CREATE PROJECTION t1_p (c1) AS SELECT *
FROM t1 UNSEGMENTED ALL NODES;
INSERT INTO t1 values (10);
INSERT INTO t1 values (10); --Duplicate primary key value
\x
Expanded display is on.
SELECT ANALYZE_CONSTRAINTS('t1');
-[ RECORD 1 ]---+-------Schema Name
| public
Table Name
| t1
Column Names
| c1
Constraint Name | pk_t1
Constraint Type | PRIMARY
Column Values
| ('10')

If the second INSERT statement above had contained any different value, the result would have
been 0 rows (no violations).

HP Vertica Analytic Database (7.0.x)

Page 732 of 1539

SQL Reference Manual
SQL Functions

In the following example, create a table that contains three integer columns, one a unique key and
one a primary key:
CREATE TABLE table_1(
a INTEGER,
b_UK INTEGER UNIQUE,
c_PK INTEGER PRIMARY KEY
);

Issue a command that refers to a nonexistent table and column:
SELECT ANALYZE_CONSTRAINTS('a_BB');
ERROR: 'a_BB' is not a table name in the current search path

Issue a command that refers to a nonexistent column:
SELECT ANALYZE_CONSTRAINTS('table_1','x');
ERROR 41614: Nonexistent columns: 'x '

Insert some values into table table_1 and commit the changes:
INSERT INTO table_1 values (1, 1, 1);
COMMIT;

Run ANALYZE_CONSTRAINTS on table table_1. No constraint violations are reported:
SELECT ANALYZE_CONSTRAINTS('table_1');
(No rows)

Insert duplicate unique and primary key values and run ANALYZE_CONSTRAINTS on table
table_1 again. The system shows two violations: one against the primary key and one against the
unique key:
INSERT INTO table_1 VALUES (1, 1, 1);
COMMIT;
SELECT ANALYZE_CONSTRAINTS('table_1');

-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| b_UK
Constraint Name | C_UNIQUE
Constraint Type | UNIQUE
Column Values
| ('1')
-[ RECORD 2 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY

HP Vertica Analytic Database (7.0.x)

Page 733 of 1539

SQL Reference Manual
SQL Functions

Column Values

| ('1')

The following command looks for constraint validations on only the unique key in the table table_1,
qualified with its schema name:
=> SELECT ANALYZE_CONSTRAINTS('public.table_1', 'b_UK');
-[ RECORD 1 ]---+--------Schema Name
| public
Table Name
| table_1
Column Names
| b_UK
Constraint Name | C_UNIQUE
Constraint Type | UNIQUE
Column Values
| ('1')
(1 row)

The following example shows that you can specify the same column more than once; ANALYZE_
CONSTRAINTS, however, returns the violation only once:
SELECT ANALYZE_CONSTRAINTS('table_1', 'c_PK, C_PK');
-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_1
Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')

The following example creates a new table, table_2, and inserts a foreign key and different
(character) data types:
CREATE TABLE table_2 (
x VARCHAR(3),
y_PK VARCHAR(4),
z_FK INTEGER REFERENCES table_1(c_PK));

Alter the table to create a multicolumn unique key and multicolumn foreign key and create
superprojections:
ALTER TABLE table_2
ADD CONSTRAINT table_2_multiuk PRIMARY KEY (x, y_PK);
WARNING 2623: Column "x" definition changed to NOT NULL
WARNING 2623: Column "y_PK" definition changed to NOT NULL

The following command inserts a missing foreign key (0) into table dim_1 and commits the
changes:
INSERT INTO table_2 VALUES ('r1', 'Xpk1', 0);
COMMIT;

HP Vertica Analytic Database (7.0.x)

Page 734 of 1539

SQL Reference Manual
SQL Functions

Checking for constraints on the table table_2 in the public schema detects a foreign key
violation:
=> SELECT ANALYZE_CONSTRAINTS('public.table_2');
-[ RECORD 1 ]---+---------Schema Name
| public
Table Name
| table_2
Column Names
| z_FK
Constraint Name | C_FOREIGN
Constraint Type | FOREIGN
Column Values
| ('0')

Now add a duplicate value into the unique key and commit the changes:
INSERT INTO table_2 VALUES ('r2', 'Xpk1', 1);
INSERT INTO table_2 VALUES ('r1', 'Xpk1', 1);
COMMIT;

Checking for constraint violations on table table_2 detects the duplicate unique key error:
SELECT ANALYZE_CONSTRAINTS('table_2');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| z_FK
Constraint Name | C_FOREIGN
Constraint Type | FOREIGN
Column Values
| ('0')
-[ RECORD 2 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| x, y_PK
Constraint Name | table_2_multiuk
Constraint Type | PRIMARY
Column Values
| ('r1', 'Xpk1')

Create a table with multicolumn foreign key and create the superprojections:
CREATE TABLE table_3(
z_fk1 VARCHAR(3),
z_fk2 VARCHAR(4));
ALTER TABLE table_3
ADD CONSTRAINT table_3_multifk FOREIGN KEY (z_fk1, z_fk2)
REFERENCES table_2(x, y_PK);

Insert a foreign key that matches a foreign key in table table_2 and commit the changes:
INSERT INTO table_3 VALUES ('r1', 'Xpk1');
COMMIT;

Checking for constraints on table table_3 detects no violations:

HP Vertica Analytic Database (7.0.x)

Page 735 of 1539

SQL Reference Manual
SQL Functions

SELECT ANALYZE_CONSTRAINTS('table_3');
(No rows)

Add a value that does not match and commit the change:
INSERT INTO table_3 VALUES ('r1', 'NONE');
COMMIT;

Checking for constraints on table dim_2 detects a foreign key violation:
SELECT ANALYZE_CONSTRAINTS('table_3');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_3
Column Names
| z_fk1, z_fk2
Constraint Name | table_3_multifk
Constraint Type | FOREIGN
Column Values
| ('r1', 'NONE')

Analyze all constraints on all tables:
SELECT ANALYZE_CONSTRAINTS('');
-[ RECORD 1 ]---+---------------Schema Name
| public
Table Name
| table_3
Column Names
| z_fk1, z_fk2
Constraint Name | table_3_multifk
Constraint Type | FOREIGN
Column Values
| ('r1', 'NONE')
-[ RECORD 2 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| x, y_PK
Constraint Name | table_2_multiuk
Constraint Type | PRIMARY
Column Values
| ('r1', 'Xpk1')
-[ RECORD 3 ]---+---------------Schema Name
| public
Table Name
| table_2
Column Names
| z_FK
Constraint Name | C_FOREIGN
Constraint Type | FOREIGN
Column Values
| ('0')
-[ RECORD 4 ]---+---------------Schema Name
| public
Table Name
| t1
Column Names
| c1
Constraint Name | pk_t1
Constraint Type | PRIMARY
Column Values
| ('10')
-[ RECORD 5 ]---+---------------Schema Name
| public
Table Name
| table_1

HP Vertica Analytic Database (7.0.x)

Page 736 of 1539

SQL Reference Manual
SQL Functions

Column Names
| b_UK
Constraint Name | C_UNIQUE
Constraint Type | UNIQUE
Column Values
| ('1')
-[ RECORD 6 ]---+---------------Schema Name
| public
Table Name
| table_1
Column Names
| c_PK
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')
-[ RECORD 7 ]---+---------------Schema Name
| public
Table Name
| target
Column Names
| a
Constraint Name | C_PRIMARY
Constraint Type | PRIMARY
Column Values
| ('1')
(5 rows)

To quickly clean up your database, issue the following command:
DROP TABLE table_1 CASCADE;
DROP TABLE table_2 CASCADE;
DROP TABLE table_3 CASCADE;

To learn how to remove violating rows, see the DISABLE_DUPLICATE_KEY_ERROR function.

ANALYZE_CORRELATIONS
Analyzes the specified tables for columns that are strongly correlated. In addition, ANALYZE_
CORRELATIONS also collects statistics.
For example, state name and country name columns are strongly correlated because the city name
usually, but perhaps not always, identifies the state name. The city of Conshohoken is uniquely
associated with Pennsylvania, whereas the city of Boston exists in Georgia, Indiana, Kentucky,
New York, Virginia, and Massachusetts. In this case, city name is strongly correlated with state
name.
For Database Designer to take advantage of these correlations, run Database Designer
programmatically. Use DESIGNER_SET_ANALYZE_CORRELATIONS_MODE to specify that
Database Designer should consider existing column correlations. Make sure to specify that
Database Designer not analyze statistics so that Database Designer does not override the existing
statistics.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 737 of 1539

SQL Reference Manual
SQL Functions

Syntax
ANALYZE_CORRELATIONS (
'[database_name.][schema_name.]table_name',
[recalculate] )

Parameters
database_name

Specifies the table(s) for which to analyze correlated columns, type VARCHAR.

schema_name
table_name
recalculate

Specifies to analyze the correlated columns, even if they have been analyzed
before, type BOOLEAN. Default: 'false'.

Permissions
l

To run ANALYZE_CORRELATIONS on a table, you must be a superuser, or a user w USAGE
privilege on the design schema.

Notes
l

Column correlation analysis typically needs to be done only once.

l

Currently, ANALYZE_CORRELATIONS can analyze only pairwise single-column correlations.

l

Projections do not change based on the analysis results. To implement the results of
ANALYZE_CORRELATIONS, you must run Database Designer.

Example
In the following example, ANALYZE_CORRELATIONS analyzes column correlations for all tables
in the public schema,even if they currently exist. The correlations that ANALYZE_
CORRELATIONS finds are saved so that Database Designer can use them the next time it runs on
the VMart database:
=> SELECT ANALYZE_CORRELATIONS (
'public.*',
'true');
ANALYZE_CORRELATIONS
---------------------0
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 738 of 1539

SQL Reference Manual
SQL Functions

See Also
l

DESIGNER_SET_ANALYZE_CORRELATIONS_MODE

DISABLE_DUPLICATE_KEY_ERROR
Disables error messaging when HP Vertica finds duplicate PRIMARY KEY/UNIQUE KEY values
at run time. Queries execute as though no constraints are defined on the schema. Effects are
session scoped.
Caution: When called, DISABLE_DUPLICATE_KEY_ERROR() suppresses data integrity
checking and can lead to incorrect query results. Use this function only after you insert
duplicate primary keys into a dimension table in the presence of a pre-join projection. Then
correct the violations and turn integrity checking back on with REENABLE_DUPLICATE_
KEY_ERROR().

Syntax
DISABLE_DUPLICATE_KEY_ERROR();

Privileges
Must be a superuser.

Examples
The following series of commands create a table named dim and the corresponding projection:
CREATE TABLE dim (pk INTEGER PRIMARY KEY, x INTEGER);
CREATE PROJECTION dim_p (pk, x) AS SELECT * FROM dim ORDER BY x UNSEGMENTED ALL NODES;

The next two statements create a table named fact and the pre-join projection that joins fact to
dim.
CREATE TABLE fact(fk INTEGER REFERENCES dim(pk));
CREATE PROJECTION prejoin_p (fk, pk, x) AS SELECT * FROM fact, dim WHERE pk=fk ORDER BY x
;

The following statements load values into table dim. The last statement inserts a duplicate primary
key value of 1:
INSERT INTO dim values (1,1);INSERT INTO dim values (2,2);
INSERT INTO dim values (1,2); --Constraint violation

HP Vertica Analytic Database (7.0.x)

Page 739 of 1539

SQL Reference Manual
SQL Functions

COMMIT;

Table dim now contains duplicate primary key values, but you cannot delete the violating row
because of the presence of the pre-join projection. Any attempt to delete the record results in the
following error message:
ROLLBACK: Duplicate primary key detected in FK-PK join Hash-Join (x dim_p), value 1

In order to remove the constraint violation (pk=1), use the following sequence of commands, which
puts the database back into the state just before the duplicate primary key was added.
To remove the violation:
1. Save the original dim rows that match the duplicated primary key:
CREATE TEMP TABLE dim_temp(pk integer, x integer);
INSERT INTO dim_temp SELECT * FROM dim WHERE pk=1 AND x=1; -- original dim row

2. Temporarily disable error messaging on duplicate constraint values:
SELECT DISABLE_DUPLICATE_KEY_ERROR();

Caution: Remember that running the DISABLE_DUPLICATE_KEY_ERROR function
suppresses the enforcement of data integrity checking.
3. Remove the original row that contains duplicate values:
DELETE FROM dim WHERE pk=1;

4. Allow the database to resume data integrity checking:
SELECT REENABLE_DUPLICATE_KEY_ERROR();

5. Reinsert the original values back into the dimension table:
INSERT INTO dim SELECT * from dim_temp;COMMIT;

6. Validate your dimension and fact tables.
If you receive the following error message, it means that the duplicate records you want to
delete are not identical. That is, the records contain values that differ in at least one column
that is not a primary key; for example, (1,1) and (1,2).

HP Vertica Analytic Database (7.0.x)

Page 740 of 1539

SQL Reference Manual
SQL Functions

ROLLBACK: Delete: could not find a data row to delete (data integrity violation?)

The difference between this message and the rollback message in the previous example is that
a fact row contains a foreign key that matches the duplicated primary key, which has been
inserted. A row with values from the fact and dimension table is now in the pre-join projection.
In order for the DELETE statement (Step 3 in the following example) to complete successfully,
extra predicates are required to identify the original dimension table values (the values that are
in the pre-join).
This example is nearly identical to the previous example, except that an additional INSERT
statement joins the fact table to the dimension table by a primary key value of 1:
INSERT INTO dim values (1,1);INSERT INTO dim values (2,2);
INSERT INTO fact values (1);
-- New insert statement joins fact with dim on primar
y key value=1
INSERT INTO dim values (1,2); -- Duplicate primary key value=1
COMMIT;

To remove the violation:
1. Save the original dim and fact rows that match the duplicated primary key:
CREATE TEMP TABLE dim_temp(pk integer, x integer);CREATE TEMP TABLE fact_temp(fk inte
ger);
INSERT INTO dim_temp SELECT * FROM dim WHERE pk=1 AND x=1; -- original dim row
INSERT INTO fact_temp SELECT * FROM fact WHERE fk=1;

2. Temporarily suppresses the enforcement of data integrity checking:
SELECT DISABLE_DUPLICATE_KEY_ERROR();

3. Remove the duplicate primary keys. These steps also implicitly remove all fact rows with the
matching foreign key.
4. Remove the original row that contains duplicate values:
DELETE FROM dim WHERE pk=1 AND x=1;

Note: The extra predicate (x=1) specifies removal of the original (1,1) row, rather than the
newly inserted (1,2) values that caused the violation.
5. Remove all remaining rows:

HP Vertica Analytic Database (7.0.x)

Page 741 of 1539

SQL Reference Manual
SQL Functions

DELETE FROM dim WHERE pk=1;

6. Reenable integrity checking:
SELECT REENABLE_DUPLICATE_KEY_ERROR();

7. Reinsert the original values back into the fact and dimension table:
INSERT INTO dim SELECT * from dim_temp;
INSERT INTO fact SELECT * from fact_temp;
COMMIT;

8. Validate your dimension and fact tables.

See Also
l

ANALYZE_CONSTRAINTS

l

REENABLE_DUPLICATE_KEY_ERROR

LAST_INSERT_ID
Returns the last value of a column whose value is automatically incremented through the AUTO_
INCREMENT or IDENTITY Column-Constraint. If multiple sessions concurrently load the same
table, the returned value is the last value generated for an AUTO_INCREMENT column by an
insert in that session.

Behavior Type
Volatile

Syntax
LAST_INSERT_ID()

Privileges
l

Table owner

l

USAGE privileges on schema

HP Vertica Analytic Database (7.0.x)

Page 742 of 1539

SQL Reference Manual
SQL Functions

Notes
l

This function works only with AUTO_INCREMENT and IDENTITY columns. See columnconstraints for the CREATE TABLE statement.

l

LAST_INSERT_ID does not work with sequence generators created through the CREATE
SEQUENCE statement.

Examples
Create a sample table called customer4.
=> CREATE TABLE customer4(
ID IDENTITY(2,2),
lname VARCHAR(25),
fname VARCHAR(25),
membership_card INTEGER
);
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Gupta', 'Saleem', 475987);

Notice that the IDENTITY column has a seed of 2, which specifies the value for the first row loaded
into the table, and an increment of 2, which specifies the value that is added to the IDENTITY value
of the previous row.
Query the table you just created:
=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
(1 row)

Insert some additional values:
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Lee', 'Chen', 598742);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------4
(1 row)

Query the table again:

HP Vertica Analytic Database (7.0.x)

Page 743 of 1539

SQL Reference Manual
SQL Functions

=> SELECT * FROM customer4;
ID | lname | fname | membership_card
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
(2 rows)

Add another row:
=> INSERT INTO customer4(lname, fname, membership_card)
VALUES ('Davis', 'Bill', 469543);

Call the LAST_INSERT_ID function:
=> SELECT LAST_INSERT_ID();
LAST_INSERT_ID
---------------6
(1 row)

Query the table again:
=> SELECT * FROM customer4; ID | lname | fname
----+-------+--------+----------------2 | Gupta | Saleem |
475987
4 | Lee
| Chen
|
598742
6 | Davis | Bill
|
469543
(3 rows)

| membership_card

See Also
l

ALTER SEQUENCE

l

CREATE SEQUENCE

l

DROP SEQUENCE

l

SEQUENCES

l

Using Named Sequences

l

Sequence Privileges

REENABLE_DUPLICATE_KEY_ERROR
Restores the default behavior of error reporting by reversing the effects of DISABLE_DUPLICATE_
KEY_ERROR. Effects are session scoped.

HP Vertica Analytic Database (7.0.x)

Page 744 of 1539

SQL Reference Manual
SQL Functions

Syntax
REENABLE_DUPLICATE_KEY_ERROR();

Privileges
Must be a superuser.

Examples
For examples and usage, see DISABLE_DUPLICATE_KEY_ERROR.

See Also
l

ANALYZE_CONSTRAINTS

HP Vertica Analytic Database (7.0.x)

Page 745 of 1539

SQL Reference Manual
SQL Functions

Data Collector Functions
The HP Vertica Data Collector is a utility that extends system table functionality by providing a
framework for recording events. It gathers and retains monitoring information about your database
cluster and makes that information available in system tables, requiring few configuration
parameter tweaks, and having negligible impact on performance.
Collected data is stored on disk in the DataCollector directory under the HP Vertica /catalog path.
You can use the information the Data Collector retains to query the past state of system tables and
extract aggregate information, as well as do the following:
l

See what actions users have taken

l

Locate performance bottlenecks

l

Identify potential improvements to HP Vertica configuration

Data Collector works in conjunction with an advisor tool called Workload Analyzer, which
intelligently monitors the performance of SQL queries and workloads and recommends tuning
actions based on observations of the actual workload history.
By default, Data Collector is on and retains information for all sessions. If performance issues
arise, a superuser can disable DC. See Data Collector Parameters and Enabling and Disabling
Data Collector in the Administrator's Guide.
This section describes the Data Collection control functions.

Related Topics
V_MONITOR.DATA_COLLECTOR
Retaining monitoring information and Analyzing Workloads in the Administrator's Guide

CLEAR_DATA_COLLECTOR
Clears all memory and disk records on the Data Collector tables and functions and resets collection
statistics in the V_MONITOR.DATA_COLLECTOR system table. A superuser can clear Data
Collector data for all components or specify an individual component
After you clear the Data Collector log, the information is no longer available for querying.

Syntax
CLEAR_DATA_COLLECTOR( [ 'component' ] )

HP Vertica Analytic Database (7.0.x)

Page 746 of 1539

SQL Reference Manual
SQL Functions

Parameters
component

Clears memory and disk records for the specified component only. If you provide no
argument, the function clears all Data Collector memory and disk records for all
components.
For the current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table.

Privileges
Must be a superuser.

Examples
The following command clears memory and disk records for the ResourceAcquisitions component:
=> SELECT clear_data_collector('ResourceAcquisitions');
clear_data_collector
---------------------CLEAR
(1 row)

The following command clears data collection for all components on all nodes:
=> SELECT clear_data_collector();
clear_data_collector
---------------------CLEAR
(1 row)

See Also
DATA_COLLECTOR

l
l

DATA_COLLECTOR_HELP
Returns online usage instructions about the Data Collector, the DATA_COLLECTOR system table, and
the Data Collector control functions.

Syntax
DATA_COLLECTOR_HELP()

HP Vertica Analytic Database (7.0.x)

Page 747 of 1539

SQL Reference Manual
SQL Functions

Privileges
None

Returns
The DATA_COLLECTOR_HELP() function returns the following information:
=> SELECT DATA_COLLECTOR_HELP();
----------------------------------------------------------------------------Usage Data Collector
The data collector retains history of important system activities.
This data can be used as a reference of what actions have been taken
by users, but it can also be used to locate performance bottlenecks,
or identify potential improvements to the Vertica configuration.
This data is queryable via Vertica system tables.
Acccess a list of data collector components, and some statistics, by running:
SELECT * FROM v_monitor.data_collector;
The amount of data retained by size and time can be controlled with several
functions.
To just set the size amount:
set_data_collector_policy(,
,
);
To set both the size and time amounts (the smaller one will dominate):
set_data_collector_policy(,
,
,
);
To set just the time amount:
set_data_collector_time_policy(,
);
To set the time amount for all tables:
set_data_collector_time_policy();
The current retention policy for a component can be queried with:
get_data_collector_policy();
Data on disk is kept in the "DataCollector" directory under the Vertica
\catalog path. This directory also contains instructions on how to load
the monitoring data into another Vertica database.
To move the data collector logs and instructions to other storage locations,
create labeled storage locations using add_location and then use:
set_data_collector_storage_location();
Additional commands can be used to configure the data collection logs.

HP Vertica Analytic Database (7.0.x)

Page 748 of 1539

SQL Reference Manual
SQL Functions

The log can be cleared with:
clear_data_collector([]);
The log can be synchronized with the disk storage using:
flush_data_collector([]);

See Also
l

DATA_COLLECTOR

l

TUNING_RECOMMENDATIONS

l

Analyzing Workloads

l

Retaining Monitoring Information

FLUSH_DATA_COLLECTOR
Waits until memory logs are moved to disk and then flushes the Data Collector, synchronizing the
log with the disk storage. A superuser can flush Data Collector information for an individual
component or for all components.

Syntax
FLUSH_DATA_COLLECTOR( [ 'component' ] )

Parameters
component

Flushes the specified component. If you provide no argument, the function flushes
the Data Collector in full.
For the current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table.

Privileges
Must be a superuser.

Examples
The following command flushes the Data Collector for the ResourceAcquisitions component:
=> SELECT flush_data_collector('ResourceAcquisitions');

HP Vertica Analytic Database (7.0.x)

Page 749 of 1539

SQL Reference Manual
SQL Functions

flush_data_collector
---------------------FLUSH
(1 row)

The following command flushes data collection for all components:
=> SELECT flush_data_collector();
flush_data_collector
---------------------FLUSH
(1 row)

See Also
DATA_COLLECTOR

l
l

GET_DATA_COLLECTOR_POLICY
Retrieves a brief statement about the retention policy for the specified component.

Syntax
GET_DATA_COLLECTOR_POLICY( 'component' )

Parameters
component

Returns the retention policy for the specified component.
For a current list of component names, query the V_MONITOR.DATA_
COLLECTOR system table

Privileges
None

Example
The following query returns the history of all resource acquisitions by specifying the
ResourceAcquisitions component:
=> SELECT get_data_collector_policy('ResourceAcquisitions');

HP Vertica Analytic Database (7.0.x)

Page 750 of 1539

SQL Reference Manual
SQL Functions

get_data_collector_policy
---------------------------------------------1000KB kept in memory, 10000KB kept on disk.
(1 row)

See Also
DATA_COLLECTOR

l
l

SET_DATA_COLLECTOR_POLICY
Sets a size restraint (memory and disk space in kilobytes) for the specified Data Collector table on
all nodes. If nodes are down, the failed nodes receive the setting when they rejoin the cluster.
You can use this function to set a size restraint only, or you can include the optional interval
argument to set disk capacity for both size and time in a single command.
If you specify interval, HP Vertica enforces the setting that is exceeded first (size or time).
Before you include a time restraint, be sure the disk size capacity is sufficiently large.
If you want to specify just a time restraint, or you want to turn off a time restraint you set using this
function, see SET_DATA_COLLECTOR_TIME_POLICY().

Syntax
SET_DATA_COLLECTOR_POLICY('component', 'memoryKB', 'diskKB' [,'interval']

)

Parameters
component

Configures the retention policy for the specified component.

memoryKB

Specifies the memory size to retain in kilobytes.

diskKB

Specifies the disk size in kilobytes.

interval

[Default off] Takes an optional interval argument to specify how long to retain the
specified component on disk. To disable a time restraint, set interval to -1.
Note: Any negative input will turn off the time restraint

Privileges
Must be a superuser.

HP Vertica Analytic Database (7.0.x)

Page 751 of 1539

SQL Reference Manual
SQL Functions

Notes
l

Before you change a retention policy, view its current setting by calling the GET_DATA_
COLLECTOR_POLICY() function.

l

If you don't know the name of a component, query the V_MONITOR.DATA_COLLECTOR system
table for a list; for example:
=> SELECT DISTINCT component, description FROM data_collector
ORDER BY 1 ASC;

Examples
The following command returns the retention policy for the ResourceAcquisitions component:
=> SELECT get_data_collector_policy('ResourceAcquisitions');
get_data_collector_policy
---------------------------------------------1000KB kept in memory, 10000KB kept on disk.
(1 row)

This command changes the memory and disk setting for ResourceAcquisitions from its current
setting of 1,000 KB memory and 10,000 KB disk space to 1500 KB and 25000 KB, respectively:
=> SELECT set_data_collector_policy('ResourceAcquisitions', '1500', '25000');
set_data_collector_policy
--------------------------SET
(1 row)

This command sets the RequestsIssued component to 1500 KB memory and 11000 KB on disk,
and includes a 3-minute time restraint:
=> SELECT set_data_collector_policy('RequestsIssued', '1500', '11000', '3 minutes'::inter
val);
set_data_collector_policy
--------------------------SET
(1 row)

The following command disables the 3-minute retention policy for the RequestsIssued component:
=> SELECT set_data_collector_policy('RequestsIssued', '-1');
set_data_collector_policy
--------------------------SET
(1 row)

HP Vertica Analytic Database (7.0.x)

Page 752 of 1539

SQL Reference Manual
SQL Functions

See Also
l

GET_DATA_COLLECTOR_POLICY

l

SET_DATA_COLLECTOR_TIME_POLICY()

l

DATA_COLLECTOR

l

Retaining Monitoring Information in the Administrator's Guide

SET_DATA_COLLECTOR_TIME_POLICY
Sets a time capacity for individual Data Collector tables on all nodes. If nodes are down, the failed
nodes receive the setting when they rejoin the cluster.
If you want to configure both time and size restraints at the same time, see SET_DATA_COLLECTOR_
POLICY().

Syntax
SET_DATA_COLLECTOR_TIME_POLICY( ['component',] 'interval' )

Parameters
component

[Optional] Configures the time retention policy for the specified component. If you
omit the component argument, HP Vertica sets the specified time capacity for all
Data Collector tables.

interval

Specifies the time restraint on disk using an INTERVAL type. To disable a time
restraint, set interval to -1.
Note: Any negative input turns off the time restraint

Privileges
Must be a superuser.

Notes
l

Before you change a retention policy, view its current setting by calling the GET_DATA_
COLLECTOR_POLICY() function.

l

If you don't know the name of a component, query the V_MONITOR.DATA_COLLECTOR system
table for a list. For example:

HP Vertica Analytic Database (7.0.x)

Page 753 of 1539

SQL Reference Manual
SQL Functions

=> SELECT DISTINCT component, description FROM data_collector
ORDER BY 1 ASC;

Setting time interval for system tables
You can also use the interval argument to query system tables the same way you query Data
Collector tables; for example:
set_data_collector_time_policy('', <'interval'>);

To illustrate, the following command in the left column is equivalent to running the series of
commands on the right:
Run one command

Instead of a series of commands

SELECT set_data_collector_time_policy
('v_monitor.query_requests',
'3 minutes'::interval);

SELECT set_data_collector_time_policy
('RequestsIssued',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('RequestsCompleted',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('Errors',
'3 minutes'::interval);
SELECT set_data_collector_time_policy
('ResourceAcquisitions',
'3 minutes'::interval);

The SET_DATA_COLLECTOR_TIME_POLICY() function updates the time capacity for all Data
Collector tables in the V_MONITOR.QUERY_REQUESTS view. The new setting overrides any previous
settings for every Data Collector table in that view.

Examples
The following command configures the Backups component to be retained on disk for 1 day:
=> SELECT set_data_collector_time_policy('Backups', '1 day'::interval);
set_data_collector_time_policy
-------------------------------SET
(1 row)

This command disables the 1-day restraint for the Backups component:
=> SELECT set_data_collector_time_policy('Backups', '-1');

HP Vertica Analytic Database (7.0.x)

Page 754 of 1539

SQL Reference Manual
SQL Functions

set_data_collector_time_policy
-------------------------------SET
(1 row)

This command sets a 30-minute time capacity for all Data Collector tables in a single command:
=> SELECT set_data_collector_time_policy('30 minutes'::interval);
set_data_collector_time_policy
-------------------------------SET
(1 row)

To view current retention policy settings for each Data Collector table, call the GET_DATA_
COLLECTION_POLICY() function. In the next example, the time restraint is included.
=> SELECT get_data_collector_policy('RequestsIssued');
get_data_collector_policy
----------------------------------------------------------------------------2000KB kept in memory, 50000KB kept on disk. 2 years 3 days 15:08 hours kept
on disk.
(1 row)

If the time policy setting is disabled, the output of GET_DATA_COLLECTION_POLICY() returns "Time
based retention disabled."
2000KB kept in memory, 50000KB kept on disk. Time based retention disabled.

See Also
l

GET_DATA_COLLECTOR_POLICY

l

SET_DATA_COLLECTOR_POLICY

l

DATA_COLLECTOR

HP Vertica Analytic Database (7.0.x)

Page 755 of 1539

SQL Reference Manual
SQL Functions

Database Designer Functions
The Database Designer functions allow you to access Database Designer functionality outside the
Administration Tools.

Permissions
To run the Database Designer functions, you must be one of the following:
l

Superuser

l

Have been granted the DBDUSER role and executed the SET ROLE DBDUSER command.
Once you have been granted the DBDUSER role, the role is in effect until it is revoked.
Important: When you grant the DBDUSER role, make sure to associate a resource pool
with that user to manage resources during Database Designer runs. Multiple users can run
Database Designer concurrently without interfering with each other or using up all the
cluster resources. When a user runs Database Designer, either using the Administration
Tools or programmatically, its execution is mostly contained by the user's resource pool,
but may spill over into some system resource pools for less-intensive tasks.

You can run Database Designer functions in vsql:

Setup Functions
This function directs Database Designer to create a new design:
l

DESIGNER_CREATE_DESIGN

Configuration Functions
The following functions allow you to specify properties of a particular design:
l

DESIGNER_DESIGN_PROJECTION_ENCODINGS

l

DESIGNER_SET_DESIGN_KSAFETY

l

DESIGNER_SET_OPTIMIZATION_OBJECTIVE

l

DESIGNER_SET_DESIGN_TYPE

l

DESIGNER_SET_PROPOSED_UNSEGMENTED_PROJECTIONS

l

DESIGNER_SET_ANALYZE_CORRELATIONS_MODE

HP Vertica Analytic Database (7.0.x)

Page 756 of 1539

SQL Reference Manual
SQL Functions

Input Functions
The following functions allow you to add tables and queries to your Database Designer design:
l

DESIGNER_ADD_DESIGN_QUERIES

l

DESIGNER_ADD_DESIGN_QUERIES_FROM RESULTS

l

DESIGNER_ADD_DESIGN_QUERY

l

DESIGNER_ADD_DESIGN_TABLES

Invocation Functions
These functions populate the Database Designer workspace and create design and deployment
scripts. You can also analyze statistics, deploy the design automatically, and drop the workspace
after the deployment:
l

DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY

l

DESIGNER_WAIT_FOR_DESIGN

Output Functions
The following functions display information about projections and scripts that the Database
Designer created:
l

DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS

l

DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT

Cleanup Functions
The following functions cancel any running Database Designer operation or drop a Database
Designer design and all its contents:
l

DESIGNER_CANCEL_POPULATE_DESIGN

l

DESIGNER_DROP_DESIGN

l

DESIGNER_DROP_ALL_DESIGNS

DESIGNER_ADD_DESIGN_QUERIES
Reads and parses all queries in the specified file. Adds accepted queries to the design and sets the
weight of each accepted query to 1.

HP Vertica Analytic Database (7.0.x)

Page 757 of 1539

SQL Reference Manual
SQL Functions

Behavior Type
Immutable

Syntax
DESIGNER_ADD_DESIGN_QUERIES (
'design_name',
'file_name',
'informative_output' )

Parameters
design_name

Name of the design to which to add the queries, type VARCHAR.

file_name

Absolute path to the queries file, type VARCHAR.

informative_output

Specifies verbose output, type BOOLEAN. Default: 'false'. If 'true', the
output lists:
l

Number of accepted queries

l

Number of queries referencing non-design tables

l

Number of unsupported queries

l

Number of illegal queries

l

Maximum number of queries was reached, if applicable. Only valid if the
optimization objective is set to INCREMENTAL.

Permissions
l

To run DESIGNER_ADD_DESIGN_QUERIES, you must be a superuser, a user granted the
DBDUSER role, or the user who created the design.

l

You must have READ privilege on the storage location of the queries file.

l

You must have sufficient privileges to execute all queries in the queries file.

Notes
l

You must run DESIGNER_ADD_DESIGN_TABLES before you run DESIGNER_ADD_
DESIGN_QUERIES. If no tables have been added to the design, HP Vertica does not accept

HP Vertica Analytic Database (7.0.x)

Page 758 of 1539

SQL Reference Manual
SQL Functions

the design queries.
l

l

l

Database Designer rejects a query and returns an error if the query:
n

Contains illegal syntax.

n

References only external tables or system tables.

n

Is a DELETE or UPDATE query with one or more subqueries.

n

References a local temporary table or other non-design table.

n

Is an INSERT query that does not include a SELECT clause.

n

Is unoptimizable by the Database Designer.

If the third parameter is 'true', DESIGNER_ADD_DESIGN_QUERIES returns the following
information:
n

Number of accepted queries

n

Number of queries referencing non-design tables

n

Number of unsupported queries

n

Number of illegal queries

n

If the number of accepted queries exceeds 100, DESIGNER_ADD_DESIGN_QUERIES
reports that as well. If you are running an incremental design, any queries after 100 are
ignored.

DESIGNER_ADD_DESIGN_QUERIES:
n

Populates the V_MONITOR.DESIGN_QUERIES system table.

n

Creates the V_MONITOR.OUTPUT_EVENT_HISTORY system table.

Examples
The following example adds the queries file vmart_queries.sql to the VMART_DESIGN design.
This file contains nine queries. Since the third parameter is 'true', DESIGNER_ADD_DESIGN_
QUERIES returns the results of adding the queries:
=> SELECT DESIGNER_ADD_DESIGN_QUERIES (
'VMART_DESIGN',
'/tmp/examples/vmart_queries.sql',
'true'
);
...
DESIGNER_ADD_DESIGN_QUERIES

HP Vertica Analytic Database (7.0.x)

Page 759 of 1539

SQL Reference Manual
SQL Functions

---------------------------------------------------Number of accepted queries
=9
Number of queries referencing non-design tables =0
Number of unsupported queries
=0
Number of illegal queries
=0
(1 row)

See Also
l

DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS

l

DESIGNER_ADD_DESIGN_QUERY

l

DESIGNER_ADD_DESIGN_TABLES

DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS
Parses and executes a user query and retrieves only queries that contain the following columns:
l

QUERY_TEXT: Text of potential design queries

l

QUERY_WEIGHT: Corresponding query weight values for the queries in QUERY_TEXT, a value
greater than 0 but no greater than 1. If empty, Database Designer sets the weight of that query to
1.

DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS parses all the retrieved queries and
adds all accepted queries to the design.

Behavior Type
Immutable

Syntax
DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS ( 'design_name', 'user_query' )

Parameters
design_name

Name of the design to which to add the queries, type VARCHAR.

user_query

A valid SQL query whose results contain columns named QUERY_TEXT and QUERY_
WEIGHT, type VARCHAR.

HP Vertica Analytic Database (7.0.x)

Page 760 of 1539

SQL Reference Manual
SQL Functions

Permissions
l

To run DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS, you must be a superuser
or a user granted the DBDUSER role who created the design.

l

You must have sufficient privileges to execute user_query and to execute each design query
retrieved from the results of user_query.

Notes
l

You must run DESIGNER_ADD_DESIGN_TABLES before you run DESIGNER_ADD_
DESIGN_QUERIES_FROM_RESULTS. If no tables have been added to the design, HP
Vertica does not accept the design queries.

l

An unlimited number of queries can be added to the design using DESIGNER_ADD_DESIGN_
QUERIES_FROM_RESULTS.

l

The  rejects a query and returns an error if the query:
n

Contains illegal syntax.

n

References only external tables.

n

Is a DELETE or UPDATE query with one or more subqueries.

n

References a local temporary table or other non-design table.

n

Is an INSERT query that does not include a SELECT clause.

n

Is unoptimizable by the Database Designer.

Example
The following example retrieves the query_text field from the 10 most recent queries in the
QUERY_REQUESTS system table QUERY_REQUESTS and adds the accepted queries to the
VMART_DESIGN design. QUERY_REQUESTS does not contains any weight value for those
queries:
=> SELECT DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS (
'VMART_DESIGN',
'SELECT request AS query_text FROM query_requests
ORDER BY start_timestamp DESC LIMIT 10;');
);

HP Vertica Analytic Database (7.0.x)

Page 761 of 1539

SQL Reference Manual
SQL Functions

See Also
l

DESIGNER_ADD_DESIGN_QUERIES

l

DESIGNER_ADD_DESIGN_TABLES

l

DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS

DESIGNER_ADD_DESIGN_QUERY
Reads and parses the specified query, and if accepted, adds it to the design.

Behavior Type
Immutable

Syntax
DESIGNER_ADD_DESIGN_QUERY (
'design_name',
'design_query',
query_weight )

Parameters
design_name

Name of the Database Designer design to which you want to add the query, type
VARCHAR.

design_query

Executable SQL query, type VARCHAR.

query_weight

Weight of query, any positive real number greater than 0 and no greater than 1.
Default: 1 You cannot add a weight of 0.
The weight of a query indicates its relative importance so that Database Designer
can prioritize the query when creating the design.

Permissions
l

To run DESIGNER_ADD_DESIGN_QUERY, you must be a superuser or a user granted the
DBDUSER role who created the design.

l

You must have sufficient privileges to execute the specified query.

HP Vertica Analytic Database (7.0.x)

Page 762 of 1539

SQL Reference Manual
SQL Functions

Notes
l

You must run DESIGNER_ADD_DESIGN_TABLES before you run DESIGNER_ADD_
DESIGN_QUERY. If no tables have been added to the design, HP Vertica does not accept the
design queries.

l

Database Designer rejects a query and returns an error if the query:
n

Contains illegal syntax.

n

References only external tables or system tables.

n

Is a DELETE or UPDATE query with one or more subqueries.

n

References a local temporary table or other non-design table.

n

Is an INSERT query that does not include a SELECT clause.

n

Is unoptimizable by the Database Designer.

Examples
The following example adds the specified query to the VMART_DESIGN design and assigns that
query a weight of 0.5:
=> SELECT DESIGNER_ADD_DESIGN_QUERY (
'VMART_DESIGN',
'SELECT customer_name, customer_type FROM vmart_design
ORDER BY customer_name ASC;',
0.5
);

See Also
l

DESIGNER_ADD_DESIGN_QUERIES

l

DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS

l

DESIGNER_ADD_DESIGN_TABLES

DESIGNER_ADD_DESIGN_TABLES
Adds the specified tables to a design.

Behavior Type
Immutable

HP Vertica Analytic Database (7.0.x)

Page 763 of 1539

SQL Reference Manual
SQL Functions

Syntax
DESIGNER_ADD_DESIGN_TABLES (
'design_name',
'table_pattern',
[ 'analyze_statistics']
)

Parameters
design_name

Name of the Database Designer design, type VARCHAR.

table_pattern

Comma-delimited list of tables, type VARCHAR. The table_pattern must
be one of the following:

analyze_statistics

l

'*' indicates to add all user tables in the current database.

l

'.*' indicates to add all tables in the specified schema.

l

'.' indicates to add the specified table in the specified
schema.

l

'
' indicates the specified table in the current search path. (Optional) BOOLEAN that specifies whether or not to analyze statistics for the design tables when adding them to the design. Default is 'false'. Accurate statistics help Database Designer optimize compression and query performance. Updating statistics takes time and resources. If 'true' , DESIGNER_ADD_DESIGN_TABLES executes the ANALYZE_ STATISTICS function. If ANALYZE_STATISTICS has previously run, set this parameter to 'false'. Permissions To run DESIGNER_ADD_DESIGN_TABLES and add tables to your design, you must be a superuser or a user granted the DBDUSER role who: l Created the design. l Has USAGE privilege on the design table schema. l Is the owner of the design table. Notes You must run DESIGNER_ADD_DESIGN_TABLES before you add design queries to the design. If no tables have been added to the design, HP Vertica does not accept the design queries. HP Vertica Analytic Database (7.0.x) Page 764 of 1539 SQL Reference Manual SQL Functions Examples The following example adds all the VMart tables to the VMART_DESIGN design, and analyzes statistics for those tables: => SELECT DESIGNER_ADD_DESIGN_TABLES( 'VMART_DESIGN', 'online_sales.*', 'true' ); DESIGNER_ADD_DESIGN_TABLES ---------------------------9 (1 row) => SELECT DESIGNER_ADD_DESIGN_TABLES( 'VMART_DESIGN', 'public.*', 'true' ); DESIGNER_ADD_DESIGN_TABLES ---------------------------9 (1 row) => SELECT DESIGNER_ADD_DESIGN_TABLES( 'VMART_DESIGN', 'store.*', 'true' ); DESIGNER_ADD_DESIGN_TABLES ---------------------------3 (1 row) See Also l DESIGNER_ADD_DESIGN_QUERIES l DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS l DESIGNER_ADD_DESIGN_QUERY DESIGNER_CANCEL_POPULATE_DESIGN Cancels the population or deployment operation for the specified design if it is currently running. Behavior Type Immutable HP Vertica Analytic Database (7.0.x) Page 765 of 1539 SQL Reference Manual SQL Functions Syntax DESIGNER_CANCEL_POPULATE_DESIGN ( 'design_name' ) Parameters design_name Name of a currently running design that you want to cancel, type VARCHAR. Permissions To run DESIGNER_CANCEL_POPULATE_DESIGN on a design, you must be a superuser, or a user granted the DBDUSER role who created the design. Notes l When you cancel a deployment, the Database Designer cancels the projection refresh operation. It does not roll back any projections that it has already deployed and refreshed. l Use DESIGNER_DROP_DESIGN to clean up any leftover files from the design. Examples The following example cancels a currently running design for VMART_DESIGN and then drops the design: => SELECT DESIGNER_CANCEL_POPULATE_DESIGN ('VMART_DESIGN');=> SELECT DESIGNER_DROP_DESIGN ('VMART_DESIGN'); See Also l DESIGNER_DROP_ALL_DESIGNS l DESIGNER_DROP_DESIGN DESIGNER_CREATE_DESIGN Creates a design with the specified name. Note: Be sure to back up the existing design using the EXPORT_CATALOG function before running the Database Designer functions on an existing schema. You must explicitly back up the existing design when using Database Designer programmatically. HP Vertica Analytic Database (7.0.x) Page 766 of 1539 SQL Reference Manual SQL Functions Behavior Type Immutable Syntax DESIGNER_CREATE_DESIGN ( 'design_name' ) Parameters design_name Name of the design you want to create, type VARCHAR. A Database Designer design name can only contain alphanumeric characters and underscore (_) characters. Permissions To run DESIGNER_CREATE_DESIGN, you must be a superuser, or a user granted the DBDUSER role. Notes l Two users may not have designs with the same name at the same time. l DESIGNER_CREATE_DESIGN creates the following system tables in the V_MONITOR schema: n DESIGNS n DESIGN_TABLES n DEPLOYMENT_PROJECTIONS n DEPLOYMENT_PROJECTION_STATEMENTS n DESIGN_QUERIES n OUTPUT_DEPLOYMENT_STATUS n OUTPUT_EVENT_HISTORY Examples The following example creates a design named VMART_DESIGN: HP Vertica Analytic Database (7.0.x) Page 767 of 1539 SQL Reference Manual SQL Functions => SELECT DESIGNER_CREATE_DESIGN('VMART_DESIGN'); DESIGNER_CREATE_DESIGN -----------------------0 (1 row) See Also l DESIGNER_DROP_DESIGN l DESIGNER_DROP_ALL_DESIGNS DESIGNER_DESIGN_PROJECTION_ENCODINGS Analyze encoding in the specified projections, create a script to implement encoding recommendations, and deploy the recommendations. Behavior Type Immutable Syntax DESIGNER_DESIGN_PROJECTION_ENCODINGS ( 'projection_list', 'projection_ddl_script_file, 'deploy' ) Parameters projection_list List of projections for which encoding analysis should be performed: l ''—All projections in the design l '.*'—All projections in the specified schema l '.'—The named projection in the specified schema l ''—The named projection in the PUBLIC schema. If you omit the schema name, DESIGNER_DESIGN_ PROJECTION_ENCODINGS uses the PUBLIC schema. HP Vertica Analytic Database (7.0.x) Page 768 of 1539 SQL Reference Manual SQL Functions projection_ddl_script_file deploy Script to deploy the encoding changes, type VARCHAR. Can be one of the following l Full path to script file l ''—Output results to STDOUT in a foreground process Specifies to deploy the encoding changes or not. Default: 'false'. Privileges l To run DESIGNER_DESIGN_PROJECTION_ENCODINGS on a design, you must n Be the OWNER of the projections for which you want to perform encoding analysis. n Have USAGE privilege on the schema that corresponds to all the specified projections. Examples The following example requests that Database Designer analyze the encoding of the projections of the online_sales schema in the VMart example database, save the SQL statements in the script file encodings.sql, but do not deploy the changes: => SELECT DESIGNER_DESIGN_PROJECTION_ENCODINGS ( 'online_sales.*', 'encodings.sql', 'false' ); DESIGNER_DESIGN_PROJECTION_ENCODINGS -------------------------------------(1 row) DESIGNER_DROP_ALL_DESIGNS Removes all Database Designer-related schemas associated with the current user. Use DESIGNER_DROP_ALL_DESIGNS to remove database objects after one or more Database Designer session completes. Behavior Type Immutable Syntax DESIGNER_DROP_ALL_DESIGNS() HP Vertica Analytic Database (7.0.x) Page 769 of 1539 SQL Reference Manual SQL Functions Parameters None. Privileges If the superuser runs DESIGNER_DROP_ALL_DESIGNS, all designs are dropped. If the DBDUSER runs DESIGNER_DROP_ALL_DESIGNS, the function only drops the designs that the DBDUSER created. Example The following example removes all schema and their contents associated with the current user. DESIGNER_DROP_ALL_DESIGNS returns the number of designs dropped: => SELECT DESIGNER_DROP_ALL_DESIGNS(); DESIGNER_DROP_ALL_DESIGNS --------------------------2 (1 row) See Also l DESIGNER_CANCEL_POPULATE_DESIGN l DESIGNER_DROP_DESIGN DESIGNER_DROP_DESIGN Removes the schema associated with the specified design and all its contents. Use DESIGNER_ DROP_DESIGN after a Database Designer design or deployment completes successfully or terminates unexpectedly. Behavior Type Immutable Syntax DESIGNER_DROP_DESIGN ( 'design_name' ) HP Vertica Analytic Database (7.0.x) Page 770 of 1539 SQL Reference Manual SQL Functions Parameters design_name Name of the design you want to drop, type VARCHAR. To drop all designs you have created, use DESIGNER_DROP_ALL_DESIGNS. Permissions You must be a superuser or a user granted the DBDUSER role who created the design, to run DESIGNER_DROP_DESIGN. Notes If a Database Designer session terminates unexpectedly, you cannot recreate that design with the same name unless you run DESIGNER_DROP_DESIGN to clean up any leftover files. Example The following example deletes the Database Designer design VMART_DESIGN, and all its contents: => SELECT DESIGNER_DROP_DESIGN ('VMART_DESIGN'); See Also l DESIGNER_CANCEL_POPULATE_DESIGN l DESIGNER_DROP_ALL_DESIGNS DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS Displays the DDL statements that define the design projections to STDOUT. Behavior Type Immutable Syntax DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS ( 'design_name' ) HP Vertica Analytic Database (7.0.x) Page 771 of 1539 SQL Reference Manual SQL Functions Parameters design_name Name of the design for which to display the DDL statements that create the design projections, type VARCHAR. Permissions You must be a superuser, or a user assigned the DBDUSER role, to run DESIGNER_OUTPUT_ ALL_DESIGN_PROJECTIONS. Examples The following example returns the design projection DDL statements for vmart_design: => SELECT DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS('vmart_design'); CREATE PROJECTION customer_dimension_DBD_1_rep_VMART_DESIGN /*createtype(D)*/ ( customer_key ENCODING DELTAVAL, customer_type ENCODING AUTO, customer_name ENCODING AUTO, customer_gender ENCODING REL, title ENCODING AUTO, household_id ENCODING DELTAVAL, customer_address ENCODING AUTO, customer_city ENCODING AUTO, customer_state ENCODING AUTO, customer_region ENCODING AUTO, marital_status ENCODING AUTO, customer_age ENCODING DELTAVAL, number_of_children ENCODING BLOCKDICT_COMP, annual_income ENCODING DELTARANGE_COMP, occupation ENCODING AUTO, largest_bill_amount ENCODING DELTAVAL, store_membership_card ENCODING BLOCKDICT_COMP, customer_since ENCODING DELTAVAL, deal_stage ENCODING AUTO, deal_size ENCODING DELTARANGE_COMP, last_deal_update ENCODING DELTARANGE_COMP ) AS SELECT customer_key, customer_type, customer_name, customer_gender, title, household_id, customer_address, customer_city, customer_state, customer_region, marital_status, HP Vertica Analytic Database (7.0.x) Page 772 of 1539 SQL Reference Manual SQL Functions customer_age, number_of_children, annual_income, occupation, largest_bill_amount, store_membership_card, customer_since, deal_stage, deal_size, last_deal_update FROM public.customer_dimension ORDER BY customer_gender, annual_income UNSEGMENTED ALL NODES; CREATE PROJECTION product_dimension_DBD_2_rep_VMART_DESIGN /*+createtype(D)*/ ( ... See Also l DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT Displays the deployment script for the specified design to STDOUT. The deployment script includes the CREATE PROJECTION commands that are also in the design script that you can display using DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS. If you have already deployed the design, this function does not return the script. Behavior Type Immutable Syntax DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT ( 'design_name' ) Parameters design_name Name of the design for which you want to display the deployment script, type VARCHAR. HP Vertica Analytic Database (7.0.x) Page 773 of 1539 SQL Reference Manual SQL Functions Permissions To run DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT, you must be a superuser or a user granted the DBDUSER role who created the design. Examples The following example displays the deployment script for VMART_DESIGN at STDOUT: => SELECT DESIGNER_OUTPUT_DEPLOYMENT_SCRIPT('VMART_DESIGN'); CREATE PROJECTION customer_dimension_DBD_1_rep_VMART_DESIGN /*createtype(D)*/ ... CREATE PROJECTION product_dimension_DBD_2_rep_VMART_DESIGN /*+createtype(D)*/ ... select refresh('public.customer_dimension, public.product_dimension, public.promotion.dimension, public.date_dimension'); select make_ahm_now(); DROP PROJECTION public.customer_dimension_super CASCADE; DROP PROJECTION public.product_dimension_super CASCADE; ... See Also l DESIGNER_OUTPUT_ALL_DESIGN_PROJECTIONS DESIGNER_RESET_DESIGN Clears the specified design but preserves the design's configuration such as parameters, tables, and queries. Running this function allows you to make additional changes to the design with or without deployment. DESIGNER_RESET_DESIGN discards all the run-specific information of the previous Database Designer build or deployment of the specified design but keeps its configuration. You can make changes to the design as needed, for example, by changing parameters or adding additional tables and/or queries, before rerunning the design. Behavior Type Immutable Syntax DESIGNER_RESET_DESIGN ( 'design_name' ) HP Vertica Analytic Database (7.0.x) Page 774 of 1539 SQL Reference Manual SQL Functions Parameters design_name Name of the design you want to reset, type VARCHAR. Permissions You must be a superuser or a user granted the DBDUSER role who created the design, to run DESIGNER_RESET_DESIGN. Example The following example resets the Database Designer design VMART_DESIGN: => SELECT DESIGNER_RESET_DESIGN ('VMART_DESIGN'); DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY Populates the design and creates the design and deployment scripts. If specified, DESIGNER_ RUN_POPULATE_DESIGN_AND_DEPLOY also analyzes statistics, deploys the design, and drops the workspace after the deployment. Note: Make sure to back up the existing design using the EXPORT_CATALOG function before running the Database Designer functions on an existing schema. You must explicitly back up the existing design when using Database Designer programmatically. Behavior Type Immutable Syntax DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY ( 'design_name', 'output_design_file', 'output_deployment_file', [ 'analyze_statistics', ] [ 'deploy', ] [ 'drop_design_workspace', ] [ 'continue_after_error', ] ) HP Vertica Analytic Database (7.0.x) Page 775 of 1539 SQL Reference Manual SQL Functions Parameters design_name Name of the design that you want to populate and deploy, type VARCHAR. output_design_file Absolute path for saving the file that contains the DDL statements that create the design projections, type VARCHAR. output_deployment_file Absolute path for saving the file that contains the deployment script, type VARCHAR. analyze_statistics (Optional) BOOLEAN that specifies whether or not to collect or refresh statistics for the tables before populating the design. Default is 'false'. Accurate statistics help Database Designer optimize compression and query performance. Updating statistics takes time and resources. If 'true', executes ANALYZE_STATISTICS. If ANALYZE_STATISTICS has run recently, set this parameter to 'false'. deploy (Optional) BOOLEAN that specifies whether or not to deploy the Database Designer design using the deployment script created by this function. Default: 'true'. drop_design_workspace (Optional) BOOLEAN that specifies whether or not to drop the design workspace after the design has been deployed. Default: 'true'. continue_after_error (Optional) BOOLEAN that specifies whether DESIGNER_RUN_ POPULATE_DESIGN_AND_DEPLOY should continue running if an error occurs. Default: 'false'. Permissions To run DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY, you must l Be a superuser, or a user granted the DBDUSER role who created the design. l Have WRITE privilege on the storage locations of the design and deployment scripts. If you do not have permission, DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY creates and deploys the design (if the deploy parameter is 'true'), but it cannot save the design and deployment scripts. HP Vertica Analytic Database (7.0.x) Page 776 of 1539 SQL Reference Manual SQL Functions Notes l l Prior to calling DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY, you must: n Create a design, a logical schema with tables. n Associates tables with the design. n Load queries to the design. n Set the design properties (K-safety level, mode, and policy) DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY does not create a backup copy of the current design before deploying the new design. Examples The following example creates projections for and deploys the VMART_DESIGN design, and analyzes statistics about the design tables. If an error occurs during execution, DESIGNER_RUN_ POPULATE_DESIGN_AND_DEPLOY terminates. => SELECT DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY ( 'VMART_DESIGN', '/tmp/examples/vmart_design_files/vmart_design_DDL', '/tmp/examples/vmart_design_files/vmart_design_deployment_scripts', 'true', 'false', 'false', ); DESIGNER_SET_ANALYZE_CORRELATIONS_MODE Specifies how Database Designer should handle column correlations in a design. Depending on what mode you set, Database Designer analyzes or reanalyzes existing column correlations and considers them when creating a database design.. Behavior Type Immutable Syntax DESIGNER_SET_ANALYZE_CORRELATIONS_MODE ( 'design_name', analyze_correlations_mode ) HP Vertica Analytic Database (7.0.x) Page 777 of 1539 SQL Reference Manual SQL Functions Parameters design_name Name of the design for which to specify how Database Designer handles correlated columns, type VARCHAR. analyze_correlations_mode Specifies the mode for analyzing correlations, type INTEGER. Default: 0. l 0—(Default) When creating a design, ignore any column correlations in the specified tables. l 1—Consider the existing correlations in the tables when creating the design. If you set the mode to 1, and there are no existing correlations, Database Designer does not consider correlations. l 2—Analyze column correlations on tables where the correlation analysis was not previously performed. When creating the design, consider all column correlations (new and existing). l 3—Analyze all column correlations in the tables and consider them when creating the design. Even if correlations exist for a table, reanalyze the table for correlations. Permissions l To run DESIGNER_SET_ANALYZE_CORRELATIONS_MODE on a design, you must be a superuser, or a user assigned the DBDUSER role with USAGE privilege on the design schema. Notes l Analyzing column correlations typically needs to be done only once. l HP Vertica recommends that you analyze correlations when the row count is at least DBDCorrelationSampleRowCount, which defaults to 4000. l To enable correlation analysis, you need to run DESIGNER_SET_ANALYZE_CORRELATIONS_ MODE for each design. HP Vertica Analytic Database (7.0.x) Page 778 of 1539 SQL Reference Manual SQL Functions l Setting the correlation analysis mode does not have any affect on whether or not Database Designer analyzes statistics when creating a design. Example The following example specifies that Database Designer analyze all correlated columns and consider them when creating a design: => SELECT DESIGNER_SET_ANALYZE_CORRELATIONS_MODE ( 'VMART_DESIGN', '3); DESIGNER_SET_ANALYZE_CORRELATIONS_MODE ---------------------------------------3 (1 row) See Also l ANALYZE_CORRELATIONS DESIGNER_SET_DESIGN_KSAFETY Sets the K-safety value for a comprehensive design and stores the K-safety value in the DESIGNS table. Behavior Type Immutable Syntax DESIGNER_SET_DESIGN_KSAFETY ( 'design_name' [, ksafety_level ] ) Parameters design_name Name of the design for which you want to set the K-safety value, type VARCHAR. HP Vertica Analytic Database (7.0.x) Page 779 of 1539 SQL Reference Manual SQL Functions ksafety_level Value of K-safety that you want for the specified design, type INTEGER. The value must be a valid K-safety value for your cluster. For example, if you have a three- or four-node cluster, you cannot set the K-safety to 2. If you do not set the design K-safety using this function, the defaults are: l Number of nodes = 1 or 2, K-safety = 0. l Number of nodes => 3, K-safety = 1. If you are a DBDUSER, the system K-safety value is unchanged after creating your design. If you are a DBADMIN user and you set the design K-safety to a value: l Lower than the system K-safety, the system K-safety changes to the lower value after Database Designer deploys the design. l Higher than the system K-safety, Database Designer creates the correct number of buddy projections for the specified value. If you create the design on all tables in the database, or all the tables in your database have the right number of buddy projections, Database Designer changes the system Ksafety to that value if it’s valid on your cluster. If you are not creating a design on all tables in the database and some of the tables do not have enough buddy projections, Database Designer gives a warning that the system K-safety cannot change and recommends which tables need buddy projections in order to raise the K -safety value. Permissions To run DESIGNER_SET_DESIGN_KSAFETY, you must be a superuser, or a user granted the DBDUSER role who created the design. Notes l You cannot change the K-safety value of an incremental design. Incremental designs assume the K-safety value of the database. Examples The following examples set the K-safety level for the VMART_DESIGN design: => SELECT DESIGNER_SET_DESIGN_KSAFETY('VMART_DESIGN', 1); => SELECT DESIGNER_SET_DESIGN_KSAFETY('VMART_DESIGN', 2); HP Vertica Analytic Database (7.0.x) Page 780 of 1539 SQL Reference Manual SQL Functions See Also l DESIGNER_SET_OPTIMIZATION_OBJECTIVE l DESIGNER_SET_DESIGN_TYPE l DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS DESIGNER_SET_DESIGN_TYPE Specifies whether Database Designer should create an initial or replacement design (the COMPREHENSIVE option) or make incremental changes to the existing design using the design queries you loaded into the design (the INCREMENTAL option). DESIGNER_SET_DESIGN_TYPE stores the design mode in the DESIGNS table. If you do not specify a design mode, Database Designer creates a comprehensive design. Behavior Type Immutable Syntax DESIGNER_SET_DESIGN_TYPE ( 'design_name', 'mode_name' ) Parameters design_name Name of the design for which you want to specify the design mode, type VARCHAR. mode_name Name of the mode that Database Designer should use when designing the database, type VARCHAR. Valid values are: l 'COMPREHENSIVE' l 'INCREMENTAL' Permissions You must be a superuser, or a user assigned the DBDUSER role, to run DESIGNER_SET_ DESIGN_TYPE. Notes Incremental designs always inherit the K-safety value of the database. HP Vertica Analytic Database (7.0.x) Page 781 of 1539 SQL Reference Manual SQL Functions Examples The following examples show the two design mode options for the VMART_DESIGN design: => SELECT DESIGNER_SET_DESIGN_TYPE( 'VMART_DESIGN', 'COMPREHENSIVE'); DESIGNER_SET_DESIGN_TYPE -------------------------0 (1 row) => SELECT DESIGNER_SET_DESIGN_TYPE( 'VMART_DESIGN', 'INCREMENTAL'); DESIGNER_SET_DESIGN_TYPE -------------------------0 (1 row) See Also l DESIGNER_SET_DESIGN_KSAFETY l DESIGNER_SET_OPTIMIZATION_OBJECTIVE l DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS DESIGNER_SET_OPTIMIZATION_OBJECTIVE Designates what optimization objective Database Designer should use when optimizing your database design: l QUERY—Optimize for query performance, so that the queries run faster. This can result in a larger database storage footprint because additional projections might be created. l LOAD—Optimize for load performance, so that the size of the database is minimized. This can result in slower query performance. l BALANCED—Balance the design between query performance and database size. DESIGNER_SET_OPTIMIZATION_OBJECTIVE stores the optimization objective in the DESIGNS table. Behavior Type Immutable HP Vertica Analytic Database (7.0.x) Page 782 of 1539 SQL Reference Manual SQL Functions Syntax DESIGNER_SET_OPTIMIZATION_OBJECTIVE ( 'design_name', 'policy_name' ) Parameters design_name Name of the design for which you want to specify the optimization policy, type VARCHAR. policy_name Name of the optimization policy for Database Designer to use when designing the database, type VARCHAR. Valid values are: l 'QUERY' l 'LOAD' l 'BALANCED' Permissions To run DESIGNER_SET_OPTIMIZATION_OBJECTIVE, you must be a superuser, or a user granted the DBDUSER role who created the design. Notes The optimization only applies to a comprehensive design; Database Designer ignores this value for incremental designs. Examples The following examples show the three optimization objective options for the VMART_DESIGN design: => SELECT DESIGNER_SET_OPTIMIZATION_OBJECTIVE( 'VMART_DESIGN', 'LOAD'); DESIGNER_SET_OPTIMIZATION_OBJECTIVE ----------------------------------0 (1 row) => SELECT DESIGNER_SET_OPTIMIZATION_OBJECTIVE( 'VMART_DESIGN', 'QUERY'); DESIGNER_SET_OPTIMIZATION_OBJECTIVE -----------------------------------0 (1 row) HP Vertica Analytic Database (7.0.x) Page 783 of 1539 SQL Reference Manual SQL Functions => SELECT DESIGNER_SET_OPTIMIZATION_OBJECTIVE( 'VMART_DESIGN', 'BALANCED'); DESIGNER_SET_OPTIMIZATION_OBJECTIVE -----------------------------------0 (1 row) See Also l DESIGNER_SET_DESIGN_KSAFETY l DESIGNER_SET_DESIGN_TYPE l DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS DESIGNER_SET_PROPOSE_UNSEGMENTED_ PROJECTIONS Specifies that Database Designer can propose unsegmented projections for all design tables and stores the setting in the DESIGNS table. Segmentation splits individual projections into chunks of data of similar size, called segments. One segment is created for and stored on each node. Projection segmentation provides high availability and recovery, and optimizes query execution. For more information about segmentation, see Projection Segmentation. Behavior Type Immutable Syntax DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS ( 'design_name', unsegmented ) Parameters design_name Name of the design for which you want segmented projections, type VARCHAR. unsegmented If 'true', Database Designer can proposed unsegmented projections for design tables. If 'false' (the default), Database Designer only proposes segmented projections. HP Vertica Analytic Database (7.0.x) Page 784 of 1539 SQL Reference Manual SQL Functions Permissions To run DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS, you must be a superuser, or a user granted the DBDUSER role who created the design. Notes DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS has no affect on one-node clusters; all projections will be unsegmented. Example The following example specifies that Database Designer propose a database design where all projections are segmented: => SELECT DESIGNER_SET_PROPOSE_UNSEGMENTED_PROJECTIONS( 'VMART_DESIGN', 'false'); See Also l DESIGNER_SET_DESIGN_KSAFETY l DESIGNER_SET_DESIGN_TYPE l DESIGNER_SET_OPTIMIZATION_OBJECTIVE DESIGNER_WAIT_FOR_DESIGN Waits for a currently running design to complete. DESIGNER_WAIT_FOR_DESIGN waits for operations that are populating and deploying the design. Behavior Type Immutable Syntax DESIGNER_WAIT_FOR_DESIGN ( 'design_name' ) Parameters design_name Name of the currently running design that you want to complete, type VARCHAR. HP Vertica Analytic Database (7.0.x) Page 785 of 1539 SQL Reference Manual SQL Functions Permissions To run DESIGNER_WAIT_FOR_DESIGN on a currently running design, you must be a superuser, or a user granted the DBDUSER role with USAGE privilege on the design schema. Notes If DESIGNER_WAIT_FOR_DESIGN is running in the foreground and still waiting, you can enter Ctrl+C to stop DESIGNER_WAIT_FOR_DESIGN and return control to the user. Examples The following example requests to wait for the currently running design of VMART_DESIGN to complete: => SELECT DESIGNER_WAIT_FOR_DESIGN ('VMART_DESIGN'); See Also l DESIGNER_CANCEL_POPULATE_DESIGN l DESIGNER_DROP_ALL_DESIGNS l DESIGNER_DROP_DESIGN HP Vertica Analytic Database (7.0.x) Page 786 of 1539 SQL Reference Manual SQL Functions Database Management Functions This section contains the database management functions specific to HP Vertica. CLEAR_RESOURCE_REJECTIONS Clears the content of the RESOURCE_REJECTIONS and DISK_RESOURCE_REJECTIONS system tables. Normally, these tables are only cleared during a node restart. This function lets you clear the tables whenever you need. For example, you might want to clear the system tables after you resolved a disk space issue that was causing disk resource rejections. Syntax CLEAR_RESOURCE_REJECTIONS(); Privileges Must be a superuser. Example The following command clears the content of the RESOURCE_REJECTIONS and DISK_ RESOURCE_REJECTIONS system tables: => SELECT clear_resource_rejections(); clear_resource_rejections --------------------------OK (1 row) See Also l DISK_RESOURCE_REJECTIONS l RESOURCE_REJECTIONS DUMP_LOCKTABLE Returns information about deadlocked clients and the resources they are waiting for. Syntax DUMP_LOCKTABLE() HP Vertica Analytic Database (7.0.x) Page 787 of 1539 SQL Reference Manual SQL Functions Privileges None Notes Use DUMP_LOCKTABLE if HP Vertica becomes unresponsive: 1. Open an additional vsql connection. 2. Execute the query: => SELECT DUMP_LOCKTABLE(); The output is written to vsql. See Monitoring the Log Files. You can also see who is connected using the following command: => SELECT * FROM SESSIONS; Close all sessions using the following command: =>SELECT CLOSE_ALL_SESSIONS(); Close a single session using the following command: => SELECT CLOSE_SESSION('session_id'); You get the session_id value from the V_MONITOR.SESSIONS system table. See Also l CLOSE_ALL_SESSIONS l CLOSE_SESSION l LOCKS l SESSIONS DUMP_PARTITION_KEYS Dumps the partition keys of all projections in the system. HP Vertica Analytic Database (7.0.x) Page 788 of 1539 SQL Reference Manual SQL Functions Syntax DUMP_PARTITION_KEYS( ) Note: The ROS objects of partitioned tables without partition keys are ignored by the tuple mover and are not merged during automatic tuple mover operations. Privileges None; however function dumps only the tables for which user has SELECT privileges. Example => SELECT DUMP_PARTITION_KEYS( ); Partition keys on node v_vmart_node0001 Projection 'states_b0' Storage [ROS container] No of partition keys: 1 Partition keys: NH Storage [ROS container] No of partition keys: 1 Partition keys: MA Projection 'states_b1' Storage [ROS container] No of partition keys: 1 Partition keys: VT Storage [ROS container] No of partition keys: 1 Partition keys: ME Storage [ROS container] No of partition keys: 1 Partition keys: CT See Also l DO_TM_TASK l DROP_PARTITION l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l PARTITION_TABLE HP Vertica Analytic Database (7.0.x) Page 789 of 1539 SQL Reference Manual SQL Functions l PARTITIONS l Working with Table Partitions EXPORT_TABLES Generates a SQL script that can be used to recreate a logical schema (schemas, tables, constraints, and views) on a different cluster. Syntax EXPORT_TABLES ( [ 'destination' ] , [ 'scope' ] ) Parameters destination Specifies the path and name of the SQL output file. An empty string (''), which is the default, outputs the script to standard output. The function writes the script to the catalog directory if no destination is specified. If you specify a file that does not exist, the function creates one. If the file preexists, the function silently overwrites its contents. scope Determines the tables to export. Specify the scope as follows: l An empty string (' ')—exports all non-virtual table objects to which the user has access, including table schemas, sequences, and constraints. Exporting all non-virtual objects is the default scope, and what the function exports if you do not specify a scope. l A comma-delimited list of objects, which can include the following: n ' [dbname.][schema.]object '—matches the named objects, which can be schemas, tables, or views, in the schema. You can optionally qualify a schema with a database prefix, and objects with a schema. You cannot pass constraints as individual arguments. n ' [dbname.]object '—matches a named object, which can be a schema, table, or view. You can optionally qualify a schema with a database prefix, and an object with its schema. For a schema, HP Vertica exports all non-virtual objects to which the user has access within the schema. If a schema and table both have the same name, the schema takes precedence. Privileges None; however: HP Vertica Analytic Database (7.0.x) Page 790 of 1539 SQL Reference Manual SQL Functions l Function exports only the objects visible to the user l Only a superuser can export output to file Example The following example exports the store_orders_fact table of the store schema (in the current database) to standard output: => SELECT EXPORT_TABLES(' ','store.store_orders_fact'); EXPORT_TABLES returns an error if: l You explicitly specify an object that does not exist l The current user does not have access to a specified object See Also EXPORT_CATALOG l EXPORT_OBJECTS l l HAS_ROLE Indicates, with a Boolean value, whether a role has been assigned to a user. This function is useful for letting you check your own role membership. Behavior Type Stable Syntax 1 HAS_ROLE( [ 'user_name' ,] 'role_name' ); Syntax 2 HAS_ROLE( 'role_name' ); HP Vertica Analytic Database (7.0.x) Page 791 of 1539 SQL Reference Manual SQL Functions Parameters user_name [Optional] The name of a user to look up. Currently, only a superuser can supply the user_name argument. role_name The name of the role you want to verify has been granted. Privileges Users can check their own role membership by calling HAS_ROLE('role_name'), but only a superuser can look up other users' memberships using the optional user_name parameter. Notes You can query V_CATALOG system tables ROLES, GRANTS, and USERS to show any directlyassigned roles; however, these tables do not indicate whether a role is available to a user when roles may be available through other roles (indirectly). Examples User Bob wants to see if he has been granted the commentor role: => SELECT HAS_ROLE('commentor'); Output t for true indicates that Bob has been assigned the commentor role: HAS_ROLE ---------t (1 row) In the following function call, a superuser checks if the logadmin role has been granted to user Bob: => SELECT HAS_ROLE('Bob', 'logadmin'); HAS_ROLE ---------t (1 row) To view the names of all roles users can access, along with any roles that have been assigned to those roles, query the V_CATALOG.ROLES system table. An asterisk in the output means role granted WITH ADMIN OPTION. => SELECT * FROM roles; HP Vertica Analytic Database (7.0.x) Page 792 of 1539 SQL Reference Manual SQL Functions role_id | name | assigned_roles -------------------+-----------------+---------------45035996273704964 | public | 45035996273704966 | dbduser | 45035996273704968 | dbadmin | dbduser* 45035996273704972 | pseudosuperuser | dbadmin* 45035996273704974 | logreader | 45035996273704976 | logwriter | 45035996273704978 | logadmin | logreader, logwriter (7 rows) See Also l GRANTS l ROLES l USERS l Managing Users and Privileges l Viewing a user's Role SET_CONFIG_PARAMETER Use SET_CONFIG_PARAMETER to specify the value of a configuration parameter. Note: HP Vertica is designed to operate with minimal configuration changes. Use this function sparingly and carefully follow any documented guidelines for that parameter. If a node is down when you invoke this function, changes will occur on UP nodes only. You must reissue the function after down nodes recover in order for the changes to take effect on those nodes. Alternatively, use the Administration Tools to copy the files. Redistributing Configuration Files to Nodes. Syntax SET_CONFIG_PARAMETER( 'parameter', value ) Parameters parameter Specifies the name of the parameter value being set. See Configuration Parameters in the Administrator's Guide for a list of supported parameters, their function, and usage examples. HP Vertica Analytic Database (7.0.x) Page 793 of 1539 SQL Reference Manual SQL Functions value Specifies the value of the supplied parameter argument. Syntax for this argument will vary depending upon the parameter and its expected data type. For strings, you must enclose the argument in single quotes; integer arguments can be unquoted. You can also query the V_MONITOR.CONFIGURATION_PARAMETERS system table to get information about configuration parameters currently in use by the system. Examples The following example sets the AnalyzeRowCountInterval parameter to 3600. SELECT SET_CONFIG_PARAMETER ('AnalyzeRowCountInterval',3600); The following statement returns all current configuration parameters and information about them, including their current and default values: => SELECT * FROM CONFIGURATION_PARAMETERS; SHUTDOWN Forces a database to shut down, even if there are users connected. Syntax SHUTDOWN ( [ 'false' | 'true' ] ) Parameters false [Default] Returns a message if users are connected. Has the same effect as supplying no parameters. true Performs a moveout operation and forces the database to shut down, disallowing further connections. Privileges Must be a superuser. Notes l Quotes around the true or false arguments are optional. HP Vertica Analytic Database (7.0.x) Page 794 of 1539 SQL Reference Manual SQL Functions l Issuing the shutdown command without arguments or with the default (false) argument returns a message if users are connected, and the shutdown fails. If no users are connected, the database performs a moveout operation and shuts down. l Issuing the SHUTDOWN('true') command forces the database to shut down whether users are connected or not. l You can check the status of the shutdown operation in the vertica.log file: 2010-03-09 16:51:52.625 unknown:0x7fc6d6d2e700 [Init] Shutdown complete. Exiting. l As an alternative to SHUTDOWN(), you can also temporarily set MaxClientSessions to 0 and then use CLOSE_ALL_SESSIONS(). New client connections cannot connect unless they connect using the dbadmin account. See CLOSE_ALL_SESSIONS for details. Examples The following command attempts to shut down the database. Because users are connected, the command fails: => SELECT SHUTDOWN('false'); NOTICE: Cannot shut down while users are connected SHUTDOWN ----------------------------Shutdown: aborting shutdown (1 row) SHUTDOWN() and SHUTDOWN('false') perform the same operation: => SELECT SHUTDOWN(); NOTICE: Cannot shut down while users are connected SHUTDOWN ----------------------------Shutdown: aborting shutdown (1 row) Using the 'true' parameter forces the database to shut down, even though clients might be connected: => SELECT SHUTDOWN('true'); SHUTDOWN ---------------------------Shutdown: moveout complete (1 row) HP Vertica Analytic Database (7.0.x) Page 795 of 1539 SQL Reference Manual SQL Functions See Also l SESSIONS HP Vertica Analytic Database (7.0.x) Page 796 of 1539 SQL Reference Manual SQL Functions Epoch Management Functions This section contains the epoch management functions specific to HP Vertica. ADVANCE_EPOCH Manually closes the current epoch and begins a new epoch. Syntax ADVANCE_EPOCH ( [ integer ] ) Parameters integer Specifies the number of epochs to advance. Privileges Must be a superuser. Notes This function is primarily maintained for backward compatibility with earlier versions of HP Vertica. Example The following command increments the epoch number by 1: => SELECT ADVANCE_EPOCH(1); See Also l ALTER PROJECTION RENAME GET_AHM_EPOCH Returns the number of the epoch in which the Ancient History Mark is located. Data deleted up to and including the AHM epoch can be purged from physical storage. Syntax GET_AHM_EPOCH() HP Vertica Analytic Database (7.0.x) Page 797 of 1539 SQL Reference Manual SQL Functions Note: The AHM epoch is 0 (zero) by default (purge is disabled). Privileges None Examples SELECT GET_AHM_EPOCH(); GET_AHM_EPOCH ---------------------Current AHM epoch: 0 (1 row) GET_AHM_TIME Returns a TIMESTAMP value representing the Ancient History Mark. Data deleted up to and including the AHM epoch can be purged from physical storage. Syntax GET_AHM_TIME() Privileges None Examples SELECT GET_AHM_TIME(); GET_AHM_TIME ------------------------------------------------Current AHM Time: 2010-05-13 12:48:10.532332-04 (1 row) See Also l SET DATESTYLE l TIMESTAMP HP Vertica Analytic Database (7.0.x) Page 798 of 1539 SQL Reference Manual SQL Functions GET_CURRENT_EPOCH The epoch into which data (COPY, INSERT, UPDATE, and DELETE operations) is currently being written. The current epoch advances automatically every three minutes. Returns the number of the current epoch. Syntax GET_CURRENT_EPOCH() Privileges None Examples SELECT GET_CURRENT_EPOCH(); GET_CURRENT_EPOCH ------------------683 (1 row) GET_LAST_GOOD_EPOCH A term used in manual recovery, LGE (Last Good Epoch) refers to the most recent epoch that can be recovered. Returns the number of the last good epoch. Syntax GET_LAST_GOOD_EPOCH() Privileges None Examples SELECT GET_LAST_GOOD_EPOCH(); GET_LAST_GOOD_EPOCH --------------------- HP Vertica Analytic Database (7.0.x) Page 799 of 1539 SQL Reference Manual SQL Functions 682 (1 row) MAKE_AHM_NOW Sets the Ancient History Mark (AHM) to the greatest allowable value, and lets you drop any projections that existed before the issue occurred. Caution: This function is intended for use by Administrators only. Syntax MAKE_AHM_NOW ( [ true ] ) Parameters true [Optional] Allows AHM to advance when nodes are down. Note: If the AHM is advanced after the last good epoch of the failed nodes, those nodes must recover all data from scratch. Use with care. Privileges Must be a superuser. Notes l l The MAKE_AHM_NOW function performs the following operations: n Advances the epoch. n Performs a moveout operation on all projections. n Sets the AHM to LGE — at least to the current epoch at the time MAKE_AHM_NOW() was issued. All history is lost and you cannot perform historical queries prior to the current epoch. Example => SELECT MAKE_AHM_NOW(); MAKE_AHM_NOW ------------------------------ HP Vertica Analytic Database (7.0.x) Page 800 of 1539 SQL Reference Manual SQL Functions AHM set (New AHM Epoch: 683) (1 row) The following command allows the AHM to advance, even though node 2 is down: => SELECT WARNING: WARNING: WARNING: MAKE_AHM_NOW(true); Received no response from v_vmartdb_node0002 in get cluster LGE Received no response from v_vmartdb_node0002 in get cluster LGE Received no response from v_vmartdb_node0002 in set AHM MAKE_AHM_NOW -----------------------------AHM set (New AHM Epoch: 684) (1 row) See Also l DROP PROJECTION l MARK_DESIGN_KSAFE l SET_AHM_EPOCH l SET_AHM_TIME SET_AHM_EPOCH Sets the Ancient History Mark (AHM) to the specified epoch. This function allows deleted data up to and including the AHM epoch to be purged from physical storage. SET_AHM_EPOCH is normally used for testing purposes. Consider SET_AHM_TIME instead, which is easier to use. Syntax SET_AHM_EPOCH ( epoch, [ true ] ) Parameters epoch Specifies one of the following: l The number of the epoch in which to set the AHM l Zero (0) (the default) disables PURGE HP Vertica Analytic Database (7.0.x) Page 801 of 1539 SQL Reference Manual SQL Functions true Optionally allows the AHM to advance when nodes are down. Note: If the AHM is advanced after the last good epoch of the failed nodes, those nodes must recover all data from scratch. Use with care. Privileges Must be a superuser. Notes If you use SET_AHM_EPOCH , the number of the specified epoch must be: l Greater than the current AHM epoch l Less than the current epoch l Less than or equal to the cluster last good epoch (the minimum of the last good epochs of the individual nodes in the cluster) l Less than or equal to the cluster refresh epoch (the minimum of the refresh epochs of the individual nodes in the cluster) Use the SYSTEM table to see current values of various epochs related to the AHM; for example: => SELECT * from SYSTEM; -[ RECORD 1 ]------------+--------------------------current_timestamp | 2009-08-11 17:09:54.651413 current_epoch | 1512 ahm_epoch | 961 last_good_epoch | 1510 refresh_epoch | -1 designed_fault_tolerance | 1 node_count | 4 node_down_count | 0 current_fault_tolerance | 1 catalog_revision_number | 1590 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 41490783 ros_row_count | 1298104 total_used_bytes | 41490783 total_row_count | 1298104 All nodes must be up. You cannot use SET_AHM_EPOCH when any node in the cluster is down, except by using the optional true parameter. When a node is down and you issue SELECT MAKE_AHM_NOW(), the following error is printed to the vertica.log: HP Vertica Analytic Database (7.0.x) Page 802 of 1539 SQL Reference Manual SQL Functions Some nodes were excluded from setAHM. If their LGE is before the AHM they will perform fu ll recovery. Examples The following command sets the AHM to a specified epoch of 12: => SELECT SET_AHM_EPOCH(12); The following command sets the AHM to a specified epoch of 2 and allows the AHM to advance despite a failed node: => SELECT SET_AHM_EPOCH(2, true); See Also l MAKE_AHM_NOW l SET_AHM_TIME l SYSTEM SET_AHM_TIME Sets the Ancient History Mark (AHM) to the epoch corresponding to the specified time on the initiator node. This function allows historical data up to and including the AHM epoch to be purged from physical storage. Syntax SET_AHM_TIME ( time , [ true ] ) Parameters time Is a TIMESTAMP value that is automatically converted to the appropriate epoch number. true [Optional] Allows the AHM to advance when nodes are down. Note: If the AHM is advanced after the last good epoch of the failed nodes, those nodes must recover all data from scratch. Privileges Must be a superuser. HP Vertica Analytic Database (7.0.x) Page 803 of 1539 SQL Reference Manual SQL Functions Notes l SET_AHM_TIME returns a TIMESTAMP WITH TIME ZONE value representing the end point of the AHM epoch. l You cannot change the AHM when any node in the cluster is down, except by using the optional true parameter. l When a node is down and you issue SELECT MAKE_AHM_NOW(), the following error is printed to the vertica.log: Some nodes were excluded from setAHM. If their LGE is before the AHM they will perform full recovery. Examples Epochs depend on a configured epoch advancement interval. If an epoch includes a three-minute range of time, the purge operation is accurate only to within minus three minutes of the specified timestamp: => SELECT SET_AHM_TIME('2008-02-27 18:13'); set_ahm_time -----------------------------------AHM set to '2008-02-27 18:11:50-05' (1 row) Note: The –05 part of the output string is a time zone value, an offset in hours from UTC (Universal Coordinated Time, traditionally known as Greenwich Mean Time, or GMT). In the previous example, the actual AHM epoch ends at 18:11:50, roughly one minute before the specified timestamp. This is because SET_AHM_TIME selects the epoch that ends at or before the specified timestamp. It does not select the epoch that ends after the specified timestamp because that would purge data deleted as much as three minutes after the AHM. For example, using only hours and minutes, suppose that epoch 9000 runs from 08:50 to 11:50 and epoch 9001 runs from 11:50 to 15:50. SET_AHM_TIME('11:51') chooses epoch 9000 because it ends roughly one minute before the specified timestamp. In the next example, if given an environment variable set as date =`date`; the following command fails if a node is down: => SELECT SET_AHM_TIME('$date'); In order to force the AHM to advance, issue the following command instead: => SELECT SET_AHM_TIME('$date', true); HP Vertica Analytic Database (7.0.x) Page 804 of 1539 SQL Reference Manual SQL Functions See Also l MAKE_AHM_NOW l SET_AHM_EPOCH l SET DATESTYLE l TIMESTAMP Flex Table Functions This section contains helper functions for use in working with flex tables. Note: While the functions are available to all users, they are applicable only to flex table, their associated flex_table_keys table and flex_table_view views. By computing keys and creating views from flex table data, the functions facilitate SELECT queries. One function restores the original keys table and view that were made when you first created the flex table. For more information, see the Flex Tables Guide. COMPUTE_FLEXTABLE_KEYS Computes the virtual columns (keys and values) from the map data of a flex table and repopulates the associated _keys table. The keys table has the following columns: l key_name l frequency l data_type_guess This function sorts the keys table by frequency and key_name. Use this function to compute keys without creating an associated table view. To build a view as well, use COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW. Usage compute_flextable_keys('flex_table') Arguments flex_table The name of the flex table. HP Vertica Analytic Database (7.0.x) Page 805 of 1539 SQL Reference Manual SQL Functions Examples During execution, this function determines a data type for each virtual column, casting the values it computes to VARCHAR, LONG VARCHAR, or LONG VARBINARY, depending on the length of the key, and whether the key includes nested maps. The following examples illustrate this function and the results of populating the _keys table, once you've created a flex table (darkdata1) and loaded data: kdb=> create flex table darkdata1(); CREATE TABLE kdb=> copy darkdata1 from '/test/flextable/DATA/tweets_12.json' parser fjsonparser(); Rows Loaded ------------12 (1 row) kdb=> select compute_flextable_keys('darkdata1'); compute_flextable_keys -------------------------------------------------Please see public.darkdata1_keys for updated keys (1 row) kdb=> select * from darkdata1_keys; key_name | frequency | data_type_guess ----------------------------------------------------------+-----------+--------------------contributors | 8 | varchar(20) coordinates | 8 | varchar(20) created_at | 8 | varchar(60) entities.hashtags | 8 | long varbinary(18 6) entities.urls | 8 | long varbinary(3 2) entities.user_mentions | 8 | long varbinary(67 4) . . . retweeted_status.user.time_zone | 1 | varchar(20) retweeted_status.user.url | 1 | varchar(68) retweeted_status.user.utc_offset | 1 | varchar(20) retweeted_status.user.verified | 1 | varchar(20) (125 rows) The flex keys table has these columns: Column Description key_name The name of the virtual column (key). frequency The number of times the virtual column occurs in the map. HP Vertica Analytic Database (7.0.x) Page 806 of 1539 SQL Reference Manual SQL Functions Column Description data_ type_ guess The data type for each virtual column, cast to VARCHAR, LONG VARCHAR or LONG VARBINARY, depending on the length of the key, and whether the key includes one or more nested maps. In the _keys table output, the data_type_guess column values are also followed by a value in parentheses, such as varchar(20). The value indicates the padded width of the key column, as calculated by the longest field, multiplied by the FlexTableDataTypeGuessMultiplier configuration parameter value. For more information, see Setting Flex Table Parameters. See Also l BUILD_FLEXTABLE_VIEW l COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW l MATERIALIZE_FLEXTABLE_COLUMNS l RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW COMPUTE_FLEXTABLE_KEYS Computes the virtual columns (keys and values) from the map data of a flex table and repopulates the associated _keys table. The keys table has the following columns: l key_name l frequency l data_type_guess This function sorts the keys table by frequency and key_name. Use this function to compute keys without creating an associated table view. To build a view as well, use COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW. Usage compute_flextable_keys('flex_table') Arguments flex_table The name of the flex table. HP Vertica Analytic Database (7.0.x) Page 807 of 1539 SQL Reference Manual SQL Functions Examples During execution, this function determines a data type for each virtual column, casting the values it computes to VARCHAR, LONG VARCHAR, or LONG VARBINARY, depending on the length of the key, and whether the key includes nested maps. The following examples illustrate this function and the results of populating the _keys table, once you've created a flex table (darkdata1) and loaded data: kdb=> create flex table darkdata1(); CREATE TABLE kdb=> copy darkdata1 from '/test/flextable/DATA/tweets_12.json' parser fjsonparser(); Rows Loaded ------------12 (1 row) kdb=> select compute_flextable_keys('darkdata1'); compute_flextable_keys -------------------------------------------------Please see public.darkdata1_keys for updated keys (1 row) kdb=> select * from darkdata1_keys; key_name | frequency | data_type_guess ----------------------------------------------------------+-----------+--------------------contributors | 8 | varchar(20) coordinates | 8 | varchar(20) created_at | 8 | varchar(60) entities.hashtags | 8 | long varbinary(18 6) entities.urls | 8 | long varbinary(3 2) entities.user_mentions | 8 | long varbinary(67 4) . . . retweeted_status.user.time_zone | 1 | varchar(20) retweeted_status.user.url | 1 | varchar(68) retweeted_status.user.utc_offset | 1 | varchar(20) retweeted_status.user.verified | 1 | varchar(20) (125 rows) The flex keys table has these columns: Column Description key_name The name of the virtual column (key). frequency The number of times the virtual column occurs in the map. HP Vertica Analytic Database (7.0.x) Page 808 of 1539 SQL Reference Manual SQL Functions Column Description data_ type_ guess The data type for each virtual column, cast to VARCHAR, LONG VARCHAR or LONG VARBINARY, depending on the length of the key, and whether the key includes one or more nested maps. In the _keys table output, the data_type_guess column values are also followed by a value in parentheses, such as varchar(20). The value indicates the padded width of the key column, as calculated by the longest field, multiplied by the FlexTableDataTypeGuessMultiplier configuration parameter value. For more information, see Setting Flex Table Parameters. See Also l BUILD_FLEXTABLE_VIEW l COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW l MATERIALIZE_FLEXTABLE_COLUMNS l RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW Combines the functionality of BUILD_FLEXTABLE_VIEW and COMPUTE_FLEXTABLE_KEYS to compute virtual columns (keys) from the map data of a flex table , and construct a view. If you don't need to perform both operations together, use one of the single-operation functions. Usage compute_flextable_keys_and_build_view('flex_table') Arguments flex_table The name of a flex table. Examples The following example calls the function for the darkdata flex table. kdb=> select compute_flextable_keys_and_build_view('darkdata'); compute_flextable_keys_and_build_view ----------------------------------------------------------------------Please see public.darkdata_keys for updated keys The view public.darkdata_view is ready for querying HP Vertica Analytic Database (7.0.x) Page 809 of 1539 SQL Reference Manual SQL Functions (1 row) See Also l BUILD_FLEXTABLE_VIEW l COMPUTE_FLEXTABLE_KEYS l MATERIALIZE_FLEXTABLE_COLUMNS l RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW MATERIALIZE_FLEXTABLE_COLUMNS Materializes virtual columns that are listed as key_names in the flextable_keys table. You can optionally indicate the number of columns to materialize, and use a keys table other than the default. If you do not specify the number of columns, the function materializes up to 50 virtual column key names. Calling this function requires that you first compute flex table keys using either COMPUTE_FLEXTABLE_KEYS or COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW . Note: Materializing any virtual column into a real column with this function affects data storage limits. Each materialized column counts against the data storage limit of your HP Vertica Enterprise Edition (EE) license. This increase is reflected when HP Vertica next performs a license compliance audit. To manually check your EE license compliance, call the audit() function, described in the SQL Reference Manual. Usage materialize_flextable_columns('flex_table' [, n-columns [, keys_table_name] ]) Arguments flex_table The name of the flex table with columns to materialize. Specifying only the flex table name attempts to materialize up to 50 columns of key names in the default flex_table_keys table, skipping any columns already materialized. To materialize a specific number of columns, use the optional parameter n_columns, described next. HP Vertica Analytic Database (7.0.x) Page 810 of 1539 SQL Reference Manual SQL Functions n-columns [Optional ] The number of columns to materialize. The function attempts to materialize the number of columns from the flex_table_ keys table, skipping any columns already materialized. HP VERTICA tables support a total of 1600 columns, which is the greatest value you can specify for n-columns. The function orders the materialized results by frequency, descending, key_namewhen materializing the first n columns. keys_table_name [Optional] The name of a flex_keys_table from which to materialize columns. The function attempts to materialize the number of columns (value of n-columns) from keys_table_name, skipping any columns already materialized. The function orders the materialized results by frequency, descending, key_namewhen materializing the first n columns. Examples The following example loads a sample file of tweets (tweets_10000.json) into the flex table twitter_r. After loading data and computing keys for the sample flex table, the example calls materialize_ flextable_columns to materialize the first four columns: dbt=> copy twitter_r from '/home/release/KData/tweets_10000.json' parser fjsonparser(); Rows Loaded ------------10000 (1 row) dbt=> select compute_flextable_keys ('twitter_r'); compute_flextable_keys --------------------------------------------------Please see public.twitter_r_keys for updated keys (1 row) dbt=> select materialize_flextable_columns('twitter_r', 4); materialize_flextable_columns ------------------------------------------------------------------------------The following columns were added to the table public.twitter_r: contributors entities.hashtags entities.urls For more details, run the following query: SELECT * FROM v_catalog.materialize_flextable_columns_results WHERE table_schema = 'publi c' and table_name = 'twitter_r'; (1 row) The last message in the example recommends querying the materialize_flextable_columns_ results system table for the results of materializing the columns. Following is an example of running that query: HP Vertica Analytic Database (7.0.x) Page 811 of 1539 SQL Reference Manual SQL Functions dbt=> SELECT * FROM v_catalog.materialize_flextable_columns_results WHERE table_schema = 'public' and table_name = 'twitter_r'; table_id | table_schema | table_name | creation_time | key_name | status | message -------------------+--------------+------------+------------------------------+-------------------+--------+-------------------------------------------------------45035996273733172 | public | twitter_r | 2013-11-20 17:00:27.945484-05 | contributors | ADDED | Added successfully 45035996273733172 | public | twitter_r | 2013-11-20 17:00:27.94551-05 | entities.hashtags | ADDED | Added successfully 45035996273733172 | public | entities.urls | ADDED | twitter_r | 2013-11-20 17:00:27.945519-05 | Added successfully 45035996273733172 | public | twitter_r | 2013-11-20 17:00:27.945532-05 | created_at | EXISTS | Column of same name already exists in table definition (4 rows) See the MATERIALIZE_FLEXTABLE_COLUMNS_RESULTS system table in the SQL Reference Manual. See Also l BUILD_FLEXTABLE_VIEW l COMPUTE_FLEXTABLE_KEYS l COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW l RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_VIEW RESTORE_FLEXTABLE_DEFAULT_KEYS_TABLE_AND_ VIEW Restores the _keys table and the _view, linking them with their associated flex table if either is dropped. This function notes whether it restores one or both. Usage restore_flextable_default_keys_table_and_view('flex_table') Arguments flex_table The name of the flex table . HP Vertica Analytic Database (7.0.x) Page 812 of 1539 SQL Reference Manual SQL Functions Examples This example invokes the function with an existing flex table, restoring both the _keys table and _ view: kdb=> select restore_flextable_default_keys_table_and_view('darkdata'); restore_flextable_default_keys_table_and_view ---------------------------------------------------------------------------------The keys table public.darkdata_keys was restored successfully. The view public.darkdata_view was restored successfully. (1 row) This example shows the function restoring darkdata_view, but noting that darkdata_keys does not need restoring: kdb=> select restore_flextable_default_keys_table_and_view('darkdata'); restore_flextable_default_keys_table_and_view -----------------------------------------------------------------------------------------------The keys table public.darkdata_keys already exists and is linked to darkdata. The view public.darkdata_view was restored successfully. (1 row) The _keys table has no content after it is restored: kdb=> select * from darkdata_keys; key_name | frequency | data_type_guess ----------+-----------+----------------(0 rows) See Also l BUILD_FLEXTABLE_VIEW l COMPUTE_FLEXTABLE_KEYS l COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW l MATERIALIZE_FLEXTABLE_COLUMNS HP Vertica Analytic Database (7.0.x) Page 813 of 1539 SQL Reference Manual SQL Functions License Management Functions This section contains function that monitor HP Vertica license status and compliance. AUDIT Estimates the raw data size of a database, a schema, a projection, or a table as it is counted in an audit of the database size. The AUDIT function estimates the size using the same data sampling method as the audit that HP Vertica performs to determine if a database is compliant with the database size allowances in its license. The results of this function are not considered when HP Vertica determines whether the size of the database complies with the HP Vertica license's data allowance. See How HP Vertica Calculates Database Size in the Administrator's Guide for details. Note: This function can only audit the size of tables, projections, schemas, and databases which the user has permission to access. If a non-superuser attempts to audit the entire database, the audit will only estimate the size of the data that the user is allowed to read. Syntax AUDIT([name] [, granularity] [, error_tolerance [, confidence_level]]) Parameters name Specifies the schema, projection, or table to audit. Enter name as a string, in single quotes (''). If the name string is empty (''), the entire database is audited. HP Vertica Analytic Database (7.0.x) Page 814 of 1539 SQL Reference Manual SQL Functions granularity Indicates the level at which the audit reports its results. The recognized levels are: l 'schema' l 'table' l 'projection' By default, the granularity is the same level as name. For example, if name is a schema, then the size of the entire schema is reported. If you instead specify 'table' as the granularity, AUDIT reports the size of each table in the schema. The granularity must be finer than that of object: specifying 'schema' for an audit of a table has no effect. The results of an audit with a granularity are reported in the V_ CATALOG.USER_AUDITS system table. error_tolerance Specifies the percentage margin of error allowed in the audit estimate. Enter the tolerance value as a decimal number, between 0 and 100. The default value is 5, for a 5% margin of error. Note: The lower this value is, the more resources the audit uses since it will perform more data sampling. Setting this value to 0 results in a full audit of the database, which is very resource intensive, as all of the data in the database is analyzed. Doing a full audit of the database significantly impacts performance and is not recommended on a production database. confidence_level Specifies the statistical confidence level percentage of the estimate. Enter the confidence value as a decimal number, between 0 and 100. The default value is 99, indicating a confidence level of 99%. Note: The higher the confidence value, the more resources the function uses since it will perform more data sampling. Setting this value to 1 results in a full audit of the database, which is very resource intensive, as all of the database is analyzed. Doing a full audit of the database significantly impacts performance and is not recommended on a production database. Permissions l SELECT privilege on table l USAGE privilege on schema Note: AUDIT() works only on the tables where the user calling the function has SELECT permissions. HP Vertica Analytic Database (7.0.x) Page 815 of 1539 SQL Reference Manual SQL Functions Notes Due to the iterative sampling used in the auditing process, making the error tolerance a small fraction of a percent (0.00001, for example) can cause the AUDIT function to run for a longer period than a full database audit. Examples To audit the entire database: => SELECT AUDIT(''); AUDIT ---------76376696 (1 row) To audit the database with a 25% error tolerance: => SELECT AUDIT('',25); AUDIT ---------75797126 (1 row) To audit the database with a 25% level of tolerance and a 90% confidence level: => SELECT AUDIT('',25,90); AUDIT ---------76402672 (1 row) To audit just the online_sales schema in the VMart example database: VMart=> SELECT AUDIT('online_sales'); AUDIT ---------35716504 (1 row) To audit the online_sales schema and report the results by table: => SELECT AUDIT('online_sales','table'); AUDIT -----------------------------------------------------------------See table sizes in v_catalog.user_audits for schema online_sales (1 row) HP Vertica Analytic Database (7.0.x) Page 816 of 1539 SQL Reference Manual SQL Functions => \x Expanded display is on. => SELECT * FROM user_audits WHERE object_schema = 'online_sales'; -[ RECORD 1 ]-------------------------+-----------------------------size_bytes | 64960 user_id | 45035996273704962 user_name | dbadmin object_id | 45035996273717636 object_type | TABLE object_schema | online_sales object_name | online_page_dimension audit_start_timestamp | 2011-04-05 09:24:48.224081-04 audit_end_timestamp | 2011-04-05 09:24:48.337551-04 confidence_level_percent | 99 error_tolerance_percent | 5 used_sampling | f confidence_interval_lower_bound_bytes | 64960 confidence_interval_upper_bound_bytes | 64960 sample_count | 0 cell_count | 0 -[ RECORD 2 ]-------------------------+-----------------------------size_bytes | 20197 user_id | 45035996273704962 user_name | dbadmin object_id | 45035996273717640 object_type | TABLE object_schema | online_sales object_name | call_center_dimension audit_start_timestamp | 2011-04-05 09:24:48.340206-04 audit_end_timestamp | 2011-04-05 09:24:48.365915-04 confidence_level_percent | 99 error_tolerance_percent | 5 used_sampling | f confidence_interval_lower_bound_bytes | 20197 confidence_interval_upper_bound_bytes | 20197 sample_count | 0 cell_count | 0 -[ RECORD 3 ]-------------------------+-----------------------------size_bytes | 35614800 user_id | 45035996273704962 user_name | dbadmin object_id | 45035996273717644 object_type | TABLE object_schema | online_sales object_name | online_sales_fact audit_start_timestamp | 2011-04-05 09:24:48.368575-04 audit_end_timestamp | 2011-04-05 09:24:48.379307-04 confidence_level_percent | 99 error_tolerance_percent | 5 used_sampling | t confidence_interval_lower_bound_bytes | 34692956 confidence_interval_upper_bound_bytes | 36536644 sample_count | 10000 cell_count | 9000000 HP Vertica Analytic Database (7.0.x) Page 817 of 1539 SQL Reference Manual SQL Functions AUDIT_FLEX Estimates the ROS size of one or more flexible tables contained in a database, schema, or projection. Use this function for flex tables only. Invoking audit_flex() with a columnar table results in an error. The audit_flex() function measures encoded, compressed data stored in ROS containers for the __raw__ column of one or more flexible tables. The function does not audit other flex table columns that are created as, or promoted to, real columns. Temporary flex tables are not included in the audit. Each time a user calls audit_flex(), HP Vertica stores the results in the V_CATALOG.USER_ AUDITS system table. Syntax AUDIT_FLEX (name) Parameters name Specifies what database entity to audit. Enter the entity name as a string in single quotes (''), as follows: l Empty string ('') — Return the size of the ROS containers for all flexible tables in the database. You cannot enter the database name. l Schema name ('schema_name') — Return the size of all __raw__ columns of flexible tables in schema_name. l A projection name ('proj_name') — Return the ROS size of a projection for a __raw__ column. l A flex table name ('flex_table_name') — Return the ROS size of a flex table's __ raw__ column. Permissions l SELECT privilege on table l USAGE privilege on schema Note: AUDIT_FLEX() works only on the flexible tables, projections, schemas, and databases to which the user has permissions. HP Vertica Analytic Database (7.0.x) Page 818 of 1539 SQL Reference Manual SQL Functions Examples To audit the flex tables in the database: dbs=> select audit_flex(''); audit_flex -----------8567679 (1 row) To audit the flex tables in a specific schema, such as public: dbs=> select audit_flex('public'); audit_flex -----------8567679 (1 row) To audit the flex tables in a specific projection, such as bakery_b0: dbs=> select audit_flex('bakery_b0'); audit_flex -----------8566723 (1 row) To audit a flex table, such as bakery: dbs=> select audit_flex('bakery'); audit_flex -----------8566723 (1 row) To report the results of all audits saved in the USER_AUDITS, the following shows part of an extended display from the system table showing an audit run on a schema called test, and the entire database, dbs: dbs=> \x Expanded display is on. dbs=> select * from user_audits; -[ RECORD 1 ]-------------------------+-----------------------------size_bytes | 0 user_id | 45035996273704962 user_name | release object_id | 45035996273736664 object_type | SCHEMA object_schema | object_name | test HP Vertica Analytic Database (7.0.x) Page 819 of 1539 SQL Reference Manual SQL Functions audit_start_timestamp | 2014-02-04 14:52:15.126592-05 audit_end_timestamp | 2014-02-04 14:52:15.139475-05 confidence_level_percent | 99 error_tolerance_percent | 5 used_sampling | f confidence_interval_lower_bound_bytes | 0 confidence_interval_upper_bound_bytes | 0 sample_count | 0 cell_count | 0 -[ RECORD 2 ]-------------------------+-----------------------------size_bytes | 38051 user_id | 45035996273704962 user_name | release object_id | 45035996273704974 object_type | DATABASE object_schema | object_name | dbs audit_start_timestamp | 2014-02-05 13:44:41.11926-05 audit_end_timestamp | 2014-02-05 13:44:41.227035-05 confidence_level_percent | 99 error_tolerance_percent | 5 used_sampling | f confidence_interval_lower_bound_bytes | 38051 confidence_interval_upper_bound_bytes | 38051 sample_count | 0 cell_count | 0 -[ RECORD 3 ]-------------------------+-----------------------------. . . AUDIT_LICENSE_SIZE Triggers an immediate audit of the database size to determine if it is in compliance with the raw data storage allowance included in your HP Vertica license. The audit is performed in the background, so this function call returns immediately. To see the results of the audit when it is done, use the GET_ COMPLIANCE_STATUS function. Syntax AUDIT_LICENSE_SIZE() Privileges Must be a superuser. Example => SELECT audit_license_size(); HP Vertica Analytic Database (7.0.x) Page 820 of 1539 SQL Reference Manual SQL Functions audit_license_size -------------------Service hurried (1 row) AUDIT_LICENSE_TERM Triggers an immediate audit to determine if the HP Vertica license has expired. The audit happens in the background, so this function returns immediately. To see the result of the audit, use the GET_ COMPLIANCE_STATUS function. Syntax AUDIT_LICENSE_TERM() Privileges Must be a superuser. Example => SELECT AUDIT_LICENSE_TERM(); AUDIT_LICENSE_TERM -------------------Service hurried (1 row) GET_AUDIT_TIME Reports the time when the automatic audit of database size occurs. HP Vertica performs this audit if your HP Vertica license includes a data size allowance. For details of this audit, see Managing Your License Key in the Administrator's Guide. To change the time the audit runs, use the SET_ AUDIT_TIME function. Syntax GET_AUDIT_TIME() Privileges None HP Vertica Analytic Database (7.0.x) Page 821 of 1539 SQL Reference Manual SQL Functions Example => SELECT get_audit_time(); get_audit_time ----------------------------------------------------The audit is scheduled to run at 11:59 PM each day. (1 row) GET_COMPLIANCE_STATUS Displays whether your database is in compliance with your HP Vertica license agreement. This information includes the results of HP Vertica's most recent audit of the database size (if your license has a data allowance as part of its terms), and the license term (if your license has an end date). The information displayed by GET_COMPLIANCE_STATUS includes: l The estimated size of the database (see How HP Vertica Calculates Database Size in the Administrator's Guide for an explanation of the size estimate). l The raw data size allowed by your HP Vertica license. l The percentage of your allowance that your database is currently using. l The date and time of the last audit. l Whether your database complies with the data allowance terms of your license agreement. l The end date of your license. l How many days remain until your license expires. Note: If your license does not have a data allowance or end date, some of the values may not appear in the output for GET_COMPLIANCE_STATUS. If the audit shows your license is not in compliance with your data allowance, you should either delete data to bring the size of the database under the licensed amount, or upgrade your license. If your license term has expired, you should contact HP immediately to renew your license. See Managing Your License Key in the Administrator's Guide for further details. Syntax GET_COMPLIANCE_STATUS() Privileges None HP Vertica Analytic Database (7.0.x) Page 822 of 1539 SQL Reference Manual SQL Functions Example GET_COMPLIANCE_STATUS --------------------------------------------------------------------------------Raw Data Size: 2.00GB +/- 0.003GB License Size : 4.000GB Utilization : 50% Audit Time : 2011-03-09 09:54:09.538704+00 Compliance Status : The database is in compliance with respect to raw data size. License End Date: 04/06/2011 Days Remaining: 28.59 (1 row) DISPLAY_LICENSE Returns the terms of your HP Vertica license. The information this function displays is: l The start and end dates for which the license is valid (or "Perpetual" if the license has no expiration). l The number of days you are allowed to use HP Vertica after your license term expires (the grace period) l The amount of data your database can store, if your license includes a data allowance. Syntax DISPLAY_LICENSE() Privileges None Examples => SELECT DISPLAY_LICENSE(); DISPLAY_LICENSE ---------------------------------------------------HP Vertica Systems, Inc. 1/1/2011 12/31/2011 30 50TB (1 row) HP Vertica Analytic Database (7.0.x) Page 823 of 1539 SQL Reference Manual SQL Functions SET_AUDIT_TIME Sets the time that HP Vertica performs automatic database size audit to determine if the size of the database is compliant with the raw data allowance in your HP Vertica license. Use this function if the audits are currently scheduled to occur during your database's peak activity time. This is normally not a concern, since the automatic audit has little impact on database performance. Audits are scheduled by the preceding audit, so changing the audit time does not affect the next scheduled audit. For example, if your next audit is scheduled to take place at 11:59PM and you use SET_AUDIT_TIME to change the audit schedule 3AM, the previously scheduled 11:59PM audit still runs. As that audit finishes, it schedules the next audit to occur at 3AM. If you want to prevent the next scheduled audit from running at its scheduled time, you can change the scheduled time using SET_AUDIT_TIME then manually trigger an audit to run immediately using AUDIT_LICENSE_SIZE. As the manually-triggered audit finishes, it schedules the next audit to occur at the time you set using SET_AUDIT_TIME (effectively overriding the previously scheduled audit). Syntax SET_AUDIT_TIME(time) time A string containing the time in 'HH:MM AM/PM' format (for example, '1:00 AM') when the audit should run daily. Privileges Must be a superuser. Example => SELECT SET_AUDIT_TIME('3:00 AM'); SET_AUDIT_TIME ----------------------------------------------------------------------The scheduled audit time will be set to 3:00 AM after the next audit. (1 row) HP Vertica Analytic Database (7.0.x) Page 824 of 1539 SQL Reference Manual SQL Functions Partition Management Functions This section contains partition management functions specific to HP Vertica. DROP_PARTITION Forces the partition of projections (if needed) and then drops the specified partition. Syntax DROP_PARTITION ( table_name , partition_value [ , ignore_moveout_errors, reorganize_data ]) Parameters table-name Specifies the name of the table. Note: The table_name argument cannot be used as a dimension table in a pre-joined projection and cannot contain projections that are not up to date (have not been refreshed). partition_value The key of the partition to drop. For example: DROP_PARTITION ('trade', 2006); ignore_moveout_errors Optional Boolean, defaults to false. l true—Ignores any WOS moveout errors and forces the operation to continue. Set this parameter to true only if there is no WOS data for the partition. l false (or omit)—Displays any moveout errors and aborts the operation on error. Note: If you set this parameter to true and the WOS includes data for the partition in WOS, partition data in WOS is not dropped. reorganize_data Optional Boolean, defaults to false. l true—Reorganizes the data if it is not organized, and then drops the partition. l false—Does not attempt to reorganize the data before dropping the partition. If this parameter is false and the function encounters a ROS without partition keys, an error occurs. HP Vertica Analytic Database (7.0.x) Page 825 of 1539 SQL Reference Manual SQL Functions Permissions l Table owner l USAGE privilege on schema that contains the table Notes and Restrictions The results of a DROP_PARTITION call go into effect immediately. If you drop a partition using DROP_PARTITION and then try to add data to a partition with the same name, HP Vertica creates a new partition. If the operation cannot obtain an O Lock on the table(s), HP Vertica attempts to close any internal Tuple Mover (TM) sessions running on the same table(s) so that the operation can proceed. Explicit TM operations that are running in user sessions are not closed. If an explicit TM operation is running on the table, then the operation cannot proceed until the explicit TM operation completes. In general, if a ROS container has data that belongs to n+1 partitions and you want to drop a specific partition, the DROP_PARTITION operation: 1. Forces the partition of data into two containers where n One container holds the data that belongs to the partition that is to be dropped. n Another container holds the remaining n partitions. 2. Drops the specified partition. DROP_PARTITION forces a moveout if there is data in the WOS (WOS is not partition aware). DROP_PARTITION acquires an exclusive lock on the table to prevent DELETE | UPDATE | INSERT | COPY statements from affecting the table, as well as any SELECT statements issued at SERIALIZABLE isolation level. You cannot perform a DROP_PARTITION operation on tables with projections that are not up to date (have not been refreshed). DROP_PARTITION fails if you do not set the optional third parameter to true and the function encounters ROS's that do not have partition keys. Examples Using the example schema in Defining Partitions, the following command explicitly drops the 2009 partition key from table trade: SELECT DROP_PARTITION('trade', 2009); DROP_PARTITION ------------------- HP Vertica Analytic Database (7.0.x) Page 826 of 1539 SQL Reference Manual SQL Functions Partition dropped (1 row) Here, the partition key is specified: SELECT DROP_PARTITION('trade', EXTRACT('year' FROM '2009-01-01'::date)); DROP_PARTITION ------------------Partition dropped (1 row) The following example creates a table called dates and partitions the table by year: CREATE TABLE dates (year INTEGER NOT NULL, month VARCHAR(8) NOT NULL) PARTITION BY year * 12 + month; The following statement drops the partition using a constant for Oct 2010 (2010*12 + 10 = 24130): SELECT DROP_PARTITION('dates', '24130'); DROP_PARTITION ------------------Partition dropped (1 row) Alternatively, the expression can be placed in line: SELECT DROP_PARTITION('dates', 2010*12 + 10); The following command first reorganizes the data if it is unpartitioned and then explicitly drops the 2009 partition key from table trade: SELECT DROP_PARTITION('trade', 2009, false, true); DROP_PARTITION ------------------Partition dropped (1 row) See Also l Dropping Partitions l ADVANCE_EPOCH l ALTER PROJECTION RENAME l COLUMN_STORAGE l CREATE TABLE HP Vertica Analytic Database (7.0.x) Page 827 of 1539 SQL Reference Manual SQL Functions l DO_TM_TASK l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l MERGE_PARTITIONS l PARTITION_PROJECTION l PARTITION_TABLE l PROJECTIONS DUMP_PROJECTION_PARTITION_KEYS Dumps the partition keys of the specified projection. Syntax DUMP_PROJECTION_PARTITION_KEYS( 'projection_name' ) Parameters projection_name Specifies the name of the projection. Privileges l SELECT privilege on table l USAGE privileges on schema Example The following example creates a simple table called states and partitions the data by state: => CREATE TABLE states (year INTEGER NOT NULL, state VARCHAR NOT NULL) PARTITION BY state; => CREATE PROJECTION states_p (state, year) AS SELECT * FROM states ORDER BY state, year UNSEGMENTED ALL NODES; Now dump the partition key of the specified projection: HP Vertica Analytic Database (7.0.x) Page 828 of 1539 SQL Reference Manual SQL Functions => SELECT DUMP_PROJECTION_PARTITION_KEYS( 'states_p_node0001' ); Partition keys on node helios_node0001 Projection 'states_p_node0001' No of partition keys: 1 Partition keys on node helios_node0002 ... (1 row) See Also l DO_TM_TASK l DROP_PARTITION l DUMP_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l PARTITION_TABLE l PROJECTIONS l Working with Table Partitions DUMP_TABLE_PARTITION_KEYS Dumps the partition keys of all projections anchored on the specified table. Syntax DUMP_TABLE_PARTITION_KEYS ( 'table_name' ) Parameters table_name Specifies the name of the table. Privilege l SELECT privilege on table l USAGE privileges on schema HP Vertica Analytic Database (7.0.x) Page 829 of 1539 SQL Reference Manual SQL Functions Examples The following example creates a simple table called states and partitions the data by state: => CREATE TABLE states (year INTEGER NOT NULL, state VARCHAR NOT NULL) PARTITION BY state; => CREATE PROJECTION states_p (state, year) AS SELECT * FROM states ORDER BY state, year UNSEGMENTED ALL NODES; Now dump the partition keys of all projections anchored on table states: => SELECT DUMP_TABLE_PARTITION_KEYS( 'states' ); Partition keys on helios_node0001 Projection 'states_p_node0004' No of partition keys: 1 Projection 'states_p_node0003' No of partition keys: 1 Projection 'states_p_node0002' No of partition keys: 1 Projection 'states_p_node0001' No of partition keys: 1 Partition keys on helios_node0002 ... (1 row) See Also l DO_TM_TASK l DROP_PARTITION l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l PARTITION_TABLE l Working with Table Partitions MERGE_PARTITIONS Merges ROS containers that have data belonging to partitions in a specified partition key range: partitionKeyFromto partitionKeyTo. HP Vertica Analytic Database (7.0.x) Page 830 of 1539 SQL Reference Manual SQL Functions Note: This function is deprecated in HP Vertica 7.0. Syntax MERGE_PARTITIONS ( table_name , partition_key_from , partition_key_to ) Parameters table_name Specifies the name of the table partition_key_from Specifies the start point of the partition partition_key_to Specifies the end point of the partition Privileges l Table owner l USAGE privilege on schema that contains the table Notes l You cannot run MERGE_PARTITIONS() on a table with data that is not reorganized. You must reorganize the data first using ALTER_TABLE table REORGANIZE, or PARTITION_TABLE(table). l The edge values are included in the range, and partition_key_from must be less than or equal to partition_key_to. l Inclusion of partitions in the range is based on the application of less than (<)/greater than (>) operators of the corresponding data type. Note: No restrictions are placed on a partition key's data type. l If partition_key_from is the same as partition_key_to, all ROS containers of the partition key are merged into one ROS. Examples => => => => => SELECT SELECT SELECT SELECT SELECT MERGE_PARTITIONS('T1', MERGE_PARTITIONS('T1', MERGE_PARTITIONS('T1', MERGE_PARTITIONS('T1', MERGE_PARTITIONS('T1', HP Vertica Analytic Database (7.0.x) '200', '400'); '800', '800'); 'CA', 'MA'); 'false', 'true'); '06/06/2008', '06/07/2008'); Page 831 of 1539 SQL Reference Manual SQL Functions => SELECT MERGE_PARTITIONS('T1', '02:01:10', '04:20:40'); => SELECT MERGE_PARTITIONS('T1', '06/06/2008 02:01:10', '06/07/2008 02:01:10'); => SELECT MERGE_PARTITIONS('T1', '8 hours', '1 day 4 hours 20 seconds'); MOVE_PARTITIONS_TO_TABLE Moves partitions from a source table to a target table. The target table must have the same projection column definitions, segmentation, and partition expressions as the source table. If the target table does not exist, the function creates a new table based on the source definition. The function requires both minimum and maximum range values, indicating what partition values to move. Syntax MOVE_PARTITIONS_TO_TABLE ( '[[db-name.]schema.]source_table', 'min_range_value', 'max_range_value', '[[db-name.]schema.]target_table' ) Parameters [[db-name.]schema.]source_table The source table (optionally qualified), from which you want to move partitions. min_range_value The minimum value in the partition to move. max_range_value The maximum value of the partition being moved. target_table The table to which the partitions are being moved. Privileges l Table owner l If target table is created as part of moving partitions, the new table has the same owner as the target. If the target table exists, user must have own the target table, and have ability to call this function. Example If you call MOVE_PARTITIONS_TO_TABLE and the destination table does not exist, the function will create the table automatically: VMART=> SELECT MOVE_PARTITIONS_TO_TABLE ( 'prod_trades', '200801', '200801', HP Vertica Analytic Database (7.0.x) Page 832 of 1539 SQL Reference Manual SQL Functions 'partn_backup.trades_200801'); MOVE_PARTITIONS_TO_TABLE --------------------------------------------------------------------------1 distinct partition values moved at epoch 15. Effective move epoch: 14. (1 row) See Also l DROP_PARTITION l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l Moving Partitions l Creating a Table Like Another PARTITION_PROJECTION Forces a split of ROS containers of the specified projection. Syntax PARTITION_PROJECTION ( '[[db-name.]schema.]projection_name' ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection_name Specifies the name of the projection. HP Vertica Analytic Database (7.0.x) Page 833 of 1539 SQL Reference Manual SQL Functions Privileges l Table owner l USAGE privilege on schema Notes Partitioning expressions take immutable functions only, in order that the same information be available across all nodes. PARTITION_PROJECTION() is similar to PARTITION_TABLE(), except that PARTITION_ PROJECTION works only on the specified projection, instead of the table. Users must have USAGE privilege on schema that contains the table. PARTITION_PROJECTION() purges data while partitioning ROS containers if deletes were applied before the AHM epoch. Example The following command forces a split of ROS containers on the states_p_node01 projection: => SELECT PARTITION_PROJECTION ('states_p_node01'); partition_projection -----------------------Projection partitioned (1 row) See Also l DO_TM_TASK l DROP_PARTITION l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_TABLE l Working with Table Partitions HP Vertica Analytic Database (7.0.x) Page 834 of 1539 SQL Reference Manual SQL Functions PARTITION_TABLE Forces the system to break up any ROS containers that contain multiple distinct values of the partitioning expression. Only ROS containers with more than one distinct value participate in the split. Syntax PARTITION_TABLE ( '[[db-name.]schema.]table_name' ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name Specifies the name of the table. Privileges l Table owner l USAGE privilege on schema Notes PARTITION_TABLE is similar to PARTITION_PROJECTION, except that PARTITION_TABLE works on the specified table. Users must have USAGE privilege on schema that contains the table. Partitioning functions take immutable functions only, in order that the same information be available across all nodes. Example The following example creates a simple table called states and partitions data by state. => CREATE TABLE states (year INTEGER NOT NULL, HP Vertica Analytic Database (7.0.x) Page 835 of 1539 SQL Reference Manual SQL Functions state VARCHAR NOT NULL) PARTITION BY state; => CREATE PROJECTION states_p (state, year) AS SELECT * FROM states ORDER BY state, year UNSEGMENTED ALL NODES; Now call the PARTITION_TABLE function to partition table states: => SELECT PARTITION_TABLE('states'); PARTITION_TABLE ------------------------------------------------------partition operation for projection 'states_p_node0004' partition operation for projection 'states_p_node0003' partition operation for projection 'states_p_node0002' partition operation for projection 'states_p_node0001' (1 row) See Also l DO_TM_TASK l DROP_PARTITION l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l Working with Table Partitions PURGE_PARTITION Purges a table partition of deleted rows. Similar to PURGE() and PURGE_PROJECTION(), this function removes deleted data from physical storage so you can reuse the disk space. PURGE_PARTITION() removes data from the AHM epoch and earlier only. Syntax PURGE_PARTITION ( '[[db_name.]schema_name.]table_name', partition_key ) HP Vertica Analytic Database (7.0.x) Page 836 of 1539 SQL Reference Manual SQL Functions Parameters [[db_name.]schema_name.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name The name of the partitioned table partition_key The key of the partition to be purged of deleted rows Privileges l Table owner l USAGE privilege on schema Example The following example lists the count of deleted rows for each partition in a table, then calls PURGE_ PARTITION() to purge the deleted rows from the data. => SELECT partition_key,table_schema,projection_name,sum(deleted_row_count) AS deleted_row_count FROM partitions GROUP BY partition_key,table_schema,projection_name ORDER BY partition_key; partition_key | table_schema | projection_name | deleted_row_count ---------------+--------------+-----------------+------------------0 | public | t_super | 2 1 | public | t_super | 2 2 | public | t_super | 2 3 | public | t_super | 2 4 | public | t_super | 2 5 | public | t_super | 2 6 | public | t_super | 2 7 | public | t_super | 2 8 | public | t_super | 2 9 | public | t_super | 1 (10 rows) => SELECT PURGE_PARTITION('t',5); -- Purge partition with key 5. purge_partition -----------------------------------------------------------------------Task: merge partitions HP Vertica Analytic Database (7.0.x) Page 837 of 1539 SQL Reference Manual SQL Functions (Table: public.t) (Projection: public.t_super) (1 row) => SELECT partition_key,table_schema,projection_name,sum(deleted_row_count) AS deleted_row_count FROM partitions GROUP BY partition_key,table_schema,projection_name ORDER BY partition_key; partition_key | table_schema | projection_name | deleted_row_count ---------------+--------------+-----------------+------------------0 | public | t_super | 2 1 | public | t_super | 2 2 | public | t_super | 2 3 | public | t_super | 2 4 | public | t_super | 2 5 | public | t_super | 0 6 | public | t_super | 2 7 | public | t_super | 2 8 | public | t_super | 2 9 | public | t_super | 1 (10 rows) See Also l MERGE_PARTITIONS l PURGE l PURGE_PROJECTION l PURGE_TABLE l STORAGE_CONTAINERS HP Vertica Analytic Database (7.0.x) Page 838 of 1539 SQL Reference Manual SQL Functions Profiling Functions This section contains profiling functions specific to HP Vertica. CLEAR_PROFILING HP Vertica stores profiled data is in memory, so depending on how much data you collect, profiling could be memory intensive. You can use this function to clear profiled data from memory. Syntax CLEAR_PROFILING( 'profiling-type' ) Parameters profiling-type The type of profiling data you want to clear. Can be one of: l session—clears profiling for basic session parameters and lock time out data l query—clears profiling for general information about queries that ran, such as the query strings used and the duration of queries l ee—clears profiling for information about the execution run of each query Example The following statement clears profiled data for queries: => SELECT CLEAR_PROFILING('query'); See Also l DISABLE_PROFILING l ENABLE_PROFILING l Profiling Database Performance DISABLE_PROFILING Disables profiling for the profiling type you specify. HP Vertica Analytic Database (7.0.x) Page 839 of 1539 SQL Reference Manual SQL Functions Syntax DISABLE_PROFILING( 'profiling-type' ) Parameters profiling-type The type of profiling data you want to disable. Can be one of: l session—disables profiling for basic session parameters and lock time out data l query—disables profiling for general information about queries that ran, such as the query strings used and the duration of queries l ee—disables profiling for information about the execution run of each query Example The following statement disables profiling on query execution runs: => SELECT DISABLE_PROFILING('ee'); DISABLE_PROFILING ----------------------EE Profiling Disabled (1 row) See Also l CLEAR_PROFILING l ENABLE_PROFILING l Profiling Database Performance ENABLE_PROFILING Enables profiling for the profiling type you specify. Note: HP Vertica stores profiled data is in memory, so depending on how much data you collect, profiling could be memory intensive. Syntax ENABLE_PROFILING( 'profiling-type' ) HP Vertica Analytic Database (7.0.x) Page 840 of 1539 SQL Reference Manual SQL Functions Parameters profiling-type The type of profiling data you want to enable. Can be one of: l session—enables profiling for basic session parameters and lock time out data l query—enables profiling for general information about queries that ran, such as the query strings used and the duration of queries l ee—enables profiling for information about the execution run of each query Example The following statement enables profiling on query execution runs: => SELECT ENABLE_PROFILING('ee'); ENABLE_PROFILING ---------------------EE Profiling Enabled (1 row) See Also l CLEAR_PROFILING l DISABLE_PROFILING l Profiling Database Performance HP Vertica Analytic Database (7.0.x) Page 841 of 1539 SQL Reference Manual SQL Functions Projection Management Functions This section contains projection management functions specific to HP Vertica. See also the following SQL system tables: l V_CATALOG.PROJECTIONS l V_CATALOG.PROJECTION_COLUMNS l V_MONITOR.PROJECTION_REFRESHES l V_MONITOR.PROJECTION_STORAGE EVALUATE_DELETE_PERFORMANCE Evaluates projections for potential DELETE performance issues. If there are issues found, a warning message is displayed. For steps you can take to resolve delete and update performance issues, see Optimizing Deletes and Updates for Performance in the Administrator's Guide. This function uses data sampling to determine whether there are any issues with a projection. Therefore, it does not generate false-positives warnings, but it can miss some cases where there are performance issues. Note: Optimizing for delete performance is the same as optimizing for update performance. So, you can use this function to help optimize a projection for updates as well as deletes. Syntax EVALUATE_DELETE_PERFORMANCE ( 'target' ) Parameters target The name of a projection or table. If you supply the name of a projection, only that projection is evaluated for DELETE performance issues. If you supply the name of a table, then all of the projections anchored to the table will be evaluated for issues. If you do not provide a projection or table name, EVALUATE_DELETE_ PERFORMANCE examines all of the projections that you can access for DELETE performance issues. Depending on the size you your database, this may take a long time. Privileges None HP Vertica Analytic Database (7.0.x) Page 842 of 1539 SQL Reference Manual SQL Functions Notes When evaluating multiple projections, EVALUATE_DELETE_PERFORMANCE reports up to ten projections that have issues, and refers you to a table that contains the full list of issues it has found. Example The following example demonstrates how you can use EVALUATE_DELETE_PERFORMANCE to evaluate your projections for slow DELETE performance. => create table example (A int, B int,C int); CREATE TABLE => create projection one_sort (A,B,C) as (select A,B,C from example) order by A; CREATE PROJECTION => create projection two_sort (A,B,C) as (select A,B,C from example) order by A,B; CREATE PROJECTION => select evaluate_delete_performance('one_sort'); evaluate_delete_performance --------------------------------------------------No projection delete performance concerns found. (1 row) => select evaluate_delete_performance('two_sort'); evaluate_delete_performance --------------------------------------------------No projection delete performance concerns found. (1 row) The previous example showed that there was no structural issue with the projection that would cause poor DELETE performance. However, the data contained within the projection can create potential delete issues if the sorted columns do not uniquely identify a row or small number of rows. In the following example, Perl is used to populate the table with data using a nested series of loops. The inner loop populates column C, the middle loop populates column B, and the outer loop populates column A. The result is column A contains only three distinct values (0, 1, and 2), while column B slowly varies between 20 and 0 and column C changes in each row. EVALUATE_ DELETE_PERFORMANCE is run against the projections again to see if the data within the projections causes any potential DELETE performance issues. => \! perl -e 'for ($i=0; $i<3; $i++) { for ($j=0; $j<21; $j++) { for ($k=0; $k<19; $k++) { printf "%d,%d,%d\n", $i,$j,$k;}}}' | /opt/vertica/bin/vsql -c "copy example from stdin delimiter ',' direct;" Password: => select * from example; A | B | C ---+----+---0 | 20 | 18 0 | 20 | 17 0 | 20 | 16 0 | 20 | 15 0 | 20 | 14 HP Vertica Analytic Database (7.0.x) Page 843 of 1539 SQL Reference Manual SQL Functions 0 | 20 | 13 0 | 20 | 12 0 | 20 | 11 0 | 20 | 10 0 | 20 | 9 0 | 20 | 8 0 | 20 | 7 0 | 20 | 6 0 | 20 | 5 0 | 20 | 4 0 | 20 | 3 0 | 20 | 2 0 | 20 | 1 0 | 20 | 0 0 | 19 | 18 1157 rows omitted 2 | 1 | 0 2 | 0 | 18 2 | 0 | 17 2 | 0 | 16 2 | 0 | 15 2 | 0 | 14 2 | 0 | 13 2 | 0 | 12 2 | 0 | 11 2 | 0 | 10 2 | 0 | 9 2 | 0 | 8 2 | 0 | 7 2 | 0 | 6 2 | 0 | 5 2 | 0 | 4 2 | 0 | 3 2 | 0 | 2 2 | 0 | 1 2 | 0 | 0 => SELECT COUNT (*) FROM example; COUNT ------1197 (1 row) => SELECT COUNT (DISTINCT A) FROM example; COUNT ------3 (1 row) => select evaluate_delete_performance('one_sort'); evaluate_delete_performance --------------------------------------------------Projection exhibits delete performance concerns. (1 row) release=> select evaluate_delete_performance('two_sort'); evaluate_delete_performance --------------------------------------------------No projection delete performance concerns found. (1 row) HP Vertica Analytic Database (7.0.x) Page 844 of 1539 SQL Reference Manual SQL Functions The one_sort projection has potential delete issues since it only sorts on column A which has few distinct values. This means that each value in the sort column corresponds to many rows in the projection, which negatively impacts DELETE performance. Since the two_sort projection is sorted on columns A and B, each combination of values in the two sort columns identifies just a few rows, allowing deletes to be performed faster. Not supplying a projection name results in all of the projections you can access being evaluated for DELETE performance issues. => select evaluate_delete_performance(); evaluate_delete_performance --------------------------------------------------------------------------The following projection exhibits delete performance concerns: "public"."one_sort" See v_catalog.projection_delete_concerns for more details. (1 row) GET_PROJECTION_STATUS Returns information relevant to the status of a projection. Syntax GET_PROJECTION_STATUS ( '[[db-name.]schema-name.]projection' ); Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection Is the name of the projection for which to display status. When using more than one schema, specify the schema that contains the projection, as noted above. Privileges None Description GET_PROJECTION_STATUS returns information relevant to the status of a projection: HP Vertica Analytic Database (7.0.x) Page 845 of 1539 SQL Reference Manual SQL Functions l The current K-safety status of the database l The number of nodes in the database l Whether the projection is segmented l The number and names of buddy projections l Whether the projection is safe l Whether the projection is up-to-date l Whether statistics have been computed for the projection Notes l You can use GET_PROJECTION_STATUS to monitor the progress of a projection data refresh. See ALTER PROJECTION. l To view a list of the nodes in a database, use the View Database Command in the Administration Tools. Examples => SELECT GET_PROJECTION_STATUS('public.customer_dimension_site01'); GET_PROJECTION_STATUS ---------------------------------------------------------------------------------------------Current system K is 1. # of Nodes: 4. public.customer_dimension_site01 [Segmented: No] [Seg Cols: ] [K: 3] [public.customer_dim ension_site04, public.customer_dimension_site03, public.customer_dimension_site02] [Safe: Yes] [UptoDate: Yes][Stats: Yes] See Also l ALTER PROJECTION RENAME l GET_PROJECTIONS, GET_TABLE_PROJECTIONS GET_PROJECTIONS, GET_TABLE_PROJECTIONS Note: This function was formerly named GET_TABLE_PROJECTIONS(). HP Vertica still supports the former function name. Returns information relevant to the status of a table: HP Vertica Analytic Database (7.0.x) Page 846 of 1539 SQL Reference Manual SQL Functions l The current K-safety status of the database l The number of sites (nodes) in the database l The number of projections for which the specified table is the anchor table l For each projection: n The projection's buddy projections n Whether the projection is segmented n Whether the projection is safe n Whether the projection is up-to-date Syntax GET_PROJECTIONS ( '[[db-name.]schema-name.]table' ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table Is the name of the table for which to list projections. When using more than one schema, specify the schema that contains the table. Privileges None Notes l You can use GET_PROJECTIONS to monitor the progress of a projection data refresh. See ALTER PROJECTION. l To view a list of the nodes in a database, use the View Database Command in the Administration Tools. HP Vertica Analytic Database (7.0.x) Page 847 of 1539 SQL Reference Manual SQL Functions Examples The following example gets information about the store_dimension table in the VMart schema: => SELECT GET_PROJECTIONS('store.store_dimension'); -------------------------------------------------------------------------------------Current system K is 1. # of Nodes: 4. Table store.store_dimension has 4 projections. Projection Name: [Segmented] [Seg Cols] [# of Buddies] [Buddy Projections] [Safe] [UptoDa te] ---------------------------------------------------------store.store_dimension_node0004 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio n_node0003, store.store_dimension_node0002, store.store_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes] store.store_dimension_node0003 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio n_node0004, store.store_dimension_node0002, store.store_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes] store.store_dimension_node0002 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio n_node0004, store.store_dimension_node0003, store.store_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes] store.store_dimension_node0001 [Segmented: No] [Seg Cols: ] [K: 3] [store.store_dimensio n_node0004, store.store_dimension_node0003, store.store_dimension_node0002] [Safe: Yes] [UptoDate: Yes][Stats: Yes] (1 row) See Also l ALTER PROJECTION RENAME l GET_PROJECTION_STATUS REFRESH Performs a synchronous, optionally-targeted refresh of a specified table's projections. Information about a refresh operation—whether successful or unsuccessful—is maintained in the PROJECTION_REFRESHES system table until either the CLEAR_PROJECTION_ REFRESHES() function is executed or the storage quota for the table is exceeded. The PROJECTION_REFRESHES.IS_EXECUTING column returns a boolean value that indicates whether the refresh is currently running (t) or occurred in the past (f). Syntax REFRESH ( '[[db-name.]schema.]table_name [ , ... ]' ) HP Vertica Analytic Database (7.0.x) Page 848 of 1539 SQL Reference Manual SQL Functions Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name Specifies the name of a specific table containing the projections to be refreshed. The REFRESH() function attempts to refresh all the tables provided as arguments in parallel. Such calls will be part of the Database Designer deployment (and deployment script). When using more than one schema, specify the schema that contains the table, as noted above. Returns Column Name Description Projection Name The name of the projection that is targeted for refresh. Anchor Table The name of the projection's associated anchor table. Status The status of the projection: l Queued—Indicates that a projection is queued for refresh. l Refreshing—Indicates that a refresh for a projection is in process. l Refreshed—Indicates that a refresh for a projection has successfully completed. l Failed—Indicates that a refresh for a projection did not successfully complete. HP Vertica Analytic Database (7.0.x) Page 849 of 1539 SQL Reference Manual SQL Functions Refresh Method The method used to refresh the projection: l Buddy—Uses the contents of a buddy to refresh the projection. This method maintains historical data. This enables the projection to be used for historical queries. l Scratch—Refreshes the projection without using a buddy. This method does not generate historical data. This means that the projection cannot participate in historical queries from any point before the projection was refreshed. Error Count The number of times a refresh failed for the projection. Duration (sec) The length of time that the projection refresh ran in seconds. Privileges REFRESH() works only if invoked on tables owned by the calling user. Notes l Unlike START_REFRESH(), which runs in the background, REFRESH() runs in the foreground of the caller's session. l The REFRESH() function refreshes only the projections in the specified table. l If you run REFRESH() without arguments, it refreshes all non up-to-date projections. If the function returns a header string with no results, then no projections needed refreshing. Examples The following example refreshes the projections in tables t1 and t2: => SELECT REFRESH('t1, t2'); REFRESH ---------------------------------------------------------------------------------------Refresh completed with the following outcomes: Projection Name: [Anchor Table] [Status] [Refresh Method] [Error Count] [Duration (sec)] ---------------------------------------------------------------------------------------"public"."t1_p": [t1] [refreshed] [scratch] [0] [0]"public"."t2_p": [t2] [refreshed] [scr atch] [0] [0] This next example shows that only the projection on table t was refreshed: => SELECT REFRESH('allow, public.deny, t'); HP Vertica Analytic Database (7.0.x) Page 850 of 1539 SQL Reference Manual SQL Functions REFRESH ---------------------------------------------------------------------------------------Refresh completed with the following outcomes: Projection Name: [Anchor Table] [Status] [Refresh Method] [Error Count] [Duration (sec)] ---------------------------------------------------------------------------------------"n/a"."n/a": [n/a] [failed: insufficient permissions on table "allow"] [] [1] [0] "n/a"."n/a": [n/a] [failed: insufficient permissions on table "public.deny"] [] [1] [0] "public"."t_p1": [t] [refreshed] [scratch] [0] [0] See Also l CLEAR_PROJECTION_REFRESHES l PROJECTION_REFRESHES l START_REFRESH l Clearing PROJECTION_REFRESHES History START_REFRESH Transfers data to projections that are not able to participate in query execution due to missing or out-of-date data. Syntax START_REFRESH() Notes l When a design is deployed through the Database Designer, it is automatically refreshed. See Deploying a Design in the Administrator's Guide. l All nodes must be up in order to start a refresh. l START_REFRESH() has no effect if a refresh is already running. l A refresh is run asynchronously. l Shutting down the database ends the refresh. l To view the progress of the refresh, see the PROJECTION_REFRESHES and PROJECTIONS system tables. l If a projection is updated from scratch, the data stored in the projection represents the table columns as of the epoch in which the refresh commits. As a result, the query optimizer might not HP Vertica Analytic Database (7.0.x) Page 851 of 1539 SQL Reference Manual SQL Functions choose the new projection for AT EPOCH queries that request historical data at epochs older than the refresh epoch of the projection. Projections refreshed from buddies retain history and can be used to answer historical queries. Privileges None Example The following command starts the refresh operation: => SELECT START_REFRESH(); start_refresh ---------------------------------------Starting refresh background process. See Also l CLEAR_PROJECTION_REFRESHES l MARK_DESIGN_KSAFE l PROJECTION_REFRESHES l PROJECTIONS l Clearing PROJECTION_REFRESHES History HP Vertica Analytic Database (7.0.x) Page 852 of 1539 SQL Reference Manual SQL Functions Purge Functions This section contains purge functions specific to HP Vertica. PURGE Permanently removes deleted data from physical storage so that the disk space can be reused. You can purge historical data up to and including the epoch in which the Ancient History Mark is contained. Purges all projections in the physical schema. PURGE does not delete temporary tables. Syntax PURGE() Privileges l Table owner l USAGE privilege on schema Notes l PURGE() was formerly named PURGE_ALL_PROJECTIONS. HP Vertica supports both function calls. Caution: PURGE could temporarily take up significant disk space while the data is being purged. See Also l MERGE_PARTITIONS l PARTITION_TABLE l PURGE_PROJECTION l PURGE_TABLE l STORAGE_CONTAINERS l Purging Deleted Data HP Vertica Analytic Database (7.0.x) Page 853 of 1539 SQL Reference Manual SQL Functions PURGE_PARTITION Purges a table partition of deleted rows. Similar to PURGE() and PURGE_PROJECTION(), this function removes deleted data from physical storage so you can reuse the disk space. PURGE_PARTITION() removes data from the AHM epoch and earlier only. Syntax PURGE_PARTITION ( '[[db_name.]schema_name.]table_name', partition_key ) Parameters [[db_name.]schema_name.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name The name of the partitioned table partition_key The key of the partition to be purged of deleted rows Privileges l Table owner l USAGE privilege on schema Example The following example lists the count of deleted rows for each partition in a table, then calls PURGE_ PARTITION() to purge the deleted rows from the data. => SELECT partition_key,table_schema,projection_name,sum(deleted_row_count) AS deleted_row_count FROM partitions GROUP BY partition_key,table_schema,projection_name ORDER BY partition_key; partition_key | table_schema | projection_name | deleted_row_count ---------------+--------------+-----------------+------------------0 | public | t_super | 2 1 | public | t_super | 2 HP Vertica Analytic Database (7.0.x) Page 854 of 1539 SQL Reference Manual SQL Functions 2 | public | t_super | 2 3 | public | t_super | 2 4 | public | t_super | 2 5 | public | t_super | 2 6 | public | t_super | 2 7 | public | t_super | 2 8 | public | t_super | 2 9 | public | t_super | 1 (10 rows) => SELECT PURGE_PARTITION('t',5); -- Purge partition with key 5. purge_partition -----------------------------------------------------------------------Task: merge partitions (Table: public.t) (Projection: public.t_super) (1 row) => SELECT partition_key,table_schema,projection_name,sum(deleted_row_count) AS deleted_row_count FROM partitions GROUP BY partition_key,table_schema,projection_name ORDER BY partition_key; partition_key | table_schema | projection_name | deleted_row_count ---------------+--------------+-----------------+------------------0 | public | t_super | 2 1 | public | t_super | 2 2 | public | t_super | 2 3 | public | t_super | 2 4 | public | t_super | 2 5 | public | t_super | 0 6 | public | t_super | 2 7 | public | t_super | 2 8 | public | t_super | 2 9 | public | t_super | 1 (10 rows) See Also l MERGE_PARTITIONS l PURGE l PURGE_PROJECTION l PURGE_TABLE l STORAGE_CONTAINERS PURGE_PROJECTION Permanently removes deleted data from physical storage so that the disk space can be reused. You can purge historical data up to and including the epoch in which the Ancient History Mark is contained. HP Vertica Analytic Database (7.0.x) Page 855 of 1539 SQL Reference Manual SQL Functions Purges the specified projection. Caution: PURGE_PROJECTION could temporarily take up significant disk space while purging the data. Syntax PURGE_PROJECTION ( '[[db-name.]schema.]projection_name' ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection_name Identifies the projection name. When using more than one schema, specify the schema that contains the projection, as noted above. Privileges l Table owner l USAGE privilege on schema Notes See PURGE for notes about the outcome of purge operations. See Also l PURGE_TABLE l STORAGE_CONTAINERS l Purging Deleted Data PURGE_TABLE Note: This function was formerly named PURGE_TABLE_PROJECTIONS(). HP Vertica still HP Vertica Analytic Database (7.0.x) Page 856 of 1539 SQL Reference Manual SQL Functions supports the former function name. Permanently removes deleted data from physical storage so that the disk space can be reused. You can purge historical data up to and including the epoch in which the Ancient History Mark is contained. Purges all projections of the specified table. You cannot use this function to purge temporary tables. Syntax PURGE_TABLE ( '[[db-name.]schema.]table_name' ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name Specifies the table to purge. Privileges l Table owner l USAGE privilege on schema Caution: PURGE_TABLE could temporarily take up significant disk space while the data is being purged. Example The following example purges all projections for the store sales fact table located in the Vmart schema: => SELECT PURGE_TABLE('store.store_sales_fact'); HP Vertica Analytic Database (7.0.x) Page 857 of 1539 SQL Reference Manual SQL Functions See Also l PURGE l PURGE_TABLE l STORAGE_CONTAINERS l Purging Deleted Data HP Vertica Analytic Database (7.0.x) Page 858 of 1539 SQL Reference Manual SQL Functions Session Management Functions This section contains session management functions specific to HP Vertica. See also the SQL system table V_MONITOR.SESSIONS CANCEL_REFRESH Cancels refresh-related internal operations initiated by START_REFRESH(). Syntax CANCEL_REFRESH() Privileges None Notes l Refresh tasks run in a background thread in an internal session, so you cannot use INTERRUPT_STATEMENT to cancel those statements. Instead, use CANCEL_REFRESH to cancel statements that are run by refresh-related internal sessions. l Run CANCEL_REFRESH() on the same node on which START_REFRESH() was initiated. l CANCEL_REFRESH() cancels the refresh operation running on a node, waits for the cancelation to complete, and returns SUCCESS. l Only one set of refresh operations runs on a node at any time. Example Cancel a refresh operation executing in the background. t=> SELECT START_REFRESH(); START_REFRESH ---------------------------------------Starting refresh background process. (1 row) => SELECT CANCEL_REFRESH(); CANCEL_REFRESH ---------------------------------------Stopping background refresh process. (1 row) HP Vertica Analytic Database (7.0.x) Page 859 of 1539 SQL Reference Manual SQL Functions See Also l INTERRUPT_STATEMENT l SESSIONS l START_REFRESH l PROJECTION_REFRESHES CLOSE_ALL_SESSIONS Closes all external sessions except the one issuing the CLOSE_ALL_SESSIONS functions. Syntax CLOSE_ALL_SESSIONS() Privileges None; however, a non-superuser can only close his or her own session. Notes Closing of the sessions is processed asynchronously. It might take some time for the session to be closed. Check the SESSIONS table for the status. Database shutdown is prevented if new sessions connect after the CLOSE_SESSION or CLOSE_ ALL_SESSIONS() command is invoked (and before the database is actually shut down). See Controlling Sessions below. Message close_all_sessions | Close all sessions command sent. Check SESSIONS for progress. Examples Two user sessions opened, each on a different node: vmartdb=> SELECT * FROM sessions; -[ RECORD 1 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0001 user_name | dbadmin client_hostname | 127.0.0.1:52110 HP Vertica Analytic Database (7.0.x) Page 860 of 1539 SQL Reference Manual SQL Functions client_pid | 4554 login_timestamp | 2011-01-03 14:05:40.252625-05 session_id | stress04-4325:0x14 client_label | transaction_start | 2011-01-03 14:05:44.325781 transaction_id | 45035996273728326 transaction_description | user dbadmin (select * from sessions;) statement_start | 2011-01-03 15:36:13.896288 statement_id | 10 last_statement_duration_us | 14978 current_statement | select * from sessions; ssl_state | None authentication_method | Trust -[ RECORD 2 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0002 user_name | dbadmin client_hostname | 127.0.0.1:57174 client_pid | 30117 login_timestamp | 2011-01-03 15:33:00.842021-05 session_id | stress05-27944:0xc1a client_label | transaction_start | 2011-01-03 15:34:46.538102 transaction_id | -1 transaction_description | user dbadmin (COPY Mart_Fact FROM '/data/mart_Fact.tbl' DELIMITER '|' NULL '\\n';) statement_start | 2011-01-03 15:34:46.538862 statement_id | last_statement_duration_us | 26250 current_statement | COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n'; ssl_state | None authentication_method | Trust -[ RECORD 3 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0003 user_name | dbadmin client_hostname | 127.0.0.1:56367 client_pid | 1191 login_timestamp | 2011-01-03 15:31:44.939302-05 session_id | stress06-25663:0xbec client_label | transaction_start | 2011-01-03 15:34:51.05939 transaction_id | 54043195528458775 transaction_description | user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT;) statement_start | 2011-01-03 15:35:46.436748 statement_id | last_statement_duration_us | 1591403 current_statement | COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT; ssl_state | None authentication_method | Trust Close all sessions: vmartdb=> \xExpanded display is off. vmartdb=> SELECT CLOSE_ALL_SESSIONS(); HP Vertica Analytic Database (7.0.x) Page 861 of 1539 SQL Reference Manual SQL Functions CLOSE_ALL_SESSIONS ------------------------------------------------------------------------Close all sessions command sent. Check v_monitor.sessions for progress. (1 row) Session contents after issuing the CLOSE_ALL_SESSIONS() command: => SELECT * FROM SESSIONS;-[ ----node_name | user_name | client_hostname | client_pid | login_timestamp | session_id | client_label | transaction_start | transaction_id | transaction_description | statement_start | statement_id | last_statement_duration_us | current_statement | ssl_state | authentication_method | RECORD 1 ]--------------+----------------------------------v_vmartdb_node0001 dbadmin 127.0.0.1:52110 4554 2011-01-03 14:05:40.252625-05 stress04-4325:0x14 2011-01-03 14:05:44.325781 45035996273728326 user dbadmin (SELECT * FROM sessions;) 2011-01-03 16:19:56.720071 25 15605 SELECT * FROM SESSIONS; None Trust Controlling Sessions The database administrator must be able to disallow new incoming connections in order to shut down the database. On a busy system, database shutdown is prevented if new sessions connect after the CLOSE_SESSION or CLOSE_ALL_SESSIONS() command is invoked—and before the database actually shuts down. One option is for the administrator to issue the SHUTDOWN('true') command, which forces the database to shut down and disallow new connections. See SHUTDOWN in the SQL Reference Manual. Another option is to modify the MaxClientSessions parameter from its original value to 0, in order to prevent new non-dbadmin users from connecting to the database. 1. Determine the original value for the MaxClientSessions parameter by querying the V_ MONITOR.CONFIGURATIONS_PARAMETERS system table: => SELECT CURRENT_VALUE FROM CONFIGURATION_PARAMETERS WHERE parameter_name='MaxClient Sessions'; CURRENT_VALUE --------------50 (1 row) HP Vertica Analytic Database (7.0.x) Page 862 of 1539 SQL Reference Manual SQL Functions 2. Set the MaxClientSessions parameter to 0 to prevent new non-dbadmin connections: => SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 0); Note: The previous command allows up to five administrators to log in. 3. Issue the CLOSE_ALL_SESSIONS() command to remove existing sessions: => SELECT CLOSE_ALL_SESSIONS(); 4. Query the SESSIONS table: => SELECT * FROM SESSIONS; When the session no longer appears in the SESSIONS table, disconnect and run the Stop Database command. 5. Restart the database. 6. Restore the MaxClientSessions parameter to its original value: => SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 50); See Also l CLOSE_SESSION l CONFIGURATION_PARAMETERS l SHUTDOWN SESSIONS l l l CLOSE_SESSION Interrupts the specified external session, rolls back the current transaction, if any, and closes the socket. HP Vertica Analytic Database (7.0.x) Page 863 of 1539 SQL Reference Manual SQL Functions Syntax CLOSE_SESSION ( 'sessionid' ) Parameters sessionid A string that specifies the session to close. This identifier is unique within the cluster at any point in time but can be reused when the session closes. Privileges None; however, a non-superuser can only close his or her own session. Notes l Closing of the session is processed asynchronously. It could take some time for the session to be closed. Check the SESSIONS table for the status. l Database shutdown is prevented if new sessions connect after the CLOSE_SESSION() command is invoked (and before the database is actually shut down. See Controlling Sessions below. Messages The following are the messages you could encounter: l For a badly formatted sessionID close_session | Session close command sent. Check SESSIONS for progress.Error: invalid Session ID format l For an incorrect sessionID parameter Error: Invalid session ID or statement key Examples User session opened. RECORD 2 shows the user session running COPY DIRECT statement. => SELECT * FROM sessions; -[ RECORD 1 ]--------------+----------------------------------------------- HP Vertica Analytic Database (7.0.x) Page 864 of 1539 SQL Reference Manual SQL Functions node_name | v_vmartdb_node0001 user_name | dbadmin client_hostname | 127.0.0.1:52110 client_pid | 4554 login_timestamp | 2011-01-03 14:05:40.252625-05 session_id | stress04-4325:0x14 client_label | transaction_start | 2011-01-03 14:05:44.325781 transaction_id | 45035996273728326 transaction_description | user dbadmin (SELECT * FROM sessions;) statement_start | 2011-01-03 15:36:13.896288 statement_id | 10 last_statement_duration_us | 14978 current_statement | select * from sessions; ssl_state | None authentication_method | Trust -[ RECORD 2 ]--------------+----------------------------------------------node_name | v_vmartdb_node0002 user_name | dbadmin client_hostname | 127.0.0.1:57174 client_pid | 30117 login_timestamp | 2011-01-03 15:33:00.842021-05 session_id | stress05-27944:0xc1a client_label | transaction_start | 2011-01-03 15:34:46.538102 transaction_id | -1 transaction_description | user dbadmin (COPY ClickStream_Fact FROM '/data/clickstream/1g/ClickStream_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT;) statement_start | 2011-01-03 15:34:46.538862 statement_id | last_statement_duration_us | 26250 current_statement | COPY ClickStream_Fact FROM '/data/clickstream /1g/ClickStream_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT; ssl_state | None authentication_method | Trust Close user session stress05-27944:0xc1a => \xExpanded display is off. => SELECT CLOSE_SESSION('stress05-27944:0xc1a'); CLOSE_SESSION -------------------------------------------------------------------Session close command sent. Check v_monitor.sessions for progress. (1 row) Query the sessions table again for current status, and you can see that the second session has been closed: => SELECT * FROM SESSIONS; -[ RECORD 1 ]--------------+-------------------------------------------node_name | v_vmartdb_node0001 user_name | dbadmin client_hostname | 127.0.0.1:52110 HP Vertica Analytic Database (7.0.x) Page 865 of 1539 SQL Reference Manual SQL Functions client_pid login_timestamp session_id client_label transaction_start transaction_id transaction_description statement_start statement_id last_statement_duration_us current_statement ssl_state authentication_method | | | | | | | | | | | | | 4554 2011-01-03 14:05:40.252625-05 stress04-4325:0x14 2011-01-03 14:05:44.325781 45035996273728326 user dbadmin (select * from SESSIONS;) 2011-01-03 16:12:07.841298 20 2099 SELECT * FROM SESSIONS; None Trust Controlling Sessions The database administrator must be able to disallow new incoming connections in order to shut down the database. On a busy system, database shutdown is prevented if new sessions connect after the CLOSE_SESSION or CLOSE_ALL_SESSIONS() command is invoked—and before the database actually shuts down. One option is for the administrator to issue the SHUTDOWN('true') command, which forces the database to shut down and disallow new connections. See SHUTDOWN in the SQL Reference Manual. Another option is to modify the MaxClientSessions parameter from its original value to 0, in order to prevent new non-dbadmin users from connecting to the database. 1. Determine the original value for the MaxClientSessions parameter by querying the V_ MONITOR.CONFIGURATIONS_PARAMETERS system table: => SELECT CURRENT_VALUE FROM CONFIGURATION_PARAMETERS WHERE parameter_name='MaxClient Sessions'; CURRENT_VALUE --------------50 (1 row) 2. Set the MaxClientSessions parameter to 0 to prevent new non-dbadmin connections: => SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 0); Note: The previous command allows up to five administrators to log in. 3. Issue the CLOSE_ALL_SESSIONS() command to remove existing sessions: HP Vertica Analytic Database (7.0.x) Page 866 of 1539 SQL Reference Manual SQL Functions => SELECT CLOSE_ALL_SESSIONS(); 4. Query the SESSIONS table: => SELECT * FROM SESSIONS; When the session no longer appears in the SESSIONS table, disconnect and run the Stop Database command. 5. Restart the database. 6. Restore the MaxClientSessions parameter to its original value: => SELECT SET_CONFIG_PARAMETER('MaxClientSessions', 50); See Also l CLOSE_ALL_SESSIONS l CONFIGURATION_PARAMETERS l SESSIONS SHUTDOWN l l l GET_NUM_ACCEPTED_ROWS Returns the number of rows loaded into the database for the last completed load for the current session. GET_NUM_ACCEPTED_ROWS is a meta-function. Do not use it as a value in an INSERT query. The number of accepted rows is not available for a load that is currently in process. Check the LOAD_STREAMS system table for its status. Also, this meta-function supports only loads from STDIN or a single file on the initiator. You cannot use GET_NUM_ACCEPTED_ROWS for multi-node loads. Syntax GET_NUM_ACCEPTED_ROWS(); HP Vertica Analytic Database (7.0.x) Page 867 of 1539 SQL Reference Manual SQL Functions Privileges None Note: The data regarding accepted rows from the last load during the current session does not persist, and is lost when you initiate a new load. See Also l GET_NUM_REJECTED_ROWS GET_NUM_REJECTED_ROWS Returns the number of rows that were rejected during the last completed load for the current session. GET_NUM_REJECTED_ROWS is a meta-function. Do not use it as a value in an INSERT query. Rejected row information is unavailable for a load that is currently running. The number of rejected rows is not available for a load that is currently in process. Check the LOAD_STREAMS system table for its status. Also, this meta-function supports only loads from STDIN or a single file on the initiator. You cannot use GET_NUM_REJECTED_ROWS for multi-node loads. Syntax GET_NUM_REJECTED_ROWS(); Privileges None Note: The data regarding rejected rows from the last load during the current session does not persist, and is dropped when you initiate a new load. See Also l GET_NUM_ACCEPTED_ROWS INTERRUPT_STATEMENT Interrupts the specified statement (within an external session), rolls back the current transaction, and writes a success or failure message to the log file. HP Vertica Analytic Database (7.0.x) Page 868 of 1539 SQL Reference Manual SQL Functions Syntax INTERRUPT_STATEMENT( 'session_id ', statement_id ) Parameters session_id Specifies the session to interrupt. This identifier is unique within the cluster at any point in time. statement_id Specifies the statement to interrupt Privileges Must be a superuser. Notes l Only statements run by external sessions can be interrupted. l Sessions can be interrupted during statement execution. l If the statement_id is valid, the statement is interruptible. The command is successfully sent and returns a success message. Otherwise the system returns an error. Messages The following list describes messages you might encounter: Message Meaning Statement interrupt sent. Check SESSIONS for progress. This message indicates success. Session could not be successfully interrupted: session not found. The session ID argument to the interrupt command does not match a running session. HP Vertica Analytic Database (7.0.x) Page 869 of 1539 SQL Reference Manual SQL Functions Message Meaning Session could not be successfully interrupted: statement not found. The statement ID does not match (or no longer matches) the ID of a running statement (if any). No interruptible statement running The statement is DDL or otherwise non-interruptible. Internal (system) sessions cannot be interrupted. The session is internal, and only statements run by external sessions can be interrupted. Examples Two user sessions are open. RECORD 1 shows user session running SELECT FROM SESSION, and RECORD 2 shows user session running COPY DIRECT: => SELECT * FROM SESSIONS; -[ RECORD 1 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0001 user_name | dbadmin client_hostname | 127.0.0.1:52110 client_pid | 4554 login_timestamp | 2011-01-03 14:05:40.252625-05 session_id | stress04-4325:0x14 client_label | transaction_start | 2011-01-03 14:05:44.325781 transaction_id | 45035996273728326 transaction_description | user dbadmin (select * from sessions;) statement_start | 2011-01-03 15:36:13.896288 statement_id | 10 last_statement_duration_us | 14978 current_statement | select * from sessions; ssl_state | None authentication_method | Trust -[ RECORD 2 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0003 user_name | dbadmin client_hostname | 127.0.0.1:56367 client_pid | 1191 login_timestamp | 2011-01-03 15:31:44.939302-05 session_id | stress06-25663:0xbec client_label | transaction_start | 2011-01-03 15:34:51.05939 transaction_id | 54043195528458775 HP Vertica Analytic Database (7.0.x) Page 870 of 1539 SQL Reference Manual SQL Functions transaction_description | user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT;) statement_start | 2011-01-03 15:35:46.436748 statement_id | 5 last_statement_duration_us | 1591403 current_statement | COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT; ssl_state | None authentication_method | Trust Interrupt the COPY DIRECT statement running in stress06-25663:0xbec: => \xExpanded display is off. => SELECT INTERRUPT_STATEMENT('stress06-25663:0x1537', 5); interrupt_statement -----------------------------------------------------------------Statement interrupt sent. Check v_monitor.sessions for progress. (1 row) Verify that the interrupted statement is no longer active by looking at the current_statement column in the SESSIONS system table. This column becomes blank when the statement has been interrupted: => SELECT * FROM SESSIONS; -[ RECORD 1 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0001 user_name | dbadmin client_hostname | 127.0.0.1:52110 client_pid | 4554 login_timestamp | 2011-01-03 14:05:40.252625-05 session_id | stress04-4325:0x14 client_label | transaction_start | 2011-01-03 14:05:44.325781 transaction_id | 45035996273728326 transaction_description | user dbadmin (select * from sessions;) statement_start | 2011-01-03 15:36:13.896288 statement_id | 10 last_statement_duration_us | 14978 current_statement | select * from sessions; ssl_state | None authentication_method | Trust -[ RECORD 2 ]--------------+---------------------------------------------------node_name | v_vmartdb_node0003 user_name | dbadmin client_hostname | 127.0.0.1:56367 client_pid | 1191 login_timestamp | 2011-01-03 15:31:44.939302-05 session_id | stress06-25663:0xbec client_label | transaction_start | 2011-01-03 15:34:51.05939 transaction_id | 54043195528458775 transaction_description | user dbadmin (COPY Mart_Fact FROM '/data/Mart_Fact.tbl' DELIMITER '|' NULL '\\n' DIRECT;) statement_start | 2011-01-03 15:35:46.436748 statement_id | 5 HP Vertica Analytic Database (7.0.x) Page 871 of 1539 SQL Reference Manual SQL Functions last_statement_duration_us current_statement ssl_state authentication_method | 1591403 | | None | Trust See Also l SESSIONS l Managing Sessions l Configuration Parameters RELEASE_ALL_JVM_MEMORY Forces all sessions to release the memory consumed by their Java Virtual Machines (JVM). Syntax RELEASE_ALL_JVM_MEMORY(); Permissions Must be a superuser. Example The following example demonstrates viewing the JVM memory use in all open sessions, then calling RELEASE_ALL_JVM_MEMORY() to release the memory: => select user_name,jvm_memory_kb FROM V_MONITOR.SESSIONS; user_name | jvm_memory_kb -----------+--------------dbadmin | 79705 (1 row) => SELECT RELEASE_ALL_JVM_MEMORY(); RELEASE_ALL_JVM_MEMORY ----------------------------------------------------------------------------Close all JVM sessions command sent. Check v_monitor.sessions for progress. (1 row) => SELECT user_name,jvm_memory_kb FROM V_MONITOR.SESSIONS; user_name | jvm_memory_kb -----------+--------------dbadmin | 0 (1 row) HP Vertica Analytic Database (7.0.x) Page 872 of 1539 SQL Reference Manual SQL Functions See Also l RELEASE_JVM_MEMORY RELEASE_JVM_MEMORY Terminates a Java Virtual Machine (JVM), making available the memory the JVM was using. Syntax RELEASE_JVM_MEMORY(); Privileges None. Examples User session opened. RECORD 2 shows the user session running COPY DIRECT statement. => SELECT RELEASE_JVM_MEMORY(); release_jvm_memory ----------------------------------------Java process killed and memory released (1 row) See Also l RELEASE_ALL_JVM_MEMORY HP Vertica Analytic Database (7.0.x) Page 873 of 1539 SQL Reference Manual SQL Functions Statistic Management Functions This section contains statistic management functions specific to HP Vertica. ANALYZE_HISTOGRAM Collects and aggregates data samples and storage information from all nodes that store projections associated with the specified table or column. If the function returns successfully (0), HP Vertica writes the returned statistics to the catalog. The query optimizer uses this collected data to recommend the best possible plan to execute a query. Without analyzing table statistics, the query optimizer would assume uniform distribution of data values and equal storage usage for all projections. ANALYZE_HISTOGRAM is a DDL operation that auto-commits the current transaction, if any. The ANALYZE_HISTOGRAM function reads a variable amount of disk contents to aggregate sample data for statistical analysis. Use the function's percent float parameter to specify the total disk space from which HP Vertica collects sample data. The ANALYZE_STATISTICS function returns similar data, but uses a fixed disk space amount (10 percent). Analyzing more than 10 percent disk space takes proportionally longer to process, but produces a higher level of sampling accuracy. ANALYZE_HISTOGRAM is supported on local temporary tables, but not on global temporary tables. Syntax ANALYZE_HISTOGRAM ('') ... | ( '[ [ db-name.]schema.]table [.column-name ]' [, percent ] ) Return Value 0 - For success. If an error occurs, refer to vertica.log for details. Parameters '' Empty string. Collects statistics for all tables. HP Vertica Analytic Database (7.0.x) Page 874 of 1539 SQL Reference Manual SQL Functions [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). table Specifies the name of the table and collects statistics for all projections of that table. If you are using more than one schema, specify the schema that contains the projection, as noted in the [[db-name.]schema.] entry. [.column-name] [Optional] Specifies the name of a single column, typically a predicate column. Using this option with a table specification lets you collect statistics for only that column. Note: If you alter a table to add or drop a column, or add a new column to a table and populate its contents with either default or other values, HP Vertica recommends calling this function on the new table column to get the most current statistics. percent [Optional] Specifies what percentage of data to read from disk (not the amount of data to analyze). Specify a float from 1 – 100, such as 33.3. By default, the function reads 10% of the table data from disk. For more information, see Collecting Statistics in the Administrator's Guide. Privileges l Any INSERT/UPDATE/DELETE privilege on table l USAGE privilege on schema that contains the table Use the HP Vertica statistics functions as follows: HP Vertica Analytic Database (7.0.x) Page 875 of 1539 SQL Reference Manual SQL Functions Use this function... ANALYZE_ STATISTICS To obtain... A fixed-size statistical data sampling (10 percent per disk). This function returns results quickly, but is less accurate than using ANALYZE_HISTOGRAM to get a larger sampling of disk data. ANALYZE_ A specified percentage of disk data sampling (from 1–100). If you analyze more HISTOGRAM than 10 percent data per disk, this function is more accurate than ANALYZE_ STATISTICS, but requires proportionately longer to return statistics. Analyzing Results To retrieve hints about under-performing queries and the associated root causes, use the ANALYZE_WORKLOAD function. This function runs the Workload Analyzer and returns tuning recommendations, such as "run analyze_statistics on schema.table.column". You or your database administrator should act upon the tuning recommendations. You can also find database tuning recommendations on the Management Console. Canceling ANALYZE_HISTOGRAM You can cancel this function mid-analysis by issuing CTRL-C in a vsql shell or by invoking the INTERRUPT_STATEMENT() function. Notes By default, HP Vertica analyzes more than one column (subject to resource limits) in a single-query execution plan to: l Reduce plan execution latency l Help speed up analysis of relatively small tables that have a large number of columns Examples In this example, the ANALYZE_STATISTICS() function reads 10 percent of the disk data. This is the static default value for this function. The function returns 0 for success: => SELECT ANALYZE_STATISTICS('shipping_dimension.shipping_key'); ANALYZE_STATISTICS -------------------0 (1 row) HP Vertica Analytic Database (7.0.x) Page 876 of 1539 SQL Reference Manual SQL Functions This example uses ANALYZE_HISTOGRAM () without specifying a percentage value. Since this function has a default value of 10 percent, it returns the identical data as the ANALYZE_ STATISTICS() function, and returns 0 for success: => SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key'); ANALYZE_HISTOGRAM ------------------0 (1 row) This example uses ANALYZE_HISTOGRAM (), specifying its percent parameter as 100, indicating it will read the entire disk to gather data. After the function performs a full column scan, it returns 0 for success: => SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key', 100); ANALYZE_HISTOGRAM ------------------0 (1 row) In this command, only 0.1% (1/1000) of the disk is read: => SELECT ANALYZE_HISTOGRAM('shipping_dimension.shipping_key', 0.1); ANALYZE_HISTOGRAM ------------------0 (1 row) See Also l ANALYZE_STATISTICS l ANALYZE_WORKLOAD l DROP_STATISTICS l EXPORT_STATISTICS l IMPORT_STATISTICS INTERRUPT_STATEMENT l l ANALYZE_STATISTICS Collects and aggregates data samples and storage information from all nodes that store projections associated with the specified table or column. HP Vertica Analytic Database (7.0.x) Page 877 of 1539 SQL Reference Manual SQL Functions If the function returns successfully (0), HP Vertica writes the returned statistics to the catalog. The query optimizer uses this collected data to recommend the best possible plan to execute a query. Without analyzing table statistics, the query optimizer would assume uniform distribution of data values and equal storage usage for all projections. ANALYZE_STATISTICS is a DDL operation that auto-commits the current transaction, if any. The ANALYZE_STATISTICS function reads a fixed, 10 percent of disk contents to aggregate sample data for statistical analysis. To obtain a larger (or smaller) data sampling, use the ANALYZE_ HISTOGRAM function, which lets you specify the percent of disk to read. Analyzing more that 10 percent disk space takes proportionally longer to process, but results in a higher level of sampling accuracy. ANALYZE_STATISTICS is supported on local temporary tables, but not on global temporary tables. Syntax ANALYZE_STATISTICS [ ('') ... | ( '[ [ db-name.]schema.]table [.column-name ]' ) ] Return value 0 - For success. If an error occurs, refer to vertica.log for details. Parameters '' Empty string. Collects statistics for all tables. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). HP Vertica Analytic Database (7.0.x) Page 878 of 1539 SQL Reference Manual SQL Functions table Specifies the name of the table and collects statistics for all projections of that table. Note: If you are using more than one schema, specify the schema that contains the projection, as noted as noted in the [[db-name.] schema.] entry. [.column-name] [Optional] Specifies the name of a single column, typically a predicate column. Using this option with a table specification lets you collect statistics for only that column. Note: If you alter a table to add or drop a column, or add a new column to a table and populate its contents with either default or other values, HP Vertica recommends calling this function on the new table column to get the most current statistics. Privileges l Any INSERT/UPDATE/DELETE privilege on table l USAGE privilege on schema that contains the table Use the HP Vertica statistics functions as follows: Use this function... ANALYZE_ STATISTICS To obtain... A fixed-size statistical data sampling (10 percent per disk). This function returns results quickly, but is less accurate than using ANALYZE_HISTOGRAM to get a larger sampling of disk data. ANALYZE_ A specified percentage of disk data sampling (from 1–100). If you analyze more HISTOGRAM than 10 percent data per disk, this function is more accurate than ANALYZE_ STATISTICS, but requires proportionately longer to return statistics. Analyzing results To retrieve hints about under-performing queries and the associated root causes, use the ANALYZE_WORKLOAD function. This function runs the Workload Analyzer and returns tuning recommendations, such as "run analyze_statistics on schema.table.column". You or your database administrator should act upon the tuning recommendations. You can also find database tuning recommendations on the Management Console. HP Vertica Analytic Database (7.0.x) Page 879 of 1539 SQL Reference Manual SQL Functions Canceling this function You can cancel statistics analysis by issuing CTRL+C in a vsql shell or by invoking the INTERRUPT_STATEMENT() function. Notes l Always run ANALYZE_STATISTICS on a table or column rather than a projection. l By default, HP Vertica analyzes more than one column (subject to resource limits) in a singlequery execution plan to: l n Reduce plan execution latency n Help speed up analysis of relatively small tables that have a large number of columns Pre-join projection statistics are updated on any pre-joined tables. Examples Computes statistics on all projections in the VMart database and returns 0 (success): => SELECT ANALYZE_STATISTICS (''); analyze_statistics -------------------0 (1 row) Computes statistics on a single table (shipping_dimension) and returns 0 (success): => SELECT ANALYZE_STATISTICS ('shipping_dimension'); analyze_statistics -------------------0 (1 row) Computes statistics on a single column (shipping_key) across all projections for the shipping_ dimension table and returns 0 (success): => SELECT ANALYZE_STATISTICS('shipping_dimension.shipping_key'); analyze_statistics -------------------0 (1 row) For use cases, see Collecting Statistics in the Administrator's Guide HP Vertica Analytic Database (7.0.x) Page 880 of 1539 SQL Reference Manual SQL Functions See Also l ANALYZE_HISTOGRAM l ANALYZE_WORKLOAD l DROP_STATISTICS l EXPORT_STATISTICS l IMPORT_STATISTICS l INTERRUPT_STATEMENT DROP_STATISTICS Removes statistics for the specified table and lets you optionally specify the category of statistics to drop. Syntax DROP_STATISTICS { ('') | ('[[db-name.]schema-name.]table' [, {'BASE' | 'HISTOGRAMS' | 'ALL'} ])}; Return Value 0 - If successful, DROP_STATISTICS always returns 0. If the command fails, DROP_ STATISTICS displays an error message. See vertica.log for message details. Parameters '' Empty string. Drops statistics for all projections. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table Drops statistics for all projections within the specified table. When using more than one schema, specify the schema that contains the table with the projections you want to delete, as noted in the syntax. HP Vertica Analytic Database (7.0.x) Page 881 of 1539 SQL Reference Manual SQL Functions CATEGORY Specifies the category of statistics to drop for the named [db-name.] schema-name.]table: l 'BASE' (default) drops histograms and row counts (min/max column values, histogram. l 'HISTOGRAMS' drops only the histograms. Row counts statistics remain. l 'ALL' drops all statistics. Privileges l INSERT/UPDATE/DELETE privilege on table l USAGE privilege on schema that contains the table Notes Once dropped, statistics can be time consuming to regenerate. Examples The following command analyzes all statistics on the VMart schema database: => SELECT ANALYZE_STATISTICS(''); ANALYZE_STATISTICS -------------------0 (1 row) This command drops base statistics for table store_sales_fact in the store schema: => SELECT DROP_STATISTICS('store.store_sales_fact', 'BASE'); DROP_STATISTICS ----------------0 (1 row) Note that this command works the same as the previous command: => SELECT DROP_STATISTICS('store.store_sales_fact'); DROP_STATISTICS ----------------0 (1 row) This command also drops statistics for all table projections: HP Vertica Analytic Database (7.0.x) Page 882 of 1539 SQL Reference Manual SQL Functions => SELECT DROP_STATISTICS (''); DROP_STATISTICS ----------------0 (1 row) For use cases, see Collecting Statistics in the Administrator's Guide See Also l ANALYZE_STATISTICS l EXPORT_STATISTICS l IMPORT_STATISTICS EXPORT_STATISTICS Generates an XML file that contains statistics for the database. You can optionally export statistics on a single database object (table, projection, or table column). Before you export statistics for the database, run ANALYZE_STATISTICS() to automatically collect the most up to date statistics information. Note: Use the second argument only if statistics in the database do not match the statistics of data. Syntax EXPORT_STATISTICS [ ( 'destination' ) ... | ( '[ [ db-name.]schema.]table [.column-name ]' ) ] Parameters destination Specifies the path and name of the XML output file. An empty string returns the script to the screen. HP Vertica Analytic Database (7.0.x) Page 883 of 1539 SQL Reference Manual SQL Functions [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). table Specifies the name of the table and exports statistics for all projections of that table. Note: If you are using more than one schema, specify the schema that contains the projection, as noted as noted in the [[db-name.] schema.] entry. [.column-name] [Optional] Specifies the name of a single column, typically a predicate column. Using this option with a table specification lets you export statistics for only that column. Privileges Must be a superuser. Examples The following command exports statistics on the VMart example database to a file: vmart=> SELECT EXPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/vmart_stats.xml'); EXPORT_STATISTICS ----------------------------------Statistics exported successfully (1 row) The next statement exports statistics on a single column (price) from a table called food: => SELECT EXPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/price.xml', 'food.pric e'); HP Vertica Analytic Database (7.0.x) Page 884 of 1539 SQL Reference Manual SQL Functions See Also l ANALYZE_STATISTICS l DROP_STATISTICS l IMPORT_STATISTICS l Collecting Database Statistics IMPORT_STATISTICS Imports statistics from the XML file generated by the EXPORT_STATISTICS command. Syntax IMPORT_STATISTICS ( 'destination' ) Parameters destination Specifies the path and name of the XML input file (which is the output of EXPORT_ STATISTICS function). Privileges Must be a superuser. Notes l Imported statistics override existing statistics for all projections on the specified table. l For use cases, see Collecting Statistics in the Administrator's Guide Example Import the statistics for the VMart database that EXPORT_STATISTICS saved. -> SELECT IMPORT_STATISTICS('/opt/vertica/examples/VMart_Schema/vmart_stats.xml'); IMPORT_STATISTICS ---------------------------------------------------------------------------Importing statistics for projection date_dimension_super column date_key failure (stats d id not contain row counts) HP Vertica Analytic Database (7.0.x) Page 885 of 1539 SQL Reference Manual SQL Functions Importing statistics for projection date_dimension_super column date failure (stats did n ot contain row counts) Importing statistics for projection date_dimension_super column full_date_description fai lure (stats did not contain row counts) ... (1 row) VMart=> See Also l ANALYZE_STATISTICS l DROP_STATISTICS l EXPORT_STATISTICS HP Vertica Analytic Database (7.0.x) Page 886 of 1539 SQL Reference Manual SQL Functions Storage Management Functions This section contains storage management functions specific to HP Vertica. ADD_LOCATION Adds a storage location to the cluster. Use this function to add a new location, optionally with a location label. You can also add a location specifically for user access, and then grant one or more users access to the location. Syntax ADD_LOCATION ( 'path' [, 'node' , 'usage', 'location_label' ] ) Parameters path [Required] Specifies where the storage location is mounted. Path must be an empty directory with write permissions for user, group, or all. node [Optional] Indicates the cluster node on which a storage location resides. If you omit this parameter, the function adds the location to only the initiator node. Specifying the node parameter as an empty string ('') adds a storage location to all cluster nodes in a single transaction. Note: If you specify a node, you must also add a usage parameter. usage [Optional] Specifies what the storage location will be used for: l DATA: Stores only data files. Use this option for labeled storage locations. l TEMP: Stores only temporary files, created during loads or queries. l DATA,TEMP: Stores both types of files in the location. l USER: Allows non-dbadmin users access to the storage location for data files (not temp files), once they are granted privileges. DO NOT create a storage location for later use in a storage policy. Storage locations with policies must be for DATA usage. Also, note that this keyword is orthogonal to DATA and TEMP, and does not specify a particular usage, other than being accessible to non-dbadmin users with assigned privileges. You cannot alter a storage location to or from USER usage. NOTE: You can use this parameter only in conjunction with the node option. If you omit the usage parameter, the default is DATA,TEMP. HP Vertica Analytic Database (7.0.x) Page 887 of 1539 SQL Reference Manual SQL Functions location_label [Optional] Specifies a location label as a string, for example, SSD. Labeling a storage location lets you use the location label to create storage policies and as part of a multi-tenanted storage scheme. Privileges Must be a superuser. Storage Location Subdirectories You cannot create a storage location in a subdirectory of an existing location. For example, if you create a storage location at one location, you cannot add a second storage location in a subdirectory of the first: dbt=> select add_location ('/myvertica/Test/KMM','','DATA','SSD'); add_location -----------------------------------------/myvertica/Test/KMM added. (1 row) dbt=> select add_location ('/myvertica/Test/KMM/SSD','','DATA','SSD'); ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert ica/Test/KMM] on node v_node0001 ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert ica/Test/KMM] on node v_node0002 ERROR 5615: Location [/myvertica/Test/KMM/SSD] conflicts with existing location [/myvert ica/Test/KMM] on node v_node0003 Example This example adds a location that stores data and temporary files on the initiator node: => SELECT ADD_LOCATION('/secondverticaStorageLocation/'); This example adds a location to store data on v_vmartdb_node0004: => SELECT ADD_LOCATION('/secondverticaStorageLocation/' , 'v_vmartdb_node0004' , 'DATA'); This example adds a new DATA storage location with a label, SSD. The label identifies the location when you create storage policies. Specifying the node parameter as an empty string adds the storage location to all cluster nodes in a single transaction: VMART=> select add_location ('home/dbadmin/SSD/schemas', '', 'DATA', 'SSD'); add_location --------------------------------home/dbadmin/SSD/schemas added. (1 row) HP Vertica Analytic Database (7.0.x) Page 888 of 1539 SQL Reference Manual SQL Functions See Also l l ALTER_LOCATION_USE l DROP_LOCATION l RESTORE_LOCATION l RETIRE_LOCATION l GRANT (Storage Location) l REVOKE (Storage Location) ALTER_LOCATION_USE Alters the type of files that can be stored at the specified storage location. Syntax ALTER_LOCATION_USE ( 'path' , [ 'node' ] , 'usage' ) Parameters path Specifies where the storage location is mounted. node [Optional] The HP Vertica node with the storage location. Specifying the node parameter as an empty string ('') alters the location across all cluster nodes in a single transaction. If you omit this parameter, node defaults to the initiator. usage Is one of the following: l DATA: The storage location stores only data files. This is the supported use for both a USER storage location, and a labeled storage location. l TEMP: The location stores only temporary files that are created during loads or queries. l DATA,TEMP: The location can store both types of files. Privileges Must be a superuser. HP Vertica Analytic Database (7.0.x) Page 889 of 1539 SQL Reference Manual SQL Functions USER Storage Location Restrictions You cannot change a storage location from a USER usage type if you created the location that way, or to a USER type if you did not. You can change a USER storage location to specify DATA (storing TEMP files is not supported). However, doing so does not affect the primary objective of a USER storage location, to be accessible by non-dbadmin users with assigned privileges. Monitoring Storage Locations Disk storage information that the database uses on each node is available in the V_ MONITOR.DISK_STORAGE system table. Example The following example alters the storage location across all cluster nodes to store only data: => SELECT ALTER_LOCATION_USE ('/thirdVerticaStorageLocation/' , '' , 'DATA'); See Also l l ADD_LOCATION l DROP_LOCATION l RESTORE_LOCATION l RETIRE_LOCATION l GRANT (Storage Location) l REVOKE (Storage Location) ALTER_LOCATION_LABEL Alters the location label. Use this function to add, change, or remove a location label. You change a location label only if it is not currently in use as part of a storage policy. You can use this function to remove a location label. However, you cannot remove a location label if the name being removed is used in a storage policy, and the location from which you are removing the label is the last available storage for its associated objects. Note: If you label an existing storage location that already contains data, and then include the labeled location in one or more storage policies, existing data could be moved. If the ATM HP Vertica Analytic Database (7.0.x) Page 890 of 1539 SQL Reference Manual SQL Functions determines data stored on a labeled location does not comply with a storage policy, the ATM moves the data elsewhere. Syntax ALTER_LOCATION_LABEL ( 'path' , 'node' , 'location_label' ) Parameters path Specifies the path of the storage location. node The HP Vertica node for the storage location. If you enter node as an empty string (''), the function performs a cluster-wide label change to all nodes. Any node that is unavailable generates an error. location_label Specifies a storage label as a string, for instance SSD. You can change an existing label assigned to a storage location, or add a new label. Specifying an empty string ('') removes an existing label. Privileges Must be a superuser. Example The following example alters (or adds) the label SSD to the storage location at the given path on all cluster nodes: VMART=> select alter_location_label('/home/dbadmin/SSD/tables','', 'SSD'); alter_location_label --------------------------------------/home/dbadmin/SSD/tables label changed. (1 row) See Also l l CLEAR_OBJECT_STORAGE_POLICY l SET_OBJECT_STORAGE_POLICY HP Vertica Analytic Database (7.0.x) Page 891 of 1539 SQL Reference Manual SQL Functions CLEAR_CACHES Clears the HP Vertica internal cache files. Syntax CLEAR_CACHES ( ) Privileges Must be a superuser. Notes If you want to run benchmark tests for your queries, in addition to clearing the internal HP Vertica cache files, clear the Linux file system cache. The kernel uses unallocated memory as a cache to hold clean disk blocks. If you are running version 2.6.16 or later of Linux and you have root access, you can clear the kernel filesystem cache as follows: 1. Make sure that all data is the cache is written to disk: # sync 2. Writing to the drop_caches file causes the kernel to drop clean caches, dentries, and inodes from memory, causing that memory to become free, as follows: n To clear the page cache: # echo 1 > /proc/sys/vm/drop_caches n To clear the dentries and inodes: # echo 2 > /proc/sys/vm/drop_caches n To clear the page cache, dentries, and inodes: # echo 3 > /proc/sys/vm/drop_caches Example The following example clears the HP Vertica internal cache files: HP Vertica Analytic Database (7.0.x) Page 892 of 1539 SQL Reference Manual SQL Functions => CLEAR_CACHES(); CLEAR_CACHES -------------Cleared (1 row) CLEAR_OBJECT_STORAGE_POLICY Removes an existing storage policy. The specified object will no longer use a default storage location. Any existing data stored currently at the labeled location in the object's storage policy is moved to default storage during the next TM moveout operation. Syntax CLEAR_OBJECT_STORAGE_POLICY ( 'object_name' , [', key_min, key_max ']) Parameters object_name Specifies the database object with a storage policy to clear. key_min, key_max Specifies the table partition key value ranges stored at the labeled location. These parameters are applicable only when object_name is a table. Privileges Must be a superuser. Example This example clears the storage policy for the object lineorder: release=> select clear_object_storage_policy('lineorder'); clear_object_storage_policy ----------------------------------Default storage policy cleared. (1 row) See Also l Clearing Storage Policies l ALTER_LOCATION_LABEL HP Vertica Analytic Database (7.0.x) Page 893 of 1539 SQL Reference Manual SQL Functions l SET_OBJECT_STORAGE_POLICY DROP_LOCATION Removes the specified storage location. Syntax DROP_LOCATION ( 'path' , 'node' ) Parameters path Specifies where the storage location to drop is mounted. node Is the HP Vertica node where the location is available. Privileges Must be a superuser. Retiring or Dropping a Storage Location Dropping a storage location is a permanent operation and cannot be undone. Therefore, HP recommends that you retire a storage location before dropping it. Retiring a storage location lets you verify that you do not need the storage before dropping it. Additionally, you can easily restore a retired storage location if you determine it is still in use. Storage Locations with Temp and Data Files Dropping storage locations is limited to storage locations that contain only temp files. If you use a storage location to store data and then alter it to store only temp files, the location can still contain data files. HP Vertica does not let you drop a storage location containing data files. You can manually merge out the data files from the storage location, and then wait for the ATM to mergeout the data files automatically, or, you can drop partitions. Deleting data files does not work. Example The following example drops a storage location on node3 that was used to store temp files: => SELECT DROP_LOCATION('/secondHP VerticaStorageLocation/' , 'node3'); HP Vertica Analytic Database (7.0.x) Page 894 of 1539 SQL Reference Manual SQL Functions See Also l l l ADD_LOCATION l ALTER_LOCATION_USE l RESTORE_LOCATION l RETIRE_LOCATION l GRANT (Storage Location) l REVOKE (Storage Location) MEASURE_LOCATION_PERFORMANCE Measures disk performance for the location specified. Syntax MEASURE_LOCATION_PERFORMANCE ( 'path' , 'node' ) Parameters path Specifies where the storage location to measure is mounted. node Is the HP Vertica node where the location to be measured is available. Privileges Must be a superuser. Notes l To get a list of all node names on your cluster, query the V_MONITOR.DISK_STORAGE system table: => SELECT node_name from DISK_STORAGE; HP Vertica Analytic Database (7.0.x) Page 895 of 1539 SQL Reference Manual SQL Functions node_name ------------------v_vmartdb_node0004 v_vmartdb_node0004 v_vmartdb_node0005 v_vmartdb_node0005 v_vmartdb_node0006 v_vmartdb_node0006 (6 rows) l If you intend to create a tiered disk architecture in which projections, columns, and partitions are stored on different disks based on predicted or measured access patterns, you need to measure storage location performance for each location in which data is stored. You do not need to measure storage location performance for temp data storage locations because temporary files are stored based on available space. l The method of measuring storage location performance applies only to configured clusters. If you want to measure a disk before configuring a cluster see Measuring Storage Performance. l Storage location performance equates to the amount of time it takes to read and write 1MB of data from the disk. This time equates to: IO time = Time to read/write 1MB + Time to seek = 1/Throughput + 1/Latency Throughput is the average throughput of sequential reads/writes (units in MB per second) Latency is for random reads only in seeks (units in seeks per second) Note: The IO time of a faster storage location is less than a slower storage location. Example The following example measures the performance of a storage location on v_vmartdb_node0004: => SELECT MEASURE_LOCATION_PERFORMANCE('/secondVerticaStorageLocation/' , 'v_vmartdb_node 0004'); WARNING: measure_location_performance can take a long time. Please check logs for progre ss measure_location_performance -------------------------------------------------Throughput : 122 MB/sec. Latency : 140 seeks/sec HP Vertica Analytic Database (7.0.x) Page 896 of 1539 SQL Reference Manual SQL Functions See Also l ADD_LOCATION l ALTER_LOCATION_USE l RESTORE_LOCATION l RETIRE_LOCATION l Measuring Storage Performance RESTORE_LOCATION Restores a storage location that was previously retired with RETIRE_LOCATION. Syntax RESTORE_LOCATION ( 'path', 'node' ) Parameters path Specifies where the retired storage location is mounted. node Is the HP Vertica node where the retired location is available. Privileges Must be a superuser. Effects of Restoring a Previously Retired Location After restoring a storage location, HP Vertica re-ranks all of the cluster storage locations and uses the newly-restored location to process queries as determined by its rank. Monitoring Storage Locations Disk storage information that the database uses on each node is available in the V_ MONITOR.DISK_STORAGE system table. Example The following example restores the retired storage location on node3: HP Vertica Analytic Database (7.0.x) Page 897 of 1539 SQL Reference Manual SQL Functions => SELECT RESTORE_LOCATION ('/thirdHP VerticaStorageLocation/' , 'v_vmartdb_node0004'); See Also l Altering Storage Location Use l ADD_LOCATION l ALTER_LOCATION_USE l DROP_LOCATION l RETIRE_LOCATION l GRANT (Storage Location) l REVOKE (Storage Location) RETIRE_LOCATION Makes the specified storage location inactive. Syntax RETIRE_LOCATION ( 'path', 'node' ) Parameters path Specifies where the storage location to retire is mounted. node Is the HP Vertica node where the location is available. Privileges Must be a superuser. Effects of Retiring a Storage Location When you use this function, HP Vertica checks that the location is not the only storage for data and temp files. At least one location must exist on each node to store data and temp files, though you can store both sorts of files in either the same location, or separate locations. Note: You cannot retire a location if it is used in a storage policy, and is the last available HP Vertica Analytic Database (7.0.x) Page 898 of 1539 SQL Reference Manual SQL Functions storage for its associated objects. When you retire a storage location: l No new data is stored at the retired location, unless you first restore it with the RESTORE_ LOCATION() function. l If the storage location being retired contains stored data, the data is not moved, so you cannot drop the storage location. Instead, HP Vertica removes the stored data through one or more mergeouts. l If the storage location being retired was used only for temp files, you can drop the location. See Dropping Storage Locations in the Administrators Guide and the DROP_LOCATION() function. Monitoring Storage Locations Disk storage information that the database uses on each node is available in the V_ MONITOR.DISK_STORAGE system table. Example The following example retires a storage location: => SELECT RETIRE_LOCATION ('/secondVerticaStorageLocation/' , 'v_vmartdb_node0004'); See Also l Retiring Storage Locations l ADD_LOCATION l ALTER_LOCATION_USE l DROP_LOCATION l RESTORE_LOCATION l GRANT (Storage Location) l REVOKE (Storage Location) SET_LOCATION_PERFORMANCE Sets disk performance for the location specified. HP Vertica Analytic Database (7.0.x) Page 899 of 1539 SQL Reference Manual SQL Functions Syntax SET_LOCATION_PERFORMANCE ( 'path' , 'node' , 'throughput' , 'average_latency' ) Parameters path Specifies where the storage location to set is mounted. node Is the HP Vertica node where the location to be set is available. If this parameter is omitted, node defaults to the initiator. throughput Specifies the throughput for the location, which must be 1 or more. average_latency Specifies the average latency for the location. The average_latency must be 1 or more. Privileges Must be a superuser. Notes To obtain the throughput and average latency for the location, run the MEASURE_LOCATION_ PERFORMANCE() function before you attempt to set the location's performance. Example The following example sets the performance of a storage location on node2 to a throughput of 122 megabytes per second and a latency of 140 seeks per second. => SELECT SET_LOCATION_PERFORMANCE('/secondVerticaStorageLocation/','node2','122','140'); See Also l ADD_LOCATION l MEASURE_LOCATION_PERFORMANCE l Measuring Storage Performance l Setting Storage Performance HP Vertica Analytic Database (7.0.x) Page 900 of 1539 SQL Reference Manual SQL Functions SET_OBJECT_STORAGE_POLICY Creates or changes an object storage policy by associating a database object with a labeled storage location. Note: You cannot create a storage policy on a USER type storage location. Syntax SET_OBJECT_STORAGE_POLICY ( 'object_name', 'location_label' [, 'key_min, key_max'] [, 'enforc e_storage_move' ] ) Parameters object_name Identifies the database object assigned to a labeled storage location. The object_name can resolve to a database, schema, or table. location_label The label of the storage location with which object_name is being associated. key_min, key_max Applicable only when object_name is a table, key_min and key_max specify the table partition key value range to be stored at the location. enforce_storage_move= {true | false} [Optional] Applicable only when setting a storage policy for an object that has data stored at another labeled location. Specify this parameter as true to move all existing storage data to the target location within this function's transaction. Privileges Must be the object owner to set the storage policy, and have access to the storage location. New Storage Policy If an object does not have a storage policy, this function creates a new policy. The labeled location is then used as the default storage location during TM operations, such as moveout and mergeout. Existing Storage Policy If the object already has an active storage policy, calling this function changes the default storage for the object to the new labeled location. Any existing data stored on the previous storage location is marked to move to the new location during the next TM moveout operations, unless you use the enforce_storage_move option. HP Vertica Analytic Database (7.0.x) Page 901 of 1539 SQL Reference Manual SQL Functions Forcing Existing Data Storage to a New Storage Location You can optionally use this function to move existing data storage to a new location as part of completing the current transaction, by specifying the last parameter as true. To move existing data as part of the next TM moveout, either omit the parameter, or specify its value as false. Note: Specifying the parameter as true performs a cluster-wide operation. If an error occurs on any node, the function displays a warning message, skips the offending node, and continues execution on the remaining nodes. Example This example sets a storage policy for the table states to use the storage labeled SSD as its default location: VMART=> select set_object_storage_policy ('states', 'SSD'); set_object_storage_policy ----------------------------------Default storage policy set. (1 row) See Also l ALTER_LOCATION_LABEL l CLEAR_OBJECT_STORAGE_POLICY l Creating Storage Policies l Moving Data Storage Locations HP Vertica Analytic Database (7.0.x) Page 902 of 1539 SQL Reference Manual SQL Functions Tuple Mover Functions This section contains tuple mover functions specific to HP Vertica. DO_TM_TASK Runs a Tuple Mover operation on one or more projections defined on the specified table. Tip: You do not need to stop the Tuple Mover to run this function. Syntax DO_TM_TASK ( 'task' [ , '[[db-name.]schema.]table' | '[[db-name.]schema.]projection' ] ) Parameters task [[db-name.]schema.] Is one of the following tuple mover operations: l 'moveout' — Moves out all projections on the specified table (if a particular projection is not specified) from WOS to ROS. l 'mergeout' — Consolidates ROS containers and purges deleted records. l 'analyze_row_count' — Automatically collects the number of rows in a projection every 60 seconds and aggregates row counts calculated during loads. [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). HP Vertica Analytic Database (7.0.x) Page 903 of 1539 SQL Reference Manual SQL Functions table Runs a tuple mover operation for all projections within the specified table. When using more than one schema, specify the schema that contains the table with the projections you want to affect, as noted above. projection If projection is not passed as an argument, all projections in the system are used. If projection is specified, DO_TM_TASK looks for a projection of that name and, if found, uses it; if a named projection is not found, the function looks for a table with that name and, if found, moves out all projections on that table. Privileges l Any INSERT/UPDATE/DELETE privilege on table l USAGE privileges on schema Notes DO_TM_TASK() is useful for moving out all projections from a table or database without having to name each projection individually. Examples The following example performs a moveout of all projections for table t1: => SELECT DO_TM_TASK('moveout', 't1'); The following example performs a moveout for projection t1_proj: => SELECT DO_TM_TASK('moveout', 't1_proj') See Also l COLUMN_STORAGE l DROP_PARTITION l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION HP Vertica Analytic Database (7.0.x) Page 904 of 1539 SQL Reference Manual SQL Functions l l HP Vertica Analytic Database (7.0.x) Page 905 of 1539 SQL Reference Manual SQL Functions Workload Management Functions This section contains workload management functions specific to HP Vertica. ANALYZE_WORKLOAD Runs the Workload Analyzer (WLA), a utility that analyzes system information held in system tables. The Workload Analyzer intelligently monitors the performance of SQL queries and workload history, resources, and configurations to identify the root causes for poor query performance. Calling the ANALYZE_WORKLOAD function returns tuning recommendations for all events within the scope and time that you specify. Tuning recommendations are based on a combination of statistics, system and data collector events, and database-table-projection design. WLA's recommendations let database administrators quickly and easily tune query performance without needing sophisticated skills. See Understanding WLA Triggering Conditions in the Administrator's Guide for the most common triggering conditions and recommendations. Syntax 1 ANALYZE_WORKLOAD ( 'scope' , 'since_time' ); Syntax 2 ANALYZE_WORKLOAD ( 'scope' , [ true ] ); Parameters scope Specifies which HP Vertica catalog objects to analyze. Can be one of: l An empty string ('') returns recommendations for all database objects l 'table_name' returns all recommendations related to the specified table l 'schema_name' returns recommendations on all database objects in the specified schema HP Vertica Analytic Database (7.0.x) Page 906 of 1539 SQL Reference Manual SQL Functions sinc e_tim e Limits the recommendations from all events that you specified in 'scope' since the specified time in this argument, up to the current system status. If you omit the since_ time parameter, ANALYZE_WORKLOAD returns recommendations on events since the last recorded time that you called this function. Note: You must explicitly cast strings that you use for the since_time parameter to TIMESTAMP or TIMESTAMPTZ. For example: SELECT ANALYZE_WORKLOAD('T1', '2010-10-04 11:18:15'::TIMESTAMPTZ);SELECT ANALYZE_WO RKLOAD('T1', TIMESTAMPTZ '2010-10-04 11:18:15'); true [Optional] Tells HP Vertica to record this particular call of WORKLOAD_ANALYZER() in the system. The default value is false (do not record). If recorded, subsequent calls to ANALYZE_WORKLOAD analyze only the events that have occurred since this recorded time, ignoring all prior events. Return Value Column Data type Description observation_coun t INTEGER Integer for the total number of events observed for this tuning recommendation. For example, if you see a return value of 1, WLA is making its first tuning recommendation for the event in 'scope'. first_observatio n_time TIMESTAM PTZ Timestamp when the event first occurred. If this column returns a null value, the tuning recommendation is from the current status of the system instead of from any prior event. last_observatio n_time TIMESTAM PTZ Timestamp when the event last occurred. If this column returns a null value, the tuning recommendation is from the current status of the system instead of from any prior event. tuning_parameter VARCHAR Objects on which you should perform a tuning action. For example, a return value of: HP Vertica Analytic Database (7.0.x) l public.t informs the DBA to run Database Designer on table t in the public schema l bsmith notifies a DBA to set a password for user bsmith Page 907 of 1539 SQL Reference Manual SQL Functions Column Data type Description tuning_descripti on VARCHAR Textual description of the tuning recommendation from the Workload Analyzer to perform on the tuning_parameter object. Examples of some of the returned values include, but are not limited to: tuning_command VARCHAR l Run database designer on table schema.table l Create replicated projection for table schema.table l Consider incremental design on query l Reset configuration parameter with SELECT set_config_ parameter('parameter', 'new_value') l Re-segment projection projection-name on highcardinality column(s) l Drop the projection projection-name l Alter a table's partition expression l Reorganize data in partitioned table l Decrease the MoveOutInterval configuration parameter setting Command string if tuning action is a SQL command. For example, the following example statements recommend that the DBA: Update statistics on a particular schema's table.column: SELECT ANALYZE_STATISTICS('public.table.column'); Resolve mismatched configuration parameter 'LockTimeout': SELECT * FROM CONFIGURATION_PARAMETERSWHERE parameter_name = 'LockTimeout'; Set the password for user bsmith: ALTER USER (user) IDENTIFIED BY ('new_password'); HP Vertica Analytic Database (7.0.x) Page 908 of 1539 SQL Reference Manual SQL Functions Column Data type Description tuning_cost VARCHAR Cost is based on the type of tuning recommendation and is one of: l LOW—minimal impact on resources from running the tuning command l MEDIUM—moderate impact on resources from running the tuning command l HIGH—maximum impact on resources from running the tuning command Depending on the size of your database or table, consider running high-cost operations after hours instead of during peak load times. ANALYZE_WORKLOAD() returns aggregated tuning recommendations, as described in the TUNING_RECOMMENDATIONS table. Privileges Must be a superuser. Examples See Analyzing Workloads through an API in the Administrator's Guide for examples. See Also TUNING_RECOMMENDATIONS l l l CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY Changes the run-time priority of a query that is actively running. Syntax CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY(TRANSACTION_ID, 'value') HP Vertica Analytic Database (7.0.x) Page 909 of 1539 SQL Reference Manual SQL Functions Parameters TRANSACTION_ID An identifier for the transaction within the session. TRANSACTION_ID cannot be NULL. You can find the transaction ID in the Sessions table. 'value' The RUNTIMEPRIORITY value. Can be HIGH, MEDIUM, or LOW. Privileges No special privileges required. However, non-super users can change the run-time priority of their own queries only. In addition, non-superusers can never raise the run-time priority of a query to a level higher than that of the resource pool. Example => SELECT CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY(45035996273705748, 'low'); CHANGE_RUNTIME_PRIORITY Changes the run-time priority of a query that is actively running. Note that, while this function is still valid, you should instead use CHANGE_CURRENT_STATEMENT_RUNTIME_PRIORITY to change run-time priority. CHANGE_RUNTIME_PRIORITY will be deprecated in a future release of Vertica. Syntax CHANGE_RUNTIME_PRIORITY(TRANSACTION_ID,STATEMENT_ID, 'value') Parameters TRANSACTION_ID An identifier for the transaction within the session. TRANSACTION_ID cannot be NULL. You can find the transaction ID in the Sessions table. STATEMENT_ID A unique numeric ID assigned by the HP Vertica catalog, which identifies the currently executing statement. You can find the statement ID in the Sessions table. You can specify NULL to change the run-time priority of the currently running query within the transaction. 'value' The RUNTIMEPRIORITY value. Can be HIGH, MEDIUM, or LOW. HP Vertica Analytic Database (7.0.x) Page 910 of 1539 SQL Reference Manual SQL Functions Privileges No special privileges required. However, non-super users can change the run-time priority of their own queries only. In addition, non-superusers can never raise the run-time priority of a query to a level higher than that of the resource pool. Example => SELECT CHANGE_RUNTIME_PRIORITY(45035996273705748, NULL, 'low'); CLEAR_CACHES Clears the HP Vertica internal cache files. Syntax CLEAR_CACHES ( ) Privileges Must be a superuser. Notes If you want to run benchmark tests for your queries, in addition to clearing the internal HP Vertica cache files, clear the Linux file system cache. The kernel uses unallocated memory as a cache to hold clean disk blocks. If you are running version 2.6.16 or later of Linux and you have root access, you can clear the kernel filesystem cache as follows: 1. Make sure that all data is the cache is written to disk: # sync 2. Writing to the drop_caches file causes the kernel to drop clean caches, dentries, and inodes from memory, causing that memory to become free, as follows: n To clear the page cache: # echo 1 > /proc/sys/vm/drop_caches n To clear the dentries and inodes: HP Vertica Analytic Database (7.0.x) Page 911 of 1539 SQL Reference Manual SQL Functions # echo 2 > /proc/sys/vm/drop_caches n To clear the page cache, dentries, and inodes: # echo 3 > /proc/sys/vm/drop_caches Example The following example clears the HP Vertica internal cache files: => CLEAR_CACHES(); CLEAR_CACHES -------------Cleared (1 row) SLEEP Waits a specified number of seconds before executing another statement or command. Syntax SLEEP( seconds ) Parameters seconds The wait time, specified in one or more seconds (0 or higher) expressed as a positive integer. Single quotes are optional; for example, SLEEP(3) is the same as SLEEP ('3'). Notes l This function returns value 0 when successful; otherwise it returns an error message due to syntax errors. l You cannot cancel a sleep operation. l Be cautious when using SLEEP() in an environment with shared resources, such as in combination with transactions that take exclusive locks. Example The following command suspends execution for 100 seconds: HP Vertica Analytic Database (7.0.x) Page 912 of 1539 SQL Reference Manual SQL Functions => SELECT SLEEP(100); sleep ------0 (1 row) HP Vertica Analytic Database (7.0.x) Page 913 of 1539 SQL Reference Manual SQL Functions HP Vertica Analytic Database (7.0.x) Page 914 of 1539 SQL Reference Manual SQL Statements SQL Statements The primary structure of a SQL query is its statement. Multiple statements are separated by semicolons; for example: CREATE TABLE fact ( ..., date_col date NOT NULL, ...); CREATE TABLE fact(..., state VARCHAR NOT NULL, ...); ALTER DATABASE Use ALTER DATABASE to: l Drop all fault groups and their child fault groups from the specified database. l Specify the subnet name of a public network to be used for import/export. Syntax ALTER DATABASE database-name [ ... [ DROP ALL FAULT GROUP ... | EXPORT ON { subnet-name | DEFAULT } ] Parameters database-name The name of the database you want to alter. DROP ALL FAULT GROUP Drops all fault groups defined on the specified database. Notice the syntax for DROP ALL FAULT GROUP is singular for GROUP). EXPORT ON subnet-name Specifies the subnet of the public network to be used for import/export. When set to DEFAULT, Vertica Analytic Database assumes that export should go to a private network. Permissions Must be a superuser to alter the database. Example The following command drops all fault groups from the exampledb database: exampledb=> ALTER DATABASE exampledb DROP ALL FAULT GROUP; ALTER DATABASE HP Vertica Analytic Database (7.0.x) Page 915 of 1539 SQL Reference Manual SQL Statements See Also Fault Groups in the Administrator's Guide High Availability With Fault Groups in the Concepts Guide Using Public and Private Networks in the Administrator's Guide ALTER NODE in the SQL Reference Manual ALTER FAULT GROUP Modifies an existing fault group. For example, use the ALTER FAULT GROUP statement to: l Add a node to or drop a node from an existing fault group l Add a child fault group to or drop a child fault group from a parent fault group l Rename a fault group Syntax ALTER ... [ ... [ ... [ ... [ ... [ FAULT GROUP fault-group-name ADD NODE node-name ] DROP NODE node-name ] ADD FAULT GROUP child-fault-group-name ] DROP FAULT GROUP child-fault-group-name ] RENAME TO new-fault-group-name ] Parameters fault-group-name The existing fault group name you want to modify. Tip: For a list of all fault groups defined in the cluster, query the V_CATALOG.FAULT_GROUPS system table. node-name The node name you want to add to or drop from the existing (parent) fault group. child-fault-group-name The name of the child fault group you want to add to or remove from an existing parent fault group. new-fault-group-name The new name for the fault group you want to rename. HP Vertica Analytic Database (7.0.x) Page 916 of 1539 SQL Reference Manual SQL Statements Permissions Must be a superuser to alter a fault group. Example This example renames the parent0 fault group to parent100: exampledb=> ALTER FAULT GROUP parent0 RENAME TO parent100; ALTER FAULT GROUP You can verify the change by querying the V_CATALOG.FAULT_GROUPS system table: exampledb=> SELECT member_name FROM fault_groups; member_name ---------------------v_exampledb_node0003 parent100 mygroup (3 rows) See Also V_CATALOG.FAULT_GROUPS and V_CATALOG.CLUSTER_LAYOUT Fault Groups in the Administrator's Guide High Availability With Fault Groups in the Concepts Guide ALTER FUNCTION Alters a user-defined SQL function or user defined function (UDF) by providing a new function or different schema name or my modifying its Fenced Mode setting. Syntax 1 ALTER FUNCTION... [[db-name.]schema.]function-name ( [ [ argname ] argtype ... RENAME TO new_name ... SET FENCED bool_val [, ...] ] ) Syntax 2 ALTER FUNCTION... [[db-name.]schema.]function-name ( [ [ argname ] argtype ... SET SCHEMA new_schema ... SET FENCED bool_val HP Vertica Analytic Database (7.0.x) [, ...] ] ) Page 917 of 1539 SQL Reference Manual SQL Statements Syntax 3 ALTER FUNCTION... [[db-name.]schema.]function-name ( [ [ argname ] argtype ... SET FENCED bool_val [, ...] ] ) Parameters [[db-name.]schema-name.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). function-name The name of the user-defined SQL Function (function body) to alter. If the function name is schema-qualified (as described above), the function is altered in the specified schema. argname Specifies the name of the argument. argtype Specifies the data type for argument that is passed to the function. Argument types must match HP Vertica type names. See SQL Data Types. RENAME TO new_name Specifies the new name of the function SET SCHEMA new_schema Specifies the new schema name where the function resides. SET FENCED bool_val A boolean value that specifies if Fenced Mode is enabled for this function. Fenced Mode is not available for User Defined Aggregates or User Defined Load. Permissions l Only a superuser or owner can alter a function. l To rename a function (ALTER FUNCTION RENAME TO) the user must have USAGE and CREATE privilege on schema that contains the function. HP Vertica Analytic Database (7.0.x) Page 918 of 1539 SQL Reference Manual SQL Statements l To specify a new schema (ALTER FUNCTION SET SCHEMA), the user must have USAGE privilege on schema that currently contains the function (old schema) and CREATE privilege on the schema to which the function will be moved (new schema). Notes When you alter a function you must specify the argument type, because there could be several functions that share the same name with different argument types. Examples This example creates a SQL function called zerowhennull that accepts an INTEGER argument and returns an INTEGER result. => CREATE FUNCTION zerowhennull(x INT) RETURN INT AS BEGIN RETURN (CASE WHEN (x IS NOT NULL) THEN x ELSE 0 END); END; This next command renames the zerowhennull function to zeronull: => ALTER FUNCTION zerowhennull(x INT) RENAME TO zeronull; ALTER FUNCTION This command moves the renamed function to a new schema called macros: => ALTER FUNCTION zeronull(x INT) SET SCHEMA macros; ALTER FUNCTION This command disables Fenced Mode for the Add2Ints function: => ALTER FUNCTION Add2Ints(INT, INT) SET FENCED false; ALTER FUNCTION See Also l CREATE FUNCTION (SQL Functions) l DROP FUNCTION l GRANT (User Defined Extension) l REVOKE (User Defined Extension) HP Vertica Analytic Database (7.0.x) Page 919 of 1539 SQL Reference Manual SQL Statements l USER_FUNCTIONS l Using User-Defined SQL Functions ALTER LIBRARY Replaces the Linux shared object library file (.so) or R file for an already-defined library with a new file. The new file is automatically distributed throughout the HP Vertica cluster. See Developing and Using User Defined Functions in the Programmer's Guide for details. All of the functions that reference the library automatically begin using the new library file after it is loaded. Note: The new library must be developed in the same language as the library file being replaced. For example, you cannot use this statement to replace a C++ library file with an R library file. Syntax ALTER LIBRARY [[db-name.]schema.]library_name AS 'library_path'; Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). library_name The name of the library being altered. This library must have already been created using CREATE LIBRARY. library_path The absolute path to the replacement library file. The file must be the same type as the library file used by the current library definition. Permissions Must be a superuser to alter a library. Notes l All of the UDFs that reference the library begin calling the code in the updated library file once it has been distributed to all of the nodes in the HP Vertica cluster. HP Vertica Analytic Database (7.0.x) Page 920 of 1539 SQL Reference Manual SQL Statements l Any nodes that are down or that are added to the cluster later automatically receive a copy of the updated library file when they join the cluster. l HP Vertica does not compare the functions defined in the new library to ensure they match any currently-defined functions in the catalog. If you change the signature of a function in the library (for example, if you change the number and data types accepted by a UDSF defined in the library), calls to that function will likely generate errors. If your new library file changes the definition of a function, you must remove the function using DROP FUNCTION before using ALTER LIBRARY to load the new library. You can then recreate the function using its new signature. ALTER NODE When used with the EXPORT ON clause, specifies the network interface of the public network on individual nodes that will be used for import/export. Caution: ALTER NODE is used internally by HP Vertica. Do not use ALTER NODE for any purpose other than importing/exporting to a public network. Syntax ALTER NODE node-name EXPORT ON {network-interface-name|DEFAULT} Parameters node-name The name of the database you want to alter. EXPORT ON network-interface-n ame Specifies the network interface of the public network on the node that will be used for import/export. Permissions Must be a superuser to alter the database. See Also Using Public and Private Networks in the Administrator's Guide In the SQL Reference Manual: l ALTER DATABASE l CREATE SUBNET HP Vertica Analytic Database (7.0.x) Page 921 of 1539 SQL Reference Manual SQL Statements l CREATE NETWORK INTERFACE l V_MONITOR.NETWORK INTERFACES ALTER NETWORK INTERFACE Lets you rename a network interface. Syntax ALTER NETWORK INTERFACE network-interface-name RENAME TO new-network-interface-name The parameters are defined as follows: network-interface-name The name of the existing network interface. new-network-interface-name The new name for the network interface. Permissions Must be a superuser to alter a network interface. ALTER PROJECTION RENAME Initiates a rename operation on the specified projection. Syntax ALTER PROJECTION [ [db-name.]schema.]projection-name RENAME TO new-projection-name HP Vertica Analytic Database (7.0.x) Page 922 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection-name Specifies the projection to change. You must include the base table name prefix that is added automatically when you create a projection. new-projection-name Specifies the new projection name. Permissions To rename a projection, the user must own the anchor table for which the projection was created and have USAGE and CREATE privileges on the schema that contains the projection. Notes The projection must exist before it can be renamed. See Also l CREATE PROJECTION ALTER PROFILE Changes a profile. Only a database superuser can alter a profile. Syntax ALTER PROFILE name LIMIT ... [PASSWORD_LIFE_TIME {life-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_GRACE_TIME {grace_period | DEFAULT | UNLIMITED}] ... [FAILED_LOGIN_ATTEMPTS {login-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_LOCK_TIME {lock-period | DEFAULT | UNLIMITED}] ... [PASSWORD_REUSE_MAX {reuse-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_REUSE_TIME {reuse-period | DEFAULT | UNLIMITED}] ... [PASSWORD_MAX_LENGTH {max-length | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LENGTH {min-length | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LETTERS {min-letters | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_UPPERCASE_LETTERS {min-cap-letters | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LOWERCASE_LETTERS {min-lower-letters | DEFAULT | UNLIMITED}] HP Vertica Analytic Database (7.0.x) Page 923 of 1539 SQL Reference Manual SQL Statements ... [PASSWORD_MIN_DIGITS {min-digits | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_SYMBOLS {min-symbols | DEFAULT | UNLIMITED}] Note: For all parameters, the special value DEFAULT means the parameter is inherited from the DEFAULT profile. Parameters Meaning of UNLIMITED value Name Description name The name of the profile to create PASSWORD_LIFE_TIME life-limit Integer number of days a Passwords password remains valid. never expire. After the time elapses, the user must change the password (or will be warned that their password has expired if PASSWORD_GRACE_ TIME is set to a value other than zero or UNLIMITED). PASSWORD_GRACE_TIMEgrace-period Integer number of days the users are allowed to login (while being issued a warning message) after their passwords are older than the PASSWORD_ LIFE_TIME. After this period expires, users are forced to change their passwords on login if they have not done so after their password expired. No grace period (the same as zero) FAILED_LOGIN_ATTEMPTSlogin-limit The number of consecutive failed login attempts that result in a user's account being locked. Accounts are never locked, no matter how many failed login attempts are made. HP Vertica Analytic Database (7.0.x) N/A Page 924 of 1539 SQL Reference Manual SQL Statements Meaning of UNLIMITED value Name Description PASSWORD_LOCK_TIME lock-period Integer value setting the number of days an account is locked after the user's account was locked by having too many failed login attempts. After the PASSWORD_LOCK_ TIME has expired, the account is automatically unlocked. Accounts locked because of too many failed login attempts are never automatically unlocked. They must be manually unlocked by the database superuser. PASSWORD_REUSE_MAX reuse-limit The number of password changes that need to occur before the current password can be reused. Users are not required to change passwords a certain number of times before reusing an old password. PASSWORD_REUSE_TIMEreuse-period The integer number of days that must pass after a password has been set before the before it can be reused. Password reuse is not limited by time. PASSWORD_MAX_LENGTH max-length The maximum number of characters allowed in a password. Value must be in the range of 8 to 100. Passwords are limited to 100 characters. PASSWORD_MIN_LENGTH min-length The minimum number of characters required in a password. Valid range is 0 to max-length. Equal to maxlength. PASSWORD_MIN_LETTERSmin-of-letters Minimum number of letters (a-z and A-Z) that must be in a password. Valid ranged is 0 to max-length. 0 (no minimum). HP Vertica Analytic Database (7.0.x) Page 925 of 1539 SQL Reference Manual SQL Statements Meaning of UNLIMITED value Name Description PASSWORD_MIN_UPPERCASE_LETTERSmin-cap-letters Minimum number of capital letters (A-Z) that must be in a password. Valid range is is 0 to max-length. 0 (no minimum). PASSWORD_MIN_LOWERCASE_LETTERSmin-lower-letters Minimum number of lowercase letters (a-z) that must be in a password. Valid range is is 0 to maxlength. 0 (no minimum). PASSWORD_MIN_DIGITS min-digits Minimum number of digits (0-9) that must be in a password. Valid range is is 0 to max-length. 0 (no minimum). PASSWORD_MIN_SYMBOLSmin-symbols Minimum number of 0 (no symbols (any printable minimum). non-letter and non-digit character, such as $, #, @, and so on) that must be in a password. Valid range is is 0 to max-length. Permissions Must be a superuser to alter a profile. Note: Only the profile settings for how many failed login attempts trigger account locking and how long accounts are locked have an effect on external password authentication methods such as LDAP or Kerberos. All password complexity, reuse, and lifetime settings have an effect on passwords managed by HP Vertica only. See Also l CREATE PROFILE l DROP PROFILE ALTER PROFILE RENAME Rename an existing profile. HP Vertica Analytic Database (7.0.x) Page 926 of 1539 SQL Reference Manual SQL Statements Syntax ALTER PROFILE name RENAME TO newname; Parameters name The current name of the profile. newname The new name for the profile. Permissions Must be a superuser to alter a profile. See Also l ALTER PROFILE l CREATE PROFILE l DROP PROFILE ALTER RESOURCE POOL Modifies a resource pool. The resource pool must exist before you can issue the ALTER RESOURCE POOL command. Syntax ALTER ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ] ... [ RESOURCE POOL pool-name MEMORYSIZE 'sizeUnits' MAXMEMORYSIZE 'sizeUnits' ] PRIORITY {integer | DEFAULT } ] EXECUTIONPARALLELISM {integer | AUTO | DEFAULT } ] RUNTIMEPRIORITY (HIGH | MEDIUM | LOW | DEFAULT) ] RUNTIMEPRIORITYTHRESHOLD {integer |DEFAULT }] QUEUETIMEOUT {integer | NONE |DEFAULT } ] PLANNEDCONCURRENCY {integer | DEFAULT | AUTO } ] RUNTIMECAP {interval | NONE |DEFAULT } ] MAXCONCURRENCY {integer | NONE | DEFAULT } ] SINGLEINITIATOR { bool | DEFAULT } ] CPUAFFINITYSET { 'cpuIndex' | 'cpuIndex list' | 'integer percentage' | NONE | DEFAULT } CPUAFFINITYMODE { SHARED | EXCLUSIVE | ANY | DEFAULT } ] HP Vertica Analytic Database (7.0.x) Page 927 of 1539 SQL Reference Manual SQL Statements Parameters If you set any of these parameters to DEFAULT, HP Vertica sets the parameter to the value stored in RESOURCE_POOL_DEFAULTS. pool-name Specifies the name of the resource pool to alter. Resource pool names are subject to the same rules as HP Vertica Identifiers. Built-in pool names cannot be used for userdefined pools. MEMORYSIZE 'sizeUnits' [Default 0%] The amount of memory allocated to this pool per node and not across the whole cluster. The default of 0% means that the pool has no memory allocated to it and must exclusively borrow from the GENERAL pool. Units can be one of the following: l Percentage (%) of total memory available to the Resource Manager. (In this case size must be 0-100). l K Kilobytes l M Megabytes l G Gigabytes l T Terabytes See also MAXMEMORYSIZE parameter. HP Vertica Analytic Database (7.0.x) Page 928 of 1539 SQL Reference Manual SQL Statements MAXMEMORYSIZE'sizeUnits' | NONE [Default unlimited] Maximum size the resource pool could grow by borrowing memory from the GENERAL pool. See BuiltIn Pools for a discussion on how resource pools interact with the GENERAL pool. Units can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case, size must be 0-100). This notation has special meaning for the GENERAL pool, described in Notes below. l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes If MAXMEMORYSIZE NONE is specified, there is no upper limit. Note: The MAXMEMORYSIZE parameter refers to the maximum memory borrowed by this pool per node and not across the whole cluster. The default of unlimited means that the pool can borrow as much memory from GENERAL pool as is available. The MAXMEMORYSIZE of the WOSDATA and SYSDATA pools cannot be changed as long as any of their memory is in use. For example, in order to change the MAXMEMORYSIZE of the WOSDATA pool, you need to disable any trickle loading jobs and wait until the WOS is empty before you can change the MAXMEMORYSIZE. HP Vertica Analytic Database (7.0.x) Page 929 of 1539 SQL Reference Manual SQL Statements EXECUTIONPARALLELISM [Default: AUTO] Limits the number of threads used to process any single query issued in this resource pool. When set to AUTO, HP Vertica sets this value based on the number of cores, available memory, and amount of data in the system. Unless data is limited, or the amount of data is very small, HP Vertica sets this value to the number of cores on the node. Reducing this value increases the throughput of short queries issued in the pool, especially if the queries are executed concurrently. If you choose to set this parameter manually, set it to a value between 1 and the number of cores. RUNTIMEPRORITY [Default: MEDIUM] Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to queries already running in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. RUNTIMEPRIORITYTHRESHOLD Specifies a time limit (in seconds) by which a query must finish before the Resource Manager assigns to it the RUNTIMEPRIORITY of the resource pool. All queries begin runnng at a HIGH priority. When a query's duration exceeds this threshold, it is assigned the RUNTIMEPRIORITY of the resource pool. [Default 2] PRIORITY HP Vertica Analytic Database (7.0.x) [Default 0] An integer that represents priority of queries in this pool, when they compete for resources in the GENERAL pool. Higher numbers denote higher priority. Administrator-created resource pools can have a priority of -100 to 100. The built-in resource pools SYSQUERY, RECOVERY, and TM can have a range of -110 to 110. Page 930 of 1539 SQL Reference Manual SQL Statements QUEUETIMEOUT [Default 300 seconds] An integer, in seconds, that represents the maximum amount of time the request is allowed to wait for resources to become available before being rejected. If set to NONE, the request can be queued for an unlimited amount of time. RUNTIMECAP HP Vertica Analytic Database (7.0.x) [Default: NONE] Sets the maximum amount of time any query on the pool can execute. Set RUNTIMECAP using interval, such as '1 minute' or '100 seconds' (see Interval Values for details). This value cannot exceed one year. Setting this value to NONE specifies that there is no time limit on queries running on the pool. If the user or session also has a RUNTIMECAP, the shorter limit applies. Page 931 of 1539 SQL Reference Manual SQL Statements PLANNEDCONCURRENCY [Default: AUTO] When set to AUTO, this value is calculated automatically at query runtime. HP Vertica sets this parameter to the lower of these two calculations: l Number of cores l Memory/2GB When this parameter is set to AUTO, HP Vertica will not choose a value lower than 4. HP Vertica advises changing this value only after evaluating performance over a period of time. Notes: l The PLANNEDCONCURRENCY setting for the GENERAL pool defaults to a too-small value for machines with large numbers of cores. To adjust to a more appropriate value: => ALTER RESOURCE POOL general PLANNEDCONCURRENCY <#cores>; l This is a cluster-wide maximum and not a per-node limit. l For clusters where the number of cores differs on different nodes, AUTO can apply differently on each node. Distributed queries run like the minimal effective planned concurrency. Single node queries run with the planned concurrency of the initiator. l If you created or upgraded your database in 4.0 or 4.1, the PLANNEDCONCURRENCY setting on the GENERAL pool defaults to a too-small value for machines with large numbers of cores. To adjust to a more appropriate value: => ALTER RESOURCE POOL general PLANNEDCONCURRENCY <#cores>; You need to set this parameter only if you created a database before 4.1, patchset 1. See Guidelines for Setting Pool Parameters in the Administrator's Guide SINGLEINITIATOR HP Vertica Analytic Database (7.0.x) [Default false] This parameter is included for backwards compatibility only. Do not change the value. Page 932 of 1539 SQL Reference Manual SQL Statements MAXCONCURRENCY [Default unlimited] An integer that represents the maximum number of concurrent execution slots available to the resource pool. If MAXCONCURRENCY NONE is specified, there is no limit. Note: This is a cluster wide maximum and NOT a per-node limit. HP Vertica Analytic Database (7.0.x) Page 933 of 1539 SQL Reference Manual SQL Statements CPUAFFINITYSET [Default none] The set of CPUs on which queries associated with this pool are executed. Can only be used with userdefined resource pools (is_internal = f). Note: If you are changing the CPUAFFINITYSET from the default value (NONE), then you must also specify the CPUAFFINITYMODE at the same time. For example, when creating a new resource pool, or altering an existing resource pool that has a CPUAFFINITYSET that is not defined (or NONE), then specify CPUAFFINITYMODE to a supported mode for the set: CREATE RESOURCE POOL load CPUAFFINITYSET '25%' CPUAFFINITYMODE SHARED For this setting, CPU numbering is defined by the number of CPUs in the system based on a 0 index. You can obtain the number of CPUs on the system with the command: lscpu | grep "^CPU(s)" For example, if the above command returned: CPU(s): 8, then 0–7 are valid CPU indexes for this parameter. Note: HP Vertica is limited to 1024 CPUs per node. Value of this parameter can be one of the following: l 'cpuIndex'—Index of a specific CPU on which to run the queries for this pool. For example '3'. Queries in this pool are not run on any other CPUs besides the CPU defined. l 'cpuIndex list'—List of CPUs on which to run the queries for this pool. CPU indexes can be comma-separated for non-continous indexes, or use the '-' character for continuous CPU indexes. For example, '0,2–4' is a CPU index list containing CPU 0, CPU 2, CPU 3, and CPU 4. Queries in this pool are not run on any other CPUs besides the CPUs defined. Note: The cpuIndex must be unique across all resource pools if using a CPUAFFINITYMODE of exclusive. the cpuIndex does not need to be unqiue l HP Vertica Analytic Database (7.0.x) 'integer percentage'—Percentage of all available CPUs to use for this query. For example '50%' uses up to half of the Page 934 of 1539 SQL Reference Manual SQL Statements available CPUs that are not reserved in other resource pools (with EXCLUSIVE affinity) for queries in this pool. Note that you must define this setting in whole percentages and that HP Vertica rounds the percentages down to account for whole CPU units. For example, a '20%' setting on an 8 CPU system is rounded down to 12.5% actual CPU percentage. (1/8 = 12.5% 2/8 - 25%). In a 16 CPU system, the setting is rounded down to 18.75% (3/16 = 18.75%, 4/16 = 25%). l NONE—Set no CPU affinity for this resource pool. The queries associated with this pool are executed on any CPU. l DEFAULT—Same as NONE. Important: CPU affinity settings apply to all nodes in the cluster. CPU counts must be identical on all nodes in the cluster. HP Vertica Analytic Database (7.0.x) Page 935 of 1539 SQL Reference Manual SQL Statements CPUAFFINITYMODE [Default any] The mode in which CPU affinity operates for this resource pool. Can be one of: l SHARED—Queries run in this pool are constrained to run only on CPUs defined in CPUAFFINITYSET, but other HP Vertica resource pools can also run queries that utilize the same CPUs. l EXCLUSIVE—The CPUs defined in CPUAFFINITYSET are exclusively assigned to this resource pool. Other HP Vertica resource pools are unable to use the CPUs. In the case that CPUAFFINITYSET is set as a percentage, then that percentage of CPU resources available to HP Vertica is assigned solely for this resource pool. l ANY—Queries can be run on any CPU. If CPUAFFINITYSET is set to a non-default value, and you then set CPUAFFINITYMODE to ANY, then the CPUAFFINITYSET is removed (set to NONE) by HP Vertica, since the ANY mode is only valid for the NONE set. l DEFAULT—Same as ANY. Note: Important! CPU affinity settings apply to all nodes in the cluster. CPU counts must be identical on all nodes in the cluster. Permissions Must be a superuser on the resource pool for the following parameters: l MAXMEMORYSIZE l PRIORITY l QUEUETIMEOUT l CPUAFFINITYSET l CPUAFFINITYMODE The following parameters require UPDATE privileges: l PLANNEDCONCURRENCY l SINGLEINITIATOR HP Vertica Analytic Database (7.0.x) Page 936 of 1539 SQL Reference Manual SQL Statements MAXCONCURRENCY l Notes l New resource pools can be created or altered without shutting down the system. The only exception is that changes to GENERAL.MAXMEMORYSIZE take effect only on a node restart. When a new pool is created (or its size altered), MEMORYSIZE amount of memory is taken out of the GENERAL pool. If the GENERAL pool does not currently have sufficient memory to create the pool due to existing queries being processed, a request is made to the system to create a pool as soon as resources become available. The pool is in operation as soon as the specified amount of memory becomes available. You can monitor whether the ALTER has been completed in the V_ MONITOR.RESOURCE_POOL_STATUS system table. l If the GENERAL.MAXMEMORYSIZE parameter is modified while a node is down, and that node is restarted, the restarted node sees the new setting whereas other nodes continue to see the old setting until they are restarted. HP Vertica recommends that you do not change this parameter unless absolutely necessary. l Under normal operation, MEMORYSIZE is required to be less than MAXMEMORYSIZE and an error is returned during CREATE/ALTER operations if this size limit is violated. However, under some circumstances where the node specification changes by addition/removal of memory, or if the database is moved to a different cluster, this invariant could be violated. In this case, MAXMEMORYSIZE is reduced to MEMORYSIZE. l If two pools have the same PRIORITY, their requests are allowed to borrow from the GENERAL pool in order of arrival. l CPUAFFINITYSET and CPUAFFINITYMODE cane only be used with user-created resource pools. See Guidelines for Setting Pool Parameters in the Administrator's Guide for details about setting these parameters. See Also l CREATE RESOURCE POOL l CREATE USER l DROP RESOURCE POOL l RESOURCE_POOL_STATUS l SET SESSION RESOURCE_POOL SET SESSION MEMORYCAP l l HP Vertica Analytic Database (7.0.x) Page 937 of 1539 SQL Reference Manual SQL Statements ALTER ROLE RENAME Rename an existing role. Syntax ALTER ROLE name RENAME [TO] new_name; Parameters name The current name of the role that you want to rename. new_name The new name for the role. Permissions Must be a superuser to rename a role. Example => ALTER ROLE applicationadministrator RENAME TO appadmin; ALTER ROLE See Also l CREATE ROLE l DROP ROLE ALTER SCHEMA Renames one or more existing schemas. Syntax ALTER SCHEMA [db-name.]schema-name [ , ... ] HP Vertica Analytic Database (7.0.x) ... RENAME TO new-schema-name [ , ... ] Page 938 of 1539 SQL Reference Manual SQL Statements Parameters [db-name.] [Optional] Specifies the current database name. Using a database name prefix is optional, and does not affect the command in any way. You must be connected to the specified database. schema-name Specifies the name of one or more schemas to rename. RENAME TO Specifies one or more new schema names. The lists of schemas to rename and the new schema names are parsed from left to right and matched accordingly using one-to-one correspondence. When renaming schemas, be sure to follow these standards: l The number of schemas to rename must match the number of new schema names supplied. l The new schema names must not already exist. The RENAME TO parameter is applied atomically. Either all the schemas are renamed or none of the schemas are renamed. If, for example, the number of schemas to rename does not match the number of new names supplied, none of the schemas are renamed. Note: Renaming a schema that is referenced by a view will cause the view to fail unless another schema is created to replace it. Privileges Schema owner or user requires CREATE privilege on the database Notes Renaming schemas does not affect existing pre-join projections because pre-join projections refer to schemas by the schemas' unique numeric IDs (OIDs), and the OIDs for schemas are not changed by ALTER SCHEMA. Tip Renaming schemas is useful for swapping schemas without actually moving data. To facilitate the swap, enter a non-existent, temporary placeholder schema. The following example uses the temporary schema temps to facilitate swapping schema S1 with schema S2. In this example, S1 is renamed to temps. Then S2 is renamed to S1. Finally, temps is renamed to S2. ALTER SCHEMA S1, S2, temps RENAME TO temps, S1, S2; HP Vertica Analytic Database (7.0.x) Page 939 of 1539 SQL Reference Manual SQL Statements Examples The following example renames schema S1 to S3 and schema S2 to S4: => ALTER SCHEMA S1, S2 RENAME TO S3, S4; See Also l CREATE SCHEMA l DROP SCHEMA ALTER SEQUENCE Changes the attributes of an existing sequence. All changes take effect in the next database session. Any parameters not set during an ALTER SEQUENCE statement retain their prior settings. You must be a sequence owner or a superuser to use this statement. Note: You can rename an existing sequence, or the schema of a sequence, but neither of these changes can be combined with any other optional parameters. Syntax ALTER ... [ ... [ ... | ... [ ... [ ... [ ... [ ... [ ... [ SEQUENCE [[db-name.]schema.]sequence-name RENAME TO new-name | SET SCHEMA new-schema-name] OWNER TO new-owner-name ] INCREMENT [ BY ] increment-value ] MINVALUE minvalue | NO MINVALUE ] MAXVALUE maxvalue | NO MAXVALUE ] RESTART [ WITH ] restart ] CACHE cache ] CYCLE | NO CYCLE ] HP Vertica Analytic Database (7.0.x) Page 940 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). sequence-name The name of the sequence to alter. The name must be unique among sequences, tables, projections, and views. RENAME TO new-name Renames a sequence within the same schema. To move a sequence, see SET SCHEMA below. OWNER TO new-owner-name Reassigns the current sequence owner to the specified owner. Only the sequence owner or a superuser can change ownership, and reassignment does not transfer grants from the original owner to the new owner (grants made by the original owner are dropped). SET SCHEMA new-schema-name Moves a sequence between schemas. INCREMENT [BY] increment-value Modifies how much to increment or decrement the current sequence to create a new value. A positive value increments an ascending sequence, and a negative value decrements the sequence. MINVALUE minvalue | NO MINVALUE Modifies the minimum value a sequence can generate. If you change this value and the current value exceeds the range, the current value is changed to the minimum value if increment is greater than zero, or to the maximum value if increment is less than zero. HP Vertica Analytic Database (7.0.x) Page 941 of 1539 SQL Reference Manual SQL Statements MAXVALUE maxvalue | NO MAXVALUE Modifies the maximum value for the sequence. If you change this value and the current value exceeds the range, the current value is changed to the minimum value if increment is greater than zero, or to the maximum value if increment is less than zero. RESTART [WITH] restart Changes the current value of the sequence to restart. The subsequent call to NEXTVAL will return the restart value. CACHE [value | NO CACHE] Modifies how many sequence numbers are preallocated and stored in memory for faster access. The default is 250,000 with a minimum value of 1. Specifying a value of 1 indicates that only one value can be generated at a time, since no cache is assigned. Alternatively, you can specify NO CACHE. CYCLE | NO CYCLE Allows you you to switch between CYCLE and NO CYCLE. The CYCLE option allows the sequence to wrap around when the maxvalue or minvalue is reached by an ascending or descending sequence respectively. If the limit is reached, the next number generated is the minvalue or maxvalue, respectively. If NO CYCLE is specified, any calls to NEXTVAL after the sequence has reached its maximum/minimum value, return an error. The default is NO CYCLE. Permissions l To rename a schema, the user must be the sequence owner and have USAGE and CREATE privileges on the schema. l To move a sequence between schemas, the user must be the sequence owner and have USAGE privilege on the schema that currently contains the sequence (old schema) and CREATE privilege on new schema to contain the sequence. Examples The following example modifies an ascending sequence called sequential to restart at 105: ALTER SEQUENCE sequential RESTART WITH 105; The following example moves a sequence from one schema to another: ALTER SEQUENCE public.sequence SET SCHEMA vmart; The following example renames a sequence in the Vmart schema: HP Vertica Analytic Database (7.0.x) Page 942 of 1539 SQL Reference Manual SQL Statements ALTER SEQUENCE vmart.sequence RENAME TO serial; The following example reassigns sequence ownership from the current owner to user Bob: ALTER SEQUENCE sequential OWNER TO Bob; See Also l CREATE SEQUENCE l CURRVAL l DROP SEQUENCE l GRANT (Sequence) NEXTVAL l l l l ALTER SUBNET Renames an existing subnet. Syntax ALTER SUBNET subnet-name RENAME TO 'new-subnet-name' Parameters The parameters are defined as follows: subnet-name The name of the existing subnet. new-subnet-name The new name for the subnet. Permissions Must be a superuser to alter a subnet. HP Vertica Analytic Database (7.0.x) Page 943 of 1539 SQL Reference Manual SQL Statements ALTER TABLE Modifies an existing table with a new table definition. Syntax 1 ALTER TABLE [[db-name.]schema.]table-name { ... ADD COLUMN column-definition ( table ) [CASCADE] ... | ADD Table-Constraint ... | ALTER COLUMN column-name | [ SET DEFAULT expression ] | [ DROP DEFAULT ] | [ { SET | DROP } NOT NULL] | [ SET DATA TYPE data-type ] ... | DROP CONSTRAINT constraint-name [ CASCADE | RESTRICT ] ... | [ DROP [ COLUMN ] column-name [ CASCADE | RESTRICT ] ] ... | RENAME [ COLUMN ] column TO new-column ... | SET SCHEMA new-schema-name [ CASCADE | RESTRICT ] ... | PARTITION BY partition-clause [ REORGANIZE ] ... | REORGANIZE ... | REMOVE PARTITIONING ... | OWNER TO new-owner-name } Syntax 2 ALTER TABLE [[db-name.]schema.]table-name [ , ... ]... RENAME [TO] new-table-name [ , ... ] HP Vertica Analytic Database (7.0.x) Page 944 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column ( mydb.myschema.mytable.colu mn1). table-name Specifies the name of the table to alter. When using more than one schema, specify the schema that contains the table. You can use ALTER TABLE in conjunction with SET SCHEMA to move only one table between schemas at a time. When using ALTER TABLE to rename one or more tables, you can specify a comma-delimited list of table names to rename. HP Vertica Analytic Database (7.0.x) Page 945 of 1539 SQL Reference Manual SQL Statements ADD COLUMN column-definition [CASCADE] Adds a new column to table as defined by column-definition and automatically adds the new column with a unique projection column name to the superprojection for that table. If you use the optional CASCADE keyword, HP Vertica also adds the new table column to all pre-join projections where the table is specified. When you use the CASCADE keyword, if you specify a default value for the column that is not a constant, HP Verticadoes not add the column to the pre-join projections. column-definition is any valid SQL function that does not contain volatile functions. For example, a constant or a function of other columns in the same table. ADD COLUMN operations take an O lock on the table until the operation completes, in order to prevent DELETE, UPDATE, INSERT, and COPY statements from affecting the table. If you use the CASCADE keyword, HP Vertica also takes O locks on all the anchor tables of any pre-join projections associated with that table.One consequence of the O lock is that SELECT statements issued at SERIALIZABLE isolation level are blocked until the operation completes. You can add a column when nodes are down. For more information, see Altering Tables in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 946 of 1539 SQL Reference Manual SQL Statements ADD table-constraint Adds a Table-Constraint to a table that does not have any associated projections. Adding a table constraint has no effect on views that reference the table. See About Constraints in the Administrator's Guide. ALTER COLUMN column-name [SET DEFAULT expression] [DROP DEFAULT] [{SET | DROP} NOT NULL] HP Vertica Analytic Database (7.0.x) Alters an existing table column to change, drop, or establish a DEFAULT expression for the column, or set or drop a NOT NULL constraint. (You can also use DROP DEFAULT to remove a default expression.) You can specify a volatile function or a user-defined function as the default expression for a column as part of an ALTER COLUMN SET DEFAULT statement. See Types of UDFs in the Programmer's Guide. Page 947 of 1539 SQL Reference Manual SQL Statements SET DATA TYPE data-type Changes the column's data type to any type whose conversion does not require storage reorganization. The following types are the conversions that HP Vertica supports: l Binary types—expansion and contraction (cannot convert between BINARY and VARBINARY types). l Character types—all conversions allowed, even between CHAR and VARCHAR l Exact numeric types– INTEGER, INT, BIGINT, TINYINT, INT8, SMALLINT, and all NUMERIC values of scale <=18 and precision 0 are interchangeable. For NUMERIC data types, you cannot alter precision, but you can change the scale in the ranges (0-18), (19-37), and so on. Restrictions You also cannot alter a column that is used in the CREATE PROJECTION .. SEGMENTED BY clause. To resize a segmented column, you must either create new superprojections and omit the column in the segmentation clause, or you can create a new table and projections with the column size that specifies the new size. The following type conversions are not allowed: l HP Vertica Analytic Database (7.0.x) Boolean to other types Page 948 of 1539 SQL Reference Manual SQL Statements DROP CONSTRAINT name [ CASCADE | RESTRICT ] l DATE/TIME type conversion l Approximate numeric type conversions l Conversions between BINARY and VARBINARY Drops the specified tableconstraint from the table. Use the CASCADE keyword to drop a constraint upon which something else depends. For example, a FOREIGN KEY constraint depends on a UNIQUE or PRIMARY KEY constraint on the referenced columns. Use the RESTRICT keyword to drop the constraint only from the given table. Dropping a table constraint has no effect on views that reference the table. HP Vertica Analytic Database (7.0.x) Page 949 of 1539 SQL Reference Manual SQL Statements DROP COLUMN column-name [ CASCADE | RESTRICT ] Drops both the specified column from the table and the ROS containers that correspond to the dropped column. Because drop operations physically purge object storage and catalog definitions (table history) from the table, AT EPOCH (historical) queries return nothing for the dropped column. Restrictions l At the table level, you cannot drop or alter a primary key column or a column participating in the table's partitioning clause. l At the projection level, you cannot drop the first column in a projection's sort order or columns that participate in the segmentation expression of a projection. l All nodes must be up for the drop operation to succeed. Using CASCADE to force a drop You can use the CASCADE keyword to drop a column if that column: HP Vertica Analytic Database (7.0.x) l Has a constraint of any kind on it. l Participates in the projection's sort order. l Participates in a pre-join projection or participates in the projection's segmentation expression. Note that when a pre-join projection contains a column to be dropped with Page 950 of 1539 SQL Reference Manual SQL Statements CASCADE, HP Vertica tries to drop the projection. In all cases, CASCADE tries to drop the projection(s) and will roll back if K-safety is compromised. See the Dropping a table column in the Administrator's Guide for additional details about CASCADE behavior and examples. Use the RESTRICT keyword to drop the column only from the given table. RENAME [TO] Renames one or more tables. In either case, the keyword changes the name of the table or tables to the specified name or names. For more information, see Altering Tables in the Administrator's Guide. Renaming a table requires USAGE and CREATE privilege on the schema that contains the table. RENAME [ COLUMN ] Renames the specified column within the table. If a column that is referenced by a view is renamed, the column does not appear in the result set of the view even if the view uses the wild card (*) to represent all columns in the table. Recreate the view to incorporate the column's new name. HP Vertica Analytic Database (7.0.x) Page 951 of 1539 SQL Reference Manual SQL Statements SET SCHEMA new-schema-name [ RESTRICT | CASCADE ] Moves a table to the specified schema. You must have USAGE privilege on the old schema and CREATE privilege on new schema. SET SCHEMA supports moving only one table between schemas at a time. You cannot move temporary tables between schemas. For more information, see Altering Tables in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 952 of 1539 SQL Reference Manual SQL Statements PARTITION BY partition-clause [ REORGANIZE ] Partitions or re-partitions a table according to the partition-clause that you define. Existing partition keys are immediately dropped when you run the command. You can use the PARTITION BY and REORGANIZE keywords separately or together. However, you cannot use these keywords with any other clauses. Partition-clause expressions are limited in the following ways: l Your partition-clause must calculate a single non-null value for each row. You can reference multiple columns, but each row must return a single value. l You can specify leaf expressions, functions, and operators in the partition clause expression. l All leaf expressions in the partition clause must be either constants or columns of the table. l Aggregate functions and queries are not permitted in the partition-clause expression. l SQL functions used in the partition-clause expression must be immutable. Partitioning or re-partitioning tables requires USAGE privilege on the schema that contains the table. See Partitioning, repartitioning, and reorganizing tables in the HP Vertica Analytic Database (7.0.x) Page 953 of 1539 SQL Reference Manual SQL Statements Administrator's Guide for details and best practices on repartitioning and reorganizing data, as well as how to monitor REORGANIZE operations. Do not alter table partitioning when nodes are down. Doing so prevents those nodes down from assisting in database recovery. REMOVE PARTITIONING Immediately removes partitioning on a table. The ROS containers are not immediately altered, but are later cleaned by the Tuple Mover. OWNER TO new-owner-name Changes the table owner. Only the table owner or a superuser can change ownership, and reassignment does not transfer grants from the original owner to the new owner (grants made by the original owner are dropped). Changing the table owner transfers ownership of the associated IDENTITY/AUTO_ INCREMENT sequences (defined in CREATE TABLE column-constraint syntax) but not other REFERENCES sequences. See Changing a table owner and Changing a sequence owner in the Administrator's Guide. Permissions You must be a table owner or a superuser and have USAGE privileges on schema that contains the table in order to: HP Vertica Analytic Database (7.0.x) Page 954 of 1539 SQL Reference Manual SQL Statements l Add, drop, rename, or alter column l Add or drop a constraint l Partition or re-partition the table To rename a table, you must have USAGE and CREATE privilege on the schema that contains the table. Moving a table to a new schema requires: l USAGE privilege on the old schema l CREATE privilege on new schema Table Behavior After Alteration After you modify a column, any new data that you load will conform to the modified table definition. If you restore the database to an epoch other than the current epoch, the restore operation will overwrite the changes with the prior table schema. For example, if you change a column's data type from CHAR(8) to CHAR(16) in epoch 10 and you restore the database from epoch 5, the column will be CHAR(8) again. Changing a Data Type for a Column Specified in a SEGMENTED BY Clause If you create a table and do not create a superprojection for it, HP Vertica automatically creates a superprojection when you first load data into the table. By default, superprojections are segmented by all columns to ensure that all of the data is available for queries. If you try to alter a column used in the superprojection's segmentation clause, HP Vertica returns an error message like in the following example: => CREATE TABLE colmod (c1 VARCHAR(13), c2 VARCHAR (8), c3 INT); CREATE TABLE => CREATE PROJECTION colmod_c1seg AS SELECT c1 FROM colmod SEGMENTED BY HASH(c1) ALL NODES; WARNING 4116: No super projections created for table public.colmod. HINT: Default super projections will be automatically created with the next DML CREATE PROJECTION => ALTER TABLE colmod ALTER COLUMN c1 SET DATA TYPE VARCHAR(30); ROLLBACK 2353: Cannot alter type of column "c1" since it is referenced in the segmentation expression of projection "colmod_c1seg" To resize a segmented column, you must either create new superprojections and omit the column in the segmentation clause or create a new table (with new column size) and projections. HP Vertica Analytic Database (7.0.x) Page 955 of 1539 SQL Reference Manual SQL Statements Locked Tables If the operation cannot obtain an O Lock on the table(s), HP Vertica attempts to close any internal Tuple Mover (TM) sessions running on the same table(s) so that the operation can proceed. Explicit TM operations that are running in user sessions are not closed. If an explicit TM operation is running on the table, then the operation cannot proceed until the explicit TM operation completes. Examples The following example drops the default expression specified for the Discontinued_flag column: => ALTER TABLE Retail.Product_Dimension ALTER COLUMN Discontinued_flag DROP DEFAULT; The following example renames a column in the Retail.Product_Dimension table from Product_ description to Item_description: => ALTER TABLE Retail.Product_Dimension RENAME COLUMN Product_description TO Item_description; The following example moves table T1 from schema S1 to schema S2. SET SCHEMA defaults to CASCADE, so all the projections that are anchored on table T1 are automatically moved to schema S2 regardless of the schema in which they reside: => ALTER TABLE S1.T1 SET SCHEMA S2; The following example adds partitioning to the Sales table based on state and reorganizes the data into partitions: => ALTER TABLE Sales PARTITION BY state REORGANIZE; Adding and Changing Constraints on Columns Using ALTER TABLE The following example uses ALTER TABLE to add a column (b) with not NULL and default 5 constraints to a table (test6): CREATE TABLE test6 (a INT); ALTER TABLE test6 ADD COLUMN b INT DEFAULT 5 NOT NULL; Use ALTER TABLE with the ALTER COLUMN and SET NOT NULL clauses to add the constraint on column a in table test6: ALTER TABLE test6 ALTER COLUMN a SET NOT NULL; HP Vertica Analytic Database (7.0.x) Page 956 of 1539 SQL Reference Manual SQL Statements Adding and Dropping NOT NULL Column Constraints Use the SET NOT NULL or DROP NOT NULL clause to add or remove a not NULL column constraint. Use these clauses to ensure that the column has the proper constraints when you have added or removed a primary key constraint on a column, or any time you want to add or remove the not NULL constraint. Note: A PRIMARY KEY constraint includes a not NULL constraint, but if you drop the PRIMARY KEY constraint on a column, the not NULL constraint remains on that column. Examples ALTER TABLE T1 ALTER COLUMN x SET NOT NULL; ALTER TABLE T1 ALTER COLUMN x DROP NOT NULL; For more information, see Altering Table Definitions. Adding New Columns to Tables with CASCADE The following example shows how to use the CASCADE keyword when adding a new column to an existing table. Using CASCADE ensures that the new column is added to the superprojection and to all pre-join projections that include that table. Create two tables: => CREATE TABLE t1 (x INT PRIMARY KEY NOT NULL, y INT); => CREATE TABLE t2 (x INT PRIMARY KEY NOT NULL, t1_x INT REFERENCES t1(x) NOT NULL, z VARCHAR(8)); After you load data into them, HP Vertica creates a superprojection for each table. The superprojections contains all the columns in their respective tables. For this example, name them super_t1 and super_t2. Create two pre-join projections that join tables t1 and t2. => CREATE PROJECTION t_pj1 AS SELECT t1.x, t1.y, t2.x, t2.t1_x, t2.z FROM t1 JOIN t2 ON t1.x = t2.t1_x UNSEGMENTED ALL NODES; => CREATE PROJECTION t_pj2 AS SELECT t1.x, t2.x FROM t1 JOIN t2 ON t1.x = t2.t1_x UNSEGMENTED ALL NODES; Add a new column w1 to table t1 using the CASCADE keyword. HP Vertica adds the column to: l Superprojection super_t1 l Pre-join projection t_pj1 HP Vertica Analytic Database (7.0.x) Page 957 of 1539 SQL Reference Manual SQL Statements l Pre-join projection t_pj2 => ALTER TABLE t ADD COLUMN w INT DEFAULT 5 NOT NULL CASCADE; Add a new column w2to table t1, and specify a nonconstant default value. HP Vertica adds the new column to the superprojection super_t1. Because the default value is not a constant, HP Vertica does not add the new column to the pre-join projections. => ALTER TABLE t ADD COLUMN w1 INT DEFAULT default (t1.y+1) NOT NULL CASCADE; WARNING: Column "c_new" in table "t" with non-constant default will not be added to prejoin(s) t_pj1, t_pj2. See Also l "Working with Tables" on page 1 Table-Constraint Adds a constraint to the metadata of a table. See Adding Constraints in the Administrator's Guide. Syntax [ CONSTRAINT constraint_name ... { PRIMARY KEY ( column [ ... | FOREIGN KEY ( column [ REFERENCES table [( column [ ] , ... ] ) , ... ] ) , ... ] )] ... | UNIQUE ( column [ , ... ] )... } Parameters CONSTRAINT constraint-name Assigns a name to the constraint. HP recommends that you name all constraints. PRIMARY KEY ( column [ , ... ] ) Adds a referential integrity constraint defining one or more NOT NULL columns as the primary key. FOREIGN KEY ( column [ , ... ] ) Adds a referential integrity constraint defining one or more columns as a foreign key. REFERENCES table [( column [ , ... ] )] HP Vertica Analytic Database (7.0.x) Specifies the table to which the FOREIGN KEY constraint applies. If you omit the optional column definition of the referenced table, the default is the primary key of table. Page 958 of 1539 SQL Reference Manual SQL Statements UNIQUE ( column [ , ... ] ) Specifies that the data contained in a column or a group of columns is unique with respect to all the rows in the table. Permissions Table owner or user WITH GRANT OPTION is grantor. l REFERENCES privilege on table to create foreign key constraints that reference this table l USAGE privilege on schema that contains the table Specifying Primary and Foreign Keys You must define PRIMARY KEY and FOREIGN KEY constraints in all tables that participate in inner joins. You can specify a foreign key table constraint either explicitly (with the FOREIGN KEY parameter), or implicitly using the REFERENCES parameter to reference the table with the primary key. You do not have to explicitly specify the columns in the referenced table, for example: CREATE TABLE fact(c1 INTEGER PRIMARY KEY); CREATE TABLE dim (c1 INTEGER REFERENCES fact); Adding Constraints to Views Adding a constraint to a table that is referenced in a view does not affect the view. Examples The VMart sample database, described in the Getting Started Guide, contains a table Product_ Dimension in which products have descriptions and categories. For example, the description "Seafood Product 1" exists only in the "Seafood" category. You can define several similar correlations between columns in the Product Dimension table. ALTER USER Changes a database user account. Only a superuser can alter another user's database account. Making changes to a database user account with the ALTER USER function does not affect current sessions. Database Account Changes Users Can Make Users can change their own user accounts with these options: HP Vertica Analytic Database (7.0.x) Page 959 of 1539 SQL Reference Manual SQL Statements l IDENTIFIED BY. . . l RESOURCE POOL . . . l SEARCH_PATH . . . Users can change their own passwords using the IDENTIFIED BY option and supplying the current password with the REPLACE clause. Users can set the default RESOURCE POOL to any pool to which they have been granted usage privileges. Syntax ALTER ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ ... [ USER name ACCOUNT { LOCK | UNLOCK } ] DEFAULT ROLE {role [, ...] | NONE} ] IDENTIFIED BY 'password' [ REPLACE 'old-password' ] ] MEMORYCAP { 'memory-limit' | NONE } ] PASSWORD EXPIRE ] PROFILE { profile-name | DEFAULT } ] RESOURCE POOL pool-name ] RUNTIMECAP { 'time-limit' | NONE } ] TEMPSPACECAP { 'space-limit' | NONE } ] SEARCH_PATH { schema[,schema2,...] | DEFAULT } ] Parameters name Specifies the name of the user to alter. You must double quote names that contain special characters. ACCOUNT LOCK | UNLOCK Locks or unlocks the named user's access to the database. Users cannot log in if their account is locked. A superuser can manually lock and unlock accounts using ALTER USER syntax or automate account locking by setting a maximum number of failed login attempts through the CREATE PROFILE statement. DEFAULT ROLE {role [, ...] | NONE} One or more roles that should be active when the user's session starts. The user must have already been granted access to the roles (see GRANT (Role)). The role or roles specified in this command replace any existing default roles. Use the NONE keyword to eliminate all default roles for the user. HP Vertica Analytic Database (7.0.x) Page 960 of 1539 SQL Reference Manual SQL Statements IDENTIFIED BY 'password' [ REPLACE 'old_passw ord' ] Sets a user's password to password. Supplying an empty string for password removes the user's password. The use of this clause differs between superusers and non-superusers. A non-superuser can alter only his or her own password, and must supply the existing password using the REPLACE parameter. Superusers can change any user's password and do not need to supply the REPLACE parameter. See Password Guidelines and Creating a Database Name and Password for password policies. PASSWORD EXPIRE Expires the user's password. HP Vertica will force the user to change passwords during his or her next login. Note: PASSWORD EXPIRE has no effect when using external password authentication methods such as LDAP or Kerberos. PROFILE profile-name | DEFAULT Sets the user's profile to profile-name. Using the value DEFAULT sets the user's profile to the default profile. MEMORYCAP 'memory-limit' | NONE Limits the amount of memory that the user's requests can use. This value is a number representing the amount of space, followed by a unit (for example, '10G'). The unit can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case value of the size size must be 0-100) l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes Setting this value to NONE means the user has no limits on memory use. HP Vertica Analytic Database (7.0.x) Page 961 of 1539 SQL Reference Manual SQL Statements RESOURCE POOL pool-name Sets the name of the default resource pool for the user. Attempting to alter a database user account to associate the account with a particular resource pool will result in an error if the user has not already been granted access to the resource pool. particular resource pool on which they have not been granted access results in an error (even for a superuser). RUNTIMECAP 'time-limit' | NONE Sets the maximum amount of time any of the user's queries can execute. time-limit is an interval, such as '1 minute' or '100 seconds' (see Interval Values for details). This value cannot exceed one year. Setting this value to NONE means there is no time limit on the user's queries. If RUNTIMECAP is also set for the resource pool or the session, HP Vertica always uses the shortest limit. TEMPSPACECAP 'space-limit' | NONE Limits the amount of temporary file storage the user's requests can use. This parameter's value has the same format as the MEMORYCAP value. SEARCH_PATH schema[,schema2,...] | DEFAULT Sets the user's default search path that tells HP Vertica which schemas to search for unqualified references to tables and UDFs. See Setting Search Paths in the Administrator's Guide for an explanation of the schema search path. The DEFAULT keyword sets the search path to: "$user", public, v_catalog, v_monitor, v_in ternal Permissions Must be a superuser to alter a user. See Also CREATE USER l DROP USER l l HP Vertica Analytic Database (7.0.x) Page 962 of 1539 SQL Reference Manual SQL Statements l ALTER VIEW Renames a view. Syntax ALTER VIEW [[db-name.]schema.] current-view-name ... RENAME TO new-view-name Parameters viewname Specifies the name of the view you want to rename. RENAME TOnew-view-name Specifies the new name of the view. The view name must be unique. Do not use the same name as any table, view, or projection within the database. Notes Views are read only. You cannot perform insert, update, delete, or copy operations on a view. Permissions To create a view, the user must be a superuser or have CREATE privileges on the schema in which the view is renamed. Example The following command renames view1 to view2: => CREATE VIEW view1 AS SELECT * FROM t; CREATE VIEW => ALTER VIEW view1 RENAME TO view2; ALTER VIEW BEGIN Starts a transaction block. Syntax BEGIN [ WORK | TRANSACTION ] [ isolation_level ] [ transaction_mode ] where isolation_level is one of: HP Vertica Analytic Database (7.0.x) Page 963 of 1539 SQL Reference Manual SQL Statements ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } and where transaction_mode is one of: READ { ONLY | WRITE } Parameters WORK | TRANSACTION Have no effect; they are optional keywords for readability. ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } A transaction retains its isolation level until it completes, even if the session's transaction isolation level changes mid-transaction. HP Vertica internal processes (such as the Tuple Mover and refresh operations) and DDL operations are always run at SERIALIZABLE isolation level to ensure consistency. Isolation level determines what data the transaction can access when other transactions are running concurrently. The isolation level cannot be changed after the first query (SELECT) or DML statement (INSERT, DELETE, UPDATE) has run. isolation_level can one of the following values: l SERIALIZABLE—Sets the strictest level of SQL transaction isolation. This level emulates transactions serially, rather than concurrently. It holds locks and blocks write operations until the transaction completes. Not recommended for normal query operations. l REPEATABLE READ—Automatically converted to SERIALIZABLE by HP Vertica. l READ COMMITTED (Default)—Allows concurrent transactions. Use READ COMMITTED isolation or Snapshot isolation for normal query operations, but be aware that there is a subtle difference between them. (See section below this table.) l READ UNCOMMITTED—Automatically converted to READ COMMITTED by HP Vertica. HP Vertica Analytic Database (7.0.x) Page 964 of 1539 SQL Reference Manual SQL Statements READ { ONLY | WRITE } Transaction mode can be one of the following: l READ WRITE—(default)The transaction is read/write. l READ ONLY—The transaction is read-only. Setting the transaction session mode to read-only disallows the following SQL commands, but does not prevent all disk write operations: l INSERT, UPDATE, DELETE, and COPY if the table they would write to is not a temporary table l All CREATE, ALTER, and DROP commands l GRANT, REVOKE, and EXPLAIN if the command it would run is among those listed. Permissions No special permissions required. Notes START TRANSACTION performs the same function as BEGIN. See Also l Transactions l Creating and Rolling Back Transactions l COMMIT l END l ROLLBACK HP Vertica Analytic Database (7.0.x) Page 965 of 1539 SQL Reference Manual SQL Statements COMMENT ON Statements The following functions allow you to create comments associated with HP Vertica database objects: l COMMENT ON COLUMN l COMMENT ON CONSTRAINT l COMMENT ON FUNCTION l COMMENT ON LIBRARY l COMMENT ON NODE l COMMENT ON PROJECTION l COMMENT ON SCHEMA l COMMENT ON SEQUENCE l COMMENT ON TABLE l COMMENT ON TRANSFORM FUNCTION l COMMENT ON VIEW COMMENT ON COLUMN Adds, revises, or removes a projection column comment. You can only add comments to projection columns, not to table columns. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON COLUMN [[db-name.]schema.]proj_name.column_name IS {'comment' | NULL} HP Vertica Analytic Database (7.0.x) Page 966 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). proj_name.column_name Specifies the name of the projection and column with which to associate the comment. comment Specifies the comment text to add. Enclose the text of the comment within single-quotes. If a comment already exists for this column, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Example The following example adds a comment to the customer_name column in the customer_dimension projection: HP Vertica Analytic Database (7.0.x) Page 967 of 1539 SQL Reference Manual SQL Statements => COMMENT ON COLUMN customer_dimension_vmart_node01.customer_name IS 'Last name only'; The following examples remove a comment from the customer_name column in the customer_ dimension projection in two ways, using the NULL option, or specifying a blank string: => COMMENT ON COLUMN customer_dimension_vmart_node01.customer_name IS NULL; => COMMENT ON COLUMN customer_dimension_vmart_node01.customer_name IS ''; See Also l COMMENTS COMMENT ON CONSTRAINT Adds, revises, or removes a comment on a constraint. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON CONSTRAINT constraint_name ON [ [db-name.]schema.]table_name IS ... {'comment' | NU LL }; Parameters constraint_name The name of the constraint associated with the comment. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). table_name Specifies the name of the table constraint with which to associate a comment. HP Vertica Analytic Database (7.0.x) Page 968 of 1539 SQL Reference Manual SQL Statements comment Specifies the comment text to add. Enclose the text of the comment within single-quotes. If a comment already exists for this constraint, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Example The following example adds a comment to the constraint_x constraint on the promotion_ dimension table: => COMMENT ON CONSTRAINT constraint_x ON promotion_dimension IS 'Primary key'; The following examples remove a comment from the constraint_x constraint on the promotion_ dimension table: => COMMENT ON CONSTRAINT constraint_x ON promotion_dimension IS NULL; => COMMENT ON CONSTRAINT constraint_x ON promotion_dimension IS ''; See Also l COMMENTS COMMENT ON FUNCTION Adds, revises, or removes a comment on a function. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. HP Vertica Analytic Database (7.0.x) Page 969 of 1539 SQL Reference Manual SQL Statements Syntax COMMENT ON FUNCTION [[db-name.]schema.]function_name function_arg IS { 'comment' | NULL }; Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). function_name Specifies the name of the function with which to associate the comment. function_arg Indicates the function arguments. comment Specifies the comment text to add. Enclose the comment text within single-quotes. If a comment already exists for this function, the comment you enter overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Notes l A superuser can view and add comments to all objects. l A user must own an object to be able to add or edit comments for the object. l A user must have viewing privileges on an object to view its comments. l If you drop an object, all comments associated with the object are dropped as well. HP Vertica Analytic Database (7.0.x) Page 970 of 1539 SQL Reference Manual SQL Statements Examples The following example adds a comment to the macros.zerowhennull (x INT) function: => COMMENT ON FUNCTION macros.zerowhennull(x INT) IS 'Returns a 0 if not NULL'; The following examples remove a comment from the macros.zerowhennull (x INT) function in two ways by using the NULL option, or specifying a blank string: => COMMENT ON FUNCTION macros.zerowhennull(x INT) IS NULL; => COMMENT ON FUNCTION macros.zerowhennull(x INT) IS ''; See Also l COMMENTS COMMENT ON LIBRARY Adds, revises, or removes a comment on a library . Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON LIBRARY [ [db-name.]schema.]library_name IS {'comment' | NULL} Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). library_name The name of the library associated with the comment. HP Vertica Analytic Database (7.0.x) Page 971 of 1539 SQL Reference Manual SQL Statements comment Specifies the comment text to add. Enclose the text of the comment within single-quotes. If a comment already exists for this library, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment to the library MyFunctions: => COMMENT ON LIBRARY MyFunctions IS 'In development'; The following examples remove a comment from the library MyFunctions: => COMMENT ON LIBRARY MyFunctions IS NULL; => COMMENT ON LIBRARY MyFunctions IS ''; See Also l COMMENTS COMMENT ON NODE Adds, revises, or removes a comment on a node. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. HP Vertica Analytic Database (7.0.x) Page 972 of 1539 SQL Reference Manual SQL Statements Syntax COMMENT ON NODE node_name IS { 'comment' | NULL } Parameters node_name The name of the node associated with the comment. comment Specifies the comment text to add. Enclose the text of the comment within singlequotes. If a comment already exists for this node, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment for the initiator node: => COMMENT ON NODE initiator IS 'Initiator node'; The following examples removes a comment from the initiator node. => COMMENT ON NODE initiator IS NULL; => COMMENT ON NODE initiator IS ''; See Also l COMMENTS HP Vertica Analytic Database (7.0.x) Page 973 of 1539 SQL Reference Manual SQL Statements COMMENT ON PROJECTION Adds, revises, or removes a comment on a projection. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON PROJECTION [ [db-name.]schema.]proj_name IS { 'comment' | NULL } Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection_name The name of the projection associated with the comment. comment Specifies the text of the comment to add. Enclose the text of the comment within single-quotes. If a comment already exists for this projection, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. Null Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. HP Vertica Analytic Database (7.0.x) Page 974 of 1539 SQL Reference Manual SQL Statements Examples The following example adds a comment to the customer_dimension_vmart_node01 projection: => COMMENT ON PROJECTION customer_dimension_vmart_node01 IS 'Test data'; The following examples remove a comment from the customer_dimension_vmart_node01 projection: => COMMENT ON PROJECTION customer_dimension_vmart_node01 IS NULL; => COMMENT ON PROJECTION customer_dimension_vmart_node01 IS ''; See Also l COMMENTS COMMENT ON SCHEMA Adds, revises, or removes a comment on a schema. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON SCHEMA [db-name.]schema_name IS {'comment' | NULL} Parameters [db-name.] [Optional] Specifies the database name. You must be connected to the database you specify. You cannot make changes to objects in other databases. schema_name Indicates the schema associated with the comment. comment Text of the comment you want to add. Enclose the text of the comment in singlequotes. If a comment already exists for this schema, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Allows you to remove an existing comment. HP Vertica Analytic Database (7.0.x) Page 975 of 1539 SQL Reference Manual SQL Statements Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment to the public schema: => COMMENT ON SCHEMA public IS 'All users can access this schema'; The following examples remove a comment from the public schema. => COMMENT ON SCHEMA public IS NULL; => COMMENT ON SCHEMA public IS ''; See Also l COMMENTS COMMENT ON SEQUENCE Adds, revises, or removes a comment on a sequence. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON SEQUENCE [[db-name.]schema.]sequence_name IS { 'comment' | NULL } HP Vertica Analytic Database (7.0.x) Page 976 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). sequence_name The name of the sequence associated with the comment. comment Specifies the text of the comment to add. Enclose the text of the comment within single-quotes. If a comment already exists for this sequence, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment to the sequence called prom_seq. HP Vertica Analytic Database (7.0.x) Page 977 of 1539 SQL Reference Manual SQL Statements => COMMENT ON SEQUENCE prom_seq IS 'Promotion codes'; The following examples remove a comment from the prom_seq sequence. => COMMENT ON SEQUENCE prom_seq IS NULL; => COMMENT ON SEQUENCE prom_seq IS ''; See Also l COMMENTS COMMENT ON TABLE Adds, revises, or removes a comment on a table. Each object can have a maximum of one comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON TABLE [ [db-name.]schema.]table_name IS { 'comment' | NULL } Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table_name Specifies the name of the table with which to associate the comment. comment Specifies the text of the comment to add. Enclose the text of the comment within single-quotes. If a comment already exists for this table, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. Null Removes a previously added comment. HP Vertica Analytic Database (7.0.x) Page 978 of 1539 SQL Reference Manual SQL Statements Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment to the promotion_dimension table: => COMMENT ON TABLE promotion_dimension IS '2011 Promotions'; The following examples remove a comment from the promotion_dimension table: => COMMENT ON TABLE promotion_dimension IS NULL; => COMMENT ON TABLE promotion_dimension IS ''; See Also l COMMENTS COMMENT ON TRANSFORM FUNCTION Adds, revises, or removes a comment on a user-defined transform function. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the v_catalog.comments system table. Syntax COMMENT ON TRANSFORM FUNCTION [[db-name.]schema.]t_function_name ...([t_function_arg_name t_function_arg_type] [,...]) IS {'comment' | NULL} HP Vertica Analytic Database (7.0.x) Page 979 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). t_function_name Specifies name of the transform function with which to associate the comment. t_function_arg_name t_function_arg_type [Optional] Indicates the names and data types of one or more transform function arguments. If you supply argument names and types, each type must match the type specified in the library used to create the original transform function. comment Specifies the comment text to add. Enclose the text of the comment within single-quotes. If a comment already exists for this transform function, the comment you enter overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. HP Vertica Analytic Database (7.0.x) Page 980 of 1539 SQL Reference Manual SQL Statements Examples The following example adds a comment to the macros.zerowhennull (x INT) UTF function: => COMMENT ON TRANSFORM FUNCTION macros.zerowhennull(x INT) IS 'Returns a 0 if not NULL'; The following example removes a comment from the acros.zerowhennull (x INT) function by using the NULL option: => COMMENT ON TRANSFORM FUNCTION macros.zerowhennull(x INT) IS NULL; COMMENT ON VIEW Adds, revises, or removes a comment on a view. Each object can have a maximum of 1 comment (1 or 0). Comments are stored in the V_CATALOG.COMMENTS system table. Syntax COMMENT ON VIEW [ [db-name.]schema.]view_name IS { 'comment' | NULL } Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). view_name The name of the view with which to associate the comment. comment Specifies the text of the comment to add. If a comment already exists for this view, the comment you enter here overwrites the previous comment. Comments can be up to 8192 characters in length. If a comment exceeds that limitation, HP Vertica truncates the comment and alerts the user with a message. You can enclose a blank value within single quotes to remove an existing comment. NULL Removes an existing comment. HP Vertica Analytic Database (7.0.x) Page 981 of 1539 SQL Reference Manual SQL Statements Permissions l A superuser can view and add comments to all objects. l The object owner can add or edit comments for the object. l A user must have VIEW privileges on an object to view its comments. Notes Dropping an object drops all comments associated with the object. Examples The following example adds a comment to a view called curr_month_ship: => COMMENT ON VIEW curr_month_ship IS 'Shipping data for the current month'; The following example removes a comment from the curr_month_ship view: => COMMENT ON VIEW curr_month_ship IS NULL; See Also l COMMENTS COMMIT Ends the current transaction and makes all changes that occurred during the transaction permanent and visible to other users. Syntax COMMIT [ WORK | TRANSACTION ] Parameters WORK | TRANSACTION Have no effect; they are optional keywords for readability. Permissions No special permissions required. HP Vertica Analytic Database (7.0.x) Page 982 of 1539 SQL Reference Manual SQL Statements Notes END is a synonym for COMMIT. See Also l l l BEGIN l ROLLBACK l START TRANSACTION CONNECT Connects to another HP Vertica database to enable data import (using the COPY FROM VERTICA statement) or export (using the EXPORT statement). By default, invoking CONNECT occurs over the HP Vertica private network. Creating a connection over a public network requires some configuration. For information about using CONNECT to export data to or import data over a public network, see Export/Import from a Public Network. When importing from or exporting to an HP Vertica database, you can connect only to a database that uses trusted- (username-only) or password-based authentication, as described in Implementing Security. Neither LDAP nor SSL authentication is supported. Syntax CONNECT TO VERTICA database USER username PASSWORD 'password' ON 'host',port Parameters database The connection target database name. username The username to use when connecting to the other database. password A string containing the password to use to connect to the other database. host A string containing the host name of one of the nodes in the other database. port The port number of the other database as an integer. Permissions No special permissions required. HP Vertica Analytic Database (7.0.x) Page 983 of 1539 SQL Reference Manual SQL Statements Connection Details Once you successfully establish a connection to another database, the connection remains open for the current session. To disconnect a connection, use the DISCONNECT statement. You can have only one connection to another database at a time, though you can create connections to multiple different databases in the same session. If the target database does not have a password, and you specify a password in the CONNECT statement, the connection succeeds, but does not give any indication that you supplied an incorrect password. Example => CONNECT TO VERTICA ExampleDB USER dbadmin PASSWORD 'Password123' ON 'VerticaHost01',54 33; CONNECT See Also l COPY FROM VERTICA l DISCONNECT l EXPORT TO VERTICA COPY Bulk loads data into an HP Vertica database. You can initiate loading one or more files or pipes on a cluster host or on a client system (using the COPY LOCAL option). Permissions You must connect to the HP Vertica database as a superuser, or, as a non-superuser, have a USER-accessible storage location, and applicable READ or WRITE privileges granted to the storage location from which files are read or written to. COPY LOCAL users must have INSERT privileges to copy data from the STDIN pipe, as well as USAGE privileges on the schema. The following permissions are required to COPY FROM STDIN: l INSERT privilege on table l USAGE privilege on schema HP Vertica Analytic Database (7.0.x) Page 984 of 1539 SQL Reference Manual SQL Statements Syntax COPY [ [db-name.]schema-name.]table ... [ ( { column-as-expression | column } ...... [ FILLER datatype ] ...... [ FORMAT 'format' ] ...... [ ENCLOSED BY 'char' ] ...... [ ESCAPE AS 'char' | NO ESCAPE ] ...... [ NULL [ AS ] 'string' ] ...... [ TRIM 'byte' ] ...... [ DELIMITER [ AS ] 'char' ] ... [, ... ] ) ] ... [ COLUMN OPTION ( column ...... [ FORMAT 'format' ] ...... [ ENCLOSED BY 'char' ] ...... [ ESCAPE AS 'char' | NO ESCAPE ] ...... [ NULL [ AS ] 'string' ] ...... [ DELIMITER [ AS ] 'char' ] ... [, ... ] ) ] FROM { STDIN ...... [ BZIP | GZIP | UNCOMPRESSED ] ...| 'pathToData' [ ON nodename | ON ANY NODE ] ...... [ BZIP | GZIP | UNCOMPRESSED ] [, ...] ...| LOCAL STDIN | 'pathToData' ...... [ BZIP | GZIP | UNCOMPRESSED ] [, ...] } ...[ NATIVE | NATIVE VARCHAR | FIXEDWIDTH COLSIZES (integer [, ....]) ] ...[ WITH ] ...[ WITH [ SOURCE source(arg='value')] [ FILTER filter(arg='value') ] [ PARSER parser([arg= 'value']) ] ] ...[ DELIMITER [ AS ] 'char' ] ...[ TRAILING NULLCOLS ] ...[ NULL [ AS ] 'string' ] ...[ ESCAPE AS 'char' | NO ESCAPE ] ...[ ENCLOSED BY 'char' ] ...[ RECORD TERMINATOR 'string' ] ...[ SKIP records ] ...[ SKIP BYTES integer ] ...[ TRIM 'byte' ] ...[ REJECTMAX integer ] ...[ REJECTED DATA {'path' [ ON nodename ] [, ...] | AS TABLE 'reject_table'} ] ...[ EXCEPTIONS 'path' [ ON nodename ] [, ...] ] ...[ ENFORCELENGTH ] ...[ ABORT ON ERROR ] ...[ AUTO | DIRECT | TRICKLE ] ...[ STREAM NAME 'streamName'] ...[ NO COMMIT ] Parameters table HP Vertica Analytic Database (7.0.x) The table containing the data to load into the HP Vertica database. Page 985 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema-name.]table [Optional] Specifies the name of a schema table (not a projection), optionally preceded by a database name. HP Vertica loads the data into all projections that include columns from the schema table. When using more than one schema, specify the schema that contains the table. Note: COPY ignores db-name or schema-name options when used as part of a CREATE EXTERNAL TABLE... or CREATE FLEX EXTERNAL TABLE... statements. column-as-expression Specifies the expression used to compute values for the target column. For example: COPY t(year AS TO_CHAR(k, 'YYYY')) FROM 'myfile.dat' Use this option to transform data when it is loaded into the target database. For more information about using expressions with COPY, see Transforming Data During Loads in the Administrator's Guide. See Ignoring Columns and Fields in the Load File in the Administrator's Guide for information about using fillers. column Restricts the load to one or more specified columns in the table. If you do not specify any columns, COPY loads all columns by default. Table columns that you do not specify in the column list are assigned their default values. If a column had no defined default value, COPY inserts NULL. If you leave the column parameter blank to load all columns in the table, you can use the optional parameter COLUMN OPTION to specify parsing options for specific columns. Note: The data file must contain the same number of columns as the COPY command's column list. For example, in a table T1 with nine columns (C1 through C9), the following command loads the three columns of data in each record to columns C1, C6, and C9, respectively: => COPY T1 (C1, C6, C9); HP Vertica Analytic Database (7.0.x) Page 986 of 1539 SQL Reference Manual SQL Statements FILLER Specifies not to load the column and its fields into the destination table. Use this option to omit columns that you do not want to transfer into a table. This parameter also transforms data from a source column and loads the transformed data to the destination table, rather than loading the original, untransformed source column (parsed column). (See Ignoring Columns and Fields in the Load File in the Administrator's Guide.) FORMAT Specifies the input formats to use when loading date/time and binary columns. These are the valid input formats when loading binary columns: l 'octal' l 'hex' l 'bitstream' See Loading Binary Data to learn more about using these formats. When loading date/time columns, using FORMAT significantly improves load performance. COPY supports the same formats as the TO_DATE function. See the following topics for additional information: l Template Patterns for Date/Time Formatting l Template Pattern Modifiers for Date/Time Formatting If you specify invalid format strings, the COPY operation returns an error. HP Vertica Analytic Database (7.0.x) Page 987 of 1539 SQL Reference Manual SQL Statements pathToData Specifies the absolute path of the file containing the data, which can be from multiple input sources. If path resolves to a storage location, and the user invoking COPY is not a superuser, these are the required privileges: l The storage location must have been created with the USER option (see ADD_LOCATION). l The user must already have been granted READ access to the storage location where the file(s) exist, as described in GRANT (Storage Location) Further, if a non-superuser invokes COPY from a storage location to which she has privileges, HP Vertica also checks any symbolic links (symlinks) the user has to ensure no symlink can access an area to which the user has not been granted privileges. The pathToData can optionally contain wildcards to match more than one file. The file or files must be accessible to the local client or the host on which the COPY statement runs. You can use variables to construct the pathname as described in Using Load Scripts. The supported patterns for wildcards are specified in the Linux Manual Page for Glob (7), and for ADO.net platforms, through the .NET Directory.getFiles Method. nodename [Optional] Specifies the node on which the data to copy resides and the node that should parse the load file. You can use nodename to COPY and parse a load file from a node other than the initiator node of the COPY statement. If you omit nodename, the location of the input file defaults to the initiator node for the COPY statement. Note: You cannot specify nodename with either STDIN or LOCAL, because STDIN is read on the initiator node only and LOCAL indicates a client node. HP Vertica Analytic Database (7.0.x) Page 988 of 1539 SQL Reference Manual SQL Statements ON ANY NODE [Optional] Specifies that the source file to load is on all of the nodes, so COPY opens the file and parses it from any node in the cluster. Make sure that the source file is available and accessible on each cluster node. You can use a wildcard or glob (such as *.dat) to load multiple input files, combined with the ON ANY NODE clause. Using a glob results in COPY distributing the list of files to all cluster nodes and spreading the workload. Note: You cannot specify ON ANY NODE with either STDIN or LOCAL, because STDIN is read on the initiator node only and LOCAL indicates a client node. STDIN Reads from the client a standard input instead of a file. STDIN takes one input source only and is read on the initiator node. To load multiple input sources, use pathToData. User must have INSERT privilege on table and USAGE privilege on schema/ LOCAL Specifies that all paths for the COPY statement are on the client system and that all COPY variants are initiated from a client. You can use the LOCAL and STDIN parameters together. See Using COPY and COPY LOCAL in the Administrator's Guide. BZIP | GZIP | UNCOMPRESSED Specifies the input file format. The default value is UNCOMPRESSED, and input files can be of any format. If using wildcards, all qualifying input files must be in the same format. Notes: WITH, AS HP Vertica Analytic Database (7.0.x) l When using concatenated BZIP or GZIP files, be sure that each source file is terminated with a record terminator before concatenating them. l Concatenated BZIP and GZIP files are not supported for NATIVE (binary) and NATIVE VARCHAR formats. Improve readability of the statement. These parameters have no effect on the actions performed by the statement. Page 989 of 1539 SQL Reference Manual SQL Statements [WITH [ SOURCE source(arg='value')] [FILTER filter(arg='value')] [PARSER parser(param='value')]] Directs COPY to optionally use one or more User Defined Load functions. You can specify up to one source, zero or more filters, and up to one parser. To load flexible tables, use the PARSER parameter followed by one of the flex table parsers, fjsonparser, fdelimitedparser, or fcefparser. For more information about the flex table parsers, and using their parameters, see Using Flex Table Parsers in the Flex Tables Guide. NATIVE | NATIVE VARCHAR | FIXEDWIDTH Specifies the parser to use when bulk loading columnar tables. These parameters are not applicable when loading flexible tables. By default, COPY uses the DELIMITER parser for UTF-8 format, delimited text input data. Do not specify DELIMITER. COPY always uses the default parser unless you specify another. For more information about using these options, see Specifying a COPY Parser in the Administrator's Guide. NOTE: COPY LOCAL does not support the NATIVE and NATIVE VARCHAR parsers. COLUMN OPTION Specifies load metadata for one or more columns declared in the table column list. For example, you can specify that a column has its own DELIMITER, ENCLOSED BY, NULL as 'NULL' expression, and so on. You do not have to specify every column name explicitly in the COLUMN OPTION list, but each column you specify must correspond to a column in the table column list. COLSIZES (integer [,...]) Required specification when loading fixed-width data using the FIXEDWIDTH parser. COLSIZES and the list of integers must correspond to the columns listed in the table column list. For more information, see Loading Fixed-Width Format Data in the Administrator's Guide. DELIMITER A single ASCII character that separates columns within each record of a file. The default in HP Vertica is a vertical bar (|). You can use any ASCII value in the range E'\000' to E'\177' inclusive. You cannot use the same character for both the DELIMITER and NULL options. For more information, see Loading UTF-8 Format Data in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 990 of 1539 SQL Reference Manual SQL Statements TRAILING NULLCOLS Specifies that if HP Vertica encounters a record with insufficient data to match the columns in the table column list, COPY inserts the missing columns with NULLs. For other information and examples, see Loading Fixed-Width Format Data in the Administrator's Guide. ESCAPE AS Sets the escape character to indicate that the following character should be interpreted literally, rather than as a special character. You can define an escape character using any ASCII value in the range E'\001' to E'\177', inclusive (any ASCII character except NULL: E'\000'). The COPY statement does not interpret the data it reads in as String Literals, and does not follow the same escape rules as other SQL statements (including the COPY parameters). When reading in data, COPY interprets only characters defined by these options as special values: l ESCAPE AS l DELIMITER l ENCLOSED BY l RECORD TERMINATOR NO ESCAPE Eliminates escape character handling. Use this option if you do not need any escape character and you want to prevent characters in your data from being interpreted as escape sequences. ENCLOSED BY Sets the quote character within which to enclose data, allowing delimiter characters to be embedded in string values. You can choose any ASCII value in the range E'\001' to E'\177' inclusive (any ASCII character except NULL: E'\000'). By default, ENCLOSED BY has no value, meaning data is not enclosed by any sort of quote character. NULL The string representing a null value. The default is an empty string (''). You can specify a null value as any ASCII value in the range E'\001' to E'\177' inclusive (any ASCII character except NULL: E'\000'). You cannot use the same character for both the DELIMITER and NULL options. For more information, see Loading UTF-8 Format Data. HP Vertica Analytic Database (7.0.x) Page 991 of 1539 SQL Reference Manual SQL Statements RECORD TERMINATOR Specifies the literal character string that indicates the end of a data file record. For more information about using this parameter, see Loading UTF-8 Format Data. SKIP records Skips a number (integer) of records in a load file. For example, you can use the SKIP option to omit table header information. SKIP BYTES total Skips the total number (integer) of bytes in a record. This option is only available when loading fixed-width data. TRIM Trims the number of bytes you specify from a column. This option is only available when loading fixed-width data. REJECTMAX Specifies a maximum number of logical records to be rejected before a load fails. For more details about using this option, see Tracking Load Exceptions and Rejections Status in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 992 of 1539 SQL Reference Manual SQL Statements REJECTED DATA { 'path' [ ON nodename ] [, ...] | AS TABLE reject_table } Specifies the file name or absolute path of the file in which to write rejected rows. The rejected data consists of each row that failed to load due to a parsing error. Use the REJECTED DATA clause with the EXCEPTIONS clause, because exceptions explain why a row was rejected. Alternatively, use the REJECTED DATA AS TABLE reject_table clause to save rejected rows in a columnar table. Saving rejections to a table also saves the reason for the rejected row. You can then query the table to access rejected data information. For more information, see Saving Load Rejections (REJECTED DATA) in the Administrator's Guide. If path resolves to a storage location, and the user invoking COPY is not a superuser, the following privileges are required: l The storage location must have been created with the USER option (see ADD_LOCATION). l The user must already have been granted READ access to the storage location where the files exist, as described in GRANT (Storage Location) The optional ON nodename clause moves any existing rejected data files on nodename to path on the same node. See Tracking Load Exceptions and Rejections Status in the Administrator's Guide. Note: If you include the NO COMMIT and REJECTED DATA AS TABLE clauses in your COPY statement and the reject_table does not already exist, Vertica Analytic Database saves the rejected-data table as a LOCAL TEMP table and returns a message that a LOCAL TEMP table is being created. HP Vertica Analytic Database (7.0.x) Page 993 of 1539 SQL Reference Manual SQL Statements EXCEPTIONS 'path' [ ON nodename ] [, ...] Specifies the file name or absolute path of the file in which to write exceptions. Exceptions are textual messages describing why each rejected row was rejected. Each exception describes the corresponding record in the file specified by the REJECTED DATA option. If path resolves to a storage location, and the user invoking COPY is not a superuser, the following privileges are required: l The storage location must have been created with the USER option (see ADD_LOCATION). l The user must already have been granted READ access to the storage location where the files exist, as described in GRANT (Storage Location). The optional ON nodename clause moves any existing exceptions files on nodename to the indicated path on the same node. For more details about using this option, see Saving Load Exceptions in the Administrator's Guide. Note: Specifying an exceptions file name is incompatible with using the REJECTED DATA AS TABLE clause, which includes the exception in the table's rejected_reason column. ENFORCELENGTH Determines whether COPY truncates or rejects data rows of type char, varchar, binary, and varbinary if they do not fit the target table. By default, COPY truncates offending rows of these data types, but does not reject them. For more details, see Tracking Load Exceptions and Rejections Status in the Administrator's Guide. ABORT ON ERROR Stops the COPY command if a row is rejected and rolls back the command. No data is loaded. AUTO | DIRECT | TRICKLE Specifies the method COPY uses to load data into the database. The default load method is AUTO, in which COPY loads data into the WOS (Write Optimized Store) in memory. When the WOS is full, the load continues directly into ROS (Read Optimized Store) on disk. For more information, see Choosing a Load Method in the Administrator's Guide. Note: COPY ignores these options when used as part of a CREATE EXTERNAL TABLE statement. HP Vertica Analytic Database (7.0.x) Page 994 of 1539 SQL Reference Manual SQL Statements STREAM NAME [Optional] Supplies a COPY load stream identifier. Using a stream name helps to quickly identify a particular load. The STREAM NAME value that you supply in the load statement appears in the stream column of the LOAD_STREAMS system table. By default, HP Vertica names streams by table and file name. For example, if you have two files (f1, f2) in Table A, their stream names are A-f1, A-f2, respectively. To name a stream: => COPY mytable FROM myfile DELIMITER '|' DIRECT STR EAM NAME 'My stream name'; NO COMMIT Prevents the COPY statement from committing its transaction automatically when it finishes copying data. For more information about using this parameter, see Choosing a Load Method in the Administrator's Guide. Notes: COPY ignores this option when used as part of a CREATE EXTERNAL TABLE statement. If you include the NO COMMIT and REJECTED DATA AS TABLE clauses in your COPY statement and the reject_ table does not already exist, Vertica Analytic Database saves the rejected-data table as a LOCAL TEMP table and returns a message that a LOCAL TEMP table is being created. Note: Always use the COPY statement REJECTED DATA and EXCEPTIONS parameters to save load rejections. Using the RETURNREJECTED parameter is supported only for internal use by the JDBC and ODBC drivers. HP Vertica's internal-use options can change without notice. COPY Option Summary The following table summarizes which COPY parameters are available when loading data using the default (DELIMITER), NATIVE (binary), NATIVE VARCHAR, and FIXEDWIDTH parsersü: COPY Option DELIMITER NATIVE (BINARY) COLUMN OPTION ü ü ü ü AUTO ü ü ü ü HP Vertica Analytic Database (7.0.x) NATIVE (VARCHAR) FIXEDWIDTH Page 995 of 1539 SQL Reference Manual SQL Statements COPY Option DELIMITER NATIVE (BINARY) NATIVE (VARCHAR) FIXEDWIDTH DIRECT ü ü ü ü TRICKLE ü ü ü ü ENFORCELENGTH ü ü ü ü EXCEPTIONS ü ü ü ü FILLER ü ü ü ü REJECTED DATA ü ü ü ü ABORT ON ERROR ü ü ü ü STREAM NAME ü ü ü ü SKIP ü ü ü ü ü SKIP BYTES REJECTMAX ü ü ü ü STDIN ü ü ü ü UNCOMPRESSED ü ü ü ü BZIP | GZIP ü ü ü ü CONCATENATED BZIP or GZIP ü NO COMMIT ü ü ü ü FORMAT ü ü ü ü NULL ü ü ü ü DELIMITED ü ENCLOSED BY ü ESCAPE AS ü TRAILING NULLCOLS ü RECORD TERMINATOR ü TRIM ü ü ü Notes When loading data with the COPY statement, COPY considers the following data invalid: HP Vertica Analytic Database (7.0.x) Page 996 of 1539 SQL Reference Manual SQL Statements l Missing columns (an input line has less columns than the recipient table). l Extra columns (an input line has more columns than the recipient table). l Empty columns for an INTEGER or DATE/TIME data type. If a column is empty for either of these types, COPY does not use the default value that was defined by the CREATE TABLE command, unless you do not supply a column option as part of the COPY statement. l Incorrect representation of a data type. For example, trying to load a non-numeric data into an INTEGER column is invalid. When COPY encounters an empty line while loading data, the line is neither inserted nor rejected, but COPY increments the line record number. Consider this behavior when evaluating rejected records. If you return a list of rejected records and COPY encountered an empty row while loading data, the position of rejected records is incremented by one. Examples The following examples load data with the COPY statement using the FORMAT, DELIMITER, NULL and ENCLOSED BY string options, as well as a DIRECT option. => COPY public.customer_dimension (customer_since FORMAT 'YYYY') FROM STDIN DELIMITER ',' NULL AS 'null' ENCLOSED BY '"' => COPY a FROM STDIN DELIMITER ',' NULL E'\\\N' DIRECT; => COPY store.store_dimension FROM :input_file DELIMITER '|' NULL '' RECORD TERMINATOR E'\f' Setting vsql Variables The first two examples load data from STDIN. The last example uses a vsql variable (input_file) . You can set a vsql variable as follows: \set input_file ../myCopyFromLocal/large_table.gzip HP Vertica Analytic Database (7.0.x) Page 997 of 1539 SQL Reference Manual SQL Statements Using Compressed Data and Named Pipes COPY supports named pipes that follow the same naming conventions as file names on the given file system. Permissions are open, write, and close. This statement creates the named pipe, pipe1, and sets two vsql variables, dir and file: \! mkfifo pipe1 \set dir `pwd`/ \set file '''':dir'pipe1''' This statement copies an uncompressed file from the named pipe: \! cat pf1.dat > pipe1 & COPY large_tbl FROM :file delimiter '|'; SELECT * FROM large_tbl; COMMIT; This statement copies a GZIP file from named pipe and uncompresses it: \! gzip pf1.dat \! cat pf1.dat.gz > pipe1 & COPY large_tbl FROM :file ON site01 GZIP delimiter '|'; SELECT * FROM large_tbl; COMMIT; \!gunzip pf1.dat.gz This statement copies a BZIP file from named pipe and then uncompresses it: \!bzip2 pf1.dat \! cat pf1.dat.bz2 > pipe1 & COPY large_tbl FROM :file ON site01 BZIP delimiter '|'; SELECT * FROM large_tbl; COMMIT; bunzip2 pf1.dat.bz2 This statement creates a Flex table, and copies JSON data into the table, using the flex table parser, fjsonparser: CREATE FLEX TABLE darkdata(); CREATE TABLE COPY tweets FROM from '/myTest/Flexible/DATA/tweets_12.json' parser fjsonparser(); Rows Loaded ------------12 (1 row) HP Vertica Analytic Database (7.0.x) Page 998 of 1539 SQL Reference Manual SQL Statements See Also l SQL Data Types l ANALYZE_CONSTRAINTS l Choosing a Load Method in the Administrator's Guide l CREATE EXTERNAL TABLE AS COPY l Directory.getFiles Method l Bulk Loading Data in the Administrator's Guide l Loading Fixed-Width Format Data in the Administrator's Guide l Loading Binary Data in the Administrator's Guide l Loading Flex Table Data in the Administrator's Guide l Ignoring Columns and Fields in the Load File in the Administrator's Guide l Linux Manual Page for Glob (7) l Tracking Load Exceptions and Rejections Status in the Administrator's Guide l Transforming Data During Loads in the Administrator's Guide COPY LOCAL Using the COPY statement with its LOCAL option lets you load a data file on a client system, rather than on a cluster host. COPY LOCAL supports the STDIN and 'pathToData' parameters, but not the [ON nodename] clause. COPY LOCAL does not support NATIVE or NATIVE VARCHAR formats. The COPY LOCAL option is platform independent. The statement works in the same way across all supported HP Vertica platforms and drivers. For more details about using COPY LOCAL with supported drivers, see the Programmer's Guide section for your platform. Note: On Windows clients, the path you supply for the COPY LOCAL file is limited to 216 characters due to limitations in the Windows API. Invoking COPY LOCAL does not automatically create exceptions and rejections files, even if exceptions occur. You cannot save exceptions and rejections to a table with the rejected data as table parameter. For information about saving such files, see Capturing Load Exceptions and Rejections in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 999 of 1539 SQL Reference Manual SQL Statements Permissions User must have INSERT privilege on the table and USAGE privilege on the schema. How Copy Local Works COPY LOCAL loads data in a platform-neutral way. The COPY LOCAL statement loads all files from a local client system to the HP Vertica host, where the server processes the files. You can copy files in various formats: uncompressed, compressed, fixed-width format, in bzip or gzip format, or specified as a bash glob. Files of a single format (such as all bzip, or gzip) can be comma-separated in the list of input files. You can also use any of the applicable COPY statement options (as long as the data format supports the option). For instance, you can define a specific delimiter character, or how to handle NULLs, and so forth. Note: The Linux glob command returns files that match the pattern you enter, as specified in the Linux Manual Page for Glob (7). For ADO.net platforms, specify patterns and wildcards as described in the .NET Directory.getFiles Method. For examples of using the COPY LOCAL option to load data, see COPY for syntactical descriptions, and the Bulk Loading Data section in the Administrator's Guide. The HP Vertica host uncompresses and processes the files as necessary, regardless of file format or the client platform from which you load the files. Once the server has the copied files, HP Vertica maintains performance by distributing file parsing tasks, such as encoding, compressing, uncompressing, across nodes. Viewing Copy Local Operations in a Query Plan When you use the COPY LOCAL option, the GraphViz Explain plan includes a label for Load-ClientFile, rather than Load-File. Following is a section from a sample Explain plan: ----------------------------------------------PLAN: BASE BULKLOAD PLAN (GraphViz Format) ----------------------------------------------digraph G { graph [rankdir=BT, label = " BASE BULKLOAD PLAN \nAll Nodes Vector: \n\n node[0]=initiator (initiator) Up\n", labelloc=t, labeljust=l ordering=out] . . . 10[label = "Load-Client-File(/tmp/diff) \nOutBlk=[UncTuple]", color = "green", shape = "ellipse"]; COPY FROM VERTICA You can import data from an earlier HP Vertica release, as long as the earlier release is a version of the last major release. For instance, for Version 6.x, you can import data from any version of 5.x, HP Vertica Analytic Database (7.0.x) Page 1000 of 1539 SQL Reference Manual SQL Statements but not from 4.x. Copies data from another HP Vertica database once you have established a connection to the other HP Vertica database with the CONNECT statement. See Importing Data for more setup information. The COPY FROM VERTICA statement works similarly to the COPY statement, but accepts only a subset of COPY parameters. By default, using COPY FROM VERTICA to copy or import data from another database occurs over the HP Vertica private network. Connecting to a public network requires some configuration. For information about using this statement to copy data across a public network, see Importing/Exporting From Public Networks. Syntax COPY [target_schema.]target_table ... [( target_column_name[, target_column_name2,...])] ... FROM VERTICA database.[source_schema.]source_table ... [(source_column_name[, source_column_name2,...])] ... [AUTO | DIRECT | TRICKLE] ... [STREAM NAME 'stream name'] ... [NO COMMIT] Parameters [target_schema.]target_table The table to store the copied data. This table must be in your local database, and must already exist. (target_column_name[, target_colu mn_name2,...]) A list of columns in the target table to store the copied data. Note: You cannot use column fillers as part of the column definition. database The name of the database that is the source of the copied data. You must have already created a connection to this database in the current session. [source_schema.]source_table The table in the source database that is the source of the copied data. (source_column_name[, source_colu mn_name2,...]) A list of columns in the source table to be copied. If this list is supplied, only these columns are copied from the source table. HP Vertica Analytic Database (7.0.x) Page 1001 of 1539 SQL Reference Manual SQL Statements AUTO | DIRECT | TRICKLE Specifies the method COPY uses to load data into the database. The default load method is AUTO, in which COPY loads data into the WOS (Write Optimized Store) in memory. When the WOS is full, the load continues directly into ROS (Read Optimized Store) on disk. For more information, see Choosing a Load Method in the Administrator's Guide. COPY ignores these options when used as part of a CREATE EXTERNAL TABLE statement. STREAM NAME [Optional] Supplies a COPY load stream identifier. Using a stream name helps to quickly identify a particular load. The STREAM NAME value that you supply in the load statement appears in the stream column of the LOAD_STREAMS system table. By default, HP Vertica names streams by table and file name. For example, if you have two files (f1, f2) in Table A, their stream names are A-f1, A-f2, respectively. To name a stream: => COPY mytable FROM myfile DELIMITER '|' DIRECT STREAM NAME 'My stream name'; NO COMMIT Prevents the COPY statement from committing its transaction automatically when it finishes copying data. For more information about using this parameter, see Choosing a Load Method in the Administrator's Guide. Permissions l SELECT privileges on the source table l USAGE privilege on source table schema l INSERT privileges for the destination table in target database l USAGE privilege on destination table schema Notes Importing and exporting data fails if either side of the connection is a single-node cluster installed to localhost, or you do not specify a host name or IP address. HP Vertica Analytic Database (7.0.x) Page 1002 of 1539 SQL Reference Manual SQL Statements l If you do not supply a list of source and destination columns, COPY FROM VERTICA attempts to match columns in the source table with corresponding columns in the destination table. See the following section for details. Source and Destination Column Mapping You can optionally supply lists of either source columns to be copied, columns in the destination table where data should be stored, or both. Specifying the lists lets you select a subset of source table columns to copy to the destination table. Since source and destination lists are not required, results differ depending on which list is present. The following table presents the results of supplying one or more lists: Omit Source Column List Supply Source Column List Matches all columns in the source table to columns in the destination table. The number of columns in Omit the two tables need not match, Destination but the destination table must not Column have fewer columns than the List source. Copies content only from the supplied list of source table columns. Matches columns in the destination table to columns in the source list. The number of columns in the two tables need not match, but the destination table must not have fewer columns than the source. Matches columns in the destination column list to columns Supply in the source. The number of Destination columns in the destination list Column must match the number of List columns in the source table. Matches columns from the source table column lists to those in the destination table. The lists must have the same number of columns. The COPY FROM VERTICA statement needs to map columns in the source table to columns in the destination table. Example This example demonstrates connecting to another database, copying the contents of an entire table from the source database to an identically-defined table in the current database directly into ROS, and then closing the connection. => CONNECT TO VERTICA vmart USER dbadmin PASSWORD '' ON 'VertTest01',5433; CONNECT => COPY customer_dimension FROM VERTICA vmart.customer_dimension DIRECT; Rows Loaded ------------500000 (1 row) => DISCONNECT vmart; DISCONNECT HP Vertica Analytic Database (7.0.x) Page 1003 of 1539 SQL Reference Manual SQL Statements This example demonstrates copying several columns from a table in the source database into a table in the local database. => CONNECT TO VERTICA vmart USER dbadmin PASSWORD '' ON 'VertTest01',5433; CONNECT => COPY people (name, gender, age) FROM VERTICA -> vmart.customer_dimension (customer_name, customer_gender, -> customer_age); Rows Loaded ------------500000 (1 row) => DISCONNECT vmart; DISCONNECT You can copy tables (or columns) containing Identity and Auto-increment values, but the sequence values are not incremented automatically at their destination. See Also l CONNECT l DISCONNECT l EXPORT TO VERTICA CREATE EXTERNAL TABLE AS COPY Creates an external table. This statement is a combination of the CREATE TABLE and COPY statements, supporting a subset of each statement's parameters, as noted below. You can also use user-defined load extension functions (UDLs) to create external tables. For more information about UDL syntax, see User Defined Load (UDL) and COPY. Note: HP Vertica does not create a superprojection for an external table when you create it. Permissions Must be a database superuser to create external tables, unless the superuser has created a useraccessible storage location to which the COPY refers, as described in ADD_LOCATION. Once external tables exist, you must also be a database superuser to access them through a select statement. Note: Permission requirements for external tables differ from other tables. To gain full access (including SELECT) to an external table that a user has privileges to create, the database superuser must also grant READ access to the USER-accessible storage location, see GRANT (Storage Location). HP Vertica Analytic Database (7.0.x) Page 1004 of 1539 SQL Reference Manual SQL Statements Syntax CREATE EXTERNAL TABLE [ IF NOT EXISTS ] [schema.]table-name { ... ( Column-Definition (table) [ , ... ] ) ... | [ column-name-list (create table) ] } AS COPY [ [db-name.]schema-name.]table ... [ ( { column-as-expression | column } ...... [ FILLER datatype ] ...... [ FORMAT 'format' ] ...... [ ENCLOSED BY 'char' ] ...... [ ESCAPE AS 'char' | NO ESCAPE ] ...... [ NULL [ AS ] 'string' ] ...... [ TRIM 'byte' ] ...... [ DELIMITER [ AS ] 'char' ] ... [, ... ] ) ] ... [ COLUMN OPTION ( column ...... [ FORMAT 'format' ] ...... [ ENCLOSED BY 'char' ] ...... [ ESCAPE AS 'char' | NO ESCAPE ] ...... [ NULL [ AS ] 'string' ] ...... [ DELIMITER [ AS ] 'char' ] ... [, ... ] ) ] FROM { ...| 'pathToData' [ ON nodename | ON ANY NODE ] ...... [ BZIP | GZIP | UNCOMPRESSED ] [, ...] } ...[ NATIVE ...| NATIVE VARCHAR ...| FIXEDWIDTH { COLSIZES (integer [, ....]) } ...] ...[ WITH ] ...[ WITH [ SOURCE source(arg='value')] [ FILTER filter(arg='value') ] [ PARSER parser(arg='v alue') ]] ...[ DELIMITER [ AS ] 'char' ] ...[ TRAILING NULLCOLS ] ...[ NULL [ AS ] 'string' ] ...[ ESCAPE AS 'char' | NO ESCAPE ] ...[ ENCLOSED BY 'char' [ AND 'char' ] ] ...[ RECORD TERMINATOR 'string' ] ...[ SKIP integer ] ...[ SKIP BYTES integer ] ...[ TRIM 'byte' ] ...[ REJECTMAX integer ] ...[ EXCEPTIONS 'path' [ ON nodename ] [, ...] ] ...[ REJECTED DATA 'path' [ ON nodename ] [, ...] ] ...[ ENFORCELENGTH ] ...[ ABORT ON ERROR ] Parameters The following parameters from the parent statements are not supported in the CREATE EXTERNAL TABLE AS COPY statement: HP Vertica Analytic Database (7.0.x) Page 1005 of 1539 SQL Reference Manual SQL Statements CREATE TABLE COPY AS AT EPOCH LAST FROM STDIN AT TIME 'timestamp' FROM LOCAL ORDER BY table-column [,...] DIRECT ENCODED BY TRICKLE hash-segmentation-clause NO COMMIT UNSEGMENTED {node | node all} KSAFE [k_num] PARTITION BY partition-clause For all supported parameters, see the CREATE TABLE and COPY statements. Notes Canceling a CREATE EXTERNAL TABLE AS COPY statement can cause unpredictable results. HP recommends that you allow the statement to finish, then use DROP TABLE once the table exists. Examples Examples of external table definitions: CREATE EXTERNAL TABLE ext1 (x integer) AS COPY FROM '/tmp/ext1.dat' DELIMITER ','; CREATE EXTERNAL TABLE ext1 (x integer) AS COPY FROM '/tmp/ext1.dat.bz2' BZIP DELIMITER ', '; CREATE EXTERNAL TABLE ext1 (x integer, y integer) AS COPY (x as '5', y) FROM '/tmp/ext1.d at.bz2' BZIP DELIMITER ','; See Also l Physical Schema l CREATE TABLE l CREATE FLEX TABLE l SELECT l Using External Tables CREATE FAULT GROUP Creates a fault group, which can contain the following: HP Vertica Analytic Database (7.0.x) Page 1006 of 1539 SQL Reference Manual SQL Statements l One or more nodes l One or more child fault groups l One or more nodes and one or more child fault groups The CREATE FAULT GROUP statement creates an empty fault group. You must run the ALTER FAULT GROUP statement to add nodes or other fault groups to an existing fault group. Syntax CREATE FAULT GROUP name Parameters name Specifies the name of the fault group to create. You must provide distinct names for each fault group you create. Permissions Must be a superuser to create a fault group. Example The following command creates a fault group called parent0: exampledb=> CREATE FAULT GROUP parent0; CREATE FAULT GROUP To add nodes or other fault groups to the parent0 fault group, run the ALTER FAULT GROUP statement. See Also l V_CATALOG.FAULT_GROUPS l V_CATALOG.CLUSTER_LAYOUT l Fault Groups in the Administrator's Guide l High Availability With Fault Groups in the Concepts Guide HP Vertica Analytic Database (7.0.x) Page 1007 of 1539 SQL Reference Manual SQL Statements CREATE FLEX TABLE Creates a flex table in the logical schema. If you create a flex table without any column definitions, two materialized columns exist: __raw__ : A LONG VARBINARY type column in which any unstructured data you load is stored. The column has a NOT NULL constraint, which can be changed using the ALTER TABLE statement. __identity__ : An identity column, present when no other column definitions exist. This column is auto-incrementing and used for segmentation and sort order. Additionally, creating any flex table results in three associated objects: l A flex table (flex_table) named in this statement l A related keys table, called flex_table_keys l A related view, called flex_table_view Both the flex table and its associated _keys table are required to use flex tables successfully. The _ keys table and _view are subservient objects of the flex table, which cannot exist if the table does not. However, you can drop either the _keys table or _view independently. Declaring columns (or other supported parameters) is optional. CREATE FLEX TABLE supports many of the parameters available when creating columnar tables, but not all. This section presents the optional use of column definitions, and the subset of supported parameters. You can also create flex external tables, with some syntactical variations, as described in CREATE FLEX EXTERNAL TABLE AS COPY . Note: HP Vertica does not support flexible global temporary tables. Syntax CREATE {FLEX | FLEXIBLE} TABLE [ IF NOT EXISTS ] [[db-name.]schema.]table-name { ... ( [ Column-Definition (table) [ , ... ]] ) ... | [ table-constraint ( column_name, ... )] ... | [ column-name-list (create table) ] } ... [ ORDER BY table-column [ , ... ] ] ... [ ENCODED BY column-definition [ , ... ] ... [ Hash-Segmentation-Clause ..... | UNSEGMENTED { NODE node | ALL NODES } ] ... [ KSAFE [k_num] ] ... [ PARTITION BY partition-clause ] Parameters See the CREATE TABLE statement for all parameter descriptions. HP Vertica Analytic Database (7.0.x) Page 1008 of 1539 SQL Reference Manual SQL Statements Unsupported CREATE Options for Flex Tables You cannot use the following options when creating a flex table: ... AS [COPY] [ [ AT EPOCH LATEST ] ... | [ AT TIME 'timestamp' ] ] [ /*+ direct */ ] query ... | [ LIKE [[db-name.]schema.]existing-table [ INCLUDING PROJECTIONS | EXCLUDING PROJECTIONS ] ] Default Flex Table and Keys Table Projections HP Vertica automatically creates superprojections for both the flex table and keys tables when you create them. If you create a flex table with one or more of the ORDER BY, ENCODED BY, SEGMENTED BY, or KSAFE clauses, the clause information is used to create projections. If no clauses are in use, HP Vertica uses the following defaults for unspecified aspects: Table order_by encoded_by Segmentation Ksafe flexible table __identity__ none by hash __identity__ 1 keys_table frequency none replicated/unsegmented all nodes 1 Note: When you build a view for a flex table (see BUILD_FLEXTABLE_VIEW), the view is ordered by frequency, desc, and key_name. Permissions To create a flex table, you must have CREATE privileges on the table schema. Examples The following example creates a flex table named darkdata without specifying any column information. HP Vertica creates a default superprojection and buddy projection as part of creating the table: => CREATE FLEXIBLE TABLE darkdata(); CREATE TABLE The following example creates a table called darkdata1 with one column (date_col) and specifies the partition by clause to partition the data by year. HP Vertica creates a default superprojection and buddy projections as part of creating the table: => CREATE FLEX TABLE darkdata1 (date_col date NOT NULL) partition by extract('year' from date_col); CREATE TABLE HP Vertica Analytic Database (7.0.x) Page 1009 of 1539 SQL Reference Manual SQL Statements See Also l Physical Schema l COPY l CREATE EXTERNAL TABLE AS COPY l CREATE FLEX EXTERNAL TABLE AS COPY l CREATE TABLE l PARTITION_PROJECTION l PARTITION_TABLE l SELECT l Working with Table Partitions l Auto Partitioning l Using External Tables CREATE FLEX EXTERNAL TABLE AS COPY Creates a flexible external table. This statement is a combination of the CREATE TABLE and COPY statements, supporting a subset of each statement's parameters, as noted below. You can also use user-defined load extension functions (UDLs) to create external flex tables. For more information about UDL syntax, see User Defined Load (UDL) and COPY. Note: HP Vertica does not create a superprojection for an external table when you create it. Permissions Must be a database superuser to create external tables, unless the superuser has created a useraccessible storage location to which the COPY refers, as described in ADD_LOCATION. Once external tables exist, you must also be a database superuser to access them through a select statement. Note: Permission requirements for external tables differ from other tables. To gain full access (including SELECT) to an external table that a user has privileges to create, the database superuser must also grant READ access to the USER-accessible storage location, see GRANT (Storage Location). HP Vertica Analytic Database (7.0.x) Page 1010 of 1539 SQL Reference Manual SQL Statements Syntax CREATE {FLEX | FLEXIBLE} EXTERNAL TABLE [ IF NOT EXISTS ] [schema.]table-name { ... ( [ Column-Definition (table) [ , ... ] ] ) } AS COPY FROM { ...| 'pathToData' [ ON nodename | ON ANY NODE ] ...... [ BZIP | GZIP | UNCOMPRESSED ] [, ...] } ...[ NATIVE ...| NATIVE VARCHAR ...| FIXEDWIDTH { COLSIZES (integer [, ....]) } ...] ...[ WITH ] ...[ WITH [ SOURCE source(arg='value')] [ FILTER filter(arg='value') ] [ PARSER parser( arg='value') ]] ...[ DELIMITER [ AS ] 'char' ] ...[ TRAILING NULLCOLS ] ...[ NULL [ AS ] 'string' ] ...[ ESCAPE AS 'char' | NO ESCAPE ] ...[ ENCLOSED BY 'char' [ AND 'char' ] ] ...[ RECORD TERMINATOR 'string' ] ...[ SKIP integer ] ...[ SKIP BYTES integer ] ...[ TRIM 'byte' ] ...[ REJECTMAX integer ] ...[ EXCEPTIONS 'path' [ ON nodename ] [, ...] ] ...[ REJECTED DATA 'path' [ ON nodename ] [, ...] ] ...[ ENFORCELENGTH ] ...[ ABORT ON ERROR ] Parameters The following parameters from the parent statements are not supported in the CREATE FLEXIBLE EXTERNAL TABLE AS COPY statement: CREATE TABLE COPY AS AT EPOCH LAST FROM STDIN AT TIME 'timestamp' FROM LOCAL ORDER BY table-column [,...] DIRECT ENCODED BY TRICKLE hash-segmentation-clause NO COMMIT UNSEGMENTED {node | node all} KSAFE [k_num] PARTITION BY partition-clause For all supported parameters, see the CREATE TABLE and COPY statements. HP Vertica Analytic Database (7.0.x) Page 1011 of 1539 SQL Reference Manual SQL Statements Notes Canceling a CREATE FLEX EXTERNAL TABLE AS COPY statement can cause unpredictable results. HP Vertica recommends that you allow the statement to finish, then use DROP TABLE once the table exists. Examples To create an external flex table: kdb=> create flex external table mountains() as copy from 'home/release/KData/kmm_ountain s.json' parser fjsonparser(); CREATE TABLE After creating an external flex table, two regular tables exist, as with other flex tables, the named table, and its associated _keys table, which is not an external table: kdb=> \dt mountains List of tables Schema | Name | Kind | Owner | Comment --------+-----------+-------+---------+--------public | mountains | table | release | (1 row) You can use the helper function COMPUTE_FLEXTABLE_KEYS_AND_BUILD_VIEW to compute keys and create a view for the external table: kdb=> select compute_flextable_keys_and_build_view ('appLog'); compute_flextable_keys_and_build_view ------------------------------------------------------------------------------------------------Please see public.appLog_keys for updated keys The view public.appLog_view is ready for querying (1 row) 1. Check the keys from the _keys table for the results of running the helper application: kdb=> select * from appLog_keys; key_name | frequency | data_type_gu ess ----------------------------------------------------------+-----------+----------------contributors | 8 | varchar(20) coordinates | 8 | varchar(20) created_at | 8 | varchar(60) entities.hashtags | 8 | long varbinary HP Vertica Analytic Database (7.0.x) Page 1012 of 1539 SQL Reference Manual SQL Statements (186) . . . retweeted_status.user.time_zone retweeted_status.user.url retweeted_status.user.utc_offset retweeted_status.user.verified (125 rows) | | | | 1 1 1 1 | | | | varchar(20) varchar(68) varchar(20) varchar(20) 2. Query from the external flex table view: kdb=> select "user.lang" from appLog_view; user.lang ----------it en es en en es tr en (12 rows) See Also l CREATE EXTERNAL TABLE AS COPY l CREATE TABLE l CREATE FLEX TABLE SELECT l l CREATE FUNCTION Statements You can use the Create Function statement to create two different kinds of functions: l User-Defined SQL functions--User defined SQL functions let you define and store commonlyused SQL expressions as a function. User defined SQL functions are useful for executing complex queries and combining HP Vertica built-in functions. You simply call the function name you assigned in your query. HP Vertica Analytic Database (7.0.x) Page 1013 of 1539 SQL Reference Manual SQL Statements User defined scalar functions (UDSFs) take in a single row of data and return a single value. These functions can be used anywhere a native HP Vertica function or statement can be used, except CREATE TABLE with its PARTITION BY or any segmentation clause. l User-Defined Scalar functions-- While you use CREATE FUNCTION to create both SQL and scalar functions, you use a different syntax for each function type. For more information, see: l CREATE FUNCTION (SQL Functions) l CREATE FUNCTION (UDF) About Creating User Defined Transform Functions (UDTFs) You can use a similar SQL statement to create user-defined transform functions. User Defined Transform Functions (UDTFs) operate on table segments and return zero or more rows of data. The data they return can be an entirely new table, unrelated to the schema of the input table, including having its own ordering and segmentation expressions. They can only be used in the SELECT list of a query. For details see Using User Defined Transforms. To create a UDTF, see CREATE TRANSFORM FUNCTION. CREATE AGGREGATE FUNCTION Adds a User Defined Aggregate Function (UDAF) stored in a shared Linux library to the catalog. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes data values to the code in the library to process it. Syntax CREATE [ OR REPLACE ] AGGREGATE FUNCTION [[db-name.]schema.]function-name ... AS LANGUAGE 'language' NAME 'factory' LIBRARY library_name; Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE AGGREGATE FUNCTION statement fails if an existing function matches the name and parameters of the function you are trying to define. If you do supply this parameter, the new function definition overwrites the old. HP Vertica Analytic Database (7.0.x) Page 1014 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify. You cannot make changes to objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name The name of the function to create. If the function name is schemaqualified (as above), the function is created in the specified schema. This name does not need to match the name of the factory, but it is less confusing if they are the same or similar. LANGUAGE 'language' The programming language used to develop the function. Currently only 'C++' is supported for UDAF. NAME 'factory' The name of the factory class in the shared library that generates the object to handle the function's processing. LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this function. This library must have been previously loaded using the CREATE LIBRARY statement. Notes l The parameters and return value for the function are automatically determined by the CREATE AGGREGATE FUNCTION statement, based on data supplied by the factory class. l When a User Defined Aggregate function that is defined multiple times with arguments of different data types is called, HP Vertica selects the function whose input parameters match the parameters in the function call to perform the processing. l You can return a list of all SQL functions and User Defined Functions (including aggregates) by querying the system table V_CATALOG.USER_FUNCTIONS or executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. Permissions l Only a superuser can create or drop a User Defined Aggregate library. l To create a User Defined Aggregate function, the user must have CREATE and USAGE privileges on the schema and USAGE privileges on the library. l To use a User Defined Aggregate, the user must have USAGE privileges on the schema and EXECUTE privileges on the defined function. See GRANT (User Defined Extension) and REVOKE (User Defined Extension). HP Vertica Analytic Database (7.0.x) Page 1015 of 1539 SQL Reference Manual SQL Statements Examples The following example demonstrates loading a library named AggregateFunctions then defining a function named ag_avg and ag_cat that are mapped to the ag_cat AverageFactory and ConcatenateFactory classes in the library: => CREATE LIBRARY AggregateFunctions AS '/opt/vertica/sdk/examples/build/AggregateFunctio ns.so'; CREATE LIBRARY => CREATE AGGREGATE FUNCTION ag_avg AS LANGUAGE 'C++' NAME 'AverageFactory' library AggregateFunctions; CREATE AGGREGATE FUNCTION => CREATE AGGREGATE FUNCTION ag_cat AS LANGUAGE 'C++' NAME 'ConcatenateFactory' library AggregateFunctions; CREATE AGGREGATE FUNCTION => \x Expanded display is on. select * from user_functions; -[ RECORD 1 ]----------+----------------------------------------------------------------schema_name | public function_name | ag_avg procedure_type | User Defined Aggregate function_return_type | Numeric function_argument_type | Numeric function_definition | Class 'AverageFactory' in Library 'public.AggregateFunctions' volatility | is_strict | f is_fenced | f comment | -[ RECORD 2 ]----------+----------------------------------------------------------------schema_name | public function_name | ag_cat procedure_type | User Defined Aggregate function_return_type | Varchar function_argument_type | Varchar function_definition | Class 'ConcatenateFactory' in Library 'public.AggregateFunction s' volatility | is_strict | f is_fenced | f comment | See Also l CREATE LIBRARY l DROP AGGREGATE FUNCTION l GRANT (User Defined Extension) l REVOKE (User Defined Extension) HP Vertica Analytic Database (7.0.x) Page 1016 of 1539 SQL Reference Manual SQL Statements l USER_FUNCTIONS l Developing and Using User Defined Extensions l Developing a User Defined Aggregate Function CREATE ANALYTIC FUNCTION Associates a User Defined Analytic Function (UDAnF) stored in a shared Linux library with a SQL function name. You must have already loaded the library containing the UDAnF using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the arguments to the analytic function in the library to process. Syntax CREATE [ OR REPLACE ] ANALYTIC FUNCTION function-name ... AS [ LANGUAGE 'language' ] NAME 'factory' ... LIBRARY library_name ... [ FENCED | NOT FENCED ]; Parameters function-name The name to assign to the UDAnF. This is the name you use in your SQL statements to call the function. LANGUAGE 'language' The programming language used to write the UDAnF. Currently, 'C++' is supported. If not supplied, C++ is assumed. NAME 'factory' The name of the C++ factory class in the shared library that generates the object to handle the function's processing. LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED | NOT FENCED ] Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. Permissions l To CREATE a function, the user must have CREATE privilege on the schema to contain the function and USAGE privilege on the library containing the function. l To use a function, the user must have USAGE privilege on the schema that contains the function and EXECUTE privileges on the function. l To DROP a function, the user must either be a superuser, the owner of the function, or the owner of the schema which contains the function. HP Vertica Analytic Database (7.0.x) Page 1017 of 1539 SQL Reference Manual SQL Statements Notes l The parameters and return value for the function are automatically determined by the CREATE ANALYTIC FUNCTION statement, based on data supplied by the factory class. l You can assign multiple functions the same name if they accept different sets of arguments. See User Defined Function Overloading in the Programmer's Guide for more information. l You can return a list of all UDFs by querying the system table V_CATALOG.USER_ FUNCTIONS. Users see only the functions on which they have EXECUTE privileges. See Also Developing a User Defined Analytic Function CREATE FILTER Adds a User Defined Load FILTER function. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the parameters to the function in the library to process it. Syntax CREATE [ OR REPLACE ] FILTER [[db-name.]schema.]function-name ... AS LANGUAGE 'language' NAME 'factory' LIBRARY library_name ... [ FENCED | NOT FENCED ]; Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE FILTER statement fails if an existing function matches the name and parameters of the filter function you are trying to define. If you do supply this parameter, the new filter function definition overwrites the old. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You must be connected to the database you specify. You cannot make changes to objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). HP Vertica Analytic Database (7.0.x) Page 1018 of 1539 SQL Reference Manual SQL Statements function-name The name of the filter function to create. If the filter function name is schema-qualified (as above), the function is created in the specified schema. This name does not need to match the name of the factory, but it is less confusing if they are the same or similar. LANGUAGE 'language' The programming language used to develop the function. 'C++' is the only language supported by User Defined Load functions. NAME 'factory' The name of the factory class in the shared library that generates the object to handle the filter function's processing. This is the same name used by the RegisterFactory class. LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this filter function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED | NOT FENCED ] Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. Notes l The parameters and return value for the filter function are automatically determined by the CREATE FILTER statement, based on data supplied by the factory class. l You can return a list of all SQL functions and User Defined Functions by querying the system table V_CATALOG.USER_FUNCTIONS or executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. Permissions l Only a superuser can create or drop a function that uses a UDx library. l To use a User Defined Filter, the user must have USAGE privileges on the schema and EXECUTE privileges on the defined filter function. See GRANT (Function) and REVOKE (Function). Important: Installing an untrusted UDL function can compromise the security of the server. UDx's can contain arbitrary code. In particular, UD Source functions can read data from any arbitrary location. It is up to the developer of the function to enforce proper security limitations. Superusers must not grant access to UDx's to untrusted users. Example The following example demonstrates loading a library named iConverterLib, then defining a function named Iconverter that is mapped to the iConverterFactory factory class in the library: HP Vertica Analytic Database (7.0.x) Page 1019 of 1539 SQL Reference Manual SQL Statements => CREATE LIBRARY iConverterLib as '/opt/vertica/sdk/examples/build/IconverterLib.so'; CREATE LIBRARY => CREATE FILTER Iconverter AS LANGUAGE 'C++' NAME 'IconverterFactory' LIBRARY Iconverter Lib; CREATE FILTER FUNCTION => \x Expanded display is on. => SELECT * FROM user_functions; -[ RECORD 1 ]----------+-------------------schema_name | public function_name | Iconverter procedure_type | User Defined Filter function_return_type | function_argument_type | function_definition | volatility | is_strict | f is_fenced | f comment | See Also l CREATE LIBRARY l DROP FILTER l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions CREATE FUNCTION (SQL Functions) Lets you store SQL expressions as functions in HP Vertica for use in queries. These functions are useful for executing complex queries or combining HP Vertica built-in functions. You simply call the function name you assigned. Note: This topic describes how to use CREATE FUNCTION to create a SQL function. If you want to create a user-defined scalar function (UDSF), see CREATE FUNCTION (UDF). In addition, if you want to see how to create a user-defined transform function (UDTF), see CREATE TRANSFORM FUNCTION. Syntax CREATE [ OR REPLACE ] FUNCTION ... [[db-name.]schema.]function-name ( [ argname argtype HP Vertica Analytic Database (7.0.x) [, ...] ] ) Page 1020 of 1539 SQL Reference Manual SQL Statements ... RETURN rettype ... AS ... BEGIN ...... RETURN expression; ... END; Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). function-name Specifies a name for the SQL function to create. When using more than one schema, specify the schema that contains the function, as noted above. argname Specifies the name of the argument. argtype Specifies the data type for argument that is passed to the function. Argument types must match HP Vertica type names. See SQL Data Types. rettype Specifies the data type to be returned by the function. RETURN expression; Specifies the SQL function (function body), which must be in the form of ‘RETURN expression.’ expression can contain built-in functions, operators, and argument names specified in the CREATE FUNCTION statement. A semicolon at the end of the expression is required. Note: Only one RETURN expression is allowed in the CREATE FUNCTION definition. FROM, WHERE, GROUP BY, ORDER BY, LIMIT, aggregation, analytics, and meta function are not allowed. Permissions l To CREATE a function, the user must have CREATE privilege on the schema to contain the function and USAGE privilege on the library containing the function. HP Vertica Analytic Database (7.0.x) Page 1021 of 1539 SQL Reference Manual SQL Statements l To use a function, the user must have USAGE privilege on the schema that contains the function and EXECUTE privileges on the function. l To DROP a function, the user must either be a superuser, the owner of the function, or the owner of the schema which contains the function. See GRANT (User Defined Extension) and REVOKE (User Defined Extension). Notes l A SQL function can be used anywhere in a query where an ordinary SQL expression can be used, except in the table partition clause or the projection segmentation clause. l SQL Macros are flattened in all cases, including DDL. l You can create views on the queries that use SQL functions and then query the views. When you create a view, a SQL function replaces a call to the user-defined function with the function body in a view definition. Therefore, when the body of the user-defined function is replaced, the view should also be replaced. l If you want to change the body of a SQL function, use the CREATE OR REPLACE syntax. The command replaces the function with the new definition. If you change only the argument name or argument type, the system maintains both versions under the same function name. See Examples section below. l If multiple SQL functions with same name and argument type are in the search path, the first match is used when the function is called. l The strictness and volatility (stable, immutable, or volatile) of a SQL Macro are automatically inferred from the function's definition. HP Vertica then determines the correctness of usage, such as where an immutable function is expected but a volatile function is provided. l You can return a list of all SQL functions by querying the system table V_CATALOG.USER_ FUNCTIONS and executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. Example This following statement creates a SQL function called myzeroifnull that accepts an INTEGER argument and returns an INTEGER result. => CREATE FUNCTION myzeroifnull(x INT) RETURN INT AS BEGIN RETURN (CASE WHEN (x IS NOT NULL) THEN x ELSE 0 END); END; You can use the new SQL function (myzeroifnull) anywhere you use an ordinary SQL expression. For example, create a simple table: HP Vertica Analytic Database (7.0.x) Page 1022 of 1539 SQL Reference Manual SQL Statements => CREATE => INSERT => INSERT => INSERT => SELECT a --1 0 (3 rows) TABLE tabwnulls(col1 INT); INTO tabwnulls VALUES(1); INTO tabwnulls VALUES(NULL); INTO tabwnulls VALUES(0); * FROM tabwnulls; Use the myzeroifnull function in a SELECT statement, where the function calls col1 from table tabwnulls: => SELECT myzeroifnull(col1) FROM tabwnulls; myzeroifnull -------------1 0 0 (3 rows) Use the myzeroifnull function in the GROUP BY clause: => SELECT COUNT(*) FROM tabwnulls GROUP BY myzeroifnull(col1); count ------2 1 (2 rows) If you want to change a SQL function's body, use the CREATE OR REPLACE syntax. The following command modifies the CASE expression: => CREATE OR REPLACE FUNCTION zerowhennull(x INT) RETURN INT RETURN (CASE WHEN (x IS NULL) THEN 0 ELSE x END); END; AS BEGIN To see how this information is stored in the HP Vertica catalog, see Viewing Information About SQL Functions in the Programmer's Guide. See Also l ALTER FUNCTION l DROP FUNCTION l GRANT (User Defined Extension) l REVOKE (User Defined Extension) HP Vertica Analytic Database (7.0.x) Page 1023 of 1539 SQL Reference Manual SQL Statements l USER_FUNCTIONS l Using User-Defined SQL Functions CREATE FUNCTION (UDF) Adds a User Defined Function (UDF) to the catalog. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the parameters to the function in the library to process it. Note: This topic describes how to use CREATE FUNCTION to create a User Defined Function. If you want to create a SQL function, see CREATE FUNCTION (SQL Function). In addition, if you want to create a user-defined transform function (UDTF), see CREATE TRANSFORM FUNCTION. Syntax CREATE [ OR REPLACE ] FUNCTION [[db-name.]schema.]function-name ... AS LANGUAGE 'language' NAME 'factory' LIBRARY library_name ... [ FENCED | NOT FENCED ]; Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE FUNCTION statement fails if an existing function matches the name and parameters of the function you are trying to define. If you do supply this parameter, the new function definition overwrites the old. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name The name of the function to create. If the function name is schemaqualified (as above), the function is created in the specified schema. This name does not need to match the name of the factory, but it is less confusing if they are the same or similar. LANGUAGE 'language' The programming language used to develop the function. 'C++' and 'R' is supported. HP Vertica Analytic Database (7.0.x) Page 1024 of 1539 SQL Reference Manual SQL Statements NAME 'factory' The name of the factory class in the shared library that generates the object to handle the function's processing. LIBRARY library_name The name of the shared library/R functions that contains the C++ object or R functions to perform the processing for this function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED | NOT FENCED ] Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. Functions written in R always run in fenced mode. Permissions l To CREATE a function, the user must have CREATE privilege on the schema to contain the function and USAGE privilege on the library containing the function. l To use a function, the user must have USAGE privilege on the schema that contains the function and EXECUTE privileges on the function. l To DROP a function, the user must either be a superuser, the owner of the function, or the owner of the schema which contains the function. Notes l The parameters and return value for the function are automatically determined by the CREATE FUNCTION statement, based on data supplied by the factory class. l Multiple functions can share the same name if they have different parameters. When you call a multiply-defined function, HP Vertica selects the UDF function whose input parameters match the parameters in the function call to perform the processing. This behavior is similar to having multiple signatures for a method or function in other programming languages. l You can return a list of all SQL functions and UDFs by querying the system table V_ CATALOG.USER_FUNCTIONS or executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. Examples The following example demonstrates loading a library named scalarfunctions, then defining a function named Add2ints that is mapped to the Add2intsInfo factory class in the library: => CREATE LIBRARY ScalarFunctions AS '/opt/vertica/sdk/examples/build/ScalarFunctions.s o'; CREATE LIBRARY => CREATE FUNCTION Add2Ints AS LANGUAGE 'C++' NAME 'Add2IntsFactory' LIBRARY ScalarFuncti ons; HP Vertica Analytic Database (7.0.x) Page 1025 of 1539 SQL Reference Manual SQL Statements CREATE FUNCTION => \x Expanded display is on. => SELECT * FROM USER_FUNCTIONS; -[ RECORD 1 ]----------+---------------------------------------------------schema_name | public function_name | Add2Ints procedure_type | User Defined Function function_return_type | Integer function_argument_type | Integer, Integer function_definition | Class 'Add2IntsFactory' in Library 'public.ScalarFunctions' volatility | volatile is_strict | f is_fenced | t comment | => \x Expanded display is off. => -- Try a simple call to the function => SELECT Add2Ints(23,19); Add2Ints ---------42 (1 row) See Also l CREATE LIBRARY l DROP FUNCTION l GRANT (User Defined Extension) l REVOKE (User Defined Extension) l USER_FUNCTIONS l Developing and Using User Defined Extensions CREATE PARSER Adds a User Defined Load PARSER function. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the parameters to the function in the library to process it. Syntax CREATE [ OR REPLACE ] PARSER [[db-name.]schema.]function-name ... AS LANGUAGE 'language' NAME 'factory' LIBRARY library_name ... [ FENCED | NOT FENCED ]; HP Vertica Analytic Database (7.0.x) Page 1026 of 1539 SQL Reference Manual SQL Statements Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE PARSER statement fails if an existing function matches the name and parameters of the parser function you are trying to define. If you do supply this parameter, the new parser function definition overwrites the old. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You must be connected to the database you specify. You cannot make changes to objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name The name of the parser function to create. If the parser function name is schema-qualified (as above), the function is created in the specified schema. This name does not need to match the name of the factory, but it is less confusing if they are the same or similar. LANGUAGE 'language' The programming language used to develop the function. 'C++' is the only language supported by User Defined Load functions. NAME 'factory' The name of the factory class in the shared library that generates the object to handle the parser function's processing. This is the same name used by the RegisterFactory class. LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this parser function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. NOT FENCED ] Notes l The parameters and return value for the parser function are automatically determined by the CREATE PARSER statement, based on data supplied by the factory class. l You can return a list of all SQL functions and User Defined Functions by querying the system table V_CATALOG.USER_FUNCTIONS or executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. HP Vertica Analytic Database (7.0.x) Page 1027 of 1539 SQL Reference Manual SQL Statements Permissions l Only a superuser can create or drop a function that uses a UDx library. l To use a User Defined Parser, the user must have USAGE privileges on the schema and EXECUTE privileges on the defined parser function. See GRANT (Function) and REVOKE (Function). Important: Installing an untrusted UDL function can compromise the security of the server. UDx's can contain arbitrary code. In particular, UD Source functions can read data from any arbitrary location. It is up to the developer of the function to enforce proper security limitations. Superusers must not grant access to UDx's to untrusted users. Example The following example demonstrates loading a library named BasicIntegrerParserLib, then defining a function named BasicIntegerParser that is mapped to the BasicIntegerParserFactory factory class in the library: => CREATE LIBRARY BasicIntegerParserLib as '/opt/vertica/sdk/examples/build/BasicIntegerP arser.so'; CREATE LIBRARY => CREATE PARSER BasicIntegerParser AS LANGUAGE 'C++' NAME 'BasicIntegerParserFactory' LI BRARY BasicIntegerParserLib; CREATE PARSER FUNCTION => \x Expanded display is on. => SELECT * FROM user_functions; -[ RECORD 1 ]----------+-------------------schema_name | public function_name | BasicIntegerParser procedure_type | User Defined Parser function_return_type | function_argument_type | function_definition | volatility | is_strict | f is_fenced | f comment | See Also l CREATE LIBRARY l DROP PARSER l GRANT (Function) l REVOKE (Function) HP Vertica Analytic Database (7.0.x) Page 1028 of 1539 SQL Reference Manual SQL Statements l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions CREATE SOURCE Adds a User Defined Load SOURCE function. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the parameters to the function in the library to process it. Syntax CREATE [ OR REPLACE ] SOURCE [[db-name.]schema.]function-name ... AS LANGUAGE 'language' NAME 'factory' LIBRARY library_name ... [ FENCED | NOT FENCED ]; Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE SOURCE statement fails if an existing function matches the name and parameters of the source function you are trying to define. If you do supply this parameter, the new source function definition overwrites the old. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You must be connected to the database you specify. You cannot make changes to objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name The name of the source function to create. If the source function name is schema-qualified (as above), the function is created in the specified schema. This name does not need to match the name of the factory, but it is less confusing if they are the same or similar. LANGUAGE 'language' The programming language used to develop the function. 'C++' is the only language supported by User Defined Load functions. NAME 'factory' The name of the factory class in the shared library that generates the object to handle the source function's processing. This is the same name used by the RegisterFactory class. HP Vertica Analytic Database (7.0.x) Page 1029 of 1539 SQL Reference Manual SQL Statements LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this source function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED | NOT FENCED ] Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. Notes l The parameters and return value for the source function are automatically determined by the CREATE SOURCE statement, based on data supplied by the factory class. l You can return a list of all SQL functions and User Defined Functions by querying the system table V_CATALOG.USER_FUNCTIONS or executing the vsql meta-command \df. Users see only the functions on which they have EXECUTE privileges. Permissions l Only a superuser can create or drop a function that uses a UDx library. l To use a User Defined Source, the user must have USAGE privileges on the schema and EXECUTE privileges on the defined source function. See GRANT (Function) and REVOKE (Function). Important: Installing an untrusted UDL function can compromise the security of the server. UDx's can contain arbitrary code. In particular, UD Source functions can read data from any arbitrary location. It is up to the developer of the function to enforce proper security limitations. Superusers must not grant access to UDx's to untrusted users. Example The following example demonstrates loading a library named curllib, then defining a function named curl that is mapped to the CurlSourceFactory factory class in the library: => CREATE LIBRARY curllib as '/opt/vertica/sdk/examples/build/cURLLib.so'; CREATE LIBRARY => CREATE SOURCE curl AS LANGUAGE 'C++' NAME 'CurlSourceFactory' LIBRARY curllib; CREATE SOURCE => \x Expanded display is on. => SELECT * FROM user_functions; -[ RECORD 1 ]----------+-------------------schema_name | public function_name | curl procedure_type | User Defined Source function_return_type | function_argument_type | function_definition | HP Vertica Analytic Database (7.0.x) Page 1030 of 1539 SQL Reference Manual SQL Statements volatility is_strict is_fenced comment | | f | f | See Also l CREATE LIBRARY l DROP SOURCE l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions CREATE TRANSFORM FUNCTION Adds a User Defined Transform Function (UDTF) stored in a shared Linux library to the catalog. You must have already loaded this library using the CREATE LIBRARY statement. When you call the SQL function, HP Vertica passes the input table to the transform function in the library to process. Note: This topic describes how to create a UDTF. If you want to create a user-defined function (UDF), see CREATE FUNCTION (UDF). If you want to create a SQL function, see CREATE FUNCTION (SQL). Syntax CREATE TRANSFORM FUNCTION function-name ... [ AS LANGUAGE 'language' ] NAME 'factory' ... LIBRARY library_name ... [ FENCED | NOT FENCED ]; Parameters function-name The name to assign to the UDTF. This is the name you use in your SQL statements to call the function. LANGUAGE 'language' The programming language used to write the UDTF. Currently, 'C++' and 'R' is supported. If not supplied, C++ is assumed. HP Vertica Analytic Database (7.0.x) Page 1031 of 1539 SQL Reference Manual SQL Statements NAME 'factory' The name of the C++ factory class or R factory function in the shared library that generates the object to handle the function's processing. LIBRARY library_name The name of the shared library that contains the C++ object to perform the processing for this function. This library must have been previously loaded using the CREATE LIBRARY statement. [ FENCED | NOT FENCED ] Enables or disables Fenced Mode for this function. Fenced mode is enabled by default. Functions written in R always run in fenced mode. Permissions l To CREATE a function, the user must have CREATE privilege on the schema to contain the function and USAGE privilege on the library containing the function. l To use a function, the user must have USAGE privilege on the schema that contains the function and EXECUTE privileges on the function. l To DROP a function, the user must either be a superuser, the owner of the function, or the owner of the schema which contains the function. See GRANT (Transform Function) and REVOKE (Transform Function). UDTF Query Restrictions A query that includes a UDTF cannot contain: n Any statements other than the SELECT statement containing the call to the UDTF and a PARTITION BY expression n Any other analytic function n A call to another UDTF n A TIMESERIES clause n A pattern matching clause n A gap filling and interpolation clause Notes l The parameters and return values for the function are automatically determined by the CREATE TRANSFORM FUNCTION statement, based on data supplied by the factory class. l You can assign multiple functions the same name if they have different parameters. When you call a multiply-defined function, HP Vertica selects the UDF function whose input parameters HP Vertica Analytic Database (7.0.x) Page 1032 of 1539 SQL Reference Manual SQL Statements match the parameters in the function call to perform the processing. This behavior is similar to having multiple signatures for a method or function in other programming languages. l You can return a list of all UDFs by querying the system table V_CATALOG.USER_ FUNCTIONS. Users see only the functions on which they have EXECUTE privileges. See Also l DROP FUNCTION l GRANT (User Defined Extension) l REVOKE (User Defined Extension) l USER_FUNCTIONS l Developing and Using User Defined Extensions CREATE HCATALOG SCHEMA Define a schema for data stored in a Hive data warehouse using the HCatalog Connector. For more information, see Using the HCatalog Connector in the Hadoop Integration Guide. Syntax CREATE HCATALOG SCHEMA [IF NOT EXISTS] schemaName [AUTHORIZATION user-id] WITH HOSTNAME='metastore-host' [PORT=hiveMetastore-port] [WEBSERVICE_HOSTNAME='webHCat-hostname'] [WEBSERVICE_PORT=webHCat-port] [HCATALOG_SCHEMA='hive-schema-name'] [HCATALOG_USER='hcat-username'] [HCATALOG_CONNECTION_TIMEOUT=timeout] [HCATALOG_SLOW_TRANSFER_LIMIT=xfer-limit] [HCATALOG_SLOW_TRANSFER_TIME=xfer-time] Parameters Default Value Parameter Description [IF NOT EXISTS] If given, the statement exits without an error when the schema named in schemaName already exists. HP Vertica Analytic Database (7.0.x) N/A Page 1033 of 1539 SQL Reference Manual SQL Statements schemaName The name of the schema to create in the Vertica Analytic Database catalog. The tables in the Hive database will be available through this schema. none user-id The name of an Vertica Analytic Database account to own the schema being created current username metastore-host The hostname or IP address of the database server that stores the Hive data warehouse's metastore information. none hiveMetastore- The port number on which the metastore database is running. port 9083 webHCathostname The hostname or IP address of the WebHCat server (formerly known as Templeton). metastorehost webHCat-port The port number on which the WebHCat service is running. 50111 hive-schemaname The name of the Hive schema or database that the Vertica Analytic Database schema is being mapped to. schemaName hcat-username The username of the HCatalog user to use in when making calls to the WebHCat server. current username timeout The number of seconds the HCatalog Connector waits for a successful connection to the WebHCat server. A value of 0 means wait indefinitely. See notes xfer-limit The lowest data transfer rate (in bytes per second) from the WebHCat server that the HCatalog Connector accepts. See xfer-time for details. See notes xfer-time The number of seconds the HCatalog Connector waits before enforcing the data transfer rate lower limit. After this time has passed, the HCatalog Connector tests whether the data transfer rate from theWebHCat server is at least as fast as the value set in xfer-limit. If it is not, then the HCatalog Connector breaks the connection and terminates the query. See notes Notes The default values for timeout, xfer-limit, and xfer-time values are set by the configuration parameters HCatConnectionTimeout, HCatSlowTransferLimit, and HCatSlowTransferTime. See HCatalog Connector Parameters in the Administrator's Guide for more information. Permissions The user must be a superuser or be granted all permissions on the database to use CREATE HCATALOG SCHEMA. HP Vertica Analytic Database (7.0.x) Page 1034 of 1539 SQL Reference Manual SQL Statements Example The following statement shows using CREATE HCATALOG SCHEMA to define a new schema for tables stored in a Hive database, then querying the system tables that contain information about those tables: => CREATE HCATALOG SCHEMA hcat WITH hostname='hcathost' HCATALOG_SCHEMA='default' -> HCATALOG_USER='hcatuser'; CREATE SCHEMA => -- Show list of all HCatalog schemas => \x Expanded display is on. => SELECT * FROM v_catalog.hcatalog_schemata; -[ RECORD 1 ]--------+-----------------------------schema_id | 45035996273748980 schema_name | hcat schema_owner_id | 45035996273704962 schema_owner | dbadmin create_time | 2013-11-04 15:09:03.504094-05 hostname | hcathost port | 9933 webservice_hostname | hcathost webservice_port | 50111 hcatalog_schema_name | default hcatalog_user_name | hcatuser metastore_db_name | hivemetastoredb => -- List the tables in all HCatalog schemas => SELECT * FROM v_catalog.hcatalog_table_list; -[ RECORD 1 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | messages hcatalog_user_name | hcatuser -[ RECORD 2 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | weblog hcatalog_user_name | hcatuser -[ RECORD 3 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | tweets hcatalog_user_name | hcatuser CREATE LIBRARY Loads a C++ shared library or R file containing user defined functions (UDFs). You supply the absolute path to a Linux shared library (.so) file or R file (.R) that contains the functions you want to access. See Developing and Using User Defined Extensions in the Programmer's Guide for HP Vertica Analytic Database (7.0.x) Page 1035 of 1539 SQL Reference Manual SQL Statements details. If you supply the optional OR REPLACE argument, the library will replace any existing library with the same name. Warning: User defined libraries are directly loaded by HP Vertica and may be run within the database process. By default, most UDF's developed in C++ run in Fenced Mode so that the function process runs outside of HP Vertica. However, if you choose not to run your code in fenced mode, or the type of UDF cannot be run in fenced mode (for example, User Defined Load), then your custom code can negatively impact database. Poorly-coded UDFs can cause instability or even database crashes. Syntax CREATE [OR REPLACE] LIBRARY [[db-name.]schema.]library_name AS 'library_path' [ LANGUAGE 'lang uage' ] Parameters [ OR REPLACE ] If you do not supply this parameter, the CREATE LIBRARY statement fails if an existing library matches the name the library you are trying to define. If you do supply this parameter, the new library replaces the old. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). library_name A name to assign to this library. This is the name you use in a CREATE FUNCTION statement to enable user defined functions stored in the library. Note that this name is arbitrary. It does not need to reflect the name of the library file, although it would be less confusing if did. 'library_path' The absolute path and filename of the library to load located on the initiator node. 'language' The programming language used to develop the function. 'R' and 'C++' are supported. Default is 'C++'. Permissions Must be a superuser to create or drop a library. HP Vertica Analytic Database (7.0.x) Page 1036 of 1539 SQL Reference Manual SQL Statements Notes l As part of the loading process, HP Vertica distributes the library file to other nodes in the database. Any nodes that are down or that are added to the cluster later automatically receive a copy of the library file when they join the cluster. Subsequent modification (or deletion) of the file/path provided in the CREATE LIBRARY statement has no effect. l The CREATE LIBRARY statement performs some basic checks on the library file to ensure it is compatible with HP Vertica. The statement fails if it detects that the library was not correctly compiled or it finds other basic incompatibilities. However, there are many issues in shared libraries that CREATE LIBRARY cannot detect. Simply loading the library is no guarantee that it functions correctly. l Libraries are added to the database catalog, and therefore persist across database restarts. Examples To load a library in the home directory of the dbadmin account with the name MyFunctions: => CREATE LIBRARY MyFunctions AS 'home/dbadmin/my_functions.so'; To load a library located in the directory where you started vsql: => \set libfile '\''`pwd`'/MyOtherFunctions.so\''; => CREATE LIBRARY MyOtherFunctions AS :libfile; See Also l DROP LIBRARY l ALTER LIBRARY l CREATE FUNCTION (UDF) CREATE LOCAL TEMPORARY VIEW Creates a new local temporary view. Temporary views have the same restrictions as permanent views, so you cannot perform insert, update, delete, or copy operations on these views. Local temporary views are session-scoped; the view drops automatically when the session ends. For more information, see Managing Sessionsin the Administrator's Guide. Note: HP Vertica does not support global temporary views. HP Vertica Analytic Database (7.0.x) Page 1037 of 1539 SQL Reference Manual SQL Statements Syntax CREATE [ OR REPLACE ] LOCAL TEMPORARY | TEMP VIEW viewname [ ( column-name [, ...] ) ] AS query ] Parameters [ OR REPLACE ] Overwrites any existing local temporary view with the name viewname. If you do not specify this option and a temporary view with that name already exists, CREATE LOCAL TEMP VIEW returns an error. viewname Specifies the name of the local temporary view to create. The temporary view name must be unique. Do not use the same name as any table, view, or projection within the database. If you do not supply a name for the temporary view, the statement uses the current user name. column-name [Optional] Specifies the list of names to use as column names for the temporary view. Columns are presented from left to right in the order given. If you do not specify one or more column names, HP Vertica automatically deduces the column names from the query. query Specifies the SELECT query that the temporary view executes. HP Vertica also uses the query to deduce the list of names to be used as columns names for the temporary view if you do not specify them. Use a SELECT statement to specify the query, which can refer to tables, temp tables, and other views. Permissions The following permissions apply to local temporary views: l To create a local temporary view, the user must have usage permissions on any base object from which the view pulls. l Privileges required on base objects for the view owner must be granted directly; you cannot grant privileges on these objects using roles. l Since local temporary entities are session scoped, local temporary views are visible only to their creator in the session in which it was created. Transforming a SELECT Query to Use a Temporary Local View When HP Vertica processes a query containing a local temp view (or any view) the view is treated as a subquery to the view's enclosing statement. For more information, see CREATE VIEW. HP Vertica Analytic Database (7.0.x) Page 1038 of 1539 SQL Reference Manual SQL Statements Example => CREATE LOCAL TEMP VIEW myview AS SELECT SUM(annual_income), customer_state FROM public.customer_dimension WHERE customer_key IN (SELECT customer_key FROM store.store_sales_fact) GROUP BY customer_state ORDER BY customer_state ASC; The following example uses the myview temporary view with a WHERE clause that limits the results to combined salaries of greater than 2,000,000,000. => SELECT * FROM myview WHERE SUM > 2000000000; SUM | customer_state -------------+---------------2723441590 | AZ 29253817091 | CA 4907216137 | CO 3769455689 | CT 3330524215 | FL 4581840709 | IL 3310667307 | IN 2793284639 | MA 5225333668 | MI 2128169759 | NV 2806150503 | PA 2832710696 | TN 14215397659 | TX 2642551509 | UT (14 rows) See Also l ALTER VIEW l SELECT l CREATE VIEW l SELECT l DROP VIEW l GRANT (View) l REVOKE (View) HP Vertica Analytic Database (7.0.x) Page 1039 of 1539 SQL Reference Manual SQL Statements CREATE NETWORK INTERFACE Identifies a network interface to which the node belongs. Use this statement when you want to configure import/export from individual nodes to other HP Vertica clusters. Syntax CREATE NETWORK INTERFACE network-interface-name ON node-name WITH 'ip address of node' network-interface-name The name you assign to the network interface. node-name The name of the node. IP address of node The IP Address of the node. Permissions Must be a superuser to create a network interface. CREATE PROCEDURE Adds an external procedure to HP Vertica. See Implementing External Procedures in the Programmer's Guide for more information about external procedures. Syntax CREATE PROCEDURE [[db-name.]schema.]procedure-name ( ... [ argname ] [ argtype [,...] ] ) ... AS 'exec-name' ... LANGUAGE 'language-name' ... USER 'OS-user' HP Vertica Analytic Database (7.0.x) Page 1040 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). procedure-name Specifies a name for the external procedure. If the procedure-name is schema-qualified, the procedure is created in the specified schema. argname [Optional] Presents a descriptive argument name to provide a cue to procedure callers. argtype [Optional] Specifies the data type for argument(s) that will be passed to the procedure. Argument types must match HP Vertica type names. See SQL Data Types. AS Specifies the executable program in the procedures directory. LANGUAGE Specifies the procedure language. This parameter must be set to EXTERNAL. USER Specifies the user executed as. The user is the owner of the file. The user cannot be root. Note: The external program must allow execute privileges for this user. Permissions To create a procedure a superuser must have CREATE privilege on schema to contain procedure. Notes l A procedure file must be owned by the database administrator (OS account) or by a user in the same group as the administrator. (The procedure file owner cannot be root.) The procedure file must also have the set UID attribute enabled, and allow read and execute permission for the group. HP Vertica Analytic Database (7.0.x) Page 1041 of 1539 SQL Reference Manual SQL Statements By default, only a database superuser can execute procedures. However, a superuser can grant the right to execute procedures to other users. See GRANT (Procedure). l Example This example illustrates how to create a procedure named helloplanet for the helloplanet.sh external procedure file. This file accepts one varchar argument. Sample file: #!/bin/bashecho "hello planet argument: $1" >> /tmp/myprocedure.log exit 0 Issue the following SQL to create the procedure: CREATE PROCEDURE helloplanet(arg1 varchar) AS 'helloplanet.sh' LANGUAGE 'external' USER ' release'; See Also DROP PROCEDURE l l CREATE PROFILE Creates a profile that controls password requirements for users. Syntax CREATE PROFILE name LIMIT ... [PASSWORD_LIFE_TIME {life-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_GRACE_TIME {grace_period | DEFAULT | UNLIMITED}] ... [FAILED_LOGIN_ATTEMPTS {login-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_LOCK_TIME {lock-period | DEFAULT | UNLIMITED}] ... [PASSWORD_REUSE_MAX {reuse-limit | DEFAULT | UNLIMITED}] ... [PASSWORD_REUSE_TIME {reuse-period | DEFAULT | UNLIMITED}] ... [PASSWORD_MAX_LENGTH {max-length | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LENGTH {min-length | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LETTERS {min-letters | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_UPPERCASE_LETTERS {min-cap-letters | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_LOWERCASE_LETTERS {min-lower-letters | DEFAULT | UNLIMITED}] ... [PASSWORD_MIN_DIGITS {min-digits | DEFAULT | UNLIMITED}] Note: For all parameters, the special DEFAULT value means that the parameter's value is inherited from the DEFAULT profile. Any changes to the parameter in the DEFAULT profile is reflected by all of the profiles that inherit that parameter. Any parameter not specified in the HP Vertica Analytic Database (7.0.x) Page 1042 of 1539 SQL Reference Manual SQL Statements CREATE PROFILE command is set to DEFAULT. Parameters Meaning of UNLIMITED value Name Description name The name of the profile to create PASSWORD_LIFE_TIME life-limit Integer number of days a Passwords password remains valid. never expire. After the time elapses, the user must change the password (or will be warned that their password has expired if PASSWORD_GRACE_ TIME is set to a value other than zero or UNLIMITED). PASSWORD_GRACE_TIMEgrace-period Integer number of days the users are allowed to login (while being issued a warning message) after their passwords are older than the PASSWORD_ LIFE_TIME. After this period expires, users are forced to change their passwords on login if they have not done so after their password expired. No grace period (the same as zero) FAILED_LOGIN_ATTEMPTSlogin-limit The number of consecutive failed login attempts that result in a user's account being locked. Accounts are never locked, no matter how many failed login attempts are made. HP Vertica Analytic Database (7.0.x) N/A Page 1043 of 1539 SQL Reference Manual SQL Statements Meaning of UNLIMITED value Name Description PASSWORD_LOCK_TIME lock-period Integer value setting the number of days an account is locked after the user's account was locked by having too many failed login attempts. After the PASSWORD_LOCK_ TIME has expired, the account is automatically unlocked. Accounts locked because of too many failed login attempts are never automatically unlocked. They must be manually unlocked by the database superuser. PASSWORD_REUSE_MAX reuse-limit The number of password changes that need to occur before the current password can be reused. Users are not required to change passwords a certain number of times before reusing an old password. PASSWORD_REUSE_TIMEreuse-period The integer number of days that must pass after a password has been set before the before it can be reused. Password reuse is not limited by time. PASSWORD_MAX_LENGTH max-length The maximum number of characters allowed in a password. Value must be in the range of 8 to 100. Passwords are limited to 100 characters. PASSWORD_MIN_LENGTH min-length The minimum number of characters required in a password. Valid range is 0 to max-length. Equal to maxlength. PASSWORD_MIN_LETTERSmin-of-letters Minimum number of letters (a-z and A-Z) that must be in a password. Valid ranged is 0 to max-length. 0 (no minimum). HP Vertica Analytic Database (7.0.x) Page 1044 of 1539 SQL Reference Manual SQL Statements Meaning of UNLIMITED value Name Description PASSWORD_MIN_UPPERCASE_LETTERSmin-cap-letters Minimum number of capital letters (A-Z) that must be in a password. Valid range is is 0 to max-length. 0 (no minimum). PASSWORD_MIN_LOWERCASE_LETTERSmin-lower-letters Minimum number of lowercase letters (a-z) that must be in a password. Valid range is is 0 to maxlength. 0 (no minimum). PASSWORD_MIN_DIGITS min-digits Minimum number of digits (0-9) that must be in a password. Valid range is is 0 to max-length. 0 (no minimum). PASSWORD_MIN_SYMBOLSmin-symbols Minimum number of 0 (no symbols (any printable minimum). non-letter and non-digit character, such as $, #, @, and so on) that must be in a password. Valid range is is 0 to max-length. Permissions Must be a superuser to create a profile. Note: Only the profile settings for how many failed login attempts trigger account locking and how long accounts are locked have an effect on external password authentication methods such as LDAP or Kerberos. All password complexity, reuse, and lifetime settings have an effect on passwords managed by HP Vertica only. See Also l ALTER PROFILE l DROP PROFILE CREATE PROJECTION Creates metadata for a projection in the HP Vertica catalog. You can create a segmented projection, recommended for large tables. Unsegmented projections are recommended only for HP Vertica Analytic Database (7.0.x) Page 1045 of 1539 SQL Reference Manual SQL Statements small tables, which are then replicated across all cluster nodes. You can also create projections using a combination of individual columns and grouped columns. You can optionally apply a specific access rank to one or more columns, and encoding for an individual column or group of columns. Syntax CREATE PROJECTION [ IF NOT EXISTS ] ...[[db-name.]schema.]projection-name ...[ ( { projection-column ...| { GROUPED ( column-reference1, column-reference2 [ ,... ])} ......... [ ACCESSRANK integer ] ......... [ ENCODING Encoding-Type ] } [ ,... ] ) ...] AS SELECT table-column [ , ... ] FROM table-reference [ , ... ] ... [ WHERE Join-Predicate [ AND join-predicate ] ... ... [ ORDER BY table-column [ , ... ] ] ... [ Hash-Segmentation-Clause ... | UNSEGMENTED { NODE node | ALL NODES } ] ... [ KSAFE [ k-num ] ] Parameters [ IF NOT EXISTS ] [Optional] Determines whether the statement generates a NOTICE message or an ERROR if -name exists. Using IF NOT EXISTS generates a NOTICE if the specified object exists. Omitting the clause generates an error if -name exists. Regardless of whether you use IF NOT EXISTS, HP Vertica does not create a new object if name exists. For more information, see also ON_ERROR_ STOP. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). projection-name HP Vertica Analytic Database (7.0.x) Specifies the name of the projection to create. If the projectionname is schema-qualified, the projection is created in the specified schema. Otherwise, the projection is created in the same schema as the anchor table. If the projection-name you supply results in a naming conflict with existing catalog objects (projections), the CREATE PROJECTION statement fails. All projections include a base table name added automatically. You refer to the base table name to drop or alter a projection. Page 1046 of 1539 SQL Reference Manual SQL Statements projection-column [Optional] Specifies the name of one or more columns in the projection. The column data type is that of the corresponding column in the schema table (based on ordinal position). If you do not explicitly provide projection column names, the column names for the table specified in the SELECT statement are used. The following example automatically uses store and transaction as the projection column names for sales_p: => CREATE TABLE sales(store INTEGER, transaction INTEGER);=> CREATE PROJECTION sales_p AS SELECT * FROM sales KSAFE 1; Note that you cannot use specific encodings on projection columns using the CREATE PROJECTION function this way. You can use different projection-column names to distinguish multiple columns with the same name in different tables so that no aliases are needed. [ ENCODING encoding-type ] [Optional] Specifies the type of encoding to use on the column. By default, the encoding type is auto. Caution: The NONE keyword is obsolete. [ ACCESSRANK integer ] [Optional] Overrides the default access rank for a column. This is useful if you want to increase or decrease the speed at which a column is accessed. See Creating and Configuring Storage Locations and Prioritizing Column Access Speed in the Administrator's Guide. To use this option correctly, you must specify ACCESSRANK n directly with the column to which it applies. For instance, this statement correctly assigns an access rank to two of the three named columns col_night, and col_day: CREATE PROJECTION PJ(col_night, accessrank 2, col_evening, c ol_day, accessrank 1)AS SELECT * FROM test The following statement will fail, because the second access rank is not associated directly with a column: CREATE PROJECTION PJ(col_night, col_evening, col_day, access rank 2, accessrank 1) AS SELECT * FROM test HP Vertica Analytic Database (7.0.x) Page 1047 of 1539 SQL Reference Manual SQL Statements [ GROUPED (column-reference1, column-reference2 [,...] ) ] [Optional] Groups the specified projection column references into a single disk file. Using the GROUPED parameter requires a minimum of two column-reference elements. You can specify more than one set of grouped columns, and intersperse them with non-grouped column references. Grouping projection columns minimizes file I/O for work loads that: l Read a large percentage of the columns in a table. l Perform single row look-ups. l Query against many small columns. l Frequently update data in these columns. If you have columns of data that are always accessed together, and not used in predicates, grouping the columns can increase query performance. However, once grouped, queries can no longer retrieve from disk all records for any individual columns within the group. Note: RLE compression is reduced when a RLE column is grouped with one or more non-RLE columns. When grouping columns you can: l Group some of the columns: (a, GROUPED(b, c), d) l Group all of the columns: (GROUPED(a, b, c, d)) l Create multiple groupings in the same projection: (GROUPED (a, b), GROUPED(c, d)) Note: HP Vertica performs dynamic column grouping. For example, to provide better read and write efficiency for small loads, HP Vertica ignores any projection-defined column grouping (or lack thereof) and groups all columns together by default. HP Vertica Analytic Database (7.0.x) Page 1048 of 1539 SQL Reference Manual SQL Statements SELECT table-column Specifies a list of schema table columns corresponding (in ordinal position) to the projection columns. Note: When creating a projection, the total number of projection column references, including those noted in the GROUPED statement, must equal the number of columns specified in the Select statement (unless the Select statement indicates select *). table-reference Specifies a list of schema tables containing the columns to include in the projection in the form: table-name [ AS ] alias [ ( column-alias [ , ...] ) ] [ , .. .] ] [ WHERE join-predicate ] [Optional] Specifies foreign-key = primary-key equijoins between the large and smaller tables. No other predicates are allowed. [ ORDER BY table-column ] [Optional] Specifies the columns to sort the projection on. You cannot specify an ascending or descending clause. HP Vertica always uses an ascending sort order in physical storage. Note: If you do not specify the ORDER BY table-column parameter, HP Vertica uses the order in which columns are specified in the column list as the sort order for the projection. hash-segmentation-clause [Optional] Segments a projection evenly and distributes the data across nodes using a built-in hash function. Creating a projection with hash segmentation results in optimal query execution. See Hash-Segmentation-Clause. Note: An elastic projection (a segmented projection created when Elastic Cluster is enabled) created with a modularhash segmentation expression uses hash instead. HP Vertica Analytic Database (7.0.x) Page 1049 of 1539 SQL Reference Manual SQL Statements UNSEGMENTED{ NODE node | ALL NODES } KSAFE [ k-num ] [Optional] Lets you specify an unsegmented projection. The default for this parameter is to create an UNSEGMENTED projection on the initiator node. You can optionally use either of the following node specifications: n NODE node—Creates an unsegmented projection only on the specified node. Projections for small tables must be UNSEGMENTED. n ALL NODES—Automatically replicates the unsegmented projection on each node. To perform distributed query execution, HP Vertica requires an unsegmented copy of each small table superprojection on each node. [Optional] Specifies the K-safety level of the projection. The knum integer determines how many replicated or segmented buddy projections are created. The value must be greater than or equal to the current K-safety level of the database and less than the total number of nodes. HP recommends that you use multiple projection syntax for K-safe clusters. If the KSAFE parameter is omitted,a single projection is created at the current system K-safety level. Unless you are creating a projection on a single-node database, the default KSAFE value is at least one. For instance, this example creates a superprojection for a database with a K-safety of one (1): KSAFE 1 Permissions Projections get implicitly created when you insert data into a table, an operation that automatically creates a superprojection for the table. Implicitly-created projections do not require any additional privileges to create or drop, other than privileges for table creation. Users who can create a table or drop a table can also create and drop the associated superprojection. To explicitly create a projection using the CREATE PROJECTION statement, a user must be a superuser or owner of the anchor table or have the following privileges: l CREATE privilege on the schema in which the projection is created l SELECT on all the base tables referenced by the projection l USAGE on all the schemas that contain the base tables referenced by the projection Explicitly-created projections can only be dropped by the table owner on which the projection is based for a single-table projection, or the owner of the anchor table for pre-join projections. HP Vertica Analytic Database (7.0.x) Page 1050 of 1539 SQL Reference Manual SQL Statements Projections and Superprojections If you attempt to create a projection or a pre-join projection before a superprojection exists, HP Vertica displays a warning. This example attempts to create a projection before a superprojection: VMart=> create table tar (x integer, y integer); CREATE TABLE VMart=> create projection tar_p as select x from tar; WARNING 4130: No super projections created for table public.tar. HINT: Default super projections will be automatically created with the next DML CREATE PROJECTION This example attempts to create a pre-join projection when no superprojection exists: VMart=> create projection foo_p as select near.x, far.x from near join far on near.x = fa r.x unsegmented all nodes; WARNING 4130: No super projections created for table public.far. HINT: Default super projections will be automatically created with the next DML CREATE PROJECTION Checking Column Constraints When you create a projection, HP Vertica checks column constraints during the process. For instance, if a join predicate includes a column with a FOREIGN_KEY constraint but without a NOT_NULL constraint, the CREATE PROJECTION statement fails. Updating the Projection Using Refresh Invoking the CREATE PROJECTION command does not load data into physical storage. If the tables over which the projection is defined already contain data, you must issue START_ REFRESH to update the projection. Depending on how much data is in the tables, updating a projection can be time-consuming. Once a projection is up-to-date, however, it is updated automatically as part of COPY, DELETE, INSERT, MERGE, or UPDATE statements. Monitoring Projecting Refresh on Buddy Projects A projection is not refreshed until after a buddy projection is created. After the CREATE PROJECTION is run, if you run SELECT START_REFRESH() the following message displays: Starting refresh background process However, the refresh does not begin until after a buddy projection is created. You can monitor the refresh operation by examining the vertica.log file or view the final status of the projection refresh by using SELECT get_projections('table-name;). For example: HP Vertica Analytic Database (7.0.x) Page 1051 of 1539 SQL Reference Manual SQL Statements => SELECT get_projections('customer_dimension'); get_projections ---------------------------------------------------------------Current system K is 1. # of Nodes: 4. Table public.customer_dimension has 4 projections. Projection Name: [Segmented] [Seg Cols] [# of Buddies] [Buddy Projections] [Safe] [UptoDa te] ----------------------------------------------------------public.customer_dimension_node 0004 [Segmented: No] [Seg Cols: ] [K: 3] [public.customer_dimension_node0003, public.cust omer_dimension_node0002, public.customer_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes]public.customer_dimension_node0003 [Segmented: N o] [Seg Cols: ] [K: 3] [public.customer_dimension_node0004, public.customer_dimension_nod e0002, public.customer_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes]public.customer_dimension_node0002 [Segmented: N o] [Seg Cols: ] [K: 3] [public.customer_dimension_node0004, public.customer_dimension_nod e0003, public.customer_dimension_node0001] [Safe: Yes] [UptoDate: Yes][Stats: Yes]public.customer_dimension_node0001 [Segmented: N o] [Seg Cols: ] [K: 3] [public.customer_dimension_node0004, public.customer_dimension_nod e0003, public.customer_dimension_node0002] [Safe: Yes] [UptoDate: Yes][Stats: Yes](1 row) Creating Unsegmented Projections with the ALL NODES Option Using the UNSEGMENTED option to create a projection takes a snapshot of the nodes defined at execution time to generate a predictable node list order. Creating unsegmented projections results in each replicated projection having the following naming convention, with an appended node-name suffix: projection-name_node-name For example, if the cluster node names are NODE01, NODE02, and NODE03, creating an unsegmented projection with the following command, creates projections named ABC_NODE01, ABC_ NODE02, and ABC_NODE03: => CREATE PROJECTION ABC ... UNSEGMENTED ALL NODES; Creating unsegmented projections (with a node-name suffix), affects the projection name argument value for functions such as GET_PROJECTIONS or GET_PROJECTION_STATUS. For these functions, you must provide the entire projection name, including the node-name suffix (ABC_ NODE01), rather than the projection name alone (ABC). To view a list of the nodes in a database, use the View Database command in the Administration Tools. Example The following example groups the highly correlated columns bid and ask. However, the stock column is stored separately. HP Vertica Analytic Database (7.0.x) Page 1052 of 1539 SQL Reference Manual SQL Statements => CREATE TABLE trades (stock CHAR(5), bid INT, ask INT); => CREATE PROJECTION tradeproj (stock ENCODING RLE, GROUPED(bid ENCODING DELTAVAL, ask)) AS (SELECT * FROM trades) KSAFE 1; Encoding-Type HP Vertica supports the following encoding and compression types: ENCODING AUTO (default) For CHAR/VARCHAR, BOOLEAN, BINARY/VARBINARY, and FLOAT columns, Lempel-ZivOberhumer-based (LZO) compression is used. For INTEGER, DATE/TIME/TIMESTAMP, and INTERVAL types, the compression scheme is based on the delta between consecutive column values. AUTO encoding is ideal for sorted, many-valued columns such as primary keys. It is also suitable for general purpose applications for which no other encoding or compression scheme is applicable. Therefore, it serves as the default if no encoding/compression is specified. The CPU requirements for this type are relatively small. In the worst case, data might expand by eight percent (8%) for LZO and twenty percent (20%) for integer data. ENCODING BLOCK_DICT For each block of storage, HP Vertica compiles distinct column values into a dictionary and then stores the dictionary and a list of indexes to represent the data block. BLOCK_DICT is ideal for few-valued, unsorted columns in which saving space is more important than encoding speed. Certain kinds of data, such as stock prices, are typically few-valued within a localized area once the data is sorted, such as by stock symbol and timestamp, and are good candidates for BLOCK_DICT. Long CHAR/VARCHAR columns are not good candidates for BLOCK_DICT encoding. CHAR and VARCHAR columns that contain 0x00 or 0xFF characters should not be encoded with BLOCK_DICT. Also, BINARY/VARBINARY columns do not support BLOCK_DICT encoding. The encoding CPU for BLOCK_DICT is significantly higher than for default encoding schemes. The maximum data expansion is eight percent (8%). ENCODING BLOCKDICT_COMP This encoding type is similar to BLOCK_DICT except that dictionary indexes are entropy coded. This encoding type requires significantly more CPU time to encode and decode and has a poorer worst-case performance. However, if the distribution of values is extremely skewed, using BLOCKDICT_COMP encoding can lead to space savings. HP Vertica Analytic Database (7.0.x) Page 1053 of 1539 SQL Reference Manual SQL Statements ENCODING COMMONDELTA_COMP This compression scheme builds a dictionary of all the deltas in the block and then stores indexes into the delta dictionary using entropy coding. This scheme is ideal for sorted FLOAT and INTEGER-based (DATE/TIME/TIMESTAMP/INTERVAL) data columns with predictable sequences and only the occasional sequence breaks, such as timestamps recorded at periodic intervals or primary keys. For example, the following sequence compresses well: 300, 600, 900, 1200, 1500, 600, 1200, 1800, 2400. The following sequence does not compress well: 1, 3, 6, 10, 15, 21, 28, 36, 45, 55. If the delta distribution is excellent, columns can be stored in less than one bit per row. However, this scheme is very CPU intensive. If you use this scheme on data with arbitrary deltas, it can lead to significant data expansion. ENCODING DELTARANGE_COMP This compression scheme is primarily used for floating-point data, and it stores each value as a delta from the previous one. This scheme is ideal for many-valued FLOAT columns that are either sorted or confined to a range. Do not use this scheme for unsorted columns that contain NULL values, as the storage cost for representing a NULL value is high. This scheme has a high cost for both compression and decompression. To determine if DELTARANGE_COMP is suitable for a particular set of data, compare it to other schemes. Be sure to use the same sort order as the projection, and select sample data that will be stored consecutively in the database. ENCODING DELTAVAL For INTEGER and DATE/TIME/TIMESTAMP/INTERVAL columns, data is recorded as a difference from the smallest value in the data block. This encoding has no effect on other data types. DELTAVAL is best used for many-valued, unsorted integer or integer-based columns. The CPU requirements for this encoding type are minimal, and the data never expands. ENCODING GCDDELTA For INTEGER and DATE/TIME/TIMESTAMP/INTERVAL columns, and NUMERIC columns with 18 or fewer digits, data is recorded as the difference from the smallest value in the data block divided by the greatest common divisor (GCD) of all entries in the block. This encoding has no effect on other data types. ENCODING GCDDELTA is best used for many-valued, unsorted, integer columns or integerbased columns, when the values are a multiple of a common factor. For example, timestamps are stored internally in microseconds, so data that is only precise to the millisecond are all multiples of HP Vertica Analytic Database (7.0.x) Page 1054 of 1539 SQL Reference Manual SQL Statements 1000. The CPU requirements for decoding GCDDELTA encoding are minimal, and the data never expands, but GCDDELTA may take more encoding time than DELTAVAL. ENCODING RLE Run Length Encoding (RLE) replaces sequences (runs) of identical values with a single pair that contains the value and number of occurrences. Therefore, it is best used for low cardinality columns that are present in the ORDER BY clause of a projection. The HP Vertica execution engine processes RLE encoding run-by-run and the HP Vertica optimizer gives it preference. Use it only when the run length is large, such as when low-cardinality columns are sorted. The storage for RLE and AUTO encoding of CHAR/VARCHAR and BINARY/VARBINARY is always the same. ENCODING NONE Do not specify this value. It is obsolete and exists only for backwards compatibility. The result of ENCODING NONE is the same as ENCODING AUTO except when applied to CHAR and VARCHAR columns. Using ENCODING NONE on these columns increases space usage, increases processing time, and leads to problems if 0x00 or 0xFF characters are present in the data. Hash-Segmentation-Clause Allows you to segment a projection based on a built-in hash function. The built-in hash function provides even data distribution across some or all nodes in a cluster, resulting in optimal query execution. Note: Hash segmentation is the preferred method of segmentation. The Database Designer uses hash segmentation by default. Syntax SEGMENTED BY expression { ALL NODES [ OFFSET offset ] | NODES node [ ,... ] } HP Vertica Analytic Database (7.0.x) Page 1055 of 1539 SQL Reference Manual SQL Statements Parameters SEGMENTED BY expression Can be a general SQL expression. However, HP recommends using the built-in HASH or MODULARHASH functions, specifying table columns as arguments. If you specify only a column name, HP Vertica gives a warning. Choose columns that have a large number of unique data values and acceptable skew in their data distribution. Primary key columns that meet the criteria could be an excellent choice for hash segmentation. ALL NODES Automatically distributes data evenly across all nodes at the time the CREATE PROJECTION statement is run. The ordering of the nodes is fixed. OFFSET offset [Optional.] An offset value indicating the node on which to start the segmentation distribution. Omitting the OFFSET clause is equivalent to OFFSET 0. The offset is an integer value, relative to 0, based on all available nodes when using the ALL NODES parameter. See example below. NODES node Specifies a subset of the nodes in the cluster over which to distribute the data. You can use a specific node only once in any projection. For a list of the nodes in a database, use the View Database command in the Administration Tools. [ ,... ] Notes l CREATE PROJECTION accepts the deprecated syntax SITES node for compatibility with previous releases. l You must use the table column names in the expression, not the new projection column names. l An elastic projection (a segmented projection created when Elastic Cluster is enabled) created with a modularhash segmentation expression uses hash instead. l To use a SEGMENTED BY expression other than HASH or MODULARHASH, the following restrictions apply: n All leaf expressions must be either constants or column-references to a column in the SELECT list of the CREATE PROJECTION command. n Aggregate functions are not allowed. n The expression must return the same value over the life of the database. n The expression must return non-negative INTEGER values in the range 0 <= x < 263 (two to the sixty-third power or 2^63), and values are generally distributed uniformly over that range. HP Vertica Analytic Database (7.0.x) Page 1056 of 1539 SQL Reference Manual SQL Statements n If expression produces a value outside of the expected range (a negative value for example), no error occurs, and the row is added to the first segment of the projection. Examples => CREATE PROJECTION ... SEGMENTED BY HASH(C1,C2) ALL NODES; => CREATE PROJECTION ... SEGMENTED BY HASH(C1,C2) ALL NODES OFFSET 1; The example produces two hash-segmented buddy projections that form part of a K-Safe design. The projections can use different sort orders. => CREATE PROJECTION fact_ts_2 ( f_price, f_cid, f_tid, f_cost, f_date) AS ( SELECT price, cid, tid, cost, dwdate FROM fact) SEGMENTED BY MODULARHASH(dwdate) ALL NODES OFFSET 2; See Also l HASH l MODULARHASH CREATE RESOURCE POOL Creates a resource pool. Syntax CREATE RESOURCE POOL pool-name ... [ MEMORYSIZE {'sizeUnits' |DEFAULT }] ... [ MAXMEMORYSIZE {'sizeUnits' | NONE |DEFAULT }] ... [ EXECUTIONPARALLELISM {int | AUTO | DEFAULT} ] ... [ PRIORITY {integer |DEFAULT}] ... [ RUNTIMEPRIORITY { HIGH | MEDIUM | LOW |DEFAULT} ] ... [ RUNTIMEPRIORITYTHRESHOLD { integer |DEFAULT }] ... [ QUEUETIMEOUT {integer | NONE |DEFAULT}] ... [ PLANNEDCONCURRENCY {integer | NONE | DEFAULT |AUTO }] ... [ MAXCONCURRENCY {integer| NONE |DEFAULT }] ... [ RUNTIMECAP {interval | NONE | DEFAULT} ] ... [ SINGLEINITIATOR { bool | DEFAULT }] ... [ CPUAFFINITYSET { 'cpuIndex' | 'cpuIndex list' | 'integer percentage' | NONE | DEFAULT } ] ... [ CPUAFFINITYMODE { SHARED | EXCLUSIVE | ANY | DEFAULT } ] HP Vertica Analytic Database (7.0.x) Page 1057 of 1539 SQL Reference Manual SQL Statements Parameters Note: If you specify DEFAULT for any parameter when creating a resource pool, HP Vertica uses the default value for the user-defined pool, stored in the RESOURCE_POOL_ DEFAULTS table. pool-name Specifies the name of the resource pool to create. MEMORYSIZE 'sizeUnits' [Default 0%] Amount of memory allocated to the resource pool. See also MAXMEMORYSIZE parameter. Units can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case, size must be 0-100.). l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes Note: This parameter refers to memory allocated to this pool per node and not across the whole cluster. The default of 0% means that the pool has no memory allocated to it and must exclusively borrow from the GENERAL pool. HP Vertica Analytic Database (7.0.x) Page 1058 of 1539 SQL Reference Manual SQL Statements MAXMEMORYSIZE'sizeUnits' | NONE [Default unlimited] Maximum size the resource pool could grow by borrowing memory from the GENERAL pool. See BuiltIn Pools for a discussion on how resource pools interact with the GENERAL pool. Units can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case, size must be 0-100). This notation has special meaning for the GENERAL pool, described in Notes below. l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes If MAXMEMORYSIZE NONE is specified, there is no upper limit. Note: The MAXMEMORYSIZE parameter refers to the maximum memory borrowed by this pool per node and not across the whole cluster. The default of unlimited means that the pool can borrow as much memory from GENERAL pool as is available. EXECUTIONPARALLELISM [Default: AUTO] Limits the number of threads used to process any single query issued in this resource pool. When set to AUTO, HP Vertica sets this value based on the number of cores, available memory, and amount of data in the system. Unless data is limited, or the amount of data is very small, HP Vertica sets this value to the number of cores on the node. Reducing this value increases the throughput of short queries issued in the pool, especially if the queries are executed concurrently. If you choose to set this parameter manually, set it to a value between 1 and the number of cores. PRIORITY HP Vertica Analytic Database (7.0.x) [Default 0] An integer that represents priority of queries in this pool, when they compete for resources in the GENERAL pool. Higher numbers denote higher priority. Page 1059 of 1539 SQL Reference Manual SQL Statements RUNTIMEPRIORITY Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to queries already running in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. [Default: Medium] RUNTIMEPRIORITYTHRESHOLD [Default 2] Specifies a time limit (in seconds) by which a query must finish before the Resource Manager assigns to it the RUNTIMEPRIORITY of the resource pool. All queries begin runnng at a HIGH priority. When a query's duration exceeds this threshold, it is assigned the RUNTIMEPRIORITY of the resource pool. QUEUETIMEOUT HP Vertica Analytic Database (7.0.x) [Default: 300 seconds] An integer, in seconds, that represents the maximum amount of time the request is allowed to wait for resources to become available before being rejected. If set to NONE, the request can be queued for an unlimited amount of time. Page 1060 of 1539 SQL Reference Manual SQL Statements PLANNEDCONCURRENCY [Default: AUTO] Integer that represents the typical number of queries running concurrently in the system. When set to AUTO, this value is calculated automatically at query runtime. HP Vertica sets this parameter to the lower of these two calculations: l Number of cores l Memory/2GB When this parameter is set to AUTO, HP Vertica will never set it to a value less than 4. HP Vertica advises changing this value only after evaluating performance over a period of time. Notes: l This is a cluster-wide maximum and not a per-node limit. l For clusters where the number of cores differs on different nodes, AUTO can apply differently on each node. Distributed queries run like the minimal effective planned concurrency. Single node queries run with the planned concurrency of the initiator. l If you created or upgraded your database in 4.0 or 4.1, the PLANNEDCONCURRENCY setting on the GENERAL pool defaults to a too-small value for machines with large numbers of cores. To adjust to a more appropriate value: => ALTER RESOURCE POOL general PLANNEDCONCURRENCY <#cores>; You need to set this parameter only if you created a database before 4.1, patchset 1. MAXCONCURRENCY [Default unlimited] An integer that represents the maximum number of concurrent execution slots available to the resource pool. If MAXCONCURRENCY NONE is specified, there is no limit. Note: This is a cluster-wide maximum and not a per-node limit. HP Vertica Analytic Database (7.0.x) Page 1061 of 1539 SQL Reference Manual SQL Statements RUNTIMECAP [Default: NONE] Sets the maximum amount of time any query on the pool can execute. Set RUNTIMECAP using interval, such as '1 minute' or '100 seconds' (see Interval Values for details). This value cannot exceed one year. Setting this value to NONE specifies that there is no time limit on queries running on the pool. If the user or session also has a RUNTIMECAP, the shorter limit applies. SINGLEINITIATOR [Default: false] This parameter is included for backwards compatibility only. Do not change the value. HP Vertica Analytic Database (7.0.x) Page 1062 of 1539 SQL Reference Manual SQL Statements CPUAFFINITYSET [Default none] The set of CPUs on which queries associated with this pool are executed. Can only be used with userdefined resource pools (is_internal = f). Note: If you are changing the CPUAFFINITYSET from the default value (NONE), then you must also specify the CPUAFFINITYMODE at the same time. For example, when creating a new resource pool, or altering an existing resource pool that has a CPUAFFINITYSET that is not defined (or NONE), then specify CPUAFFINITYMODE to a supported mode for the set: CREATE RESOURCE POOL load CPUAFFINITYSET '25%' CPUAFFINITYMODE SHARED For this setting, CPU numbering is defined by the number of CPUs in the system based on a 0 index. You can obtain the number of CPUs on the system with the command: lscpu | grep "^CPU(s)" For example, if the above command returned: CPU(s): 8, then 0–7 are valid CPU indexes for this parameter. Note: HP Vertica is limited to 1024 CPUs per node. Value of this parameter can be one of the following: l 'cpuIndex'—Index of a specific CPU on which to run the queries for this pool. For example '3'. Queries in this pool are not run on any other CPUs besides the CPU defined. l 'cpuIndex list'—List of CPUs on which to run the queries for this pool. CPU indexes can be comma-separated for non-continous indexes, or use the '-' character for continuous CPU indexes. For example, '0,2–4' is a CPU index list containing CPU 0, CPU 2, CPU 3, and CPU 4. Queries in this pool are not run on any other CPUs besides the CPUs defined. Note: The cpuIndex must be unique across all resource pools if using a CPUAFFINITYMODE of exclusive. the cpuIndex does not need to be unqiue l HP Vertica Analytic Database (7.0.x) 'integer percentage'—Percentage of all available CPUs to use for this query. For example '50%' uses up to half of the Page 1063 of 1539 SQL Reference Manual SQL Statements available CPUs that are not reserved in other resource pools (with EXCLUSIVE affinity) for queries in this pool. Note that you must define this setting in whole percentages and that HP Vertica rounds the percentages down to account for whole CPU units. For example, a '20%' setting on an 8 CPU system is rounded down to 12.5% actual CPU percentage. (1/8 = 12.5% 2/8 - 25%). In a 16 CPU system, the setting is rounded down to 18.75% (3/16 = 18.75%, 4/16 = 25%). l NONE—Set no CPU affinity for this resource pool. The queries associated with this pool are executed on any CPU. l DEFAULT—Same as NONE. Important: CPU affinity settings apply to all nodes in the cluster. CPU counts must be identical on all nodes in the cluster. HP Vertica Analytic Database (7.0.x) Page 1064 of 1539 SQL Reference Manual SQL Statements CPUAFFINITYMODE [Default any] The mode in which CPU affinity operates for this resource pool. Can be one of: l SHARED—Queries run in this pool are constrained to run only on CPUs defined in CPUAFFINITYSET, but other HP Vertica resource pools can also run queries that utilize the same CPUs. l EXCLUSIVE—The CPUs defined in CPUAFFINITYSET are exclusively assigned to this resource pool. Other HP Vertica resource pools are unable to use the CPUs. In the case that CPUAFFINITYSET is set as a percentage, then that percentage of CPU resources available to HP Vertica is assigned solely for this resource pool. l ANY—Queries can be run on any CPU. If CPUAFFINITYSET is set to a non-default value, and you then set CPUAFFINITYMODE to ANY, then the CPUAFFINITYSET is removed (set to NONE) by HP Vertica, since the ANY mode is only valid for the NONE set. l DEFAULT—Same as ANY. Note: Important! CPU affinity settings apply to all nodes in the cluster. CPU counts must be identical on all nodes in the cluster. Permissions Must be a superuser to create a resource pool. Notes l Resource pool names are subject to the same rules as HP Vertica Identifiers. Built-in pool names cannot be used for user-defined pools. l New resource pools can be created or altered without shutting down the system. l When a new pool is created (or its size altered), MEMORYSIZE amount of memory is taken out of the GENERAL pool. If the GENERAL pool does not currently have sufficient memory to create the pool due to existing queries being processed, a request is made to the system to create a pool as soon as resources become available. The pool is created immediately and memory is moved to the pool as it becomes available. Such memory movement has higher priority than any query. HP Vertica Analytic Database (7.0.x) Page 1065 of 1539 SQL Reference Manual SQL Statements The pool is in operation as soon as the specified amount of memory becomes available. You can monitor whether the ALTER has been completed in the V_MONITOR.RESOURCE_POOL_STATUS system table. l Under normal operation, MEMORYSIZE is required to be less than MAXMEMORYSIZE and an error is returned during CREATE/ALTER operations if this size limit is violated. However, under some circumstances where the node specification changes by addition/removal of memory, or if the database is moved to a different cluster, this invariant could be violated. In this case, MAXMEMORYSIZE is increased to MEMORYSIZE. l If two pools have the same PRIORITY, their requests are allowed to borrow from the GENERAL pool in order of arrival. See Guidelines for Setting Pool Parameters in the Administrator's Guide for details about setting these parameters. Examples The following command creates a resource pool with MEMORYSIZE of 1800MB to ensure that the CEO query has adequate memory reserved for it: => CREATE RESOURCE POOL ceo_pool MEMORYSIZE '1800M' PRIORITY 10; CREATE RESOURCE POOL dbadmin=> \x Expanded display is on. dbadmin=> SELECT * FROM resource_pools WHERE name = 'ceo_pool'; -[ RECORD 1 ]------------+-----------------pool_id | 45035996273733364 name | ceo_pool is_internal | f memorysize | 1800M maxmemorysize | executionparallelism | AUTO priority | 10 runtimepriority | MEDIUM runtimeprioritythreshold | 2 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | f cpuaffinityset | cpuaffinitymode | ANY Assuming the CEO report user already exists, associate this user with the above resource pool using ALTER USER statement. => GRANT USAGE ON RESOURCE POOL ceo_pool to ceo_user;GRANT PRIVILEGE => ALTER USER ceo_user RESOURCE POOL ceo_pool; ALTER USER Issue the following command to confirm that the ceo_user is associated with the ceo_pool: HP Vertica Analytic Database (7.0.x) Page 1066 of 1539 SQL Reference Manual SQL Statements => SELECT * FROM users WHERE user_name ='ceo_user'; -[ RECORD 1 ]-----+-------------------------------------------------user_id | 45035996273733402 user_name | ceo_user is_super_user | f profile_name | default is_locked | f lock_time | resource_pool | ceo_pool memory_cap_kb | unlimited temp_space_cap_kb | unlimited run_time_cap | unlimited all_roles | default_roles | search_path | "$user", public, v_catalog, v_monitor, v_internal See Also l ALTER RESOURCE POOL l CREATE USER l DROP RESOURCE POOL l SET SESSION RESOURCE_POOL SET SESSION MEMORYCAP l l Built-In Pools HP Vertica is preconfigured with built-in pools for various system tasks. The built-in pools can be reconfigured to suit your usage. The following sections describe the purpose of built-in pools and the default settings. Built-InSettings Pool HP Vertica Analytic Database (7.0.x) Page 1067 of 1539 SQL Reference Manual SQL Statements GENERAL A special, catch-all pool used to answer requests that have no specific resource pool associated with them. Any memory left over after memory has been allocated to all other pools is automatically allocated to the GENERAL pool. The MEMORYSIZE parameter of the GENERAL pool is undefined (variable), however, the GENERAL pool must be at least 1GB in size and cannot be smaller than 25% of the memory in the system. The MAXMEMORYSIZE parameter of the GENERAL pool has special meaning; when set as a % value it represents the percent of total physical RAM on the machine that the Resource Manager can use for queries. By default, it is set to 95%. The GENERAL.MAXMEMORYSIZE governs the total amount of RAM that the Resource Manager can use for queries, regardless of whether it is set to a percent or to a specific value (for example, '10GB') Any user-defined pool can “borrow” memory from the GENERAL pool to satisfy requests that need extra memory until the MAXMEMORYSIZE parameter of that pool is reached. If the pool is configured to have MEMORYSIZE equal to MAXMEMORYSIZE, it cannot borrow any memory from the GENERAL pool and is said to be a standalone resource pool. When multiple pools request memory from the GENERAL pool, they are granted access to general pool memory according to their priority setting. In this manner, the GENERAL pool provides some elasticity to account for point-in-time deviations from normal usage of individual resource pools. SYSQUERY The pool that runs queries against system monitoring and catalog tables. The SYSQUERY pool reserves resources for system table queries so that they are never blocked by contention for available resources. SYSDATA The pool reserved for temporary storage of intermediate results of queries against system monitoring and catalog tables. If the SYSDATA pool size is too low, HP Vertica cannot execute queries for large system tables or during high concurrent access to system tables. WOSDATA The Write Optimized Store (WOS) resource pool. Data loads to the WOS automatically spill to the ROS once it exceeds a certain amount of WOS usage; the PLANNEDCONCURRENCY parameter of the WOS is used to determine this spill threshold. For instance, if PLANNEDCONCURRENCY of the WOSDATA pool is set to 4, once a load has occupied one quarter of the WOS, it spills to the ROS. See Scenario: Tuning for Continuous Load and Query in the Administrator's Guide. TM The Tuple Mover (TM) pool. You can use the MAXCONCURRENCY parameter for the TM pool to allow more than one concurrent TM operation to occur. See Scenario: Tuning Tuple Mover Pool Settings in the Administrator's Guide. RECOVERY The pool used by queries issued when recovering another node of the database. The MAXCONCURRENCY parameter is used to determine how many concurrent recovery threads to use. You can use the PLANNEDCONCURRENCY parameter (by default, set to twice the MAXCONCURRENCY) to tune how to apportion memory to recovery queries. See Scenario: Tuning for Recovery in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1068 of 1539 SQL Reference Manual SQL Statements REFRESH The pool used by queries issued by the PROJECTION_REFRESHES operations. Refresh does not currently use multiple concurrent threads; thus, changes to the MAXCONCURRENCY values have no effect. See Scenario: Tuning for Refresh in the Administrator's Guide. DBD The Database Designer pool, used to control resource usage for the DBD internal processing. Since the Database Designer is such a resource-intensive process, the DBD pool is configured with a zero (0) second QUEUETIMEOUT value. Whenever resources are under pressure, this timeout setting causes the DBD to time out immediately, and not be queued to run later. The Database Designer then requests the user to run the designer later, when resources are more available. HP recommends that you do not reconfigure this pool. JVM The JVM pool controls Java Virtual Machine resources used by Java User Defined Extensions. When a Java UDx starts the JVM, it draws resources from the those specified in the JVM resource pool. HP Vertica does not reserve memory in advance for the JVM pool. When needed, the pool can expand to 10% of physical memory or 2 GB of memory, whichever is smaller. If you are buffering large amounts of data, you may need to increase the size of the JVM resource pool. You can adjust the size of your JVM resource pool by changing its configuration settings. Unlike other resource pools, the JVM resource pool does not release resources until a session is closed. Upgrade From Earlier Versions of HP Vertica For a database being upgraded from earlier versions of, HP Vertica automatically translates most existing parameter values into the new resource pool settings. The PLANNEDCONCURRENCY and MAXCONCURRENCY parameters of the resource pools must be manually tuned per Guidelines for Setting Pool Parameters in the Administrator's Guide. See Also l RESOURCE_ACQUISITIONS Built-In Pool Configuration The following tables list the default configuration setting values of built-in resource pools for a new database and for a database upgraded from prior versions of HP Vertica. Note: Some of the built-in resource pool parameter values have restrictions, which are noted in the tables. HP Vertica Analytic Database (7.0.x) Page 1069 of 1539 SQL Reference Manual SQL Statements GENERAL Setting Value MEMORYSIZE N/A (cannot be set) MAXMEMORYSIZE Default: 95% of Total RAM on the node. Setting this value to 100% generates warnings that swapping could result. MAXMEMORYSIZE has the following restrictions: l Must be 1GB or greater. l Must not be less than 25% of total system RAM. PRIORITY 0 RUNTIMEPRIORITY Medium RUNTIMEPRIORITYTHRESHOLD 2 QUEUETIMEOUT 300 RUNTIMECAP NONE HP Vertica Analytic Database (7.0.x) Page 1070 of 1539 SQL Reference Manual SQL Statements Setting Value PLANNEDCONCURRENCY [Default: Auto] An integer that represents the number of concurrent queries that are normally expected to be running against the resource pool. When set to the default value of AUTO, HP Vertica automatically sets PLANNEDCONCURRENCY at query runtime, choosing the lower of these two values: l # of cores l Memory/2BG The value 4 is the minimum value for PLANNEDCONCURRENCY. HP Vertica advises changing this value only after evaluating performance over a period of time. Notes: l See Best Practices For Workload Management in the Administrator's Guide for guidance on how to tune. l The PLANNEDCONCURRENCY setting for the GENERAL pool defaults to a too-small value for machines with large numbers of cores. To adjust to a more appropriate value: => ALTER RESOURCE POOL general PLANNEDCONCURRENCY <#cores>; See Guidelines for Setting Pool Parameters in the Administrator's Guide MAXCONCURRENCY Unlimited Restrictions: Setting to 0 generates warnings that no system queries may be able to run in the system. SINGLEINITIATOR False. This parameter is included for backwards compatibility only. Do not change the value. SYSQUERY Setting Value MEMORYSIZE 64M Restrictions: Setting to <20M generates warnings because it could prevent system queries from running and make problem diagnosis difficult. MAXMEMORYSIZE Unlimited HP Vertica Analytic Database (7.0.x) Page 1071 of 1539 SQL Reference Manual SQL Statements Setting Value EXECUTIONPARALLELISM AUTO PRIORITY 110 RUNTIMEPRIORITY HIGH RUNTIMEPRIORITYTHRESHOLD 0 QUEUETIMEOUT 300 RUNTIMECAP NONE. PLANNEDCONCURRENCY See GENERAL MAXCONCURRENCY Unlimited Restrictions: Setting to 0 generates warnings that no system queries may be able to run in the system. SINGLEINITIATOR False. This parameter is included for backwards compatibility only. Do not change the value. SYSDATA Setting Value MEMORYSIZE 100m MAXMEMORYSIZE 10% Restriction: Setting To <4m generates warnings that no system queries may be able to run in the system. EXECUTIONPARALLELISM N/A (cannot be set) PRIORITY N/A (cannot be set) RUNTIMEPRIORITY N/A (cannot be set) RUNTIMEPRIORITYTHRESHOLD N/A (cannot be set) QUEUETIMEOUT N/A (cannot be set) RUNTIMECAP N/A (cannot be set) PLANNEDCONCURRENCY N/A (cannot be set) MAXCONCURRENCY N/A (cannot be set) SINGLEINITIATOR N/A (cannot be set) HP Vertica Analytic Database (7.0.x) Page 1072 of 1539 SQL Reference Manual SQL Statements WOSDATA Setting Value MEMORYSIZE 0% MAXMEMORYSIZE 25% or 2GB, whichever is less. EXECUTIONPARALLELISM N/A (cannot be set) PRIORITY N/A (cannot be set) RUNTIMEPRIORITY N/A (cannot be set) RUNTIMEPRIORITYTHRESHOLD N/A (cannot be set) QUEUETIMEOUT N/A (cannot be set) RUNTIMECAP NONE PLANNEDCONCURRENCY 2*# nodes MAXCONCURRENCY N/A (cannot be set) SINGLEINITIATOR N/A (cannot be set) TM Setting Value MEMORYSIZE 100M MAXMEMORYSIZE Unlimited EXECUTIONPARALLELISM AUTO PRIORITY 105 RUNTIMEPRIORITY MEDIUM RUNTIMEPRIORITYTHRESHOLD 60 QUEUETIMEOUT 300 RUNTIMECAP NONE PLANNEDCONCURRENCY 1 MAXCONCURRENCY 2 Restrictions: Cannot set to 0 or NONE (unlimited) SINGLEINITIATOR True. This parameter is included for backwards compatibility. Do not change the value. HP Vertica Analytic Database (7.0.x) Page 1073 of 1539 SQL Reference Manual SQL Statements REFRESH Setting Value MEMORYSIZE 0% MAXMEMORYSIZE Unlimited EXECUTIONPARALLELISM AUTO PRIORITY -10 RUNTIMEPRIORITY MEDIUM RUNTIMEPRIORITYTHRESHOLD 60 QUEUETIMEOUT 300 RUNTIMECAP NONE PLANNEDCONCURRENCY 4 MAXCONCURRENCY Unlimited Restrictions: cannot set to 0 SINGLEINITIATOR True. This parameter is included for backwards compatibility. Do not change the value. RECOVERY Setting Value MEMORYSIZE 0% MAXMEMORYSIZE Unlimited Restrictions: cannot set to < 25%. EXECUTIONPARALLELISM AUTO PRIORITY 107 RUNTIMEPRIORITY MEDIUM RUNTIMEPRIORITYTHRESHOLD 60 QUEUETIMEOUT 300 RUNTIMECAP NONE PLANNEDCONCURRENCY Twice MAXCONCURRENCY HP Vertica Analytic Database (7.0.x) Page 1074 of 1539 SQL Reference Manual SQL Statements Setting Value MAXCONCURRENCY (# of cores / 2) + 1 Restrictions: Cannot set to 0 or NONE (unlimited) SINGLEINITIATOR True. This parameter is included for backwards compatibility. Do not change the value. DBD Setting Value MEMORYSIZE 0% MAXMEMORYSIZE Unlimited EXECUTIONPARALLELISM AUTO PRIORITY 0 RUNTIMEPRIORITY MEDIUM RUNTIMEPRIORITYTHRESHOLD 0 QUEUETIMEOUT 0 RUNTIMECAP NONE PLANNEDCONCURRENCY See GENERAL MAXCONCURRENCY Unlimited SINGLEINITIATOR False. This parameter is included for backwards compatibility. Do not change the value. JVM Setting Value MEMORYSIZE 0% MAXMEMORYSIZE 10% of memory or 2 GB, whichever is smaller EXECUTIONPARALLELISM AUTO PRIORITY 0 RUNTIMEPRIORITY MEDIUM RUNTIMEPRIORITYTHRESHOLD 2 HP Vertica Analytic Database (7.0.x) Page 1075 of 1539 SQL Reference Manual SQL Statements Setting Value QUEUETIMEOUT 300 RUNTIMECAP NONE PLANNEDCONCURRENCY AUTO MAXCONCURRENCY N/A (cannot be set) SINGLEINITIATOR FALSE. This parameter is included for backwards compatibility. Do not change the value. CREATE ROLE Creates a new, empty role. You must then add permissions to the role using one of the GRANT statements. Syntax CREATE ROLE role; Parameters role The name for the new role. Permissions Must be a superuser to create a role. See Also l ALTER ROLE RENAME l DROP ROLE CREATE SCHEMA Defines a new schema. Syntax CREATE SCHEMA [ IF NOT EXISTS ] [db-name.]schema [ AUTHORIZATION user-name ] HP Vertica Analytic Database (7.0.x) Page 1076 of 1539 SQL Reference Manual SQL Statements Parameters [ IF NOT EXISTS ] [Optional] Determines whether the statement generates a NOTICE message or an ERROR if -name exists. Using IF NOT EXISTS generates a NOTICE if the specified object exists. Omitting the clause generates an error if -name exists. Regardless of whether you use IF NOT EXISTS, HP Vertica does not create a new object if -name exists. For more information, see also ON_ ERROR_STOP. [db-name.] [Optional] Specifies the current database name. Using a database name prefix is optional, and does not affect the command in any way. You must be connected to the specified database. schema Specifies the name of the schema to create. AUTHORIZATION user-name Assigns ownership of the schema to a user. If a user name is not provided, the user who creates the schema is assigned ownership. Only a Superuser is allowed to create a schema that is owned by a different user. Privileges To create a schema, the user must either be a superuser or have CREATE privilege for the database. See GRANT (Database). Optionally, CREATE SCHEMA could include the following sub-statements to create tables within the schema: l CREATE TABLE l GRANT With the following exceptions, these sub-statements are treated as if they have been entered as individual commands after the CREATE SCHEMA statement has completed: l If the AUTHORIZATION statement is used, all tables are owned by the specified user. l The CREATE SCHEMA statement and all its associated sub-statements are completed as one transaction. If any of the statements fail, the entire CREATE SCHEMA statement is rolled back. Examples The following example creates a schema named s1 with no objects. => CREATE SCHEMA s1; HP Vertica Analytic Database (7.0.x) Page 1077 of 1539 SQL Reference Manual SQL Statements The following command creates schema s2 if it does not already exist: => CREATE SCHEMA IF NOT EXISTS schema2; If the schema already exists, HP Vertica returns a rollback message: => CREATE SCHEMA IF NOT EXISTS schema2; NOTICE 4214: Object "schema2" already exists; nothing was done The following series of commands create a schema named s1 with a table named t1 and grants Fred and Aniket access to all existing tables and ALL privileges on table t1: => CREATE SCHEMA s1;=> CREATE TABLE t1 (c INT); => GRANT USAGE ON SCHEMA s1 TO Fred, Aniket; => GRANT ALL ON TABLE t1 TO Fred, Aniket; See Also l ALTER SCHEMA l SET SEARCH_PATH l DROP SCHEMA CREATE SEQUENCE Defines a new named sequence number generator object. Use sequences or auto-incrementing columns for primary key columns. For example, to generate only even numbers in a sequence, specify a start value of 2, and increment the sequence by 2. For more information see Using Sequences in the Administrator's Guide. Sequences guarantee uniqueness and avoid constraint enforcement problems and their associated overhead. Syntax CREATE SEQUENCE [[db-name.]schema.]sequence_name ... [ INCREMENT [ BY ] positive_or_negative ] ... [ MINVALUE minvalue | NO MINVALUE ] ... [ MAXVALUE maxvalue | NO MAXVALUE ] ... [ START [ WITH ] start ] ... [ CACHE cache ] ... [ CYCLE | NO CYCLE ] HP Vertica Analytic Database (7.0.x) Page 1078 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). sequence_name The name (optionally schema-qualified) of the sequence to create. The name must be unique among sequences, tables, projections, and views. If you do not specify a sequence_name, HP Vertica assigns an internallygenerated name in the current schema. INCREMENT [BY] positive_or_negative Specifies how much to increment (or decrement) the current sequence value. A positive value creates an ascending sequence; a negative value makes a descending sequence. The default value is 1. MINVALUE minvalue | NO MINVALUE Determines the minimum value a sequence can generate. If you do not specify this clause, or you specify NO MINVALUE, default values are used. The defaults are 1 and -263-1 for ascending and descending sequences, respectively. MAXVALUE maxvalue | NO MAXVALUE Determines the maximum value for the sequence. If this clause is not supplied or you specify NO MAXVALUE, default values are used. The defaults are 263-1 and -1 for ascending and descending sequences, respectively. START [WITH] startvalue Specifies a specific start value of the sequence (startvalue). The default values are minvalue for ascending sequences and maxvalue for descending sequences. Note: The [WITH] option is ignored and has no effect. HP Vertica Analytic Database (7.0.x) Page 1079 of 1539 SQL Reference Manual SQL Statements CACHE cache Specifies how many sequence numbers are preallocated and stored in memory for faster access. The default is 250,000 with a minimum value of 1. Specifying a cache value of 1 indicates that only one value can be generated at a time, since no cache is assigned. Notes: CYCLE | NO CYCLE l If you use the CACHE clause when creating a sequence, each session has its own cache on each HP Vertica node. l Sequences that specify a cache size that is insufficient for the number of sequence values could cause a performance degradation. Allows the sequence to restart when an ascending or descending sequence reaches the maxvalue or minvalue. If the sequence reaches a limit, the next number generated is the minvalue or maxvalue, respectively. If you specify NO CYCLE when creating a sequence, any calls to NEXTVAL after the sequence reaches its maximum/minimum value return an error. NO CYCLE is the default. Permissions To create a sequence, the user must have CREATE privilege on the schema to contain the sequence. Only the owner and superusers can initially access the sequence. All other users must be granted access to the sequence by a superuser or the owner. To create a table with a sequence, the user must have SELECT privilege on the sequence and USAGE privilege on the schema that contains the sequence. Note: Referencing a named sequence in a CREATE TABLE statement requires SELECT privilege on the sequence object and USAGE privilege on the schema of the named sequence. Incrementing and Obtaining Sequence Values After creating a sequence, use the NEXTVAL function to create a cache in which the sequence value is stored. Use the CURRVAL function to get the current sequence value. You cannot use NEXTVAL or CURRVAL to act on a sequence in a SELECT statement: l in a WHERE clause l in a GROUP BY or ORDER BY clause HP Vertica Analytic Database (7.0.x) Page 1080 of 1539 SQL Reference Manual SQL Statements l in a DISTINCT clause l along with a UNION l in a subquery Additionally, you cannot use NEXTVAL or CURRVAL to act on a sequence in: l a subquery of UPDATE or DELETE l a view You can use subqueries to work around some of these restrictions. For example, to use sequences with a DISTINCT clause: => SELECT t.col1, shift_allocation_seq.nextval SELECT DISTINCT col1 FROM av_temp1) t; FROM ( Removing a Sequence Use the DROP SEQUENCE function to remove a sequence. You cannot drop a sequence upon which other objects depend. Sequences used in a default expression of a column cannot be dropped until all references to the sequence are removed from the default expression. DROP SEQUENCE ... CASCADE is not supported. Examples The following example creates an ascending sequence called my_seq, starting at 100: dbt=> create sequence my_seq START 100; CREATE SEQUENCE After creating a sequence, you must call the NEXTVAL function at least once in a session to create a cache for the sequence and its initial value. Subsequently, use NEXTVAL to increment the sequence. Use the CURRVAL function to get the current value. The following NEXTVAL function instantiates the newly-created my_seq sequence and sets its first number: => SELECT NEXTVAL('my_seq'); nextval --------100 (1 row) If you call CURRVAL before NEXTVAL, the system returns an error: HP Vertica Analytic Database (7.0.x) Page 1081 of 1539 SQL Reference Manual SQL Statements dbt=> SELECT CURRVAL('my_seq'); ERROR 4700: Sequence my_seq has not been accessed in the session The following command returns the current value of this sequence. Since no other operations have been performed on the newly-created sequence, the function returns the expected value of 100: => SELECT CURRVAL('my_seq'); currval --------100 (1 row) The following command increments the sequence value: => SELECT NEXTVAL('my_seq'); nextval --------101 (1 row) Calling the CURRVAL again function returns only the current value: => SELECT CURRVAL('my_seq'); currval --------101 (1 row) The following example shows how to use the my_seq sequence in an INSERT statement. => CREATE TABLE customer ( lname VARCHAR(25), fname VARCHAR(25), membership_card INTEGER, id INTEGER ); => INSERT INTO customer VALUES ('Hawkins' ,'John', 072753, NEXTVAL('my_seq')); Now query the table you just created to confirm that the ID column has been incremented to 102: => SELECT * FROM customer; lname | fname | membership_card | id ---------+-------+-----------------+----Hawkins | John | 72753 | 102 (1 row) The following example shows how to use a sequence as the default value for an INSERT command: => CREATE TABLE customer2( HP Vertica Analytic Database (7.0.x) Page 1082 of 1539 SQL Reference Manual SQL Statements id INTEGER DEFAULT NEXTVAL('my_seq'), lname VARCHAR(25), fname VARCHAR(25), membership_card INTEGER ); => INSERT INTO customer2 VALUES (default,'Carr', 'Mary', 87432); Now query the table you just created. The ID column has been incremented again to 103: => SELECT * FROM customer2; id | lname | fname | membership_card -----+-------+-------+----------------103 | Carr | Mary | 87432 (1 row) The following example shows how to use NEXTVAL in a SELECT statement: => SELECT NEXTVAL('my_seq'), lname FROM customer2; NEXTVAL | lname ---------+------104 | Carr (1 row) As you can see, each time you call NEXTVAL(), the value increments. The CURRVAL() function returns the current value. See Also l ALTER SEQUENCE l Column-Constraint l CURRVAL l DROP SEQUENCE l GRANT (Sequence) NEXTVAL l l l CREATE SUBNET Identifies the subnet to which the nodes of an HP Vertica database belong. Use this statement when you want to configure import/export from a database to other HP Vertica clusters. HP Vertica Analytic Database (7.0.x) Page 1083 of 1539 SQL Reference Manual SQL Statements Syntax CREATE SUBNET subnet-name with 'subnet prefix' Parameters subnet-name The name you assign to the subnet. subnet prefix The routing prefix expressed in quad-dotted decimal representation. Refer to v_ monitor.network_interfaces system table to get the prefix for all available IP networks. You can then configure the database to use the subnet for import/export. (See Identify the Database or Node(s) used for Import/Export for more information.) Permissions Must be a superuser to create a subnet. CREATE TABLE Creates a table in the logical schema or an external table definition. Syntax CREATE TABLE [ IF NOT EXISTS ] [[db-name.]schema.]table-name { ... ( Column-Definition (table) [ , ... ] ) ... | [ table-constraint ( column_name, ... )] ... | [ column-name-list (create table) ] AS [COPY] [ [ AT EPOCH LATEST ] ... | [ AT TIME 'timestamp' ] ] [ /*+ direct */ ] query ... | [ LIKE [[db-name.]schema.]existing-table [ {INCLUDING | EXCLUDING} PROJECTIONS ] ] } ... [ ORDER BY table-column [ , ... ] ] ... [ ENCODED BY column-definition [ , ... ] ... [ Hash-Segmentation-Clause ... | UNSEGMENTED { NODE node | ALL NODES } ] ... [ KSAFE [k_num] ] ... [ PARTITION BY partition-clause ] HP Vertica Analytic Database (7.0.x) Page 1084 of 1539 SQL Reference Manual SQL Statements Parameters [ IF NOT EXISTS ] [Optional] Determines whether the statement generates a NOTICE message or an ERROR if -name exists. Using IF NOT EXISTS generates a NOTICE if the specified object exists. Omitting the clause generates an error if -name exists. Regardless of whether you use IF NOT EXISTS, HP Vertica does not create a new object if -name exists. For more information, see also ON_ERROR_STOP. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). If you do not specify a schema, the table is created in the default schema. table-name Identifies the name of the table to create. Schema-name specifies the schema where the table is created. If you omit schema-name, the new table is created in the first schema listed in the current search_path. column-definition Defines one or more columns. See Column-Definition (table). column-name-list Renames columns when creating a table from a query (CREATE TABLE AS SELECT). See column-name-list. AT EPOCH LATEST | AT TIME 'timestamp' Used with AS query to query historical data. You can specify AT EPOCH LATEST to include data from the latest committed DML transaction or specify a specific epoch based on its time stamp. Note: You cannot use either of these options when creating external tables. HP Vertica Analytic Database (7.0.x) Page 1085 of 1539 SQL Reference Manual SQL Statements /*+ direct */ Writes the data directly to disk (ROS) bypassing memory (WOS). HP Vertica accepts optional spaces before and after the plus (+) sign and the direct hint. Space characters between the opening /* or the closing */ are not permitted. The following directives are all acceptable: /*+direct*/ /* + direct*/ /*+ direct*/ /*+direct */ AS query Creates a new table from the results of a query and fills it with data from the query. For example: CREATE TABLE promo AS SELECT ... ; Column renaming is supported as part of the process: CREATE TABLE promo (name, address, ...) AS SELECT customer_nam e, customer_address ... ; The query table-column must be followed by the FROM clause to identify the table from which to copy the columns. See the example at the bottom of this topic as well as the SELECT statement. The AS clause is not supported for flex tables. If the query output has expressions other than simple columns (for example, constants, functions, etc) then you must either specify an alias for that expression, or list all columns in the column name list. Note: If any of the columns returned by query would result in a zero-width column, the column is automatically converted to a VARCHAR(80) column. For example, the following statement: CREATE TABLE example AS SELECT '' AS X; would attempt to create a table containing column X as a zerowidth VARCHAR. Instead, HP Vertica automatically converts this column to a VARCHAR(80) to prevent the creation of a zero-width VARCHAR column. HP Vertica requires variablewidth data type columns to be at least 1 character wide. HP Vertica Analytic Database (7.0.x) Page 1086 of 1539 SQL Reference Manual SQL Statements [LIKE existing-table [INCLUDING | EXCLUDING PR OJECTIONS]] Replicates an existing table to create a new table. The LIKE clause is not supported for flex tables. The optional INCLUDING PROJECTIONS clause creates the current and non-pre-join projections of the original table when you populate the new table. If the table has an associated storage policy, the associated policy is also replicated. As a DDL statement, EXCLUDING PROJECTIONS is the default value. Note: HP Vertica does not support using CREATE TABLE new_table LIKE table_exist INCLUDING PROJECTIONS if table_exist is a temporary table. For more information about using this option, see Creating a Table Like Another in the Administrator's Guide. [ ORDER BY table-column ] [Optional] Specifies the sort order for the superprojection that is automatically created for the table. Data is in ascending order only. If you do not specify the sort order, HP Vertica uses the order in which columns are specified in the column definition as the sort order for the projection. For example: ORDER BY col2, col1, col5 Note: You cannot use this option when creating external tables. ENCODED BY column-definit ion [CREATE TABLE AS query Only] This parameter is useful to specify the column encoding and/ or the access rank for specific columns in the query when a columndefinition is not used to rename columns for the table to be created. See Column-Definition (table) for examples. If you rename table columns when creating a table from a query, you can supply the encoding type and access rank in the column name list instead. Note: You cannot use this option when creating external tables. HP Vertica Analytic Database (7.0.x) Page 1087 of 1539 SQL Reference Manual SQL Statements hash-segmentation-clause [Optional] Lets you segment the superprojection based on a built-in hash function that provides even distribution of data across nodes, resulting in optimal query execution. See Hash-SegmentationClause. Note: You cannot use this option when creating external tables. Note: An elastic projection (a segmented projection created when Elastic Cluster is enabled) created with a modular hash segmentation expression uses hash instead. UNSEGMENTED{ NODE node | ALL NODES } [Optional] Lets you specify an unsegmented projection. The default for this parameter is to create an UNSEGMENTED projection on the initiator node. You can optionally use either of the following node specifications: n NODE node—Creates an unsegmented projection only on the specified node. Projections for small tables must be UNSEGMENTED. n ALL NODES—Automatically replicates the unsegmented projection on each node. To perform distributed query execution, HP Vertica requires an unsegmented copy of each small table superprojection on each node. Note: You cannot use this option when creating external tables. HP Vertica Analytic Database (7.0.x) Page 1088 of 1539 SQL Reference Manual SQL Statements KSAFE [ k ] [Optional] Specifies the K-safety level of the projection created for the table. Note: You cannot use this option when creating external tables. The integer k determines how many unsegmented or segmented buddy projections are created. The value must be greater than or equal to the current K-safety level of the database and less than the total number of nodes. If KSAFE or its value are not specified, the superprojection is created at the current system K-safety level. For example: K-SAFE 1 Note: When a hash-segmentation-clause is used with KSAFE, HP Vertica automatically creates k_num+1 buddy projections to meet the K-safety requirement. PARTITION BY partition-cl ause [Not supported for queries (CREATE TABLE AS SELECT)] l The partition clause must calculate a single non-null value for each row. Multiple columns can be referenced, but a single value must be returned for each row. l All leaf expressions must be either constants or columns of the table. l All other expressions must be functions and operators; aggregate functions and queries are not permitted in the expression. l SQL functions used in the partitioning expression must be immutable. Note: You cannot use this option when creating external tables. Permissions l To create a table, you must have CREATE privilege on the table schema. l To create a table with a named sequence, you must have SELECT privilege on the sequence object and USAGE privilege on the schema associated with the sequence. l Referencing a named sequence in a CREATE TABLE statement requires the following HP Vertica Analytic Database (7.0.x) Page 1089 of 1539 SQL Reference Manual SQL Statements privileges: l n SELECT privilege on sequence object n USAGE privilege on sequence schema To create a table with the LIKE clause, you must have owner permissions on the source table Automatic Projection Creation To get your database up and running quickly, HP Vertica automatically creates a default projection for each table created through the CREATE TABLE and CREATE TEMPORARY TABLE statements. Each projection created automatically (or manually) includes a base projection name prefix. You must use the projection prefix when altering or dropping a projection (ALTER PROJECTION RENAME, DROP PROJECTION). How you use the CREATE TABLE statement determines when the projection is created: l If you create a table without providing the projection-related clauses, HP Vertica automatically creates a superprojection for the table when you use an INSERT INTO or COPY statement to load data into the table for the first time. The projection is created in the same schema as the table. Once HP Vertica has created the projection, it loads the data. l If you use CREATE TABLE AS SELECT to create a table from the results of a query, the table is created first and a projection is created immediately after, using some of the properties of the underlying SELECT query. l (Advanced users only) If you use any of the following parameters, the default projection is created immediately upon table creation using the specified properties: n column-definition (ENCODING encoding-type and ACCESSRANK integer) n ORDER BY table-column n hash-segmentation-clause n UNSEGMENTED { NODE node | ALL NODES } n KSAFE Note: Before you define a superprojection in the above manner, read Creating Custom Designs in the Administrator's Guide. Partition Clauses Creating a table with a partition clause causes all projections anchored on that table to be partitioned according to the clause. For each partitioned projection, logically, there are as many HP Vertica Analytic Database (7.0.x) Page 1090 of 1539 SQL Reference Manual SQL Statements partitions as the number of unique values returned by the partitioned expression applied over the rows of the projection. All projections include a base projection name prefix, which HP Vertica adds automatically. To ensure a unique projection name, HP Vertica adds a version number within the name if necessary. You use projection names to drop or rename a projection. Note: Due to the impact on the number of ROS containers, explicit and implicit upper limits are imposed on the number of partitions a projection can have; these limits, however, are detected during the course of operation, such as during COPY. Creating a partitioned table does not necessarily force all data feeding into a table’s projection to be segmented immediately. Logically, the partition clause is applied after the segmented by clause. Partitioning specifies how data is organized at individual nodes in a cluster and after projection data is segmented; only then is the data partitioned at each node based on the criteria in the partitioning clause. SQL functions used in the partitioning expression must be immutable, which means they return the exact same value whenever they are invoked and independently of session or environment settings, such as LOCALE. For example, the TO_CHAR function is dependent on locale settings and cannot be used. The RANDOM function also produces different values on each invocation, so cannot be used. Data loaded with the COPY command is automatically partitioned according to the table's PARTITION BY clause. For more information, see "Restrictions on Partitioning Expressions" in Defining Partitions in the Administrator's Guide Examples The following example creates a table named Product_Dimension in the Retail schema. HP Vertica creates a default superprojection when data is loaded into the table: => CREATE TABLE Retail.Product_Dimension ( Product_Key integer NOT NULL, Product_Description varchar(128), SKU_Number char(32) NOT NULL, Category_Description char(32), Department_Description char(32) NOT NULL, Package_Type_Description char(32), Package_Size char(32), Fat_Content integer, Diet_Type char(32), Weight integer, Weight_Units_of_Measure char(32), Shelf_Width integer, Shelf_Height integer, Shelf_Depth integer ); HP Vertica Analytic Database (7.0.x) Page 1091 of 1539 SQL Reference Manual SQL Statements The following example creates a table named Employee_Dimension. HP Vertica creates its associated superprojection in the Public schema when data is loaded into the table. Instead of using the sort order from the column definition, the superprojection uses the sort order specified by the ORDER BY clause: => CREATE TABLE Public.Employee_Dimension ( Employee_key integer PRIMARY KEY NOT NULL, Employee_gender varchar(8) ENCODING RLE, Employee_title varchar(8), Employee_first_name varchar(64), Employee_middle_initial varchar(8), Employee_last_name varchar(64), ) ORDER BY Employee_gender, Employee_last_name, Employee_first_name; The following example creates a table called time and partitions the data by year. HP Vertica creates a default superprojection when data is loaded into the table: => CREATE TABLE time( ..., date_col date NOT NULL, ...) => PARTITION BY extract('year' FR OM date_col); The following example creates a table named location and partitions the data by state. HP Vertica creates a default superprojection when data is loaded into the table: => CREATE TABLE location(..., state VARCHAR NOT NULL, ...) PARTITION BY state; The following statement uses SELECT AS to create a table called promo and load data from columns in the existing customer_dimension table in which the customer's annual_income is greater than $1,000,000. The data is ordered by state and annual income. => CREATE TABLE promo AS SELECT customer_name, customer_address, customer_city, customer_state, annual_income FROM customer_dimension WHERE annual_income>1000000 ORDER BY customer_state, annual_income; The following table uses SELECT AS to create a table called promo and load data from the latest committed DML transaction (AT EPOCH LATEST). => CREATE TABLE promo AS AT EPOCH LATEST SELECT customer_name, customer_address, customer_city, customer_state, annual_income HP Vertica Analytic Database (7.0.x) Page 1092 of 1539 SQL Reference Manual SQL Statements FROM customer_dimension; The next example creates a new table (date_dimcopy) based on the VMart database date_ dimension table, and including projections. VMart=> create table date_dimcopy like date_dimension including projections; CREATE TABLE The new table, date_dimcopy, has the same definitions as the original date_dimension table. VMart=> select ordinal_position,column_name, data_type FROM columns where table_name='dat e_dimcopy' ORDER BY ordinal_position; ordinal_position | column_name | data_type -----------------+-------------------------------+------------1 | date_key | int 2 | date | date 3 | full_date_description | varchar(18) 4 | day_of_week | varchar(9) 5 | day_number_in_calendar_month | int 6 | day_number_in_calendar_year | int 7 | day_number_in_fiscal_month | int 8 | day_number_in_fiscal_year | int 9 | last_day_in_week_indicator | int 10 | last_day_in_month_indicator | int 11 | calendar_week_number_in_year | int 12 | calendar_month_name | varchar(9) 13 | calendar_month_number_in_year | int 14 | calendar_year_month | char(7) 15 | calendar_quarter | int 16 | calendar_year_quarter | char(7) 17 | calendar_half_year | int 18 | calendar_year | int 19 | holiday_indicator | varchar(10) 20 | weekday_indicator | char(7) 21 | selling_season | varchar(32) (21 rows) The following examples illustrate creating a table, and then attempting to create the same table, with and without the IF NOT EXISTS argument, to show the results. 1. Create a simple table: => CREATE TABLE t (a INT); CREATE TABLE 2. Try to create the same table, without IF NOT EXISTS, so a rollback occurs: => CREATE TABLE t (a INT, b VARCHAR(256)); HP Vertica Analytic Database (7.0.x) Page 1093 of 1539 SQL Reference Manual SQL Statements ROLLBACK: object "t" already exists 3. Try again to create the table, using the IF NOT EXISTS clause, so a notice occurs: => CREATE TABLE IF NOT EXISTS t (a INT, b VARCHAR(256)); NOTICE: object "t" already exists; nothing was done CREATE TABLE The IF NOT EXISTS argument is useful for SQL scripts where you want to create a table if it does not already exist, and reuse the existing table if it does. See Also l Physical Schema l COPY l CREATE EXTERNAL TABLE AS COPY l CREATE TEMPORARY TABLE l CREATE FLEX TABLE l DROP_PARTITION l DROP PROJECTION l DUMP_PARTITION_KEYS l DUMP_PROJECTION_PARTITION_KEYS l DUMP_TABLE_PARTITION_KEYS l PARTITION_PROJECTION l PARTITION_TABLE l SELECT l Working with Table Partitions l Auto Partitioning l Creating Flex Tables l Using External Tables HP Vertica Analytic Database (7.0.x) Page 1094 of 1539 SQL Reference Manual SQL Statements Column-Definition (table) A column definition specifies the name, data type, and constraints to be applied to a column. Syntax column-name data-type { ... [ Column-Constraint ] ... [ ENCODING encoding-type ] ... [ ACCESSRANK integer ] } Parameters column-name Specifies the name of a column to be created or added. data-type Specifies one of the following data types: BINARY BOOLEAN CHARACTER DATE/TIME NUMERIC Tip: When specifying the maximum column width in a CREATE TABLE statement, use the width in bytes (octets) for any of the string types. Each UTF-8 character may require four bytes, but European languages generally require a little over one byte per character, while Oriental language generally require a little under three bytes per character. column-constraint Specifies a Column-Constraint to add on the column. ENCODING encoding-type [Optional] Specifies the type of encoding to use on the column. By default, the encoding type is auto. Caution: The NONE keyword is obsolete. ACCESSRANK integer [Optional] Overrides the default access rank for a column. This is useful if you want to increase or decrease the speed at which a column is accessed. See Creating and Configuring Storage Locations and Prioritizing Column Access Speed in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1095 of 1539 SQL Reference Manual SQL Statements Example The following example creates a table named Employee_Dimension and its associated superprojection in the Public schema. The Employee_key column is designated as a primary key, and RLE encoding is specified for the Employee_gender column definition: => CREATE TABLE Public.Employee_Dimension ( Employee_key integer PRIMARY KEY NOT NULL, Employee_gender varchar(8) ENCODING RLE, Employee_title varchar(8), Employee_first_name varchar(64), Employee_middle_initial varchar(8), Employee_last_name varchar(64), ); Column-Name-List (table) Is used to rename columns when creating a table from a query (CREATE TABLE AS SELECT). It can also be used to specify the Encoding-Type and access rank of the column. Syntax column-name-list ... [ ENCODING encoding-type ] ... [ ACCESSRANK integer ] [ , ... ] ... [ GROUPED ( projection-column-reference [,...] ) ] Parameters column-name Specifies the new name for the column. ENCODING encoding-type Specifies the type of encoding to use on the column. By default, the encoding-type is auto. See Encoding-Type for a complete list. Caution: Using the NONE keyword for strings could negatively affect the behavior of string columns. ACCESSRANK integer Overrides the default access rank for a column. This is useful if you want to increase or decrease the speed at which a column is accessed. See Creating and Configuring Storage Locations and Prioritizing Column Access Speed in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1096 of 1539 SQL Reference Manual SQL Statements GROUPED Groups two or more columns into a single disk file. This minimizes file I/O for work loads that: l Read a large percentage of the columns in a table. l Perform single row look-ups. l Query against many small columns. l Frequently update data in these columns. If you have data that is always accessed together and it is not used in predicates, you can increase query performance by grouping these columns. Once grouped, queries can no longer independently retrieve from disk all records for an individual column independent of the other columns within the group. Note: RLE compression is reduced when a RLE column is grouped with one or more non-RLE columns. When grouping columns you can: l Group some of the columns: (a, GROUPED(b, c), d) l Group all of the columns: (GROUPED(a, b, c, d)) l Create multiple groupings in the same projection: (GROUPED(a, b), GROUPED(c, d)) Note: HP Vertica performs dynamic column grouping. For example, to provide better read and write efficiency for small loads, HP Vertica ignores any projection-defined column grouping (or lack thereof) and groups all columns together by default. Notes If You Are Using a Query Neither the data type nor column constraint can be specified for a column in the column-name-list. These are derived by the columns in the query table identified in the FROM clause. If the query output has expressions other than simple columns (for example, constants, functions, etc) then either an alias must be specified for that expression, or all columns must be listed in the column name list. HP Vertica Analytic Database (7.0.x) Page 1097 of 1539 SQL Reference Manual SQL Statements You can supply the encoding type and access rank in either the column-name-list or the column list in the query, but not both. The following statements are both allowed: => CREATE TABLE promo (state ENCODING RLE ACCESSRANK 1, zip ENCODING RLE, ...) AS SELECT * FROM customer_dimension ORDER BY customer_state, ... ; => CREATE TABLE promo AS SELECT * FROM customer_dimension ORDER BY customer_state ENCODED BY customer_state ENCODING RLE ACCESSRANK 1, customer_zip ENCODING RLE ...; The following statement is not allowed because encoding is specified in both column-name-list and ENCODED BY clause: => CREATE TABLE promo (state ENCODING RLE ACCESSRANK 1, zip ENCODING RLE, ...) AS SELECT * FROM customer_dimension ORDER BY customer_state ENCODED BY customer_state ENCODING RLE ACCESSRANK 1, customer_zip ENCODING RLE ...; Example The following example creates a table named employee_dimension and its associated superprojection in the public schema. Note that encoding-type RLE is specified for the employee_ gender column definition: => CREATE TABLE public.employee_dimension ( employee_key INTEGER PRIMARY KEY NOT NULL, employee_gender VARCHAR(8) ENCODING RLE, employee_title VARCHAR(8), employee_first_name VARCHAR(64), employee_middle_initial VARCHAR(8), employee_last_name VARCHAR(64) ); Using the VMart schema, the following example creates a table named promo from a query that selects data from columns in the customer_dimension table. RLE encoding is specified for the state column in the column name list. => CREATE TABLE promo ( name, address, city, state ENCODING RLE, income ) AS SELECT customer_name, customer_address, customer_city, customer_state, annual_income FROM customer_dimension WHERE annual_income > 1000000 HP Vertica Analytic Database (7.0.x) Page 1098 of 1539 SQL Reference Manual SQL Statements ORDER BY customer_state, annual_income; Column-Constraint Adds a referential integrity constraint to the metadata of a column. See Adding Constraints in the Administrator's Guide. Syntax [ CONSTRAINT constraint-name ] { ...[ NULL | NOT NULL ] ...| PRIMARY KEY ...| REFERENCES table-name [( column [ , ... ] )] ...| UNIQUE ...[ DEFAULT default ] ...[ AUTO_INCREMENT ] ...[ IDENTITY [ ( cache ) | ( start, increment[, cache ] ) ] ] } Parameters CONSTRAINT constraint-name [Optional] Assigns a name to the constraint. HP recommends that you name all constraints. [NULL | NOT NULL] Specifies that the column can contain null values (NULL, the default), or cannot (NOT NULL). Using NOT NULL specifies that the column must receive a value during INSERT and UPDATE operations. If no DEFAULT value is specified and no value is provided, the INSERT or UPDATE statement returns an error, since no default value exists. PRIMARY KEY HP Vertica Analytic Database (7.0.x) Adds a referential integrity constraint defining the column as the primary key. Page 1099 of 1539 SQL Reference Manual SQL Statements REFERENCES table-name [column] Specifies the table to which the FOREIGN KEY column constraint applies. You can specify a FOREIGN KEY constraint explicitly or just by a reference to the table and column with the PRIMARY KEY. If you omit the column, the default value is the primary key of the referenced table. UNIQUE Constrains the data that a column (or group of columns) contains to be unique with respect to all the rows in the table. If you insert or update the column with a duplicate value, HP Vertica does not give an error. To ensure that the column has unique values, run ANALYZE_ STATISTICS. HP Vertica Analytic Database (7.0.x) Page 1100 of 1539 SQL Reference Manual SQL Statements DEFAULT default Specifies a default value for a column if the column is used in an INSERT operation and no value is specified for the column. If no value is specified for the column and there is no default, the default is NULL. Default value usage: l A default value can be set for a column of any data type. l The default value can be any variable-free expression, as long as it matches the data type of the column. l Variable-free expressions can contain constants, SQL functions, null-handling functions, system information functions, string functions, numeric functions, formatting functions, nested functions, and all HP Vertica-supported operators Default value restrictions: HP Vertica Analytic Database (7.0.x) l Expressions can contain only constant arguments. l Subqueries and cross-references to other columns in the table are not permitted in the expression. l The return value of a default expression cannot be NULL. l The return data type of the default expression after evaluation either matches that of the column for which it is defined, or an implicit cast between the two data types is possible. For example, a character value cannot be cast to a numeric data type implicitly, but a number data type can be cast to character data type implicitly. Page 1101 of 1539 SQL Reference Manual SQL Statements l Default expressions, when evaluated, conform to the bounds for the column. l Volatile functions are not supported when adding columns to existing tables. See ALTER TABLE. Note: HP Vertica attempts to check the validity of default expressions, but some errors might not be caught until run time. AUTO_INCREMENT Creates a table column whose values are automatically generated by the database. The initial value of an AUTO_INCREMENT column is always 1. You cannot specify a different initial value. Each time you add a row to the table, HP Vertica increments the column value by 1. You cannot change the value of an AUTO_ INCREMENT column. HP Vertica Analytic Database (7.0.x) Page 1102 of 1539 SQL Reference Manual SQL Statements IDENTITY [ ( cache ) | ( start, increment[, cache ] ) ] Specifies a column whose values are automatically generated by the database. You can use IDENTITY columns as primary keys. IDENTITY column parameters are evaluated in order as follows: l One parameter: Evaluated as cache, indicates the number of unique numbers each node allocates per session. cache must be a positive integer. Default: 250,000. Minimum: 1. l Two parameters: Evaluated as start, increment. start specifies the number at which to start the IDENTITY column. Default: 1. increment specifies how much to increment the value from the previous row's value. Default: 1. l Three parameters: Evaluated as start, increment, cache. Note: You cannot change the value of an IDENTITY column once the table exists. Permissions Table owner or user WITH GRANT OPTION is grantor. l REFERENCES privilege on table to create foreign key constraints that reference this table l USAGE privilege on schema that contains the table Notes l HP Vertica supports only one IDENTITY or one AUTO_INCREMENT column per table. HP Vertica Analytic Database (7.0.x) Page 1103 of 1539 SQL Reference Manual SQL Statements l When you use ALTER TABLE to change the table owner, HP Vertica transfers ownership of the associated IDENTITY/AUTO_INCREMENT sequences but not other REFERENCES sequences. l You can specify a FOREIGN KEY constraint explicitly by using the FOREIGN KEY parameter, or implicitly, using a REFERENCES parameter to the table with the PRIMARY KEY. If you omit the column in the referenced table, HP Vertica uses the primary key: => CREATE TABLE fact(c1 INTEGER PRIMARY KEY NOT NULL); => CREATE TABLE dim (c1 INTEGER REFERENCES fact NOT NULL); l Columns that are given a PRIMARY constraint must also be set NOT NULL. HP Vertica automatically sets these columns to be NOT NULL if you do not do so explicitly. l HP Vertica supports variable-free expressions in the column DEFAULT clause. See COPY [Column as Expression]. l If you are using a CREATE TABLE AS SELECT statement, the column-constraint parameter does not apply. Constraints are set by the columns in the query table identified in the FROM clause. l An AUTO-INCREMENT or IDENTITY value is never rolled back, even if a transaction that tries to insert a value into a table is not committed. Example The following command creates the store_dimension table and sets the default column value for store_state to MA: => CREATE TABLE store_dimension (store_state CHAR (2) DEFAULT MA); The following command creates the public.employee_dimension table and sets the default column value for hire_date to current_date(): => CREATE TABLE public.employee_dimension (hire_date DATE DEFAULT current_date()); The following example uses the IDENTITY column-constraint to create a table with an ID column that has an initial value of 1. It is incremented by 1 every time a row is inserted. => CREATE TABLE Premium_Customer( ID IDENTITY(1,1), lname VARCHAR(25), fname VARCHAR(25), store_membership_card INTEGER ); => INSERT INTO Premium_Customer (lname, fname, store_membership_card ) VALUES ('Gupta', 'Saleem', 475987); Confirm the row you added and see the ID value: HP Vertica Analytic Database (7.0.x) Page 1104 of 1539 SQL Reference Manual SQL Statements => SELECT * FROM Premium_Customer; ID | lname | fname | store_membership_card ----+-------+--------+----------------------1 | Gupta | Saleem | 475987 (1 row) Now add another row: => INSERT INTO Premium_Customer (lname, fname, store_membership_card) VALUES ('Lee', 'Chen', 598742); Calling the LAST_INSERT_ID function returns value 2 because you previously inserted a new customer (Chen Lee), and this value is incremented each time a row is inserted: => SELECT LAST_INSERT_ID(); last_insert_id ---------------2 (1 row) View all the ID values in the Premium_Customer table: => SELECT * FROM Premium_Customer; ID | lname | fname | store_membership_card ----+-------+--------+----------------------1 | Gupta | Saleem | 475987 2 | Lee | Chen | 598742 (2 rows) The following example uses the AUTO_INCREMENT column-constraint to create a table with an ID column that automatically increments every time a row is inserted. => CREATE TABLE Premium_Customer( ID AUTO_INCREMENT, lname VARCHAR(25), fname VARCHAR(25), store_membership_card INTEGER ); => INSERT INTO Premium_Customer (lname, fname, store_membership_card ) VALUES ('Gupta', 'Saleem', 475987); Confirm the row you added and see the ID value: => SELECT * FROM Premium_Customer; ID | lname | fname | store_membership_card ----+-------+--------+----------------------1 | Gupta | Saleem | 475987 (1 row) Now add two rows: HP Vertica Analytic Database (7.0.x) Page 1105 of 1539 SQL Reference Manual SQL Statements => INSERT INTO Premium_Customer (lname, fname, store_membership_card) VALUES ('Lee', 'Chen', 598742); => INSERT INTO Premium_Customer (lname, fname, store_membership_card) VALUES ('Brown', 'John', 642159); => SELECT * FROM Premium_Customer; ID | lname | fname | store_membership_card ----+-------+--------+----------------------1 | Gupta | Saleem | 475987 2 | Lee | Chen | 598742 3 | Brown | John | 642159 (3 rows) This time the LAST_INSERT_ID returns a value of 3: => SELECT LAST_INSERT_ID(); LAST_INSERT_ID ---------------3 (1 row) The next examples illustrate the three valid ways to use IDENTITY arguments. The first example uses a cache of 100, and the defaults for start value (1) and increment value (1): => CREATE TABLE t1(x IDENTITY(100), y INT); The second example specifies the start and increment values as 1, and defaults to a cache value of 250,000: => CREATE TABLE t2(y IDENTITY(1,1), x INT); The third example specifies start and increment values of 1, and a cache value of 100: => CREATE TABLE t3(z IDENTITY(1,1,100), zx INT); For additional examples, see CREATE SEQUENCE. Table-Constraint Adds a constraint to the metadata of a table. See Adding Constraints in the Administrator's Guide. Syntax [ CONSTRAINT constraint_name ... { PRIMARY KEY ( column [ ... | FOREIGN KEY ( column [ REFERENCES table [( column [ ] , ... ] ) , ... ] ) , ... ] )] ... | UNIQUE ( column [ , ... ] )... } HP Vertica Analytic Database (7.0.x) Page 1106 of 1539 SQL Reference Manual SQL Statements Parameters CONSTRAINT constraint-name Assigns a name to the constraint. HP recommends that you name all constraints. PRIMARY KEY ( column [ , ... ] ) Adds a referential integrity constraint defining one or more NOT NULL columns as the primary key. FOREIGN KEY ( column [ , ... ] ) Adds a referential integrity constraint defining one or more columns as a foreign key. REFERENCES table [( column [ , ... ] )] Specifies the table to which the FOREIGN KEY constraint applies. If you omit the optional column definition of the referenced table, the default is the primary key of table. UNIQUE ( column Specifies that the data contained in a column or a group of columns is unique with respect to all the rows in the table. [ , ... ] ) Permissions Table owner or user WITH GRANT OPTION is grantor. l REFERENCES privilege on table to create foreign key constraints that reference this table l USAGE privilege on schema that contains the table Specifying Primary and Foreign Keys You must define PRIMARY KEY and FOREIGN KEY constraints in all tables that participate in inner joins. You can specify a foreign key table constraint either explicitly (with the FOREIGN KEY parameter), or implicitly using the REFERENCES parameter to reference the table with the primary key. You do not have to explicitly specify the columns in the referenced table, for example: CREATE TABLE fact(c1 INTEGER PRIMARY KEY); CREATE TABLE dim (c1 INTEGER REFERENCES fact); Adding Constraints to Views Adding a constraint to a table that is referenced in a view does not affect the view. HP Vertica Analytic Database (7.0.x) Page 1107 of 1539 SQL Reference Manual SQL Statements Examples The VMart sample database, described in the Getting Started Guide, contains a table Product_ Dimension in which products have descriptions and categories. For example, the description "Seafood Product 1" exists only in the "Seafood" category. You can define several similar correlations between columns in the Product Dimension table. Hash-Segmentation-Clause (table) Hash segmentation allows you to segment a projection based on a built-in hash function that provides even distribution of data across some or all of the nodes in a cluster, resulting in optimal query execution. Note: Hash segmentation is the preferred method of segmentation. The Database Designer uses hash segmentation by default. Syntax SEGMENTED BY expression [ ALL NODES | NODES node [ ,... ] ] Parameters SEGMENTED BY expression Can be a general SQL expression. However, HP recommends using the built-in HASH or MODULARHASH functions, specifying table columns as arguments. If you specify only a column name, HP Vertica gives a warning. Choose columns that have a large number of unique data values and acceptable skew in their data distribution. Primary key columns that meet the criteria could be an excellent choice for hash segmentation. ALL NODES NODES node Automatically distributes the data evenly across all nodes at the time the projection is created. The ordering of the nodes is fixed. [ ,... ] Specifies a subset of the nodes in the cluster over which to distribute the data. You can use a specific node only once in any projection. For a list of the nodes in a database, use the View Database command in the Administration Tools. Notes l Table column names must be used in the expression, not the projection column names. n To use a SEGMENTED BY expression other than HASH or MODULARHASH, the following restrictions apply: HP Vertica Analytic Database (7.0.x) Page 1108 of 1539 SQL Reference Manual SQL Statements o All leaf expressions must be either constants or column-references to a column in the SELECT list of the CREATE PROJECTION command. o Aggregate functions are not allowed. o The expression must return the same value over the life of the database. o The expression must return non-negative INTEGER values in the range 0 <= x < 263 (two to the sixty-third power or 2^63), and values are generally distributed uniformly over that range. o If expression produces a value outside of the expected range (a negative value for example), no error occurs, and the row is added to the first segment of the projection. The hash-segmentation-clause within the CREATE TABLE or CREATE TEMP TABLE statement does not support the OFFSET keyword, which is available in the CREATE PROJECTION command. The OFFSET is set to zero (0). l n l When a hash-segmentation-clause is used with KSAFE [k_num], HP Vertica automatically creates k_num+1 buddy projections to meet the K-safety requirement. Example This example segments the default superprojection and its buddies for the Public.Employee_ Dimension table using HASH segmentation across all nodes based on the Employee_key column: => CREATE TABLE Public.Employee_Dimension ( Employee_key integer PRIMARY KEY NOT NULL, Employee_gender varchar(8) ENCODING RLE, Employee_title varchar(8), Employee_first_name varchar(64), Employee_middle_initial varchar(8), Employee_last_name varchar(64), ) SEGMENTED BY HASH(Employee_key) ALL NODES; See Also l HASH l MODULARHASH CREATE TEMPORARY TABLE Creates a temporary table. HP Vertica Analytic Database (7.0.x) Page 1109 of 1539 SQL Reference Manual SQL Statements Syntax CREATE [ GLOBAL | LOCAL ] TEMPORARY | TEMP ... TABLE [ IF NOT EXISTS ] [[db-name.]schema.].table-name { ... ( Column-Definition (temp table) [ , ... ] ) ... | [ column-name-list (create table) ] } ... [ ON COMMIT { DELETE | PRESERVE } ROWS ] ... [ AS [ { AT EPOCH { integer | LATEST } | AT TIME 'timestamp'} ] ... [ /*+ direct */ ] query ] ... [ ORDER BY table-column [ , ... ] ] ... [ ENCODED BY column-definition [ , ... ] ] ....[ Hash-Segmentation-Clause ......| UNSEGMENTED { NODE node ......| ALL NODES } ] ....[ KSAFE [ k-num ] ] ....| [ NO PROJECTION ] ] Parameters GLOBAL [Optional] Specifies that the table definition is visible to all sessions. This is the default value when creating a temporary table. Temporary table data is visible only to the session that inserts the data into the table. LOCAL [Optional] Specifies that the table definition is visible only to the session in which it is created. TEMPORARY | TEMP Specifies that the table is a temporary table. [ IF NOT EXISTS ] [Optional] Determines whether the statement generates a NOTICE message or an ERROR if -name exists. Using IF NOT EXISTS generates a NOTICE if the specified object exists. Omitting the clause generates an error if -name exists. Regardless of whether you use IF NOT EXISTS, HP Vertica does not create a new object if -name exists. For more information, see also ON_ ERROR_STOP. [[db-name.]schema.] Specifies the schema in which to create the table. If you do not specify a schema-name, the statement creates the table in the first schema listed in the current search_path. You can specify a schema (and optional database name) only for a global temporary table. Schema-name is not supported for local temporary tables, which are always created in a special schema. table-name Specifies the name of the temporary table to create. column-definition Defines one or more columns. See Column-Definition (temp table). HP Vertica Analytic Database (7.0.x) Page 1110 of 1539 SQL Reference Manual SQL Statements column-name-list Renames columns when creating a temporary table from a query, such as: CREATE TEMPORARY TABLE as select... See column-name-list . ON COMMIT { PRESERVE | DELETE } ROWS AS [ { AT EPOCH { integ er | LATEST } | AT TIME 'timestamp'} ] /*+ direct */ [Optional] Specifies whether data is transaction- or session-scoped: l DELETE marks the temporary table for transaction-scoped data. HP Vertica truncates the table (delete all its rows) after each commit. DELETE ROWS is the default. l PRESERVE marks the temporary table for session-scoped data, which is preserved beyond the lifetime of a single transaction. HP Vertica truncates the table (delete all its rows) when you terminate a session. Specifies the epoch to use with an AS clause to query historical: l AT EPOCH LATEST—Data from the latest committed DML transaction l AT EPOCH integer—An epoch specified as an integer l AT TIME 'timestamp'—An epoch based on its timestamp Writes the data directly to disk (ROS) bypassing memory (WOS). HP Vertica accepts optional spaces before and after the plus (+) sign and the direct hint. Space characters between the opening /* or the closing */ are not permitted. The following directives are all acceptable: /*+direct*/ /* + direct*/ /*+ direct*/ /*+direct */ Note: If you create a temporary table using the direct hint, you still need to use the ON COMMIT PRESERVE ROWS option for the rows. HP Vertica Analytic Database (7.0.x) Page 1111 of 1539 SQL Reference Manual SQL Statements AS query [Optional.] Creates a new table from the results of a query and populates it with data from the query as long as you also specify ON COMMIT PRESERVE ROWS: CREATE GLOBAL TEMP TABLE temp_table1 ON COMMIT PRESERVE ROWS AS S ELECT ...; If you specify ON COMMIT DELETE ROWS, the temporary table is created, but no data is inserted from the query: CREATE GLOBAL TEMP TABLE temp_table1 ON COMMIT DELETE ROWS AS SEL ECT ...; Column renaming is supported as part of the process: CREATE TEMP TABLE temp-table1 (name, address, ...) AS SELECT cust omer_name, customer_address ... ; ORDER BY table-column [Optional] Specifies the superprojection sort order. HP Vertica creates a superprojection automatically for the table when you load data into the table. If you do not use this option to indicate the sort order, such as: ORDER BY col2, col1, col5 the projection is created with the column order specified in the column definition. HP Vertica does not create a superprojection sorted on a LONG VARBINARY or LONG VARCHAR column. Note: Data is in ascending order only. ENCODED BY column-defin ition [Applicable only with CREATE TEMPORARY TABLE AS query] Specifies the column encoding and/or the access rank for specific columns in the query when you do not use a column-definition to rename columns for the table being created. See Column-Definition (temp table) for examples. If you rename table columns when creating a temporary table from a query, you can supply the encoding type and access rank in the column name list instead. hash-segmentation-claus e [Optional] Segments the superprojection based on a built-in hash function that provides even data distribution across nodes, resulting in optimal query execution. See Hash-Segmentation-Clause. Note: An elastic projection (a segmented projection created when Elastic Cluster is enabled) created with a modularhash segmentation expression uses hash instead. HP Vertica Analytic Database (7.0.x) Page 1112 of 1539 SQL Reference Manual SQL Statements UNSEGMENTED{ NODE node | ALL NODES } KSAFE [ k-num ] [Optional] Lets you specify an unsegmented projection. The default for this parameter is to create an UNSEGMENTED projection on the initiator node. You can optionally use either of the following node specifications: n NODE node—Creates an unsegmented projection only on the specified node. Projections for small tables must be UNSEGMENTED. n ALL NODES—Automatically replicates the unsegmented projection on each node. To perform distributed query execution, HP Vertica requires an unsegmented copy of each small table superprojection on each node. [Optional] Specifies the K-safety level of the projection created for the table. The integer K determines how many unsegmented or segmented buddy projections to create. The value must be greater than or equal to the current K-safety level of the database, and less than the total number of nodes. If you do not specify a KSAFE value, the superprojection is created at the current system K-safety level. For example: K-SAFE 1 Note: When a hash-segmentation-clause is used with KSAFE, HP Vertica automatically creates k_num+1 buddy projections to meet the K-safety requirement. NO PROJECTION [Optional] Prevents automatically creating a default superprojection for the temporary table until data is loaded. You cannot use the NO PROJECTION option with queries (CREATE TEMPORARY TABLE AS SELECT), ORDER BY, ENCODED BY, KSAFE, or Hash-Segmentation-Clause. Notes l You cannot add projections to non-empty, session-scoped temporary tables (ON COMMIT PRESERVE ROWS). Make sure that projections exist before you load data. See the "Automatic Projection Creation" in the CREATE TABLE statement. l Although adding projections is allowed for tables with ON COMMIT DELETE ROWS specified, be aware that you could lose all the data. l The V_TEMP_SCHEMA namespace is automatically part of the search path. Thus, temporary table names do not need to be preceded with the schema. l Queries that involve temporary tables have the same restrictions on SQL support as queries that do not use temporary tables. HP Vertica Analytic Database (7.0.x) Page 1113 of 1539 SQL Reference Manual SQL Statements l Single-node (pinned to the initiator node only) projections are supported. l AT EPOCH LATEST queries that refer to session-scoped temporary tables work the same as those for transaction-scoped temporary tables. Both return all committed and uncommitted data regardless of epoch. For example, you can commit data from a temporary table in one epoch, advance the epoch, and then commit data in a new epoch. l Moveout and mergeout operations cannot be used on session-scoped temporary data. l If you issue the TRUNCATE TABLE statement on a temporary table, only session-specific data is truncated with no affect on data in other sessions. l The DELETE ... FROM TEMP TABLE syntax does not truncate data when the table was created with PRESERVE; it marks rows for deletion. See DELETE for additional details. l In general, session-scoped temporary table data is not visible using system (virtual) tables. l Views are supported for temporary tables. l ANALYZE_STATISTICS is supported on local temporary tables, but not on global temporary tables. l Table partitions are not supported for temporary tables. l Temporary tables do not recover. If a node fails, queries that use the temporary table also fail. Restart the session and populate the temporary table. l Pre-join projections that refer to both temporary and non-temporary tables are not supported. l You cannot use temporary tables as dimensions when the fact table is non-temporary in pre-join projections. All small tables in a pre-join projection must be at least as persistent as the large table and other small tables. The persistence scale is: Normal > session-scoped temporary table > transaction-scoped temporary table. n If the the anchor table of a pre-join projection is a transaction-scoped temp table, you can use any type of table (temp or normal) in the pre-join. n If the anchor table of a pre-join is a normal table, you can use only normal tables as dimension tables. n If there is a snowflake dimension session-scoped temporary table, its dimension tables may not be a transaction-scoped temporary tables. See Also l ALTER TABLE l CREATE TABLE HP Vertica Analytic Database (7.0.x) Page 1114 of 1539 SQL Reference Manual SQL Statements DELETE l DROP TABLE l l l l Column-Definition (temp table) A column definition specifies the name, data type, default, and other characteristics to be applied to a column. Syntax column-name data-type [ DEFAULT ] [ NULL | NOT NULL ] [ ENCODING encoding-type ] [ ACCESSRANK integer ] ] Parameters column-name Specifies the name of the temporary table to be created. data-type Specifies one of the following data types: l BINARY l BOOLEAN l CHARACTER l DATE/TIME l NUMERIC HP Vertica Analytic Database (7.0.x) Page 1115 of 1539 SQL Reference Manual SQL Statements DEFAULT default Specifies a default value for a column if the column is used in an INSERT operation and no value is specified for the column. If no value is specified for the column and there is no default, the default is NULL. Default value usage: l A default value can be set for a column of any data type. l The default value can be any variable-free expression, as long as it matches the data type of the column. l Variable-free expressions can contain constants, SQL functions, null-handling functions, system information functions, string functions, numeric functions, formatting functions, nested functions, and all HP Vertica-supported operators Default value restrictions: l Expressions can contain only constant arguments. l Subqueries and cross-references to other columns in the table are not permitted in the expression. l The return value of a default expression cannot be NULL. l The return data type of the default expression after evaluation either matches that of the column for which it is defined, or an implicit cast between the two data types is possible. For example, a character value cannot be cast to a numeric data type implicitly, but a number data type can be cast to character data type implicitly. l Default expressions, when evaluated, conform to the bounds for the column. l Volatile functions are not supported when adding columns to existing tables. See ALTER TABLE. Note: HP Vertica attempts to check the validity of default expressions, but some errors might not be caught until run time. NULL [Default] Specifies that the column is allowed to contain null values. NOT NULL Specifies that the column must receive a value during INSERT and UPDATE operations. If no DEFAULT value is specified and no value is provided, the INSERT or UPDATE statement returns an error because no default value exists. HP Vertica Analytic Database (7.0.x) Page 1116 of 1539 SQL Reference Manual SQL Statements ENCODING encoding-type [Optional] Specifies the type of encoding to use on the column. By default, the encoding type is auto. Caution: The NONE keyword is obsolete. ACCESSRANK integer [Optional] Overrides the default access rank for a column. This is useful if you want to increase or decrease the speed at which a column is accessed. See Creating and Configuring Storage Locations and Prioritizing Column Access Speed in the Administrator's Guide. Column-Name-List (temp table) A column name list is used to rename columns when creating a temporary table from a query (CREATE TEMPORARY TABLE AS SELECT). It can also be used to specify the encoding type and access rank of the column. Syntax column-name-list [ ENCODING encoding-type ] [ ACCESSRANK integer ] [ , ... ] ojection-column-reference [,...] ) ] [ GROUPED( pr Parameters column-name-list Specifies the new name for the column. ENCODING encoding-type [Optional] Specifies the type of encoding to use on the column. By default, the encoding-type is auto. See encoding type for a complete list. Caution: Using the NONE keyword for strings could negatively affect the behavior of string columns. ACCESSRANK integer [Optional] Overrides the default access rank for a column. This is useful if you want to increase or decrease the speed at which a column is accessed. See Creating and Configuring Storage Locations and Prioritizing Column Access Speed in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1117 of 1539 SQL Reference Manual SQL Statements GROUPED Groups two or more columns into a single disk file. This minimizes file I/O for work loads that: l Read a large percentage of the columns in a table. l Perform single row look-ups. l Query against many small columns. l Frequently update data in these columns. If you have data that is always accessed together and it is not used in predicates, you can increase query performance by grouping these columns. Once grouped, queries can no longer independently retrieve from disk all records for an individual column independent of the other columns within the group. Note: RLE compression is reduced when a RLE column is grouped with one or more non-RLE columns. When grouping columns you can: l Group some of the columns: l (a, GROUPED(b, c), d) l Group all of the columns: l (GROUPED(a, b, c, d)) l Create multiple groupings in the same projection: l (GROUPED(a, b), GROUPED(c, d)) HP Vertica performs dynamic column-grouping. For example, to provide better read and write efficiency for small loads, HP Vertica ignores any projection-defined column grouping (or lack thereof) and groups all columns together by default. Notes If you are using a CREATE TEMPORARY TABLE AS SELECT statement: l The data-type cannot be specified for a column in the column name list. It is derived by the column in the query table identified in the FROM clause l You can supply the encoding type and access rank in either the column name list or the column HP Vertica Analytic Database (7.0.x) Page 1118 of 1539 SQL Reference Manual SQL Statements list in the query, but not both. The following statements are both allowed: => CREATE TEMPORARY TABLE temp_table1 (state ENCODING RLE ACCESSRANK 1, zip ENCODING R LE, ...) AS SELECT * FROM customer_dimension ORDER BY customer_state, ... ; => CREATE TEMPORARY TABLE temp_table1 AS SELECT * FROM customer_dimension ORDER BY customer_state ENCODED BY customer_state ENCODING RLE ACCESSRANK 1, customer_zip ENCODING RLE ...; The following statement is not allowed: => CREATE TEMPORARY TABLE temp_table1 (state ENCODING RLE ACCESSRANK 1, zip ENCODING R LE, ...) AS SELECT * FROM customer_dimension ORDER BY customer_state ENCODED BY customer_state ENCODING RLE ACCESSRANK 1, customer_zip ENCODING RLE ...; Example The following example creates a temporary table named temp_table2 and its associated superprojection. Note that encoding-type RLE is specified for the y column definition: => CREATE x y b z GLOBAL TEMP TABLE temp_table2 ( NUMERIC, NUMERIC ENCODING RLE, VARCHAR(8), VARCHAR(8) ); The following example creates a table named temp_table3 from a query that selects data from columns in the customer_dimension table. RLE encoding is specified for the state column in the column name list. => CREATE TABLE temp_table3 (name, address, city, state ENCODING RLE, income) T customer_name, customer_address, customer_city, customer_state, annual_income FROM customer_dimension WHERE annual_income > 1000000 ORDER BY customer_state, annual_income; AS SELEC Hash-Segmentation-Clause (temp table) By default, a superprojection for a temp table is segmented and not pinned. HP Vertica Analytic Database (7.0.x) Page 1119 of 1539 SQL Reference Manual SQL Statements Hash segmentation allows you to segment a table based on a built-in hash function. The built-in hash function provides even distribution of data across some or all nodes in a cluster, resulting in optimal query execution. Projections created in this manner are not pinned. Note: Hash segmentation is the preferred method of segmentation. The Database Designer uses hash segmentation by default. Syntax SEGMENTED BY expression [ ALL NODES | NODES node [ ,... ] ] Parameters SEGMENTED BY expression Can be a general SQL expression. However, HP recommends using the built-in HASH or MODULARHASH functions, specifying table columns as arguments. If you specify only a column name, HP Vertica gives a warning. Choose columns that have a large number of unique data values and acceptable skew in their data distribution. Primary key columns that meet the criteria could be an excellent choice for hash segmentation. ALL NODES NODES node Automatically distributes the data evenly across all nodes at the time the projection is created. The ordering of the nodes is fixed. [ ,... ] Specifies a subset of the nodes in the cluster over which to distribute the data. You can use a specific node only once in any projection. For a list of the nodes in a database, use the View Database command in the Administration Tools. Notes l You must use the table column names in the expression, not the projection column names. l To use a SEGMENTED BY expression other than HASH or MODULARHASH, the following restrictions apply: n All leaf expressions must be either constants or column-references to a column in the SELECT list of the CREATE PROJECTION command. n Aggregate functions are not allowed. n The expression must return the same value over the life of the database. n The expression must return non-negative INTEGER values in the range 0 <= x < 263 (two to the sixty-third power or 2^63), and values are generally distributed uniformly over that range. HP Vertica Analytic Database (7.0.x) Page 1120 of 1539 SQL Reference Manual SQL Statements n l If expression produces a value outside of the expected range (a negative value for example), no error occurs, and the row is added to the first segment of the projection. The hash-segmentation-clause within the CREATE TABLE or CREATE TEMP TABLE statement does not support the OFFSET keyword, which is available in the CREATE PROJECTION command. The OFFSET is set to zero (0). Example This example segments the default superprojection and its buddies using HASH segmentation based on column 1 (C1). => CREATE TEMPORARY TABLE ... SEGMENTED BY HASH(C1) ALL NODES; See Also l HASH l MODULARHASH CREATE USER Adds a name to the list of authorized database users. Syntax CREATE USER name ... [ ACCOUNT {LOCK | UNLOCK} ] ... [ IDENTIFIED BY 'password' ] ... [ MEMORYCAP {'memory-limit' | NONE} ] ... [ PASSWORD EXPIRE ] ... [ PROFILE {profile | DEFAULT} ] ... [ RESOURCE POOL pool-name ] ... [ RUNTIMECAP {'time-limit' | NONE} ] ... [ TEMPSPACECAP {'space-limit' | NONE} ] ... [ SEARCH_PATH {schema[,schema2,...]} | DEFAULT ] HP Vertica Analytic Database (7.0.x) Page 1121 of 1539 SQL Reference Manual SQL Statements Parameters name Specifies the name of the user to create; names that contain special characters must be doublequoted. Tip: HP Vertica database user names are logically separate from user names of the operating system in which the server runs. If all the users of a particular server also have accounts on the server's machine, it makes sense to assign database user names that match their operating system user names. However, a server that accepts remote connections could have many database users who have no local operating system account, and in such cases there need be no connection between database user names and OS user names. ACCOUNT LOCK | UNLOCK Locks or unlocks the a user's access to the database. UNLOCK is the default for new users, so the keyword is optional. You'll most commonly use UNLOCK with the ALTER USER command. Specifying LOCK prevents a new user from logging in, which might be useful if you want to create an account for users who don't need access yet. Tip: A superuser can automate account locking by setting a maximum number of failed login attempts through the CREATE PROFILE statement. HP Vertica Analytic Database (7.0.x) Page 1122 of 1539 SQL Reference Manual SQL Statements IDENTIFIED BY 'password' Sets the new user's password. Supplying an empty string for password creates a user without a password, as does omitting the IDENTIFIED BY 'password' clause. If a user does not have a password, he or she will not be prompted for one when connecting. Providing a password using the IDENTIFIED BY clause requires that the given password conform to the password complexity policy set by the user's profile. User profiles are either specified with the PROFILE parameter, or associated with a default profile if a superuser omits the PROFILE parameter. See Password Guidelines and Creating a Database Name and Password for password policies. PASSWORD EXPIRE Expires the user's password immediately. The user will be forced to change the password when he or she next logs in. The grace period setting (if any) in the user's profile is overridden. Note: PASSWORD EXPIRE has no effect when using external password authentication methods such as LDAP or Kerberos. MEMORYCAP 'memory-limit' | NONE Limits the amount of memory that the user's requests can use. This value is a number representing the amount of space, followed by a unit (for example, '10G'). The unit can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case value for the size must be 0-100) l K— Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes Setting this value to NONE means the user's sessions have no limits on memory use. This is the default value. HP Vertica Analytic Database (7.0.x) Page 1123 of 1539 SQL Reference Manual SQL Statements PROFILE profile | DEFAULT Assigns the user to the profile named profile. Profiles set the user's password policy. See Profiles in the Administrator's Guide for details. Using the value DEFAULT here assigns the user to the default profile. If this parameter is omitted, the user is assigned to the default profile. RESOURCE POOL pool-name Sets the name of the resource pool from which to request the user's resources. This command creates a usage grant for the user on the resource pool unless the resource pool is publicly usable. RUNTIMECAP 'time-limit' | NONE Sets the maximum amount of time any of the user's queries can execute. time-limit is an interval, such as '1 minute' or '100 seconds' (see Interval Values for details). The maximum duration allowed is one year. Setting this value to NONE means there is no time limit on the user's queries. If RUNTIMECAP is also set for the resource pool or session, HP Vertica always uses the shortest limit. TEMPSPACECAP 'space-limit' | NONE Limits the amount of temporary file storage the user's requests can use. This parameter's value has the same format as the MEMORYCAP value. SEARCH_PATH schema[,schema2,...] | DEFAUL T Sets the user's default search path that tells HP Vertica which schemas to search for unqualified references to tables and UDFs. See Setting Search Paths in the Administrator's Guide for an explanation of the schema search path. The DEFAULT keyword sets the search path to: "$user", public, v_catalog, v_monitor, v_interna l Permissions Must be a superuser to create a user. Notes l User names created with double-quotes are case sensitive. For example: => CREATE USER "FrEd1"; HP Vertica Analytic Database (7.0.x) Page 1124 of 1539 SQL Reference Manual SQL Statements In the above example, the login name must be an exact match. If the user name was created without double-quotes (for example, FRED1), then the user can log in as FRED1, FrEd1, fred1, and so on. Note: ALTER USER and DROP USER are case-insensitive. l Newly-created users do not have access to schema PUBLIC by default. Make sure to GRANT USAGE ON SCHEMA PUBLIC to all users you create. l You can change a user password by using the ALTER USER statement. If you want to configure a user to not have any password authentication, you can set the empty password ‘’ in CREATE or ALTER USER statements, or omit the IDENTIFIED BY parameter in CREATE USER. l By default, users have the right to create temporary tables in the database. Examples => CREATE USER Fred; => GRANT USAGE ON SCHEMA PUBLIC to Fred; See Also ALTER USER l DROP USER l l l CREATE VIEW Defines a new view. Views are read only. You cannot perform insert, update, delete, or copy operations on a view. Syntax CREATE [ OR REPLACE ] VIEW viewname [ ( column-name [, ...] ) ] AS query ] HP Vertica Analytic Database (7.0.x) Page 1125 of 1539 SQL Reference Manual SQL Statements Parameters [ OR REPLACE ] When you supply this option, HP Vertica overwrites any existing view with the name viewname. If you do not supply this option and a view with that name already exists, CREATE VIEW returns an error. viewname Specifies the name of the view to create. The view name must be unique. Do not use the same name as any table, view, or projection within the database. If the view name is not provided, the user name is used as the view name. column-name [Optional] Specifies the list of names to be used as column names for the view. Columns are presented from left to right in the order given. If not specified, HP Vertica automatically deduces the column names from the query. query Specifies the query that the view executes. HP Vertica also uses the query to deduce the list of names to be used as columns names for the view if they are not specified. Use a SELECT statement to specify the query.The SELECT statement can refer to tables, temp tables, and other views. Permissions To create a view, the user must be a superuser or have CREATE privileges on the schema in which the view is created. Privileges required on base objects for the view owner must be granted directly; you cannot grant privileges on these objects using roles: l If a non-owner runs a SELECT query on the view, the view owner must also have SELECT ... WITH GRANT OPTION privileges on the view's base tables or views. This privilege must be directly granted to the owner; it should not be granted through a role. l If a view owner runs a SELECT query on the view, the owner must also have SELECT privilege directly granted (not through a role) on a view's base objects (table or view). Transforming a SELECT Query to Use a View When HP Vertica processes a query that contains a view, the view is treated as a subquery because the view name is replaced by the view's defining query. The following example defines a view (ship) and illustrates how a query that refers to the view is transformed. Create a new view, called ship: CREATE VIEW ship AS SELECT * FROM public.shipping_dimension; Review the original query, and then the transformed subquery version: HP Vertica Analytic Database (7.0.x) Page 1126 of 1539 SQL Reference Manual SQL Statements SELECT * FROM ship; SELECT * FROM (SELECT * FROM public.shipping_dimension) AS ship; Dropping a View Use the DROP VIEW statement to drop a view. Only the specified view is dropped. HP Vertica does not support CASCADE functionality for views, and it does not check for dependencies. Dropping a view causes any view that references it to fail. Renaming a View Use the ALTER VIEW statement to rename a view. Example => CREATE VIEW myview AS SELECT SUM(annual_income), customer_state FROM public.customer_dimension WHERE customer_key IN (SELECT customer_key FROM store.store_sales_fact) GROUP BY customer_state ORDER BY customer_state ASC; The following example uses the myview view with a WHERE clause that limits the results to combined salaries of greater than 2,000,000,000. => SELECT * FROM myview WHERE SUM > 2000000000; SUM | customer_state -------------+---------------2723441590 | AZ 29253817091 | CA 4907216137 | CO 3769455689 | CT 3330524215 | FL 4581840709 | IL 3310667307 | IN 2793284639 | MA 5225333668 | MI 2128169759 | NV 2806150503 | PA 2832710696 | TN 14215397659 | TX 2642551509 | UT (14 rows) HP Vertica Analytic Database (7.0.x) Page 1127 of 1539 SQL Reference Manual SQL Statements See Also l ALTER VIEW l SELECT l DROP VIEW l GRANT (View) l REVOKE (View) l CREATE LOCAL TEMPORARY VIEW DELETE Marks tuples as no longer valid in the current epoch, marking the records for deletion in the WOS, rather than deleting data from disk storage. By default, delete uses the WOS and if the WOS fills up, overflows to the ROS. You cannot delete records from a projection. Syntax DELETE [ /*+ direct */ ] [ /*+ label(label-name)*/ ] ... FROM [[db-name.]schema.]table ... WHERE Clause Parameters /*+ direct */ Writes the data directly to disk (ROS) bypassing memory (WOS). Note: If you delete using the direct hint, you still need to issue a COMMIT or ROLLBACK command to finish the transaction. /*+ label(label-name)*/ Passes a user-defined label to a query as a hint, letting you quickly identify labeled queries for profiling and debugging. See Query Labeling in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1128 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). When using more than one schema, specify the schema that contains the table in your DELETE statement. table Specifies the name of a base table or temporary table. Permissions Table owner or user with GRANT OPTION is grantor. l DELETE privilege on table l USAGE privilege on schema that contains the table l SELECT privilege on the referenced table when executing a DELETE statement that references table column values in a WHERE or SET clause Using the DELETE Statement DELETE statements support subqueries and joins, which is useful for deleting values in a table based on values that are stored in other tables. See the Examples section below. The delete operation deletes rows that satisfy the WHERE clause from the specified table. On completing successfully, the DELETE statement returns a count of the number of deleted rows. A count of 0 is not an error, but indicates that no rows matched the condition. If no WHERE clause exists, the statement deletes all table rows, resulting in an empty table. To remove all rows from a temporary table, use a DELETE statement with no WHERE clause. In this case, the rows are not stored in the system, which improves performance. The DELETE statement removes all rows, but preserves the columns, projections, and constraints, thus making it easy to re-populate the table. If you include a WHERE clause with a DELETE statement on a temporary table, DELETE behaves the same as for base tables, marking all delete vectors for storage, and you lose any performance benefits. If the delete operation succeeds on temporary tables, you cannot roll back to a prior savepoint. HP Vertica Analytic Database (7.0.x) Page 1129 of 1539 SQL Reference Manual SQL Statements To truncate a temporary table, without ending the transaction, use DELETE FROM temp_table. Examples To use the DELETEor UPDATE statements with a WHERE Clause, the user must have both SELECT and DELETEprivileges on the table. The following command truncates a temporary table called temp1: => DELETE FROM temp1; The following command deletes all records from base table T where C1 = C2 - C1. => DELETE FROM T WHERE C1=C2-C1; The following command deletes all records from the customer table in the retail schema where the state attribute is in MA or NH: => DELETE FROM retail.customer WHERE state IN ('MA', 'NH'); For examples on how to nest a subquery within a DELETE statement, see Subqueries in UPDATE and DELETE in the Programmer's Guide. See Also l DROP TABLE l TRUNCATE TABLE l Bulk Deleting and Purging Data l Best Practices for DELETE and UPDATE DISCONNECT Closes a previouslyestablished connection to another HP Vertica database. You must have previously used the CONNECT statement to perform a COPY FROM VERTICA or EXPORT TO VERTICA statement. Syntax DISCONNECT database-name Parameters database-name The name of the database whose connection to close. HP Vertica Analytic Database (7.0.x) Page 1130 of 1539 SQL Reference Manual SQL Statements Permissions No special permissions required. Example => DISCONNECT ExampleDB; DISCONNECT See Also l CONNECT l COPY FROM VERTICA l EXPORT TO VERTICA DROP AGGREGATE FUNCTION Drops a User Defined Aggregate Function (UDAF) from the HP Vertica catalog. Syntax DROP AGGREGATE FUNCTION [[db-name.]schema.]function-name [, ...] ... ( [ [ argname ] argtype [, ...] ] ) Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). HP Vertica Analytic Database (7.0.x) Page 1131 of 1539 SQL Reference Manual SQL Statements function-name Specifies a name of the SQL function to drop. If the function name is schema-qualified, the function is dropped from the specified schema (as noted above). argname Specifies the name of the argument, typically a column name. argtype Specifies the data type for argument(s) that are passed to the function. Argument types must match HP Vertica type names. See SQL Data Types. Notes l To drop a function, you must specify the argument types because there could be several functions that share the same name with different parameters. l HP Vertica does not check for dependencies, so if you drop a SQL function where other objects reference it (such as views or other SQL functions), HP Vertica returns an error when those objects are used and not when the function is dropped. Permissions Only the superuser or owner can drop the function. Example The following command drops the ag_avg function: => DROP AGGREGATE FUNCTION ag_avg(numeric); DROP AGGREGATE FUNCTION See Also l ALTER FUNCTION l CREATE AGGREGATE FUNCTION l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Using User-Defined SQL Functions HP Vertica Analytic Database (7.0.x) Page 1132 of 1539 SQL Reference Manual SQL Statements l Developing and Using User Defined Extensions l Developing a User Defined Aggregate Function DROP FAULT GROUP A drop operation removes the specified fault group and its child fault groups, placing all nodes under the parent of the dropped fault group. To drop all fault groups, use ALTER DATABASE..DROP ALL FAULT GROUP syntax. To add an orphaned node back to a fault group, you must manually re-assign it to a new or existing fault group using a combination of CREATE FAULT GROUP and ALTER FAULT GROUP..ADD NODE statements. Tip: For a list of all fault groups defined in the cluster, query the V_CATALOG.FAULT_ GROUPS system table. Syntax DROP FAULT GROUP name Parameters name Specifies the name of the fault group to drop. Permissions Must be a superuser to drop a fault group. Example The following example drops the group2 fault group from the cluster: exampledb=> DROP FAULT GROUP group2; DROP FAULT GROUP See Also l V_CATALOG.FAULT_GROUPS and V_CATALOG.CLUSTER_LAYOUT l Fault Groups in the Administrator's Guide l High Availability With Fault Groups in the Concepts Guide HP Vertica Analytic Database (7.0.x) Page 1133 of 1539 SQL Reference Manual SQL Statements DROP FUNCTION Drops a SQL function or User Defined Function (UDF) from the HP Vertica catalog. Syntax DROP FUNCTION [[db-name.]schema.] function-name [, ...] ... ( [ [ argname ] argtype [, ...] ] ) Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). function-name Specifies a name of the SQL function to drop. If the function name is schema-qualified, the function is dropped from the specified schema (as noted above). argname Specifies the name of the argument, typically a column name. argtype Specifies the data type for argument(s) that are passed to the function. Argument types must match HP Vertica type names. See SQL Data Types. Permissions Must be a superuser, function owner, or schema owner to drop a function. Notes l To drop a function, you must specify the argument types because there could be several functions that share the same name with different parameters. HP Vertica Analytic Database (7.0.x) Page 1134 of 1539 SQL Reference Manual SQL Statements l HP Vertica does not check for dependencies, so if you drop a SQL function where other objects reference it (such as views or other SQL functions), HP Vertica returns an error when those objects are used and not when the function is dropped. Example The following command drops the zerowhennull function in the macros schema: => DROP FUNCTION macros.zerowhennull(x INT); DROP FUNCTION See Also l ALTER FUNCTION l CREATE FUNCTION (SQL Functions) l GRANT (User Defined Extension) l REVOKE (User Defined Extension) l USER_FUNCTIONS l Using User-Defined SQL Functions DROP SOURCE Drops a User Defined Load Source function from the HP Vertica catalog. Syntax DROP SOURCE [[db-name.]schema.]source-name(); HP Vertica Analytic Database (7.0.x) Page 1135 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). source-name Specifies the name of the source function to drop. If the function name is schema-qualified, the function is dropped from the specified schema (as noted above). You must include empty parenthesis after the function name. Permissions Only the superuser or owner can drop the source function. Example The following command drops the curl source function: => drop source curl(); DROP SOURCE See Also l ALTER FUNCTION l CREATE SOURCE l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions HP Vertica Analytic Database (7.0.x) Page 1136 of 1539 SQL Reference Manual SQL Statements DROP FILTER Drops a User Defined Load Filter function from the HP Vertica catalog. Syntax DROP FILTER [[db-name.]schema.]filter-name(); Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). filter-name Specifies the name of the filter function to drop. If the function name is schema-qualified, the function is dropped from the specified schema (as noted above). You must include empty parenthesis after the function name. Permissions Only the superuser or owner can drop the filter function. Example The following command drops the Iconverter filter function:: => drop filter Iconverter(); DROP FILTER HP Vertica Analytic Database (7.0.x) Page 1137 of 1539 SQL Reference Manual SQL Statements See Also l ALTER FUNCTION l CREATE FILTER l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions DROP PARSER Drops a User Defined Load Parserfunction from the HP Vertica catalog. Syntax DROP PARSER[[db-name.]schema.]parser-name(); Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). parser-name Specifies the name of the parser function to drop. If the function name is schema-qualified, the function is dropped from the specified schema (as noted above). You must include empty parenthesis after the function name. Permissions Only the superuser or owner can drop the parser function. HP Vertica Analytic Database (7.0.x) Page 1138 of 1539 SQL Reference Manual SQL Statements Example The following command drops the BasicIntegerParser parser function: => DROP PARSER BasicIntegerParser(); DROP PARSER See Also l ALTER FUNCTION l CREATE PARSER l GRANT (Function) l REVOKE (Function) l USER_FUNCTIONS l Developing User Defined Load (UDL) Functions DROP LIBRARY Removes a shared library from the database. The user defined functions (UDFs) in the library are no longer available. See Using User Defined Functions in the Programmer's Guide for details. Syntax DROP LIBRARY [[db-name.]schema.]library_name [CASCADE] HP Vertica Analytic Database (7.0.x) Page 1139 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). library_name The name of the library to drop. This must be the same name given to CREATE LIBRARY to load the library. [CASCADE] Drops any functions that have been defined using the library. This statement fails if CASCADE is not specified and there is one or more UDFs that have been defined using the library. Permissions Must be a superuser to drop a library. Notes The library file is deleted from the managed directories on the HP Vertica nodes. Example To drop the library named MyFunctions: => DROP LIBRARY MyFunctions CASCADE; DROP NETWORK INTERFACE Removes a network interface from HP Vertica. You can use the CASCADE option to also remove the network interface from any node definition. (See Identify the Database or Node(s) used for Import/Export for more information.) HP Vertica Analytic Database (7.0.x) Page 1140 of 1539 SQL Reference Manual SQL Statements Syntax DROP NETWORK INTERFACE network-interface-name [CASCADE] Parameters The parameters are defined as follows: network-interface-name The network interface you want to remove. Permissions Must be a superuser to drop a network interface. DROP PROCEDURE Removes an external procedure from HP Vertica. Syntax DROP PROCEDURE [[db-name.]schema.]name ( [ argname ] [ argtype ] [,...] ) Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). name Specifies the name of the procedure to be dropped. argname [Optional] The argument name or names used when creating the procedure. argtype Optional unless an argument type was specified when the procedure was created. The argument type or types used when creating the procedure. Permissions Must be a superuser or procedure owner and have USAGE privilege on schema that contain procedure or be the schema owner. HP Vertica Analytic Database (7.0.x) Page 1141 of 1539 SQL Reference Manual SQL Statements Notes l Only the database superuser can drop procedures. l Only the reference to the procedure is removed. The external file remains in the /procedures directory on each node in the database. Example => DROP PROCEDURE helloplanet(arg1 varchar); See Also l CREATE PROCEDURE DROP PROFILE Removes a profile from the database. Only the superuser can drop a profile. Syntax DROP PROFILE name [, ...] [ CASCADE ] Parameters name The name of one or more profiles (separated by commas) to be removed. CASCADE Moves all users assigned to the profile or profiles being dropped to the DEFAULT profile. If you do not include CASCADE in the DROP PROFILE command and a targeted profile has users assigned to it, the command returns an error. Permissions Must be a superuser to drop a profile. Notes You cannot drop the DEFAULT profile. HP Vertica Analytic Database (7.0.x) Page 1142 of 1539 SQL Reference Manual SQL Statements See Also l ALTER PROFILE l CREATE PROFILE DROP PROJECTION Marks a projection to be dropped from the catalog so it is unavailable to user queries. Syntax DROP PROJECTION { base-projname | projname-node [ , ...] } ... [ RESTRICT | CASCADE ] Parameters base-projname Specifies the base projection to drop, along with all replicated buddies on all nodes simultaneously. When using more than one schema, specify the schema containing the base projection. projname can be 'projname' or 'schema.projname'. projname-node Drops only the specified projection on the specified node.When using more than one schema, specify the schema that contains the projection to drop. projname can be 'projname' or 'schema.projname'. RESTRICT Drops the projection only if it does not contain any objects. RESTRICT is the default. CASCADE Drops the projection even if it contains one or more objects. Permissions To drop a projection, the user must own the anchor table for which the projection was created and have USAGE privilege on schema that contains the projection OR be the schema owner. Notes To prevent data loss and inconsistencies, tables must contain one superprojection, so DROP PROJECTION fails if a projection is the table's only superprojection. In such cases, use the DROP TABLE command. To a drop all projections: => DROP PROJECTION prejoin_p; HP Vertica Analytic Database (7.0.x) Page 1143 of 1539 SQL Reference Manual SQL Statements To drop the projection on node 2: => DROP PROJECTION prejoin_p_site02; Alternatively, you can issue a command like the following, which drops projections on a particular schema: => DROP PROJECTION schema1.fact_proj_a, schema1.fact_proj_b; If you want to drop a set of buddy projections, you could be prevented from dropping them individually using a sequence of DROP PROJECTION statements due to K-safety violations. See MARK_DESIGN_KSAFE for details. See Also l CREATE PROJECTION l DROP TABLE l GET_PROJECTIONS, GET_TABLE_PROJECTIONS l GET_PROJECTION_STATUS MARK_DESIGN_KSAFE l l DROP RESOURCE POOL Drops a user-created resource pool. All memory allocated to the pool is returned back to the GENERAL pool. Syntax DROP RESOURCE POOL pool-name Parameters pool-name Specifies the name of the resource pool to be dropped. Permissions Must be a superuser to drop a resource pool. HP Vertica Analytic Database (7.0.x) Page 1144 of 1539 SQL Reference Manual SQL Statements Transferring Resource Requests Any requests queued against the pool are transferred to the GENERAL pool according to the priority of the pool compared to the GENERAL pool. If the pool’s priority is higher than the GENERAL pool, the requests are placed at the head of the queue; otherwise the requests are placed at the end of the queue. Any users who are using the pool are switched to use the GENERAL pool with a NOTICE: NOTICE: Switched the following users to the General pool: username DROP RESOURCE POOL returns an error if the user does not have permission to use the GENERAL pool. Existing sessions are transferred to the GENERAL pool regardless of whether the session's user has permission to use the GENERAL pool. This can result in additional user privileges if the pool being dropped is more restrictive than the GENERAL pool. To prevent giving users additional privileges, follow this procedure to drop restrictive pools: 1. Revoke the permissions on the pool for all users. 2. Close any sessions that had permissions on the pool. 3. Drop the resource pool. Example The following command drops the resource pool that was created for the CEO: => DROP RESOURCE POOL ceo_pool; See Also ALTER RESOURCE POOL l CREATE RESOURCE POOL l l DROP ROLE Removes a role from the database. Only the database superuser can drop a role. Use the CASCADE option to drop a role that is assigned to one or more users or roles. Syntax DROP ROLE role [CASCADE]; HP Vertica Analytic Database (7.0.x) Page 1145 of 1539 SQL Reference Manual SQL Statements Parameters role The name of the role to drop CASCADE Revoke the role from users and other roles before dropping the role Permissions Must be a superuser to drop a role. Examples => DROP ROLE appadmin; NOTICE: User bob depends on Role appadmin ROLLBACK: DROP ROLE failed due to dependencies DETAIL: Cannot drop Role appadmin because other objects depend on it HINT: Use DROP ROLE ... CASCADE to remove granted roles from the dependent users/roles => DROP ROLE appadmin CASCADE; DROP ROLE See Also l ALTER ROLE RENAME l CREATE ROLE DROP SCHEMA Permanently removes a schema from the database. Be sure that you want to remove the schema before you drop it, because DROP SCHEMA is an irreversible process. Use the CASCADE parameter to drop a schema containing one or more objects. Syntax DROP SCHEMA [db-name.]schema [, ...] [ CASCADE | RESTRICT ] Parameters [db-name.] [Optional] Specifies the current database name. Using a database name prefix is optional, and does not affect the command in any way. You must be connected to the specified database. schema Specifies the name of the schema to drop. HP Vertica Analytic Database (7.0.x) Page 1146 of 1539 SQL Reference Manual SQL Statements CASCADE Drops the schema even if it contains one or more objects. RESTRICT Drops the schema only if it does not contain any objects (the default). Privileges Schema owner Restrictions You cannot drop the PUBLIC schema. Notes l A schema owner can drop a schema even if the owner does not own all the objects within the schema. All the objects within the schema are also dropped. l If a user is accessing an object within a schema that is in the process of being dropped, the schema is not deleted until the transaction completes. l Canceling a DROP SCHEMA statement can cause unpredictable results. Examples The following example drops schema S1 only if it doesn't contain any objects: => DROP SCHEMA S1; The following example drops schema S1 whether or not it contains objects: => DROP SCHEMA S1 CASCADE; DROP SEQUENCE Removes the specified sequence number generator. Syntax DROP SEQUENCE [[db-name.]schema.]name [ , ... ] HP Vertica Analytic Database (7.0.x) Page 1147 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). When using more than one schema, specify the schema that contains the sequence to drop. name Specifies the name of the sequence to drop. Permissions To drop a sequence, the user must be the sequence owner or schema owner. Notes l For sequences specified in a table's default expression, the default expression fails the next time you try to load data. HP Vertica does not check for these instances. l The CASCADE keyword is not supported. Sequences used in a default expression of a column cannot be dropped until all references to the sequence are removed from the default expression. Example The following command drops the sequence named sequential. => DROP SEQUENCE sequential; See Also l ALTER SEQUENCE l CREATE SEQUENCE l CURRVAL l GRANT (Sequence) l NEXTVAL HP Vertica Analytic Database (7.0.x) Page 1148 of 1539 SQL Reference Manual SQL Statements l l DROP SUBNET Removes a subnet from HP Vertica. You can use the CASCADE option to also remove the subnet from any database definition. (See Identify the Database or Node(s) used for Import/Export for more information.) Syntax DROP SUBNET subnet-name [CASCADE] Parameters The parameters are defined as follows: subnet-name The subnet you want to remove. If you remove a subnet, be sure your database is not configured to allow export on the public subnet. (See Identify the Database or Node(s) used for Import/Export for more information.) Permissions Must be a superuser to drop a subnet. DROP TABLE Removes a table and, optionally, its associated projections. Syntax DROP TABLE [ IF EXISTS ] [[db-name.]schema.]table [, ...] [ CASCADE ] Parameters [IF EXISTS] If specified, DROP TABLE does not report an error if one or of the tables to be dropped does not exist. This clause is useful in SQL scripts where you want to drop a table if it exists before recreating it. HP Vertica Analytic Database (7.0.x) Page 1149 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). table Specifies the table name. When using more than one schema, specify the schema that contains the table in the DROP TABLE statement. CASCADE [Optional] Drops all projections that include the table. NOTE: You cannot use the CASCADE option when dropping external tables. For more information, see Working with External Tables in the Administrator's Guide. Permissions Table owner with USAGE privilege on schema that contains the table or schema owner Note: The schema owner can drop a table but cannot truncate a table. Notes l Canceling a DROP TABLE statement can cause unpredictable results. l Make sure that all other users have disconnected before using DROP TABLE. l Views that reference a table that is dropped and then replaced by another table with the same name continue to function and use the contents of the new table, as long as the new table contains the same columns and column names. l Use the multiple projection syntax in K-safe clusters. Examples If you try to drop a table with associated projections, a message listing the projections displays. For example: HP Vertica Analytic Database (7.0.x) Page 1150 of 1539 SQL Reference Manual SQL Statements => DROP TABLE d1; NOTICE: Constraint - depends on Table d1 NOTICE: Projection d1p1 depends on Table d1 NOTICE: Projection d1p2 depends on Table d1 NOTICE: Projection d1p3 depends on Table d1 NOTICE: Projection f1d1p1 depends on Table d1 NOTICE: Projection f1d1p2 depends on Table d1 NOTICE: Projection f1d1p3 depends on Table d1 ERROR: DROP failed due to dependencies: Cannot drop Table d1 because other objects depend on it HINT: Use DROP ... CASCADE to drop the dependent objects too. => DROP TABLE d1 CASCADE; DROP TABLE => CREATE TABLE mytable (a INT, b VARCHAR(256)); CREATE TABLE => DROP TABLE IF EXISTS mytable; DROP TABLE => DROP TABLE IF EXISTS mytable; -- Doesn't exist NOTICE: Nothing was dropped DROP TABLE See Also l DELETE l DROP PROJECTION l TRUNCATE TABLE l Adding Nodes l Bulk Deleting and Purging Data DROP TRANSFORM FUNCTION Drops a User Defined Transform Function (UDTF) from the HP Vertica catalog. Syntax DROP TRANSFORM FUNCTION [[db-name.]schema.]name [, ...] ... ( [ [ argname ] argtype [, ...] ] ) HP Vertica Analytic Database (7.0.x) Page 1151 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). name Specifies the name of the transform function to drop. argname Specifies the name of the argument, typically a column name. argtype Specifies the data type for argument(s) that are passed to the function. Argument types must match HP Vertica type names. See SQL Data Types. Permissions Must be a superuser, function owner, or schema owner to drop a function. Notes To drop a transform function, you must specify the argument types because there could be several functions that share the same name with different parameters. Example The following command drops the tokenize UDTF in the macros schema: => DROP TRANSFORM FUNCTION macros.tokenize(varchar); DROP TRANSFORM FUNCTION See Also l CREATE TRANSFORM FUNCTION l Deploying and Using User Defined Transforms DROP USER Removes a name from the list of authorized database users. HP Vertica Analytic Database (7.0.x) Page 1152 of 1539 SQL Reference Manual SQL Statements Syntax DROP USER name [, ...] [ CASCADE ] Parameters name Specifies the name or names of the user to drop. CASCADE [Optional] Drops all user-defined objects created by the user dropped, including schema, table and all views that reference the table, and the table's associated projections. Permissions Must be a superuser to drop a user. Examples DROP USER fails if objects exist that were created by the user, such as schemas, and tables and their associated projections: => DROP USER user1; NOTICE: Table T_tbd1 depends on User user1 ROLLBACK: DROP failed due to dependencies DETAIL: Cannot drop User user1 because other objects depend on it HINT: Use DROP ... CASCADE to drop the dependent objects too DROP USER CASCADE succeeds regardless of any pre-existing user-defined objects. The statement forcibly drops all user-defined objects, such as schemas, tables and their associated projections: => DROP USER user1 CASCADE; Caution: Tables owned by the user being dropped cannot be recovered after you issue DROP USER CASCADE. DROP USER succeeds if no user-defined objects exist (no schemas, tables or projections defined by the user): => CREATE USER user2; CREATE USER => DROP USER user2; DROP USER HP Vertica Analytic Database (7.0.x) Page 1153 of 1539 SQL Reference Manual SQL Statements See Also l ALTER USER l CREATE USER DROP VIEW Removes the specified view. This statement drops only the specified view. HP Vertica does not support a cascade parameter for views, nor does it check for dependencies on the dropped view. Any other views that reference the dropped view will fail. If you drop a view and replace it with another view or table with the same name and column names, any views dependent on the dropped view continue to function using the new view. If you change the column data type in the new view, the server coerces the old data type to the new one if possible. Otherwise, it returns an error. Syntax DROP VIEW name [ , ... ] Parameters name Specifies the name of the view to drop. Permissions To drop a view, the user must be the view owner and have USAGE privileges on the schema or be the schema owner. Examples => DROP VIEW myview; END Ends the current transaction and makes all changes that occurred during the transaction permanent and visible to other users. Syntax COMMIT [ WORK | TRANSACTION ] HP Vertica Analytic Database (7.0.x) Page 1154 of 1539 SQL Reference Manual SQL Statements Parameters WORK | TRANSACTION Have no effect; they are optional keywords for readability. Permissions No special permissions required. Notes COMMIT is a synonym for END. See Also l l l BEGIN l ROLLBACK l START TRANSACTION EXPLAIN Returns the query plan execution strategy to standard output. Syntax EXPLAIN { SELECT... | INSERT... | UPDATE... } Returns A compact representation of the query plan, laid out hierarchically. For example: => EXPLAIN SELECT * FROM hTicks h FULL OUTER JOIN aTicks a ON (h.time = a.time); ------------------------------ QUERY PLAN DESCRIPTION: -----------------------------Access Path: +-JOIN HASH [FullOuter] [Cost: 31, Rows: 4 (NO STATISTICS)] (PATH ID: 1) Outer (FILTER) Inner (FILTER) | Join Cond: (h."time" = a."time") | Execute on: All Nodes | +-- Outer -> STORAGE ACCESS for h [Cost: 15, Rows: 4 (NO STATISTICS)] (PATH ID: 2) | | Projection: public.HTicks_node0001 HP Vertica Analytic Database (7.0.x) Page 1155 of 1539 SQL Reference Manual SQL Statements | | | | | | | Materialize: h.stock, h."time", h.price | Execute on: All Nodes +-- Inner -> STORAGE ACCESS for a [Cost: 15, Rows: 4 (NO STATISTICS)] (PATH ID: 3) | Projection: public.ATicks_node0001 | Materialize: a.stock, a."time", a.price | Execute on: All Nodes Permissions Privileges required to run this command are the same privileges required to run the query you preface with the EXPLAIN keyword. Notes l Information about understanding the EXPLAIN command's output is described in Understanding Query Plans in the Administrator's Guide. l Query plans rely on reasonably representative statistics of your data. See Collecting Statistics in the Administrator's Guide for details. EXPORT TO VERTICA Exports an entire table, columns from a table, or the results of a SELECT statement to another HP Vertica database. Exported data is written to the target database using AUTO mode. Exporting data to another database requires first establishing a connection to the target database using the CONNECT statement. See Exporting Data for more setup information. When loading data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. You can export data from an earlier HP Vertica release, as long as the earlier release is a version of the last major release. For instance, for Version 6.x, you can export data from any version of 5.x, but not from 4.x. By default, using EXPORT TO VERTICA to copy data to another database occurs over the HP Vertica private network. Connecting to a public network requires some configuration. For information about using this statement to copy data across a public network, see Importing/Exporting From Public Networks. Syntax EXPORT TO VERTICA database.[dest-schema.]dest-table ... [(dest-column [,dest-column2,...])] ... { AS SELECT select-expression ... | FROM [source-schema.]source-table ... [(source-column [,source-column2,...])]}; HP Vertica Analytic Database (7.0.x) Page 1156 of 1539 SQL Reference Manual SQL Statements Parameters database A string containing the name of the database to receive the exported data. There must be an active connection to this database for the export to succeed. .[dest-schema.] dest-table The table to store the exported data (schema specification is optional). This table must already exist. dest-column [,dest-column2,...] A list of columns in the target table to store the exported data. AS SELECT select-expression A standard SELECT expression that selects the data to be exported. See SELECT for the syntax. FROM [source-schema.] source-table The table that contains the data to be exported (schema optional) source-column [,source-column2,...] A list of the columns in the source table to export. If present, only these columns are exported. Notes Importing and exporting data fails if either side of the connection is a single-node cluster installed to localhost, or you do not specify a host name or IP address. Permissions l SELECT privileges on the source table l USAGE privilege on source table schema l INSERT privileges for the destination table in target database l USAGE privilege on destination table schema Source and Destination Column Mapping To complete a successful export, the EXPORT TO statement maps source table columns to destination table columns. If you do not supply a list of source and destination columns, EXPORT attempts to match columns in the source table with corresponding columns in the destination table. Auto-projections for the target table are similar to the projections for the source table. You can optionally supply lists of either source columns to be copied, columns in the destination table where data should be stored, or both. Specifying the lists lets you select a subset of source table columns to copy to the destination table. Since source and destination lists are not required, results differ depending on which list is present. The following table presents the results of supplying one or more lists: HP Vertica Analytic Database (7.0.x) Page 1157 of 1539 SQL Reference Manual SQL Statements Omit Source Column List Supply Source Column List Matches all columns in the source table to columns in the destination table. The number of columns in Omit the two tables need not match, Destination but the destination table must not Column have fewer columns than the List source. Copies content only from the supplied list of source table columns. Matches columns in the destination table to columns in the source list. The number of columns in the two tables need not match, but the destination table must not have fewer columns than the source. Matches columns in the destination column list to columns Supply in the source. The number of Destination columns in the destination list Column must match the number of List columns in the source table. Matches columns from the source table column lists to those in the destination table. The lists must have the same number of columns. Examples First, open the connection to the other database, then perform a simple export of an entire table to an identical table in the target database. => CONNECT TO VERTICA testdb USER dbadmin PASSWORD '' ON 'VertTest01',5433; CONNECT => EXPORT TO VERTICA testdb.customer_dimension FROM customer_dimension; Rows Exported --------------23416 (1 row) The following statement demonstrates exporting a portion of a table using a simple SELECT statement. => EXPORT TO VERTICA testdb.ma_customers AS SELECT customer_key, customer_name, annual_in come -> FROM customer_dimension WHERE customer_state = 'MA'; Rows Exported --------------3429 (1 row) This statement exports several columns from one table to several different columns in the target database table using column lists. Remember that when supplying both a source and destination column list, the number of columns must match. => EXPORT TO VERTICA testdb.people (name, gender, age) FROM customer_dimension -> (customer_name, customer_gender, customer_age); Rows Exported --------------23416 HP Vertica Analytic Database (7.0.x) Page 1158 of 1539 SQL Reference Manual SQL Statements (1 row) You can export tables (or columns) containing Identity and Auto-increment values, but the sequence values are not incremented automatically at their destination. You can also use the EXPORT TO VERTICA statement with a SELECT AT EPOCH LATEST expression to include data from the latest committed DML transaction. See Also l CONNECT l COPY FROM VERTICA l DISCONNECT HP Vertica Analytic Database (7.0.x) Page 1159 of 1539 SQL Reference Manual SQL Statements GRANT Statements GRANT statements, described in this section, allow you to grant privileges on database objects to specific users: l GRANT (Database) l GRANT (Procedure) l GRANT (Resource Pool) l GRANT (Role) l GRANT (Schema) l GRANT (Sequence) l GRANT (Storage Location) l GRANT (Table) l GRANT (User Defined Extension) l GRANT (View) GRANT (Database) Grants the right to create schemas within the database to a user or role. By default, only the superuser has the right to create a database schema. Syntax GRANT { ... { CREATE [, ...] ... | { TEMPORARY | TEMP } ... | ALL [ PRIVILEGES ] ... | CONNECT } } ... ON DATABASE database-name [, ...] ... TO { username | rolename } [, ...] ... [ WITH GRANT OPTION ] Parameters CREATE Allows the user to create schemas within the specified database. TEMPORARY | TEMP Allows the user to create temp tables in the database. Note: This privilege is provided by default with CREATE USER. HP Vertica Analytic Database (7.0.x) Page 1160 of 1539 SQL Reference Manual SQL Statements CONNECT Allows the user to connect to a database. ALL Applies to all privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. database-name Identifies the database in which to grant the privilege. username | rolename Grants the privilege to the specified user or role. WITH GRANT OPTION Allows the recipient of the privilege to grant it to other users. Example The following example grants user Fred the right to create schemas on vmartdb. => GRANT CREATE ON DATABASE vmartdb TO Fred; See Also REVOKE (Database) l l GRANT (Procedure) Grants privileges on a procedure to a database user or role. Only the superuser can grant privileges to a procedure. To grant privileges to a schema containing the procedure, users must have USAGE privileges. See GRANT (Schema). Syntax GRANT { EXECUTE | ALL } ON PROCEDURE [ [ db-name.]schema.]procedure-name [, ...] ( [ argname ] argtype [,... ] ) TO { username | role | PUBLIC } [, ...] Parameters { EXECUTE | ALL } HP Vertica Analytic Database (7.0.x) The type of privilege to grant the procedure. Either EXECUTE or ALL are applicable privileges to grant. When using more than one schema, specify the schema that contains the procedure. Page 1161 of 1539 SQL Reference Manual SQL Statements [[ db-name.]schema-name.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). procedure-name The SQL or User Defined procedure on which to grant the privilege. If using more than one schema, you must specify the schema that contains the procedure. argname The optional argument name for the procedure. argtype The required argument data type or types of the procedure. { username | role | PUBLIC } [,...] The recipient of the procedure privileges, which can be one or more users, one or more roles, or all users and roles (PUBLIC). l username—Indicates a specific user l role—Specifies a particular role l PUBLIC—Indicates that all users and roles have granted privileges to the procedure. Example The following command grants EXECUTE privileges on the tokenize procedure to users Bob and Jules, and to the Operator role: => GRANT EXECUTE ON PROCEDURE tokenize(varchar) TO Bob, Jules, Operator; See Also REVOKE (Procedure) l l HP Vertica Analytic Database (7.0.x) Page 1162 of 1539 SQL Reference Manual SQL Statements GRANT (Resource Pool) Grants privileges on one or more resource pools to a database user or role. Once granted usage rights, users can switch to using the resource pool with ALTER USER (username) or with SET SESSION RESOURCE POOL. Syntax GRANT USAGE ON RESOURCE POOL resource-pool [, ...] TO { username | role | PUBLIC } [, ...] Parameters resource-pool The resource pools on which to grant the privilege. { username | role | PUBLIC } [,...] The recipient of the procedure privileges, which can be one or more users, one or more roles, or all users and roles (PUBLIC). l username—Indicates one or more user names. l role—Indicates one or more roles. l PUBLIC—Indicates that all users and roles have granted privileges to the procedure. See Also REVOKE (Resource Pool) l l GRANT (Role) Adds a predefined role to users or other roles. Granting a role does not activate the role automatically; the user must enable it using the SET ROLE command. Granting a privilege to a role immediately affects active user sessions. When you grant a new privilege, it becomes immediately available to every user with the role active. Syntax GRANT role [,...] ... TO { user | role | PUBLIC } [, ...] ... [ WITH ADMIN OPTION ]; HP Vertica Analytic Database (7.0.x) Page 1163 of 1539 SQL Reference Manual SQL Statements Parameters role [,...] The name of one or more roles to be granted to users or roles user | role | PUBLIC The name of a user or other role to be granted the role. If the keyword PUBLIC is supplied, then all users have access to the role. WITH ADMIN OPTION Grants users and roles administrative privileges for the role. They are able to grant the role to and revoke the role from other users or roles. Notes HP Vertica will return a NOTICE if you grant a role with or without admin option, to a grantee who has already been granted that role. For example: => GRANT commentor to Bob; NOTICE 4622: Role "commentor" was already granted to user "Bob" Creating Roles These examples create three roles, appdata, applogs, and appadmin, and grant one of the roles to a user, bob: => CREATE ROLE appdata; CREATE ROLE => CREATE ROLE applogs; CREATE ROLE => CREATE ROLE appadmin; CREATE ROLE => GRANT appdata TO bob; GRANT ROLE Activating a Role After granting a role to a user, the role must be activated. You can activate a role on a session basis, or as part of the user's login. To activate a role for a user's session: => CREATE ROLE appdata; CREATE ROLE => GRANT appdata TO bob; GRANT ROLE => SET ROLE appdata To activate a role as part of the the user's login: HP Vertica Analytic Database (7.0.x) Page 1164 of 1539 SQL Reference Manual SQL Statements => CREATE ROLE appdata; CREATE ROLE => GRANT appdata TO bob; GRANT ROLE => ALTER USER bob DEFAULT ROLE appdata; Granting One Role To Another Grant two roles to another role: => GRANT appdata, applogs TO appadmin; -- grant to other roles GRANT ROLE Now, any privileges assigned to either appdata or applogs are automatically assigned to appadmin as well. Checking for Circular References When you grant one role to another role, HP Vertica combines the newly granted role's permissions with the existing role's permissions. HP Vertica also checks for circular references when you grant one role to another. The GRANT ROLE function fails with an error if a circular reference is found. => GRANT appadmin TO appdata; WARNING: Circular assignation of roles is not allowed HINT: Cannot grant appadmin to appdata GRANT ROLE Granting Administrative Privileges A superuser can assign a user or role administrative access to a role by supplying the optional WITH ADMIN OPTION argument to the GRANT statement. Administrative access allows the user to grant and revoke access to the role for other users (including granting them administrative access). Giving users the ability to grant roles lets a superuser delegate role administration to other users. As with all user privilege models, database superusers should be cautious when granting any user a role with administrative privileges. For example, if the database superuser grants two users a role with administrative privileges, both users can revoke the role of the other user. This example shows granting the appadmin role (with administrative privileges) to users bob and alice. After each user has been granted the appadmin role, either use can connect as the other will full privileges. => GRANT appadmin TO bob, alice WITH ADMIN OPTION; GRANT ROLE => \connect - bob You are now connected as user "bob". => REVOKE appadmin FROM alice; HP Vertica Analytic Database (7.0.x) Page 1165 of 1539 SQL Reference Manual SQL Statements REVOKE ROLE See Also REVOKE (Role) l l GRANT (Schema) Grants privileges on a schema to a database user or role. Syntax GRANT { ... { CREATE | USAGE } [ , ... ] ... | ALL [ PRIVILEGES ] } ... ON SCHEMA [db-name.]schema [ , ... ] ... TO { username | role | PUBLIC } [ , ... ] ... [ WITH GRANT OPTION ] Parameters CREATE Allows the user read access to the schema and the right to create tables and views within the schema. USAGE Allows the user access to the objects contained within the schema. This allows the user to look up objects within the schema. Note that the user must also be granted access to the individual objects. See the GRANT TABLE and GRANT VIEW statements. ALL Applies to all privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. [db-name.] [Optional] Specifies the current database name. Using a database name prefix is optional, and does not affect the command in any way. You must be connected to the specified database. schema Identifies the schema to which you are granting privileges. username Grants the privilege to a specific user. role Grants the privilege to a specific role. PUBLIC Grants the privilege to all users. WITH GRANT OPTION Allows the recipient of the privilege to grant it to other users. HP Vertica Analytic Database (7.0.x) Page 1166 of 1539 SQL Reference Manual SQL Statements Notes Newly-created users do not have access to schema PUBLIC by default. Make sure to grant USAGE on schema PUBLIC to all users you create. See Also REVOKE (Schema) l l GRANT (Sequence) Grants privileges on a sequence generator to a user or role. Optionally grants privileges on all sequences within one or more schemas. Syntax GRANT { SELECT | ALL [ PRIVILEGES ] }... ON SEQUENCE [[db-name.]schema.]sequence-name [ , ... ] ... | ON ALL SEQUENCES IN SCHEMA schema-name [, ...] ... TO { username | role | PUBLIC } [ , ... ] ... [ WITH GRANT OPTION ] Parameters SELECT Allows the right to use both the CURRVAL() and NEXTVAL() functions on the specified sequence. PRIVILEGES Is for SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). sequence-name Specifies the sequence on which to grant the privileges. When using more than one schema, specify the schema that contains the sequence on which to grant privileges. ON ALL SEQUENCES IN SCHEMA Grants privileges on all sequences within one or more schemas to a user and/or role. HP Vertica Analytic Database (7.0.x) Page 1167 of 1539 SQL Reference Manual SQL Statements username Grants the privilege to the specified user. role Grants the privilege to the specified role. PUBLIC Grants the privilege to all users. WITH GRANT OPTION Allows the user to grant the same privileges to other users. Notes The user must also be granted USAGE on the schema that contains the sequence. See GRANT (Schema). See Also REVOKE (Sequence) l l GRANT (Storage Location) Grants privileges to non-superusers or roles to read from or write to an HP Vertica storage location. First, a superuser creates a special class of storage location with the USER keyword through the usage parameter. Creating a storage location with a USER type specifies that the the location can be made accessible to non-dbadmin users. The superuser must then grant users or roles the appropriate privileges through the GRANT (Storage Location) statement. Note: GRANT/REVOKE (Storage Location) statements are applicable only to 'USER' storage locations. If the storage location is dropped, all privileges are revoked automatically. Syntax GRANT { READ | WRITE | ALL [ PRIVILEGES ] } ... ON LOCATION 'path' [, ON 'node' ] ... TO { username | role | PUBLIC } [, ...] ... ... [ WITH GRANT OPTION ] Parameters READ HP Vertica Analytic Database (7.0.x) Lets users or roles copy data from files in the storage location into a table. Page 1168 of 1539 SQL Reference Manual SQL Statements WRITE Lets users or roles export data from a table to a storage location. WRITE privileges also lets users export COPY statement exceptions and rejected data files from HP Vertica to the specified storage location. ALL Applies to all privileges. PRIVILEGES [Optional] For SQL standard compatibility and is ignored. ON LOCATION 'path' [, ON 'node' ] { username | role | PUBLIC } [,...] WITH GRANT OPTION l path—[Required] Specifies where the storage location is mounted l node—[Optional] The node on which the location is available. If this parameter is omitted, node defaults to the initiator. [Required] The recipient of the privileges, which can be one or more users, one or more roles, or all users (PUBLIC). l username—Indicates a specific user l role-Specifies a particular role l PUBLIC-Indicates that all users have READ and/or WRITE permissions. [Optional] Allows the grantee to grant the same READ/WRITE privileges to others. Notes Only a superuser can add, alter, retire, drop, and restore a location, as well as set and measure location performance. All other users or roles must be granted READ and/or WRITE privileges on storage locations. Examples In the following series of commands, a superuser creates a new storage location and grants it to user Bob: dbadmin=> SELECT ADD_LOCATION('/home/dbadmin/UserStorage/BobStore', e0007', 'USER'); ADD_LOCATION ------------------------------------------/home/dbadmin/UserStorage/BobStore' added. (1 row) 'v_mcdb_nod Now the superuser grants Bob READ/WRITE permissions on the /BobStore location: HP Vertica Analytic Database (7.0.x) Page 1169 of 1539 SQL Reference Manual SQL Statements dbadmin=> GRANT ALL ON LOCATION '/home/dbadmin/UserStorage/BobStore' TO Bob;GRANT PRIVILE GE Revoke all storage location privileges from Bob: dbadmin=> REVOKE ALL ON LOCATION '/home/dbadmin/UserStorage/BobStore' FROM Bob;REVOKE PRI VILEGE Grant privileges to Bob on the BobStore location again, this time specifying the node: dbadmin=> GRANT ALL ON LOCATION '/home/dbadmin/UserStorage/BobStore' node0007 TO Bob; GRANT PRIVILEGE ON v_mcdb_ Revoke all storage location privileges from Bob: dbadmin=> REVOKE ALL ON LOCATION '/home/dbadmin/UserStorage/BobStore' b_node0007 FROM Bob; REVOKE PRIVILEGE ON v_mcd See Also Storage Management Functions l REVOKE (Storage Location) l l GRANT (Table) Grants privileges on a table to a user or role. Optionally grants privileges on all tables within one or more schemas. Note: Granting privileges on all tables within a schema includes all views in the same schema. Syntax GRANT { { SELECT | INSERT | UPDATE | DELETE | REFERENCES } [ ,... ] ... | ALL [ PRIVILEGES ] } ... ON [ TABLE ] [ [ db-name.]schema.]tablename [ , ... ] ... | ON ALL TABLES IN SCHEMA schema-name [, ...] ... TO { username | role | PUBLIC } [ , ... ] ... [ WITH GRANT OPTION ] HP Vertica Analytic Database (7.0.x) Page 1170 of 1539 SQL Reference Manual SQL Statements Parameters SELECT Allows the user to SELECT from any column of the specified table. INSERT Allows the user to INSERT tuples into the specified table and to use the COPY command to load the table. Note: COPY FROM STDIN is allowed to any user granted the INSERT privilege, while COPY FROM is an admin-only operation. UPDATE Allows the user to UPDATE tuples in the specified table. DELETE Allows DELETE of a row from the specified table. REFERENCES Is necessary to have this privilege on both the referencing and referenced tables in order to create a foreign key constraint. Also need USAGE on schema that contains the table. ALL Applies to all privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). tablename Specifies the table on which to grant the privileges. When using more than one schema, specify the schema that contains the table on which to grant privileges. ON ALL TABLES IN SCHEMA Grants privileges on all tables (and by default all views) within one or more schemas to a user and/or role. username Grants the privilege to the specified user. role Grants the privilege to the specified role. PUBLIC Grants the privilege to all users. WITH GRANT OPTION Allows the user to grant the same privileges to other users. HP Vertica Analytic Database (7.0.x) Page 1171 of 1539 SQL Reference Manual SQL Statements Notes l The user must also be granted USAGE on the schema that contains the table. See GRANT (Schema). l To use the DELETE or UPDATE commands with a WHERE Clause, a user must have both SELECT and UPDATE and DELETE privileges on the table. l The user can be granted privileges on a global temporary table, but not a local temporary table. See Also REVOKE (Table) l l GRANT (User Defined Extension) Grants privileges on a user-defined extension (UDx) to a database user or role. Optionally grants all privileges on the user-defined extension within one or more schemas. You can grant privileges on the following user-defined extension types: l l User Defined Functions (UDF) n User Defined SQL Functions n User Defined Scalar Functions (UDSF) n User Defined Transform Functions (UDTF) n User Defined Aggregate Functions (UDAF) n User Defined Analytic Functions (UDAnF) User Defined Load Functions (UDL) n UDL Filter n UDL Parser n UDL Source Syntax GRANT { EXECUTE | ALL } ... ON FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON AGGREGATE FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON ANALYTIC FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON TRANSFORM FUNCTION [[db-name.]schema.]function-name [, ...] HP Vertica Analytic Database (7.0.x) Page 1172 of 1539 SQL Reference Manual SQL Statements ... ... ... ... ... ... | ON FILTER [ [ db-name.]schema.]filter-name [, ...] | ON PARSER [ [ db-name.]schema.]parser-name [, ...] | ON SOURCE [ [ db-name.]schema.]source-name [, ...] | ON ALL FUNCTIONS IN SCHEMA schema-name [, ...] ( [ argname ] argtype [, ...] ) TO { username | role | PUBLIC } [, ...] Parameters { EXECUTE | ALL } [[ db-name.]schema-name.] The type of privilege to grant the UDx: l EXECUTE grants permission to call a user-defined extension. l ALL grants all privileges on the user-defined extension [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name filter-name parser-name source-name The name of the UDx on which to grant the privilege. If you use more than one schema, you must specify the schema that contains the UDx, as noted in the previous row. ON ALL FUNCTIONS IN SCHEMA Grants privileges on all UDx's within one or more schemas to a user, role, or all users and roles. argname [Optional] The argument name for the UDx. argtype The argument data type of the UDx. { username | role | PUBLIC } [,...] The recipient of the UDx privileges, which can be one or more users, one or more roles, or all users and roles (PUBLIC). HP Vertica Analytic Database (7.0.x) l username - Indicates a specific user l role - Specifies a particular role l PUBLIC - Indicates that all users and roles have granted privileges to the UDx. Page 1173 of 1539 SQL Reference Manual SQL Statements Permissions Only a superuser and owner can grant privileges on a UDx. To grant privileges to a specific schema UDx or to all UDx's within one or more schemas, grantees must have USAGE privileges on the schema. See GRANT (Schema). Examples The following command grants EXECUTE privileges on the myzeroifnull SQL function to users Bob and Jules, and to the Operator role. The function takes one integer argument: => GRANT EXECUTE ON FUNCTION myzeroifnull (x INT) TO Bob, Jules, Operator; The following command grants EXECUTE privileges on all functions in the zero-schema schema to user Bob: => GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA zero-schema TO Bob; The following command grants EXECUTE privileges on the tokenize transform function to user Bob and to the Operator role: => GRANT EXECUTE ON TRANSFORM FUNCTION tokenize(VARCHAR) TO Bob, Operator; The following command grants EXECUTE privileges on the HCatalogSource() source to user Alice. => CREATE USER Alice; => GRANT USAGE ON SCHEMA hdfs TO Alice; => GRANT EXECUTE ON SOURCE HCatalogSource() TO Alice; The next command grants ALL privileges on the HCatalogSource() source to user Alice: => GRANT ALL ON SOURCE HCatalogSource() TO Alice; See Also l REVOKE (User Defined Extension) l Granting and Revoking Privileges in the Administrator's Guide l Developing and Using User Defined Functions in the Programmer's Guide GRANT (View) Grants privileges on a view to a database user or role. HP Vertica Analytic Database (7.0.x) Page 1174 of 1539 SQL Reference Manual SQL Statements Syntax GRANT ... { SELECT | ALL [ PRIVILEGES ] } ... ON [ [ db-name.]schema.]viewname [, ...] ... TO { username | role | PUBLIC } [, ...] ... [ WITH GRANT OPTION ] Parameters SELECT Grants a user or role SELECT operations to a view, and any resources referenced within it. ALL Grants a user or role all privileges to a view, and any resources referenced within it. PRIVILEGES [Optional] For SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). viewname Specifies the view on which to grant the privileges. When using more than one schema, specify the schema that contains the view, as noted above. username Grants the privilege to the specified user. role Grants the privilege to the specified role. PUBLIC Grants the privilege to all users. WITH GRANT OPTION Permits the user to grant the same privileges to other users. Note: If userA wants to grant userB access to a view, userA must specify WITH GRANT OPTION on the base table, in addition to the view, regardless of whether userB (grantee) has access to the base table. See Also REVOKE (View) l l HP Vertica Analytic Database (7.0.x) Page 1175 of 1539 SQL Reference Manual SQL Statements INSERT Inserts values into all projections of a table. You must insert one complete tuple at a time. By default, Insert first uses the WOS. When the WOS is full, the INSERT overflows to the ROS. Note: If a table has no associated projections, HP Vertica creates a default superprojection for the table in which to insert the data. HP Vertica does not support subqueries as the target of an INSERT statement. Syntax INSERT [ /*+ direct */ ] [ /*+ label(label-name)*/ ] ... INTO [[db-name.]schema.]table ... [ ( column [, ...] ) ] ... { DEFAULT VALUES ... | VALUES ( { expression | DEFAULT } [, ...] ) ... | SELECT... } Parameters /*+ direct */ Writes the data directly to disk (ROS) bypassing memory (WOS). HP Vertica accepts optional spaces before and after the plus (+) sign and the direct hint. Space characters between the opening /* or the closing */ are not permitted. The following directives are all acceptable: /*+direct*/ /* + direct*/ /*+ direct*/ /*+direct */ Note: If you insert using the direct hint, you still need to issue a COMMIT or ROLLBACK command to finish the transaction. /*+ label(label-name)*/ Passes a user-defined label to a query as a hint, letting you quickly identify labeled queries for profiling and debugging. See Query Labeling in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1176 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). table Specifies the name of a table in the schema. You cannot INSERT tuples into a projection. When using more than one schema, specify the schema that contains the table, as noted above. column Specifies one or more table columns. You can list the target columns in any order. If no list of column names is given at all, 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. DEFAULT VALUES Fills all columns with their default values as specified in CREATE TABLE. VALUES Specifies a list of values to store in the corresponding columns. If no value is supplied for a column, HP Vertica implicitly adds a DEFAULT value, if present. Otherwise HP Vertica inserts a NULL value. If the column is defined as NOT NULL, INSERT returns an error. expression Specifies a value to store in the corresponding column. Do not use meta-functions in INSERT statements. DEFAULT Stores the default value in the corresponding column. SELECT... Specifies a query (SELECT statement) that supplies the rows to insert. An INSERT ... SELECT statement refers to tables in both its INSERT and SELECT clauses. Isolation level applies only to the SELECT clauses and work just like an normal query. Permissions l Table owner or user with GRANT OPTION is grantor. l INSERT privilege on table HP Vertica Analytic Database (7.0.x) Page 1177 of 1539 SQL Reference Manual SQL Statements l USAGE privilege on schema that contains the table Examples => => => => INSERT INSERT INSERT INSERT INTO INTO INTO INTO t1 VALUES (101, 102, 103, 104); customer VALUES (10, 'male', 'DPR', 'MA', 35); retail.t1 (C0, C1) VALUES (1, 1001); films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07'; HP Vertica does not support subqueries as the target of an INSERT statement, and the following query returns an error message: INSERT INTO t1 (col1, col2) VALUES ('abc', (SELECT mycolumn FROM mytable)); ERROR 4821: Subqueries not allowed in target of insert You can rewrite the above query as follows: INSERT INTO t1 (col1, col2) (SELECT 'abc', mycolumn FROM mytable); OUTPUT -------0 (1 row) When doing an INSERT /*+ direct */ HP Vertica takes optional spaces before and after the plus sign (e.g., between the /* and the +). Both of the following commands, for example, load data into the ROS: => => => => CREATE TABLE rostab(x TIMESTAMP); INSERT /*+ direct */ INTO rostab VALUES ('2011-02-10 12:01:00'); INSERT /*+ direct */ INTO rostab VALUES ('2011-02-15 12:01:00'); SELECT wos_row_count, ros_row_count FROM column_storage WHERE anchor_table_name = 'rostab'; wos_row_count | ros_row_count ---------------+--------------0 | 2 0 | 2 (2 rows) MERGE The MERGE statement combines INSERT, UPDATE, and DELETE operations in a single operation. During a merge, HP Vertica updates and inserts rows in the target table from rows in the source table, depending on conditions you specify, such as whether the target table already has a row that matches data from the source. By default, HP Vertica prepares an optimized query plan for a MERGE statement when the statement and its tables meet certain conditions. See Optimized Versus Non-Optimized MERGE in the Administrator's Guide for details. HP Vertica Analytic Database (7.0.x) Page 1178 of 1539 SQL Reference Manual SQL Statements A MERGE operation uses the WOS by default. If the WOS fills up, data overflows to the ROS. You cannot use the MERGE statement with unstructured tables. Syntax MERGE [/*+ direct */] ... INTO [[db-name.]schema.]target-table [ alias ] ... USING [[db-name.]schema.]source-table [ alias ] ... ON ( condition ) ... [ WHEN MATCHED THEN UPDATE SET column1 = value1 [, column2 = value2 ... ] ] ... [ WHEN NOT MATCHED THEN INSERT ( column1 [, column2 ...]) VALUES ( value1 [, value2 ... ] ) ] Returns The returned value at the end of a MERGE operation represents the number of rows updated plus the number of rows inserted into the target table. Parameters /*+ direct */ Writes the data directly to disk (ROS) bypassing memory (WOS). HP Vertica accepts optional spaces before and after the plus (+) sign and the direct hint. Space characters between the opening /* or the closing */ are not permitted. The following directives are all acceptable: /*+direct*/ /* + direct*/ /*+ direct*/ /*+direct */ HP Vertica Analytic Database (7.0.x) Page 1179 of 1539 SQL Reference Manual SQL Statements [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). INTO target-table Specifies the target table name (with optional alias) that you want to update. MERGE takes an X (exclusive) lock on the target table during the operation. You cannot merge into a projection or unstructured table. USING source-table Specifies the source table name (with optional alias) that contains the data you want to update or insert into the target table. Source data can come from a base or external table only. Subqueries and joins are not allowed. ON condition Specifies the search condition through the join columns, which HP Vertica uses to evaluate each row in the source table to update, delete, and/or insert source rows into the target table. Tip: For the MERGE statement be eligible for an optimized query plan, the target table's join column must have a UNIQUE or PRIMARY KEY constraint. See Optimized Versus Non-Optimized MERGE in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1180 of 1539 SQL Reference Manual SQL Statements WHEN MATCHED THEN UPDATE SET column1 = value1 [Optional] Specifies what columns to update in the target table when the search condition is true for a given row in the source table. When a match is found, HP Vertica updates and/or deletes existing rows in the target table with data from the source table. When preparing an optimized query plan for a MERGE statement, HP Vertica enforces strict requirements for unique and primary key constraints in the join key (ON clause). If you haven't enforced such constraints, MERGE fails when it finds: l More than one matching value in target join column for a corresponding value in the source table when the target join column has a unique or primary key constraint. If the target join column has no such constraint, the statement runs without error, but it also runs without optimization. l More than one matching value in the source join column for a corresponding value in the target table. The source join column does not require a unique or primary key constraint. Only one WHEN MATCHED THEN UPDATE clause per statement is permitted. Note: The WHEN.. UPDATE is clause is optional; however, it is required for a MERGE statement to be eligible for an optimized query plan. See Optimized Versus Non-Optimized MERGE in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1181 of 1539 SQL Reference Manual SQL Statements WHEN NOT MATCHED THEN INSERT (column1,....,columnn) VALUES (value 1, ..., valuen) [Optional] Specifies what to update in the target table when the search condition does not match. HP Vertica inserts into the target table all rows from the source table that do not match any rows in the target table. Only one WHEN NOT MATCHED THEN INSERT clause per statement is permitted. The columns you specify in the WHEN NOT MATCHED THEN INSERT clause must be columns from the target table. The VALUES clause specifies a list of values to store in the corresponding columns. If you do not supply a column value, do not list that column in the WHEN NOT MATCHED clause. For example, in the following syntax, column 2 (c2) is excluded from both the WHEN NOT MATCHED and VALUES clauses: WHEN NOT MATCHED THEN INSERT(c1,c3,c4) VALUES(c 1_value,c3_value,c4_value) HP Vertica inserts a NULL value or uses the DEFAULT value (specified through the CREATE TABLE statement) for column 2 in the above example. You cannot qualify table name or alias with the columns; for example, the following is not allowed: WHEN NOT MATCHED THEN INSERT source.x If column names are not listed, MERGE behaves like INSERT..SELECT by assuming that the columns are in the exact same table definition order. Note: The WHEN..INSERT is optional; however, it is required for a MERGE statement to be eligible for an optimized query plan, where all columns from the target table must be included. See Optimized Versus Non-Optimized MERGE in the Administrator's Guide. Privileges A MERGE statement requires SELECT permissions on the source table and INSERT, UPDATE, and DELETE permissions on the target table. HP Vertica Analytic Database (7.0.x) Page 1182 of 1539 SQL Reference Manual SQL Statements Using Named Sequences If you are using named sequences, HP Vertica can perform a MERGE operation if you omit the sequence from the query. See Using Named Sequences in the Administrator's Guide. Improving MERGE Performance You can help improve the performance of MERGE operations by ensuring projections are designed for optimal use. See Projection Design for Merge Operations in the Administrator's Guide. Notes and Restrictions l An optimized query plan for a MERGE statement assumes that the data you are trying to merge conforms with any unique or primary key constraints you declare. l You cannot run a MERGE operation on identity/auto-increment columns or on columns that have primary key or foreign key referential integrity constraints, as defined in CREATE TABLE ColumnConstraint syntax. l You cannot use MERGE with unstructured tables. l If you run the MERGE statement more than once using the same target and source tables, you could introduce duplicate values into the join columns, such as when using constants in the UPDATE/INSERT clauses. Examples For examples, see Optimized Versus Non-Optimized MERGE in the Administrator's Guide: See Also Synchronizing Table Data with MERGE in the Administrator's Guide PROFILE Profiles a single SQL statement. Syntax PROFILE { SELECT ... } Output Writes a hint to stderr, as described in the example below. HP Vertica Analytic Database (7.0.x) Page 1183 of 1539 SQL Reference Manual SQL Statements Permissions Privileges required to run this command are the same privileges required to run the query being profiled. Notes To profile a single statement, add the PROFILE keyword to the beginning of the statement, which saves profiling information for future analysis: => PROFILE SELECT customer_name, annual_income FROM public.customer_dimension WHERE (customer_gender, annual_income) IN ( SELECT customer_gender, MAX(annual_income) FROM public.customer_dimension GROUP BY customer_gender); While a query is executing, a notice and hint display in the terminal window. For example, the preceding query returns the following: NOTICE 4788: Statement is being profiled HINT: Select * from v_monitor.execution_engine_profiles where transaction_id=45035996273 726389 and statement_id=10; NOTICE 3557: Initiator memory for query: [on pool general: 732168 KB, minimum: 451218 K B] NOTICE 5077: Total memory required by query: [732168 KB] customer_name | annual_income -----------------+--------------James M. McNulty | 999979 Emily G. Vogel | 999998 (2 rows) Tip: Use the statement returned by the hint as a starting point for reviewing the query's profiling data, such as to see what counters are available. Real-Time Profiling Example The following sample statement requests the operators with the largest execution time on each node: => SELECT node_name, operator_name, counter_valueexecution_time_us FROM v_monitor.execution_engine_profiles WHERE counter_name='execution time (us)' ORDER BY node_name, counter_value DESC; HP Vertica Analytic Database (7.0.x) Page 1184 of 1539 SQL Reference Manual SQL Statements How to Use the Linux watch Command You can use the Linux watch command to monitor long-running queries with one-second updates; for example: WATCH -n 1 -d "vsql-c \"select node_name, operator_name, counter_valueexecution_time_u s... \"" How to Find Out Which Counters are Available HP Vertica keeps track of the following counters during query execution: => SELECT DISTINCT(counter_name) FROM EXECUTION_ENGINE_PROFILES; counter_name ----------------------------------------------------estimated rows produced bytes spilled rle rows produced join inner current size of temp files (bytes) request wait (us) start time intermediate rows to process producer wait (us) rows segmented consumer stall (us) bytes sent rows sent join inner completed merge phases encoded bytes received cumulative size of raw temp data (bytes) end time bytes read from cache total merge phases rows pruned by valindex cumulative size of temp files (bytes) output queue wait (us) rows to process input queue wait (us) rows processed memory allocated (bytes) join inner cumulative size of temp files (bytes) current size of temp files (bytes) join inner cumulative size of raw temp data (bytes) bytes received file handles bytes read from disk join inner total merge phases completed merge phases memory reserved (bytes) clock time (us) response wait (us) network wait (us) rows received HP Vertica Analytic Database (7.0.x) Page 1185 of 1539 SQL Reference Manual SQL Statements encoded bytes sent execution time (us) producer stall (us) buffers spilled rows produced (43 rows) RELEASE SAVEPOINT Destroys a savepoint without undoing the effects of commands executed after the savepoint was established. Syntax RELEASE [ SAVEPOINT ] savepoint_name Parameters savepoint_name Specifies the name of the savepoint to destroy. Permissions No special permissions required. Notes Once destroyed, the savepoint is unavailable as a rollback point. Example The following example establishes and then destroys a savepoint called my_savepoint. The values 101 and 102 are both inserted at commit. => => => => => INSERT INTO product_key VALUES (101); SAVEPOINT my_savepoint; INSERT INTO product_key VALUES (102); RELEASE SAVEPOINT my_savepoint; COMMIT; HP Vertica Analytic Database (7.0.x) Page 1186 of 1539 SQL Reference Manual SQL Statements See Also l SAVEPOINT l ROLLBACK TO SAVEPOINT HP Vertica Analytic Database (7.0.x) Page 1187 of 1539 SQL Reference Manual SQL Statements REVOKE Statements The following functions allow you to revoke privileges on database objects for specified users: l REVOKE (Database) l REVOKE (Procedure) l REVOKE (Resource Pool) l REVOKE (Role) l REVOKE (Schema) l REVOKE (Sequence) l REVOKE (Storage Location) l REVOKE (Table) l REVOKE (User Defined Extension) l REVOKE (View) REVOKE (Database) Revokes the right for the specified user or role to create schemas in the specified database. Syntax REVOKE [ GRANT OPTION FOR ] ... { CREATE | { TEMPORARY | TEMP } [ ,... ] } ... | CONNECT ... | ALL [ PRIVILEGES ] } ... ON DATABASE database-name [ , ... ] ... FROM { username | role }[ , ... ] ... [ CASCADE ] Parameters GRANT OPTION FOR Revokes the grant option for the privilege, not the privilege itself. If omitted, revokes both the privilege and the grant option. CREATE Revokes the right to create schemas in the specified database. TEMPORARY | TEMP Revokes the right to create temp tables in the database. Note: This privilege is provided by default with CREATE USER. HP Vertica Analytic Database (7.0.x) Page 1188 of 1539 SQL Reference Manual SQL Statements ALL Applies to all privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. database-name Identifies the database from which to revoke the privilege. username Identifies the user from whom to revoke the privilege. role Identifies the role from which to revoke the privilege. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. Examples The following example revokes Fred's right to create schemas on vmartdb: => REVOKE CREATE ON DATABASE vmartdb FROM Fred; The following revokes Fred's right to create temporary tables in vmartdb: => REVOKE TEMPORARY ON DATABASE vmartdb FROM Fred; See Also GRANT (Database) l l REVOKE (Procedure) Revokes the execute privilege on a procedure from a user or role. Syntax REVOKE EXECUTE ... ON [ [ db-name.]schema.]procedure-name [ , ... ] ... ( [ argname ] argtype [ ,... ] ] ) ... FROM { username | PUBLIC | role } [ , ... ] ...[ CASCADE ] HP Vertica Analytic Database (7.0.x) Page 1189 of 1539 SQL Reference Manual SQL Statements Parameters [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). procedure-name Specifies the procedure on which to revoke the execute privilege. When using more than one schema, specify the schema that contains the procedure, as noted above. argname Specifies the argument names used when creating the procedure. argtype Specifies the argtypes used when creating the procedure. username Specifies the user from whom to revoke the privilege. PUBLIC Revokes the privilege from all users. role Specifies the role from whom to revoke the privilege. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. Notes Only a superuser can revoke USAGE on a procedure. See Also GRANT (Procedure) l l HP Vertica Analytic Database (7.0.x) Page 1190 of 1539 SQL Reference Manual SQL Statements REVOKE (Resource Pool) Revokes a user's or role's access privilege to a resource pool. Syntax REVOKE USAGE... ON RESOURCE POOL resource-pool ... FROM { username | PUBLIC | role } [ , ... ] ...[ CASCADE ] Parameters resource-pool Specifies the resource pool from which to revoke the usage privilege. username Revokes the privilege from the specified user. PUBLIC Revokes the privilege from all users. role Revokes the privilege from the specified role. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. Notes l HP Vertica checks resource pool permissions when a user initially switches to the pool, rather than on each access. Revoking a user's permission to use a resource pool does not affect existing sessions. You need to close the user's open sessions that are accessing the resource pool if you want to prevent them from continuing to use the pool's resources. l It is an error to revoke a user's access permissions for the resource pool to which they are assigned (their default pool). You must first change the pool they are assigned to using ALTER USER ... RESOURCE POOL (potentially using GRANT USAGE ON RESOURCE POOL first to allow them to access the new pool) before revoking their access. See Also GRANT (Resource Pool) l l REVOKE (Role) Revokes a role (and administrative access, applicable) from a grantee. A user that has administrator access to a role can revoke the role for other users. HP Vertica Analytic Database (7.0.x) Page 1191 of 1539 SQL Reference Manual SQL Statements If you REVOKE role WITH ADMIN OPTION, HP Vertica revokes only the ADMIN OPTION from the grantee, not the role itself. You can also remove a role's access to another role. Syntax REVOKE [ ADMIN OPTION FOR ] role [, ...] ... FROM { user | role | PUBLIC } [, ...] ...[ CASCADE ]; Parameters ADMIN OPTION FOR Revokes just the user's or role's administration access to the role. role The name of one or more roles from which you want to revoke access. user | role | PUBLIC The name of a user or role whose permission you want to revoke. You can use the PUBLIC option to revoke access to a role that was previously made public. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. Notes If the role you are trying to revoke was not already granted to the grantee, HP Vertica returns a NOTICE: => REVOKE commentor FROM Sue; NOTICE 2022: Role "commentor" was not already granted to user "Sue" REVOKE ROLE See Also GRANT (Role) l l REVOKE (Schema) Revokes privileges on a schema from a user or role. Note: In a database with trust authentication, the GRANT and REVOKE statements appear to HP Vertica Analytic Database (7.0.x) Page 1192 of 1539 SQL Reference Manual SQL Statements work as expected but have no actual effect on the security of the database. Syntax REVOKE [ GRANT OPTION FOR ] { ... { CREATE | USAGE } [ ,... ] ... | ALL [ PRIVILEGES ] } ... ON SCHEMA [db-name.] schema [ , ... ] ... FROM { username | PUBLIC | role } [ , ... ] ...[ CASCADE ] Parameters GRANT OPTION FOR Revokes the grant option for the privilege, not the privilege itself. If omitted, revokes both the privilege and the grant option. CREATE Revokes the user read access to the schema and the right to create tables and views within the schema. USAGE Revokes user access to the objects contained within the schema. Note that the user can also have access to the individual objects revoked. See the GRANT TABLE and GRANT VIEW statements. ALL Revokes all privileges previously granted. PRIVILEGES Is for SQL standard compatibility and is ignored. [db-name.] [Optional] Specifies the current database name. Using a database name prefix is optional, and does not affect the command in any way. You must be connected to the specified database. schema Identifies the schema from which to revoke privileges. username Revokes the privilege to a specific user. PUBLIC Revokes the privilege to all users. role Revokes the privilege to a specific role. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. See Also GRANT (Schema) l l HP Vertica Analytic Database (7.0.x) Page 1193 of 1539 SQL Reference Manual SQL Statements REVOKE (Sequence) Revokes privileges on a sequence generator from a user or role. Optionally revokes privileges on all sequences within one or more schemas. Syntax REVOKE [ GRANT OPTION FOR ] ... { SELECT | ALL [ PRIVILEGES ] } ... ON SEQUENCE [ [ db-name.]schema.]sequence-name [ , ... ] ... | ON ALL SEQUENCES IN SCHEMA schema-name [, ...] ... FROM { username | PUBLIC | role } [ , ... ] ...[ CASCADE ] Parameters SELECT Revokes the right to use both the CURRVAL() and NEXTVAL() functions on the specified sequence. ALL Applies to all privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). sequence-name Specifies the sequence from which to revoke privileges. When using more than one schema, specify the schema that contains the sequence from which to revoke privileges. ON ALL SEQUENCES IN SCHEMA Revokes privileges on all sequences within one or more schemas from a user and/or role. username Revokes the privilege from the specified user. PUBLIC Revokes the privilege from all users. HP Vertica Analytic Database (7.0.x) Page 1194 of 1539 SQL Reference Manual SQL Statements role Revokes the privilege from the specified role. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. See Also GRANT (Sequence) l l REVOKE (Storage Location) Revokes privileges from a user or role to read from or write to a storage location. Note: The REVOKE (Storage Location) statement is applicable only to 'USER' storage locations. See GRANT (Storage Location) for more information. If the storage location is dropped, all user privileges are removed as part of that. Syntax REVOKE [ GRANT OPTION FOR ] ... { READ | WRITE | ALL [ PRIVILEGES ] } ... ON LOCATION [ 'path' , [ ON 'node' ] ] ... FROM { username | role | PUBLIC } [, ...] ... [ CASCADE ] Parameters GRANT OPTION FOR Revokes GRANT privileges from the grantee. READ Revokes privileges to copy data from files in a storage locations into a table. WRITE Revokes privileges to export HP Vertica data from a table to a storage location. Also revokes permissions to export the COPY statement's exceptions/rejections files HP Vertica to a storage location. ALL Applies to all privileges. PRIVILEGES For SQL standard compatibility and is ignored. HP Vertica Analytic Database (7.0.x) Page 1195 of 1539 SQL Reference Manual SQL Statements { username | role | PUBLIC } [,...] ON LOCATION ( 'path' , [ ON 'node' ] ) CASCADE The recipient of the privileges, which can be one or more users, one or more roles, or all users (PUBLIC). l username-Indicates a specific user l role-Specifies a particular role l PUBLIC-Indicates that all users have READ and/or WRITE permissions. l path—specifies where the storage location is mounted l node—the HP Vertica node where the location is available. If this parameter is omitted, node defaults to the initiator. Revokes the privilege from the specified user or role and then from others. After a user or role has been granted a privilege, the user can grant that privilege to other users and roles; the CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. Examples For examples, see GRANT (Storage Location) See Also l REVOKE (Table) Revokes privileges on a table from a user or role. Optionally revokes privileges on all tables within one or more schemas. Note: Revoking privileges on all tables within a schema includes all views in the same schema. In a database with trust authentication, the GRANT and REVOKE statements appear to work as expected but have no actual effect on the security of the database. Syntax REVOKE [ GRANT OPTION FOR ]... { ......{ SELECT | INSERT | UPDATE | DELETE | REFERENCES } [ ,... ] HP Vertica Analytic Database (7.0.x) Page 1196 of 1539 SQL Reference Manual SQL Statements ......| ALL [ PRIVILEGES ] ... } ... ON [ TABLE ] [ [ db-name.]schema.]tablename [ , ... ] ... | ON ALL TABLES IN SCHEMA schema-name [, ...] ... FROM { username | PUBLIC | role } [ , ... ] ... [ CASCADE ] Parameters GRANT OPTION FOR Revokes the grant option for the privilege, not the privilege itself. If omitted, revokes both the privilege and the grant option. SELECT Revokes the user's ability to SELECT from any column of the specified table. INSERT Revokes the user from being able to INSERT tuples into the specified table and to use the COPY command to load the table. Note: COPY FROM STDIN is allowed to any user granted the INSERT privilege, while COPY FROM is an admin-only operation. UPDATE Revokes user from being allowed to UPDATE tuples in the specified table. DELETE Revokes user from being able to DELETE a row from the specified table. REFERENCES Revokes the user's privilege on both the referencing and referenced tables for creating a foreign key constraint. ALL Revokes all previously granted privileges. PRIVILEGES Is for SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). HP Vertica Analytic Database (7.0.x) Page 1197 of 1539 SQL Reference Manual SQL Statements tablename Specifies the table from which to remove privileges. When using more than one schema, specify the schema that contains the table on which to revoke privileges, as noted above. ON ALL TABLES IN SCHEMA Revokes privileges on all tables (and by default views) within one or more schemas from a user and/or role. username Revokes the privilege from the specified user. PUBLIC Revokes the privilege from all users. role Revokes the privilege from the specified role. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. See Also GRANT (Table) l l REVOKE (User Defined Extension) Revokes the EXECUTE privilege on a user-defined extension (UDx) from a database user or role. Optionally revokes privileges on all user-defined extensions within one or more schemas. You can revoke privileges on the following user-defined extension types: l l User Defined Functions (UDF) n User Defined SQL Functions n User Defined Scalar Functions (UDSF) n User Defined Transform Functions (UDTF) n User Defined Aggregate Functions (UDAF) n User Defined Analytic Functions (UDAnF) User Defined Load Functions (UDL) n UDL Filter n UDL Parser n UDL Source HP Vertica Analytic Database (7.0.x) Page 1198 of 1539 SQL Reference Manual SQL Statements Syntax REVOKE EXECUTE ...ON FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON AGGREGATE FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON ANALYTIC FUNCTION [ [ db-name.]schema.]function-name [, ...] ... | ON TRANSFORM FUNCTION [[db-name.]schema.]function-name [, ...] ... | ON FILTER [ [ db-name.]schema.]filter-name [, ...] ... | ON PARSER [ [ db-name.]schema.]parser-name [, ...] ... | ON SOURCE [ [ db-name.]schema.]source-name [, ...] ... | ON ALL FUNCTIONS IN SCHEMA schema-name [, ...] ... ( [ argname ] argtype [, ...] ) ... FROM { username | role | PUBLIC } [, ...] ... [ CASCADE ] Parameters [[ db-name.]schema-name.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). function-name filter-name parser-name source-name The name of the UDx from which to revoke the EXECUTE privilege. If you use more than one schema, you must specify the schema that contains the UDx, as noted in the previous row. ON ALL FUNCTIONS IN SCHEMA Revokes EXECUTE privileges on all UDx's within one or more schemas from a user, role, or all users and roles. argname [Optional] The argument name or names for the UDx. argtype The argument data type or types of the UDx. { username | role | PUBLIC } [,...] Revokes the privileges from the specified user, role, or all users and roles (PUBLIC) that have been granted the privilege. CASCADE Revokes the privilege from the specified user or role and then from others. After a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. HP Vertica Analytic Database (7.0.x) Page 1199 of 1539 SQL Reference Manual SQL Statements Permissions Only a superuser and owner can revoke EXECUTE privileges on a UDx. Examples The following command revokes EXECUTE privileges from user Bob on the myzeroifnull function: > REVOKE EXECUTE ON FUNCTION myzeroifnull (x INT) FROM Bob; The following command revokes EXECUTE privileges on all functions in the zero-schema schema from user Bob: > REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA zero-schema FROM Bob; The following command revokes EXECUTE privileges from user Bob on the tokenize function: > REVOKE EXECUTE ON TRANSFORM FUNCTION tokenize(VARCHAR) FROM Bob; The following command revokes ALL privileges on the HCatalogSource() source from user Alice: > REVOKE ALL ON SOURCE HCatalogSource() FROM Alice; See Also l GRANT (User Defined Extension) l Granting and Revoking Privileges in the Administrator's Guide l Developing and Using User Defined Functions in the Programmer's Guide REVOKE (View) Revokes user privileges on a view. Note: In a database with trust authentication, the GRANT and REVOKE statements appear to work as expected but have no actual effect on the security of the database. Syntax REVOKE [ GRANT OPTION FOR ]... { SELECT | ALL [ PRIVILEGES ] } ... ON [ VIEW ] [ [ db-name.]schema.]viewname [ , ... ] ... FROM { username | PUBLIC } [ , ... ] ... [ CASCADE ] HP Vertica Analytic Database (7.0.x) Page 1200 of 1539 SQL Reference Manual SQL Statements Parameters GRANT OPTION FOR Revokes the grant option for the privilege, not the privilege itself. If omitted, revokes both the privilege and the grant option. SELECT Allows the user to perform SELECT operations on a view and the resources referenced within it. PRIVILEGES Is for SQL standard compatibility and is ignored. [[db-name.]schema.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). viewname Specifies the view on which to revoke the privileges. When using more than one schema, specify the schema that contains the view, as noted above. username Revokes the privilege from the specified user. PUBLIC Revokes the privilege from all users. CASCADE Revokes the privilege from the specified user or role and then from others. Once a user or role has been granted a privilege, the user can grant that privilege to other users and roles. The CASCADE keyword first revokes the privilege from the initial user or role, and then from other grantees extended the privilege. See Also GRANT (View) l l ROLLBACK Ends the current transaction and discards all changes that occurred during the transaction. HP Vertica Analytic Database (7.0.x) Page 1201 of 1539 SQL Reference Manual SQL Statements Syntax ROLLBACK [ WORK | TRANSACTION ] Parameters WORKTRANSACTION Have no effect; they are optional keywords for readability. Permissions No special permissions required. Notes When an operation is rolled back, any locks that are acquired by the operation are also rolled back. ABORT is a synonym for ROLLBACK. See Also l l l BEGIN l COMMIT l END l START TRANSACTION ROLLBACK TO SAVEPOINT Rolls back all commands that have been entered within the transaction since the given savepoint was established. Syntax ROLLBACK TO [SAVEPOINT] savepoint_name Parameters savepoint_name Specifies the name of the savepoint to roll back to. HP Vertica Analytic Database (7.0.x) Page 1202 of 1539 SQL Reference Manual SQL Statements Permissions No special permissions required. Notes l The savepoint remains valid and can be rolled back to again later if needed. l When an operation is rolled back, any locks that are acquired by the operation are also rolled back. l ROLLBACK TO SAVEPOINT implicitly destroys all savepoints that were established after the named savepoint. Example The following example rolls back the values 102 and 103 that were entered after the savepoint, my_ savepoint, was established. Only the values 101 and 104 are inserted at commit. => => => => => => => INSERT INTO product_key VALUES (101); SAVEPOINT my_savepoint; INSERT INTO product_key VALUES (102); INSERT INTO product_key VALUES (103); ROLLBACK TO SAVEPOINT my_savepoint; INSERT INTO product_key VALUES (104); COMMIT; See Also l RELEASE SAVEPOINT l SAVEPOINT SAVEPOINT Creates a special mark, called a savepoint, inside a transaction. A savepoint allows all commands that are executed after it was established to be rolled back, restoring the transaction to the state it was in at the point in which the savepoint was established. Tip: Savepoints are useful when creating nested transactions. For example, a savepoint could be created at the beginning of a subroutine. That way, the result of the subroutine could be rolled back if necessary. HP Vertica Analytic Database (7.0.x) Page 1203 of 1539 SQL Reference Manual SQL Statements Syntax SAVEPOINT savepoint_name Parameters savepoint_name Specifies the name of the savepoint to create. Permissions No special permissions required. Notes l Savepoints are local to a transaction and can only be established when inside a transaction block. l Multiple savepoints can be defined within a transaction. l If a savepoint with the same name already exists, it is replaced with the new savepoint. Example The following example illustrates how a savepoint determines which values within a transaction can be rolled back. The values 102 and 103 that were entered after the savepoint, my_savepoint, was established are rolled back. Only the values 101 and 104 are inserted at commit. => INSERT INTO T1 (product_key) VALUES => SAVEPOINT my_savepoint; => INSERT INTO T1 (product_key) VALUES => INSERT INTO T1 (product_key) VALUES => ROLLBACK TO SAVEPOINT my_savepoint; => INSERT INTO T1 (product_key) VALUES => COMMIT; => SELECT product_key FROM T1; . . . 101 104 (2 rows) HP Vertica Analytic Database (7.0.x) (101); (102); (103); (104); Page 1204 of 1539 SQL Reference Manual SQL Statements See Also l RELEASE SAVEPOINT l ROLLBACK TO SAVEPOINT SELECT Retrieves a result set from one or more tables. Syntax [ AT EPOCH LATEST ] | [ AT TIME 'timestamp' ]SELECT [ /*+ label(label-name)*/ ] [ ALL | DISTIN CT ] ... ( expression [, ...] ) ] ] ... * ... | expression [ AS ] output_name ] [ , ... ] ... [ INTO ] ... [ FROM [, ...] ] ... [ WHERE condition ] ... [ TIMESERIES slice_time ] ... [ GROUP BY expression [ , ... ] ] ... [ HAVING condition [ , ... ] ] ... [ WINDOW window_name AS ( window_definition_clause ) [ ,... ] ] [ window_partition_clause ] [ window_order_clause ] ... ... ... ... ... ... ... [ [ [ [ [ [ [ MATCH ]... [ UNION { ALL | DISTINCT } ] EXCEPT ] INTERSECT ] ORDER BY expression { ASC | DESC } [ ,... ] ] LIMIT { count | ALL } ] OFFSET start ] FOR UPDATE [ OF table_name [ , ... ] ] ] HP Vertica Analytic Database (7.0.x) Page 1205 of 1539 SQL Reference Manual SQL Statements Parameters AT EPOCH LATEST Queries all data in the database up to but not including the current epoch without holding a lock or blocking write operations. See Snapshot isolation for more information. AT EPOCH LATEST is ignored when applied to temporary tables (all rows are returned). By default, queries run under the READ COMMITTED isolation level, which means: l AT EPOCH LATEST includes data from the latest committed DML transaction. l Each epoch contains exactly one transaction—the one that modified the data. l The Tuple Mover can perform moveout and mergeout operations on committed data immediately. AT TIME 'timestamp' Queries all data in the database up to and including the epoch representing the specified date and time without holding a lock or blocking write operations. This is called a historical query. AT TIME is ignored when applied to temporary tables (all rows are returned). /*+ label(label-name)*/ Passes a user-defined label to a query as a hint, letting you quickly identify labeled queries for profiling and debugging. See Query Labeling in the Administrator's Guide. * Is equivalent to listing all columns of the tables in the FROM Clause. HP recommends that you avoid using SELECT * for performance reasons. An extremely large and wide result set can cause swapping. DISTINCT Removes duplicate rows from the result set (or group).The DISTINCT set quantifier must immediately follow the SELECT keyword. Only one DISTINCT keyword can appear in the select list. HP Vertica Analytic Database (7.0.x) Page 1206 of 1539 SQL Reference Manual SQL Statements expression Forms the output rows of the SELECT statement. The expression can contain: l Column References to columns computed in the FROM clause l Literals (constants) l Mathematical Operators l String Concatenation Operators l Aggregate Expressions l CASE Expressions l SQL Functions output_name Specifies a different name for an output column. This name is primarily used to label the column for display. It can also be used to refer to the column's value in ORDER BY and GROUP BY clauses, but not in the WHERE or HAVING clauses. FOR UPDATE Is most often used from READ COMMITTED isolation. When specified, the SELECT statement takes an X lock on all tables specified in the query. The FOR UPDATE keywords require update/delete permissions on the tables involved and cannot be issued from a read-only transaction. Permissions Table owner or user with GRANT OPTION is grantor. l SELECT privilege on table l USAGE privilege on schema that contains the table Privileges required on base objects for the view owner must be granted directly; you cannot grant privileges on these objects using roles: l If a non-owner runs a SELECT query on the view, the view owner must also have SELECT ... WITH GRANT OPTION privileges on the view's base tables or views. This privilege must be directly granted to the owner; it should not be granted through a role. l If a view owner runs a SELECT query on the view, the owner must also have SELECT privilege directly granted (not through a role) on a view's base objects (table or view). HP Vertica Analytic Database (7.0.x) Page 1207 of 1539 SQL Reference Manual SQL Statements Example When multiple clients run transactions like in the following example query, deadlocks can occur if FOR UPDATE is not used. Two transactions acquire an S lock, and when both attempt to upgrade to an X lock, they encounter deadlocks: => SELECT balance FROM accounts WHERE account_id=3476 FOR UPDATE; ... => UPDATE accounts SET balance = balance+10 WHERE account_id=3476; => COMMIT; See Also l LOCKS l Analytic Functions l Using SQL Analytics l Using Time Series Analytics l Event Series Pattern Matching l Subqueries l Joins EXCEPT Clause Combines two or more SELECT queries, returning the results of the left-hand query that are not returned by the right-hand SELECT query. Note: MINUS is an alias for EXCEPT. Syntax SELECT ... EXCEPT select ... [ EXCEPT select ]... ... [ ORDER BY { column-name ... | ordinal-number } ... [ ASC | DESC ] [ , ... ] ] ... [ LIMIT { integer | ALL } ] ... [ OFFSET integer ] HP Vertica Analytic Database (7.0.x) Page 1208 of 1539 SQL Reference Manual SQL Statements Notes l Use the EXCEPT clause to filter out specific results from a SELECT statement. The EXCEPT query operates on the results of two or more SELECT queries; it returns only those rows in the left-hand query that are not returned by the right-hand query. l HP Vertica evaluates multiple EXCEPT clauses in the same SELECT query from left to right, unless parentheses indicate otherwise. l You cannot use the ALL keyword with an EXCEPT query. l The results of each SELECT statement must be union compatible; they must return the same number of columns, and the corresponding columns must have compatible data types. For example, you cannot use the EXCEPT clause on a column of type INTEGER and a column of type VARCHAR. If they do not meet these criteria, HP Vertica returns an error. Note: The Data Type Coercion Chart lists the data types that can be cast to other data types. If one data type can be cast to the other, those two data types are compatible. l You can use EXCEPT in FROM, WHERE, and HAVING clauses. l You can order the results of an EXCEPT operation by adding an ORDER BY operation. In the ORDER BY list, specify the column names from the leftmost SELECT statement or specify integers that indicate the position of the columns by which to sort. l The rightmost ORDER BY, LIMIT, or OFFSET clauses in an EXCEPT query do not need to be enclosed in parentheses because the rightmost query specifies that HP Vertica perform the operation on the results of the EXCEPT operation. Any ORDER BY, LIMIT, or OFFSET clauses contained in SELECT queries that appear earlier in the EXCEPT query must be enclosed in parentheses. l HP Vertica supports EXCEPT noncorrelated subquery predicates: => SELECT * FROM T1 WHERE T1.x IN (SELECT MAX(c1) FROM T2 EXCEPT SELECT MAX(cc1) FROM T3 EXCEPT SELECT MAX(d1) FROM T4); Examples Consider the following three tables: Company_A HP Vertica Analytic Database (7.0.x) Page 1209 of 1539 SQL Reference Manual SQL Statements Id | emp_lname | dept | sales ------+-----------+----------------+------1234 | Vincent | auto parts | 1000 5678 | Butch | auto parts | 2500 9012 | Marcellus | floral | 500 3214 | Smithson | sporting goods | 1500 (4 rows) Company_B Id | emp_lname | dept | sales ------+-----------+-------------+------4321 | Marvin | home goods | 250 8765 | Zed | electronics | 20000 9012 | Marcellus | home goods | 500 3214 | Smithson | home goods | 1500 (4 rows) Company_C Id | emp_lname | dept | sales ------+-----------+----------------+------3214 | Smithson | sporting goods | 1500 5432 | Madison | sporting goods | 400 7865 | Jefferson | outdoor | 1500 1234 | Vincent | floral | 1000 (4 rows) The following query returns the IDs and last names of employees that exist in Company_A, but not in Company_B: => SELECT id, emp_lname FROM Company_A EXCEPT SELECT id, emp_lname FROM Company_B; id | emp_lname ------+----------1234 | Vincent 5678 | Butch (2 rows) The following query sorts the results of the previous query by employee last name: => SELECT id, emp_lname FROM Company_A EXCEPT SELECT id, emp_lname FROM Company_B ORDER BY emp_lname ASC; id | emp_lname ------+----------5678 | Butch 1234 | Vincent (2 rows) If you order by the column position, the query returns the same results: HP Vertica Analytic Database (7.0.x) Page 1210 of 1539 SQL Reference Manual SQL Statements => SELECT id, emp_lname FROM Company_A EXCEPT SELECT id, emp_lname FROM Company_B ORDER BY 2 ASC; id | emp_lname ------+----------5678 | Butch 1234 | Vincent (2 rows) The following query returns the IDs and last names of employees that exist in Company_A, but not in Company_B or Company_C: => SELECT id, emp_lname FROM Company_A EXCEPT SELECT id, emp_lname FROM Company_B EXCEPT SELECT id, emp_lname FROM Company_C; id | emp_lname ------+----------5678 | Butch (1 row) The following query shows the results of mismatched data types: => SELECT id, emp_lname FROM Company_A EXCEPT SELECT emp_lname, id FROM Company_B; ERROR 3429: For 'EXCEPT', types int and varchar are inconsistent DETAIL: Columns: id and emp_lname Using the VMart example database, the following query returns information about all Connecticutbased customers who bought items through stores and whose purchases amounted to more than $500, except for those customers who paid cash: => SELECT customer_key, customer_name FROM public.customer_dimension WHERE customer_key IN (SELECT customer_key FROM store.store_sales_fact WHERE sales_dollar_amount > 500 EXCEPT SELECT customer_key FROM store.store_sales_fact WHERE tender_type = 'Cash') AND customer_state = 'CT'; customer_key | customer_name --------------+---------------------15084 | Doug V. Lampert 21730 | Juanita F. Peterson 24412 | Mary U. Garnett 25840 | Ben Z. Taylor 29940 | Brian B. Dobisz 32225 | Ruth T. McNulty 33127 | Darlene Y. Rodriguez 40000 | Steve L. Lewis 44383 | Amy G. Jones HP Vertica Analytic Database (7.0.x) Page 1211 of 1539 SQL Reference Manual SQL Statements 46495 | Kevin H. Taylor (10 rows) See Also INTERSECT Clause l SELECT l l l UNION Clause FROM Clause Specifies one or more source tables from which to retrieve rows. Syntax FROM Table-Reference [ , ... ] ... [ subquery ] [AS] name ... Parameters table-reference Is a Table-Primary or a Joined-Table. Example The following example returns all records from the customer_dimension table: => SELECT * FROM customer_dimension Table-Reference Syntax Table-Primary | Joined-Table Parameters table-primary Specifies an optionally qualified table name with optional table aliases, column aliases, and outer joins. joined-table Specifies an outer join. HP Vertica Analytic Database (7.0.x) Page 1212 of 1539 SQL Reference Manual SQL Statements Table-Primary Syntax { table-name [ AS ] alias | ( Joined-Table ) } [ ( column-alias [ , ...] ) ] [ , ...] ] Parameters table-name Specifies a table in the logical schema. HP Vertica selects a suitable projection to use. alias Specifies a temporary name to be used for references to the table. column-alias Specifies a temporary name to be used for references to the column. joined-table Specifies an outer join. Joined-Table Syntax table-reference join-type table-referenceON Join-Predicate Parameters table-reference Is a Table-Primary or another joined-table. join-type Is one of the following: INNER JOINLEFT [ OUTER ] JOIN RIGHT [ OUTER ] JOIN FULL [ OUTER ] JOIN join-predicate An equi-join based on one or more columns in the joined tables. Notes A query that uses INNER JOIN syntax in the FROM clause produces the same result set as a query that uses the WHERE clause to state the join-predicate. See Joins in the Programmer's Guide for more information. GROUP BY Clause Divides a query result set into sets of rows that match an expression. HP Vertica Analytic Database (7.0.x) Page 1213 of 1539 SQL Reference Manual SQL Statements Syntax GROUP BY expression [ ,... ] Parameters expression Is any expression including constants and references to columns in the tables specified in the FROM clause. For example: column1, ..., column_n, aggregate_function (expression) Notes l The expression cannot include Aggregate Functions; however, the GROUP BY clause is often used with Aggregate Functions to return summary values for each group. l The GROUP BY clause without aggregates is similar to using SELECT DISTINCT. For example, the following two queries are equal: SELECT DISTINCT household_id from customer_dimension; SELECT household_id from customer_dimension GROUP BY household_id; l All non-aggregated columns in the SELECT list must be included in the GROUP BY clause. l Using the WHERE clause with the GROUP BY clause is useful in that all rows that do not satisfy the WHERE clause conditions are eliminated before any grouping operations are computed. l The GROUP BY clause does not order data. If you want to sort data a particular way, place the ORDER BY Clause after the GROUP BY clause. Examples In the following example, the WHERE clause filters out all employees whose last name does not begin with S. The GROUP BY clause returns the groups of last names that begin with S, and the SUM aggregate function computes the total vacation days for each group. => SELECT employee_last_name, SUM(vacation_days) FROM employee_dimension WHERE employee_last_name ILIKE 'S%' GROUP BY employee_last_name; employee_last_name | SUM --------------------+-----Sanchez | 2892 Smith | 2672 HP Vertica Analytic Database (7.0.x) Page 1214 of 1539 SQL Reference Manual SQL Statements Stein | 2660 (3 rows) => SELECT vendor_region, MAX(deal_size) as "Biggest Deal" FROM vendor_dimension GROUP BY vendor_region; vendor_region | Biggest Deal ---------------+-------------East | 990889 MidWest | 699163 NorthWest | 76101 South | 854136 SouthWest | 609807 West | 964005 (6 rows) The only difference between the following query and the one before it is the HAVING clause filters the groups to deal sizes greater than $900,000: => SELECT vendor_region, MAX(deal_size) as "Biggest Deal" FROM vendor_dimension GROUP BY vendor_region HAVING MAX(deal_size) > 900000; vendor_region | Biggest Deal ---------------+-------------East | 990889 West | 964005 (2 rows) HAVING Clause Restricts the results of a GROUP BY Clause. Syntax HAVING condition [, ...] Parameters condition Must unambiguously reference a grouping column, unless the reference appears within an aggregate function Notes l Semantically the having clause occurs after the group by operation. l You can use expressions in the HAVING clause. l The HAVING clause was added to the SQL standard because you cannot use WHERE with Aggregate Functions. HP Vertica Analytic Database (7.0.x) Page 1215 of 1539 SQL Reference Manual SQL Statements Example The following example returns the employees with salaries greater than $50,000: => SELECT employee_last_name, MAX(annual_salary) as "highest_salary" FROM employee_dimension GROUP BY employee_last_name HAVING MAX(annual_salary) > 50000; employee_last_name | highest_salary --------------------+---------------Bauer | 920149 Brown | 569079 Campbell | 649998 Carcetti | 195175 Dobisz | 840902 Farmer | 804890 Fortin | 481490 Garcia | 811231 Garnett | 963104 Gauthier | 927335 (10 rows) INTERSECT Clause Calculates the intersection of the results of two or more SELECT queries; returns all elements that exist in all the results. Syntax SELECT ... INTERSECT select ... [ INTERSECT select ]... ... [ ORDER BY { column-name ... | ordinal-number } ... [ ASC | DESC ] [ , ... ] ] ... [ LIMIT { integer | ALL } ] ... [ OFFSET integer ] Notes l Use the INTERSECT clause to return all elements that are common to the results of all the SELECT queries. The INTERSECT query operates on the results of two or more SELECT queries; it returns only the rows that are returned by all the specified queries. You cannot use the ALL keyword with an INTERSECT query. l The results of each SELECT query must be union compatible; they must return the same number of columns, and the corresponding columns must have compatible data types. For example, you cannot use the INTERSECT clause on a column of type INTEGER and a column HP Vertica Analytic Database (7.0.x) Page 1216 of 1539 SQL Reference Manual SQL Statements of type VARCHAR. If the SELECT queries do not meet these criteria, HP Vertica returns an error. Note: The Data Type Coercion Chart lists the data types that can be cast to other data types. If one data type can be cast to the other, those two data types are compatible. l You can order the results of an INTERSECT operation with an ORDER BY clause. In the ORDER BY list, specify the column names from the leftmost SELECT statement or specify integers that indicate the position of the columns by which to sort. l You can use INTERSECT in FROM, WHERE, and HAVING clauses. l The rightmost ORDER BY, LIMIT, or OFFSET clauses in an INTERSECT query do not need to be enclosed in parentheses because the rightmost query specifies that HP Vertica perform the operation on the results of the INTERSECT operation. Any ORDER BY, LIMIT, or OFFSET clauses contained in SELECT queries that appear earlier in the INTERSECT query must be enclosed in parentheses. l HP Vertica supports INTERSECT noncorrelated subquery predicates: => SELECT * FROM T1 WHERE T1.x IN (SELECT MAX(c1) FROM T2 INTERSECT SELECT MAX(cc1) FROM T3 INTERSECT SELECT MAX(d1) FROM T4); Examples Consider the following three tables: Company_A id emp_lname dept sales ------+------------+----------------+------1234 | Vincent | auto parts | 1000 5678 | Butch | auto parts | 2500 9012 | Marcellus | floral | 500 3214 | Smithson | sporting goods | 1500 Company_B id emp_lname dept sales ------+------------+-------------+------4321 | Marvin | home goods | 250 9012 | Marcellus | home goods | 500 8765 | Zed | electronics | 20000 HP Vertica Analytic Database (7.0.x) Page 1217 of 1539 SQL Reference Manual SQL Statements 3214 | Smithson | home goods | 1500 Company_C id | emp_lname | dept | sales ------+-----------+----------------+------3214 | Smithson | sporting goods | 1500 5432 | Madison | sporting goods | 400 7865 | Jefferson | outdoor | 1500 1234 | Vincent | floral | 1000 The following query returns the IDs and last names of employees that exist in both Company_A and Company_B: => SELECT id, emp_lname FROM Company_A INTERSECT SELECT id, emp_lname FROM Company_B; id | emp_lname ------+----------3214 | Smithson 9012 | Marcellus (2 rows) The following query returns the same two employees in descending order of sales: => SELECT id, emp_lname, sales FROM Company_A INTERSECT SELECT id, emp_lname, sales FROM Company_B ORDER BY sales DESC; id | emp_lname | sales ------+-----------+------3214 | Smithson | 1500 9012 | Marcellus | 500 (2 rows) You can also use the integer that represents the position of the sales column (3) to return the same result: => SELECT id, emp_lname, sales FROM Company_A INTERSECT SELECT id, emp_lname, sales FROM Company_B ORDER BY 3 DESC; id | emp_lname | sales ------+-----------+------3214 | Smithson | 1500 9012 | Marcellus | 500 (2 rows) The following query returns the employee who works for both companies whose sales in Company_ B are greater than 1000: HP Vertica Analytic Database (7.0.x) Page 1218 of 1539 SQL Reference Manual SQL Statements => SELECT id, emp_lname, sales FROM Company_A INTERSECT (SELECT id, emp_lname, sales FROM company_B WHERE sales > 1000) ORDER BY sales DESC; id | emp_lname | sales ------+-----------+------3214 | Smithson | 1500 (1 row) In the following query returns the ID and last name of the employee who works for all three companies: => SELECT id, emp_lname FROM Company_A INTERSECT SELECT id, emp_lname FROM Company_B INTERSECT SELECT id, emp_lname FROM Company_C; id | emp_lname ------+----------3214 | Smithson (1 row) The following query shows the results of a mismatched data types; these two queries are not union compatible: => SELECT id, emp_lname FROM Company_A INTERSECT SELECT emp_lname, id FROM Company_B; ERROR 3429: For 'INTERSECT', types int and varchar are inconsistent DETAIL: Columns: id and emp_lname Using the VMart example database, the following query returns information about all Connecticutbased customers who bought items online and whose purchase amounts were between $400 and $500: => SELECT customer_key, customer_name from public.customer_dimension WHERE customer_key IN (SELECT customer_key FROM online_sales.online_sales_fact WHERE sales_dollar_amount > 400 INTERSECT SELECT customer_key FROM online_sales.online_sales_fact WHERE sales_dollar_amount < 500) AND customer_state = 'CT'; customer_key | customer_name --------------+-----------------------39 | Sarah S. Winkler 44 | Meghan H. Overstreet 70 | Jack X. Jefferson 103 | Alexandra I. Vu 110 | Matt . Farmer 173 | Mary R. Reyes 188 | Steve G. Williams 233 | Theodore V. McNulty HP Vertica Analytic Database (7.0.x) Page 1219 of 1539 SQL Reference Manual SQL Statements 250 294 313 375 384 387 | | | | | | Marcus E. Williams Samantha V. Young Meghan P. Pavlov Sally N. Vu Emily R. Smith Emily L. Garcia ... The previous query returns the same data as: => SELECT customer_key,customer_name FROM public.customer_dimension WHERE customer_key IN (SELECT customer_key FROM online_sales.online_sales_fact WHERE sales_dollar_amount > 400 AND sales_dollar_amount < 500) AND customer_state = 'CT'; See Also EXCEPT Clause l SELECT l l l UNION Clause INTO Clause Creates a new table from the results of a query and fills it with data from the query. Syntax INTO [ { GLOBAL | LOCAL } { TEMPORARY | TEMP } ] ... [ TABLE ] table-name ... [ON COMMIT { PRESERVE | DELETE } ROWS ] Parameters GLOBAL [Optional] Specifies that the table definition is visible to all sessions. LOCAL [Optional] Specifies that the table is visible only to the user who creates it for the duration of the session. When the session ends, the table definition is automatically dropped from the database catalogs. TABLE [Optional] Specifies that a table is to be created. HP Vertica Analytic Database (7.0.x) Page 1220 of 1539 SQL Reference Manual SQL Statements table-name Specifies the name of the table to be created. ON COMMIT { PRESERVE | DELETE } ROWS [Optional] Specifies whether data is transaction- or session-scoped: l DELETE marks a temporary table for transactionscoped data. HP Vertica truncates the table (delete all its rows) after each commit. DELETE ROWS is the default. l PRESERVE marks a temporary table for sessionscoped data, which is preserved beyond the lifetime of a single transaction. HP Vertica truncates the table (delete all its rows) when you terminate a session. Examples The following statement creates a table called newtable and fills it with the data from customer_ dimension: => SELECT * INTO newtable FROM customer_dimension; The following statement creates a temporary table called newtable and fills it with the data from customer_dimension: => SELECT * INTO temp TABLE newtable FROM customer_dimension; The following example creates a local temporary table and inserts the contents from mytable into it: => SELECT * INTO LOCAL TEMP TABLE ltt FROM mytable; WARNING: No rows are inserted into table "v_temp_schema"."ltt" because ON COMMIT DELE TE ROWS is the default for create temporary table HINT: Use "ON COMMIT PRESERVE ROWS" to preserve the data in temporary table CREATE TABLE See Also l LIMIT Clause Specifies the maximum number of result set rows to return. Syntax LIMIT { rows | ALL } HP Vertica Analytic Database (7.0.x) Page 1221 of 1539 SQL Reference Manual SQL Statements Parameters rows Specifies the maximum number of rows to return ALL Returns all rows (same as omitting LIMIT) Notes When both LIMIT and OFFSET are used, HP Vertica skips the specified number of rows before it starts to count the rows to be returned. You can use LIMIT without an ORDER BY Clause that includes all columns in the select list, but the query could produce nondeterministic results. Nondeterministic: Omits the ORDER BY clause and returns any five records from the customer_dimension table: Deterministic: Specifies the ORDER BY clause: => SELECT customer_city FROM customer_dimension LIMIT 5; customer_city --------------Baltimore Nashville Allentown Clarksville Baltimore (5 rows) => SELECT customer_city FROM customer_dimension ORDER BY customer_city LIMIT 5; customer_city --------------Abilene Abilene Abilene Abilene Abilene (5 rows) Examples The following examples illustrate the LIMIT clause queries that HP Vertica supports: => => => => => => SELECT SELECT SELECT SELECT SELECT SELECT * * * * * * FROM FROM FROM FROM FROM FROM (SELECT * FROM t1 ORDER BY x ) alias LIMIT 3; (SELECT * FROM t1 ORDER BY x LIMIT 5) alias LIMIT 3; (SELECT * FROM t1 ORDER BY x) alias LIMIT 4 OFFSET 3; t1 UNION SELECT * FROM t2 LIMIT 3; fact JOIN dim using (x) LIMIT 3; t1 JOIN t2 USING (x) LIMIT 3; MATCH Clause A SQL extension that lets you screen large amounts of historical data in search of event patterns, the MATCH clause provides subclasses for analytic partitioning and ordering and matches rows from the result table based on a pattern you define. HP Vertica Analytic Database (7.0.x) Page 1222 of 1539 SQL Reference Manual SQL Statements You specify a pattern as a regular expression, which is composed of event types defined in the DEFINE subclause, where each event corresponds to a row in the input table. Then you can search for the pattern within a sequence of input events. Pattern matching returns the contiguous sequence of rows that conforms to PATTERN subclause. For example, pattern P (A B* C) consist of three event types: A, B, and C. When HP Vertica finds a match in the input table, the associated pattern instance must be an event of type A followed by 0 or more events of type B, and an event of type C. Pattern matching is particularly useful for clickstream analysis where you might want to identify users' actions based on their Web browsing behavior (page clicks). A typical online clickstream funnel is: Company home page -> product home page -> search -> results -> purchase online Using the above clickstream funnel, you can search for a match on the user's sequence of web clicks and identify that the user: l Landed on the company home page l Navigated to the product page l Ran a search l Clicked a link from the search results l Made a purchase For examples that use this clickstream model, see Event Series Pattern Matching in the Programmer's Guide. Syntax MATCH ( [ PARTITION BY table_column ] ORDER BY table_column ... DEFINE event_name AS boolean_expr [, ...] ... PATTERN pattern_name AS ( regexp ) ... [ ROWS MATCH ( ALL EVENTS | FIRST EVENT ) ] ) Parameters PARTITION BY [Optional] Defines the window data scope in which the pattern, defined in the PATTERN subclause, is matched. The partition clause partitions the data by matched patterns defined in the PATTERN subclause. For each partition, data is sorted by the ORDER BY clause. If the partition clause is omitted, the entire data set is considered a single partition. HP Vertica Analytic Database (7.0.x) Page 1223 of 1539 SQL Reference Manual SQL Statements ORDER BY Defines the window data scope in which the pattern, defined in the PATTERN subclause, is matched. For each partition, the order clause specifies how the input data is ordered for pattern matching. Note: The ORDER BY clause is mandatory. DEFINE Defines the boolean expressions that make up the event types in the regular expressions. For example: DEFINE Entry Onsite AS RefURL NOT ILIKE '%website2.com%' AND PageURL ILIKE '%website2.com%', AS PageURL ILIKE '%website2.com%' AND Action='V', Purchase AS PageURL ILIKE '%website2.com%' AND Action='P' The DEFINE subclause accepts a maximum of 52 events. See Event Series Pattern Matching in the Programmer's Guide for examples. event_name Is the name of the event to evaluate for each row; for example, Entry, Onsite, Purchase. Note: Event names are case insensitive and follow the same naming conventions as those used for tables and columns. boolean_expr Is an expression that returns true or false. boolean_expr can include Boolean Operators and relational (comparison) operators. For example: Purchase AS PageURL ILIKE '%website2.com%' AND Action = 'P' PATTERN pattern_name Is the name of the pattern, which you define in the PATTERN subclause; for example, P is the pattern name defined below: PATTERN P AS (...) PATTERN defines the regular expression composed of event types that you specify in the DEFINE subclause. HP Vertica supports one pattern per query. HP Vertica Analytic Database (7.0.x) Page 1224 of 1539 SQL Reference Manual SQL Statements regexp Is the pattern that is composed of the event types defined in the DEFINE subclause and which returns the contiguous sequence of rows that conforms to the PATTERN subclause. * Match 0 or more times *? Match 0 or more times, not greedily + Match 1 or more times +? Match 1 or more times, not greedily ? Match 0 or 1 time ?? Match 0 or 1 time, not greedily *+ Match 0 or more times, possessive ++ Match 1 or more times, possessive ?+ Match 0 or 1 time, possessive Note: Syntax for regular expressions is compatible with the Perl 5 regular expression syntax. See the Perl Regular Expressions Documentation for details. ROWS MATCH [Optional] Defines how to resolve more than one event evaluating to true for a single row. l If you use ROWS MATCH ALL EVENTS (default), HP Vertica returns the following run-time error if more than one event evaluates to true for a single row: ERROR: pattern events must be mutually exclusive HINT: l try using ROWS MATCH FIRST EVENT For ROWS MATCH FIRST EVENT, if more than one event evaluates to true for a single row, HP Vertica chooses the event defined first in the SQL statement to be the event it uses for the row. Pattern Semantic Evaluation l The semantic evaluating ordering of the SQL clauses is: FROM -> WHERE -> PATTERN MATCH -> SELECT. l Data is partitioned as specified in the the PARTITION BY clause. If the partition clause is omitted, the entire data set is considered a single partition. HP Vertica Analytic Database (7.0.x) Page 1225 of 1539 SQL Reference Manual SQL Statements l For each partition, the order clause specifies how the input data is ordered for pattern matching. l Events are evaluated for each row. A row could have 0, 1, or N events evaluate to true. If more than one event evaluates to true for the same row, HP Vertica returns a run-time error unless you specify ROWS MATCH FIRST EVENT. If you specify ROWS MATCH FIRST EVENT and more than one event evaluates to TRUE for a single row, HP Vertica chooses the event that was defined first in the SQL statement to be the event it uses for the row. l HP Vertica performs pattern matching by finding the contiguous sequence of rows that conforms to the pattern defined in the PATTERN subclause. For each match, HP Vertica outputs the rows that contribute to the match. Rows not part of the match (do not satisfy one or more predicates) are not output. l HP Vertica reports only non-overlapping matches. If an overlap occurs, HP Vertica chooses the first match found in the input stream. After finding the match, HP Vertica looks for the next match, starting at the end of the previous match. l HP Vertica reports the longest possible match, not a subset of a match. For example, consider pattern: A*B with input: AAAB. Because A uses the greedy regular expression quantifier (*), HP Vertica reports all A inputs (AAAB), not AAB, AB, or B. Notes and Restrictions l DISTINCT and GROUP BY/HAVING clauses are not allowed in pattern match queries. l The following expressions are not allowed in the DEFINE subclause: l n Subqueries, such as DEFINE X AS c IN (SELECT c FROM table1) n Analytic functions, such as DEFINE X AS c < LEAD(1) OVER (ORDER BY 1) n Aggregate functions, such as DEFINE X AS c < MAX(1) You cannot use the same pattern name to define a different event; for example, the following is not allowed for X: DEFINE X AS c1 < X AS c1 >= 3 l 3 Used with MATCH clause, HP Vertica Pattern Matching Functions provide additional data about the patterns it finds. For example, you can use the functions to return values representing the name of the event that matched the input row, the sequential number of the match, or a partitionwide unique identifier for the instance of the pattern that matched. Examples For examples, see Event Series Pattern Matching in the Programmer's Guide. HP Vertica Analytic Database (7.0.x) Page 1226 of 1539 SQL Reference Manual SQL Statements See Also l Pattern Matching Functions l EVENT_NAME l MATCH_ID l PATTERN_ID l Perl Regular Expressions Documentation MINUS Clause MINUS is an alias for EXCEPT. OFFSET Clause Omits a specified number of rows from the beginning of the result set. Syntax OFFSET rows Parameters rows specifies the number of result set rows to omit. Notes l When both LIMIT and OFFSET are specified, specified number of rows are skipped before starting to count the rows to be returned. l When using OFFSET, use an ORDER BY Clause. Otherwise the query returns an undefined subset of the result set. Example The following example is similar to the the example used in the LIMIT Clause. If you want to see just records 6–10, however, use the OFFSET clause to skip over the first five cities: => SELECT customer_city FROM customer_dimension WHERE customer_name = 'Metamedia' ORDER BY customer_city HP Vertica Analytic Database (7.0.x) Page 1227 of 1539 SQL Reference Manual SQL Statements OFFSET 5; customer_city -----------------El Monte Fontana Hartford Joliet Peoria Rancho Cucamonga Ventura Waco Wichita Falls (9 rows) The following are the results without the OFFSET clause: customer_city -----------------Arvada Arvada Athens Beaumont Coral Springs El Monte Fontana Hartford Joliet Peoria Rancho Cucamonga Ventura Waco Wichita Falls (14 rows) ORDER BY Clause Sorts a query result set on one or more columns. Syntax ORDER BY expression [ ASC | DESC ] [, ...] HP Vertica Analytic Database (7.0.x) Page 1228 of 1539 SQL Reference Manual SQL Statements Parameters expression Can be: l The name or ordinal number of a SELECT list item l An arbitrary expression formed from columns that do not appear in the SELECT list l A CASE expression Notes l The ordinal number refers to the position of the result column, counting from the left beginning at one. This makes it possible to order by a column that does not have a unique name. (You can assign a name to a result column using the AS clause.) l While the user's current locale and collation sequence are used to compare strings and determine the results of the ORDER BY clause of a query, data in HP Vertica projections is always stored sorted by the ASCII (binary) collating sequence. l For INTEGER, INT, and DATE/TIME data types, NULL appears first (smallest) in ascending order. l For FLOAT, BOOLEAN, CHAR, and VARCHAR, NULL appears last (largest) in ascending order. Example The follow example returns all the city and deal size for customer Metamedia, sorted by deal size in descending order. => SELECT customer_city, deal_size FROM customer_dimension WHERE customer_name = 'Metamedia' ORDER BY deal_size DESC; customer_city | deal_size ------------------+----------El Monte | 4479561 Athens | 3815416 Ventura | 3792937 Peoria | 3227765 Arvada | 2671849 Coral Springs | 2643674 Fontana | 2374465 Rancho Cucamonga | 2214002 Wichita Falls | 2117962 Beaumont | 1898295 Arvada | 1321897 HP Vertica Analytic Database (7.0.x) Page 1229 of 1539 SQL Reference Manual SQL Statements Waco Joliet Hartford (14 rows) | | | 1026854 945404 445795 TIMESERIES Clause Provides gap-filling and interpolation (GFI) computation, an important component of time series analytics computation. See Using Time Series Analytics in the Programmer's Guide for details and examples. Syntax TIMESERIES slice_time AS 'length_and_time_unit_expression' OVER ( ... [ window_partition_clause [ , ... ] ] ... ORDER BY time_expression ) ... [ ORDER BY table_column [ , ... ] ] Parameters slice_time A time column produced by the TIMESERIES clause, which stores the time slice start times generated from gap filling. Note: This parameter is an alias, so you can use any name that an alias would take. 'length_and_time_unit_expression' Is INTERVAL (DAY TO SECOND) that represents the length of time unit of time slice computation; for example, TIMESERIES slice_time AS '3 seconds' ... OVER() Specifies partitioning and ordering for the function. OVER() also specifies that the time series function operates on a query result set (the rows that are returned after the FROM, WHERE, GROUP BY, and HAVING clauses have been evaluated). PARTITION BY Partitions the data by expressions (column1 ..., column_n, slice_time). expression Expressions on which to partition the data, where each partition is sorted by time_expression. Gap filling and interpolation is performed on each partition separately. ORDER BY Sorts the data by time_expression. Note: The TIMESERIES clause requires an ORDER BY operation on the timestamp column. HP Vertica Analytic Database (7.0.x) Page 1230 of 1539 SQL Reference Manual SQL Statements time_expression An expression that computes the time information of the time series data. The time_expression can be TIMESTAMP data type only. Notes If the window_partition_clause is not specified in TIMESERIES OVER(), for each defined time slice, exactly one output record is produced; otherwise, one output record is produced per partition per time slice. Interpolation is computed there. Given a query block that contains a TIMESERIES clause, the following are the semantic phases of execution (after evaluating the FROM and the optional WHERE clauses): 1. Compute time_expression. 2. Perform the same computation as the TIME_SLICE() function on each input record based on the result of time_expression and 'length_and_time_unit_expression'. a. Perform gap filling to generate time slices missing from the input. b. Name the result of this computation as slice_time, which represents the generated “time series” column (alias) after gap filling. 3. Partition the data by expression, slice_time. For each partition, do step 4. 4. Sort the data by time_expression. Interpolation is computed here. There is semantic overlap between the TIMESERIES clause and the TIME_SLICE function with the following key differences: l TIMESERIES only supports the DAY TO SECOND Interval-Qualifier (does not allow YEAR TO MONTH). l Unlike TIME_SLICE, the time slice length and time unit expressed in length_and_time_unit_ expr must be constants so gaps in the time slices are well-defined. l TIMESERIES performs gap filling; the TIME_SLICE function does not. l TIME_SLICE can return the start or end time of a time slice, depending on the value of its fourth input parameter (start_or_end). TIMESERIES, on the other hand, always returns the start time of each time slice. To output the end time of each time slice, you can write a SELECT statement like the following: SELECT slice_time + ; HP Vertica Analytic Database (7.0.x) Page 1231 of 1539 SQL Reference Manual SQL Statements Restrictions When the TIMESERIES clause occurs in a SQL query block, only SELECT, FROM, WHERE, and ORDER BY clauses can be used in that same query block. GROUP BY and HAVING clauses are not allowed. l If a GROUP BY operation is needed before or after gap-filling and interpolation (GFI), use a subquery and place the GROUP BY In the outer query. For example: => SELECT symbol, AVG(first_bid) as avg_bid FROM ( SELECT symbol, slice_time, TS_FIRST_VALUE(bid1) AS first_bid FROM Tickstore WHERE symbol IN ('MSFT', 'IBM') TIMESERIES slice_time AS '5 seconds' OVER (PARTITION BY symbol ORDER BY ts) ) AS resultOfGFI GROUP BY symbol; When the TIMESERIES clause is present in the SQL query block, only time series aggregate functions (such as TS_FIRST_VALUE and TS_LAST_VALUE), the slice_time column, PARTITION BY expressions, and TIME_SLICE are allowed in the SELECT list. For example, the following two queries would return a syntax error because bid1 was not a PARTITION BY or GROUP BY column: l => SELECT bid, symbol, TS_FIRST_VALUE(bid) FROM Tickstore TIMESERIES slice_time AS '5 seconds' OVER (PARTITION BY symbol ORDER BY ts); ERROR: column "Tickstore.bid" must appear in the PARTITION BY list of Timeseries c lause or be used in a Timeseries Output function => SELECT bid, symbol, AVG(bid) FROM Tickstore GROUP BY symbol; ERROR: column "Tickstore.bid" must appear in the GROUP BY clause or be used in an aggregate function Examples For examples, see Gap Filling and Interpolation (GFI) in the Programmer's Guide. See Also l TIME_SLICE l TS_FIRST_VALUE TS_LAST_VALUE l l HP Vertica Analytic Database (7.0.x) Page 1232 of 1539 SQL Reference Manual SQL Statements UNION Clause Combines the results of two or more SELECT statements. Syntax SELECT ... UNION { ALL | DISTINCT } select ... [ UNION { ALL | DISTINCT } select ]... ... [ ORDER BY { column-name | ordinal-number } ... [ ASC | DESC ] [ , ... ] ] ... [ LIMIT { integer | ALL } ] ... [ OFFSET integer ] Notes l The UNION operation combines the results of several SELECT statements into a single result. Specifically, all rows in the result of a UNION operation must exist in the results of at least one of the SELECT statements. l The results of each SELECT statement must be union compatible; they must return the same number of columns, and the corresponding columns must have compatible data types. For example, you cannot use the UNION clause on a column of type INTEGER and a column of type VARCHAR. If they do not meet these criteria, HP Vertica returns an error. Note: The Data Type Coercion Chart lists the data types that can be cast to other data types. If one data type can be cast to the other, those two data types are compatible. l The results of a UNION contain only distinct rows. UNION ALL keeps all duplicate rows, and so results in better performance than UNION. Therefore, unless you must eliminate duplicates, use UNION ALL for best performance. l You can use UNION [ALL] in FROM, WHERE, and HAVING clauses. l You can order the results of an UNION operation with an ORDER BY clause. In the ORDER BY list, specify the column names from the leftmost SELECT statement or specify integers that indicate the position of the columns by which to sort. l The rightmost ORDER BY, LIMIT, or OFFSET clauses in a UNION query do not need to be enclosed in parentheses because the rightmost query specifies that HP Vertica perform the operation on the results of the UNION operation. Any ORDER BY, LIMIT, or OFFSET clauses contained in SELECT queries that appear earlier in the UNION query must be enclosed in parentheses. l HP Vertica supports UNION noncorrelated subquery predicates: => SELECT * FROM T1 WHERE T1.x IN HP Vertica Analytic Database (7.0.x) Page 1233 of 1539 SQL Reference Manual SQL Statements (SELECT MAX(c1) FROM T2 UNION { ALL | DISTINCT } SELECT MAX(cc1) FROM T3 UNION { ALL | DISTINCT } SELECT MAX(d1) FROM T4); Examples Consider the following two tables: Company_A Id emp_lname dept sales ------+------------+-------------+------1234 | Vincent | auto parts | 1000 5678 | Butch | auto parts | 2500 9012 | Marcellus | floral | 500 Company_B Id emp_lname dept sales ------+------------+-------------+------4321 | Marvin | home goods | 250 9012 | Marcellus | home goods | 500 8765 | Zed | electronics | 20000 The following query lists all distinct IDs and last names of employees; Marcellus works for both companies, so he only appears once in the results. The DISTINCT keyword is the default; if you omit the DISTINCT keyword, the query returns the same results: => SELECT id, emp_lname FROM Company_A UNION DISTINCT SELECT id, emp_lname FROM Company_B; id | emp_lname ------+----------1234 | Vincent 4321 | Marvin 5678 | Butch 8765 | Zed 9012 | Marcellus (5 rows) The following query lists all IDs and surnames of employees. Marcellus works for both companies, so both his records appear in the results: => SELECT id, emp_lname FROM Company_A UNION ALL SELECT id, emp_lname FROM Company_B; id | emp_lname ------+----------- HP Vertica Analytic Database (7.0.x) Page 1234 of 1539 SQL Reference Manual SQL Statements 1234 | Vincent 5678 | Butch 9012 | Marcellus 4321 | Marvin 9012 | Marcellus 8765 | Zed (6 rows) The next example returns the top two performing salespeople in each company and orders the full results in descending order of sales: => (SELECT id, emp_lname, sales FROM Company_A ORDER BY sales DESC LIMIT 2) UNION ALL (SELECT id, emp_lname, sales FROM Company_b ORDER BY sales DESC LIMIT 2) ORDER BY sales DESC; id | emp_lname | sales ------+-----------+------8765 | Zed | 20000 5678 | Butch | 2500 1234 | Vincent | 1000 9012 | Marcellus | 500 (4 rows) The following query returns all employee orders by sales. The rightmost clause (ORDER BY) is applied to the entire result, listing the sales in ascending order: => SELECT id, emp_lname, sales FROM Company_A UNION SELECT id, emp_lname, sales FROM Company_B ORDER BY sales; id | emp_lname | sales ------+-----------+------4321 | Marvin | 250 9012 | Marcellus | 500 1234 | Vincent | 1000 5678 | Butch | 2500 8765 | Zed | 20000 (5 rows) To calculate the sum of the sales for each company, grouped by department, use this query: => (SELECT 'Company A' as company, dept, SUM(sales) FROM Company_A GROUP BY dept) UNION (SELECT 'Company B' as company, dept, SUM(sales) FROM Company_B GROUP BY dept) ORDER BY 1; company | dept | sum -----------+-------------+------Company A | auto parts | 3500 Company A | floral | 500 HP Vertica Analytic Database (7.0.x) Page 1235 of 1539 SQL Reference Manual SQL Statements Company B | electronics | 20000 Company B | home goods | 750 (4 rows) The following query shows the results of mismatched data types: => SELECT id, emp_lname FROM Company_A UNION SELECT emp_lname, id FROM Company_B; ERROR 3429: For 'UNION', types int and varchar are inconsistent DETAIL: Columns: id and emp_lname Using the VMart example database, the following query returns information about all Connecticutbased customers who bought items through either stores or online sales channels and whose purchases totaled more than $500: => SELECT DISTINCT customer_key, customer_name FROM public.customer_dimension tomer_key IN (SELECT customer_key FROM store.store_sales_fact WHERE sales_dollar_amount > 500 UNION ALL SELECT customer_key FROM online_sales.online_sales_fact WHERE sales_dollar_amount > 500) AND customer_state = 'CT'; customer_key | customer_name --------------+-----------------------955 | Darlene N. Vu 48916 | Tanya H. Wilson 43123 | Luigi I. Fortin 33780 | Ben T. Nielson 24827 | Luigi . Kramer 21631 | Jack R. Perkins 31493 | Matt E. Miller 12438 | Samantha Q. Campbell 7021 | Luigi T. Dobisz 5229 | Julie V. Garcia 1971 | Betty V. Dobisz ... WHERE cus See Also l EXCEPT Clause l INTERSECT Clause l SELECT l Subqueries WHERE Clause Eliminates rows from the result table that do not satisfy one or more predicates. HP Vertica Analytic Database (7.0.x) Page 1236 of 1539 SQL Reference Manual SQL Statements Syntax WHERE boolean-expression [ subquery ] ... Parameters boolean-expression Is an expression that returns true or false. Only rows for which the expression is true become part of the result set. The boolean-expression can include Boolean Operators and the following elements: l BETWEEN-predicate l Boolean-Predicate l Column-Value-Predicate l IN-predicate l Join-Predicate l LIKE-predicate l NULL-predicate Notes You can use parentheses to group expressions, predicates, and boolean operators. For example: => ... WHERE NOT (A=1 AND B=2) OR C=3; Example The following example returns the names of all customers in the Eastern region whose name starts with 'Amer'. Without the WHERE clause filter, the query returns all customer names in the customer_dimension table. => SELECT DISTINCT customer_name FROM customer_dimension WHERE customer_region = 'East' AND customer_name ILIKE 'Amer%'; customer_name --------------Americare Americom Americore Americorp HP Vertica Analytic Database (7.0.x) Page 1237 of 1539 SQL Reference Manual SQL Statements Ameridata Amerigen Amerihope Amerimedia Amerishop Ameristar Ameritech (11 rows) WINDOW Clause Creates a named window for an analytics query so you can avoid typing long OVER() clause syntax. Syntax WINDOW window_name AS ( window_definition_clause ); [ window_partition_clause ] [ window_order_clause ] Parameters WINDOW window_name Specifies that window name. AS window_definition_clause Defines the window_partition_clause and window_order_clause See Also Analytic Functions l l WITH Clause WITH clauses are individually-evaluated SELECT statements for use in a larger, container query. Each WITH clause is evaluated once while processing the main query, though it can be used in subsequent WITH clauses to create combinatorial results. HP Vertica maintains the results of each concomitant WITH statement as if it were a temporary table, stored only for the duration of the container query's execution. Each WITH clause query must have a unique name. Attempting to use same-name aliases for WITH clause query names causes an error. Syntax This syntax statement is illustrative, rather than syntactically exact, to show the possibility of numerous successive WITH queries in use with others: WITH... with_query_1 [(col_name[,...])]AS (SELECT ...), ... with_query_2 [(col_name[,...])]AS (SELECT ...[with_query_1]), HP Vertica Analytic Database (7.0.x) Page 1238 of 1539 SQL Reference Manual SQL Statements . . . ... with_query_n [(col_name[,...])]AS (SELECT ...[with_query1, with_query_2, with_query_n [,.. .]]) SELECT . . . Restrictions There are two restrictions when using WITH clauses: l Do not support INSERT, UPDATE, or DELETE statements. l Cannot be used recursively, only in succession. Examples Consider the following example: -- Begin WITH clauses, -- First WITH clause,regional_sales WITH regional_sales AS ( SELECT region, SUM(amount) AS total_sales FROM orders GROUP BY region), -- Second WITH clause top_regions top_regions AS ( SELECT region FROM regional_sales WHERE total_sales > (SELECT SUM (total_sales)/10 FROM regional_sales) ) -- End defining WITH clause statement -- Begin main primary query SELECT region, product, SUM(quantity) AS product_units, SUM(amount) AS product_sales FROM orders WHERE region IN (SELECT region FROM top_regions) GROUP BY region, product; See Also SELECT l l l HP Vertica Analytic Database (7.0.x) Page 1239 of 1539 SQL Reference Manual SQL Statements SET DATESTYLE Specifies the format of date/time output for the current session. Syntax SET DATESTYLE TO { value | 'value' } [ ,... ] Parameters The DATESTYLE parameter can have multiple, non-conflicting values: Value Interpretation Example MDY month-day-year 12/16/2011 DMY day-month-year 16/12/2011 YMD year-month-day 2011-12-16 ISO ISO 8601/SQL standard (default) 2011-12-16 07:37:16-08 POSTGRES verbose style Fri Dec 16 07:37:16 2012 PST SQL traditional style 12/16/2011 07:37:16.00 PST GERMAN regional style 16.12.2011 07:37:16.00 PST In the SQL style, if DMY field ordering has been specified, the day appears before the month. Otherwise, the month appears before the day. (To see how this setting also affects interpretation of input values, see Date/Time Literals.) The following table shows an example. DATESTYLE Input Ordering Example Output SQL, DMY day/month/year 17/12/2007 15:37:16.00 CET SQL, MDY month/day/year 12/17/2007 07:37:16.00 PST Permissions No special permissions required. Notes l HP Vertica ISO output for DATESTYLE is ISO long form, but several input styles are accepted. If the year appears first in the input, YMD is used for input and output, regardless of the DATESTYLE value. HP Vertica Analytic Database (7.0.x) Page 1240 of 1539 SQL Reference Manual SQL Statements l The SQL standard requires the use of the ISO 8601 format. l INTERVAL output looks like the input format, except that units like CENTURY or WEEK are converted to years and days, and AGO is converted to the appropriate sign. In ISO mode, the output looks like [ quantity unit [ ... ] ] [ days ] [ hours:minutes:seconds ] l The SHOW command displays the run-time parameters. Example The following examples show how the DATESTYLE parameter affects the output of the SELECT INTERVAL command: =>SHOW DATESTYLE; name | setting -----------+---------datestyle | ISO, MDY => SELECT INTERVALYM '-12-11', INTERVAL '-10 15:05:1.234567'; ?column? | ?column? ----------+---------------------12-11 | -10 15:05:01.234567 => SET INTERVALSTYLE TO UNITS; SET => SELECT INTERVALYM '-12-11', INTERVAL '-10 15:05:1.234567'; ?column? | ?column? ---------------------+--------------------------12 years 11 months | -10 days 15:05:01.234567 => SET DATESTYLE TO SQL;; SET => SELECT INTERVALYM '-12-11', INTERVAL '-10 15:05:1.234567'; ?column? | ?column? ----------+---------------------12-11 | -10 15:05:01.234567 => SET DATESTYLE TO POSTGRES; SET => SELECT INTERVALYM '-12-11', INTERVAL '-10 15:05:1.234567'; ?column? | ?column? --------------------------+--------------------------------------------@ 12 years 11 months ago | @ 10 days 15 hours 5 mins 1.234567 secs ago => SET DATESTYLE TO GERMAN; SET => SELECT INTERVALYM '-12-11', INTERVAL '-10 15:05:1.234567'; ?column? | ?column? ---------------------+--------------------------12 years 11 months | -10 days 15:05:01.234567 SET ESCAPE_STRING_WARNING Issues a warning when a backslash is used in a string literal during the current session. HP Vertica Analytic Database (7.0.x) Page 1241 of 1539 SQL Reference Manual SQL Statements Syntax SET ESCAPE_STRING_WARNING TO { ON | OFF } Parameters ON [Default] Issues a warning when a back slash is used in a string literal. Tip: Organizations that have upgraded from earlier versions of HP Vertica can use this as a debugging tool for locating backslashes that used to be treated as escape characters, but are now treated as literals. OFF Ignores back slashes within string literals. Permissions No special permissions required. Notes l This statement works under vsql only. l Turn off standard conforming strings before you turn on this parameter. Tip: To set escape string warnings across all sessions, use the EscapeStringWarnings configuration parameter. See the Internationalization Parameters in the Administrator's Guide. Examples The following example shows how to turn OFF escape string warnings for the session. => SET ESCAPE_STRING_WARNING TO OFF; See Also l SET STANDARD_CONFORMING_STRINGS SET INTERVALSTYLE Specifies whether to include units in interval output for the current session. HP Vertica Analytic Database (7.0.x) Page 1242 of 1539 SQL Reference Manual SQL Statements Syntax SET INTERVALSTYLE TO [ plain | units ] Parameters plain Sets the default interval output to omit units. PLAIN is the default value. units Enables interval output to include units. When you enable interval units, the DATESTYLE parameter controls the output. If you enable units and they do not display in the output, check the DATESTYLE parameter value, which must be set to ISO or POSTGRES for interval units to display. Permissions No special permissions required. Output Intervals with Units The following statement sets the INTERVALSTYLE output to show units: => SET INTERVALSTYLE TO UNITS; SET => SELECT INTERVAL '3 2' DAY TO HOUR; ?column? -------------3 days 2 hours (1 row) Output Intervals Without Units This statement sets the INTERVALSTYLE to plain (no units) on output: => SET INTERVALSTYLE TO PLAIN; SET => SELECT INTERVAL '3 2' DAY TO HOUR; ?column? ---------3 2 (1 row) Displaying the Current Interval OUTPUT Style Use the SHOW command to display the INTERVALSTYLE runtime parameter: => SHOW INTERVALSTYLE; HP Vertica Analytic Database (7.0.x) Page 1243 of 1539 SQL Reference Manual SQL Statements name | setting ---------------+--------intervalstyle | plain (1 row) See Also l INTERVAL SET LOCALE Specifies the locale for the current session. Syntax SET LOCALE TO < ICU-locale-identifier > Parameters < ICU-locale-identifier > Specifies the ICU locale identifier to use. By default, the locale for the database is en_US@collation=binary (English as in the United States of America). ICU Locales were developed by the ICU Project. See the ICU User Guide (http://userguide.icu-project.org/locale) for a complete list of parameters that can be used to specify a locale. Note: The only keyword HP Vertica supports is the COLLATION keyword. Note: Single quotes are mandatory to specify the collation. Permissions No special permissions required. Notes Though not inclusive, the following are some commonly-used locales: l German (Germany) de_DE l English (Great Britain) en_GB l Spanish (Spain) es_ES HP Vertica Analytic Database (7.0.x) Page 1244 of 1539 SQL Reference Manual SQL Statements l French (France) fr_FR l Portuguese (Brazil) pt_BR l Portuguese (Portugal) pt_PT l Russian (Russia) ru_RU l Japanese (Japan) ja_JP l Chinese (China, simplified Han) zh_CN l Chinese (Taiwan, traditional Han) zh_Hant_TW Session related: l The locale setting is session scoped and applies to queries only (no DML/DDL) run in that session. You cannot specify a locale for an individual query. l The default locale for new sessions can be set using a configuration parameter Query related: The following restrictions apply when queries are run with locale other than the default en_ US@collation=binary: l Multicolumn NOT IN subqueries are not supported when one or more of the left-side NOT IN columns is of CHAR or VARCHAR data type. For example: => CREATE TABLE test (x VARCHAR(10), y INT); => SELECT ... FROM test WHERE (x,y) NOT IN (SELECT ...); ERROR: Multi-expression NOT IN subquery is not supported because a left hand expres sion could be NULL Note: An error is reported even if columns test.x and test.y have a "NOT NULL" constraint. l Correlated HAVING clause subqueries are not supported if the outer query contains a GROUP BY on a CHAR or a VARCHAR column. In the following example, the GROUP BY x in the outer query causes the error: => DROP TABLE test CASCADE; => CREATE TABLE test (x VARCHAR(10)); => SELECT COUNT(*) FROM test t GROUP BY x HAVING x IN (SELECT x FROM test WHERE t.x||'a' = test.x||'a' ); ERROR: subquery uses ungrouped column "t.x" from outer query l Subqueries that use analytic functions in the HAVING clause are not supported. For example: HP Vertica Analytic Database (7.0.x) Page 1245 of 1539 SQL Reference Manual SQL Statements => DROP TABLE test CASCADE; => CREATE TABLE test (x VARCHAR(10)); => SELECT MAX(x)OVER(PARTITION BY 1 ORDER BY 1) FROM test GROUP BY x HAVING x IN (SELECT MAX(x) FROM test); ERROR: Analytics query with having clause expression that involves aggregates and subq uery is not supported DML/DDL related: l SQL identifiers (such as table names, column names, and so on) can use UTF-8 Unicode characters. For example, the following CREATE TABLE statement uses the ß (German eszett) in the table name: => CREATE TABLE straße(x int, y int); CREATE TABLE l Projection sort orders are made according to the default en_US@collation=binary collation. Thus, regardless of the session setting, issuing the following command creates a projection sorted by col1 according to the binary collation: => CREATE PROJECTION p1 AS SELECT * FROM table1 ORDER BY col1; Note that in such cases, straße and strasse would not be near each other on disk. Sorting by binary collation also means that sort optimizations do not work in locales other than binary. HP Vertica returns the following warning if you create tables or projections in a nonbinary locale: WARNING: Projections are always created and persisted in the default HP Vertica local e. The current locale is de_DE l When creating pre-join projections, the projection definition query does not respect the locale or collation setting. This means that when you insert data into the fact table of a pre-join projection, referential integrity checks are not locale or collation aware. For example: \locale LDE_S1 -- German => CREATE TABLE dim (col1 varchar(20) primary key); => CREATE TABLE fact (col1 varchar(20) references dim(col1)); => CREATE PROJECTION pj AS SELECT * FROM fact JOIN dim ON fact.col1 = dim.col1 UNSEGMENTED ALL NODES; => INSERT INTO dim VALUES('ß'); => COMMIT; HP Vertica Analytic Database (7.0.x) Page 1246 of 1539 SQL Reference Manual SQL Statements The following INSERT statement fails with a "nonexistent FK" error even though 'ß' is in the dim table, and in the German locale 'SS' and 'ß' refer to the same character. => INSERT INTO fact VALUES('SS'); ERROR: Nonexistent foreign key value detected in FK-PK join (fact x dim) using subquery and dim_node0001; value SS => => ROLLBACK; => DROP TABLE dim, fact CASCADE; l When the locale is non-binary, the collation function is used to transform the input to a binary string which sorts in the proper order. This transformation increases the number of bytes required for the input according to this formula: result_column_width = input_octet_width * CollationExpansion + 4 CollationExpansion defaults to 5. l CHAR fields are displayed as fixed length, including any trailing spaces. When CHAR fields are processed internally, they are first stripped of trailing spaces. For VARCHAR fields, trailing spaces are usually treated as significant characters; however, trailing spaces are ignored when sorting or comparing either type of character string field using a non-BINARY locale. Examples This example sets the locale for the session to en_GB (English as in Great Britain). SET LOCALE TO en_GB; INFO: Locale: 'en_GB' INFO: English (United Kingdom) INFO: Short form: 'LEN' You can also use the short form of a locale in this command: SET LOCALE TO LEN; INFO: Locale: 'en' INFO: English INFO: Short form: 'LEN' Single quotes are mandatory to specify the collation: SET LOCALE TO 'tr_tr@collation=standard'; INFO: Locale: 'tr_TR@collation=standard' Standard collation: 'LTR' Turkish (Turkey, collation=standard) Türkçe (Türkiye, Sıralama=standard) SET HP Vertica Analytic Database (7.0.x) Page 1247 of 1539 SQL Reference Manual SQL Statements See Also l l SET ROLE Enables a role for the current user's current session. The user will gain the permissions that have been granted to the role. Syntax SET ROLE { role [, ...] | NONE | ALL | DEFAULT } Parameters role [, ...] | NONE | ALL | DEFAULT The name of one or more roles to set as the current role, or one of the following keywords: l NONE disables all roles for the current session. l ALL enables all of the roles to which the user has access. l DEFAULT sets the current role to the user's default role. Permissions You can only set a role that has been granted to you. Run the SHOW AVAILABLE_ROLES command to get a list of the roles available to the user. Notes l The default role is the first role that was assigned to the user or set by the superuser via the ALTER USER statement's DEFAULT ROLE argument. l Enabling a role does not affect any other roles that are currently enabled. A user session can have more than one role enabled at a time. The user's permissions are the union of all the roles that are currently active, plus any permissions granted directly to the user. HP Vertica Analytic Database (7.0.x) Page 1248 of 1539 SQL Reference Manual SQL Statements Example => SHOW ENABLED_ROLES; -- Which roles are active now. name | setting ---------------+---------------------------enabled roles | (1 row) => SHOW AVAILABLE_ROLES; -- All roles the user can access name | setting -----------------+---------------------------available roles | applogs, appadmin, appuser (1 row) => SET ROLE applogs; SET => SHOW ENABLED_ROLES; name | setting ---------------+--------enabled roles | applogs (1 row) => SET ROLE appuser; SET => SHOW ENABLED_ROLES; name | setting ---------------+-----------------enabled roles | applogs, appuser (1 row) => SET ROLE NONE; -- disable all roles SET dbadmin=> SHOW ENABLED_ROLES; name | setting ---------------+--------enabled roles | (1 row) SET SEARCH_PATH Specifies the order in which HP Vertica searches schemas when a SQL statement contains an unqualified table name. HP Vertica provides the SET search_path statement instead of the CURRENT_SCHEMA statement found in some other databases. Syntax 1 SET SEARCH_PATH [ TO | = ] schemaname [ , ... ] Syntax 2 SET SEARCH_PATH [ TO | = ] default HP Vertica Analytic Database (7.0.x) Page 1249 of 1539 SQL Reference Manual SQL Statements Parameters schemaname A comma-delimited list of schemas that indicates the order in which HP Vertica searches schemas when a SQL statement contains an unqualified table name. The default value for this parameter is '"$user", public' Where: default l $user is the schema with the same name as the current user. If the schema does not exist, $user is ignored. l public is the public database. Public is ignored if there is no schema named 'public'. Returns the search path to the default value of '"$user", public'. Permissions No special permissions required. Notes The first schema named in the search path is called the current schema. The current schema is the first schema that HP Vertica searches. It is also the schema in which HP Vertica creates new tables if the CREATE TABLE command does not specify a schema name. Examples The following example shows the current search path settings: => SHOW SEARCH_PATH; name | setting -------------+--------------------------------------------------search_path | "$user", public, v_catalog, v_monitor, v_internal (1 row) This command sets the order in which HP Vertica searches schemas to T1, U1, and V1: => SET SEARCH_PATH TO T1, U1, V1; This command returns the search path to the default of '"$user", public': => SET SEARCH_PATH = default; HP Vertica Analytic Database (7.0.x) Page 1250 of 1539 SQL Reference Manual SQL Statements SET SESSION AUTOCOMMIT Sets whether statements automatically commit their transactions on completion. This statement is primarily used by the client drivers to enable and disable autocommit, you should never have to directly call it. Syntax SET SESSION AUTOCOMMIT TO { ON | OFF } Parameters ON Enable autocommit. Statements automatically commit their transactions when they complete. This is the default setting for connections made using the HP Vertica client libraries. OFF Disable autocommit. Transactions are not automatically committed. This is the default for interactive sessions (connections made through vsql). Permissions No special permissions required. See Also l SET SESSION CHARACTERISTICS Sets the transaction characteristics for the isolation level and access mode (read/write or readonly). Setting the transaction mode affects subsequent transactions of a user session. Syntax SET SESSION CHARACTERISTICS AS TRANSACTION transaction_mode [, ...]where transaction_mode is o ne of: ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } READ { ONLY | WRITE } Parameters A transaction retains its isolation level until it completes, even if the session's transaction isolation level changes mid-transaction. HP Vertica internal processes (such as the Tuple Mover and HP Vertica Analytic Database (7.0.x) Page 1251 of 1539 SQL Reference Manual SQL Statements refresh operations) and DDL operations are always run at SERIALIZABLE isolation level to ensure consistency. Isolation level, described in the following table, determines what data the transaction can access when other transactions are running concurrently. The isolation level cannot be changed after the first query (SELECT) or DML statement (INSERT, DELETE, UPDATE) if a transaction has run. SERIALIZABLE Sets the strictest level of SQL transaction isolation. This level emulates transactions serially, rather than concurrently. It holds locks and blocks write operations until the transaction completes. Not recommended for normal query operations. REPEATABLE READ Automatically converted to SERIALIZABLE by HP Vertica. READ COMMITTED (Default) Allows concurrent transactions. Use READ COMMITTED isolation or Snapshot isolation for normal query operations, but be aware that there is a subtle difference between them. (See section below this table.) READ UNCOMMITTED Automatically converted to READ COMMITTED by HP Vertica. READ {WRITE | ONLY} Determines whether the transaction is read/write or read-only. Read/write is the default. Setting the transaction session mode to read-only disallows the following SQL commands, but does not prevent all disk write operations: l INSERT, UPDATE, DELETE, and COPY if the table they would write to is not a temporary table l All CREATE, ALTER, and DROP commands l GRANT, REVOKE, and EXPLAIN if the command it would run is among those listed. Permissions No special permissions required. Understanding READ COMMITTED and Snapshot Isolation By itself, AT EPOCH LATEST produces purely historical query behavior. However, with READ COMMITTED, SELECT queries return the same result set as AT EPOCH LATEST, plus any changes made by the current transaction. This is standard ANSI SQL semantics for ACID transactions. Any select query within a transaction sees the transaction's own changes regardless of isolation level. HP Vertica Analytic Database (7.0.x) Page 1252 of 1539 SQL Reference Manual SQL Statements Using SERIALIZABLE Transaction Isolation Setting the transaction isolation level to SERIALIZABLE does not apply to temporary tables. Temporary tables are isolated by their transaction scope. Applications using SERIALIZABLE must be prepared to retry transactions due to serialization failures. Setting READ ONLY Transaction Mode This example sets a read-only transaction level: => SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED READ ONLY; SET SET SESSION MEMORYCAP Specifies a limit on the amount of memory that any request issued by the session can consume. Syntax SET SESSION MEMORYCAP 'memory-limit' | = default Parameters memory-limit | = default The maximum amount of memory the session can use. To set a value, supply number followed by a unit. Units can be one of the following: l % percentage of total memory available to the Resource Manager. (In this case, size must be 0-100). l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes If you use the value = default the session's MEMORYCAP is set to the user's MEMORYCAP value. HP Vertica Analytic Database (7.0.x) Page 1253 of 1539 SQL Reference Manual SQL Statements Permissions l This command requires superuser privileges if the MEMORYCAP is being increased over the user's MEMORYCAP limit (see CREATE USER for details). l Non-superusers can change this value to anything below or equal to their MEMORYCAP limit. Notes The MEMORYCAP limit is per user session, not an overall cap on the user's memory usage. A user could spawn multiple sessions, each of which could use up to the limit set by the MEMORYCAP. Examples The following command sets a memorycap of 4 gigabytes on the session: => SET SESSION MEMORYCAP '4G'; To return the memorycap to the previous setting: => SET SESSION MEMORYCAP NONE; => SHOW MEMORYCAP; name | setting -----------+----------memorycap | UNLIMITED (1 row) See Also l ALTER RESOURCE POOL l CREATE RESOURCE POOL l CREATE USER l DROP RESOURCE POOL SET SESSION RESOURCE_POOL l l SET SESSION RESOURCE_POOL Associates the user session with the specified resource pool. HP Vertica Analytic Database (7.0.x) Page 1254 of 1539 SQL Reference Manual SQL Statements Syntax SET SESSION RESOURCE_POOL = { pool-name | default } Parameters pool-name | default Specifies the name of the resource pool to be associated with session. If you use the value default, then the session's resource pool is set to the default resource pool for the user. Permissions l This command requires non-superusers to have USAGE privileges for the resource pool. l Superusers can assign their session to any resource pool they want. l To set the resource pool session, the user needs USAGE privilege on the resource pool. Notes The resource pool must exist. See Also l ALTER RESOURCE POOL l CREATE RESOURCE POOL l CREATE USER l DROP RESOURCE POOL l GRANT (Resource Pool) SET SESSION MEMORYCAP l l SET SESSION RUNTIMECAP Sets the maximum amount of time a session's query can run. Syntax SET SESSION RUNTIMECAP [ 'duration' | NONE | = default ] HP Vertica Analytic Database (7.0.x) Page 1255 of 1539 SQL Reference Manual SQL Statements Parameters 'duration' | NONE | DEFAULT One of three values: l An interval such as '1 minute' or '100 seconds' (see Interval Values for a full explanation) setting the maximum amount of time this session's queries should be allowed to run. l NONE which eliminates any limit on the amount of time the session's queries can run (the default value). l = default which sets the session's RUNTIMECAP to the user's RUNTIMECAP value. You must include the equals (=) sign before the default keyword. Notes l The largest allowable RUNTIMECAP value is 1 year (365 days). l If RUNTIMECAP is also set for the user or the resource pool, HP Vertica uses the shortest limit. l This command requires superuser privileges if the RUNTIMECAP is being increased over the user's RUNTIMECAP limit. l Normal users can change the RUNTIMECAP of their own sessions to any value below their own RUNTIMECAP. They cannot increase the RUNTIMECAP beyond any limit set for them by the superuser. l The timeout is not precise, so a query may run a little longer than the value set in RUNTIMECAP. l Queries that violate the RUNTIMECAP are terminated with the error message Execution time exceeded run time cap of . l SHOW RUNTIMECAP (below) shows only the session RUNTIMECAP; it does not show the user or resource pool RUNTIMECAP. Examples The following command sets the session's RUNTIMECAP to 10 minutes: => SET SESSION RUNTIMECAP '10 minutes'; To return the RUNTIMECAP to the user's default setting: => SET SESSION RUNTIMECAP =DEFAULT; HP Vertica Analytic Database (7.0.x) Page 1256 of 1539 SQL Reference Manual SQL Statements SET => SHOW RUNTIMECAP; name | setting ------------+----------runtimecap | UNLIMITED (1 row) See Also CREATE USER l ALTER USER l l SET SESSION TEMPSPACECAP Sets the maximum amount of temporary file storage space that any request issued by the session can consume. Syntax SET SESSION TEMPSPACECAP 'space-limit' | = default | NONE Parameters 'space-limit' The maximum amount of temporary file space the session can use. To set a limit, use a numeric value followed by a unit (for example: '10G'). The unit can be one of the following: l % percentage of total temporary storage space available. (In this case, the numeric value must be 0-100). l K—Kilobytes l M—Megabytes l G—Gigabytes l T—Terabytes Setting this value to = default sets the session's TEMPSPACECAP to the user's TEMPSPACECAP value. Setting this value to NONE results in the session having unlimited temporary storage space. This is the default value. HP Vertica Analytic Database (7.0.x) Page 1257 of 1539 SQL Reference Manual SQL Statements Permissions l This command requires superuser privileges to increase the TEMPSPACECAP over the user's TEMPSPACECAP limit. l Regular users can change the TEMPSPACECAP associated with their own sessions to any value less than or equal to their own TEMPSPACECAP. They cannot increase its value beyond their own TEMPSPACECAP value. Notes l This limit is per session, not per user. A user could open multiple sessions, each of which could use up to the TEMPSPACECAP. l Any execution plan that exceeds its TEMPSPACECAP usage results in the error: ERROR: Exceeded temp space cap. Examples The following command sets a TEMPSPACECAP of 20gigabytes on the session: => SET SESSION TEMPSPACECAP '20G'; SET => SHOW TEMPSPACECAP; name | setting --------------+---------tempspacecap | 20971520 (1 row) Note: SHOW displays the TEMPSPACECAP in kilobytes. To return the memorycap to the previous setting: => SET SESSION TEMPSPACECAP NONE; SET => SHOW TEMPSPACECAP; name | setting --------------+----------tempspacecap | UNLIMITED (1 row) HP Vertica Analytic Database (7.0.x) Page 1258 of 1539 SQL Reference Manual SQL Statements See Also ALTER USER l CREATE USER l l SET STANDARD_CONFORMING_STRINGS Treats backslashes as escape characters for the current session. Syntax SET STANDARD_CONFORMING_STRINGS TO { ON | OFF } Parameters ON Makes ordinary string literals ('...') treat back slashes (\) literally. This means that back slashes are treated as string literals, not escape characters. (This is the default.) OFF Treats back slashes as escape characters. Permissions No special permissions required. Notes l This statement works under vsql only. l When standard conforming strings are on, HP Vertica supports SQL:2008 string literals within Unicode escapes. l Standard conforming strings must be ON to use Unicode-style string literals (U&'\nnnn'). Tip: To set conforming strings across all sessions (permanently), use theStandardConformingStrings as described in Internationalization Parameters in the Administrator's Guide. Examples The following example shows how to turn off conforming strings for the session. HP Vertica Analytic Database (7.0.x) Page 1259 of 1539 SQL Reference Manual SQL Statements => SET STANDARD_CONFORMING_STRINGS TO OFF; The following command lets you verify the settings: => SHOW STANDARD_CONFORMING_STRINGS; name | setting -----------------------------+--------standard_conforming_strings | off (1 row) The following example shows how to turn on conforming strings for the session. => SET STANDARD_CONFORMING_STRINGS TO ON; See Also l SET ESCAPE_STRING_WARNING SET TIME ZONE Changes the TIME ZONE run-time parameter for the current session. Syntax SET TIME ZONE TO { value | 'value' } Parameters value Is one of the following: l One of the time zone names specified in the tz database, as described in Sources for Time Zone and Daylight Saving Time Data. Time Zone Names for Setting TIME ZONE listed in the next section are for convenience only and could be out of date. l A signed integer representing an offset from UTC in hours l An interval value Permissions No special permissions required. HP Vertica Analytic Database (7.0.x) Page 1260 of 1539 SQL Reference Manual SQL Statements Notes l TIME ZONE is a synonym for TIMEZONE. Both are allowed in HP Vertica syntax. l The built-in constants LOCAL and DEFAULT, which set the time zone to the one specified in the TZ environment variable or, if TZ is undefined, from the operating system time zone. See TZ Environment Variable and Using Time Zones with HP Vertica in the Installation Guide. l When using a Country/City name, do not omit the country or the city. For example: => SET TIME ZONE TO 'Africa/Cairo'; -- valid => SET TIME ZONE TO 'Cairo'; -- invalid l Include the required keyword TO. l Positive integer values represent an offset east from UTC. l The SHOW command displays the run-time parameters. l If you set the timezone using POSIX format, the timezone abbreviation you use overrides the default timezone abbreviation. If the DATESTYLE is set to POSTGRES, the timezone abbreviation you use is also used when converting a timestamp to a string. Examples => => => => => SET SET SET SET SET TIME TIME TIME TIME TIME ZONE ZONE ZONE ZONE ZONE TO TO TO TO TO DEFAULT; 'PST8PDT'; -- Berkeley, California 'Europe/Rome'; -- Italy '-7'; -- UDT offset equivalent to PDT INTERVAL '-08:00 HOURS'; See Also l Using Time Zones With HP Vertica Time Zone Names for Setting TIME ZONE The following time zone names are recognized by HP Vertica as valid settings for the SQL time zone (the TIME ZONE run-time parameter). Note: The names listed here are for convenience only and could be out of date. Refer to the Sources for Time Zone and Daylight Saving Time Data page for precise information. HP Vertica Analytic Database (7.0.x) Page 1261 of 1539 SQL Reference Manual SQL Statements These names are not the same as the names shown in /opt/vertica/share/timezonesets, which are recognized by HP Vertica in date/time input values. The TIME ZONE names shown below imply a local daylight-savings time rule, where date/time input names represent a fixed offset from UTC. In many cases there are several equivalent names for the same zone. These are listed on the same line. The table is primarily sorted by the name of the principal city of the zone. In addition to the names listed in the table, HP Vertica accepts time zone names of the form STDoffset or STDoffsetDST, where STD is a zone abbreviation, offset is a numeric offset in hours west from UTC, and DST is an optional daylight-savings zone abbreviation, assumed to stand for one hour ahead of the given offset. For example, if EST5EDT were not already a recognized zone name, it would be accepted and would be functionally equivalent to USA East Coast time. When a daylight-savings zone name is present, it is assumed to be used according to USA time zone rules, so this feature is of limited use outside North America. Be wary that this provision can lead to silently accepting bogus input, since there is no check on the reasonableness of the zone abbreviations. For example, SET TIME ZONE TO FOOBANKO works, leaving the system effectively using a rather peculiar abbreviation for GMT. Time Zone Africa America Antarctica Asia Atlantic Australia CET EET Etc/GMT Europe Factory GMT GMT+0 GMT-0 GMT0 Greenwich Etc/GMT Etc/GMT+0 Etc/GMT-0 Etc/GMT0 Etc/Greenwich Indian MET Pacific HP Vertica Analytic Database (7.0.x) Page 1262 of 1539 SQL Reference Manual SQL Statements UCT Etc/UCT UTC Universal Zulu Etc/UTC Etc/Universal Etc/Zulu WET SHOW Displays run-time parameters for the current session. Syntax SHOW { name | ALL } Parameters name AUTOCOMMIT Displays whether statements automatically commit their transactions when they complete. AVAILABLE_ROLES Lists all roles available to the user. DATESTYLE Displays the current style of date values. See SET DATESTYLE. ENABLED_ROLES Displays the roles enabled for the current session. See SET ROLE. ESCAPE_STRING_WARNING Displays whether warnings are issued when backslash escapes are found in strings. See SET ESCAPE_ STRING_WARNING. INTERVALSTYLE Displays whether units are output when printing intervals. See SET INTERVALSTYLE. LOCALE Displays the current locale. See SET LOCALE. MEMORYCAP Displays the maximum amount of memory that any request use. See SET MEMORYCAP. RESOURCE_POOL Displays the resource pool that the session is using. See SET RESOURCE POOL. RUNTIMECAP Displays the maximum amount of time that queries can run in the session. See SET RUNTIMECAP SEARCH_PATH Displays the order in which HP Vertica searches schemas. See SET SEARCH_PATH. HP Vertica Analytic Database (7.0.x) Page 1263 of 1539 SQL Reference Manual SQL Statements SESSION_CHARACTERISTICS Displays the transaction characteristics. See SET SESSION CHARACTERISTICS. STANDARD_CONFORMING_STRINGS Displays whether backslash escapes are enabled for the session. See SET STANDARD_CONFORMING_ STRINGS. TEMPSPACECAP Displays the maximum amount of temporary file space that queries can use in the session. See SET TEMPSPACECAP. TIMEZONE Displays the timezone set in the current session. See SET TIMEZONE. TRANSACTION_ISOLATION Displays the current transaction isolation setting, as described in SET SESSION CHARACTERISTICS. TRANSACTION_READ_ONLY Displays the current setting, as described in SET SESSION CHARACTERISTICS. ALL Shows all run-time parameters. Permissions No special permissions required. How to Display All Current Run-Time Parameter Settings The following command returns all the run-time parameter settings: => SHOW ALL; name | setting -----------------------------+--------------------------------------------------locale | en_US@collation=binary (LEN_KBINARY) autocommit | off standard_conforming_strings | on escape_string_warning | on datestyle | ISO, MDY intervalstyle | plain timezone | US/Eastern search_path | "$user", public, v_catalog, v_monitor, v_internal transaction_isolation | READ COMMITTED transaction_read_only | false resource_pool | general memorycap | UNLIMITED tempspacecap | UNLIMITED runtimecap | UNLIMITED enabled roles | available roles | applogs, appadmin HP Vertica Analytic Database (7.0.x) Page 1264 of 1539 SQL Reference Manual SQL Statements (15 rows) Displaying Current Search Path Settings The following command returns the search path settings: => SHOW SEARCH_PATH; name | setting -------------+--------------------------------------------------search_path | "$user", public, v_catalog, v_monitor, v_internal (1 row) Displaying the Transaction Isolation Level The following command shows the session transaction isolation level: => SHOW TRANSACTION ISOLATION LEVEL; name | setting -----------------------+---------------transaction_isolation | READ COMMITTED (1 row) The next command returns the setting for SESSION CHARACTERISTICS AS TRANSACTION. False indicates that the default read/write is the current setting: => SHOW transaction_read_only; name | setting -----------------------+--------transaction_read_only | false (1 row) To change to read only, you'd need to enter: => SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY; Now the same SHOW command returns true: => SHOW transaction_read_only; name | setting -----------------------+--------transaction_read_only | true (1 row) START TRANSACTION Starts a transaction block. HP Vertica Analytic Database (7.0.x) Page 1265 of 1539 SQL Reference Manual SQL Statements Syntax START TRANSACTION [ isolation_level ] where isolation_level is one of: ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }READ { O NLY | WRITE } Parameters Isolation level, described in the following table, determines what data the transaction can access when other transactions are running concurrently. The isolation level cannot be changed after the first query (SELECT) or DML statement (INSERT, DELETE, UPDATE) has run. A transaction retains its isolation level until it completes, even if the session's transaction isolation level changes midtransaction. HP Vertica internal processes (such as the Tuple Mover and refresh operations) and DDL operations are always run at SERIALIZABLE isolation level to ensure consistency. WORK | TRANSACTION Have no effect; they are optional keywords for readability. HP Vertica Analytic Database (7.0.x) Page 1266 of 1539 SQL Reference Manual SQL Statements ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } l SERIALIZABLE—Sets the strictest level of SQL transaction isolation. This level emulates transactions serially, rather than concurrently. It holds locks and blocks write operations until the transaction completes. Not recommended for normal query operations. l REPEATABLE READ—Automatically converted to SERIALIZABLE by HP Vertica. l READ COMMITTED (Default)—Allows concurrent transactions. Use READ COMMITTED isolation for normal query operations, but be aware that there is a subtle difference between them. (See section that follows this table.) l READ UNCOMMITTED—Automatically converted to READ COMMITTED by HP Vertica. HP Vertica Analytic Database (7.0.x) Page 1267 of 1539 SQL Reference Manual SQL Statements R D E e A tD e r{ W m R i I n T e E s | w O h N L e tY } h e r t h e t r a n s a c t i o n i s r e a d / w r i HP Vertica Analytic Database (7.0.x) Page 1268 of 1539 SQL Reference Manual SQL Statements Permissions Setting the transaction session mode to read-only disallows the following SQL commands, but does not prevent all disk write operations: l INSERT, UPDATE, DELETE, and COPY if the table they would write No special permissions required. to is not a temporary table Notes l All CREATE, ALTER, and DROP commands l function GRANT,asREVOKE, and EXPLAIN if the command it would run is BEGIN performs the same START TRANSACTION. among those listed. See Also l Transactions l Creating and Rolling Back Transactions l COMMIT l END l ROLLBACK TRUNCATE TABLE Removes all storage associated with a table, while preserving the table definitions. TRUNCATE TABLE auto-commits the current transaction after statement execution and cannot be rolled back. Syntax TRUNCATE TABLE [[db-name.]schema.]table Parameters [[db-name.]schema.] [Optional] Specifies the database name and optional schema name. Using a database name identifies objects that are not unique within the current search path (see Setting Search Paths). You must be connected to the database you specify, and you cannot change objects in other databases. Specifying different database objects lets you qualify database objects as explicitly as required. For example, you can use a database and a schema name (mydb.myschema). table Specifies the name of a base table or temporary table. Cannot truncate an external table. HP Vertica Analytic Database (7.0.x) Page 1269 of 1539 SQL Reference Manual SQL Statements Permissions Superuser or table owner. A schema owner can drop a table but cannot truncate a table. Notes l To truncate an ON COMMIT DELETE ROWS temporary table without ending the transaction, use DELETE FROM temp_table syntax. Note: The effect of DELETE FROM depends on the table type. If the table is specified as ON COMMIT DELETE ROWS, then DELETE FROM works like TRUNCATE TABLE; otherwise it behaves like a normal delete in that it does not truncate the table. l After truncate operations complete, the data recovers from that current epoch onward. Because TRUNCATE TABLE removes table history, AT EPOCH queries return nothing. TRUNCATE TABLE behaves the same when you have data in WOS, ROS, or both, as well as for unsegmented/segmented projections. If the operation cannot obtain an O Lock on the table(s), HP Vertica attempts to close any internal Tuple Mover (TM) sessions running on the same table(s) so that the operation can proceed. Explicit TM operations that are running in user sessions are not closed. If an explicit TM operation is running on the table, then the operation cannot proceed until the explicit TM operation completes. Examples For examples about how to use TRUNCATE, see Dropping and Truncating Tables in the Administrator's Guide. See Also l DELETE l DROP TABLE l LOCKS l Transactions l Best Practices for DELETE and UPDATE UPDATE Replaces the values of the specified columns in all rows for which a specific condition is true. All other columns and rows in the table are unchanged. By default, UPDATE uses the WOS and if the HP Vertica Analytic Database (7.0.x) Page 1270 of 1539 SQL Reference Manual SQL Statements WOS fills up, overflows to the ROS. Syntax UPDATE [ /*+ direct */ ] [ /*+ label(label-name)*/ ] ... [[db-name.]schema.]Table-Reference [AS] alias ... SET column = ... { expression | DEFAULT } [ , ... ] ... [ FROM from-list ] ... [ WHERE Clause ] Parameters /*+ direct */ Writes the data directly to disk (ROS) bypassing memory (WOS). HP Vertica accepts optional spaces before and after the plus (+) sign and the direct hint. Space characters between the opening /* or the closing */ are not permitted. The following directives are all acceptable: /*+direct*/ /* + direct*/ /*+ direct*/ /*+direct */ Note: If you update using the direct hint, you still need to issue a COMMIT or ROLLBACK command to finish the transaction. /*+ label(label-n ame)*/ Passes a user-defined label to a query as a hint, letting you quickly identify labeled queries for profiling and debugging. See Query Labeling in the Administrator's Guide. [[db-name.]schem a.] [Optional] Specifies the schema name. Using a schema identifies objects that are not unique within the current search path (see Setting Schema Search Paths). You can optionally precede a schema with a database name, but you must be connected to the database you specify. You cannot make changes to objects in other databases. The ability to specify different database objects (from database and schemas to tables and columns) lets you qualify database objects as explicitly as required. For example, use a table and column (mytable.column1), a schema, table, and column (myschema.mytable.column1), and, as full qualification, a database, schema, table, and column (mydb.myschema.mytable.column1). HP Vertica Analytic Database (7.0.x) Page 1271 of 1539 SQL Reference Manual SQL Statements table-reference table-primary or joined-table: table-pri mary Specifies an optionally qualified table name with optional table aliases, colum n aliases, and outer joins. joined-ta ble Specifies an outer join. You cannot update a projection. alias Specifies a temporary name to be used for references to the table. column Specifies the name of a non-key column in the table. expression Specifies a value to assign to the column. The expression can use the current values of this and other columns in the table. For example: UPDATE T1 SET C1 = C1+1; from-list 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 command. Note that the target table must not appear in the from-list. Permissions Table owner or user with GRANT OPTION is grantor. l UPDATE privilege on table l USAGE privilege on schema that contains the table l SELECT privilege on the table when executing an UPDATE statement that references table column values in a WHERE or SET clause Notes l Subqueries and joins are permitted in UPDATE statements, which is useful for updating values in a table based on values that are stored in other tables. UPDATE changes the values of the specified columns in all rows that satisfy the condition. Only the columns to be modified need to be specified in the SET clause. Columns that are not explicitly modified retain their previous values. On successful completion, an UPDATE operation returns a count, which represents the number of rows updated. A count of 0 is not an error; it means that no rows matched the condition. See Subqueries in UPDATE and DELETE Statements in the Programmer's Guide. l The table you specify in the UPDATE list cannot also appear in the FROM list (no self joins); for example, the following UPDATE statement is not allowed: HP Vertica Analytic Database (7.0.x) Page 1272 of 1539 SQL Reference Manual SQL Statements => BEGIN; => UPDATE result_table SET address='new' || r2.address FROM result_table r2 WHERE r2.cust_id = result_table.cust_id + 10; ERROR: Self joins in UPDATE statements are not allowed DETAIL: Target relation result_table also appears in the FROM list l If the joins specified in the WHERE predicate produce more than one copy of the row in the table to be updated, the new value of the row in the table is chosen arbitrarily. l UPDATE inserts new records into the WOS and marks the old records for deletion. l You cannot UPDATE columns that have primary key or foreign key referential integrity constraints. l To use the DELETE or UPDATE commands with a WHERE Clause, you must have both SELECT and DELETE privileges on the table. Examples In the FACT table, modify the PRICE column value for all rows where the COST column value is greater than 100: => UPDATE FACT SET PRICE = PRICE - COST * 80 WHERE COST > 100; In the Retail.CUSTOMER table, set the STATE column to 'NH' when the CID column value is greater than 100: => UPDATE Retail.CUSTOMER SET STATE = 'NH' WHERE CID > 100; To use table aliases in UPDATE queries, consider the following two tables: => SELECT * FROM Result_Table; cust_id | address ---------+-------------------20 | Lincoln Street 30 | Beach Avenue 30 | Booth Hill Road 40 | Mt. Vernon Street 50 | Hillside Avenue (5 rows) => SELECT * FROM New_Addresses; new_cust_id | new_address -------------+--------------20 | Infinite Loop 30 | Loop Infinite 60 | New Addresses (3 rows) HP Vertica Analytic Database (7.0.x) Page 1273 of 1539 SQL Reference Manual SQL Statements The following query and subquery use table aliases to update the address column in Result_Table (alias r) with the new address from the corresponding column in the New_Addresses table (alias n): => UPDATE Result_Table r SET address=n.new_address FROM New_Addresses n WHERE r.cust_id = n.new_cust_id; The Result_Table table reflects the address field updates made for customer IDs 20 and 30: => SELECT * FROM Result_Table ORDER BY cust_id; cust_id | address ---------+-----------------20 | Infinite Loop 30 | Loop Infinite 30 | Loop Infinite 40 | Mt. Vernon Street 50 | Hillside Avenue (5 rows) For more information about nesting subqueries within an UPDATE statement, see Subqueries in UPDATE and DELETE in the Programmer's Guide. HP Vertica Analytic Database (7.0.x) Page 1274 of 1539 SQL Reference Manual HP Vertica System Tables HP Vertica System Tables HP Vertica provides system tables that let you monitor your database. Query these tables the same way you perform query operations on base or temporary tables—by using SELECT statements. For more information, see the following sections in the Administrator's Guide: l Using System Tables l Monitoring Vertica HP Vertica Analytic Database (7.0.x) Page 1275 of 1539 SQL Reference Manual HP Vertica System Tables V_CATALOG Schema The system tables in this section reside in the v_catalog schema. These tables provide information (metadata) about the objects in a database; for example, tables, constraints, users, projections, and so on. ALL_TABLES Provides summary information about the tables in HP Vertica. Column Name Data Type Description SCHEMA_NAME VARCHAR The name of the schema that contains the table. TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the table. TABLE_NAME VARCHAR The table name. TABLE_TYPE VARCHAR The type of table, which can be one of the following: REMARKS VARCHAR l TABLE l SYSTEM TABLE l VIEW l GLOBAL TEMPORARY l LOCAL TEMPORARY A brief comment about the table. You define this field by using the COMMENT ON TABLE and COMMENT ON VIEW commands. Example onenode=> SELECT DISTINCT table_name, table_type FROM all_tables WHERE table_name ILIKE 't%'; table_name | table_type ------------------------+-------------types | SYSTEM TABLE trades | TABLE tuple_mover_operations | SYSTEM TABLE tables | SYSTEM TABLE tuning_recommendations | SYSTEM TABLE testid | TABLE table_constraints | SYSTEM TABLE transactions | SYSTEM TABLE HP Vertica Analytic Database (7.0.x) Page 1276 of 1539 SQL Reference Manual HP Vertica System Tables (8 rows) onenode=> SELECT table_name, table_type FROM all_tables WHERE table_name ILIKE 'my%'; table_name | table_type ------------+-----------mystocks | VIEW (1 row) => SELECT * FROM all_tables LIMIT 4; -[ RECORD 1 ]------------------------------------------schema_name | v_catalog table_id | 10206 table_name | all_tables table_type | SYSTEM TABLE remarks | A complete listing of all tables and views -[ RECORD 2 ]------------------------------------------schema_name | v_catalog table_id | 10000 table_name | columns table_type | SYSTEM TABLE remarks | Table column information -[ RECORD 3 ]------------------------------------------schema_name | v_catalog table_id | 10054 table_name | comments table_type | SYSTEM TABLE remarks | User comments on catalog objects -[ RECORD 4 ]------------------------------------------schema_name | v_catalog table_id | 10134 table_name | constraint_columns table_type | SYSTEM TABLE remarks | Table column constraint information CLUSTER_LAYOUT Shows the relative position of the actual arrangement of the nodes participating in the cluster and the fault groups that affect them. Ephemeral nodes are not shown in the cluster layout ring because they hold no resident data. Column Name Data Type Description CLUSTER_POSITION INTEGER Position of the node in the cluster ring, counting forward from 0. Note: An output value of 0 has no special meaning other than there are no nodes in position before the node assigned 0. NODE_ID INTEGER HP Vertica Analytic Database (7.0.x) A unique numeric ID assigned by the HP Vertica catalog that identifies the node. Page 1277 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR The name of the node in the cluster ring. Only permanent nodes participating in database activity appear in the cluster layout. Ephemeral nodes are not shown in the output. FAULT_GROUP_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the fault group. Note: This value matches the FAULT_GROUP.MEMBER_ID value, but only if this node is in a fault group; otherwise the value is NULL. FAULT_GROUP_NAME VARCHAR The name of the fault group for the node. FAULT_GROUP_TIER INTEGER The node's depth in the fault group tree hierarchy. For example is the node: l Is not in a fault group, output is null l Is in the top level fault group, output is 0 l Is in a fault group's child, output is 1 l Is a fault group's grandchild, output is 2 Example => SELECT cluster_position FROM cluster_layout; cluster_position -----------------0 1 2 3 4 5 6 7 (8 rows) See Also Large Cluster in the Administrator's Guide COLUMNS Provides table column information. HP Vertica Analytic Database (7.0.x) Page 1278 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the table. TABLE_SCHEMA VARCHAR The schema name for which information is listed in the database. TABLE_NAME VARCHAR The table name for which information is listed in the database. IS_SYSTEM_TABLE BOOLEAN Indicates if the table is a system table, where t is true and f is false. COLUMN_ID VARCHAR A unique VARCHAR ID, assigned by the HP Vertica catalog, that identifies a column in a table. COLUMN_NAME VARCHAR The column name for which information is listed in the database. DATA_TYPE VARCHAR The data type assigned to the column; for example VARCHAR(16), INT, FLOAT. DATA_TYPE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the data type. DATA_TYPE_LENGTH INTEGER The maximum allowable length of the data type. CHARACTER_MAXIMUM_LENGTH VARCHAR The maximum allowable length of the column. NUMERIC_PRECISION INTEGER The number of significant decimal digits. NUMERIC_SCALE INTEGER The number of fractional digits. DATETIME_PRECISION INTEGER For TIMESTAMP data type, returns the declared precision; returns NULL if no precision was declared. INTERVAL_PRECISION INTEGER The number of fractional digits retained in the seconds field. ORDINAL_POSITION INTEGER The position of the column respective to other columns in the table. IS_NULLABLE BOOLEAN Indicates whether the column can contain NULL values, where t is true and f is false. COLUMN_DEFAULT VARCHAR The default value of a column, such as empty or expression. IS_IDENTITY BOOLEAN True if the column is an identity column. See ColumnConstraint. HP Vertica Analytic Database (7.0.x) Page 1279 of 1539 SQL Reference Manual HP Vertica System Tables Example Retrieve table and column information from the COLUMNS table: => SELECT table_schema, table_name, column_name, data_type, is_nullable FROM columns WHERE table_schema = 'store' AND data_type = 'Date'; table_schema | table_name | column_name | data_type | is_nullable --------------+-------------------+------------------------+-----------+------------store | store_dimension | first_open_date | Date | f store | store_dimension | last_remodel_date | Date | f store | store_orders_fact | date_ordered | Date | f store | store_orders_fact | date_shipped | Date | f store | store_orders_fact | expected_delivery_date | Date | f store | store_orders_fact | date_delivered | Date | f 6 rows) NULL results indicate that those columns were not defined. For example, given the following table, the result for the DATETIME_PRECISION column is NULL because no precision was declared: => CREATE TABLE c (c TIMESTAMP); CREATE TABLE => SELECT table_name, column_name, datetime_precision FROM columns WHERE table_name = 'c'; table_name | column_name | datetime_precision ------------+-------------+-------------------c | c | (1 row) In this example, the DATETIME_PRECISION column returns 4 because the precision was declared as 4 in the CREATE TABLE statement: => DROP TABLE c; => CREATE TABLE c (c TIMESTAMP(4)); CREATE TABLE => SELECT table_name, column_name, datetime_precision FROM columns WHERE table_name = 'c'; table_name | column_name | datetime_precision ------------+-------------+-------------------c | c | 4 An identity column is a sequence available only for numeric column types. To identify what column in a table, if any, is an identity column, search the COLUMNS table to find the identity column in a table testid: => CREATE TABLE testid (c1 IDENTITY(1, 1, 1000), c2 INT); => \x Expanded display is on. => SELECT * FROM COLUMNS WHERE is_identity='t' AND table_name='testid'; -[ RECORD 1 ]------------+-------------------table_id | 45035996273719486 HP Vertica Analytic Database (7.0.x) Page 1280 of 1539 SQL Reference Manual HP Vertica System Tables table_schema table_name is_system_table column_id column_name data_type data_type_id data_type_length character_maximum_length numeric_precision numeric_scale datetime_precision interval_precision ordinal_position is_nullable column_default is_identity | | | | | | | | | | | | | | | | | public testid f 45035996273719486-1 c1 int 6 8 1 f t Use the SEQUENCES table to get detailed information about the sequence in testid: => SELECT * FROM sequences WHERE identity_table_name='testid'; -[ RECORD 1 ]-------+-------------------sequence_schema | public sequence_name | testid_c1_seq owner_name | dbadmin identity_table_name | testid session_cache_count | 1000 allow_cycle | f output_ordered | f increment_by | 1 minimum | 1 maximum | 9223372036854775807 current_value | 0 sequence_schema_id | 45035996273704976 sequence_id | 45035996273719488 owner_id | 45035996273704962 identity_table_id | 45035996273719486 For more information about sequences and identity columns, see Using Named Sequences. COMMENTS Returns information about comments associated with objects in the database. Column Name Data Type Description COMMENT_ID INTEGER The comment's internal ID number OBJECT_ID INTEGER The internal ID number of the object associated with the comment HP Vertica Analytic Database (7.0.x) Page 1281 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description OBJECT_TYPE VARCHAR The type of object associated with the comment. Possible values are: l COLUMN l CONSTRAINT l FUNCTION l LIBRARY l NODE l PROJECTION l SCHEMA l SEQUENCE l TABLE l VIEW OBJECT_SCHEMA VARCHAR The schema containing the object. OBJECT_NAME VARCHAR The name of the object associated with the comment. OWNER_ID VARCHAR The internal ID of the owner of the object. OWNER_NAME VARCHAR The object owner's name. CREATION_TIME TIMESTAMPTZ When the comment was created. LAST_MODIFIED_TIME TIMESTAMPTZ When the comment was last modified. COMMENT VARCHAR The text of the comments. CONSTRAINT_COLUMNS Records information about table column constraints. Column Name Data Type Description CONSTRAINT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the constraint. TABLE_SCHEMA VARCHAR Name of the schema that contains this table. HP Vertica Analytic Database (7.0.x) Page 1282 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the table. TABLE_NAME VARCHAR Name of the table in which the column resides. COLUMN_NAME VARCHAR Name of the column that is constrained. CONSTRAINT_NAME VARCHAR Constraint name for which information is listed. CONSTRAINT_TYPE CHAR Is one of: l c — check is reserved, but not supported l f — foreign l n — not null l p — primary l u — unique l d — determines REFERENCE_TABLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the referenced table REFERENCE_TABLE_SCHEMA VARCHAR Schema name for which information is listed. REFERENCE_TABLE_NAME VARCHAR References the TABLE_NAME column in the PRIMARY_KEY table. REFERENCE_COLUMN_NAME VARCHAR References the COLUMN_NAME column in the PRIMARY_KEY table. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. DATABASES Provides information about the databases in this HP Vertica installation. Column Name Data Type Description DATABASE_ID INTEGER The database's internal ID number DATABASE_NAME VARCHAR The database's name HP Vertica Analytic Database (7.0.x) Page 1283 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description OWNER_ID INTEGER The database owner's ID OWNER_NAME INTEGER The database owner's name START_TIME TIMESTAMPTZ The date and time the database last started COMPLIANCE_MESSAGE VARCHAR Message describing the current state of the database's license compliance. EXPORT_SUBNET VARCHAR The subnet (on the public network) used by the database for import/export. LOAD_BALANCE_POLICY VARCHAR The current native connection load balance policy, which controls whether client connection requests are redirected to other hosts in the database. See About Native Connection Load Balancing in the Administrator's Guide. DUAL DUAL is a single-column "dummy" table with one record whose value is X; for example: => SELECT * FROM DUAL; dummy ------X (1 row) You can now write the following types of queries: => SELECT 1 FROM dual; ?column? ---------1 (1 row) => SELECT current_timestamp, current_user FROM dual; ?column? | current_user -------------------------------+-------------2010-03-08 12:57:32.065841-05 | release (1 row) => CREATE TABLE t1(col1 VARCHAR(20), col2 VARCHAR(2)); => INSERT INTO T1(SELECT 'hello' AS col1, 1 AS col2 FROM dual);) => SELECT * FROM t1; col1 | col2 -------+-----hello | 1 (1 row Because DUAL is a system table, you cannot create projections for it. You also cannot use it in pre-join projections for table objects. For example, assuming the following table schema (CREATE HP Vertica Analytic Database (7.0.x) Page 1284 of 1539 SQL Reference Manual HP Vertica System Tables TABLE t1 (col1 varchar(20), col2 varchar(2));) both of the following statements are not permitted and will return errors: => CREATE PROJECTION t1_prejoin AS SELECT * FROM t1 JOIN dual ON t1.col1 = dual.dummy; ERROR: Virtual tables are not allowed in FROM clause of projection => CREATE PROJECTION dual_proj AS SELECT * FROM dual; ERROR: Virtual tables are not allowed in FROM clause of projection ELASTIC_CLUSTER Returns information about cluster elasticity, such as whether Elastic Cluster is running. Column Name Data Type Description SCALING_FACTOR INTEGER This value is only meaningful when you enable local segments. SCALING_FACTOR influences the number of local segments on each node. Initially—before a rebalance runs—there are scaling_factor number of local segments per node. A large SCALING_FACTOR is good for rebalancing a potentially wide range of cluster configurations quickly. However, too large a value could lead to ROS pushback, particularly in a database with a table with a large number of partitions. See SET_SCALING_FACTOR for more details. MAXIMUM_SKEW_PERCENT INTEGER This value is only meaningful when you enable local segments. MAXIMUM_SKEW_PERCENT is the maximum amount of skew a rebalance operation tolerates, which preferentially redistributes local segments; however, if after doing so the segment ranges of any two nodes differs by more than this amount, rebalance will separate and distribute storage to even the distribution. SEGMENT_LAYOUT VARCHAR Current, offset=0, segment layout. New segmented projections will be created with this layout, with segments rotated by the corresponding offset. Existing segmented projections will be rebalanced into an offset of this layout. LOCAL_SEGMENT_LAYOUT VARCHAR Similar to SEGMENT_LAYOUT but includes details that indicate the number of local segments, their relative size and node assignment. VERSION INTEGER Number that gets incremented each time the cluster topology changes (nodes added, marked ephemeral, marked permanent, etc). Useful for monitoring active and past rebalance operations. IS_ENABLED BOOLEAN True if Elastic Cluster is enabled, otherwise false. HP Vertica Analytic Database (7.0.x) Page 1285 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_LOCAL_SEGMENT_ENABLED BOOLEAN True if local segments are enabled, otherwise false. IS_REBALANCE_RUNNING BOOLEAN True if rebalance is currently running, otherwise false. Permissions Must be a superuser. Example => SELECT * FROM elastic_cluster; -[ RECORD 1 ]------------+------------------------------------------------scaling_factor | 4 maximum_skew_percent | 15 segment_layout | v_myvdb_node0004[33.3%] v_myvdb_node0005[33.3%] | v_myvdb_node0006[33.3%] local_segment_layout | v_myvdb_node0004[8.3%] v_myvdb_node0004[8.3%] | v_myvdb_node0004[8.3%] v_myvdb_node0004[8.3%] | v_myvdb_node0005[8.3%] v_myvdb_node0005[8.3%] | v_myvdb_node0005[8.3%] v_myvdb_node0005[8.3%] | v_myvdb_node0006[8.3%] v_myvdb_node0006[8.3%] | v_myvdb_node0006[8.3%] v_myvdb_node0006[8.3%] version | 1 is_enabled | t is_local_segment_enabled | f is_rebalance_running | f See Also l ENABLE_ELASTIC_CLUSTER l DISABLE_ELASTIC_CLUSTER l Elastic Cluster EPOCHS For all epochs, provides the date and time of the close and the corresponding epoch number of the closed epoch. This information lets you determine which time periods pertain to which epochs. Column Name Data Type EPOCH_CLOSE_TIME DATETIME The date and time of the close of the epoch. EPOCH_NUMBER INTEGER HP Vertica Analytic Database (7.0.x) Description The corresponding epoch number of the closed epoch. Page 1286 of 1539 SQL Reference Manual HP Vertica System Tables Example => SELECT * FROM epochs; epoch_close_time | epoch_number -------------------------------+-------------2012-11-14 09:26:10.696296-05 | 0 2012-11-14 10:04:55.668457-05 | 1 2012-11-14 10:08:05.963606-05 | 2 (3 rows) See Also l l Epoch Management Functions FAULT_GROUPS View the fault groups and their hierarchy in the cluster. Column Name Data Type Description MEMBER_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the fault group. MEMBER_TYPE VARCHAR The type of fault group. Values can be either NODE or FAULT GROUP. MEMBER_NAME VARCHAR Name associated with this fault group. Values will be the node name or the fault group name. PARENT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the parent fault group. The parent fault group can contain: PARENT_TYPE VARCHAR HP Vertica Analytic Database (7.0.x) l Nodes l Other fault groups l Nodes and other fault groups The type of parent fault group, where the default/root parent is the DATABASE object. Can be one of the following objects: l FAULT GROUP l DATABASE Page 1287 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PARENT_NAME VARCHAR The name of the fault group that contains nodes or other fault groups or both nodes and fault groups. IS_AUTOMATICALLY_GENERATED BOOLEAN If true, denotes whether Vertica Analytic Database created fault groups for you to manage the fault tolerance of control nodes in large cluster configurations. If false, denotes that you created fault groups manually. See Fault Groups for more information Example The following example shows the current hierarchy of the fault groups in the cluster: vmartdb=> SELECT member_type, member_name, parent_type, CASE WHEN parent_type = 'DATABASE' THEN '' ELSE parent_name END FROM fault_groups ORDER BY member_name; member_type | member_name | parent_type | parent_name -------------+-------------+-------------+------------NODE | node01 | FAULT GROUP | two NODE | node02 | FAULT GROUP | two NODE | node03 | FAULT GROUP | three FAULT GROUP | one | DATABASE | FAULT GROUP | three | DATABASE | FAULT GROUP | two | FAULT GROUP | one This example queries the ELASTIC_CLUSTER system table to view the distribution of the segment layout. vmartdb=> SELECT segment_layout from elastic_cluster; segment_layout ------------------------------------------------------------------------v_vmart_node0001[33.3%] v_vmart_node0003[33.3%] v_vmart_node0004[33.3%] (1 row) See Also High Availability With Fault Groups in the Concepts Guide Fault Groups in the Administrator's Guide FOREIGN_KEYS Provides foreign key information. HP Vertica Analytic Database (7.0.x) Page 1288 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CONSTRAINT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the constraint. CONSTRAINT_NAME VARCHAR The constraint name for which information is listed. COLUMN_NAME VARCHAR The name of the column that is constrained. ORDINAL_POSITION VARCHAR The position of the column within the key. The numbering of columns starts at 1. TABLE_NAME VARCHAR The table name for which information is listed. REFERENCE_TABLE_NAME VARCHAR References the TABLE_NAME column in the PRIMARY_KEY table. CONSTRAINT_TYPE VARCHAR The constraint type, f, for foreign key. REFERENCE_COLUMN_NAME VARCHAR References the COLUMN_NAME column in the PRIMARY_KEY table. TABLE_SCHEMA VARCHAR The schema name for which information is listed. REFERENCE_TABLE_SCHEMA VARCHAR References the TABLE_SCHEMA column in the PRIMARY_KEY table. Example mydb=> SELECT constraint_name, table_name, ordinal_position, reference_table_name FROM foreign_keys ORDER BY 3; constraint_name | table_name | ordinal_position | reference_table_name ---------------------------+-------------------+------------------+---------------------fk_store_sales_date | store_sales_fact | 1 | date_dimension fk_online_sales_saledate | online_sales_fact | 1 | date_dimension fk_store_orders_product | store_orders_fact | 1 | product_dimension fk_inventory_date | inventory_fact | 1 | date_dimension fk_inventory_product | inventory_fact | 2 | product_dimension fk_store_sales_product | store_sales_fact | 2 | product_dimension fk_online_sales_shipdate | online_sales_fact | 2 | date_dimension fk_store_orders_product | store_orders_fact | 2 | product_dimension fk_inventory_product | inventory_fact | 3 | product_dimension fk_store_sales_product | store_sales_fact | 3 | product_dimension fk_online_sales_product | online_sales_fact | 3 | product_dimension fk_store_orders_store | store_orders_fact | 3 | store_dimension fk_online_sales_product | online_sales_fact | 4 | product_dimension fk_inventory_warehouse | inventory_fact | 4 | warehouse_dimension fk_store_orders_vendor | store_orders_fact | 4 | vendor_dimension fk_store_sales_store | store_sales_fact | 4 | store_dimension HP Vertica Analytic Database (7.0.x) Page 1289 of 1539 SQL Reference Manual HP Vertica System Tables fk_store_orders_employee fk_store_sales_promotion fk_online_sales_customer fk_store_sales_customer fk_online_sales_cc fk_store_sales_employee fk_online_sales_op fk_online_sales_shipping fk_online_sales_warehouse fk_online_sales_promotion (26 rows) | | | | | | | | | | store_orders_fact store_sales_fact online_sales_fact store_sales_fact online_sales_fact store_sales_fact online_sales_fact online_sales_fact online_sales_fact online_sales_fact | | | | | | | | | | 5 5 5 6 6 7 7 8 9 10 | | | | | | | | | | employee_dimension promotion_dimension customer_dimension customer_dimension call_center_dimension employee_dimension online_page_dimension shipping_dimension warehouse_dimension promotion_dimension GRANTS Provides information about privileges granted on various objects, the granting user, and grantee user. The order of columns in the table corresponds to the order in which they appear in the GRANT command. The GRANTS table does not retain the role grantor. Column Name Data Type Description GRANT_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the grant. GRANTOR_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the user who performed the grant operation. GRANTOR VARCHAR The user granting the permission. PRIVILEGES_DESCRIPTION VARCHAR A readable description of the privileges being granted; for example INSERT, SELECT. An asterisk in PRIVILEGES_ DESCRIPTION output indicates a privilege WITH GRANT OPTION. OBJECT_SCHEMA VARCHAR The name of the schema that is being granted privileges. OBJECT_NAME VARCHAR The name of the object that is being granted privileges. Note that for schema privileges, the schemaname appears in the OBJECT_NAME column instead of the OBJECT_SCHEMA column. OBJECT_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the object granted. OBJECT_TYPE VARCHAR The object type on which the grant was applied; for example, ROLE, SCHEMA, DATABASE, RESOURCEPOOL. Output from this column is useful in cases where a schema, resource pool, or user share the same name. HP Vertica Analytic Database (7.0.x) Page 1290 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description GRANTEE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the user granted permissions. GRANTEE VARCHAR The user being granted permission. Notes The vsql commands \dp and \z both include the schema name in the output; for example: => \dp Access privileges for database "vmartdb" Grantee | Grantor | Privileges | Schema | Name ---------+---------+------------+--------+----------------| dbadmin | USAGE | | public | dbadmin | USAGE | | v_internal | dbadmin | USAGE | | v_catalog | dbadmin | USAGE | | v_monitor | dbadmin | USAGE | | v_internal | dbadmin | USAGE | | v_catalog | dbadmin | USAGE | | v_monitor | dbadmin | USAGE | | v_internal | dbadmin | USAGE | | designer_system (9 rows) The vsql command \dp *.tablename displays table names in all schemas. This command lets you distinguish grants for same-named tables in different schemas: => \dp *.events Access privileges for database "dbadmin" Grantee | Grantor | Privileges | Schema | Name ---------+---------+--------------------------------------------+---------+-------user2 | dbadmin | INSERT, SELECT, UPDATE, DELETE, REFERENCES | schema1 | events user1 | dbadmin | SELECT | schema1 | events user2 | dbadmin | INSERT, SELECT, UPDATE, DELETE, REFERENCES | schema2 | events user1 | dbadmin | INSERT, SELECT | schema2 | events (4 rows) The vsql command \dp schemaname.* displays all tables in the named schema: => \dp schema1.* Access privileges for database "dbadmin" Grantee | Grantor | Privileges | Schema | Name ---------+---------+--------------------------------------------+--------------+----------user2 | dbadmin | INSERT, SELECT, UPDATE, DELETE, REFERENCES | schema1 | events user1 | dbadmin | SELECT | schema1 | events (2 rows) HP Vertica Analytic Database (7.0.x) Page 1291 of 1539 SQL Reference Manual HP Vertica System Tables Examples This example shows CREATE and USAGE privileges granted to Bob in the fictitious apps database: => SELECT grantor, privileges_description, object_schema, object_name, grantee FROM grants; grantor | privileges_description | object_schema | object_name | grantee ---------+------------------------+---------------+-------------+--------dbadmin | USAGE | | general | Bob dbadmin | CREATE | | schema2 | Bob (2 rows) This next query looks for privileges granted to a particular set of grantees. The asterisk in privileges_description column for User1 means that user has WITH GRANT OPTION privileges. => SELECT grantor, privileges_description, object_schema, object_name, grantee FROM grants WHERE grantee ILIKE 'User%'; grantor | privileges_description | object_schema | object_name | grantee ---------+---------------------------+---------------+-------------+--------release | USAGE | | general | User1 release | USAGE | | general | User2 release | USAGE | | general | User3 release | USAGE | | s1 | User1 release | USAGE | | s1 | User2 release | USAGE | | s1 | User3 User1 | INSERT*, SELECT*, UPDATE* | s1 | t1 | User1 (7 rows) In the following example, online_sales is the schema that first gets privileges, and then inside that schema the anchor table gets SELECT privileges: => SELECT grantee, grantor, privileges_description, object_schema, object_name FROM grants WHERE grantee='u1' ORDER BY object_name; grantee | grantor | privileges_description | object_schema | object_name ---------+---------+------------------------+-------- ------+-----------------u1 | dbadmin | CREATE | | online_sales u1 | dbadmin | SELECT | online_sales | online_sales_fact The following statement shows all grants for user Bob: -> SELECT * FROM GRANTS WHERE grantee = 'Bob'; -[ RECORD 1 ]----------+-------------------grant_id | 45035996273749244 grantor_id | 45035996273704962 grantor | dbadmin privileges_description | USAGE object_schema | object_name | general HP Vertica Analytic Database (7.0.x) Page 1292 of 1539 SQL Reference Manual HP Vertica System Tables object_id | 45035996273718666 object_type | RESOURCEPOOL grantee_id | 45035996273749242 grantee | Bob -[ RECORD 2 ]----------+-------------------grant_id | 45035996273749598 grantor_id | 45035996273704962 grantor | dbadmin privileges_description | object_schema | object_name | dbadmin object_id | 45035996273704968 object_type | ROLE grantee_id | 45035996273749242 grantee | Bob -[ RECORD 3 ]----------+-------------------grant_id | 45035996273749716 grantor_id | 45035996273704962 grantor | dbadmin privileges_description | object_schema | object_name | dbadmin object_id | 45035996273704968 object_type | ROLE grantee_id | 45035996273749242 grantee | Bob -[ RECORD 4 ]----------+-------------------grant_id | 45035996273755986 grantor_id | 45035996273704962 grantor | dbadmin privileges_description | object_schema | object_name | pseudosuperuser object_id | 45035996273704970 object_type | ROLE grantee_id | 45035996273749242 grantee | Bob -[ RECORD 5 ]----------+-------------------grant_id | 45035996273756986 grantor_id | 45035996273704962 grantor | dbadmin privileges_description | CREATE, CREATE TEMP object_schema | object_name | mcdb object_id | 45035996273704974 object_type | DATABASE grantee_id | 45035996273749242 grantee | Bob -[ RECORD 5 ]----------+-------------------... HP Vertica Analytic Database (7.0.x) Page 1293 of 1539 SQL Reference Manual HP Vertica System Tables See Also l HAS_ROLE l ROLES l USERS l Managing Users and Privileges HCATALOG_COLUMNS Describes the columns of all tables available through the HCatalog Connector. Each row in this table corresponds to to a column in a table accessible through the HCatalog Connector. See About the HCatalog Connector in the Hadoop Integration Guide for more information. Column Name Data Type Description TABLE_SCHEMA VARCHAR (128) The name of the Vertica Analytic Database schema that contains the table containing this column HCATALOG_ SCHEMA VARCHAR (128) The name of the Hive schema or database that contains the table containing this column TABLE_NAME VARCHAR (128) The name of the table that contains the column IS_PARTITION_ COLUMN BOOLEAN Whether the table is partitioned on this column COLUMN_NAME VARCHAR (128) The name of the column HCATALOG_DATA_ TYPE VARCHAR (128) The Hive data type of this column DATA_TYPE VARCHAR (128) The Vertica Analytic Database data type of this column DATA_TYPE_ID INTEGER Numeric ID of the column's Vertica Analytic Database data type DATA_TYPE_ LENGTH INTEGER The number of bytes used to store this data type CHARACTER_ MAXIMUM_LENGTH INTEGER For string data types, the maximum number of characters it can hold NUMERIC_ PRECISION INTEGER For numeric types, the precision of the values in the column HP Vertica Analytic Database (7.0.x) Page 1294 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NUMERIC_SCALE INTEGER For numeric data types, the scale of the values in the column DATETIME_ PRECISION INTEGER For datetime data types, the precision of the values in the column INTERVAL_ PRECISION INTEGER For interval data types, the precision of the values in the column ORDINAL_ POSITION INTEGER The position of the column within the table Permissions No explicit permissions are required; however, users see only the records that correspond to schemata they have permissions to access. Notes l Querying this table results in one web service call to the WebHCat server for each table in each HCatalog schema. Depending on the number of tables available through the HCatalog Connector, querying this table takes a while. l If you need to perform multiple queries on this table in a short period of time, consider creating a copy of the table using a CREATE TABLE AS statement. The copy does not reflect any changes made to the schema of the Hive tables after it was created, but it is much faster to query. Example The following example demonstrates finding the column information for a specific table: => SELECT * FROM HCATALOG_COLUMNS WHERE table_name = 'hcatalogtypes' -> ORDER BY ordinal_position; -[ RECORD 1 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | intcol hcatalog_data_type | int data_type | int data_type_id | 6 data_type_length | 8 character_maximum_length | numeric_precision | numeric_scale | datetime_precision | HP Vertica Analytic Database (7.0.x) Page 1295 of 1539 SQL Reference Manual HP Vertica System Tables interval_precision | ordinal_position | 1 -[ RECORD 2 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | floatcol hcatalog_data_type | float data_type | float data_type_id | 7 data_type_length | 8 character_maximum_length | numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 2 -[ RECORD 3 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | doublecol hcatalog_data_type | double data_type | float data_type_id | 7 data_type_length | 8 character_maximum_length | numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 3 -[ RECORD 4 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | charcol hcatalog_data_type | string data_type | varchar(65000) data_type_id | 9 data_type_length | 65000 character_maximum_length | 65000 numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 4 -[ RECORD 5 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | varcharcol hcatalog_data_type | string data_type | varchar(65000) HP Vertica Analytic Database (7.0.x) Page 1296 of 1539 SQL Reference Manual HP Vertica System Tables data_type_id | 9 data_type_length | 65000 character_maximum_length | 65000 numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 5 -[ RECORD 6 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | boolcol hcatalog_data_type | boolean data_type | boolean data_type_id | 5 data_type_length | 1 character_maximum_length | numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 6 -[ RECORD 7 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | timestampcol hcatalog_data_type | string data_type | varchar(65000) data_type_id | 9 data_type_length | 65000 character_maximum_length | 65000 numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 7 -[ RECORD 8 ]------------+----------------table_schema | hcat hcatalog_schema | default table_name | hcatalogtypes is_partition_column | f column_name | varbincol hcatalog_data_type | binary data_type | varbinary(65000) data_type_id | 17 data_type_length | 65000 character_maximum_length | 65000 numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 8 -[ RECORD 9 ]------------+----------------table_schema | hcat HP Vertica Analytic Database (7.0.x) Page 1297 of 1539 SQL Reference Manual HP Vertica System Tables hcatalog_schema table_name is_partition_column column_name hcatalog_data_type data_type data_type_id data_type_length character_maximum_length numeric_precision numeric_scale datetime_precision interval_precision ordinal_position | | | | | | | | | | | | | | default hcatalogtypes f bincol binary varbinary(65000) 17 65000 65000 9 See Also l HCATALOG_SCHEMATA l HCATALOG_TABLES l HCATALOG_TABLE_LIST HCATALOG_SCHEMATA Lists all of the schemata (plural of schema) defined using the HCatalog Connector. See Using the HCatalog Connector in the Hadoop Integration Guide. Column Name Data Type Description SCHEMA_ID INTEGER The Vertica Analytic Database ID number for the schema SCHEMA_NAME VARCHAR (128) The name of the schema defined in the Vertica Analytic Database catalog SCHEMA_ OWNER_ID INTEGER The ID number of the user who owns the Vertica Analytic Database schema SCHEMA_ OWNER VARCHAR (128) The username of the Vertica Analytic Database schema's owner CREATE_TIME TIMESTAMPTZ The date and time the schema as created HOSTNAME VARCHAR (128) The host name or IP address of the database server that holds the Hive metadata PORT INTEGER The port number on which the metastore database listens for connections HP Vertica Analytic Database (7.0.x) Page 1298 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description WEBSERVICE_ HOSTNAME VARCHAR (128) The host name or IP address of the WebHCat server for the Hive database WEBSERVICE_ PORT INTEGER The port number on which the WebHCat server listens for connections HCATALOG_ SCHEMA_NAME VARCHAR (128) The name of the schema or database in Hive to which the Vertica Analytic Database schema is mapped/ HCATALOG_ USER_NAME VARCHAR (128) The username the HCatalog Connector uses to authenticate itself to the Hive database. METASTORE_ DB_NAME VARCHAR (128) The name of the database containing the metadata about the Hive database. Permissions No explicit permissions are required; however, users see only the records that correspond to schemata they have permissions to access. Notes Unlike other HCatalog Connector-related system tables, this table does not make any calls to the WebHCat server. Therefore querying incurs very little overhead. Example => \x Expanded display is on. dbadmin=> SELECT * FROM HCATALOG_SCHEMATA; -[ RECORD 1 ]--------+----------------------------schema_id | 45035996273864536 schema_name | hcat schema_owner_id | 45035996273704962 schema_owner | dbadmin create_time | 2013-11-05 10:19:54.70965-05 hostname | hcathost port | 9083 webservice_hostname | hcathost webservice_port | 50111 hcatalog_schema_name | default hcatalog_user_name | hive metastore_db_name | hivemetastoredb HP Vertica Analytic Database (7.0.x) Page 1299 of 1539 SQL Reference Manual HP Vertica System Tables See Also l HCATALOG_COLUMNS l HCATALOG_TABLE_LIST l HCATALOG_TABLES HCATALOG_TABLES Detailed list of all tables made available through the HCatalog Connector. See Using the HCatalog Connector in the Hadoop Integration Guide. Column Name Data Type Description TABLE_ SCHEMA_ID INTEGER ID number of the schema TABLE_SCHEMA VARCHAR (128) The name of the Vertica Analytic Database schema through which the table is available HCATALOG_ SCHEMA VARCHAR (128) The name of the Hive schema or database that contains the table TABLE_NAME VARCHAR (128) The name of the table HCATALOG_ USER_NAME VARCHAR (128) The name of the HCatalog user whose credentials are used to access the table's data MIN_FILE_SIZE_ BYTES INTEGER The file size of the table's smallest data file TOTAL_ NUMBER_FILES INTEGER The number of files used to store this table's data in HDFS LOCATION VARCHAR (8192) The URI for the directory containing this table's data, normally an HDFS URI LAST_UPDATE_ TIME TIMESTAMPTZ The last time data in this table was updated OUTPUT_ FORMAT VARCHAR (128) LAST_ACCESS_ TIME TIMESTAMPTZ The last time data in this table was accessed MAX_FILE_SIZE_ BYTES INTEGER HP Vertica Analytic Database (7.0.x) The Hive SerDe class used to output data from this table The size of the largest data file for this table Page 1300 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_PARTITIONED BOOLEAN Whether this table is partitioned PARTITION_ EXPRESSION VARCHAR (128) The expression used to partition this table TABLE_OWNER VARCHAR (128) The Hive user that owns this table in the Hive database INPUT_FORMAT VARCHAR (128) The SerDe class used to read the data from this table TOTAL_FILE_ SIZE_BYTES INTEGER Total number of bytes used by all of this table's data files HCATALOG_ GROUP VARCHAR (128) The permission group assigned to this table PERMISSION VARCHAR (128) The Unix file permissions for this group, as shown by the ls -l command Permissions No explicit permissions are required; however, users see only the records that correspond to schemata they have permissions to access. Notes Querying this table results in Vertica Analytic Database making one REST function call to WebHCat for each table in all of the schemata available through the HCatalog Connector. This means that querying this table may take a long while, depending on the number tables and number of HCatalog schemata. Example The following example demonstrates querying HCATALOG_TABLES to view a single table's details: => \x Expanded display is on. => SELECT * FROM HCATALOG_TABLES WHERE table_name = 'msgjson'; -[ RECORD 1 ]---------+----------------------------------------------------------table_schema_id | 45035996273864536 table_schema | hcat hcatalog_schema | default table_name | msgjson hcatalog_user_name | hcatuser min_file_size_bytes | 13524 total_number_files | 10 HP Vertica Analytic Database (7.0.x) Page 1301 of 1539 SQL Reference Manual HP Vertica System Tables location last_update_time output_format last_access_time max_file_size_bytes is_partitioned partition_expression table_owner input_format total_file_size_bytes hcatalog_group permission | | | | | | | | | | | | hdfs://hive.example.com:8020/user/exampleuser/msgjson 2013-11-05 14:18:07.625-05 org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat 2013-11-11 13:21:33.741-05 45762 f hcatuser org.apache.hadoop.mapred.TextInputFormat 453534 supergroup rwxr-xr-x See Also l HCATALOG_SCHEMATA l HCATALOG_COLUMNS l HCATALOG_TABLE_LIST HCATALOG_TABLE_LIST A concise list of all tables contained in all Hive schemata and databases available through the HCatalog Connector. See Using the HCatalog Connector in the Hadoop Integration Guide. Column Name Data Type Description TABLE_SCHEMA_ ID INTEGER Internal ID number for the schema containing the table TABLE_SCHEMA VARCHAR (128) Name of the Vertica Analytic Database schema through which the table is available HCATALOG_ SCHEMA VARCHAR (128) Name of the Hive schema or database containing the table TABLE_NAME VARCHAR (128) The name of the table HCATALOG_ USER_NAME VARCHAR (128) Name of Hive user used to access the table Permissions No explicit permissions are required; however, users see only the records that correspond to schemata they have permissions to access. HP Vertica Analytic Database (7.0.x) Page 1302 of 1539 SQL Reference Manual HP Vertica System Tables Notes l Querying this table results in one call to WebHCat for each Hive schema defined using the HCatalog Connector. This means that the query usually takes longer than querying other system tables. l Querying this table is faster than querying HCATALOG_TABLES. Querying HCATALOG_ TABLE_LIST only makes one WebHCat call per HCatalog schema versus one call per table for HCATALOG_TABLES. Example The following example demonstrates defining a new HCatalog schema then querying HCATALOG_ TABLE_LIST. Note that one table defined in a different HCatalog schema also appears. The HCATALOGTABLE_LIST lists all of the tables available in any of the HCatalog schemata: => CREATE HCATALOG SCHEMA hcat WITH hostname='hcathost' -> HCATALOG_SCHEMA='default' HCATALOG_DB='default' HCATALOG_USER='hcatuser'; CREATE SCHEMA => \x Expanded display is on. => SELECT * FROM v_catalog.hcatalog_table_list; -[ RECORD 1 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | weblogs hcatalog_user_name | hcatuser -[ RECORD 2 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | tweets hcatalog_user_name | hcatuser -[ RECORD 3 ]------+-----------------table_schema_id | 45035996273748980 table_schema | hcat hcatalog_schema | default table_name | messages hcatalog_user_name | hcatuser -[ RECORD 4 ]------+-----------------table_schema_id | 45035996273864948 table_schema | hiveschema hcatalog_schema | default table_name | weblogs hcatalog_user_name | hcatuser HP Vertica Analytic Database (7.0.x) Page 1303 of 1539 SQL Reference Manual HP Vertica System Tables See Also l HCATALOG_COLUMNS l HCATALOG_SCHEMATA l HCATALOG_TABLES LARGE_CLUSTER_CONFIGURATION_STATUS Shows the current cluster nodes and control node (spread hosts) designations in the Catalog so you can see if they match. Column Name Data Type Description NODE_NAME VARCHAR The name of the node in the cluster. SPREAD_HOST_NAME VARCHAR The host name of the control node (the host that manages control message responsibilities) CONTROL_NODE_NAME VARCHAR The name of the control node See Also Large Cluster in the Administrator's Guide LICENSE_AUDITS Lists the results of HP Vertica's license automatic compliance audits. See How HP Vertica Calculates Database Size in the Administrator's Guide. Column Name Data Type Description DATABASE_SIZE_BYTES INTEGER The estimated raw data size of the database LICENSE_SIZE_BYTES INTEGER The licensed data allowance USAGE_PERCENT FLOAT Percentage of the licensed allowance used AUDIT_START_TIMESTAMP TIMESTAMPTZ When the audit started AUDIT_END_TIMESTAMP TIMESTAMPTZ When the audit finished CONFIDENCE_LEVEL_PERCENT FLOAT HP Vertica Analytic Database (7.0.x) The confidence level of the size estimate Page 1304 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ERROR_TOLERANCE_PERCENT FLOAT The error tolerance used for the size estimate USED_SAMPLING BOOLEAN Whether data was randomly sampled (if false, all of the data was analyzed) CONFIDENCE_INTERVAL_LOWER_BOUND_BYTES INTEGER The lower bound of the data size estimate within the confidence level CONFIDENCE_INTERVAL_UPPER_BOUND_BYTES INTEGER The upper bound of the data size estimate within the confidence level SAMPLE_COUNT INTEGER The number of data samples used to generate the estimate CELL_COUNT INTEGER The number of cells in the database LICENSES For all licenses, provides information information on license types, the dates for which licenses are valid, and the limits the licenses impose. Column Name Data Type Description LICENSE_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the license. NAME VARCHAR The license’s name. LICENSEE VARCHAR The entity to which the product is licensed. START_DATE VARCHAR The start date for which the license is valid. END_DATE VARCHAR The end date until which the license is valid (or "Perpetual" if the license has no expiration). SIZE VARCHAR The size limit for data on the license. IS_COMMUNITY_EDITION BOOLEAN Indicates whether the license is a Community Edition license, where t is true and f is false. NODE_RESTRICTION VARCHAR The node limit the license imposes. Example => \x HP Vertica Analytic Database (7.0.x) Page 1305 of 1539 SQL Reference Manual HP Vertica System Tables Expanded display is on. => SELECT * FROM licenses; -[ RECORD 1 ]--------+---------------------------------------license_id | 45035996273704986 name | vertica licensee | Vertica Community Edition start_date | 2011-11-22 end_date | Perpetual size | 1TB is_community_edition | t node_restriction | 3 -[ RECORD 2 ]--------+---------------------------------------license_id | 45035996274085644 name | com.vertica.flextable licensee | Vertica Community Edition, Flextable start_date | 2013-10-29 end_date | Perpetual size | 1TB is_community_edition | t node_restriction | MATERIALIZE_FLEXTABLE_COLUMNS_RESULTS Returns the results after you run the flex table function, MATERIALIZE_FLEXTABLE_COLUMNS. The system table includes the following information: Column Name Data Type Description TABLE_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the license. TABLE_SCHEMA VARCHAR The license’s name. TABLE_NAME VARCHAR The HP Verticaproduct toward which the license is applied. CREATION_TIME VARCHAR The start date for which the license is valid. KEY_NAME VARCHAR The end date until which the license is valid (or "Perpetual" if the license has no expiration). STATUS VARCHAR The function status, which can be one of these values: l ADDED l EXISTS l ERROR HP Vertica Analytic Database (7.0.x) Page 1306 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description MESSAGE BOOLEAN The message associated with the status in the previous column: l Added successfully l Column of same name already exists in table definition l Add operation failed --or-l No data type guess provided to add column Example ddbt=> SELECT table_name, creation_time, key_name, status, message FROM v_catalog.materialize_flextable_columns_results WHERE table_name = 'twitter_r'; table_name | creation_time | key_name | status | message ------------+-------------------------------+-------------------+--------+------------------------------------------------------twitter_r | 2013-11-20 17:00:27.945484-05 | contributors | ADDED | Added successfu lly twitter_r | 2013-11-20 17:00:27.94551-05 | entities.hashtags | ADDED | Added successfu lly twitter_r | 2013-11-20 17:00:27.945519-05 | entities.urls | ADDED | Added successfu lly twitter_r | 2013-11-20 17:00:27.945532-05 | created_at | EXISTS | Column of same name already exists in table definition (4 rows) NODES Lists details about the nodes in the database. Column Name Date Type Description NODE_NAME VARCHAR (128) The name of the node. NODE_ID INT A unique numeric ID, assigned by the HP Vertica catalog, which identifies the node. HP Vertica Analytic Database (7.0.x) Page 1307 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Date Type Description NODE_STATE VARCHAR (128) The node's current state (up, down, recovering, etc.). NODE_ADDRESS VARCHAR (80) The host address of the node. EXPORT_ADDRESS VARCHAR The IP address of the node (on the public network) used for import/export operations. CATALOG_PATH VARCHAR (8192) The absolute path to the catalog on the node. IS_EPHEMERAL BOOLEAN True if this node has been marked as ephemeral (in preparation of removing it from the cluster). Example dbadmin=> \x Expanded display is on. -[ RECORD 1 ]--+---------------------------------------------------node_name | v_mcdb_node0001 node_id | 45035996273704980 node_state | UP node_address | XX.XX.XXX.X2 export_address | XX.XX.XXX.X2 catalog_path | /home/dbadmin/mcdb/v_vmart_node0001_catalog/Catalog is_ephemeral | f -[ RECORD 2 ]--+---------------------------------------------------node_name | v_mcdb_node0002 node_id | 45035996273718764 node_state | UP node_address | XX.XX.XXX.X3 export_address | XX.XX.XXX.X3 catalog_path | /home/dbadmin/mcdb/v_vmart_node0002_catalog/Catalog is_ephemeral | f -[ RECORD 3 ]--+---------------------------------------------------node_name | v_mcdb_node0003 node_id | 45035996273718768 node_state | UP node_address | XX.XX.XXX.X4 export_address | XX.XX.XXX.X4 catalog_path | /home/dbadmin/mcdb/v_vmart_node0003_catalog/Catalog is_ephemeral | f ODBC_COLUMNS Provides table column information. The format is defined by the ODBC standard for the ODBC SQLColumns metadata. Details on the ODBC SQLColumns format are available in the ODBC HP Vertica Analytic Database (7.0.x) Page 1308 of 1539 SQL Reference Manual HP Vertica System Tables specification: http://msdn.microsoft.com/enus/library/windows/desktop/ms711683%28v=vs.85%29.aspx. Column Name Data Type Description SCHEMA_NAME VARCHAR The name of the schema in which the column resides. If the column does not reside in a schema, this field is empty. TABLE_NAME VARCHAR The name of the table in which the column resides. COLUMN_NAME VARCHAR The name of the column. DATA_TYPE INTEGER The data type of the column. This can be an ODBC SQL data type or a driver-specific SQL data type. This column corresponds to the ODBC_TYPE column in the TYPES table. DATA_TYPE_NAME VARCHAR The driver-specific data type name. COLUMN_SIZE INTEGER The ODBC-defined data size of the column. BUFFER_LENGTH INTEGER The transfer octet length of a column is the maximum number of bytes returned to the application when data is transferred to its default C data type. See http://msdn.microsoft.com/enus/library/windows/desktop/ms713979%28v=vs.85%29.aspx DECIMAL_DIGITS INTEGER The total number of significant digits to the right of the decimal point. This value has no meaning for non-decimal data types. NUM_PREC_RADIX INTEGER The radix HP Vertica reports decimal_digits and columns_size as. This value is always 10, because it refers to a number of decimal digits, rather than a number of bits. NULLABLE BOOLEAN Indicates whether the column can contain null values. Values are 0 or 1. REMARKS VARCHAR The textual remarks for the column. COLUMN_DEFAULT VARCHAR The default value of the column. SQL_TYPE_ID INTEGER The SQL data type of the column. SQL_DATETIME_SUB VARCHAR The subtype for a datetime data type. This value has no meaning for non-datetime data types. CHAR_OCTET_LENGTH INTEGER The maximum length of a string or binary data column. ORDINAL_POSITION INTEGER Indicates the position of the column in the table definition. IS_NULLABLE VARCHAR Values can be YES or NO, determined by the value of the NULLABLE column. IS_IDENTITY BOOLEAN Indicates whether the column is a sequence, for example, an auto increment column. HP Vertica Analytic Database (7.0.x) Page 1309 of 1539 SQL Reference Manual HP Vertica System Tables Example dbadmin=> SELEECT schema_name, table_name,data_type_name FROM odbc_columns LIMIT 2; schema_name | table_name | data_type_name -------------+---------------------------+---------------v_monitor | execution_engine_profiles | Boolean v_monitor | query_profiles | Boolean (2 rows) PASSWORDS Contains user passwords information. This table stores not only current passwords, but also past passwords if any profiles have PASSWORD_REUSE_TIME or PASSWORD_REUSE_MAX parameters set. See CREATE PROFILE for details. Column Name Data Type Description USER_ID INTEGER The ID of the user who owns the password. USER_NAME VARCHAR The name of the user who owns the password. PASSWORD VARCHAR The encrypted password. PASSWORD_CREATE_TIME DATETIME The date and time when the password was created. IS_CURRENT_PASSWORD BOOLEAN Denotes whether this is the user's current password. Noncurrent passwords are retained to enforce password reuse limitations. PROFILE_ID INTEGER The ID number of the profile to which the user is assigned. PROFILE_NAME VARCHAR The name of the profile to which the user is assigned. PASSWORD_REUSE_MAX VARCHAR The number password changes that must take place before an old password can be reused. PASSWORD_REUSE_TIME VARCHAR The amount of time that must pass before an old password can be reused. PRIMARY_KEYS Provides primary key information. Column Name Data Type Description CONSTRAINT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the constraint. HP Vertica Analytic Database (7.0.x) Page 1310 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CONSTRAINT_NAME VARCHAR The constraint name for which information is listed. COLUMN_NAME VARCHAR The column name for which information is listed. ORDINAL_POSITION VARCHAR The position of the column within the key. The numbering of columns starts at 1. TABLE_NAME VARCHAR The table name for which information is listed. CONSTRAINT_TYPE VARCHAR The constraint type, p, for primary key. TABLE_SCHEMA VARCHAR The schema name for which information is listed. Example Request specific columns from the PRIMARY_KEYS table: => SELECT constraint_name, table_name, ordinal_position, table_schema FROM primary_keys ORDER BY 3; constraint_name | table_name | ordinal_position | table_schema -----------------+-----------------------+------------------+-------------C_PRIMARY | customer_dimension | 1 | public C_PRIMARY | product_dimension | 1 | public C_PRIMARY | store_dimension | 1 | store C_PRIMARY | promotion_dimension | 1 | public C_PRIMARY | date_dimension | 1 | public C_PRIMARY | vendor_dimension | 1 | public C_PRIMARY | employee_dimension | 1 | public C_PRIMARY | shipping_dimension | 1 | public C_PRIMARY | warehouse_dimension | 1 | public C_PRIMARY | online_page_dimension | 1 | online_sales C_PRIMARY | call_center_dimension | 1 | online_sales C_PRIMARY | product_dimension | 2 | public (12 rows) PROFILE_PARAMETERS Defines what information is stored in profiles. Column Name Data Type Description PROFILE_ID INTEGER The ID of the profile to which this parameter belongs. PROFILE_NAME VARCHAR The name of the profile to which this parameter belongs. PARAMETER_TYPE VARCHAR The policy type of this parameter (password_complexity, password_security, etc.) PARAMETER_NAME VARCHAR The name of the parameter. PARAMETER_LIMIT VARCHAR The parameter's value. HP Vertica Analytic Database (7.0.x) Page 1311 of 1539 SQL Reference Manual HP Vertica System Tables PROFILES Provides information about password policies that you set using the CREATE PROFILE statement. Column Name Data Type Description PROFILE_ID INTEGER The unique identifier for the profile. PROFILE_NAME VARCHAR The profile's name. PASSWORD_LIFE_TIME VARCHAR The number of days before the user's password expires. After expiration, the user is forced to change passwords during login or warned that their password has expired if password_grace_ time is set to a value other than zero or unlimited. PASSWORD_GRACE_TIME VARCHAR The number of days users are allowed to log in after their passwords expire. During the grace time, users are warned about their expired passwords when they log in. After the grace period, the user is forced to change passwords if he or she hasn't already. PASSWORD_REUSE_MAX VARCHAR The number of password changes that must occur before the current password can be reused. PASSWORD_REUSE_TIME VARCHAR The number of days that must pass after setting a password before it can be used again. FAILED_LOGIN_ATTEMPTS VARCHAR The number of consecutive failed login attempts that triggers HP Vertica to lock the account. PASSWORD_LOCK_TIME VARCHAR The number of days an account is locked after being locked due to too many failed login attempts. PASSWORD_MAX_LENGTH VARCHAR The maximum number of characters allowed in a password. PASSWORD_MIN_LENGTH VARCHAR The minimum number of characters required in a password. PASSWORD_MIN_LETTERS VARCHAR The minimum number of letters (either uppercase or lowercase) required in a password. PASSWORD_MIN_LOWERCASE_LETTERS VARCHAR The minimum number of lowercase. PASSWORD_MIN_UPPERCASE_LETTERS VARCHAR The minimum number of uppercase letters required in a password. HP Vertica Analytic Database (7.0.x) Page 1312 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PASSWORD_MIN_DIGITS VARCHAR The minimum number of digits required in a password. PASSWORD_MIN_SYMBOLS VARCHAR The minimum of symbols (for example, !, #, $, etc.) required in a password. Notes Non-superusers querying this table see only the information for the profile to which they are assigned. See Also l CREATE PROFILE l ALTER PROFILE PROJECTION_CHECKPOINT_EPOCHS Records when each projection checkpoint epoch changes. Column Name Data Type Description NODE_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the node for which information is listed NODE_NAME VARCHAR Node name for which information is listed. PROJECTION_SCHEMA_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the specific schema that contains the projection. PROJECTION_SCHEMA VARCHAR Schema containing the projection. PROJECTION_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Projection name for which information is listed. IS_UP_TO_DATE BOOLEAN Indicates whether the projection is up to date, where t is true and f is false. Projections must be up to date for queries to use them. CHECKPOINT_EPOCH INTEGER Checkpoint epoch of the projection on the corresponding node. Data up to and including this epoch is in persistent storage. If the node were to fail, without moving more data out of the WOS, data after this epoch would need to be recovered. HP Vertica Analytic Database (7.0.x) Page 1313 of 1539 SQL Reference Manual HP Vertica System Tables Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Examples => SELECT epoch FROM t; epoch ------52 52 53 (3 rows)=> SELECT node_name, projection_schema, projection_name, is_up-to-date, checkpoin t_epoch FROM projection_checkpoint_epochs; node_name | projection_schema | projection_name | is_up_to_date | checkpoint_epoch -----------+-------------------+------------------+---------------+-----------------node01 | public | t_super | t | 51 node01 | public | p_super | t | 51 (2 rows) => SELECT DO_TM_TASK('moveout',''); do_tm_task -------------------------------------------------------------------------Task: moveout (Table: public.t) (Projection: public.t_super) (Table: public.p) (Projection: public.p_super) (1 row) => SELECT node_name, projection_schema, projection_name, is_up-to-date, checkpoint_epoch FROM projection_checkpoint_epochs; node_name | projection_schema | projection_name | is_up_to_date | checkpoint_epoch -----------+-------------------+-----------------+---------------+-----------------node01 | public | t_super | t | 53 node01 | public | p_super | t | 53 (2 rows) PROJECTION_COLUMNS Provides information about projection columns, such as encoding type, sort order, type of statistics, and the time at which columns statistics were last updated. Column Name Data Type Description PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR The projection name for which information is listed. HP Vertica Analytic Database (7.0.x) Page 1314 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PROJECTION_COLUMN_NAME VARCHAR The projection column name. COLUMN_POSITION INTEGER The ordinal position of a projection's column used in the CREATE PROJECTION statement. SORT_POSITION INTEGER The projection's column sort specification, as specified in CREATE PROJECTION .. ORDER BY clause. SORT_POSITION output is NULL if the column is not included in the projection's sort order. COLUMN_ID INTEGER A unique numeric object ID (OID) assigned by the HP Vertica catalog, COLUMN_ID is the OID of the associated projection column object. This field is helpful as a key to other system tables. DATA_TYPE VARCHAR Matches the corresponding table column data type (see V_CATALOG.COLUMNS). DATA_ TYPE is provided as a complement to ENCODING_TYPE. ENCODING_TYPE VARCHAR The encoding type defined on the projection column. ACCESS_RANK INTEGER The access rank of the projection column. See the ACCESSRANK parameter in the CREATE PROJECTION statement for more information. GROUP_ID INTEGER A unique numeric ID (OID) assigned by the HP Vertica catalog that identifies the group. TABLE_SCHEMA VARCHAR The schema name in which the projection resides. TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the table. TABLE_NAME VARCHAR The table name that contains the projection. TABLE_COLUMN_ID VARCHAR A unique VARCHAR ID, assigned by the HP Vertica catalog, that identifies a column in a table. TABLE_COLUMN_NAME VARCHAR The projection's corresponding table column name. HP Vertica Analytic Database (7.0.x) Page 1315 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description STATISTICS_TYPE VARCHAR The type of statistics the column has, which can be one of: STATISTICS_UPDATED_TIMESTAMP l NONE—No statistics l ROWCOUNT—Created from existing catalog metadata, which HP Vertica automatically and periodically updates l FULL—Created by running ANALYZE_ STATISTICS() TIMESTAMPTZ The time at which the columns statistics were last updated. Querying this column, along with STATISTICS_TYPE and PROJECTION_COLUMN_ NAME, lets you quickly identify projection columns whose statistics need updating. See also V_CATALOG.PROJECTIONS.HAS_ STATISTICS. Example On a single-node cluster, the following sample schema defines a table named trades, which groups the highly-correlated columns bid and ask and stores the stock column separately: => CREATE TABLE trades (stock CHAR(5), bid INT, ask INT); => CREATE PROJECTION trades_p (stock ENCODING RLE, GROUPED(bid ENCODING DELTAVAL, ask)) AS (SELECT * FROM trades) ORDER BY stock, bid; => INSERT INTO trades VALUES('acme', 10, 20); => COMMIT; Query the PROJECTION_COLUMNS table for table trades: => \x Expanded display is on. => SELECT * FROM PROJECTION_COLUMNS WHERE table_name = 'trades'; Notice that the statistics_type column returns NONE for all three columns in the trades table. Also, there is no value in the statistics_updated_timestamp field because statistics have not yet been run on this table. -[ RECORD 1 ]----------------+-------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | stock column_position | 0 sort_position | 0 HP Vertica Analytic Database (7.0.x) Page 1316 of 1539 SQL Reference Manual HP Vertica System Tables column_id | 45035996273718840 data_type | char(5) encoding_type | RLE access_rank | 0 group_id | 0 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-1 table_column_name | stock statistics_type | NONE statistics_updated_timestamp | -[ RECORD 2 ]----------------+-------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | bid column_position | 1 sort_position | 1 column_id | 45035996273718842 data_type | int encoding_type | DELTAVAL access_rank | 0 group_id | 45035996273718844 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-2 table_column_name | bid statistics_type | NONE statistics_updated_timestamp | -[ RECORD 3 ]----------------+-------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | ask column_position | 2 sort_position | column_id | 45035996273718846 data_type | int encoding_type | AUTO access_rank | 0 group_id | 45035996273718844 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-3 table_column_name | ask statistics_type | NONE statistics_updated_timestamp | Now run statistics on the stock column: => SELECT ANALYZE_STATISTICS('trades.stock'); The system returns 0 for success: HP Vertica Analytic Database (7.0.x) Page 1317 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 1 ]------+-ANALYZE_STATISTICS | 0 Now query PROJECTION_COLUMNS again: => SELECT * FROM PROJECTION_COLUMNS where table_name = 'trades'; This time, statistics_type changes to FULL for the trades.stock column (representing full statistics were run), and the statistics_updated_timestamp column returns the time the stock columns statistics were updated. The timestamp for the bid and ask columns have not changed because statistics were not run on those columns. Also, the bid and ask columns changed from NONE to ROWCOUNT. This is because HP Vertica automatically updates ROWCOUNT statistics from time to time. The statistics are created by looking at existing catalog metadata. -[ RECORD 1 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | stock column_position | 0 sort_position | 0 column_id | 45035996273718840 data_type | char(5) encoding_type | RLE access_rank | 0 group_id | 0 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-1 table_column_name | stock statistics_type | FULL statistics_updated_timestamp | 2012-12-08 13:52:04.178294-05 -[ RECORD 2 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | bid column_position | 1 sort_position | 1 column_id | 45035996273718842 data_type | int encoding_type | DELTAVAL access_rank | 0 group_id | 45035996273718844 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-2 table_column_name | bid statistics_type | ROWCOUNT statistics_updated_timestamp | 2012-12-08 13:51:20.016465-05 -[ RECORD 3 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | ask HP Vertica Analytic Database (7.0.x) Page 1318 of 1539 SQL Reference Manual HP Vertica System Tables column_position sort_position column_id data_type encoding_type access_rank group_id table_schema table_id table_name table_column_id table_column_name statistics_type statistics_updated_timestamp | | | | | | | | | | | | | | 2 45035996273718846 int AUTO 0 45035996273718844 public 45035996273718836 trades 45035996273718836-3 ask ROWCOUNT 2012-12-08 13:51:20.016475-05 If you run statistics on the bid column and then query this system table again, only RECORD 2 is updated: => SELECT ANALYZE_STATISTICS('trades.bid'); -[ RECORD 1 ]------+-ANALYZE_STATISTICS | 0 => SELECT * FROM PROJECTION_COLUMNS where table_name = 'trades'; -[ RECORD 1 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | stock column_position | 0 sort_position | 0 column_id | 45035996273718840 data_type | char(5) encoding_type | RLE access_rank | 0 group_id | 0 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-1 table_column_name | stock statistics_type | FULL statistics_updated_timestamp | 2012-12-08 13:52:04.178294-05 -[ RECORD 2 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | bid column_position | 1 sort_position | 1 column_id | 45035996273718842 data_type | int encoding_type | DELTAVAL access_rank | 0 group_id | 45035996273718844 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-2 table_column_name | bid HP Vertica Analytic Database (7.0.x) Page 1319 of 1539 SQL Reference Manual HP Vertica System Tables statistics_type | FULL statistics_updated_timestamp | 2012-12-08 13:53:23.438447-05 -[ RECORD 3 ]----------------+-----------------------------projection_id | 45035996273718838 projection_name | trades_p projection_column_name | ask column_position | 2 sort_position | column_id | 45035996273718846 data_type | int encoding_type | AUTO access_rank | 0 group_id | 45035996273718844 table_schema | public table_id | 45035996273718836 table_name | trades table_column_id | 45035996273718836-3 table_column_name | ask statistics_type | ROWCOUNT statistics_updated_timestamp | 2012-12-08 13:51:20.016475-05 You can quickly query just the timestamp column to see when the columns were updated: => \x Expanded display is off. => SELECT ANALYZE_STATISTICS('trades'); ANALYZE_STATISTICS -------------------0 (1 row) => SELECT projection_column_name, statistics_type, statistics_updated_timestamp FROM PROJECTION_COLUMNS where table_name = 'trades'; projection_column_name | statistics_type | statistics_updated_timestamp ------------------------+-----------------+------------------------------stock | FULL | 2012-12-08 13:54:27.428622-05 bid | FULL | 2012-12-08 13:54:27.428632-05 ask | FULL | 2012-12-08 13:54:27.428639-05 (3 rows) See Also l PROJECTIONS l ANALYZE_STATISTICS CREATE PROJECTION l l HP Vertica Analytic Database (7.0.x) Page 1320 of 1539 SQL Reference Manual HP Vertica System Tables PROJECTION_DELETE_CONCERNS Lists projections whose design may cause performance issues when deleting data. This table is generated by calling the EVALUATE_DELETE_PERFORMANCE function. See Optimizing Deletes and Updates for Performance in the Administrator's Guide for more information. Column Name Data Type Description PROJECTION_ID INTEGER The ID number of the projection PROJECTION_SCHEMA VARCHAR The schema containing the projection PROJECTION_NAME VARCHAR The projection's name CREATION_TIME TIMESTAMPTZ When the projection was created LAST_MODIFIED_TIME TIMESTAMPTZ When the projection was last modified COMMENT VARCHAR A comment describing the potential delete performance issue. PROJECTIONS Provides information about projections. Column Name Data Type Description PROJECTION_SCHEMA_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the specific schema that contains the projection. PROJECTION_SCHEMA VARCHAR The name of the schema that contains the projection. PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR The projection name for which information is listed. OWNER_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection owner. OWNER_NAME VARCHAR The name of the projection's owner. ANCHOR_TABLE_ID INTEGER The unique numeric identification (OID) of the anchor table for pre-join projections, or the OID of the table from which the projection was created if it is not a prejoin projection. Note: A projection has only one anchor (fact) table. HP Vertica Analytic Database (7.0.x) Page 1321 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ANCHOR_TABLE_NAME VARCHAR The name of the anchor table for pre-join projections, or the name of the table from which the projection was created if it is not a pre-join projection. NODE_ID INTEGER A unique numeric ID (OID) that identifies the node(s) that contain the projection. NODE_NAME VARCHAR The name of the node(s) that contain the projection. Note: this column returns information for unsegmented projections only, not for segmented and pinned projections. IS_PREJOIN BOOLEAN Indicates whether the projection is a pre-join projection, where t is true and f is false. IS_SUPER_PROJECTION BOOLEAN Indicates t (true) if a projection is a super-projection or f (false) if it is not. CREATED_EPOCH INTEGER The epoch in which the projection was created. CREATE_TYPE VARCHAR The method in which the projection was created: l CREATE PROJECTION—A custom projection created using a CREATE PROJECTION statement. l CREATE TABLE—A superprojection that was automatically created when its associated table was created using a CREATE TABLE statement. l CREATE TABLE WITH PROJ CLAUSE—A superprojection created using a CREATE TABLE statement. l DELAYED_CREATION—A superprojection that was automatically created when data was loaded into its associated table. l DESIGNER—A new projection created by the Database Designer. l SYSTEM TABLE—A projection that was automatically created for a system table. Rebalancing does not change the CREATE_TYPE value for a projection. HP Vertica Analytic Database (7.0.x) Page 1322 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description VERIFIED_FAULT_TOLERANCE INTEGER The projection K-safe value. This value can be greater than the database K-safety value (if more replications of a projection exist than are required to meet the database K-safety). This value cannot be less than the database K-safe setting. IS_UP_TO_DATE BOOLEAN Indicates whether the projection is up to date, where t is true and f is false. Projections must be up to date to be used in queries. HAS_STATISTICS BOOLEAN Indicates whether there are statistics for any column in the projection, where t is true and f is false. Notes: l This column returns true only when all non-epoch columns for a table have full statistics. Otherwise the column returns false. See ANALYZE_ STATISTICS(). l Projections that have no data never have full statistics. Use the PROJECTION_STORAGE system table to see if your projection contains data. Example The following example queries the PROJECTION_COLUMNS table to see if the projections are up to date and are pre-join projections. => SELECT projection_name, anchor_table_name, is_prejoin, is_up_to_date FROM projections; projection_name | anchor_table_name | is_prejoin | is_up_to_date ------------------------------+-----------------------+------------+--------------customer_dimension_site01 | customer_dimension | f | t customer_dimension_site02 | customer_dimension | f | t customer_dimension_site03 | customer_dimension | f | t customer_dimension_site04 | customer_dimension | f | t product_dimension_site01 | product_dimension | f | t product_dimension_site02 | product_dimension | f | t product_dimension_site03 | product_dimension | f | t product_dimension_site04 | product_dimension | f | t store_sales_fact_p1 | store_sales_fact | t | t store_sales_fact_p1_b1 | store_sales_fact | t | t store_orders_fact_p1 | store_orders_fact | t | t store_orders_fact_p1_b1 | store_orders_fact | t | t online_sales_fact_p1 | online_sales_fact | t | t online_sales_fact_p1_b1 | online_sales_fact | t | t promotion_dimension_site01 | promotion_dimension | f | t promotion_dimension_site02 | promotion_dimension | f | t promotion_dimension_site03 | promotion_dimension | f | t HP Vertica Analytic Database (7.0.x) Page 1323 of 1539 SQL Reference Manual HP Vertica System Tables promotion_dimension_site04 date_dimension_site01 date_dimension_site02 date_dimension_site03 date_dimension_site04 vendor_dimension_site01 vendor_dimension_site02 vendor_dimension_site03 vendor_dimension_site04 employee_dimension_site01 employee_dimension_site02 employee_dimension_site03 employee_dimension_site04 shipping_dimension_site01 shipping_dimension_site02 shipping_dimension_site03 shipping_dimension_site04 warehouse_dimension_site01 warehouse_dimension_site02 warehouse_dimension_site03 warehouse_dimension_site04 inventory_fact_p1 inventory_fact_p1_b1 store_dimension_site01 store_dimension_site02 store_dimension_site03 store_dimension_site04 online_page_dimension_site01 online_page_dimension_site02 online_page_dimension_site03 online_page_dimension_site04 call_center_dimension_site01 call_center_dimension_site02 call_center_dimension_site03 call_center_dimension_site04 (52 rows) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | promotion_dimension date_dimension date_dimension date_dimension date_dimension vendor_dimension vendor_dimension vendor_dimension vendor_dimension employee_dimension employee_dimension employee_dimension employee_dimension shipping_dimension shipping_dimension shipping_dimension shipping_dimension warehouse_dimension warehouse_dimension warehouse_dimension warehouse_dimension inventory_fact inventory_fact store_dimension store_dimension store_dimension store_dimension online_page_dimension online_page_dimension online_page_dimension online_page_dimension call_center_dimension call_center_dimension call_center_dimension call_center_dimension | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f f | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t t See Also l ANALYZE_STATISTICS l PROJECTION_COLUMNS l PROJECTION_STORAGE RESOURCE_POOL_DEFAULTS Provides information about the default values for resource pools. Information is for both HP Verticainternal and DBA-created pools. For any resource pool, you can restore default values contained in this table by simply using the DEFAULT keyword in the ALTER_RESOURCE_POOL statement. To see default values for resource pools: HP Vertica Analytic Database (7.0.x) Page 1324 of 1539 SQL Reference Manual HP Vertica System Tables VMart= > SELECT * FROM V_CATALOG.RESOURCE_POOL_DEFAULTS; Permissions No explicit permissions are required. See Also l Built-In Pool Configuration l RESOURCE_POOLS l CREATE RESOURCE POOL l ALTER RESOURCE POOL l SET SESSION RESOURCE_POOL l DROP RESOURCE POOL RESOURCE_POOLS Displays information about the parameters specified for the resource pool in the CREATE RESOURCE POOL statement. Column Name Data Type Description NAME VARCHAR The name of the resource pool. IS_INTERNAL BOOLEAN Denotes whether a pool is one of the Built-In Pools. MEMORYSIZE VARCHAR Value of the amount of memory allocated to the resource pool. MAXMEMORYSIZE VARCHAR Value assigned as the maximum size the resource pool could grow by borrowing memory from the GENERAL pool. HP Vertica Analytic Database (7.0.x) Page 1325 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description EXECUTIONPARALLELISM INTEGER [Default: AUTO] Limits the number of threads used to process any single query issued in this resource pool. When set to AUTO, HP Vertica sets this value based on the number of cores, available memory, and amount of data in the system. Unless data is limited, or the amount of data is very small, HP Vertica sets this value to the number of cores on the node. Reducing this value increases the throughput of short queries issued in the pool, especially if the queries are executed concurrently. If you choose to set this parameter manually, set it to a value between 1 and the number of cores. PRIORITY INTEGER Value of PRIORITY parameter specified when defining the pool. RUNTIMEPRIORITY VARCHAR Value that indicates the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to running queries in the resource pool. Valid values are: l HIGH l MEDIUM (Default) l LOW These values are relative to each other. Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. RUNTIMEPRIORITYTHRESHOLD INTEGER Value that specifies the time limit (in seconds) by which a query must finish before the Resource Manager assigns to it the RUNTIMEPRIORITY of the resource pool. All queries begin running at a HIGH priority. When a query's duration exceeds this threshold, it is assigned the RUNTIMEPRIORITY of the resource pool. Default is 2. QUEUETIMEOUT INTEGER Value in seconds of QUEUETIMEOUT parameter specified when defining the pool. Represents the maximum amount of time the request is allowed to wait for resources to become available before being rejected. HP Vertica Analytic Database (7.0.x) Page 1326 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PLANNEDCONCURRENCY INTEGER Value of PLANNEDCONCURRENCY parameter specified when defining the pool, which represents the number of concurrent queries that are normally expected to be running against the resource pool. MAXCONCURRENCY INTEGER Value of MAXCONCURRENCY parameter specified when defining the pool, which represents the maximum number of concurrent execution slots available to the resource pool. RUNTIMECAP INTERVAL [Default: NONE] Sets the maximum amount of time any query on the pool can execute. Set RUNTIMECAP using interval, such as '1 minute' or '100 seconds' (see Interval Values for details). This value cannot exceed one year. Setting this value to NONE specifies that there is no time limit on queries running on the pool. If the user or session also has a RUNTIMECAP, the shorter limit applies. SINGLEINITIATOR BOOLEAN Value that indicates whether all requests using this pool are issued against the same initiator node or whether multiple initiator nodes can be used; for instance in a round-robin configuration. CPUAFFINITYSET VARCHAR Value which represents the set of CPUs on which queries associated with this pool are executed. For example, '0, 2-4' for the 0, 2, 3, and 4 CPUs, or '25%' for a percentage of available CPUs. Percentage values are rounded down to whole CPUs. CPUAFFINITYMODE VARCHAR Value which represents the mode of the CPU affinity. If CPUAFFINITYSET is set to a a CPU percentage or index/index list, then the value can be: HP Vertica Analytic Database (7.0.x) l SHARED - This pool is pinned to the CPU index(s) or percentage defined in CPUAFFINITYSET, and other pools can share the same CPU(s). l EXCLUSIVE - This pool is pinned to the CPU index (s) or percentage defined in CPUAFFINITYSET, but other pools can NOT use the same CPU(s). l ANY - The pool does not have an affinity for any particular CPU or percentage of available CPUs. Page 1327 of 1539 SQL Reference Manual HP Vertica System Tables Notes Column names in the RESOURCE_POOL table mirror syntax in the CREATE RESOURCE POOL statement; therefore, column names do not use underscores. Example To see values set for your resource pools: => \x Expanded display is on. => SELECT * FROM V_CATALOG.RESOURCE_POOLS; -[ RECORD 1 ]------------+-----------------pool_id | 45035996273718852 name | general is_internal | t memorysize | maxmemorysize | Special: 95% executionparallelism | AUTO priority | 0 runtimepriority | MEDIUM runtimeprioritythreshold | 2 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | f cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 2 ]------------+-----------------pool_id | 45035996273718854 name | sysquery is_internal | t memorysize | 64M maxmemorysize | executionparallelism | AUTO priority | 110 runtimepriority | HIGH runtimeprioritythreshold | 0 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | f cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 3 ]------------+-----------------pool_id | 45035996273718856 name | sysdata is_internal | t memorysize | 100M maxmemorysize | 10% executionparallelism | priority | HP Vertica Analytic Database (7.0.x) Page 1328 of 1539 SQL Reference Manual HP Vertica System Tables runtimepriority | runtimeprioritythreshold | queuetimeout | plannedconcurrency | maxconcurrency | runtimecap | singleinitiator | cpuaffinityset | cpuaffinitymode | -[ RECORD 4 ]------------+-----------------pool_id | 45035996273718858 name | wosdata is_internal | t memorysize | 0% maxmemorysize | 25% executionparallelism | priority | runtimepriority | runtimeprioritythreshold | queuetimeout | plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | cpuaffinityset | cpuaffinitymode | -[ RECORD 5 ]------------+-----------------pool_id | 45035996273718860 name | tm is_internal | t memorysize | 200M maxmemorysize | executionparallelism | AUTO priority | 105 runtimepriority | MEDIUM runtimeprioritythreshold | 60 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | 3 runtimecap | singleinitiator | t cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 6 ]------------+-----------------pool_id | 45035996273718862 name | refresh is_internal | t memorysize | 0% maxmemorysize | executionparallelism | AUTO priority | -10 runtimepriority | MEDIUM runtimeprioritythreshold | 60 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | t HP Vertica Analytic Database (7.0.x) Page 1329 of 1539 SQL Reference Manual HP Vertica System Tables cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 7 ]------------+-----------------pool_id | 45035996273718864 name | recovery is_internal | t memorysize | 0% maxmemorysize | executionparallelism | AUTO priority | 107 runtimepriority | MEDIUM runtimeprioritythreshold | 60 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | 1 runtimecap | singleinitiator | t cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 8 ]------------+-----------------pool_id | 45035996273718866 name | dbd is_internal | t memorysize | 0% maxmemorysize | executionparallelism | AUTO priority | 0 runtimepriority | MEDIUM runtimeprioritythreshold | 0 queuetimeout | 0 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | t cpuaffinityset | cpuaffinitymode | ANY -[ RECORD 9 ]------------+-----------------pool_id | 45035996273718948 name | jvm is_internal | t memorysize | 0% maxmemorysize | 10% executionparallelism | AUTO priority | 0 runtimepriority | MEDIUM runtimeprioritythreshold | 2 queuetimeout | 300 plannedconcurrency | AUTO maxconcurrency | runtimecap | singleinitiator | f cpuaffinityset | cpuaffinitymode | ANY HP Vertica Analytic Database (7.0.x) Page 1330 of 1539 SQL Reference Manual HP Vertica System Tables See Also l CREATE RESOURCE POOL l ALTER RESOURCE POOL ROLES Contains the names of all roles the user can access, along with any roles that have been assigned to those roles. Column Name Data Type Description ROLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the role. NAME VARCHAR The name of a role that the user can access. ASSIGNED_ROLES VARCHAR The names of any roles that have been granted to this role. By enabling the role, the user also has access to the privileges of these additional roles. Note: If you see an asterisk in the ASSIGNED_ROLES column output, it means the user has roles WITH ADMIN OPTION. Tip: You can also use the HAS_ROLE() function to see if a role is available to a user. Example => SELECT * FROM roles; role_id | name | assigned_roles -------------------+-----------------+---------------45035996273704964 | public | 45035996273704966 | dbduser | 45035996273704968 | dbadmin | dbduser* 45035996273704972 | pseudosuperuser | dbadmin* 45035996273704974 | logreader | 45035996273704976 | logwriter | 45035996273704978 | logadmin | logreader, logwriter (7 rows) HP Vertica Analytic Database (7.0.x) Page 1331 of 1539 SQL Reference Manual HP Vertica System Tables See Also l GRANTS l HAS_ROLE l USERS SCHEMATA Provides information about schemas in the database. Column Name Data Type Description SCHEMA_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the specific schema. SCHEMA_NAME VARCHAR Schema name for which information is listed. SCHEMA_OWNER_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the owner who created the schema. SCHEMA_OWNER VARCHAR Name of the owner who created the schema. SYSTEM_SCHEMA_CREATOR VARCHAR Creator information for system schema or NULL for non-system schema CREATE_TIME TIMESTAMPTZ Time when the schema was created. IS_SYSTEM_SCHEMA BOOLEAN Indicates whether the schema was created for system use, where t is true and f is false. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM schemata; -[ RECORD 1 ]---------+-----------------------------schema_id | 8300 schema_name | v_internal schema_owner_id | 45035996273704962 schema_owner | dbadmin system_schema_creator | dbadmin create_time | 2012-03-22 11:19:46.311825-04 HP Vertica Analytic Database (7.0.x) Page 1332 of 1539 SQL Reference Manual HP Vertica System Tables is_system_schema | t -[ RECORD 2 ]---------+-----------------------------schema_id | 8301 schema_name | v_catalog schema_owner_id | 45035996273704962 schema_owner | dbadmin system_schema_creator | dbadmin create_time | 2012-03-22 11:19:46.311905-04 is_system_schema | t -[ RECORD 3 ]---------+-----------------------------schema_id | 8302 schema_name | v_monitor schema_owner_id | 45035996273704962 schema_owner | dbadmin system_schema_creator | dbadmin create_time | 2012-03-22 11:19:46.31193-04 is_system_schema | t -[ RECORD 4 ]---------+-----------------------------schema_id | 45035996273704968 schema_name | public schema_owner_id | 45035996273704962 schema_owner | dbadmin system_schema_creator | create_time | 2012-03-22 11:19:40.75002-04 is_system_schema | f SEQUENCES Displays information about the parameters specified for a sequence using the CREATE SEQUENCE statement. Column Name Data Type Description SEQUENCE_SCHEMA VARCHAR Schema in which the sequence was created. SEQUENCE_NAME VARCHAR Name of the sequence defined in the CREATE SEQUENCE statement. OWNER_NAME VARCHAR Name of the owner; for example, dbadmin. IDENTITY_TABLE_NAME VARCHAR If created by an identity column, the name of the table to which it belongs. See column constraints in the CREATE TABLE statement. SESSION_CACHE_COUNT INTEGER Count of values cached in a session. ALLOW_CYCLE BOOLEAN Values allowed to cycle when max/min is reached. See CYCLE | NO CYCLE parameter in CREATE SEQUENCE. OUTPUT_ORDERED BOOLEAN Values guaranteed to be ordered (always false). INCREMENT_BY INTEGER Sequence values are incremented by this number (negative for reverse sequences). HP Vertica Analytic Database (7.0.x) Page 1333 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description MINIMUM INTEGER Minimum value the sequence can generate. MAXIMUM INTEGER Maximum value the sequence can generate. CURRENT_VALUE INTEGER Current value of the sequence. SEQUENCE_SCHEMA_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the schema. SEQUENCE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the sequence. OWNER_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the user who created the sequence. IDENTITY_TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the table to which the column belongs (if created by an identity column). Examples Create a simple sequence: => CREATE SEQUENCE my_seq MAXVALUE 5000 START 150; CREATE SEQUENCE Return information about the sequence you just created: => \x Expanded display is on. => SELECT * FROM sequences; -[ RECORD 1 ]-------+-----------------sequence_schema | public sequence_name | my_seq owner_name | dbadmin identity_table_name | session_cache_count | 250000 allow_cycle | f output_ordered | f increment_by | 1 minimum | 1 maximum | 5000 current_value | 149 sequence_schema_id | 45035996273704966 sequence_id | 45035996273844996 owner_id | 45035996273704962 identity_table_id | 0 An identity column is a sequence available only for numeric column types. To identify what column in a table, if any, is an identity column, search the COLUMNS table to find the identity column in a table: HP Vertica Analytic Database (7.0.x) Page 1334 of 1539 SQL Reference Manual HP Vertica System Tables => CREATE TABLE testid (c1 IDENTITY(1, 1, 1000), c2 INT); => \x Expanded display is on. => SELECT * FROM COLUMNS WHERE is_identity='t' AND table_name='testid'; -[ RECORD 1 ]------------+-----------------table_id | 45035996274150730 table_schema | public table_name | testid is_system_table | f column_name | c1 data_type | int data_type_id | 6 data_type_length | 8 character_maximum_length | numeric_precision | numeric_scale | datetime_precision | interval_precision | ordinal_position | 1 is_nullable | f column_default | is_identity | t Use the SEQUENCES table to get detailed information about the sequence in testid: => SELECT * FROM sequences WHERE identity_table_name='testid'; -[ RECORD 1 ]-------+-------------------sequence_schema | public sequence_name | testid_c1_seq owner_name | dbadmin identity_table_name | testid session_cache_count | 1000 allow_cycle | f output_ordered | f increment_by | 1 minimum | 1 maximum | 9223372036854775807 current_value | 0 sequence_schema_id | 45035996273704976 sequence_id | 45035996274150770 owner_id | 45035996273704962 identity_table_id | 45035996274150768 Use the vsql command \ds to return a list of sequences. The following results show the two sequences created in the preceding examples. If more sequences existed, the table would list them. The CurrentValue of the new sequence is one less than the start number you specified in the CREATE SEQUENCE and IDENTITY commands, because you have not yet used NEXTVAL to instantiate the sequences to assign their cache or supply their first start values. => \ds List of Sequences -[ RECORD 1 ]+-------------------- HP Vertica Analytic Database (7.0.x) Page 1335 of 1539 SQL Reference Manual HP Vertica System Tables Schema | public Sequence | my_seq CurrentValue | 149 IncrementBy | 1 Minimum | 1 Maximum | 5000 AllowCycle | f Comment | -[ RECORD 2 ]+-------------------Schema | public Sequence | testid_c1_seq CurrentValue | 0 IncrementBy | 1 Minimum | 1 Maximum | 9223372036854775807 AllowCycle | f Comment | See Also l CREATE SEQUENCE STORAGE_LOCATIONS Provides information about storage locations, their IDs labels, and status. Column Name Data Type Description LOCATION_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the storage location. NODE_NAME VARCHAR The node name on which the storage location exists. LOCATION_PATH VARCHAR The path where the storage location is mounted. LOCATION_USAGE VARCHAR The type of information stored in the location: l DATA: Only data is stored in the location. l TEMP: Only temporary files that are created during loads or queries are stored in the location. l DATA,TEMP: Both types of files are stored in the location. l USER: The storage location can be used by non-dbadmin users, who are granted access to the storage location l CATALOG: The area is used for the HP Vertica catalog. This usage is set internally and cannot be removed or changed. HP Vertica Analytic Database (7.0.x) Page 1336 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_RETIRED BOOLEAN Whether the storage location has been retired. This column has a value of t (true) if the location is retired, or f (false) if it is not. LOCATION_LABEL VARCHAR The label associated with a specific storage location, added with the ALTER_LOCATION_LABEL function. RANK INTEGER The Access Rank value either assigned or supplied to the storage location, as described in Prioritizing Column Access Speed. THROUGHPUT INTEGER The throughput performance of the storage location, measured in MB/sec. You can get location performance values using MEASURE_LOCATION_PERFORMANCE, and set them with the SET_LOCATION_PERFORMANCE function. LATENCY INTEGER The measured latency of the storage location as number of data seeks per second. You can get location performance values using MEASURE_LOCATION_PERFORMANCE, and set them with the SET_LOCATION_PERFORMANCE function. Permissions Must be a superuser. Example Query the STORAGE_LOCATIONS table on a one-node cluster database: onenode=> SELECT * FROM storage_locations; -[ RECORD 1 ]--+---------------------------------------------location_id | 45035996273704982 node_name | v_onenode_node0001 location_path | /home/dbadmin/onenode/v_onenode_node0001_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 0 latency | 0 The next example uses the VMart example database (see Introducing the VMart Example Database). VMart=> \x VMart=> select * from storage_locations; HP Vertica Analytic Database (7.0.x) Page 1337 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 1 ]--+---------------------------------------------location_id | 45035996273704982 node_name | v_onenode_node0001 location_path | /home/dbadmin/onenode/v_onenode_node0001_data location_usage | DATA,TEMP is_retired | f location_label | rank | 1 throughput | 24 latency | 38 -[ RECORD 2 ]--+---------------------------------------------location_id | 45035996273356845 node_name | v_onenode_node0001 location_path | /home/dbadmin/onenode/v_onenode_node0001_data location_usage | DATA,TEMP is_retired | f location_label | rank | 2 throughput | 45 latency | 42 -[ RECORD 3 ]--+---------------------------------------------location_id | 45035996273713695 node_name | v_onenode_node0001 location_path | /home/dbadmin/onenode/v_onenode_node0001_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 26 latency | 24 -[ RECORD 4 ]--+---------------------------------------------location_id | 45035996273734821 node_name | v_onenode_node0002 location_path | /home/dbadmin/onenode/v_onenode_node0002_data location_usage | DATA,TEMP is_retired | f location_label | rank | 1 throughput | 33 latency | 31 -[ RECORD 5 ]--+---------------------------------------------location_id | 45035996273757686 node_name | v_onenode_node0002 location_path | /home/dbadmin/onenode/v_onenode_node0002_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 25 latency | 23 -[ RECORD 6 ]--+---------------------------------------------location_id | 45035996273767432 node_name | v_onenode_node0002 location_path | /home/dbadmin/onenode/v_onenode_node0002_data location_usage | DATA,TEMP is_retired | f location_label | HP Vertica Analytic Database (7.0.x) Page 1338 of 1539 SQL Reference Manual HP Vertica System Tables rank | 0 throughput | 44 latency | 35 -[ RECORD 7 ]--+---------------------------------------------location_id | 45035996273789765 node_name | v_onenode_node0002 location_path | /home/dbadmin/onenode/v_onenode_node0002_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 43 latency | 36 -[ RECORD 8 ]--+---------------------------------------------location_id | 45035996273777654 node_name | v_onenode_node0003 location_path | /home/dbadmin/onenode/v_onenode_node0003_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 25 latency | 34 -[ RECORD 9 ]--+---------------------------------------------location_id | 45035996273799043 node_name | v_onenode_node0003 location_path | /home/dbadmin/onenode/v_onenode_node0003_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 41 latency | 43 -[ RECORD 10]--+---------------------------------------------location_id | 45035996273799477 node_name | v_onenode_node0003 location_path | /home/dbadmin/onenode/v_onenode_node0003_data location_usage | DATA,TEMP is_retired | f location_label | rank | 0 throughput | 22 latency | 21 (10 rows) See Also l DISK_STORAGE l MEASURE_LOCATION_PERFORMANCE l SET_LOCATION_PERFORMANCE l STORAGE_POLICIES HP Vertica Analytic Database (7.0.x) Page 1339 of 1539 SQL Reference Manual HP Vertica System Tables l STORAGE_USAGE l Storage Management Functions SYSTEM_COLUMNS Provides table column information for SYSTEM_TABLES. Column Name Data Type Description TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the table. TABLE_SCHEMA VARCHAR The schema name for which information is listed. TABLE_NAME VARCHAR The table name for which information is listed. IS_SYSTEM_TABLE BOOLEAN Indicates whether the table is a system table, where t is true and f is false. COLUMN_ID VARCHAR A unique VARCHAR ID, assigned by the HP Vertica catalog, that identifies a column in a table. COLUMN_NAME VARCHAR The column name for which information is listed in the database. DATA_TYPE VARCHAR The data type assigned to the column; for example VARCHAR(16). DATA_TYPE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the data type. DATA_TYPE_LENGTH INTEGER The maximum allowable length of the data type. CHARACTER_MAXIMUM_LENGTH INTEGER The maximum allowable length of the column. NUMERIC_PRECISION INTEGER The number of significant decimal digits. NUMERIC_SCALE INTEGER The number of fractional digits. DATETIME_PRECISION INTEGER For TIMESTAMP data type, returns the declared precision; returns null if no precision was declared. INTERVAL_PRECISION INTEGER The number of fractional digits retained in the seconds field. ORDINAL_POSITION INTEGER The position of the column respective to other columns in the table. IS_NULLABLE BOOLEAN Indicates whether the column can contain null values, where t is true and f is false. COLUMN_DEFAULT VARCHAR The default value of a column, such as empty or expression. HP Vertica Analytic Database (7.0.x) Page 1340 of 1539 SQL Reference Manual HP Vertica System Tables Example => SELECT table_schema, table_name, column_name, column_id, data_type FROM system_columns WHERE table_name = 'projection_columns' ORDER BY 1,2; table_schema | table_name | column_name | column_id | data_ type --------------+--------------------+------------------------------+-------------+-------------v_catalog | projection_columns | statistics_updated_timestamp | 10038-17 | timesta mptz v_catalog | projection_columns | statistics_type | 10038-16 | varchar (8192) v_catalog | projection_columns | table_column_name | 10038-15 | varchar (128) v_catalog | projection_columns | table_column_id | 10038-14 | varchar (41) v_catalog | projection_columns | table_name | 10038-13 | varchar (128) v_catalog | projection_columns | table_id | 10038-12 | int v_catalog | projection_columns | table_schema | 10038-11 | varchar (128) v_catalog | projection_columns | group_id | 10038-10 | int v_catalog | projection_columns | access_rank | 10038-9 | int v_catalog | projection_columns | encoding_type | 10038-8 | varchar (18) v_catalog | projection_columns | data_type | 10038-7 | varchar (128) v_catalog | projection_columns | column_id | 10038-6 | int v_catalog | projection_columns | sort_position | 10038-5 | int v_catalog | projection_columns | column_position | 10038-4 | int v_catalog | projection_columns | projection_column_name | 10038-3 | varchar (128) v_catalog | projection_columns | projection_name | 10038-2 | varchar (128) v_catalog | projection_columns | projection_id | 10038-1 | int (17 rows) SYSTEM_TABLES Returns a list of all system table names. Column Name Data Type Description TABLE_SCHEMA_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the schema. TABLE_SCHEMA VARCHAR The schema name in which the system table resides; for example, V_CATALOG or V_MONITOR. HP Vertica Analytic Database (7.0.x) Page 1341 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TABLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the table. TABLE_NAME VARCHAR The name of the system table. TABLE_DESCRIPTION VARCHAR A description of the system table's purpose. Example Select all the system tables and order them by schema: => SELECT * FROM system_tables ORDER BY 1, 2; Select tables related to column information: => SELECT * FROM system_tables WHERE table_name ILIKE '%col%'; table_schema_id | table_schema | table_id | table_name | table_descripti on -----------------+--------------+----------+--------------------+----------------------------------8301 | v_catalog | 10038 | projection_columns | Projection columns ... 8301 | v_catalog | 10212 | system_columns | System column ... 8301 | v_catalog | 10208 | odbc_columns | An ODBC compliant ... 8301 | v_catalog | 10134 | constraint_columns | Table column constraint ... 8301 | v_catalog | 10000 | columns | Table column informatio n ... 8301 | v_catalog | 10024 | view_columns | View column information ... 8302 | v_monitor | 10200 | column_storage | Information on amount o f disk ... 8302 | v_monitor | 10058 | data_collector | Statistics on usage Dat a Col... (8 rows) TABLE_CONSTRAINTS Provides information about table constraints. Column Name Data Type Description CONSTRAINT_ID VARCHAR A unique numeric ID, assigned by the HP Vertica catalog, which identifies the constraint. CONSTRAINT_NAME VARCHAR The name of the constraint, if specified as UNIQUE, FOREIGN KEY, NOT NULL, or PRIMARY KEY. HP Vertica Analytic Database (7.0.x) Page 1342 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CONSTRAINT_SCHEMA_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the schema containing the constraint. CONSTRAINT_KEY_COUNT INTEGER The number of constraint keys. FOREIGN_KEY_COUNT INTEGER The number of foreign keys. TABLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the table. TABLE_NAME VARCHAR The name of the table that contains the UNIQUE, FOREIGN KEY, NOT NULL, or PRIMARY KEY constraint FOREIGN_TABLE_ID INTEGER The unique object ID of the foreign table referenced in a foreign key constraint (zero if not a foreign key constraint). CONSTRAINT_TYPE INTEGER Is one of 'c', 'f', 'p', 'U' or 'd,' which refer to 'check', 'foreign', 'primary', 'unique' and 'determines', respectively. Example The following command returns constraint column names and types against the VMart schema. vmartdb=> SELECT constraint_name, constraint_type FROM table_constraints ORDER BY constraint_type; constraint_name | constraint_type ---------------------------+----------------fk_online_sales_promotion | f fk_online_sales_warehouse | f fk_online_sales_shipping | f fk_online_sales_op | f fk_online_sales_cc | f fk_online_sales_customer | f fk_online_sales_product | f fk_online_sales_shipdate | f fk_online_sales_saledate | f fk_store_orders_employee | f fk_store_orders_vendor | f fk_store_orders_store | f fk_store_orders_product | f fk_store_sales_employee | f fk_store_sales_customer | f fk_store_sales_promotion | f fk_store_sales_store | f fk_store_sales_product | f fk_store_sales_date | f fk_inventory_warehouse | f fk_inventory_product | f fk_inventory_date | f | p | p | p HP Vertica Analytic Database (7.0.x) Page 1343 of 1539 SQL Reference Manual HP Vertica System Tables (33 rows) | | | | | | | | p p p p p p p p See Also l ANALYZE_CONSTRAINTS TABLES Provides information about all tables in the database. Column Name Data Type Description TABLE_SCHEMA_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the schema. TABLE_SCHEMA VARCHAR The schema name for which information is listed. TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the table. TABLE_NAME VARCHAR The table name for which information is listed. OWNER_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the owner. OWNER_NAME VARCHAR The name of the user who created the table. IS_TEMP_TABLE BOOLEAN Indicates whether table is a system table, where t is true and f is false. IS_SYSTEM_TABLE BOOLEAN Indicates whether table is a temporary table, where t is true and f is false. IS_FLEXTABLE BOOLEAN Indicates if the table is a Flex table, where t is true and f is false. SYSTEM_TABLE_CREATOR VARCHAR The name of the process that created the table, such as Designer. PARTITION_EXPRESSION VARCHAR The partition expression for the table. CREATE_TIME TIMESTAMP Returns the timestamp for when the table was created. HP Vertica Analytic Database (7.0.x) Page 1344 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TABLE_DEFINITION VARCHAR The COPY statement table definition. This column is applicable only to external tables. Notes The TABLE_SCHEMA and TABLE_NAME columns are case sensitive when you run queries that contain the equality (=) predicate. Use the ILIKE predicate instead: => SELECT table_schema, table_name FROM v_catalog.tables WHERE table_schema ILIKE 'schema1'; Example To return information on all tables in the Vmart schema: vmartdb=> SELECT table_schema, table_name, owner_name, is_system_table FROM tables; table_schema | table_name | owner_name | is_system_table --------------+-----------------------+------------+----------------public | customer_dimension | release | f public | product_dimension | release | f public | promotion_dimension | release | f public | date_dimension | release | f public | vendor_dimension | release | f public | employee_dimension | release | f public | shipping_dimension | release | f public | warehouse_dimension | release | f public | inventory_fact | release | f store | store_dimension | release | f store | store_sales_fact | release | f store | store_orders_fact | release | f online_sales | online_page_dimension | release | f online_sales | call_center_dimension | release | f online_sales | online_sales_fact | release | f (15 rows) To return the timestamp for when the tables were created: vmartdb=> SELECT table_schema, table_name, create_time FROM tables; table_schema | table_name | create_time --------------+-----------------------+------------------------------public | customer_dimension | 2011-08-15 11:18:25.784203-04 public | product_dimension | 2011-08-15 11:18:25.815653-04 public | promotion_dimension | 2011-08-15 11:18:25.850592-04 public | date_dimension | 2011-08-15 11:18:25.892347-04 public | vendor_dimension | 2011-08-15 11:18:25.942805-04 public | employee_dimension | 2011-08-15 11:18:25.966985-04 public | shipping_dimension | 2011-08-15 11:18:25.999394-04 public | warehouse_dimension | 2011-08-15 11:18:26.461297-04 HP Vertica Analytic Database (7.0.x) Page 1345 of 1539 SQL Reference Manual HP Vertica System Tables public store store store online_sales online_sales online_sales (15 rows) | | | | | | | inventory_fact store_dimension store_sales_fact store_orders_fact online_page_dimension call_center_dimension online_sales_fact | | | | | | | 2011-08-15 2011-08-15 2011-08-15 2011-08-15 2011-08-15 2011-08-15 2011-08-15 11:18:26.513525-04 11:18:26.657409-04 11:18:26.737535-04 11:18:26.825801-04 11:18:27.007329-04 11:18:27.476844-04 11:18:27.49749-04 To return information about whether certain tables are temporary and flex tables: => SELECT distinct table_name, table_schema, is_temp_table, is_flextable FROM v_catalog.t ables WHERE table_name ILIKE 't%'; table_name | table_schema | is_temp_table | is_flextable --------------+--------------+---------------+----------------t2_temp | public | t | t tt_keys | public | f | f t2_temp_keys | public | f | f t3 | public | t | f t1 | public | f | f t9_keys | public | f | f t2_keys | public | f | t t6 | public | t | f t5 | public | f | f t2 | public | f | t t8 | public | f | f t7 | public | t | f tt | public | t | t t2_keys_keys | public | f | f t9 | public | t | t (15 rows) TYPES Provides information about supported data types. Note: This table was updated with new columns in Release 5.1. Column Name Data Type Description TYPE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the specific data type. ODBC_TYPE INTEGER The numerical ODBC type. ODBC_ SUBTYPE INTEGER The numerical ODBC subtype, used to differentiate types such as time and interval that have multiple subtypes. MIN_SCALE INTEGER The minimum number of digits supported to the right of the decimal point for the data type. HP Vertica Analytic Database (7.0.x) Page 1346 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description MAX_SCALE INTEGER The maximum number of digits supported to the right of the decimal point for the data type. A value of 0 is used for types that do not use decimal points. COLUMN_ SIZE INTEGER The number of characters required to display the type. See: http://msdn.microsoft.com/enus/library/windows/desktop/ms711786%28v=VS.85%29.aspx for the details on COLUMN_SIZE for each type. INTERVAL_ MASK INTEGER For data types that are intervals, the bitmask to determine the range of the interval from the HP Vertica TYPE_ID. Details are available in the HP Vertica SDK. TYPE_NAME VARCHAR The data type name associated with a particular data type ID. CREATION_ VARCHAR PARAMETERS A list of keywords, separated by commas, corresponding to each parameter that the application may specify in parentheses when using the name that is returned in the TYPE_NAME field. The keywords in the list can be any of the following: length, precision, or scale. They appear in the order that the syntax requires them to be used. Example dbadmin=> \x Expanded display is on. dbadmin=> SELECT * FROM types LIMIT 3; -[ RECORD 1 ]-------+-------------------------type_id | 5 odbc_type | -7 odbc_subtype | 0 min_scale | 0 max_scale | 0 column_size | 1 interval_mask | 0 type_name | Boolean creation_parameters | -[ RECORD 2 ]-------+-------------------------type_id | 6 odbc_type | -5 odbc_subtype | 0 min_scale | 0 max_scale | 0 column_size | 20 interval_mask | 0 type_name | Integer creation_parameters | -[ RECORD 3 ]-------+-------------------------type_id | 7 HP Vertica Analytic Database (7.0.x) Page 1347 of 1539 SQL Reference Manual HP Vertica System Tables odbc_type odbc_subtype min_scale max_scale column_size interval_mask type_name creation_parameters | | | | | | | | 8 0 0 0 15 0 Float precision USER_AUDITS Lists the results of database and object size audits generated by users calling the AUDIT function. See Monitoring Database Size for License Compliance in the Administrator's Guide for more information. Column Name Data Type Description SIZE_BYTES INTEGER The estimated raw data size of the database USER_ID INTEGER The ID of the user who generated the audit USER_NAME VARCHAR The name of the user who generated the audit OBJECT_ID INTEGER The ID of the object being audited OBJECT_TYPE VARCHAR The type of object being audited (table, schema, etc.) OBJECT_SCHEMA VARCHAR The schema containing the object being audited OBJECT_NAME VARCHAR The name of the object being audited AUDIT_START_TIMESTAMP TIMESTAMPTZ When the audit started AUDIT_END_TIMESTAMP TIMESTAMPTZ When the audit finished CONFIDENCE_LEVEL_PERCENT FLOAT The confidence level of the size estimate ERROR_TOLERANCE_PERCENT FLOAT The error tolerance used for the size estimate USED_SAMPLING BOOLEAN Whether data was randomly sampled (if false, all of the data was analyzed) HP Vertica Analytic Database (7.0.x) Page 1348 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CONFIDENCE_INTERVAL_LOWER_BOUND_BYTES INTEGER The lower bound of the data size estimate within the confidence level CONFIDENCE_INTERVAL_UPPER_BOUND_BYTES INTEGER The upper bound of the data size estimate within the confidence level SAMPLE_COUNT INTEGER The number of data samples used to generate the estimate CELL_COUNT INTEGER The number of cells in the database USER_FUNCTIONS Returns metadata about user-defined SQL functions (which store commonly used SQL expressions as a function in the HP Vertica catalog) and User Defined functions (UDx). Column Name Data Type Description SCHEMA_NAME VARCHAR The name of the schema in which this function exists. FUNCTION_NAME VARCHAR The name assigned by the user to the SQL function or User Defined Function. PROCEDURE_TYPE VARCHAR The type of user defined function. For example, 'User Defined Function'. FUNCTION_RETURN_TYPE VARCHAR The data type name that the SQL function returns. FUNCTION_ARGUMENT_TYPE VARCHAR The number and data types of parameters for the function. FUNCTION_DEFINITION VARCHAR The SQL expression that the user defined in the SQL function's function body. VOLATILITY VARCHAR The SQL function's volatility (whether a function returns the same output given the same input). Can be immutable, volatile, or stable. IS_STRICT BOOLEAN Indicates whether the SQL function is strict, where t is true and f is false. IS_FENCED BOOLEAN Indicates whether the function runs in Fenced Mode or not. COMMENT VARCHAR A comment about this function provided by the function creator. HP Vertica Analytic Database (7.0.x) Page 1349 of 1539 SQL Reference Manual HP Vertica System Tables Notes l The volatility and strictness of a SQL function are automatically inferred from the function definition in order that HP Vertica determine the correctness of usage, such as where an immutable function is expected but a volatile function is provided. l The volatility and strictness of a UDx is defined by the UDx's developer. Example Create a SQL function called myzeroifnull in the public schema: => CREATE FUNCTION myzeroifnull(x INT) RETURN INT AS BEGIN RETURN (CASE WHEN (x IS NOT NULL) THEN x ELSE 0 END); END; Now query the USER_FUNCTIONS table. The query returns just the myzeroifnull macro because it is the only one created in this schema: => SELECT * FROM user_functions; -[ RECORD 1 ]----------+--------------------------------------------------schema_name | public function_name | myzeroifnull procedure_type | User Defined Function function_return_type | Integer function_argument_type | x Integer function_definition | RETURN CASE WHEN (x IS NOT NULL) THEN x ELSE 0 END volatility | immutable is_strict | f is_fenced | f comment | See Also l CREATE FUNCTION (SQL Functions) l ALTER FUNCTION l DROP FUNCTION USER_PROCEDURES Provides information about external procedures that have been defined for HP Vertica. User see only the procedures they can execute. HP Vertica Analytic Database (7.0.x) Page 1350 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PROCEDURE_NAME VARCHAR The name given to the external procedure through the CREATE PROCEDURE statement. PROCEDURE_ARGUMENTS VARCHAR Lists arguments for the external procedure. SCHEMA_NAME VARCHAR Indicates the schema in which the external procedure is defined. Example => SELECT * FROM user_procedures; procedure_name | procedure_arguments | schema_name ----------------+---------------------+------------helloplanet | arg1 Varchar | public (1 row) USER_TRANSFORMS Lists the currently-defined User Defined Transform Functions (UDTFs). Column Name Data Type Description SCHEMA_NAME VARCHAR (128) The name of the schema containing the UDTF. FUNCTION_ NAME VARCHAR (128) The SQL function name assigned by the user. FUNCTION_ RETURN_TYPE VARCHAR (128) The data types of the columns the UDTF returns. FUNCTION_ ARGUMENT_ TYPE VARCHAR (8192) The data types of the columns that make up the input row. FUNCTION_ DEFINITION VARCHAR (128) A string containing the name of the factory class for the UDTF, and the name of the library that contains it. IS_FENCED BOOLEAN Whether the UDTF runs in fenced mode. Permissions No explicit permissions are required; however, users see only UDTFs contained in schemas to which they have read access. HP Vertica Analytic Database (7.0.x) Page 1351 of 1539 SQL Reference Manual HP Vertica System Tables See Also l Developing a User Defined Transform Function in C++ and Developing a User Defined Transform Function in Java in the Programmer's Guide. l CREATE TRANSFORM FUNCTION USERS Provides information about all users in the database. Column Name Data Type Description USER_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the user. USER_NAME VARCHAR The user name for which information is listed. IS_SUPER_USER BOOLEAN Indicates whether the current user is superuser, where t is true and f is false. PROFILE_NAME VARCHAR The name of the profile to which the user is assigned. The profile controls the user's password policy. IS_LOCKED BOOLEAN Whether the user's account is locked. A locked user cannot log into the system. LOCK_TIME DATETIME When the user's account was locked. Used to determine when to automatically unlock the account, if the user's profile has a PASSWORD_LOCK_TIME parameter set. RESOURCE_POOL VARCHAR The resource pool to which the user is assigned. MEMORY_CAP_KB VARCHAR The maximum amount of memory a query run by the user can consume, in kilobytes. TEMP_SPACE_CAP_KB VARCHAR The maximum amount of temporary disk space a query run by the user can consume, in kilobytes. RUN_TIME_CAP VARCHAR The maximum amount of time any of the user's queries is allowed to run. ALL_ROLES VARCHAR Roles assigned to the user. An asterisk in ALL_ROLES output means role granted WITH ADMIN OPTION. See Database Roles in the Administrator's Guide. HP Vertica Analytic Database (7.0.x) Page 1352 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description DEFAULT_ROLES VARCHAR Default role(s) assigned to the user. An asterisk in DEFAULT_ ROLES output means role granted WITH ADMIN OPTION. See Default roles for database users in the Administrator's Guide. SEARCH_PATH VARCHAR Sets the default schema search path for the user. See Setting Schema Search Paths in the Administrator's Guide. Notes You can call the HAS_ROLE() function to see if a role has been assigned to a user. Example => \x Expanded display is on. => SELECT * FROM users; -[ RECORD 1 ]-----+--------------------------user_id | 45035996273704962 user_name | dbadmin is_super_user | t profile_name | default is_locked | f lock_time | resource_pool | general memory_cap_kb | unlimited temp_space_cap_kb | unlimited run_time_cap | unlimited all_roles | dbadmin*, pseudosuperuser* default_roles | dbadmin*, pseudosuperuser* search_path | "$user", public, v_catalog, v_monitor, v_internal -[ RECORD 2 ]-----+--------------------------user_id | 45035996273713664 user_name | Alice is_super_user | f profile_name | default is_locked | f lock_time | resource_pool | general memory_cap_kb | unlimited temp_space_cap_kb | unlimited run_time_cap | unlimited all_roles | logadmin default_roles | search_path | "$user", public, v_catalog, v_monitor, v_internal -[ RECORD 3 ]-----+--------------------------user_id | 45035996273714428 user_name | Bob is_super_user | f profile_name | default is_locked | f HP Vertica Analytic Database (7.0.x) Page 1353 of 1539 SQL Reference Manual HP Vertica System Tables lock_time resource_pool memory_cap_kb temp_space_cap_kb run_time_cap all_roles default_roles search_path | | | | | | | | general unlimited unlimited unlimited logadmin, commentor* "$user", public, v_catalog, v_monitor, v_internal Note: An asterisk in the output means role WITH ADMIN OPTION. See Also l GRANTS l HAS_ROLE l ROLES VIEW_COLUMNS Provides view attribute information. Column Name Data Type Description TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the view of the table. TABLE_SCHEMA VARCHAR The schema name for which information is listed. TABLE_NAME VARCHAR The table name for which information is listed. COLUMN_ID VARCHAR A unique VARCHAR ID, assigned by the HP Vertica catalog, that identifies a column in a table. COLUMN_NAME VARCHAR The column name for which information is listed. DATA_TYPE VARCHAR The data type of the column for which information is listed; for example, VARCHAR(128). DATA_TYPE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the data type. DATA_TYPE_LENGTH INTEGER The maximum allowable length for the data type. CHARACTER_MAXIMUM_LENGTH INTEGER The maximum allowable length for the column, valid for character types. NUMERIC_PRECISION INTEGER The number of significant decimal digits. HP Vertica Analytic Database (7.0.x) Page 1354 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NUMERIC_SCALE INTEGER The number of fractional digits. DATETIME_PRECISION INTEGER For TIMESTAMP data type, returns the declared precision; returns null if no precision was declared. INTERVAL_PRECISION INTEGER The number of fractional digits retained in the seconds field. ORDINAL_POSITION INTEGER The position of the column respective to other columns. Notes A warning like the following means only that view had its associated table dropped. The view is not returned by the SELECT * FROM view_columns command, and the warning is returned merely to notify users about an orphaned view. WARNING: invalid view v: relation "public.t" does not exist Example NULL fields in the results indicate that those columns were not defined. For example, given the following table, the result for the datetime_precision column is NULL because no precision was declared: => CREATE TABLE c (c TIMESTAMP); CREATE TABLE => SELECT table_name, column_id, column_name, datetime_precision FROM columns WHERE table_name = 'c'; table_name | column_id | column_name | datetime_precision ------------+---------------------+-------------+-------------------c | 45035996273720664-1 | c | (1 row) In the next statement, the datetime_precision column returns 4 because the precision was declared as 4 in the CREATE TABLE statement: => DROP TABLE c; => CREATE TABLE c (c TIMESTAMP(4)); CREATE TABLE => SELECT table_name, column_id, column_name, datetime_precision FROM columns WHERE table_name = 'c'; table_name | column_id | column_name | datetime_precision ------------+---------------------+-------------+-------------------c | 45035996273720700-1 | c | 4 (1 row) HP Vertica Analytic Database (7.0.x) Page 1355 of 1539 SQL Reference Manual HP Vertica System Tables See Also l VIEWS VIEWS Provides information about all views within the system. See Implementing Views for more information. Column Name Data Type Description TABLE_SCHEMA_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the schema of the table that the view references. TABLE_SCHEMA VARCHAR The name of the schema that contains the view. TABLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the view. TABLE_NAME VARCHAR The view name for which information is listed. OWNER_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the view owner. OWNER_NAME VARCHAR The name of the view owner. VIEW_DEFINITION VARCHAR The query that defines the view. IS_SYSTEM_VIEW BOOLEAN Indicates whether the table is a system view, where t is true and f is false. SYSTEM_VIEW_CREATOR VARCHAR The user name who created the view. CREATE_TIME TIMESTAMP The date/time the view was created. Example Query the VIEWS table: =>\pset expanded Expanded display is on. => SELECT * FROM VIEWS; -[ RECORD 1 ]-------+-----------------------------table_schema_id | 45035996273704976 table_schema | public table_id | 45035996273951536 table_name | testview owner_id | 45035996273704962 owner_name | dbadmin HP Vertica Analytic Database (7.0.x) Page 1356 of 1539 SQL Reference Manual HP Vertica System Tables view_definition is_system_view system_view_creator create_time | SELECT bar.x FROM public.bar | f | | 2013-01-14 12:02:03.244809-05 See Also l VIEW_COLUMNS HP Vertica Analytic Database (7.0.x) Page 1357 of 1539 SQL Reference Manual HP Vertica System Tables V_MONITOR Schema The system tables in this section reside in the v_monitor schema. These tables provide information about the health of the HP Vertica database. ACTIVE_EVENTS Returns all active events in the cluster. See Monitoring Events. Column Name Data Type Description NODE_NAME VARCHAR The node name where the event occurred. EVENT_CODE INTEGER A numeric ID that indicates the type of event. See Event Types for a list of event type codes. EVENT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the specific event. EVENT_SEVERITY VARCHAR The severity of the event from highest to lowest. These events are based on standard syslog severity types. l 0—Emergency l 1—Alert l 2—Critical l 3—Error l 4—Warning l 5—Notice l 6—Informational l 7—Debug EVENT_POSTED_TIMESTAMP TIMESTAMP The year, month, day, and time the event was reported. The time is posted in military time. EVENT_EXPIRATION VARCHAR The year, month, day, and time the event expire. The time is posted in military time. If the cause of the event is still active, the event is posted again. EVENT_CODE_DESCRIPTION VARCHAR A brief description of the event and details pertinent to the specific situation. HP Vertica Analytic Database (7.0.x) Page 1358 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description EVENT_PROBLEM_DESCRIPTION VARCHAR A generic description of the event. REPORTING_NODE VARCHAR The name of the node within the cluster that reported the event. EVENT_SENT_TO_CHANNELS VARCHAR The event logging mechanisms that are configured for HP Vertica. These can include vertica.log, (configured by default) syslog, and SNMP. EVENT_POSTED_COUNT INTEGER Tracks the number of times an event occurs. Rather than posting the same event multiple times, HP Vertica posts the event once and then counts the number of additional instances in which the event occurs. Example Query the ACTIVE_EVENTS table: =>\pset expanded Expanded display is on. => SELECT * FROM active_events; -[ RECORD 1 ]-------------+----------------------------------------node_name | site01 event_code | 6 event_id | 6 event_severity | Informational is_event_posted | 2009-08-11 09:38:39.008458 event_expiration | 2077-08-29 11:52:46.008458 event_code_description | Node State Change event_problem_description | Changing node site01 startup state to UP reporting_node | site01 event_sent_to_channels | Vertica Log event_posted_count | 1 -[ RECORD 2 ]-------------+----------------------------------------node_name | site02 event_code | 6 event_id | 6 event_severity | Informational is_event_posted | 2009-08-11 09:38:39.018172 event_expiration | 2077-08-29 11:52:46.018172 event_code_description | Node State Change event_problem_description | Changing node site02 startup state to UP reporting_node | site02 event_sent_to_channels | Vertica Log event_posted_count | 1 -[ RECORD 3 ]-------------+----------------------------------------current_timestamp | 2009-08-11 14:38:48.859987 node_name | site03 event_code | 6 event_id | 6 event_severity | Informational HP Vertica Analytic Database (7.0.x) Page 1359 of 1539 SQL Reference Manual HP Vertica System Tables is_event_posted | 2009-08-11 09:38:39.027258 event_expiration | 2077-08-29 11:52:46.027258 event_code_description | Node State Change event_problem_description | Changing node site03 startup state to UP reporting_node | site03 event_sent_to_channels | Vertica Log event_posted_count | 1 -[ RECORD 4 ]-------------+----------------------------------------node_name | site04 event_code | 6 event_id | 6 event_severity | Informational is_event_posted | 2009-08-11 09:38:39.008288 event_expiration | 2077-08-29 11:52:46.008288 event_code_description | Node State Change event_problem_description | Changing node site04 startup state to UP reporting_node | site04 event_sent_to_channels | Vertica Log event_posted_count | 1 ... COLUMN_STORAGE Returns the amount of disk storage used by each column of each projection on each node. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. COLUMN_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the column. COLUMN_NAME VARCHAR The column name for which information is listed. ROW_COUNT INTEGER The number of rows in the column. USED_BYTES INTEGER The disk storage allocation of the column in bytes. ENCODINGS VARCHAR The encoding type for the column. COMPRESSION VARCHAR The compression type for the column. WOS_ROW_COUNT INTEGER The number of WOS rows in the column. ROS_ROW_COUNT INTEGER The number of ROS rows in the column. ROS_USED_BYTES INTEGER The number of ROS bytes in the column. ROS_COUNT INTEGER The number of ROS containers. PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. HP Vertica Analytic Database (7.0.x) Page 1360 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PROJECTION_NAME VARCHAR The associated projection name for the column. PROJECTION_SCHEMA VARCHAR The name of the schema associated with the projection. ANCHOR_TABLE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the anchor table. ANCHOR_TABLE_NAME VARCHAR The associated table name. ANCHOR_TABLE_SCHEMA VARCHAR The associated table's schema name. ANCHOR_TABLE_COLUMN_ID VARCHAR A unique VARCHAR ID, assigned by the HP Vertica catalog, that identifies a column in a table. ANCHOR_TABLE_COLUMN_NAME VARCHAR The name of the anchor table. Notes l WOS data is stored by row, so per-column byte counts are not available. l The ENCODINGS and COMPRESSION columns let you compare how different encoding types affect column storage, when optimizing for compression. Example Query the COLUMN_STORAGE table: => \pset expanded Expanded display is on. => SELECT * FROM column_storage; -[ RECORD 1 ]------------+-------------------node_name | v_onenode_node0001 column_id | 45035996273718840 column_name | stock row_count | 1 used_bytes | 31 encodings | String compressions | lzo wos_row_count | 0 ros_row_count | 1 ros_used_bytes | 31 ros_count | 1 projection_id | 45035996273718838 projection_name | trades_p projection_schema | public anchor_table_id | 45035996273718836 anchor_table_name | trades anchor_table_schema | public anchor_table_column_id | 45035996273718836-1 anchor_table_column_name | stock HP Vertica Analytic Database (7.0.x) Page 1361 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 2 ]------------+-------------------node_name | v_onenode_node0001 column_id | 45035996273718842 column_name | bid row_count | 1 used_bytes | 68 encodings | Int_Delta compressions | lzo wos_row_count | 0 ros_row_count | 1 ros_used_bytes | 68 ros_count | 1 projection_id | 45035996273718838 projection_name | trades_p projection_schema | public anchor_table_id | 45035996273718836 anchor_table_name | trades anchor_table_schema | public anchor_table_column_id | 45035996273718836-2 anchor_table_column_name | bid -[ RECORD 3 ]------------+-------------------node_name | v_onenode_node0001 column_id | 45035996273718846 column_name | ask row_count | 1 used_bytes | 0 encodings | Uncompressed compressions | lzo wos_row_count | 0 ros_row_count | 1 ros_used_bytes | 0 ros_count | 1 projection_id | 45035996273718838 projection_name | trades_p projection_schema | public anchor_table_id | 45035996273718836 anchor_table_name | trades anchor_table_schema | public anchor_table_column_id | 45035996273718836-3 anchor_table_column_name | ask -[ RECORD 4 ]------------+-------------------node_name | v_onenode_node0001 column_id | 45035996273718848 column_name | epoch row_count | 1 used_bytes | 48 encodings | Int_Delta compressions | none wos_row_count | 0 ros_row_count | 1 ros_used_bytes | 48 ros_count | 1 projection_id | 45035996273718838 projection_name | trades_p projection_schema | public anchor_table_id | 45035996273718836 anchor_table_name | trades anchor_table_schema | public HP Vertica Analytic Database (7.0.x) Page 1362 of 1539 SQL Reference Manual HP Vertica System Tables anchor_table_column_id | 45035996273718836-4 anchor_table_column_name | Call specific columns from the COLUMN_STORAGE table: SELECT column_name, row_count, projection_name, anchor_table_name FROM column_storage WHERE node_name = 'site02' AND row_count = 1000; column_name | row_count | projection_name | anchor_table_name ----------------------+-----------+------------------------------+----------------------end_date | 1000 | online_page_dimension_site02 | online_page_dimension epoch | 1000 | online_page_dimension_site02 | online_page_dimension online_page_key | 1000 | online_page_dimension_site02 | online_page_dimension page_description | 1000 | online_page_dimension_site02 | online_page_dimension page_number | 1000 | online_page_dimension_site02 | online_page_dimension page_type | 1000 | online_page_dimension_site02 | online_page_dimension start_date | 1000 | online_page_dimension_site02 | online_page_dimension ad_media_name | 1000 | promotion_dimension_site02 | promotion_dimension ad_type | 1000 | promotion_dimension_site02 | promotion_dimension coupon_type | 1000 | promotion_dimension_site02 | promotion_dimension display_provider | 1000 | promotion_dimension_site02 | promotion_dimension display_type | 1000 | promotion_dimension_site02 | promotion_dimension epoch | 1000 | promotion_dimension_site02 | promotion_dimension price_reduction_type | 1000 | promotion_dimension_site02 | promotion_dimension promotion_begin_date | 1000 | promotion_dimension_site02 | promotion_dimension promotion_cost | 1000 | promotion_dimension_site02 | promotion_dimension promotion_end_date | 1000 | promotion_dimension_site02 | promotion_dimension promotion_key | 1000 | promotion_dimension_site02 | promotion_dimension promotion_media_type | 1000 | promotion_dimension_site02 | promotion_dimension promotion_name | 1000 | promotion_dimension_site02 | promotion_dimension 20 rows) CONFIGURATION_CHANGES Records the change history of system configuration parameters (V_ MONITOR.CONFIGURATION_PARAMETERS). This information is useful for identifying: l Who changed the configuration parameter value l When the configuration parameter was changed l Whether nonstandard settings were in effect in the past Column Name Data Type Description EVENT_TIMESTAMP TIMESTAMPTZ Time when the row was recorded. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_ID INTEGER Identifier of the user who changed configuration parameters. HP Vertica Analytic Database (7.0.x) Page 1363 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description USER_NAME VARCHAR Name of the user who changed configuration parameters at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. PARAMETER VARCHAR Name of the changed parameter. See Configuration Parameters in the Administrator's Guide for a detailed list of supported parameters. VALUE VARCHAR New value of the configuration parameter. Permissions Must be a superuser. Example => SELECT * FROM configuration_changes; event_timestamp | node_name | user_id | user_name | session_i d | parameter | value -------------------------------+-----------+-------------------+-----------+------------------+--------------------------------+------2011-09-16 14:40:31.575335-04 | e1 | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 0 2011-09-16 14:40:31.576015-04 | initiator | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 0 2011-09-16 14:40:31.576106-04 | e0 | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 0 2011-09-16 14:40:33.103278-04 | e0 | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 1 2011-09-16 14:40:33.10332-04 | e1 | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 1 2011-09-16 14:40:33.104521-04 | initiator | 45035996273704962 | smith | smthl-9010:0 xb2e | UseOnlyResilientRedistribution | 1 2011-09-16 14:51:59.884112-04 | e0 | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 0 2011-09-16 14:51:59.884519-04 | e1 | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 0 2011-09-16 14:51:59.884695-04 | initiator | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 0 2011-09-16 14:52:00.580423-04 | initiator | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 1 2011-09-16 14:52:00.580673-04 | e0 | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 1 2011-09-16 14:52:00.581464-04 | e1 | 45035996273704962 | smith | smthl-9010:0 x109d | UseOnlyResilientRedistribution | 1 (12 rows) HP Vertica Analytic Database (7.0.x) Page 1364 of 1539 SQL Reference Manual HP Vertica System Tables See Also l CONFIGURATION_PARAMETERS CONFIGURATION_PARAMETERS Provides information about configuration parameters currently in use by the system. Column Name Data Type Description NODE_NAME VARCHAR The node names on the cluster for which information is listed. PARAMETER_NAME VARCHAR The name of the configurable parameter. See Configuration Parameters in the Administrator's Guide for a detailed list of supported parameters. CURRENT_VALUE INTEGER The value of the current setting for the parameter. DEFAULT_VALUE INTEGER The default value for the parameter. CHANGE_UNDER_SUPPORT_GUIDANCE BOOLEAN A t (true) setting indicates parameters intended for Vertica's use only. CHANGE_REQUIRES_RESTART BOOLEAN Indicates whether the configuration change requires a restart, where t is true and f is false. DESCRIPTION VARCHAR A description of the parameter's purpose. Notes The CONFIGURATION_PARAMETERS table returns the following error in non-default locales: ERROR: ORDER BY is not supported with UNION/INTERSECT/EXCEPT in non-default locales HINT: Please move the UNION to a FROM clause subquery. See the SET LOCALE command for details. Example The following command returns all current configuration parameters in HP Vertica: => SELECT * FROM CONFIGURATION_PARAMETERS; HP Vertica Analytic Database (7.0.x) Page 1365 of 1539 SQL Reference Manual HP Vertica System Tables See Also l Configuration Parameters CPU_USAGE Records CPU usage history on the system. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. START_TIME TIMESTAMP Beginning of history interval. END_TIME TIMESTAMP End of history interval. AVERAGE_CPU_USAGE_PERCENT FLOAT Average CPU usage in percent of total CPU time (0100) during history interval Permissions Must be a superuser Example => SELECT * FROM cpu_usage; node_name | start_time | end_time | cpu_usage_pe rcent -----------+-------------------------------+-------------------------------+-----------------initiator | 2011-09-16 15:23:38.000703-04 | 2011-09-16 15:24:00.005645-04 | 34.49 initiator | 2011-09-16 15:24:00.005645-04 | 2011-09-16 15:25:00.002346-04 | 12.37 e0 | 2011-09-16 15:23:37.002957-04 | 2011-09-16 15:24:00.003022-04 | 35.35 e0 | 2011-09-16 15:24:00.003022-04 | 2011-09-16 15:25:00.004471-04 | 12.38 e1 | 2011-09-16 15:23:37.000871-04 | 2011-09-16 15:24:00.002474-04 | 35.37 e1 | 2011-09-16 15:24:00.002474-04 | 2011-09-16 15:25:00.002049-04 | 12.38 (6 rows) CRITICAL_HOSTS Lists the critical hosts whose failure would cause the database to become unsafe and force a shutdown. HP Vertica Analytic Database (7.0.x) Page 1366 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description HOST_NAME Name of a critical host. VARCHAR Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM critical_hosts; host_name -----------Host1 Host3 (2 rows) CRITICAL_NODES Lists the critical nodes whose failure would cause the database to become unsafe and force a shutdown. Column Name Date Type Description NODE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the node. NODE_NAME VARCHAR The name of a critical node. Example => SELECT * FROM v_monitor.critical_nodes; node_id | node_name -------------------+-------------------45035996273704980 | v_onenode_node0001 (1 row) CURRENT_SESSION Returns information about the current active session. You can use this table to find out the current session's sessionID and get the duration of the previously-run query. HP Vertica Analytic Database (7.0.x) Page 1367 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. USER_NAME VARCHAR The name used to log into the database or NULL if the session is internal. CLIENT_HOSTNAME VARCHAR The host name and port of the TCP socket from which the client connection was made; NULL if the session is internal CLIENT_PID INTEGER The process identifier of the client process that issued this connection. Note: Remember that the client process could be on a different machine than the server. LOGIN_TIMESTAMP TIMESTAMP The date and time the user logged into the database or when the internal session was created. This column can be useful for identifying sessions that have been left open and could be idle. SESSION_ID VARCHAR The identifier required to close or interrupt a session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. CLIENT_LABEL VARCHAR A user-specified label for the client connection that can be set when using ODBC. See Label in DSN Parameters in Programmer's Guide. TRANSACTION_START TIMESTAMP The date/time the current transaction started or NULL if no transaction is running. TRANSACTION_ID VARCHAR A string containing the hexadecimal representation of the transaction ID, if any; otherwise NULL. TRANSACTION_DESCRIPTION VARCHAR A description of the current transaction. HP Vertica Analytic Database (7.0.x) Page 1368 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type STATEMENT_START TIMESTAMP The date/time the current statement started execution, or NULL if no statement is running. STATEMENT_ID VARCHAR Unique numeric ID for the currentlyrunning statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. LAST_STATEMENT_DURATION_US INTEGER The duration of the last completed statement in microseconds. CURRENT_STATEMENT VARCHAR The currently-running statement, if any. NULL indicates that no statement is currently being processed. LAST_STATEMENT VARCHAR NULL if the user has just logged in; otherwise the currently running statement or the most recently completed statement. EXECUTION_ENGINE_PROFILING_CONFIGURATION VARCHAR Returns a value that indicates whether profiling is turned on. Results are: HP Vertica Analytic Database (7.0.x) Description l Empty when no profiling l 'Local' when profiling on for this session l 'Global' when on by default for all sessions l 'Local, Global' when on by default for all sessions and on for current session Page 1369 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description QUERY_PROFILING_CONFIGURATION VARCHAR Returns a value that indicates whether profiling is turned on. Results are: SESSION_PROFILING_CONFIGURATION CLIENT_TYPE VARCHAR VARCHAR l Empty when no profiling l 'Local' when profiling on for this session l 'Global' when on by default for all sessions l 'Local, Global' when on by default for all sessions and on for current session Returns a value that indicates whether profiling is turned on. Results are: l Empty when no profiling l 'Local' when profiling on for this session l 'Global' when on by default for all sessions l 'Local, Global' when on by default for all sessions and on for current session The type of client from which the connection was made. Possible client type values: l ADO.NET Driver l ODBC Driver l JDBC Driver l vsql CLIENT_VERSION VARCHAR Returns the client version. CLIENT_OS VARCHAR Returns the client operating system. HP Vertica Analytic Database (7.0.x) Page 1370 of 1539 SQL Reference Manual HP Vertica System Tables Notes l The default for profiling is ON ('1') for all sessions. Each session can turn profiling ON or OFF. l Profiling parameters (such as GlobalEEProfiling in the examples below) are set in the HP Vertica configuration file (vertica.conf). To turn profiling off, set the parameter to '0'. To turn profiling on, set the parameter to '1'. Examples Query the CURRENT_SESSION table: => SELECT * FROM CURRENT_SESSION; -[ RECORD 1 ]----------------------------+---------------------------------------node_name | v_vmartdb_node01 user_name | release client_hostname | xxx.x.x.x:xxxxx client_pid | 18082 login_timestamp | 2010-10-07 10:10:03.114863-04 session_id | myhost-17956:0x1d client_label | transaction_start | 2010-10-07 11:52:32.43386 transaction_id | 45035996273727909 transaction_description | user release (select * from passwords;) statement_start | 2010-10-07 12:30:42.444459 statement_id | 11 last_statement_duration_us | 85241 current_statement | SELECT * FROM CURRENT_SESSION; last_statement | SELECT * FROM CONFIGURATION_PARAMETERS; execution_engine_profiling_configuration | Local query_profiling_configuration | session_profiling_configuration | client_type | vsql client_version | 07.00.0000 client_os | Linux 2.6.18-308.el5 x86_64 Request specific columns from the table: => SELECT node_name, session_id, execution_engine_profiling_configuration FROM CURRENT_SESSION; node_name | session_id | execution_engine_profiling_configuration -----------+---------------------+-----------------------------------------site01 | myhost-17956:0x1d | Global (1 row) The sequence of commands in this example shows the use of disabling and enabling profiling for local and global sessions. This command disables EE profiling for query execution runs: => SELECT disable_profiling('EE'); HP Vertica Analytic Database (7.0.x) Page 1371 of 1539 SQL Reference Manual HP Vertica System Tables disable_profiling ----------------------EE Profiling Disabled (1 row) The following command sets the GlobalEEProfiling configuration parameter to 0, which turns off profiling: => SELECT set_config_parameter('GlobalEEProfiling', '0'); set_config_parameter ---------------------------Parameter set successfully (1 row) The following command tells you whether profiling is set to 'Local' or 'Global' or none: => SELECT execution_engine_profiling_configuration FROM CURRENT_SESSION; ee_profiling_config --------------------(1 row) Note: The result set is empty because profiling was turned off in the preceding example. This command now enables EE profiling for query execution runs: => SELECT enable_profiling('EE'); enable_profiling ---------------------EE Profiling Enabled (1 row) Now when you run a select on the CURRENT_SESSION table, you can see profiling is ON for the local session: => SELECT execution_engine_profiling_configuration FROM CURRENT_SESSION; ee_profiling_config --------------------Local (1 row) Now turn profiling on for all sessions by setting the GlobalEEProfiling configuration parameter to 1: => SELECT set_config_parameter('GlobalEEProfiling', '1'); set_config_parameter ---------------------------Parameter set successfully (1 row) Now when you run a select on the CURRENT_SESSION table, you can see profiling is ON for the local sessions, as well as for all sessions: HP Vertica Analytic Database (7.0.x) Page 1372 of 1539 SQL Reference Manual HP Vertica System Tables => SELECT execution_engine_profiling_configuration FROM CURRENT_SESSION; ee_profiling_config --------------------Local, Global (1 row) See Also l CLOSE_SESSION l CLOSE_ALL_SESSIONS l EXECUTION_ENGINE_PROFILES l QUERY_PROFILES l SESSION_PROFILES l SESSIONS DATA_COLLECTOR Shows the Data Collector components, their current retention policies, and statistics about how much data is retained and how much has been discarded for various reasons. The DATA_ COLLECTOR system table also calculates approximate collection rate, to aid in sizing calculations. Column Name Data Type Description NODE_NAME VARCHAR The node name on which information is retained. COMPONENT VARCHAR The name of the component and its policy. TABLE_NAME VARCHAR The data collector (dc) table name for which information is listed. DESCRIPTION VARCHAR A short description about the component. IN_DB_LOG BOOLEAN Denotes if monitoring information is retained in the db.log file. IN_VERTICA_LOG BOOLEAN Denotes if monitoring information is retained in the vertica.log file. MEMORY_BUFFER_SIZE_KB INTEGER The size of the memory buffer in kilobytes. DISK_SIZE_KB INTEGER The on-disk size of the table in kilobytes. HP Vertica Analytic Database (7.0.x) Page 1373 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description RECORD_TOO_BIG_ERRORS INTEGER A number that increments by one each time an error is thrown because data did not fit in memory (based on the data collector retention policy). LOST_BUFFERS INTEGER The number of buffers lost. LOST_RECORDS INTEGER The number of records lost. RETIRED_FILES INTEGER The number of retired files. RETIRED_RECORDS INTEGER The number of retired records. CURRENT_MEMORY_RECORDS INTEGER The current number of rows in memory. CURRENT_DISK_RECORDS INTEGER The current number of rows stored on disk. CURRENT_MEMORY_BYTES INTEGER Total current memory used in kilobytes. CURRENT_DISK_BYTES INTEGER Total current disk space used in kilobytes. FIRST_TIME TIMESTAMP Timestamp of the first record. LAST_TIME TIMESTAMP Timestamp of the last record KB_PER_DAY INTEGER Total kilobytes used per day. Notes l Data Collector is on by default, but you can turn it off if you need to. See Enabling and Disabling Data Collector in the Administrator's Guide. l You can configure monitoring information retention policies. See Data Collector Functions in this guide and Configuring Data Retention Policies in the Administrator's Guide. l Query the DATA_COLLECTOR system table for a list of all current component names; for example: => SELECT DISTINCT component, description FROM data_collector ORDER BY 1 ASC; Examples The following command, which queries all columns in the DATA_COLLECTOR system table, is truncated for brevity: => \x => SELECT * FROM data_collector; HP Vertica Analytic Database (7.0.x) Page 1374 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 1 ]----------+-------------------------------------------node_name | v_vmartdb_node0003 component | AllocationPoolStatistics table_name | dc_allocation_pool_statistics description | Information about global memory pools, ... in_db_log | f in_vertica_log | f memory_buffer_size_kb | 64 disk_size_kb | 256 record_too_big_errors | 0 lost_buffers | 0 lost_records | 0 retired_files | 150 retired_records | 66318 current_memory_records | 0 current_disk_records | 1582 current_memory_bytes | 0 current_disk_bytes | 234536 first_time | 2011-05-26 13:19:01.006121-04 last_time | 2011-05-26 13:25:36.004994-04 kb_per_day | 50014.1761771333 -[ RECORD 2 ]----------+-------------------------------------------node_name | v_vmartdb_node0003 component | AllocationPoolStatisticsBySecond table_name | dc_allocation_pool_statistics_by_second description | Information about global memory pools, ... in_db_log | f in_vertica_log | f memory_buffer_size_kb | 64 disk_size_kb | 256 record_too_big_errors | 0 lost_buffers | 0 lost_records | 0 retired_files | 648 retired_records | 66180 current_memory_records | 0 current_disk_records | 349 current_memory_bytes | 0 current_disk_bytes | 222742 first_time | 2011-05-26 13:24:09.002271-04 last_time | 2011-05-26 13:25:36.005041-04 kb_per_day | 214367.571703045 -[ RECORD 3 ]----------+-------------------------------------------... The following command returns all component names and their descriptions. This is a useful query if you want to change the retention policy for a particular component and don't remember its name: => SELECT DISTINCT component, description FROM data_collector ORDER BY 1 ASC; component | description ----------------------------------+-----------------------------------------------------------------AllocationPoolStatistics | Information about global memory pools ... AllocationPoolStatisticsByDay | Information about global memory pools, ... (historica l, by day) AllocationPoolStatisticsByHour | Information about global memory pools, ... HP Vertica Analytic Database (7.0.x) Page 1375 of 1539 SQL Reference Manual HP Vertica System Tables (historical, by hour) AllocationPoolStatisticsByMinute l, by minute) AllocationPoolStatisticsBySecond l, by second) AnalyzeStatistics Backups CatalogInfo CatalogInfoByDay CatalogInfoByHour CatalogInfoByMinute e) CatalogInfoBySecond d) ClientServerMessages l) sent ConfigurationChanges CpuAggregate CpuAggregateByDay CpuAggregateByHour CpuAggregateByMinute CpuAggregateBySecond CpuInfo CpuInfoByDay CpuInfoByHour CpuInfoByMinute CpuInfoBySecond DeploymentsCompleted DesignsCompleted DiskResourceRejections Errors ExecutionEngineEvents execution ExecutionEngineProfiles IoInfo IoInfoByDay IoInfoByHour IoInfoByMinute IoInfoBySecond LockAttempts LockReleases LockRequests LoginFailures MemoryInfo evel MemoryInfoByDay ical, by day) MemoryInfoByHour ical, by hour) MemoryInfoByMinute ical, by minute) MemoryInfoBySecond ical, by second) MonitoringEventsCleared MonitoringEventsPosted NetworkInfo NetworkInfoByDay cal, by day) HP Vertica Analytic Database (7.0.x) | Information about global memory pools, ... (historica | Information about global memory pools, ... (historica | | | | | | History of statistics collection Monitoring successful backups Catalog statistics and history Catalog statistics and history (historical, by day) Catalog statistics and history (historical, by hour) Catalog statistics and history (historical, by minut | Catalog statistics and history (historical, by secon | Client-Server Messages (Front End to Back End Protoco | | | | | | | | | | | | | | | | Changes to configuration parameters (vertica.conf) Aggregate CPU information Aggregate CPU information (historical, by day) Aggregate CPU information (historical, by hour) Aggregate CPU information (historical, by minute) Aggregate CPU information (historical, by second) CPU information CPU information (historical, by day) CPU information (historical, by hour) CPU information (historical, by minute) CPU information (historical, by second) History of designs deployed History of designs executed Disk Resource Rejection Records History of all errors+warnings encountered History of important events during local planning and | | | | | | | | | | | History of EE profiles Information about device IOs Information about device IOs (historical, by Information about device IOs (historical, by Information about device IOs (historical, by Information about device IOs (historical, by History of lock attempts (resolved requests) History of lock releases History of lock requests Failed login attempts Information about node memory allocation, at day) hour) minute) second) the OS l | Information about node memory allocation, ... (histor | Information about node memory allocation, ... (histor | Information about node memory allocation, ... (histor | Information about node memory allocation, ... (histor | | | | Monitoring events Monitoring events Network interface Network interface cleared posted information and statistics information and statistics (histori Page 1376 of 1539 SQL Reference Manual HP Vertica System Tables NetworkInfoByHour cal, by hour) NetworkInfoByMinute cal, by minute) NetworkInfoBySecond cal, by second) NodeState OptimizerEvents OptimizerStats ProcessInfo system limits ProcessInfoByDay ical, by day) ProcessInfoByHour ical, by hour) ProcessInfoByMinute ical, by minute) ProcessInfoBySecond ical, by second) ProjectionRecoveries ProjectionRefreshesCompleted ProjectionsUsed RebalancedSegments RequestsCompleted RequestsIssued RequestsRetried ResourceAcquisitions ResourceRejections ResourceReleases RosesCreated RosesDestroyed SessionEnds SessionStarts Signals Startups StorageInfo StorageInfoByDay l, by day) StorageInfoByHour l, by hour) StorageInfoByMinute l, by minute) StorageInfoBySecond l, by second) StorageLayerStatistics StorageLayerStatisticsByDay historical, by day) StorageLayerStatisticsByHour historical, by hour) StorageLayerStatisticsByMinute historical, by minute) StorageLayerStatisticsBySecond historical, by second) Test TransactionEnds TransactionStarts TuningAnalysis TuningRecommendations HP Vertica Analytic Database (7.0.x) | Network interface information and statistics (histori | Network interface information and statistics (histori | Network interface information and statistics (histori | | | | History of all node state changes History of important events during optimizer planning History of optimizer runtime statistics Information about vertica process memory, handles and | Information about vertica process memory, ... (histor | Information about vertica process memory, ... (histor | Information about vertica process memory, ... (histor | Information about vertica process memory, ... (histor | | | | | | | | | | | | | | | | | | Monitoring completed projection recoveries History of refreshed projections Projections used in each SQL request issued History of all segments rebalanced (EC) History of all SQL requests completed History of all SQL requests issued History of all SQL requests issued that were retried History of all resource acquisitions Resource Rejection Records History of all resource acquisition releases History of all ROS and DVROS created History of all ROS destroyed Sessions ended Sessions started History of process signals received History of all node startup events Storage information (Used and Free space) Storage information (Used and Free space) (historica | Storage information (Used and Free space) (historica | Storage information (Used and Free space) (historica | Storage information (Used and Free space) (historica | Statistics and history of storage and caching layer | Statistics and history of storage and caching layer ( | Statistics and history of storage and caching layer ( | Statistics and history of storage and caching layer ( | Statistics and history of storage and caching layer ( | | | | | For data collector infrastructure testing History of end transactions (commit or rollback) History of begin transactions Tuning analysis history in Workload Analyzer Tuning Recommendations in Workload Analyzer Page 1377 of 1539 SQL Reference Manual HP Vertica System Tables TupleMoverEvents Upgrades UserAudits (93 rows) | History of Tuple Mover activities | Monitoring catalog upgrades | History of user audits Related Topics l Data Collector Functions l Retaining Monitoring Information and How HP Vertica Calculates Database Size in the Administrator's Guide DATABASE_BACKUPS Lists historical information for each backup that successfully completed after running the vbr.py utility. This information is useful for determining whether to create a new backup before you advance the AHM. Because this system table displays historical information, its contents do not always reflect the current state of a backup repository. For example, if you delete a backup from a repository, the DATABASE_BACKUPS system table continues to display information about it. To monitor snapshot information while vbr.py is running, query the DATABASE_SNAPSHOTS system table. To list existing backups, run vbr.py as described in Viewing Backups in the Administrator's Guide. Column Name Data Type Description BACKUP_TIMESTAMP TIMESTAMP The timestamp of the backup. NODE_NAME VARCHAR The name local or remote backup host, as specified in the backupHost parameter of the vbr.py configuration file. SNAPSHOT_NAME VARCHAR The name of the backup, as specified in the snapshotName parameter of the vbr.py configuration file. BACKUP_EPOCH INTEGER The database epoch at which the backup was saved. NODE_COUNT INTEGER The number of nodes backed up in the completed backup, and as listed in the [Mappingn] sections of the configuration file. OBJECTS VARCHAR The name of the object(s) contained in an object-level backup. This column is empty if the record is for a full cluster backup. Permissions Must be a superuser. HP Vertica Analytic Database (7.0.x) Page 1378 of 1539 SQL Reference Manual HP Vertica System Tables Example VMart=> select * from v_monitor.database_backups; -[ RECORD 1 ]----+-----------------------------backup_timestamp | 2013-05-10 14:41:12.673381-04 node_name | v_vmart_node0003 snapshot_name | schemabak backup_epoch | 174 node_count | 3 objects | public, store, online_sales -[ RECORD 2 ]----+-----------------------------backup_timestamp | 2013-05-13 11:17:30.913176-04 node_name | v_vmart_node0003 snapshot_name | kantibak backup_epoch | 175 node_count | 3 objects | . . . -[ RECORD 15 ]---+-----------------------------backup_timestamp | 2013-05-16 07:20:18.585076-04 node_name | v_vmart_node0003 snapshot_name | table2bak backup_epoch | 180 node_count | 3 objects | test2 -[ RECORD 16 ]---+-----------------------------backup_timestamp | 2013-05-28 14:06:03.027673-04 node_name | v_vmart_node0003 snapshot_name | kantibak backup_epoch | 182 node_count | 3 objects | See Also l DATABASE_SNAPSHOTS DATABASE_CONNECTIONS Lists the connections that have been established to other databases for importing and exporting data. See Moving Data Between HP Vertica Databases in the Administrator's Guide. Column Name Data Type Description DATABASE VARCHAR The name of the connected database USERNAME VARCHAR The username used to create the connection HOST VARCHAR The host name used to create the connection HP Vertica Analytic Database (7.0.x) Page 1379 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description PORT VARCHAR The port number used to create the connection ISVALID BOOLEAN Whether the connection is still open and usable or not Example => CONNECT TO VERTICA vmart USER dbadmin PASSWORD '' ON '10.10.20.150',5433; CONNECT => SELECT * FROM DATABASE_CONNECTIONS; database | username | host | port | isvalid ----------+----------+--------------+------+--------vmart | dbadmin | 10.10.20.150 | 5433 | t (1 row) DATABASE_SNAPSHOTS Displays information about database snapshots. A snapshot is a special temporary image of the database, which vbr.py uses internally as part of creating a full or object-level backup. When vbr.py completes a backup, it deletes the associated snapshot and its entry in the database_ snapshots system table. To see historical data about successfully created backups, query the DATABASE_BACKUPS system table. To see existing backups, run vbr.py as described in Viewing Backups in the Administrator's Guide. Column Name Data Type Description NODE_NAME VARCHAR The name of the node where the snapshot will be stored, as specified in the backupHost parameter of the vbr.py configuration file. SNAPSHOT_NAME VARCHAR The name of the snapshot you specify in the vbr.py configuration file snapshotName parameter. IS_DURABLE_SNAPSHOT BOOLEAN Indicates the snapshot durability. This value is always set to t (true). TOTAL_SIZE_BYTES INTEGER The total size (in bytes) of the data being backed up. This value differs from the data storage size (STORAGE_ COST_BYTES), described next. STORAGE_COST_BYTES INTEGER The amount of disk space used for a snapshot, and which will be freed when vbr.py deletes it. This value can change over time. For example, the storage_cost_ bytes increases when storage is discarded from the database. ACQUISITION_TIMESTAMP TIMESTAMP The recorded time at which vbr.py will create the snapshot. HP Vertica Analytic Database (7.0.x) Page 1380 of 1539 SQL Reference Manual HP Vertica System Tables Example To monitor snapshot information during vbr.py execution: vmartdb=> SELECT * FROM database_snapshots; node_name | snapshot_name | is_durable_snapshot | total_size_bytes | storage_cost_bytes | acquisition_timestamp --------------------+---------------+---------------------+------------------+-------------------+-----------------------node0001 | mysnapshot | t | 116108615 | 5054638 | 2010-10-07 12:39:22-04 node0002 | mysnapshot | t | 116385001 | 5066175 | 2010-10-07 12:39:35-04 node0003 | mysnapshot | t | 116379703 | 505469 | 2010-10-07 12:38:00-04 node0004 | mysnapshot | t | 116354638 | 5043155 | 2010-10-07 12:36:10-04 (4 rows) See Also l DATABASE_BACKUPS DELETE_VECTORS Holds information on deleted rows to speed up the delete process. Column Name Data Type Description NODE_NAME VARCHAR The name of the node storing the deleted rows. SCHEMA_NAME VARCHAR The name of the schema where the deleted rows are located. PROJECTION_NAME VARCHAR The name of the projection where the deleted rows are located. STORAGE_TYPE VARCHAR The type of storage containing the delete vector (WOS or ROS). DV_OID INTEGER The unique numeric ID (OID) that identifies this delete vector. STORAGE_OID INTEGER The unique numeric ID (OID) that identifies the storage container that holds the delete vector. DELETED_ROW_COUNT INTEGER The number of rows deleted. USED_BYTES INTEGER The number of bytes used to store the deletion. START_EPOCH INTEGER The start epoch of the data in the delete vector. END_EPOCH INTEGER The end epoch of the data in the delete vector. HP Vertica Analytic Database (7.0.x) Page 1381 of 1539 SQL Reference Manual HP Vertica System Tables DEPLOY_STATUS Records the history of the Database Designer designs that have been deployed and their deployment steps. Column Name Data Type Description EVENT_TIME TIMESTAMP Time when the row recorded the event. USER_NAME VARCHAR Name of the user who deployed a design at the time HP Vertica recorded the session. DEPLOY_NAME VARCHAR Name the deployment, same as the userspecified design name. DEPLOY_STEP VARCHAR Steps in the design deployment. DEPLOY_STEP_STATUS VARCHAR Textual status description of the current step in the deploy process. DEPLOY_STEP_COMPLETE_PERCENT FLOAT Progress of current step in percentage (0–100). DEPLOY_COMPLETE_PERCENT FLOAT Progress of overall deployment in percentage (0– 100). ERROR_MESSAGE VARCHAR Error or warning message during deployment. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example The following example shows the content of the DEPLOY_STATUS for a Database Designer deployment executed by the DBADMIN user: => select * from v_monitor.deploy_status; event_time | user_name | deploy_name | deploy_step | deploy_step_status | deploy_st ep_complete_percent | deploy_complete_percent | error_message ---------------------+-----------+-------------+-------------------------------------+-------------------+------------------------------+-------------------------+-------------2012-02-14 10:33:14 | dbadmin | design1 | create_deployment | success | | | N/A 2012-02-14 10:33:14 | dbadmin | design1 | populate_deployment | started | | | N/A 2012-02-14 10:33:21 | dbadmin | design1 | populate_deployment | success | | | N/A 2012-02-14 10:33:21 | dbadmin | design1 | deployment_script | started | | | N/A 2012-02-14 10:33:23 | dbadmin | design1 | run_deployment | success | | | N/A 2012-02-14 10:33:23 | dbadmin | design1 | deployment_script | success | | | N/A 2012-02-14 10:33:24 | dbadmin | design1 | execute_deployment | started | | | N/A HP Vertica Analytic Database (7.0.x) Page 1382 of 1539 SQL Reference Manual HP Vertica System Tables 2012-02-14 10:33:26 0 | 0 | N/A 2012-02-14 10:33:27 2012-02-14 10:33:27 2012-02-14 10:33:43 100 | 11.11 | N/A 2012-02-14 10:33:43 | 100 | 22.22 | N/A 2012-02-14 10:33:43 100 | 33.33 | N/A 2012-02-14 10:33:43 100 | 37.04 | N/A 2012-02-14 10:33:43 100 | 38.89 | N/A 2012-02-14 10:33:43 100 | 40.74 | N/A 2012-02-14 10:33:43 100 | 51.85 | N/A 2012-02-14 10:33:43 100 | 53.7 | N/A 2012-02-14 10:33:43 100 | 55.56 | N/A 2012-02-14 10:33:44 2012-02-14 10:33:44 2012-02-14 10:33:56 100 | 77.78 | N/A 2012-02-14 10:33:56 100 | 100 | N/A 2012-02-14 10:33:56 2012-02-14 10:33:56 2012-02-14 10:33:57 2012-02-14 10:33:57 2012-02-14 10:33:57 ... | dbadmin | design1 | add: Dim_DBD_3_rep_ctx_design1 | complete | 10 | dbadmin | design1 | drop: Dim_b0 | complete | 100 | 0 | N/A | dbadmin | design1 | drop: Dim_b1 | complete | 100 | 0 | N/A | dbadmin | design1 | add: Fact1_DBD_11_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_12_seg_1_ctx_design1 | complete | dbadmin | design1 | add: Fact1_DBD_1_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_4_rep_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_5_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_6_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_7_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_8_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact1_DBD_9_seg_ctx_design1 | complete | | dbadmin | design1 | drop: Fact1_b0 | complete | 100 | 55.56 | N/A | dbadmin | design1 | drop: Fact1_b1 | complete | 100 | 55.56 | N/A | dbadmin | design1 | add: Fact2_DBD_10_seg_ctx_design1 | complete | | dbadmin | design1 | add: Fact2_DBD_2_seg_ctx_design1 | complete | | | | | | dbadmin dbadmin dbadmin dbadmin dbadmin | | | | | design1 design1 design1 design1 design1 | | | | | drop: Fact2_b0 | complete | 100 | 100 | N/A drop: Fact2_b1 | complete | 100 | 100 | N/A run_deployment | success | | | N/A execute_deployment | success | | | N/A deployment | completed | | | N/A DEPLOYMENT_PROJECTION_STATEMENTS Contains information about the CREATE PROJECTION statements used to deploy your design. Each row contains information about a different CREATE PROJECTION statement. Running DESIGNER_RUN_POPULATE_DESIGN_AND_DEPLOY populates this table. Column Name Column Type DEPLOYMENT_ID INTEGER Unique ID that Database Designer assigned to the deployment. DESIGN_NAME VARCHAR Unique name that the user assigned to the design. DEPLOYMENT_ PROJECTION_ID INTEGER Unique ID assigned to the output projection by Database Designer. HP Vertica Analytic Database (7.0.x) Description Page 1383 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Column Type STATEMENT_ID INTEGER Unique ID assigned to the statement type that creates the projection. STATEMENT VARCHAR Text for the statement that creates the projection. Description Query the DEPLOYMENT_PROJECTION_STATEMENTS table after deploying a design on the VMart database: => \x Expanded display is on. => SELECT * FROM DEPLOYMENT_PROJECTIONS_STATEMENTS; -[ RECORD 1 ]------------+-----------------------deployment_id | 45035996273708449 design_name | VMART_DESIGN deployment_projection_id | 1 statement_id | 1 statement | CREATE PROJECTION public.customer_dimension_DBD_1_rep_VMART_DE SIGN /*+createtype(D)*/ customer_key ENCODING DELTAVAL, customer_type ENCODING AUTO, customer_name ENCODING AUTO, customer_gender ENCODING AUTO, title ENCODING AUTO, household_id ENCODING DELTAVAL, customer_address ENCODING AUTO, customer_city ENCODING AUTO, customer_state ENCODING AUTO, customer_region ENCODING AUTO, marital_status ENCODING AUTO, customer_age ENCODING DELTAVAL, number_of_children ENCODING BLOCKDICT_COMP, annual_income ENCODING DELTARANGE_COMP, occupation ENCODING AUTO, largest_bill_amount ENCODING DELTAVAL, store_membership_card ENCODING BLOCKDICT_COMP, customer_since ENCODING AUTO, deal_stage ENCODING AUTO, deal_size ENCODING DELTARANGE_COMP, last_deal_update ENCODING DELTARANGE_COMP AS SELECT customer_key, customer_type, customer_name, customer_gender, title, household_id, customer_address, customer_city, customer_state, customer_region, marital_status, customer_age, number_of_children, HP Vertica Analytic Database (7.0.x) Page 1384 of 1539 SQL Reference Manual HP Vertica System Tables annual_income, occupation, largest_bill_amount, store_membership_card, customer_since, deal_stage, deal_size, last_deal_update FROM public.customer_dimension ORDER BY customer_gender, annual_income UNSEGMENTED ALL NODES; -[ RECORD 2 ]------------+-----------------------... DEPLOYMENT_PROJECTIONS Contains information about projections created and dropped during the design. Each row contains information about a different projection. Database Designer populates this table after the design has been deployed. Column Name Column Type deployment_id INTEGER Unique ID that Database Designerassigned to the deployment. deployment_projection_id INTEGER Unique ID that Database Designer assigned to the output projection. design_name VARCHAR Name of the design being deployed. deployment_projection_name VARCHAR Name that Database Designer assigned to the projection. anchor_table_schema VARCHAR Name of the schema that contains the table the projection is based on. anchor_table_name VARCHAR Name of the table the projection is based on. deployment_operation VARCHAR Action being taken on the projection, for example, add or drop. HP Vertica Analytic Database (7.0.x) Description Page 1385 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Column Type DEPLOYMENT_PROJECTION_TYPE VARCHAR Description Indicates whether has proposed new projections for this design (DBD) or is using the existing catalog design (CATALOG). The REENCODED suffix indicates that the projection sort order and segmentation are the same, but the projection columns have new encodings: l DBD l CATALOG l DBD_REENCODED l CATALOG_REENCODED DEPLOY_WEIGHT INTEGER Weight of this projection in creating the design. This field is always 0 for projections that have been dropped. ESTIMATED_SIZE_ON_DISK INTEGER Approximate size of the projection on disk, in MB. Example Query the DEPLOYMENT_PROJECTIONS table after deploying a design for the VMart database: => \x Expanded display is on. => SELECT * FROM DEPLOYMENT_PROJECTIONS; -[ RECORD 1 ]--------------+--------------------------------------------deployment_id | 45035996273708449 deployment_projection_id | 1 design_name | VMART_DESIGN deployment_projection_name | customer_dimension_DBD_1_rep_VMART_DESIGN anchor_table_schema | public anchor_table_name | customer_dimension deployment_operation | add deployment_projection_type | DBD deploy_weight | 1050000 estimated_size_on_disk | 2165897 -[ RECORD 2 ]--------------+--------------------------------------------deployment_id | 45035996273708449 deployment_projection_id | 2 design_name | VMART_DESIGN deployment_projection_name | product_dimension_DBD_2_rep_VMART_DESIGN anchor_table_schema | public anchor_table_name | product_dimension deployment_operation | add HP Vertica Analytic Database (7.0.x) Page 1386 of 1539 SQL Reference Manual HP Vertica System Tables deployment_projection_type | DBD deploy_weight | 1260000 estimated_size_on_disk | 2327964 -[ RECORD 3 ]--------------+--------------------------------------------deployment_id | 45035996273708449 deployment_projection_id | 3 design_name | VMART_DESIGN deployment_projection_name | product_dimension_DBD_3_rep_vmart_design anchor_table_schema | public anchor_table_name | product_dimension deployment_operation | add deployment_projection_type | DBD deploy_weight | 300000 estimated_size_on_disk | 1116277 ... -[ RECORD 13 ]-------------+--------------------------------------------deployment_id | 4503599628449 deployment_projection_id | 13 design_name | VMART_DESIGN deployment_projection_name | store_orders_fact_DBD_13_seg_VMART_DESIGN_b0 anchor_table_schema | store anchor_table_name | store_orders_fact deployment_operation | add deployment_projection_type | DBD_REENCODED deploy_weight | 5700000 estimated_size_on_disk | 9240800 -[ RECORD 14 ]-------------+----------------------------------------------deployment_id | 4503599628449 deployment_projection_id | 13 design_name | N/A deployment_projection_name | customer_dimension_super anchor_table_schema | public anchor_table_name | customer_dimension deployment_operation | drop deployment_projection_type | EXISTING deploy_weight | 0 estimated_size_on_disk | 2165897 ... DESIGN_QUERIES Contains info about design queries for a given design. The following functions populate this table: l DESIGNER_ADD_DESIGN_QUERIES l DESIGNER_ADD_DESIGN_QUERIES_FROM_RESULTS l DESIGNER_ADD_DESIGN_QUERY HP Vertica Analytic Database (7.0.x) Page 1387 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Column Type Description design_id INTEGER Unique id that Database Designer assigned to the design. design_name VARCHAR Name that you specified for the design. design_ query_id INTEGER Unique id that Database Designer assigned to the design query. design_ query_id_ index INTEGER Database Designer chunks the query text if it exceeds the maximum attribute size before storing it in this table. Database Designer stored all chunks stored under the same value of DESIGN_QUERY_ID. DESIGN_ QUERY_ID_INDEX keeps track of the order of the chunks, starting with 0 and ending in n, the index of the final chunk. query_text VARCHAR Text of the query chunk, or the entire query text if it does not exceed the maximum attribute size. weight FLOAT A value from 0 to 1 that indicates the importance of that query in creating the design. Assign a higher weight to queries that you run frequently so that Database Designer prioritizes those queries in creating the design. Default: 1. design_ query_ search_path VARCHAR The search path with which the query is to be parsed. design_ query_ signature INTEGER An INTEGER that categorizes queries that affect the design that Database Designer creates in the same way. Database Designer assigns a signature to each query, weights one query for each signature group, depending on how many queries there are with that signature, and Database Designer considers that query when creating the design. Example Add queries to VMART_DESIGN and query the DESIGN_QUERIES table: => SELECT DESIGNER_ADD_DESIGN_QUERIES('VMART_DESIGN', '/tmp/examples/vmart_queries.sql',' true'); DESIGNER_ADD_DESIGN_QUERIES ----------------------------Number of accepted queries =9 Number of queries referencing non-design tables =0 HP Vertica Analytic Database (7.0.x) Page 1388 of 1539 SQL Reference Manual HP Vertica System Tables Number of unsupported queries =0 Number of illegal queries =0 => \x Expanded display is on. => SELECT * FROM V_MONITOR.DESIGN.QUERIES -[ RECORD 1 ]------------+------------------design_id | 45035996273705090 design_name | vmart_design design_query_id | 1 design_query_id_index | 0 query_text | SELECT fat_content FROM ( SELECT DISTINCT fat_content FROM product_dimension WHERE department_description IN ('Dairy') ) AS food ORDER BY fat_content LIMIT 5; weight | 1 design_query_search_path | v_dbd_vmart_design_vmart_design_ltt, "$user", public, v_catalo g, v_monitor, v_internal design_query_signature | 45035996273724651 -[ RECORD 2]-------------+------------------design_query_id | 2 design_query_id_index | 0 query_text | SELECT order_number, date_ordered FROM store.store_orders_fact orders WHERE orders.store_key IN ( SELECT store_key FROM store.store_dimension WHERE store_state = 'MA') AND orders.vendor_key NOT IN ( SELECT vendor_key FROM public.vendor_dimension WHERE vendor_state = 'MA') AND date_ordered < '2003-03-01'; weight | 1 design_query_search_path | v_dbd_vmart_design_vmart_design_ltt, "$user", public, v_catalo g, v_monitor, v_internal design_query_signature | 45035996273724508 -[ RECORD 3]-------------+------------------... DESIGN_STATUS Records the progress of a running Database Designer design or history of the last Database Designer design executed by the current user. Column Name Data Type event_time TIMESTAMP Time when the row recorded the event. HP Vertica Analytic Database (7.0.x) Description Page 1389 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description user_name VARCHAR Name of the user who ran a design at the time HP Vertica recorded the session. design_name VARCHAR Name of the user-specified design. design_phase VARCHAR Phase of the design. phase_step VARCHAR Substep in each design phase phase_step_complete_percent FLOAT Progress of current substep in percentage (0– 100). phase_complete_percent FLOAT Progress of current design phase in percentage (0–100). Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example The following example shows the content of the DESIGN_STATUS table of a complete Database Designer run: => SELECT event_time, design_name, design_phase, phase_complete_percent FROM v_monitor.design_status; event_time | design_name | design_phase | phase_com plete_percent ---------------------+-------------+------------------------------------------------+----------------------2012-02-14 10:31:20 | design1 | Design started | 2012-02-14 10:31:21 | design1 | Design in progress: Analyze statistics phase | 2012-02-14 10:31:21 | design1 | Analyzing data statistics | 33.3 3 2012-02-14 10:31:22 | design1 | Analyzing data statistics | 66.6 7 2012-02-14 10:31:24 | design1 | Analyzing data statistics | 100 2012-02-14 10:31:25 | design1 | Design in progress: Query optimization phase | 2012-02-14 10:31:25 | design1 | Optimizing query performance | 37.5 2012-02-14 10:31:31 | design1 | Optimizing query performance | 62.5 2012-02-14 10:31:36 | design1 | Optimizing query performance | 75 2012-02-14 10:31:39 | design1 | Optimizing query performance | 87.5 2012-02-14 10:31:41 | design1 | Optimizing query performance | 87.5 2012-02-14 10:31:42 | design1 | Design in progress: Storage optimization phase | 2012-02-14 10:31:44 | design1 | Optimizing storage footprint | 4.17 2012-02-14 10:31:44 | design1 | Optimizing storage footprint | 16.6 7 2012-02-14 10:32:04 | design1 | Optimizing storage footprint | 29.1 7 HP Vertica Analytic Database (7.0.x) Page 1390 of 1539 SQL Reference Manual HP Vertica System Tables 2012-02-14 5 2012-02-14 3 2012-02-14 2 2012-02-14 2012-02-14 2012-02-14 2012-02-14 2012-02-14 2012-02-14 (24 rows) 10:32:04 | design1 | Optimizing storage footprint | 31.2 10:32:05 | design1 | Optimizing storage footprint | 33.3 10:32:05 | design1 | Optimizing storage footprint | 35.4 10:32:05 10:32:05 10:32:39 10:32:39 10:32:41 10:33:12 | | | | | | | | | | | | | | | | | | design1 design1 design1 design1 design1 design1 Optimizing storage footprint Optimizing storage footprint Optimizing storage footprint Optimizing storage footprint Optimizing storage footprint Design completed successfully 37.5 62.5 87.5 87.5 100 DESIGN_TABLES Contains information about all the design tables for all the designs for which you are the owner. Each row contains information about a different design table. Running DESIGNER_CREATE_ DESIGN creates this table in the V_MONITOR schema. Column Name Column Type Description design_name VARCHAR Unique name that the user specified for the design. design_table_ id INTEGER Unique ID that Database Designer assigned to the design table. table_schema VARCHAR Name of the schema that contains the design table. table_id INTEGER System object identifier (OID) assigned to the design table. table_name VARCHAR Name of the design table. Example Add all the tables from the VMart database to the design VMART_DESIGN. This operation populates the DESIGN_TABLES table: => SELECT DESIGNER_ADD_DESIGN_TABLES('VMART_DESIGN','online_sales.*'); DESIGNER_ADD_DESIGN_TABLES ---------------------------3 (1 row) => SELECT DESIGNER_ADD_DESIGN_TABLES('VMART_DESIGN','public.*'); DESIGNER_ADD_DESIGN_TABLES ---------------------------9 (1 row) => SELECT DESIGNER_ADD_DESIGN_TABLES('VMART_DESIGN','store.*'); DESIGNER_ADD_DESIGN_TABLES HP Vertica Analytic Database (7.0.x) Page 1391 of 1539 SQL Reference Manual HP Vertica System Tables ---------------------------3 (1 row) => SELECT * FROM DESIGN_TABLES; design_name | design_table_id | table_schema | table_id | table_name -------------+-----------------+--------------+-------------------+---------------------VMART_DESIGN | 1 | online_sales | 45035996373718754 | online_page_dimension VMART_DESIGN | 2 | online_sales | 45035996373718758 | call_center_dimension VMART_DESIGN | 3 | online_sales | 45035996373718762 | online_sales_fact VMART_DESIGN | 4 | public | 45035996373718766 | customer_dimension VMART_DESIGN | 5 | public | 45035996373718770 | product_dimension VMART_DESIGN | 6 | public | 45035996373718774 | promotion_dimension VMART_DESIGN | 7 | public | 45035996373718778 | date_dimension VMART_DESIGN | 8 | public | 45035996373718782 | vendor_dimension VMART_DESIGN | 9 | public | 45035996373718786 | employee_dimension VMART_DESIGN | 10 | public | 45035996373718822 | shipping_dimension VMART_DESIGN | 11 | public | 45035996373718826 | warehouse_dimension VMART_DESIGN | 12 | public | 45035996373718830 | inventory_face VMART_DESIGN | 13 | store | 45035996373718794 | store_dimension VMART_DESIGN | 14 | store | 45035996373718798 | store_sales_fact VMART_DESIGN | 15 | store | 45035996373718812 | store_orders_fact (15 rows) DESIGNS Contains information about a Database Designer design. After you create a design and specify certain parameters for Database Designer, DESIGNER_CREATE_DESIGN creates this table in the V_MONITOR schema. Column Name Column Type Description design_id INTEGER Unique ID that Database Designer assigns to this design. design_name VARCHAR Name that the user specifies for the design. ksafety_level INTEGER K-safety level for the design. Database Designer assigns a Ksafety value of 0 for clusters with 1 or 2 nodes, and assigns a value of 1 for clusters with 3 or more nodes. optimization_ objective VARCHAR Name of the optimization objective for the design. Valid values are: HP Vertica Analytic Database (7.0.x) l 'QUERY' l 'LOAD' l 'BALANCED' (Default) Page 1392 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Column Type Description design_type VARCHAR Name of the design type. Valid values are: l 'COMPREHENSIVE'(default) l 'INCREMENTAL' propose_ super_first BOOLEAN Specifies to propose superprojections before projections. 'f' by default. If DESIGN_MODE is 'COMPREHENSIVE', this field has no impact. design_ available BOOLEAN 't' if the design is currently available, otherwise, 'f' (the default). collected_ statistics BOOLEAN 't' if statistics are to be collected when creating the design, otherwise, 'f' (the default). populate_ design_ tables_from_ queries BOOLEAN 't' if you want to populate the design tables from the design queries, otherwise, 'f' (the default). encoding_ design BOOLEAN 't' if the design is an encoding optimization design on preexisting projections, otherwise, 'f' (the default). deployment_ parallelism INTEGER Number of tables to be deployed in parallel when the design is complete. Default: 0 propose_ unsegmented_ projections BOOLEAN 't' if you specify unsegmented projections, otherwise, 'f' (the default). analyze_ correlations_ mode INTEGER Specifies how Database Designer should handle existing column correlations in a design and whether or not Database Designer should reanalyze existing column correlations. HP Vertica Analytic Database (7.0.x) l 0—(Default) Ignore column correlations when creating the design. l 1—Consider the existing correlations in the tables when creating the design. l 2—Analyze column correlations if not previously performed, and consider the column correlations when creating the design. l 3—Analyze all column correlations in the tables and consider them when creating the design, even if they have been analyzed previously. Page 1393 of 1539 SQL Reference Manual HP Vertica System Tables Example View the record in the DESIGNS table that HP Vertica adds when you create a comprehensive design for the VMart database that you name VMART_DESIGN: => \x Expanded display is on. => SELECT * FROM DESIGNS; -[ RECORD 1 ]-----------------------+-----------------design_id | 45035996273705112 design_name | VMART_DESIGN ksafety_level | 0 optimization_objective | BALANCED design_type | COMPREHENSIVE propose_super_first | f design_available | f collected_statistics | f populate_design_tables_from_queries | f encoding_design | f deployment_parallelism | 0 propose_unsegmented_projections | t analyze_correlations_mode | 0 -[ RECORD 2 ]-----------------------+-----------------... DISK_RESOURCE_REJECTIONS Returns requests for resources that are rejected due to disk space shortages. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. RESOURCE_TYPE VARCHAR The resource request requester (example: Temp files). REJECTED_REASON VARCHAR One of 'Insufficient disk space' or 'Failed volume'. REJECTED_COUNT INTEGER Number of times this REJECTED_REASON has been given for this RESOURCE_TYPE. FIRST_REJECTED_TIMESTAMP TIMESTAMP The time of the first rejection for this REJECTED_ REASON and RESOURCE_TYPE. LAST_REJECTED_TIMESTAMP TIMESTAMP The time of the most recent rejection for this REJECTED_REASON and RESOURCE_TYPE. LAST_REJECTED_VALUE INTEGER HP Vertica Analytic Database (7.0.x) The value of the most recent rejection for this REJECTED_REASON and RESOURCE_TYPE. Page 1394 of 1539 SQL Reference Manual HP Vertica System Tables Notes Output is aggregated by both RESOURCE_TYPE and REJECTED_REASON to provide more comprehensive information. Example =>\pset expanded Expanded display on. => SELECT * FROM disk_resource_rejections; -[ RECORD 1 ]------------+--------------------------node_name | e0 resource_type | Table Data rejected_reason | Insufficient disk space rejected_count | 2 first_rejected_timestamp | 2009-10-16 15:55:16.336246 last_rejected_timestamp | 2009-10-16 15:55:16.336391 last_rejected_value | 1048576 -[ RECORD 2 ]------------+--------------------------node_name | e1 resource_type | Table Data rejected_reason | Insufficient disk space rejected_count | 2 first_rejected_timestamp | 2009-10-16 15:55:16.37908 last_rejected_timestamp | 2009-10-16 15:55:16.379207 last_rejected_value | 1048576 See Also l RESOURCE_REJECTIONS l CLEAR_RESOURCE_REJECTIONS DISK_STORAGE Returns the amount of disk storage used by the database on each node. Column Name Date Type Description NODE_NAME VARCHAR The node name for which information is listed. STORAGE_PATH VARCHAR The path where the storage location is mounted. HP Vertica Analytic Database (7.0.x) Page 1395 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Date Type Description STORAGE_USAGE VARCHAR The type of information stored in the location: l DATA: Only data is stored in the location. l TEMP: Only temporary files that are created during loads or queries are stored in the location. l DATA,TEMP: Both types of files are stored in the location. l USER: The storage location can be used by nondbadmin users, who are granted access to the storage location l CATALOG: The area is used for the HP Vertica catalog. This usage is set internally and cannot be removed or changed. RANK INTEGER The rank assigned to the storage location based on its performance. Ranks are used to create a storage locations on which projections, columns, and partitions are stored on different disks based on predicted or measured access patterns. See Creating and Configuring Storage Locations in the Administrator's Guide. THROUGHPUT INTEGER The measure of a storage location's performance in MB/sec. 1/throughput is the time taken to read 1MB of data. LATENCY INTEGER The measure of a storage location's performance in seeks/sec. 1/latency is the time taken to seek to the data. STORAGE_STATUS VARCHAR The status of the storage location: active or retired. DISK_BLOCK_SIZE_BYTES INTEGER The block size of the disk in bytes. DISK_SPACE_USED_BLOCKS INTEGER The number of disk blocks in use. DISK_SPACE_USED_MB INTEGER The number of megabytes of disk storage in use. DISK_SPACE_FREE_BLOCKS INTEGER The number of free disk blocks available. DISK_SPACE_FREE_MB INTEGER The number of megabytes of free storage available. DISK_SPACE_FREE_PERCENT INTEGER The percentage of free disk space remaining. HP Vertica Analytic Database (7.0.x) Page 1396 of 1539 SQL Reference Manual HP Vertica System Tables Notes l All values returned are in the context of the operating system's filesystems and are not specific to HP Vertica-specific space. l The storage usage annotation called CATALOG indicates the location is used to store the catalog. However, CATALOG location can only be specified when creating a new database and no new locations can be added as CATALOG locations using ADD_LOCATION. Existing CATALOG annotations cannot be removed. l A storage location's performance is measured in throughput in MB/sec and latency in seeks/sec. These two values are converted to single number(Speed) with the following formula: ReadTime (time to read 1MB) = 1/throughput + 1 / latency n 1/throughput is the time taken to read 1MB of data n 1/latency is the time taken to seek to the data. n ReadTime is the time taken to read 1MB of data. l A disk is faster than another disk if its ReadTime is less. l There can be multiple storage locations per node, and these locations can be on different disks with different free/used space, block size, etc. This information is useful in letting you know where the data files reside. Example Query the DISK_STORAGE table: =>\pset expanded Expanded display is on. => SELECT * FROM DISK_STORAGE; -[ RECORD 1 ]-----------+----------------------------current_timestamp | 2009-08-11 14:48:35.932541 node_name | site01 storage_path | /mydb/node01_catalog/Catalog storage_usage | CATALOG rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 34708721 disk_space_used_mb | 135581 disk_space_free_blocks | 178816678 disk_space_free_mb | 698502 disk_space_free_percent | 83% -[ RECORD 2 ]-----------+----------------------------current_timestamp | 2009-08-11 14:48:53.884255 HP Vertica Analytic Database (7.0.x) Page 1397 of 1539 SQL Reference Manual HP Vertica System Tables node_name | site01 storage_path | /mydb/node01_data storage_usage | DATA,TEMP rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 34708721 disk_space_used_mb | 135581 disk_space_free_blocks | 178816678 disk_space_free_mb | 698502 disk_space_free_percent | 83% -[ RECORD 3 ]-----------+----------------------------current_timestamp | 2009-08-11 14:49:08.299012 node_name | site02 storage_path | /mydb/node02_catalog/Catalog storage_usage | CATALOG rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19968349 disk_space_used_mb | 78001 disk_space_free_blocks | 193557050 disk_space_free_mb | 756082 disk_space_free_percent | 90% -[ RECORD 4 ]-----------+----------------------------current_timestamp | 2009-08-11 14:49:22.696772 node_name | site02 storage_path | /mydb/node02_data storage_usage | DATA,TEMP rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19968349 disk_space_used_mb | 78001 disk_space_free_blocks | 193557050 disk_space_free_mb | 756082 disk_space_free_percent | 90% -[ RECORD 5 ]-----------+----------------------------current_timestamp | 2009-08-11 14:50:03.960157 node_name | site03 storage_path | /mydb/node03_catalog/Catalog storage_usage | CATALOG rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19902595 disk_space_used_mb | 77744 disk_space_free_blocks | 193622804 disk_space_free_mb | 756339 disk_space_free_percent | 90% HP Vertica Analytic Database (7.0.x) Page 1398 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 6 ]-----------+----------------------------current_timestamp | 2009-08-11 14:50:27.415735 node_name | site03 storage_path | /mydb/node03_data storage_usage | DATA,TEMP rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19902595 disk_space_used_mb | 77744 disk_space_free_blocks | 193622804 disk_space_free_mb | 756339 disk_space_free_percent | 90% -[ RECORD 7 ]-----------+----------------------------current_timestamp | 2009-08-11 14:50:39.398879 node_name | site04 storage_path | /mydb/node04_catalog/Catalog storage_usage | CATALOG rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19972309 disk_space_used_mb | 78017 disk_space_free_blocks | 193553090 disk_space_free_mb | 756066 disk_space_free_percent | 90% -[ RECORD 8 ]-----------+----------------------------current_timestamp | 2009-08-11 14:50:57.879302 node_name | site04 storage_path | /mydb/node04_data storage_usage | DATA,TEMP rank | 0 throughput | 0 latency | 0 storage_status | Active disk_block_size_bytes | 4096 disk_space_used_blocks | 19972309 disk_space_used_mb | 78017 disk_space_free_blocks | 193553090 disk_space_free_mb | 756066 disk_space_free_percent | 90% Request only specific columns from the table: => SELECT node_name, storage_path, storage_status, disk_space_free_percent FROM disk_storage; node_name | storage_path | storage_status | disk_space_free_percent -----------+------------------------------+----------------+------------------------site01 | /mydb/node01_catalog/Catalog | Active | 83% site01 | /mydb/node01_data | Active | 83% site02 | /mydb/node02_catalog/Catalog | Active | 90% site02 | /mydb/node02_data | Active | 90% HP Vertica Analytic Database (7.0.x) Page 1399 of 1539 SQL Reference Manual HP Vertica System Tables site03 site03 site04 site04 (8 rows) | | | | /mydb/node03_catalog/Catalog /mydb/node03_data /mydb/node04_catalog/Catalog /mydb/node04_data | | | | Active Active Active Active | | | | 90% 90% 90% 90% ERROR_MESSAGES Lists system error messages and warnings HP Vertica encounters while processing queries. Column Name Data Type Description EVENT_TIMESTAMP TIMESTAMPTZ Time when the row recorded the event. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_ID INTEGER Identifier of the user who received the error message. USER_NAME VARCHAR Name of the user who received the error message at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. REQUEST_ID INTEGER Unique identifier of the query request in the user session. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID, and REQUEST_ID uniquely identifies a statement within a session. HP Vertica Analytic Database (7.0.x) Page 1400 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ERROR_LEVEL Severity of the error, can be one of: VARCHAR l LOG l INFO l NOTICE l WARNING l ERROR l ROLLBACK l INTERNAL l FATAL l PANIC ERROR_CODE INTEGER Error code that HP Vertica reports. MESSAGE VARCHAR Textual output of the error message. DETAIL VARCHAR Additional information about the error message, in greater detail. HINT VARCHAR Actionable hint about the error. For example: HINT: Set the locale in this session to en_ US@collation=binary using the command "\locale en_US@collation=binary" Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Notes Some errors occur when no transaction is in progress, so the transaction identifier or statement identifier columns could return NULL. Example => SELECT event_timestamp, statement_id, error_level, message FROM error_messages; event_timestamp | statement_id | error_level | message HP Vertica Analytic Database (7.0.x) Page 1401 of 1539 SQL Reference Manual HP Vertica System Tables -------------------------------+--------------+-------------+----------------------------------------------2012-03-30 17:52:12.326927-04 | -1 | FATAL | Client canceled session ras ter-s1-10295:0x225b 2012-03-30 17:42:12.249989-04 | 20 | ERROR | Syntax error at or near "na me" 2012-03-30 17:42:07.018451-04 | -1 | FATAL | Client canceled session ras ter-s1-10295:0x225b 2012-03-30 17:40:22.665446-04 | 17 | ERROR | Execution canceled by opera tor 2012-03-30 16:32:38.784384-04 | 11 | ERROR | Relation "systm_tables" doe s not exist 2012-03-30 16:26:51.072655-04 | 98 | ERROR | Relation "rebalance_project ions" does not exist 2012-03-30 14:31:09.953241-04 | -1 | FATAL | Client canceled session ras ter-s1-10295:0x70 2012-03-30 14:26:06.655026-04 | 42 | ERROR | Syntax error at or near "co nstraint" 2012-03-30 11:48:22.30045-04 | 31 | ERROR | Column "UDX" does not exist 2012-03-30 11:21:14.659128-04 | 20 | ERROR | Invalid attnum 1 for ranget able entry t ... EVENT_CONFIGURATIONS Monitors the configuration of events. Column Name Date Type Description EVENT_ID VARCHAR The name of the event. EVENT_DELIVERY_CHANNELS VARCHAR The delivery channel on which the event occurred. Example => SELECT * FROM event_configurations; event_id | event_delivery_channels -------------------------------------------+------------------------Low Disk Space | Vertica Log, SNMP Trap Read Only File System | Vertica Log, SNMP Trap Loss Of K Safety | Vertica Log, SNMP Trap Current Fault Tolerance at Critical Level | Vertica Log, SNMP Trap Too Many ROS Containers | Vertica Log, SNMP Trap WOS Over Flow | Vertica Log, SNMP Trap Node State Change | Vertica Log, SNMP Trap Recovery Failure | Vertica Log, SNMP Trap Recovery Error | Vertica Log Recovery Lock Error | Vertica Log Recovery Projection Retrieval Error | Vertica Log Refresh Error | Vertica Log Refresh Lock Error | Vertica Log Tuple Mover Error | Vertica Log HP Vertica Analytic Database (7.0.x) Page 1402 of 1539 SQL Reference Manual HP Vertica System Tables Timer Service Task Error Stale Checkpoint (16 rows) | Vertica Log | Vertica Log, SNMP Trap EXECUTION_ENGINE_PROFILES Provides profiling information about query execution runs. The hierarchy of IDs, from highest level to actual execution is: l PATH_ID l BASEPLAN_ID l LOCALPLAN_ID l OPERATOR_ID Counters (output from the COUNTER_NAME column) are collected for each actual Execution Engine (EE) operator instance. The following columns form a unique key for rows in the Data Collector table DC_EXECUTION_ ENGINE_EVENTS: l TRANSACTION_ID l STATEMENT_ID l NODE_NAME l OPERATOR_ID l COUNTER_NAME l COUNTER_TAG For additional details about profiling and debugging, see Profiling Database Performance in the Administrator's Guide. Column Name Data Type Description NODE_NAME VARCHAR Node name for which information is listed. USER_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the user. USER_NAME VARCHAR User name for which query profile information is listed. HP Vertica Analytic Database (7.0.x) Page 1403 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description SESSION_ID VARCHAR Identifier of the session for which profiling information is captured. This identifier is unique within the cluster at any point in time but can be reused when the session closes. TRANSACTION_ID INTEGER Identifier for the transaction within the session if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. OPERATOR_NAME VARCHAR Name of the Execution Engine (EE) component; for example, NetworkSend. OPERATOR_ID INTEGER Identifier assigned by the EE operator instance that performs the work. OPERATOR_ID is different from LOCALPLAN_ID because each logical operator, such as Scan, may be executed by multiple threads concurrently. Each thread operates on a different operator instance, which has its own ID. BASEPLAN_ID INTEGER Assigned by the optimizer on the initiator to EE operators in the original base (EXPLAIN) plan. Each EE operator in the base plan gets a unique ID. PATH_ID INTEGER Identifier that HP Vertica assigns to a query operation or path; for example to a logical grouping operation that might be performed by multiple execution engine operators. For each path, the same PATH ID is shared between the query plan (using EXPLAIN output) and in error messages that refer to joins. LOCALPLAN_ID INTEGER Identifier assigned by each local executor while preparing for plan execution (local planning). Some operators in the base plan, such as the Root operator, which is connected to the client, do not run on all nodes. Similarly, certain operators, such as ExprEval, are added and removed during local planning due to implementation details. ACTIVITY_ID INTEGER Identifier of the plan activity. RESOURCE_ID INTEGER Identifier of the plan resource. COUNTER_NAME VARCHAR Name of the counter. See the "COUNTER_NAME Values" section below this table. COUNTER_TAG VARCHAR String that uniquely identifies the counter for operators that might need to distinguish between different instances. For example, COUNTER_TAG is used to identify to which of the node bytes are being sent to or received from for the NetworkSend operator. HP Vertica Analytic Database (7.0.x) Page 1404 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description COUNTER_VALUE INTEGER Value of the counter. IS_EXECUTING BOOLEAN Indicates whether the profile is active or completed, where t is active and f is completed. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. COUNTER_NAME Values The value of COUNTER_NAME can be any of the following: COUNTER_NAME Description buffers spilled [NetworkSend] Buffers spilled to disk by NetworkSend. bytes received [NetworkRecv] The number of bytes received over the network for query execution. bytes read from cache [DataSource] The number of bytes read from HP Vertica cache when an EE DataSource operator is reading from ROS containers. bytes read from disk [DataSource] The number of bytes read from disk when an EE DataSource operator is reading from ROS containers. bytes sent [NetworkSend] Size of data after encoding and compression sent over the network (actual network bytes). HP Vertica Analytic Database (7.0.x) Page 1405 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description bytes spilled [NetworkSend] Bytes spilled to disk by NetworkSend. bytes total Only relevant to SendFiles operator (that is, recover-bycontainer plan) total number of bytes to send / receive. clock time (us) Real-time clock time spent processing the query, in microseconds. completed merge phases Number of merge phases already completed by an LSort or DataTarget operator. Compare to the total merge phases. Variants on this value include join inner completed merge phases. cumulative size of raw temp data (bytes) Total amount of temporary data the operator has written to files. Compare to cumulative size of temp files (bytes) to understand impact of encoding and compression in an externalizing operator. Variants on this value include join inner cumulative size of raw temp files (bytes). HP Vertica Analytic Database (7.0.x) Page 1406 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description cumulative size of temp files (bytes) For externalizing operators only, the total number of encoded and compressed temp data the operator has written to files. A sort operator might go through multiple merge phases, where at each pass sorted chunks of data are merged into fewer chunks. This counter remembers the cumulative size of all temp files past and present. Variants on this value include join inner cumulative size of temp files (bytes). current size of temp files (bytes) For externalizing operators only, the current size of the encoded and compressed temp data that the operator has written to files. Variants on this value include join inner current size of temp files (bytes). distinct value estimation time (µs) [Analyze Statistics] Time spent estimating the number of distinct values from the sample after data has been read off disk and into the statistical sample. encoded bytes received [NetworkRecv] Size of received data after decompressed (but still encoded) received over the network. HP Vertica Analytic Database (7.0.x) Page 1407 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description encoded bytes sent [NetworkSend] Size of data sent over the network after encoding. end time Time (timestamp) when HP Vertica stopped processing the operation estimated rows produced Number of rows that the optimizer estimated would be produced. See rows produced for the actual number of rows that are produced. execution time (us) CPU clock time spent processing the query, in microseconds. exceptions cumulative size of raw temp data (bytes) Counters that store total or current size of exception data. exceptions rows cumulative size of temp files (bytes) exceptions rows current size of temp files (bytes) files completed Relevant only to SendFiles/RecvFiles operators (that is, recover-by-container plan) number of files sent / received. files total Relevant only to SendFiles/RecvFiles operators (that is, recover-by-container plan) total number of files to send / receive. HP Vertica Analytic Database (7.0.x) Page 1408 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description histogram creation time(µs) [Analyze Statistics] Time spent estimating the number of distinct values from the sample after data has been read off disk and into the statistical sample. input queue wait (µs) Time in microseconds that an operator spends waiting for upstream operators. input rows Actual number of rows that were read into the operator. input size (bytes) Total number of bytes of the Load operator's input source, where NULL is unknown (read from FIFO). join inner completed mergephases See the completed merge phases counter. join inner cumulative size of raw temp data (bytes) join inner cumulative size of temp files (bytes) join inner current size of temp files (bytes) join inner total mergephases max sample size (rows) [Analyze Statistics] Maximum number of rows that will be stored in the statistical sample. network wait (µs) [NetworkSend, NetworkRecv] Time in microseconds spent waiting on the network. HP Vertica Analytic Database (7.0.x) Page 1409 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description output queue wait (µs) Time in microseconds that an operator spends waiting for the output buffer to be consumed by a downstream operator. producer stall (µs) [NetworkSend] Time in microseconds spent by NetworkSend when stalled waiting for network buffers to clear. producer wait (µs) [NetworkSend] Time in microseconds spent by the input operator making rows to send. read (bytes) Number of bytes read from the input source by the Load operator. receive time (µs) Time in microseconds that a Recv operator spends reading data from its socket. rejected data cumulative size of raw temp data (bytes) Counters that store total or current size of rejected row numbers. Are variants of: rejected data cumulative size of temp files (bytes) l cumulative size of raw temp data (bytes) l cumulative size of temp files (bytes) l current size of temp files (bytes) rejected data current size of temp files (bytes) rejected rows cumulative size of raw temp data (bytes) rejected rows cumulative size of temp files (bytes) rejected rows current size of temp files (bytes) HP Vertica Analytic Database (7.0.x) Page 1410 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description rle rows produced Number of physical tuples produced by an operator. Complements the rows produced counter, which shows the number of logical rows produced by an operator. For example, if a value occurs 1000 rows consecutively and is RLE encoded, it counts as 1000 rows produced not only 1 rle rows produced. ROS blocks bounded [DataTarget] Number of ROS blocks created, due to boundary alignment with RLE prefix columns, when an EE DataTarget operator is writing to ROS containers. ROS blocks encoded [DataTarget] Number of ros blocks created when an EE DataTarget operator is writing to ROS containers. ROS bytes written [DataTarget] Number of bytes written to disk when an EE DataTarget operator is writing to ROS containers. rows in sample [Analyze Statistics] Actual number of rows that will be stored in the statistical sample. HP Vertica Analytic Database (7.0.x) Page 1411 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description rows output by sort [DataTarget] Number of rows sorted when an EE DataTarget operator is writing to ROS containers. rows processed [DataSource] Number of rows processed when an EE DataSource operator is writing to ROS containers rows produced Number of logical rows produced by an operator. See also the rle rows produced counter. rows pruned by valindex [DataSource] Number of rows it skips direct scanning with help of valindex when an EE DataSource operator is writing to ROS containers. This counter's value is not greater than "rows processed" counter. rows received [NetworkRecv] Number of received sent over the network. rows rejected The number of rows rejected by the Load operator. rows sent [NetworkSend] Number of rows sent over the network. send time (µs) Time in microseconds that a Send operator spends writing data to its socket. HP Vertica Analytic Database (7.0.x) Page 1412 of 1539 SQL Reference Manual HP Vertica System Tables COUNTER_NAME Description start time Time (timestamp) when HP Vertica started to process the operation. total merge phases Number of merge phases an LSort or DataTarget operator must complete to finish sorting its data. NULL until the operator can compute this value (all data must first be ingested by the operator). Variants on this value include join inner total merge phases. wait clock time (µs) StorageUnion wait time in microseconds. WOS bytes acquired Number of bytes acquired from the WOS by a DataTarget operator. Note: This is usually more but can be less than WOS bytes written if an earlier statement in the transaction acquired some WOS memory. WOS bytes written Number of bytes written to the WOS by a DataTarget operator. written rows [DataTarget] Number of rows written when an EE DataTarget operator writes to ROS containers Examples The next two examples show the contents of the EXECUTION_ENGINE_PROFILES table: HP Vertica Analytic Database (7.0.x) Page 1413 of 1539 SQL Reference Manual HP Vertica System Tables => SELECT operator_name, operator_id, counter_name, counter_value FROM EXECUTION_ENGINE_PROFILES WHERE operator_name = 'Scan' ORDER BY counter_value DESC; operator_name | operator_id | counter_name | counter_value ---------------+-------------+--------------------------+----------------Scan | 12 | end time | 397916465478595 Scan | 9 | end time | 397916465478510 Scan | 12 | start time | 397916465462098 Scan | 9 | start time | 397916465447998 Scan | 14 | bytes read from disk | 28044535 Scan | 14 | bytes read from disk | 28030212 Scan | 12 | rows processed | 5000000 Scan | 12 | estimated rows produced | 4999999 Scan | 18 | rows produced | 1074828 Scan | 18 | rle rows produced | 1074828 Scan | 3 | memory allocated (bytes) | 1074568 Scan | 7 | rows produced | 799526 Scan | 7 | rle rows produced | 799526 Scan | 7 | memory allocated (bytes) | 682592 Scan | 12 | clock time (us) | 673806 Scan | 7 | execution time (us) | 545717 Scan | 3 | memory allocated (bytes) | 537400 Scan | 12 | clock time (us) | 505315 Scan | 14 | execution time (us) | 495176 Scan | 3 | bytes read from disk | 452403 Scan | 14 | execution time (us) | 420189 Scan | 12 | execution time (us) | 404184 Scan | 18 | clock time (us) | 398751 Scan | 18 | execution time (us) | 339321 (24 rows) => SELECT DISTINCT counter_name FROM execution_engine_profiles; counter_name ------------------------------------------------------end time clock time (us) rle rows produced bytes read from disk start time rows processed memory allocated (bytes) estimated rows produced rows produced execution time (us) (10 rows) The notable thing about the following query is the path_id column, which links the path that the query optimizer takes (via the EXPLAIN command's textual output) with join error messages. => SELECT operator_name, path_id, counter_name, counter_value FROM execution_engine_profiles; operator_name | path_id | counter_name | counter_value ---------------+---------+---------------------------+--------------Join | 1 | estimated rows produced | 10000 HP Vertica Analytic Database (7.0.x) Page 1414 of 1539 SQL Reference Manual HP Vertica System Tables Join Join Join Join Join Join Join | | | | | | | 1 1 1 1 1 1 1 | | | | | | | file handles memory allocated (bytes) memory reserved (bytes) rle rows produced rows produced clock time (us) execution time (us) | | | | | | | 0 2405824 1769472 3 3 24105 235 HOST_RESOURCES Provides a snapshot of the node. This is useful for regularly polling the node with automated tools or scripts. Column Name Data Type Description HOST_NAME VARCHAR The host name for which information is listed. OPEN_FILES_LIMIT INTEGER The maximum number of files that can be open at one time on the node. THREADS_LIMIT INTEGER The maximum number of threads that can coexist on the node. CORE_FILE_LIMIT_MAX_SIZE_BYTES INTEGER The maximum core file size allowed on the node. PROCESSOR_COUNT INTEGER The number of system processors. PROCESSOR_CORE_COUNT INTEGER The number of processor cores in the system. PROCESSOR_DESCRIPTION VARCHAR A description of the processor. For example: Inter(R) Core(TM)2 Duo CPU T8100 @2.10GHz (1 row) OPENED_FILE_COUNT INTEGER The total number of open files on the node. OPENED_SOCKET_COUNT INTEGER The total number of open sockets on the node. OPENED_NONFILE_NONSOCKET_COUNT INTEGER The total number of other file descriptions open in which 'other' could be a directory or FIFO. It is not an open file or socket. TOTAL_MEMORY_BYTES INTEGER The total amount of physical RAM, in bytes, available on the system. TOTAL_MEMORY_FREE_BYTES INTEGER The amount of physical RAM, in bytes, left unused by the system. TOTAL_BUFFER_MEMORY_BYTES INTEGER The amount of physical RAM, in bytes, used for file buffers on the system HP Vertica Analytic Database (7.0.x) Page 1415 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TOTAL_MEMORY_CACHE_BYTES INTEGER The amount of physical RAM, in bytes, used as cache memory on the system. TOTAL_SWAP_MEMORY_BYTES INTEGER The total amount of swap memory available, in bytes, on the system. TOTAL_SWAP_MEMORY_FREE_BYTES INTEGER The total amount of swap memory free, in bytes, on the system. DISK_SPACE_FREE_MB INTEGER The free disk space available, in megabytes, for all storage location file systems (data directories). DISK_SPACE_USED_MB INTEGER The disk space used, in megabytes, for all storage location file systems. DISK_SPACE_TOTAL_MB INTEGER The total free disk space available, in megabytes, for all storage location file systems. Examples Query the HOST_RESOURCES table: =>\pset expanded Expanded display is on. => SELECT * FROM HOST_RESOURCES; -[ RECORD 1 ]------------------+-------------------------------------host_name | myhost-s1 open_files_limit | 65536 threads_limit | 15914 core_file_limit_max_size_bytes | 1649680384 processor_count | 2 processor_core_count | 8 processor_description | Intel(R) Xeon(R) CPU E5504 @ 2.00GHz opened_file_count | 5 opened_socket_count | 4 opened_nonfile_nonsocket_count | 3 total_memory_bytes | 16687161344 total_memory_free_bytes | 4492627968 total_buffer_memory_bytes | 1613922304 total_memory_cache_bytes | 9349111808 total_swap_memory_bytes | 36502126592 total_swap_memory_free_bytes | 36411580416 disk_space_free_mb | 121972 disk_space_used_mb | 329235 disk_space_total_mb | 451207 -[ RECORD 2 ]------------------+-------------------------------------host_name | myhost-s2 open_files_limit | 65536 threads_limit | 15914 core_file_limit_max_size_bytes | 3772891136 processor_count | 2 HP Vertica Analytic Database (7.0.x) Page 1416 of 1539 SQL Reference Manual HP Vertica System Tables processor_core_count | 4 processor_description | Intel(R) Xeon(R) CPU E5504 @ 2.00GHz opened_file_count | 5 opened_socket_count | 3 opened_nonfile_nonsocket_count | 3 total_memory_bytes | 16687161344 total_memory_free_bytes | 9525706752 total_buffer_memory_bytes | 2840420352 total_memory_cache_bytes | 3060588544 total_swap_memory_bytes | 34330370048 total_swap_memory_free_bytes | 34184642560 disk_space_free_mb | 822190 disk_space_used_mb | 84255 disk_space_total_mb | 906445 -[ RECORD 3 ]------------------+-------------------------------------host_name | myhost-s3 open_files_limit | 65536 threads_limit | 15914 core_file_limit_max_size_bytes | 3758211072 processor_count | 2 processor_core_count | 4 processor_description | Intel(R) Xeon(R) CPU E5504 @ 2.00GHz opened_file_count | 5 opened_socket_count | 3 opened_nonfile_nonsocket_count | 3 total_memory_bytes | 16687161344 total_memory_free_bytes | 9718706176 total_buffer_memory_bytes | 2928369664 total_memory_cache_bytes | 2757115904 total_swap_memory_bytes | 34315689984 total_swap_memory_free_bytes | 34205523968 disk_space_free_mb | 820789 disk_space_used_mb | 85640 disk_space_total_mb | 906429 -[ RECORD 4 ]------------------+-------------------------------------host_name | myhost-s4 open_files_limit | 65536 threads_limit | 15914 core_file_limit_max_size_bytes | 3799433216 processor_count | 2 processor_core_count | 8 processor_description | Intel(R) Xeon(R) CPU E5504 @ 2.00GHz opened_file_count | 5 opened_socket_count | 3 opened_nonfile_nonsocket_count | 3 total_memory_bytes | 16687161344 total_memory_free_bytes | 8772620288 total_buffer_memory_bytes | 3792273408 total_memory_cache_bytes | 2831040512 total_swap_memory_bytes | 34356912128 total_swap_memory_free_bytes | 34282590208 disk_space_free_mb | 818896 disk_space_used_mb | 55291 disk_space_total_mb | 874187 HP Vertica Analytic Database (7.0.x) Page 1417 of 1539 SQL Reference Manual HP Vertica System Tables IO_USAGE Provides disk I/O bandwidth usage history for the system. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. START_TIME TIMESTAMP Beginning of history interval. END_TIME TIMESTAMP End of history interval. READ_KBYTES_PER_SEC FLOAT Counter history of the number of bytes read measured in kilobytes per second. WRITTEN_KBYTES_PER_SEC FLOAT Counter history of the number of bytes written measured in kilobytes per second. Permissions Must be a superuser. Example => SELECT * FROM io_usage; node_name | start_time | end_time | read_kbytes_ per_sec | written_kbytes_per_sec -----------+------------------------------+-------------------------------+--------------------+-----------------------initiator | 2011-09-16 15:23:38.003714-04 | 2011-09-16 15:24:00.015769-04 | 11.63 | 620.03 e0 | 2011-09-16 15:23:37.005431-04 | 2011-09-16 15:24:00.011519-04 | 11.13 | 593.24 initiator | 2011-09-16 15:24:00.015728-04 | 2011-09-16 15:25:00.015439-04 | 18.67 | 473.87 e1 | 2011-09-16 15:24:00.014491-04 | 2011-09-16 15:25:00.010432-04 | 18.67 | 473.9 e1 | 2011-09-16 15:23:37.006595-04 | 2011-09-16 15:24:00.014533-04 | 11.13 | 593.18 e0 | 2011-09-16 15:24:00.011478-04 | 2011-09-16 15:25:00.017536-04 | 18.66 | 473.82 (6 rows) LOAD_STREAMS Monitors active and historical load metrics for load streams on each node. This is useful for obtaining statistics about how many records got loaded and rejected from the previous load. HP HP Vertica Analytic Database (7.0.x) Page 1418 of 1539 SQL Reference Manual HP Vertica System Tables Vertica maintains system table metrics until they reach a designated size quota (in kilobytes). The quota is set through internal processes and cannot be set or viewed directly. Column Name Date Type Description SESSION_ID VARCHAR Identifier of the session for which HP Vertica captures load stream information. This identifier is unique within the cluster for the current session, but can be reused in a subsequent session. TRANSACTION_ID INTEGER Identifier for the transaction within a session. If a session is active but no transaction has begun, this is NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. STREAM_NAME VARCHAR Load stream identifier. If the user does not supply a specific name, the STREAM_NAME default value is: tablename-ID where tablename is the table into which data is being loaded, and ID is an integer value, guaranteed to be unique with the current session on a node. The LOAD_STREAMS system table includes stream names for every COPY statement that takes more than 1-second to run. The 1-second duration includes the time to plan and execute the statement. SCHEMA_NAME VARCHAR Schema name for which load stream information is listed. Lets you identify two streams that are targeted at tables with the same name in different schemas TABLE_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the table. TABLE_NAME VARCHAR Name of the table being loaded. LOAD_START VARCHAR Linux system time when the load started. LOAD_DURATION_MS NUMERIC (54,0) Duration of the load stream in milliseconds. IS_EXECUTING BOOLEAN Indicates whether the load is executing, where t is true and f is false. ACCEPTED_ROW_COUNT INTEGER Number of rows loaded. REJECTED_ROW_COUNT INTEGER Number of rows rejected. HP Vertica Analytic Database (7.0.x) Page 1419 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Date Type Description READ_BYTES INTEGER Number of bytes read from the input file. INPUT_FILE_SIZE_BYTES INTEGER Size of the input file in bytes. Note: When using STDIN as input, the input file size is zero (0). PARSE_COMPLETE_PERCENT INTEGER Percent of rows from the input file that have been loaded. UNSORTED_ROW_COUNT INTEGER Cumulative number rows not sorted across all projections. Note: UNSORTED_ROW_COUNT could be greater than ACCEPTED_ROW_COUNT because data is copied and sorted for every projection in the target table. SORTED_ROW_COUNT INTEGER Cumulative number of rows sorted across all projections. SORT_COMPLETE_PERCENT INTEGER Percent of rows from the input file that have been sorted. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. LOCK_USAGE Provides aggregate information about lock requests, releases, and attempts, such as wait time/count and hold time/count. HP Vertica records: l Lock attempts at the end of the locking process l Lock releases after locks attempts are released See also system table LOCKS. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information on which lock interaction occurs. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. OBJECT_NAME VARCHAR Name of object being locked; can be a table or an internal structure (projection, global catalog, or local catalog). HP Vertica Analytic Database (7.0.x) Page 1420 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description MODE VARCHAR Intended operations of the transaction: l S — Share lock needed for select operations. l I — Insert lock needed for insert operations. l SI — Share+Insert lock needed for operations that read and query the table. Distinguished from X because SI mode disallows delete/update operations. SI is also the result of lock promotion (see Table 2). l X — Exclusive lock is always needed for delete operations. X lock is also the result of lock promotion (see Table 2). l T — Tuple Mover lock used by the Tuple Mover and also used for COPY into pre-join projections. l U — Usage lock needed for moveout and mergeout operations in the first phase; they then upgrade their U lock to a T lock for the second phase. U locks conflicts with no other locks but O. l O — Owner lock needed for DROP_PARTITION, TRUNCATE TABLE, and ADD COLUMN. O locks conflict with all locks. O locks never promote. l NONE AVG_HOLD_TIME INTERVAL Average time (measured in intervals) that HP Vertica holds a lock. MAX_HOLD_TIME INTERVAL Maximum time (measured in intervals) that HP Vertica holds a lock. HOLD_COUNT INTEGER Total number of times lock was taken in the given mode. AVG_WAIT_TIME INTERVAL Average time (measured in intervals) that HP Vertica waits on the lock MAX_WAIT_TIME INTERVAL Maximum time (measured in intervals) that HP Vertica waits on a lock WAIT_COUNT INTEGER Total number of times lock was unavailable at the time it was first requested. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. HP Vertica Analytic Database (7.0.x) Page 1421 of 1539 SQL Reference Manual HP Vertica System Tables Example => SELECT * FROM lock_usage; -[ RECORD 1 ]-+---------------------------------node_name | v_myvdb_node0004 session_id | raster-f1.verticaco-13199:0x100 object_name | Global Catalog mode | S avg_hold_time | 00:00:00.032718 max_hold_time | 00:00:00.251213 hold_count | 34 avg_wait_time | 00:00:00.000048 max_wait_time | 00:00:00.000119 wait_count | 0 -[ RECORD 2 ]-+---------------------------------node_name | v_myvdb_node0004 session_id | raster-f1.verticaco-13199:0x102 object_name | Global Catalog mode | S avg_hold_time | 00:00:00.038148 max_hold_time | 00:00:00.185088 hold_count | 34 avg_wait_time | 00:00:00.000049 max_wait_time | 00:00:00.000124 wait_count | 0 -[ RECORD 3 ]-+---------------------------------node_name | v_myvdb_node0004 session_id | raster-f1.verticaco-13199:0x119 object_name | Table:public.dwdate mode | T avg_hold_time | 00:00:04.269108 max_hold_time | 00:00:04.269108 hold_count | 1 avg_wait_time | 00:00:00.000019 max_wait_time | 00:00:00.000019 wait_count | 0 -[ RECORD 4 ]-+---------------------------------node_name | v_myvdb_node0004 session_id | raster-f1.verticaco-13199:0x11d object_name | Global Catalog mode | X avg_hold_time | 00:00:00.027261 max_hold_time | 00:00:00.027261 hold_count | 1 avg_wait_time | 00:00:00.000038 max_wait_time | 00:00:00.000038 wait_count | 0 ... This example shows an INSERT lock in use: =>\pset expanded Expanded display is on. => SELECT * FROM LOCKS; -[ RECORD 1 ]-----------+--------------------------------------------------------- HP Vertica Analytic Database (7.0.x) Page 1422 of 1539 SQL Reference Manual HP Vertica System Tables node_names object_name object_id transaction_description | | | | lock_mode lock_scope request_timestamp grant_timestamp | | | | node01,node02,node03,node04 Table:fact 45035996273772278 Txn: a000000000112b 'COPY fact FROM '/data_dg/fact.dat' DELIMITER '|' NULL '\\N';' I TRANSACTION 2011-04-17 14:01:07.662325-04 2011-04-17 14:01:07.662325-04 See Also l DUMP_LOCKTABLE l LOCKS l PROJECTION_REFRESHES l SELECT l SESSION_PROFILES LOCKS Monitors lock grants and requests for all nodes. See also LOCK_USAGE for aggregate information about lock requests, releases, and attempts, such as wait time/count and hold time/count. Column Name Date Type Description NODE_NAMES VARCHAR Nodes on which lock interaction occurs. Note on node rollup: If a transaction has the same lock in the same mode in the same scope on multiple nodes, it gets one (1) line in the table. NODE_NAMES are separated by commas. OBJECT_NAME VARCHAR Name of object being locked; can be a table or an internal structure (projection, global catalog, or local catalog). OBJECT_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the object being locked. TRANSACTION_ID VARCHAR Identifier for the transaction within the session, if any; otherwise NULL. Useful for creating joins to other system tables. HP Vertica Analytic Database (7.0.x) Page 1423 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Date Type Description TRANSACTION_DESCRIPTION VARCHAR Identification of transaction and associated description, typically the query that caused the transaction's creation. LOCK_MODE VARCHAR Intended operation of the transaction: HP Vertica Analytic Database (7.0.x) l S — Share lock needed for select operations. Select operations in READ COMMITTED transaction mode do not require share (S) table locks. See Transactions in the Concepts Guide. l I — Insert lock needed for insert operations. l SI — Share+Insert lock needed for operations that read and query the table. Distinguished from X because SI mode disallows delete/update operations. SI is also the result of lock promotion (see Table 2). l X — Exclusive lock is always needed for delete operations. X lock is also the result of lock promotion (see Table 2). l T — Tuple Mover lock used by the Tuple Mover and also used for COPY into pre-join projections l U — Usage lock needed for moveout and mergeout operations in the first phase; they then upgrade their U lock to a T lock for the second phase. U locks conflicts with no other locks but O. l O — Owner lock needed for DROP_PARTITION, TRUNCATE TABLE, and ADD COLUMN. O locks conflict with all locks. O locks never promote. Page 1424 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Date Type Description LOCK_SCOPE VARCHAR Expected duration of the lock once it is granted. Before the lock is granted, the scope is listed as REQUESTED. Once a lock has been granted, the following scopes are possible: l STATEMENT_LOCALPLAN l STATEMENT_COMPILE l STATEMENT_EXECUTE l TRANSACTION_POSTCOMMIT l TRANSACTION All scopes, other than TRANSACTION, are transient and are used only as part of normal query processing. REQUEST_TIMESTAMP TIMESTAMP Time when the transaction started waiting on the lock. GRANT_TIMESTAMP TIMESTAMP Time the transaction acquired or upgraded the lock. Notes: l Return values are NULL until the grant occurs. l Values could be the same as REQUEST_ TIMESTAMP if the grant occurs immediately. Notes l Lock acquisition and wait times are collected and exposed via the START_TIMESTAMP column. l Locks acquired on tables that were subsequently dropped by another transaction can result in the message, Unknown or deleted object, appearing in the output's OBJECT column. l If a SELECT..FROM LOCKS query times out after five minutes, it is possible the cluster has failed. Run the Diagnostics Utility. l A table call with no results indicates that no locks are in use. Table 1: Lock compatibility matrix This table is for compatibility with other users. The table is symmetric. Granted Mode HP Vertica Analytic Database (7.0.x) Page 1425 of 1539 SQL Reference Manual HP Vertica System Tables Requested Mode S I SI X T U O S Yes No No No Yes Yes No I No Yes No No Yes Yes No SI No No No No Yes Yes No X No No No No No Yes No T Yes Yes Yes No Yes Yes No U Yes Yes Yes Yes Yes Yes No O No No No No No No No The following two examples refer to Table 1 above: l Example 1: If someone else has an S lock, you cannot get an I lock. l Example 2: If someone has an I lock, you can get an I lock. Table 2: Lock conversion matrix This table is used for upgrading locks you already have. For example, If you have an S lock and you want an I lock, you request an X lock. If you have an S lock and you want an S lock, no lock requests is required. Granted Mode Requested Mode S I SI X T U O S S SI SI X S S O I SI I I I O SI SI SI SI X SI SI O X X X X X X X O T S I SI X T T O U S I SI X T U O O O O O O O O O SI X Example This example shows an INSERT lock in use: =>\pset expanded HP Vertica Analytic Database (7.0.x) Page 1426 of 1539 SQL Reference Manual HP Vertica System Tables Expanded display is on. => SELECT * FROM LOCKS; -[ RECORD 1 ]-----------+--------------------------------------------------------node_names | node01,node02,node03,node04 object_name | Table:fact object_id | 45035996273772278 transaction_description | Txn: a000000000112b 'COPY fact FROM '/data_dg/fact.dat' DELIMITER '|' NULL '\\N';' lock_mode | I lock_scope | TRANSACTION request_timestamp | 2011-04-17 14:01:07.662325-04 grant_timestamp | 2011-04-17 14:01:07.662325-04 See Also l DUMP_LOCKTABLE l LOCK_USAGE l PROJECTION_REFRESHES l SELECT l SESSION_PROFILES LOGIN_FAILURES Lists failures for each user failed login attempt. This information is useful for determining if a user is having trouble getting into the database, as well as identifying a possible intrusion attempt. Column Name Data Type LOGIN_TIMESTAMP TIMESTAMPTZ Time when HP Vertica recorded the login. DATABASE_NAME VARCHAR The name of the database for the login attempt. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_NAME VARCHAR Name of the user whose login failed at the time HP Vertica recorded the session. CLIENT_HOSTNAME VARCHAR Host name and port of the TCP socket from which the client connection was made; NULL if the session is internal. HP Vertica Analytic Database (7.0.x) Description Page 1427 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_PID INTEGER Identifier of the client process that issued this connection. Note: The client process could be on a different machine from the server. CLIENT_VERSION VARCHAR Unused AUTHENTICATION_METHOD VARCHAR Determines whether the client application (or the user who is running the client application) is permitted to connect to the server using the database user name provided. HP Vertica supports the following client authentication methods: l Trust l Reject l Kerberos 5 l GSS l LDAP l Ident l Password See Implementing Client Authentication in the Administrator's Guide for details. REASON VARCHAR Description of login failure reason: l "INVALID USER" l "ACCOUNT LOCKED" l "REJECT" l "FAILED" l "INVALID AUTH METHOD" l "INVALID DATABASE" Permissions Must be a superuser.. HP Vertica Analytic Database (7.0.x) Page 1428 of 1539 SQL Reference Manual HP Vertica System Tables Example => SELECT login_timestamp, database_name, node_name, user_name, client_hostname, authentication_method, reason FROM login_failures; login_timestamp | database_name | node_name | user_name | client_hostname | au thentication_method | reason -------------------------------+---------------+-----------+-----------+----------------+-----------------------+-------------2012-03-25 13:38:56.54813-04 | smith | node01 | u1 | 127.0.0.1 | Password | FAILED 2012-03-25 13:38:56.543396-04 | smith | node01 | bad_user | 127.0.0.1 | Password | FAILED 2012-03-25 13:38:56.543225-04 | bad_user | node01 | bad_user | 127.0.0.1 | Reject | INVALID USER (3 rows) MEMORY_USAGE Records system resource history for memory usage. This is useful for comparing memory that HP Vertica uses versus memory in use by the entire system. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. START_TIME TIMESTAMP Beginning of history interval. END_TIME TIMESTAMP End of history interval. AVERAGE_MEMORY_USAGE_PERCENT FLOAT Records the average memory usage in percent of total memory (0-100) during the history interval. Permissions Must be a superuser. Example => SELECT * FROM memory_usage; node_name | start_time | end_time | average_memo ry_usage_percent -----------+-------------------------------+-------------------------------+------------- HP Vertica Analytic Database (7.0.x) Page 1429 of 1539 SQL Reference Manual HP Vertica System Tables ---------------initiator | 2012-03-25 50.39 initiator | 2012-03-25 51.08 e0 | 2012-03-25 50.3 e0 | 2012-03-25 51.08 e1 | 2012-03-25 50.3 e1 | 2012-03-25 51.08 (6 rows) 15:23:38.001952-04 | 2012-03-25 15:24:00.011432-04 | 15:24:00.011432-04 | 2012-03-25 15:25:00.008539-04 | 15:23:37.00339-04 | 2012-03-25 15:24:00.006837-04 | 15:24:00.006837-04 | 2012-03-25 15:25:00.011629-04 | 15:23:37.001344-04 | 2012-03-25 15:24:00.009634-04 | 15:24:00.009634-04 | 2012-03-25 15:25:00.005176-04 | MONITORING_EVENTS Reports significant events that can affect database performance and functionality if you do not address their root causes. See Monitoring Events in the Administrator's Guide for details. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. EVENT_CODE INTEGER Numeric identifier that indicates the type of event. See Event Types in Monitoring Events in the Administrator's Guide for a list of event type codes. EVENT_ID INTEGER Unique numeric ID that identifies the specific event. HP Vertica Analytic Database (7.0.x) Page 1430 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description EVENT_SEVERITY VARCHAR Severity of the event from highest to lowest. These events are based on standard syslog severity types: 0 – Emergency 1 – Alert 2 – Critical 3 – Error 4 – Warning 5 – Notice 6 – Info 7 – Debug EVENT_POSTED_TIMESTAMP TIMESTAMPTZ When this event was posted. EVENT_CLEARED_TIMESTAMP TIMESTAMPTZ When this event was cleared. Note: You can also query the ACTIVE_EVENTS system table to see events that have not been cleared. EVENT_EXPIRATION TIMESTAMPTZ Time at which this event expires. If the same event is posted again prior to its expiration time, this field gets updated to a new expiration time. EVENT_CODE_DESCRIPTION VARCHAR Brief description of the event and details pertinent to the specific situation. EVENT_PROBLEM_DESCRIPTION VARCHAR Generic description of the event. Permissions Must be a superuser. Notes For details about where HP Vertica posts events, see Monitoring in the Administrator's Guide Example -[ RECORD 1 ]-------------+--------------------------------------------------------------------------------------node_name | v_myvdb_node0001 HP Vertica Analytic Database (7.0.x) Page 1431 of 1539 SQL Reference Manual HP Vertica System Tables event_code | 0 event_id | 0 event_severity | Warning event_posted_timestamp | 2012-03-22 11:05:32.002682-04 event_cleared_timestamp | event_expiration | 2012-03-22 17:07:32.002681-04 event_code_description | Low Disk Space event_problem_description | Warning: Low disk space detected (80% in use) -[ RECORD 2 ]-------------+--------------------------------------------------------------------------------------node_name | v_myvdb_node0001 event_code | 6 event_id | 6 event_severity | Informational event_posted_timestamp | 2012-03-22 11:03:49.055705-04 event_cleared_timestamp | event_expiration | 2080-04-09 13:17:56.055704-05 event_code_description | Node State Change event_problem_description | Changing node v_myvdb_node0001 startup state to UP -[ RECORD 3 ]-------------+--------------------------------------------------------------------------------------node_name | v_myvdb_node0001 event_code | 6 event_id | 7 event_severity | Informational event_posted_timestamp | 2012-03-22 11:03:49.03912-04 event_cleared_timestamp | 2012-03-22 11:03:49.05626-04 event_expiration | 2080-04-09 13:17:56.039117-05 event_code_description | Node State Change event_problem_description | Changing node v_myvdb_node0001 startup state to REA DY -[ RECORD 4 ]-------------+--------------------------------------------------------------------------------------node_name | v_myvdb_node0001 event_code | 6 event_id | 8 event_severity | Informational event_posted_timestamp | 2012-03-12 10:26:16.731482-04 event_cleared_timestamp | event_expiration | 2080-03-30 12:40:23.731482-05 event_code_description | Node State Change event_problem_description | Changing node v_myvdb_node0001 startup state to SHU TDOWN ... See Also l ACTIVE_EVENTS NETWORK_INTERFACES Provides information about network interfaces on all HP Vertica nodes. HP Vertica Analytic Database (7.0.x) Page 1432 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_ID INTEGER Unique identifier for the node that recorded the row. NODE_NAME VARCHAR Name of the node that is reporting the requested information. INTERFACE VARCHAR Network interface name. IP_ADDRESS VARCHAR IP address for this interface. SUBNET VARCHAR IP subnet for this interface. MASK VARCHAR IP network mask for this interface. BROADCAST_ADDRESS VARCHAR IP broadcast address for this interface. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM network_interfaces; node_name | interface | ip_address | subnet | mask | broadcas t_address ------------------+-----------+----------------+--------------+---------------+-----------------v_gry22_node0001 | lo | 127.0.0.1 | 127.0.0.0 | 255.0.0.X | 127.0.0.1 v_gry22_node0001 | eth0 | 10.20.XX.XXX | 10.20.XX.X | 255.255.255.X | 10.20.XX. XXX v_gry22_node0001 | eth1 | 192.168.XX.XXX | 192.168.XX.0 | 255.255.255.X | 192.168.X X.XXX v_gry22_node0002 | lo | 127.0.0.1 | 127.0.0.0 | 255.0.0.0 | 127.0.0.1 v_gry22_node0002 | eth1 | 10.20.XX.XXX | 10.20.XX.X | 255.255.255.X | 10.20.XX. XXX v_gry22_node0002 | eth2 | 192.168.XX.XXX | 192.168.XX.0 | 255.255.255.X | 192.168.X X.XXX v_gry22_node0003 | lo | 127.0.0.1 | 127.0.0.0 | 255.0.0.X | 127.0.0.1 v_gry22_node0003 | eth1 | 10.20.XX.XXX | 10.20.XX.X | 255.255.255.X | 10.20.XX. XXX v_gry22_node0003 | eth2 | 192.168.XX.XXX | 192.168.XX.0 | 255.255.255.X | 192.168.X X.XXX v_gry22_node0004 | lo | 127.0.0.1 | 127.0.0.0 | 255.0.0.X | 127.0.0.1 v_gry22_node0004 | eth1 | 10.20.XX.XXX | 10.20.XX.X | 255.255.255.X | 10.20.XX. XXX v_gry22_node0004 | eth2 | 192.168.XX.XXX | 192.168.XX.0 | 255.255.255.0 | 192.168.X X.XXX (12 rows) HP Vertica Analytic Database (7.0.x) Page 1433 of 1539 SQL Reference Manual HP Vertica System Tables NETWORK_USAGE Provides network bandwidth usage history on the system. This is useful for determining if HP Vertica is using a large percentage of its available network bandwidth. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. START_TIME TIMESTAMP Beginning of history interval. END_TIME TIMESTAMP End of history interval. TX_KBYTES_PER_SEC FLOAT Counter history of outgoing (transmitting) usage in kilobytes per second. RX_KBYTES_PER_SEC FLOAT Counter history of incoming (receiving) usage in kilobytes per second. Permissions Must be a superuser. Example => SELECT node_name, start_time, end_time, tx_kbytes_per_sec AS tx_kb, rx_kbytes_per_sec AS rx_kb FROM network_usage; node_name | start_time | end_time | AS tx_kb | AS rx_kb ----------+-------------------------------+-------------------------------+----------+--------initiator | 2012-03-25 15:23:38.000834-04 | 2012-03-25 15:24:00.006087-04 | 0.22 | 0.86 e0 | 2012-03-25 15:23:37.003062-04 | 2012-03-25 15:24:00.003448-04 | 0.21 | 0.83 e1 | 2012-03-25 15:24:00.002963-04 | 2012-03-25 15:25:00.002497-04 | 0.81 | 0.45 e1 | 2012-03-25 15:23:37.000989-04 | 2012-03-25 15:24:00.002963-04 | 0.21 | 0.83 e0 | 2012-03-25 15:24:00.003448-04 | 2012-03-25 15:25:00.004897-04 | 0.81 | 0.45 initiator | 2012-03-25 15:24:00.006087-04 | 2012-03-25 15:25:00.007525-04 | 0.81 | 0.45 (6 rows) NODE_RESOURCES Provides a snapshot of the node. This is useful for regularly polling the node with automated tools or scripts. HP Vertica Analytic Database (7.0.x) Page 1434 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. HOST_NAME VARCHAR The hostname associated with a particular node. PROCESS_SIZE_BYTES INTEGER The total size of the program. PROCESS_RESIDENT_SET_SIZE_BYTES INTEGER The total number of pages that the process has in memory. PROCESS_SHARED_MEMORY_SIZE_BYTES INTEGER The amount of shared memory used. PROCESS_TEXT_MEMORY_SIZE_BYTES INTEGER The total number of text pages that the process has in physical memory. This does not include any shared libraries. PROCESS_DATA_MEMORY_SIZE_BYTES INTEGER The amount of physical memory, in pages, used for performing processes. This does not include the executable code. PROCESS_LIBRARY_MEMORY_SIZE_BYTES INTEGER The total number of library pages that the process has in physical memory. PROCESS_DIRTY_MEMORY_SIZE_BYTES INTEGER The number of pages that have been modified since they were last written to disk. Example Query the NODE_RESOURCES table: =>\pset expanded Expanded display is on. => SELECT * FROM NODE_RESOURCES; -[ RECORD 1 ]---------------------+------------------node_name | v_vmartdb_node01 host_name | myhost-s1 process_size_bytes | 2001829888 process_resident_set_size_bytes | 40964096 process_shared_memory_size_bytes | 16543744 process_text_memory_size_bytes | 46649344 process_data_memory_size_bytes | 0 process_library_memory_size_bytes | 1885351936 process_dirty_memory_size_bytes | 0 -[ RECORD 2 ]---------------------+------------------node_name | v_vmartdb_node02 host_name | myhost-s2 process_size_bytes | 399822848 process_resident_set_size_bytes | 31453184 process_shared_memory_size_bytes | 10862592 process_text_memory_size_bytes | 46649344 HP Vertica Analytic Database (7.0.x) Page 1435 of 1539 SQL Reference Manual HP Vertica System Tables process_data_memory_size_bytes | 0 process_library_memory_size_bytes | 299356160 process_dirty_memory_size_bytes | 0 -[ RECORD 3 ]---------------------+------------------node_name | v_vmartdb_node03 host_name | myhost-s3 process_size_bytes | 399822848 process_resident_set_size_bytes | 31100928 process_shared_memory_size_bytes | 10735616 process_text_memory_size_bytes | 46649344 process_data_memory_size_bytes | 0 process_library_memory_size_bytes | 299356160 process_dirty_memory_size_bytes | 0 -[ RECORD 4 ]---------------------+------------------node_name | v_vmartdb_node04 host_name | myhost-s4 process_size_bytes | 466923520 process_resident_set_size_bytes | 31309824 process_shared_memory_size_bytes | 10735616 process_text_memory_size_bytes | 46649344 process_data_memory_size_bytes | 0 process_library_memory_size_bytes | 366456832 process_dirty_memory_size_bytes | 0 NODE_STATES Monitors node recovery state-change history on the system. Column Name Data Type Description EVENT_TIMESTAMP TIMESTAMPTZ Time when HP Vertica recorded the event. NODE_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the node. NODE_NAME VARCHAR Name of the node that is reporting the requested information. NODE_STATE VARCHAR Shows the node's state. Can be one of: HP Vertica Analytic Database (7.0.x) l UP l READY l UNSAFE l SHUTDOWN l RECOVERING Page 1436 of 1539 SQL Reference Manual HP Vertica System Tables Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example Query the NODE_STATES table: => SELECT * FROM node_states; event_timestamp | node_id | node_name | node_state -------------------------------+-------------------+--------------------+-------------2012-12-09 06:36:22.10059-05 | 45035996273704980 | v_onenode_node0001 | UP 2012-12-09 06:36:22.10044-05 | 45035996273704980 | v_onenode_node0001 | READY 2012-12-09 06:36:22.081961-05 | 45035996273704980 | v_onenode_node0001 | INITIALIZING 2012-12-09 05:29:13.637828-05 | 45035996273704980 | v_onenode_node0001 | DOWN 2012-12-09 05:29:12.739187-05 | 45035996273704980 | v_onenode_node0001 | SHUTDOWN 2012-12-08 13:50:21.074688-05 | 45035996273704980 | v_onenode_node0001 | UP 2012-12-08 13:50:21.074544-05 | 45035996273704980 | v_onenode_node0001 | READY 2012-12-08 13:50:21.073529-05 | 45035996273704980 | v_onenode_node0001 | INITIALIZING (8 rows) OUTPUT_DEPLOYMENT_STATUS Contains information about the deployment status of all the projections in your design. Each row contains information about a different projection. Running DESIGNER_RUN_POPULATE_ DESIGN_AND_DEPLOY and deploying the design populates this table. Column Name Column Type deployment_id INTEGER Unique ID that Database Designer assigned to the deployment. design_name VARCHAR Unique name that the user assigned to the design. deployment_ projection_id INTEGER Unique ID that Database Designer assigned to the output projection. deployment_ projection_ name VARCHAR Name that Database Designer assigned to the output projection or the name of the projection to be dropped. HP Vertica Analytic Database (7.0.x) Description Page 1437 of 1539 SQL Reference Manual HP Vertica System Tables Column Name deployment_ status error_message Column Type Description VARCHAR Status of the deployment: VARCHAR l pending l complete l needs_refresh l in_progress l error Text of any error that occurred when creating or refreshing the specified projection. Example Query the OUTPUT_DEPLOYMENT_STATUS table after deploying a design on the VMart database: => \x Expanded display is on. => SELECT * FROM OUTPUT_DEPLOYMENT_STATUS; -[ RECORD 1 ]--------------+--------------------------------------------deployment_id | 45035996273708449 design_name | VMART_DESIGN deployment_projection_id | 1 deployment_projection_name | customer_dimension_DBD_1_rep_VMART_DESIGN deployment_status | complete error_message | N/A -[ RECORD 2 ]--------------+--------------------------------------------deployment_id | 45035996273708449 design_name | VMART_DESIGN deployment_projection_id | 2 deployment_projection_name | product_dimension_DBD_2_rep_VMART_DESIGN deployment_status | complete error_message | N/A -[ RECORD 3 ]--------------+--------------------------------------------deployment_id | 45035996273708449 design_name | VMART_DESIGN deployment_projection_id | 3 deployment_projection_name | product_dimension_DBD_3_rep_VMART_DESIGN deployment_status | complete error_message | N/A -[ RECORD 4 ]--------------+--------------------------------------------deployment_id | 45035996273708449 design_name | VMART_DESIGN deployment_projection_id | 4 deployment_projection_name | promotion_dimension_DBD_4_rep_VMART_DESIGN deployment_status | HP Vertica Analytic Database (7.0.x) Page 1438 of 1539 SQL Reference Manual HP Vertica System Tables error_message ... | N/A OUTPUT_EVENT_HISTORY Contains information about each stage that Database Designer performs to design and optimize your database design. Column Name Column Type TIME_STAMP TIMESTAMP Date and time of the specified stage. DESIGN_ID INTEGER Unique id that Database Designer assigned to the design. DESIGN_NAME VARCHAR Unique name that the user assigned to the design. STAGE_TYPE VARCHAR Design stage that Database Designer was working on at the time indicated by the TIME_STAMP field. Possible values include: Description l Design in progress l Analyzing data statistics l Optimizing query performance l Optimizing storage footprint l All done l Deployment in progress ITERATION_ NUMBER INTEGER Iteration number for the Optimizing query performance stage. TOTAL_QUERY_ COUNT INTEGER Total number of design queries in the design. REMAINING_ QUERY_COUNT INTEGER Number of design queries remaining for Database Designer to process. MAX_STEP_ NUMBER INTEGER Number of steps in the current stage. CURRENT_ STEP_NUMBER INTEGER Step in the current stage being processed at the time indicated by the TIME_STAMP field. HP Vertica Analytic Database (7.0.x) Page 1439 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Column Type CURRENT_ STEP_ DESCRIPTION VARCHAR TABLE_ID INTEGER HP Vertica Analytic Database (7.0.x) Description Name of the step that Database Designer is performing at that time indicated in the TIME_STAMP field. Possible values include: l Design with deployment started l Design in progress: Analyze statistics phase l design_table_name l projection_name l Design in progress: Query optimization phase l Extracting interesting columns l Enumerating sort orders l Setting up projection candidates l Assessing projection candidates l Choosing best projections l Calculating estimated benefit of best projections l Complete l Design in progress: Storage optimization phase l Design completed successfully l Setting up deployment metadata l Identifying projections to be dropped l Running deployment l Deployment completed successfully Unique id that Database Designer assigned to the design table. Page 1440 of 1539 SQL Reference Manual HP Vertica System Tables Example The following example shows the steps that Database Designer performs while optimizing the VMart example database: => SELECT DESIGNER_CREATE_DESIGN('VMART_DESIGN'); => SELECT DESIGNER_ADD_DESIGN_TABLES('VMART_DESIGN','public.*'); => SELECT DESIGNER_ADD_DESIGN_QUERIES('VMART_DESIGN','/tmp/examples/vmart_queries.sql',); ... => \x Expanded display is on. => SELECT * FROM OUTPUT_EVENT_HISTORY; -[ RECORD 1 ] -----------+---------------------------time_stamp | 2013-06-05 11:44:41.588 design_id | 45035996273705090 design_name | VMART_DESIGN stage_type | Design in progress iteration_number | total_query_count | remaining_query_count | max_step_number | current_step_number | current_step_description | Design with deployment started table id | -[ RECORD 2 ] -----------+---------------------------time_stamp | 2013-06-05 11:44:41.611 design_id | 45035996273705090 design_name | VMART_DESIGN stage_type | Design in progress iteration_number | total_query_count | remaining_query_count | max_step_number | current_step_number | current_step_description | Design in progress: Analyze statistics phase table id | -[ RECORD 3 ] -----------+---------------------------time_stamp | 2013-06-05 11:44:42.011 design_id | 45035996273705090 design_name | VMART_DESIGN stage_type | Analyzing statistics iteration_number | total_query_count | remaining_query_count | max_step_number | 15 current_step_number | 1 current_step_description | public.customer_dimension table id | ... -[ RECORD 20 ] ----------+---------------------------time_stamp | 2013-06-05 11:44:49.324 design_id | 45035996273705090 design_name | VMART_DESIGN stage_type | Optimizing query performance iteration_number | 1 total_query_count | 9 HP Vertica Analytic Database (7.0.x) Page 1441 of 1539 SQL Reference Manual HP Vertica System Tables remaining_query_count | 9 max_step_number | 7 current_step_number | 1 current_step_description | Extracting interesting columns table id | ... -[ RECORD 62 ] ----------+---------------------------time_stamp | 2013-06-05 11:51:23.790 design_id | 45035996273705090 design_name | VMART_DESIGN stage_type | Deployment in progress iteration_number | total_query_count | remaining_query_count | max_step_number | current_step_number | current_step_description | Deployment completed successfully table id | PARTITION_REORGANIZE_ERRORS Monitors all background partitioning tasks, and if HP Vertica encounters an error, creates an entry in this table with the appropriate information. Does not log repartitioning tasks that complete successfully. Column Name Data Type Description SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. USER_NAME VARCHAR Name of the user who received the error at the time HP Vertica recorded the session. NODE_NAME VARCHAR Name of the node that is reporting the requested information. TABLE_NAME VARCHAR Name of the partitioned table. PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Projection name for which information is listed. MESSAGE VARCHAR Textual output of the error message. HINT VARCHAR Actionable hint about the error. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. HP Vertica Analytic Database (7.0.x) Page 1442 of 1539 SQL Reference Manual HP Vertica System Tables PARTITION_STATUS Shows, for each projection of each partitioned table, the fraction of its data that is actually partitioned according to the current partition expression. When the partitioning of a table is altered, the value in partition_reorganize_percent for each of its projections drops to zero and goes back up to 100 when all the data is repartitioned. Column Name Data Type Description PROJECTION_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. TABLE_SCHEMA VARCHAR Name of the schema that contains the partitioned table. TABLE_NAME VARCHAR Table name that is partitioned. TABLE_ID INTEGER Unique numeric ID assigned by the HP Vertica, which identifies the table. PROJECTION_SCHEMA VARCHAR Schema containing the projection. PROJECTION_NAME VARCHAR Projection name for which information is listed. PARTITION_REORGANIZE_PERCENT INTEGER For each projection, drops to zero and goes back up to 100 when all the data is repartitioned after the partitioning of a table has been altered. Ideally all rows will show 100 (%). Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM partition_status; -[ RECORD 1 ]----------------+----------------------projection_id | 45035996281788238 table_schema | public table_name | lineorder table_id | 45035996281787664 projection_schema | public projection_name | VLINEORDER partition_reorganize_percent | 100 -[ RECORD 2 ]----------------+----------------------projection_id | 45035996281788312 table_schema | public table_name | lineorder HP Vertica Analytic Database (7.0.x) Page 1443 of 1539 SQL Reference Manual HP Vertica System Tables table_id | 45035996281787664 projection_schema | public projection_name | VLINEORDER1 partition_reorganize_percent | 100 -[ RECORD 3 ]----------------+----------------------projection_id | 45035996281788752 table_schema | public table_name | lineorder table_id | 45035996281787664 projection_schema | public projection_name | VLINEORDER2 partition_reorganize_percent | 100 -[ RECORD 4 ]----------------+----------------------projection_id | 45035996281788822 table_schema | public table_name | lineorder table_id | 45035996281787664 projection_schema | public projection_name | VLINEORDER1_BUD partition_reorganize_percent | 100 ... PARTITIONS Displays partition metadata, one row per partition key, per ROS container. Column Name Data Type Description PARTITION_KEY VARCHAR The partition value(s). PROJECTION_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the projection. TABLE_SCHEMA VARCHAR The schema name for which information is listed. PROJECTION_NAME VARCHAR The projection name for which information is listed. ROS_ID VARCHAR A unique numeric ID assigned by the HP Vertica catalog, which identifies the ROS container. ROS_SIZE_BYTES INTEGER The ROS container size in bytes. ROS_ROW_COUNT INTEGER Number of rows in the ROS container. NODE_NAME VARCHAR Node where the ROS container resides. DELETED_ROW_COUNT INTEGER The number of rows in the partition. LOCATION_LABEL VARCHAR The location label of the default storage location. HP Vertica Analytic Database (7.0.x) Page 1444 of 1539 SQL Reference Manual HP Vertica System Tables Notes l A many-to-many relationship exists between partitions and ROS containers. PARTITIONS displays information in a denormalized fashion. l To find the number of ROS containers having data of a specific partition, aggregate PARTITIONS over the partition_key column. l To find the number of partitions stored in a ROS container, aggregate PARTITIONS over the ros_id column. Example Given a projection named p1, with three ROS containers, the PARTITIONS table returns three rows: => SELECT PARTITION_KEY, PROJECTION_NAME, ROS_ID, ROS_SIZE_BYTES, ROS_ROW_COUNT, NODE_NAME FROM partitions; PARTITION_KEY | PROJECTION_NAME | ROS_ID | ROS_SIZE_BYTES | ROS_ROW_COUNT | NODE_NAME ---------------+------------------+-------------------+----------------+---------------+---------------------2008 | trade_p_node0001 | 45035996273740461 | 90 | 1 | node0001 2007 | trade_p_node0001 | 45035996273740477 | 99 | 2 | node0001 2006 | trade_p_node0001 | 45035996273740493 | 99 | 2 | node0001 (3 rows) PROCESS_SIGNALS Returns a history of signals that were received and handled by the HP Vertica process. Column Name Data Type SIGNAL_TIMESTAMP TIMESTAMPTZ Time when HP Vertica recorded the signal. NODE_NAME VARCHAR Name of the node that is reporting the requested information. SIGNAL_NUMBER INTEGER Signal number. SIGNAL_CODE INTEGER Signal code. HP Vertica Analytic Database (7.0.x) Description Page 1445 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description SIGNAL_PID INTEGER Linux process identifier of the signal. SIGNAL_UID INTEGER Process ID of sending process. SIGNAL_ADDRESS INTEGER Address at which fault occurred. Permissions Must be a superuser. Example => SELECT signal_timestamp, node_name, signal_number, signal_pid, signal_uid, signal)addr ess FROM process_signals; signal_timestamp | node_name | signal_number | signal_pid | signal_uid | si gnal_address -------------------------------+-----------+---------------+------------+------------+--------------2012-02-14 13:15:23.608359-04 | initiator | 15 | 31721 | 500 | 2 147483679721 (1 row) PROJECTION_RECOVERIES Retains history about projection recoveries. Since HP Vertica adds an entry per recovery plan, a projection/node pair could appear multiple times in the output. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is recovering or has recovered the corresponding projection. PROJECTION_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Name of the projection that is being or has been recovered on the corresponding node. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any. TRANSACTION_ID initializes as NO_TRANSACTION with a value of 0. HP Vertica will ignore the recovery query and keep (0) if there's no action to take (no data in the table, etc). When no recovery transaction starts, ignored value appears in this table's STATUS column. HP Vertica Analytic Database (7.0.x) Page 1446 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. METHOD VARCHAR Recovery method that HP Vertica chooses. Possible values are: STATUS PROGRESS VARCHAR INTEGER l incremental l incremental-replay-delete l split l recovery-by-container Current projection-recovery status on the corresponding node. STATUS can be "queued," which indicates a brief period between the time the query is prepared and when it runs. Possible values are: l queued l running l finished l ignored l error-retry l error-fatal An estimate (value in the range [0,100]) of percent complete for the recovery task described by this information. Note: The actual amount of time it takes to complete a recovery task depends on a number of factors, including concurrent workloads and characteristics of the data; therefore, accuracy of this estimate can vary. The PROGRESS column value is NULL after the task completes. HP Vertica Analytic Database (7.0.x) Page 1447 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description DETAIL VARCHAR More detailed information about PROGRESS. The values returned for this column depend on the type of recovery plan: l General recovery plans – value displays the estimated progress, as a percent, of the three primary parts of the plan: Scan, Sort, and Write. l Recovery-by-container plans – value begins with CopyStorage: and is followed by the number of bytes copied over the total number of bytes to copy. l Replay delete plans – value begins with Delete: and is followed by the number of deletes replayed over an estimate of the total number of deletes to replay. The DETAIL column value becomes NULL after the recovery plan completes. START_TIME TIMESTAMPTZ Time the recovery task described by this information started. END_TIME TIMESTAMPTZ Time the recovery task described by this information ended. RUNTIME_PRIORITY VARCHAR Determines the amount of runtime resources (CPU, I/O bandwidth) the Resource Manager should dedicate to running queries in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Notes If you are interested in monitoring recovery progress when recovery seems to be taking a while, note that you cannot query system tables table during cluster recovery; the cluster must be UP to accept connections. HP Vertica Analytic Database (7.0.x) Page 1448 of 1539 SQL Reference Manual HP Vertica System Tables Example => SELECT node_name, recover_epoch, recovery_phase, current_completed,current_total, is_running FROM recovery_status; node_name | recover_epoch | recovery_phase | current_completed | current_total | i s_running -----------+---------------+-------------------+-------------------+---------------+----------node01 | | | 0 | 0 | f node02 | 0 | historical pass 1 | 0 | 0 | t node03 | 1 | current | 0 | 0 | f (3 rows) => SELECT node_name, projection_name, method, status, progress, detail, start_time FROM projection_recoveries; node_name | projection_name | method | status | progress | detail | start_time -----------+-----------------+---------------------------+---------+----------+------------------------------+------------------------------node02 | public.t_p1 | incremental | running | 69 | Scan:1 00% Sort:100% Write:87% | 2011-10-04 14:41:51.354757-04 node02 | public.t_p0 | incremental-replay-delete | running | 71 | Delete :0/6563442 | 2011-10-04 14:41:51.353797-04 node02 | public.tt_p0 | recovery-by-container | running | 76 | CopySt orage:27427070/35938922 | 2011-10-04 14:44:50.525465-04 (3 rows) See Also l RECOVERY_STATUS PROJECTION_REFRESHES Provides information about refresh operations for projections. Column Name Data Type Description NODE_NAME VARCHAR Node where the refresh was initiated. PROJECTION_SCHEMA VARCHAR Name of the schema associated with the projection. PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Name of the projection that is targeted for refresh. HP Vertica Analytic Database (7.0.x) Page 1449 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ANCHOR_TABLE_NAME VARCHAR Name of the projection's associated anchor table. REFRESH_STATUS VARCHAR Status of the projection: REFRESH_PHASE VARCHAR l Queued — Indicates that a projection is queued for refresh. l Refreshing — Indicates that a refresh for a projection is in process. l Refreshed — Indicates that a refresh for a projection has successfully completed. l Failed — Indicates that a refresh for a projection did not successfully complete. Indicates how far the refresh has progressed: l Historical – Indicates that the refresh has reached the first phase and is refreshing data from historical data. This refresh phase requires the most amount of time. l Current – Indicates that the refresh has reached the final phase and is attempting to refresh data from the current epoch. To complete this phase, refresh must be able to obtain a lock on the table. If the table is locked by some other transaction, refresh is put on hold until that transaction completes. The LOCKS system table is useful for determining if a refresh has been blocked on a table lock. To determine if a refresh has been blocked, locate the term "refresh" in the transaction description. A refresh has been blocked when the scope for the refresh is REQUESTED and one or more other transactions have acquired a lock on the table. Note: The REFRESH_PHASE field is NULL until the projection starts to refresh and is NULL after the refresh completes. HP Vertica Analytic Database (7.0.x) Page 1450 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description REFRESH_METHOD VARCHAR Method used to refresh the projection: l Buddy – Uses the contents of a buddy to refresh the projection. This method maintains historical data. This enables the projection to be used for historical queries. l Scratch – Refreshes the projection without using a buddy. This method does not generate historical data. This means that the projection cannot participate in historical queries from any point before the projection was refreshed. l Rebalance – If the projection is segmented it is refreshed from scratch; if unsegmented it is refreshed from buddy. REFRESH_FAILURE_COUNT INTEGER Number of times a refresh failed for the projection. FAILURE_COUNT does not indicate whether the projection was eventually refreshed. See REFRESH_STATUS to determine how the refresh operation is progressing. SESSION_ID VARCHAR Unique numeric ID assigned by the HP Vertica catalog, which identifies the refresh session. REFRESH_START TIMESTAMPTZ Time the projection refresh started (provided as a timestamp). REFRESH_DURATION_SEC INTERVAL SECOND (0) Length of time that the projection refresh ran in seconds. IS_EXECUTING BOOLEAN Distinguishes between active (t) and completed (f) refresh operations. RUNTIME_PRIORITY VARCHAR Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to running queries in the resource pool. Valid values are: HP Vertica Analytic Database (7.0.x) l HIGH l MEDIUM l LOW Page 1451 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description transaction_id Int Identifier for the transaction within the session, if any; otherwise NULL. Note: The transaction_id is correlated with the execution plan only when refreshing from scratch. When refreshing from a buddy, multiple sub-transactions are created Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Notes l Information about a refresh operation—whether successful or unsuccessful—is maintained in the PROJECTION_REFRESHES system table until either the CLEAR_PROJECTION_ REFRESHES() function is executed or the storage quota for the table is exceeded. l Tables and projections can be dropped while a query runs against them. The query continues to run, even after the drop occurs. Only when the query finishes does it notice the drop, which could cause a rollback. The same is true for refresh queries. PROJECTION_REFRESHES, therefore, could report that a projection failed to be refreshed before the refresh query completes. In this case, the REFRESH_DURATION_SEC column continues to increase until the refresh query completes. Example The following command purges projection refresh history from the PROJECTION_REFRESHES table: => SELECT clear_projection_refreshes(); clear_projection_refreshes ---------------------------CLEAR (1 row) Only the rows where the IS_EXECUTING column equals false are cleared. See Also l CLEAR_PROJECTION_REFRESHES HP Vertica Analytic Database (7.0.x) Page 1452 of 1539 SQL Reference Manual HP Vertica System Tables PROJECTION_STORAGE Monitors the amount of disk storage used by each projection on each node. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. PROJECTION_ID VARCHAR A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR The projection name for which information is listed. PROJECTION_SCHEMA VARCHAR The name of the schema associated with the projection. PROJECTION_COLUMN_COUNT INTEGER The number of columns in the projection. ROW_COUNT INTEGER The number of rows in the table's projections, including any rows marked for deletion. USED_BYTES INTEGER The number of bytes of disk storage used by the projection. WOS_ROW_COUNT INTEGER The number of WOS rows in the projection. WOS_USED_BYTES INTEGER The number of WOS bytes in the projection. ROS_ROW_COUNT INTEGER The number of ROS rows in the projection. ROS_USED_BYTES INTEGER The number of ROS bytes in the projection. ROS_COUNT INTEGER The number of ROS containers in the projection. ANCHOR_TABLE_NAME VARCHAR The associated table name for which information is listed. ANCHOR_TABLE_SCHEMA VARCHAR The associated table schema for which information is listed. Notes Projections that have no data never have full statistics. Querying this system table lets you see if your projection contains data. Example Query the system table: => SELECT * FROM projection_storage; -[ RECORD 1 ]-----------+------------------- HP Vertica Analytic Database (7.0.x) Page 1453 of 1539 SQL Reference Manual HP Vertica System Tables node_name | v_onenode_node0001 projection_id | 45035996273718838 projection_name | trades_p projection_schema | public projection_column_count | 4 row_count | 1 used_bytes | 147 wos_row_count | 0 wos_used_bytes | 0 ros_row_count | 1 ros_used_bytes | 147 ros_count | 1 anchor_table_name | trades anchor_table_schema | public anchor_table_id | 45035996273718836 => SELECT projection_name, row_count, ros_used_bytes, used_bytes FROM PROJECTION_STORAGE WHERE projection_schema = 'store' ORDER BY used_bytes; projection_name | row_count | ros_used_bytes | used_bytes ------------------------------------------------------------+-----------+---------------+-----------store_dimension_DBD_4_seg_vmartdb_design_vmartdb_design | 53 | 2791 | 2791 store_dimension_DBD_29_seg_vmartdb_design_vmartdb_design | 53 | 2791 | 2791 store_dimension_DBD_29_seg_vmartdb_design_vmartdb_design | 56 | 2936 | 2936 store_dimension_DBD_4_seg_vmartdb_design_vmartdb_design | 56 | 2936 | 2936 store_dimension_DBD_4_seg_vmartdb_design_vmartdb_design | 68 | 3360 | 3360 store_dimension_DBD_29_seg_vmartdb_design_vmartdb_design | 68 | 3360 | 3360 store_dimension_DBD_29_seg_vmartdb_design_vmartdb_design | 73 | 3579 | 3579 store_dimension_DBD_4_seg_vmartdb_design_vmartdb_design | 73 | 3579 | 3579 store_orders_fact_DBD_31_seg_vmartdb_design_vmartdb_design | 53974 | 1047782 | 1047782 store_orders_fact_DBD_6_seg_vmartdb_design_vmartdb_design | 53974 | 1047782 | 1047782 store_orders_fact_DBD_6_seg_vmartdb_design_vmartdb_design | 66246 | 1285786 | 1285786 store_orders_fact_DBD_31_seg_vmartdb_design_vmartdb_design | 66246 | 1285786 | 1285786 store_orders_fact_DBD_31_seg_vmartdb_design_vmartdb_design | 71909 | 1395258 | 1395258 store_orders_fact_DBD_6_seg_vmartdb_design_vmartdb_design | 71909 | 1395258 | 1395258 store_orders_fact_DBD_6_seg_vmartdb_design_vmartdb_design | 107871 | 2090941 | 2090941 store_orders_fact_DBD_31_seg_vmartdb_design_vmartdb_design | 107871 | 2090941 | 2090941 store_sales_fact_DBD_5_seg_vmartdb_design_vmartdb_design | 1235825 | 24285740 | 24285740 store_sales_fact_DBD_30_seg_vmartdb_design_vmartdb_design | 1235825 | 24285740 | 24285740 store_sales_fact_DBD_30_seg_vmartdb_design_vmartdb_design | 1245865 | 24480819 HP Vertica Analytic Database (7.0.x) Page 1454 of 1539 SQL Reference Manual HP Vertica System Tables | 24480819 store_sales_fact_DBD_5_seg_vmartdb_design_vmartdb_design | 1245865 | | 24480819 store_sales_fact_DBD_5_seg_vmartdb_design_vmartdb_design | 1249547 | | 24551817 store_sales_fact_DBD_30_seg_vmartdb_design_vmartdb_design | 1249547 | | 24551817 store_sales_fact_DBD_30_seg_vmartdb_design_vmartdb_design | 1268763 | | 24930549 store_sales_fact_DBD_5_seg_vmartdb_design_vmartdb_design | 1268763 | | 24930549 (24 rows) The following command returns the per-node storage used by a segmented table: SELECT anchor_table_name, node_name, SUM(ros_used_bytes)/1024/1024 AS MB, SUM(ros_row_count) AS Rows FROM projection_storage GROUP BY 1,2 ORDER BY 1,2; anchor_table_name | node_name | MB | Rows -----------------------+--------------------+----+--------call_center_dimension | v_vmartdb_node0001 | 0 | 98 call_center_dimension | v_vmartdb_node0002 | 0 | 101 call_center_dimension | v_vmartdb_node0003 | 0 | 102 call_center_dimension | v_vmartdb_node0004 | 0 | 99 customer_dimension | v_vmartdb_node0001 | 0 | 24030 customer_dimension | v_vmartdb_node0002 | 0 | 1648 customer_dimension | v_vmartdb_node0003 | 0 | 25970 customer_dimension | v_vmartdb_node0004 | 1 | 48352 date_dimension | v_vmartdb_node0001 | 0 | 910 date_dimension | v_vmartdb_node0002 | 0 | 913 date_dimension | v_vmartdb_node0003 | 0 | 916 date_dimension | v_vmartdb_node0004 | 0 | 913 employee_dimension | v_vmartdb_node0001 | 0 | 4998 employee_dimension | v_vmartdb_node0002 | 0 | 4999 employee_dimension | v_vmartdb_node0003 | 0 | 5002 employee_dimension | v_vmartdb_node0004 | 0 | 5001 inventory_fact | v_vmartdb_node0001 | 0 | 150414 inventory_fact | v_vmartdb_node0002 | 0 | 149736 inventory_fact | v_vmartdb_node0003 | 0 | 149586 inventory_fact | v_vmartdb_node0004 | 0 | 150264 online_page_dimension | v_vmartdb_node0001 | 0 | 499 online_page_dimension | v_vmartdb_node0002 | 0 | 500 online_page_dimension | v_vmartdb_node0003 | 0 | 501 online_page_dimension | v_vmartdb_node0004 | 0 | 500 online_sales_fact | v_vmartdb_node0001 | 59 | 4941898 online_sales_fact | v_vmartdb_node0002 | 59 | 5024898 online_sales_fact | v_vmartdb_node0003 | 59 | 5058102 online_sales_fact | v_vmartdb_node0004 | 59 | 4975102 product_dimension | v_vmartdb_node0001 | 1 | 103185 product_dimension | v_vmartdb_node0002 | 1 | 100428 product_dimension | v_vmartdb_node0003 | 1 | 76815 product_dimension | v_vmartdb_node0004 | 1 | 79572 promotion_dimension | v_vmartdb_node0001 | 0 | 499 promotion_dimension | v_vmartdb_node0002 | 0 | 500 promotion_dimension | v_vmartdb_node0003 | 0 | 501 promotion_dimension | v_vmartdb_node0004 | 0 | 500 rostab | v_vmartdb_node0001 | 0 | 0 rostab | v_vmartdb_node0002 | 0 | 0 rostab | v_vmartdb_node0003 | 0 | 0 HP Vertica Analytic Database (7.0.x) 24480819 24551817 24551817 24930549 24930549 Page 1455 of 1539 SQL Reference Manual HP Vertica System Tables rostab shipping_dimension shipping_dimension shipping_dimension shipping_dimension store_dimension store_dimension store_dimension store_dimension store_orders_fact store_orders_fact store_orders_fact store_orders_fact store_sales_fact store_sales_fact store_sales_fact store_sales_fact vendor_dimension vendor_dimension vendor_dimension vendor_dimension warehouse_dimension warehouse_dimension warehouse_dimension warehouse_dimension (64 rows) | | | | | | | | | | | | | | | | | | | | | | | | | v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 v_vmartdb_node0001 v_vmartdb_node0002 v_vmartdb_node0003 v_vmartdb_node0004 | | | | | | | | | | | | | | | | | | | | | | | | | 0 0 0 0 0 0 0 0 0 2 2 2 2 46 47 46 46 0 0 0 0 0 0 0 0 | | | | | | | | | | | | | | | | | | | | | | | | | 0 49 50 51 50 123 125 127 125 147768 149759 152232 150241 2501318 2512691 2498682 2487309 48 48 52 52 49 50 51 50 See Also l PROJECTIONS l ANALYZE_STATISTICS PROJECTION_USAGE Records information about projections HP Vertica uses in each processed query. Column Name Data Type QUERY_START_TIMESTAMP TIMESTAMPTZ Value of query at beginning of history interval. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_NAME VARCHAR Name of the user at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. HP Vertica Analytic Database (7.0.x) Description Page 1456 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description REQUEST_ID INTEGER Unique identifier of the query request in the user session. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID, and REQUEST_ID uniquely identifies a statement within a session. IO_TYPE VARCHAR Input/output. PROJECTION_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Projection name for which information is listed. ANCHOR_TABLE_ID INTEGER Unique numeric ID assigned by the HP Vertica, which identifies the anchor table. ANCHOR_TABLE_SCHEMA VARCHAR Name of the schema that contains the anchor table. ANCHOR_TABLE_NAME VARCHAR Name of the projection's associated anchor table. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Examples => SELECT query_start_timestamp, node_name, user_name, request_id, io_type, projection_id, projection_name, anchor_table_name FROM projection_usage; query_start_timestamp | node_name | user_name | request_id | io_type | projectio n_name | anchor_table_name -------------------------------+-----------+-----------+------------+----------+----------------+------------------2011-09-16 13:38:47.00034-04 | node01 | kelly | 16 | 1 | t_super | t 2011-09-16 13:38:52.920688-04 | node01 | kelly | 18 | 2 | t_super | t 2011-09-16 13:38:52.987128-04 | node01 | kelly | 20 | 1 | t_super | t (3 rows) HP Vertica Analytic Database (7.0.x) Page 1457 of 1539 SQL Reference Manual HP Vertica System Tables QUERY_EVENTS Returns information about query planning, optimization, and execution events. Column Name Data Type EVENT_TIMESTAMP TIMESTAMPTZ Time when HP Vertica recorded the event. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_ID INTEGER Identifier of the user for the query event. USER_NAME VARCHAR Name of the user for which HP Vertica lists query information at the time it recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. REQUEST_ID INTEGER Unique identifier of the query request in the user session. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID, and REQUEST_ID uniquely identifies a statement within a session. EVENT_CATEGORY VARCHAR Category of event: OPTIMIZATION or EXECUTION. EVENT_TYPE VARCHAR Type of event. Examples include but are not limited to: EVENT_DESCRIPTION VARCHAR HP Vertica Analytic Database (7.0.x) Description l PREDICATE OUTSIDE HISTOGRAM l NO HISTOGRAM l MEMORY LIMIT HIT l GROUP_BY_SPILLED l JOIN_SPILLED l PARTITIONS_ELIMINATED l MERGE_CONVERTED_TO_UNION Generic description of the event. Page 1458 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description OPERATOR_NAME VARCHAR Name of the Execution Engine component that generated the event, if applicable; for example, NetworkSend. Values from the OPERATOR_NAME and PATH_ID columns let you tie a query event back to a particular operator in the EXPLAIN plan. If the event did not come from a specific operator, the OPERATOR_NAME column is NULL. PATH_ID INTEGER Unique identifier that HP Vertica assigns to a query operation or path in a query plan. If the event did not come from a specific operator, the PATH_ID column is NULL. See EXECUTION_ENGINE_PROFILES for more information. OBJECT_ID INTEGER Object identifier (such as projection or table) to which the event refers. EVENT_DETAILS VARCHAR Free-form text describing the specific event. SUGGESTED_ACTION VARCHAR Suggested user action, if any is available. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Examples => \x Expanded display is on. => SELECT * FROM query_events; -[ RECORD 1 ]-----+------------------------------------------------------------event_timestamp | 2012-12-09 23:59:00.174464-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-31427:0x82fb request_id | 1 transaction_id | 45035996273711993 statement_id | 1 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | HP Vertica Analytic Database (7.0.x) Page 1459 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 2 ]-----+------------------------------------------------------------event_timestamp | 2012-12-09 06:37:01.518944-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-31427:0x19 request_id | 2 transaction_id | 45035996273708310 statement_id | 2 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 1 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 3 ]-----+------------------------------------------------------------event_timestamp | 2012-12-08 23:59:00.08586-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x4c7c request_id | 1 transaction_id | 45035996273707118 statement_id | 1 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 4 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:55:20.047935-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0xb0 request_id | 0 transaction_id | 45035996273705015 statement_id | 1 event_category | EXECUTION event_type | SMALL_MERGE_REPLACED event_description | Small StorageMerge replaced with StorageUnion for efficiency operator_name | StorageMerge path_id | object_id | 45035996273718838 event_details | Projection: public.trades_p suggested_action | -[ RECORD 5 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:54:27.394169-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin HP Vertica Analytic Database (7.0.x) Page 1460 of 1539 SQL Reference Manual HP Vertica System Tables session_id | doca01.verticacorp.-19852:0x14 request_id | 10 transaction_id | 45035996273705005 statement_id | 1 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 6 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:54:27.39424-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 10 transaction_id | 45035996273705005 statement_id | 1 event_category | EXECUTION event_type | SMALL_MERGE_REPLACED event_description | Small StorageMerge replaced with StorageUnion for efficiency operator_name | StorageMerge path_id | 2 object_id | 45035996273718838 event_details | Projection: public.trades_p suggested_action | -[ RECORD 7 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:54:27.403897-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 10 transaction_id | 45035996273705005 statement_id | 2 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 8 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:54:27.415003-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 10 transaction_id | 45035996273705005 statement_id | 3 event_category | EXECUTION HP Vertica Analytic Database (7.0.x) Page 1461 of 1539 SQL Reference Manual HP Vertica System Tables event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 9 ]-----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:53:23.425399-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 8 transaction_id | 45035996273704996 statement_id | 1 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 10 ]----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:52:04.122981-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 6 transaction_id | 45035996273704983 statement_id | 1 event_category | EXECUTION event_type | RLE_OVERRIDDEN event_description | Compressed execution will not be used on some columns, because the av erage run counts are not large enough. operator_name | Scan path_id | 2 object_id | 45035996273718840 event_details | Column public.trades_p.stock will not be processed using RLE. suggested_action | -[ RECORD 11 ]----+-------------------------------------------------------------event_timestamp | 2012-12-08 13:52:04.123235-05 node_name | v_onenode_node0001 user_id | 45035996273704962 user_name | dbadmin session_id | doca01.verticacorp.-19852:0x14 request_id | 6 transaction_id | 45035996273704983 statement_id | 1 event_category | EXECUTION event_type | SMALL_MERGE_REPLACED event_description | Small StorageMerge replaced with StorageUnion for efficiency operator_name | StorageMerge path_id | 2 HP Vertica Analytic Database (7.0.x) Page 1462 of 1539 SQL Reference Manual HP Vertica System Tables object_id event_details suggested_action | 45035996273718838 | Projection: public.trades_p | See Also l EXECUTION_ENGINE_PROFILES l QUERY_PLAN_PROFILES QUERY_METRICS Monitors the sessions and queries running on each node. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. ACTIVE_USER_SESSION_COUNT INTEGER The number of active user sessions (connections). ACTIVE_SYSTEM_SESSION_COUNT INTEGER The number of active system sessions. TOTAL_USER_SESSION_COUNT INTEGER The total number of user sessions. TOTAL_SYSTEM_SESSION_COUNT INTEGER The total number of system sessions. TOTAL_ACTIVE_SESSION_COUNT INTEGER The total number of active user and system sessions. TOTAL_SESSION_COUNT INTEGER The total number of user and system sessions. RUNNING_QUERY_COUNT INTEGER The number of queries currently running. EXECUTED_QUERY_COUNT INTEGER The total number of queries that ran. Notes Totals get reset each time you restart the database. Example =>\pset expanded Expanded display is on. => SELECT * FROM QUERY_METRICS; -[ RECORD 1 ]---------------+------------------node_name | v_vmartdb_node01 active_user_session_count | 1 active_system_session_count | 2 HP Vertica Analytic Database (7.0.x) Page 1463 of 1539 SQL Reference Manual HP Vertica System Tables total_user_session_count | 2 total_system_session_count | 6248 total_active_session_count | 3 total_session_count | 6250 running_query_count | 1 executed_query_count | 42 -[ RECORD 2 ]---------------+------------------node_name | v_vmartdb_node02 active_user_session_count | 1 active_system_session_count | 2 total_user_session_count | 2 total_system_session_count | 6487 total_active_session_count | 3 total_session_count | 6489 running_query_count | 0 executed_query_count | 0 -[ RECORD 3 ]---------------+------------------node_name | v_vmartdb_node03 active_user_session_count | 1 active_system_session_count | 2 total_user_session_count | 2 total_system_session_count | 6489 total_active_session_count | 3 total_session_count | 6491 running_query_count | 0 executed_query_count | 0 -[ RECORD 4 ]---------------+------------------node_name | v_vmartdb_node04 active_user_session_count | 1 active_system_session_count | 2 total_user_session_count | 2 total_system_session_count | 6489 total_active_session_count | 3 total_session_count | 6491 running_query_count | 0 executed_query_count | 0 QUERY_PLAN_PROFILES Provides detailed execution status for queries that are currently running in the system. Output from the table shows the real-time flow of data and the time and resources consumed for each path in each query plan. Column Name Data Type Description TRANSACTION_ID INTEGER An identifier for the transaction within the session if any; otherwise NULL. HP Vertica Analytic Database (7.0.x) Page 1464 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID and STATEMENT_ID uniquely identifies a statement within a session; these columns are useful for creating joins with other system tables. PATH_ID INTEGER Unique identifier that HP Vertica assigns to a query operation or path in a query plan. Textual representation for this path is output in the PATH_LINE column. PATH_LINE_INDEX INTEGER Each plan path in QUERY_PLAN_PROFILES could be represented with multiple rows. PATH_LINE_INDEX returns the relative line order. You should include the PATH_LINE_INDEX column in the QUERY_PLAN_ PROFILES ... ORDER BY clause so rows in the result set appear as they do in EXPLAIN plan output. PATH_IS_EXECUTING BOOLEAN Status of a path in the query plan. True (t) if the path has started running, otherwise false. PATH_IS_COMPLETE BOOLEAN Status of a path in the query plan. True (t) if the path has finished running, otherwise false. IS_EXECUTING BOOLEAN Status of a running query. True if the query is currently active (t), otherwise false (f). RUNNING_TIME INTERVAL The amount of elapsed time the query path took to execute. MEMORY_ALLOCATED_BYTES INTEGER The amount of memory the path used, in bytes. READ_FROM_DISK_BYTES INTEGER The number of bytes the path read from disk (or the disk cache). RECEIVED_BYTES INTEGER The number of bytes received over the network. SENT_BYTES INTEGER Size of data sent over the network by the path. PATH_LINE VARCHAR The EXPLAIN plan text string for the path, associated with the PATH ID and PATH_LINE_INDEX columns. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. HP Vertica Analytic Database (7.0.x) Page 1465 of 1539 SQL Reference Manual HP Vertica System Tables Best Practices Table results can be very wide. For best results when you query the QUERY_PLAN_PROFILES table, sort on these columns: l TRANSACTION_ID l STATEMENT_ID l PATH_ID l PATH_LINE_INDEX For example: => SELECT ... FROM query_plan_profiles WHERE ... ORDER BY transaction_id, statement_id, path_id, path_line_index; Example For examples and additional information, see Profiling query plan profiles in the Administrator's Guide See Also l EXECUTION_ENGINE_PROFILES l EXPLAIN l PROFILE l QUERY_EVENTS QUERY_PROFILES Provides information about queries that have already executed. Column Name Data Type Description SESSION_ID VARCHAR The identification of the session for which profiling information is captured. This identifier is unique within the cluster at any point in time but can be reused when the session closes. TRANSACTION_ID INTEGER An identifier for the transaction within the session if any; otherwise NULL. HP Vertica Analytic Database (7.0.x) Page 1466 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. IDENTIFIER VARCHAR A string to identify the query in system tables. Note: You can query the IDENTIFIER column to quickly identify queries you have labeled for profiling and debugging. See How to label queries for profiling in the Administrator's Guide for details. NODE_NAME VARCHAR The node name for which information is listed. QUERY VARCHAR The query string used for the query. QUERY_SEARCH_PATH VARCHAR A list of schemas in which to look for tables. SCHEMA_NAME VARCHAR The schema name in which the query is being profiled. TABLE_NAME VARCHAR The table name in the query being profiled. PROJECTIONS_USED VARCHAR The projections used in the query. QUERY_DURATION_US NUMERIC (18,0) The duration of the query in microseconds. QUERY_START_EPOCH INTEGER The epoch number at the start of the given query. QUERY_START VARCHAR The Linux system time of query execution in a format that can be used as a DATE/TIME expression. QUERY_TYPE VARCHAR Is one of INSERT, SELECT, UPDATE, DELETE, UTILITY, or UNKNOWN. ERROR_CODE INTEGER The return error code for the query. USER_NAME VARCHAR The name of the user who ran the query. PROCESSED_ROW_COUNT INTEGER The number of rows returned by the query. RESERVED_EXTRA_MEMORY INTEGER The amount of extra memory, in bytes, reserved for the query. Extra memory is the amount of memory reserved for the plan but not assigned to a particular operator. This is the memory from which unbounded operators pull first. If operators acquire all of the extra memory, then the plan must go back to the Resource Manager for more memory. See the Notes section below this table. HP Vertica Analytic Database (7.0.x) Page 1467 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_EXECUTING BOOLEAN Displays information about actively running queries, regardless of whether profiling is enabled. Notes l l The total memory reserved by the query is available in RESOURCE_ ACQUISITIONS.MEMORY_INUSE_KB. The difference between RESOURCE_ ACQUISITIONS.MEMORY_INUSE_KB and QUERY_PROFILES.EXTRA_MEMORY is the "essential memory." n RESOURCE_ACQUISITIONS.MEMORY_INUSE_KB is the total memory acquired. n QUERY_PROFILES.RESERVED_EXTRA_MEMORY is the unused portion of the acquired memory. n The difference gives you the memory in use. If the query has finished executing, query the RESOURCE_ACQUISITIONS table. Example Query the QUERY_PROFILES table: =>\pset expanded Expanded display is on. => SELECT * FROM QUERY_PROFILES;-[ RECORD 1 ]-------+-----------------------------------------------------... -[ RECORD 18 ]------+------------------------------------------------------node_name | v_vmartdb_node0001 session_id | raster-s1-17956:0x1d transaction_id | 45035996273728061 statement_id | 6 identifier | query | SELECT * FROM event_configurations; query_search_path | "$user", public, v_catalog, v_monitor, v_internal schema_name | table_name | projections_used | v_monitor.event_configurations_p query_duration_us | 9647 query_start_epoch | 429 query_start | 2010-10-07 12:46:24.370044-04 query_type | SELECT error_code | 0 user_name | release processed_row_count | 16 reserved_extra_memory | 0 is_executing | f -[ RECORD ...]------+------------------------------------------------------... The following topics in the Administrator's Guide: HP Vertica Analytic Database (7.0.x) Page 1468 of 1539 SQL Reference Manual HP Vertica System Tables See Also l QUERY_REQUESTS l RESOURCE_ACQUISITIONS QUERY_REQUESTS Returns information about user-issued query requests. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_NAME VARCHAR Name of the user who issued the query at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. REQUEST_ID INTEGER Unique identifier of the query request in the user session. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID, and REQUEST_ID uniquely identifies a statement within a session. HP Vertica Analytic Database (7.0.x) Page 1469 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description REQUEST_TYPE VARCHAR Type of the query request. Examples include, but are not limited to: l QUERY l DDL l LOAD l UTILITY l TRANSACTION l PREPARE l EXECUTE l SET l SHOW REQUEST VARCHAR Query statement. REQUEST_LABEL VARCHAR Label of the query, if available/ SEARCH_PATH VARCHAR Contents of the search path. MEMORY_ACQUIRED_MB FLOAT Memory acquired by this query request in megabytes. SUCCESS BOOLEAN Value returned if the query successfully executed. ERROR_COUNT INTEGER Number of errors encountered in this query request (logged in ERROR_MESSAGES table). START_TIMESTAMP TIMESTAMPTZ Beginning of history interval. END_TIMESTAMP TIMESTAMPTZ End of history interval. REQUEST_DURATION_MS INTEGER Length of time the query ran in milliseconds. IS_EXECUTING BOOLEAN Distinguishes between actively-running (t) and completed (f) queries. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. HP Vertica Analytic Database (7.0.x) Page 1470 of 1539 SQL Reference Manual HP Vertica System Tables Examples => \x Expanded display is on. => select * from query_requests; -[ RECORD 1 ]-------+---------------------------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | localhost.localdoma-10713:0xd8fd request_id | 15 transaction_id | 45035996273733877 statement_id | 13 request_type | QUERY request | select * from query_requests; request_label | search_path | "$user", public, v_catalog, v_monitor, v_internal memory_acquired_mb | 100 success | error_count | start_timestamp | 2013-12-05 15:40:17.270719-08 end_timestamp | request_duration_ms | is_executing | t -[ RECORD 2 ]-------+--------------------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | localhost.localdoma-10713:0xd8fd request_id | 14 transaction_id | 45035996273733877 statement_id | 12 request_type | QUERY request | select * from query_events; request_label | search_path | "$user", public, v_catalog, v_monitor, v_internal memory_acquired_mb | 100 success | t error_count | start_timestamp | 2013-12-05 15:39:04.938447-08 end_timestamp | 2013-12-05 15:39:05.455356-08 request_duration_ms | 517 is_executing | f -[ RECORD 3 ]-------+---------------------------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | localhost.localdoma-10713:0xd8fd request_id | 13 transaction_id | 45035996273733877 statement_id | 11 request_type | QUERY request | SELECT node_name, start_time, end_time, tx_kbytes_per_sec AS tx_kby tes, rx_kbytes_per_sec as rx_kbytes FROM network_usage; request_label | search_path | "$user", public, v_catalog, v_monitor, v_internal memory_acquired_mb | 100 success | t error_count | HP Vertica Analytic Database (7.0.x) Page 1471 of 1539 SQL Reference Manual HP Vertica System Tables start_timestamp | 2013-12-05 12:46:54.652349-08 end_timestamp | 2013-12-05 12:47:09.386931-08 request_duration_ms | 14734 is_executing | f -[ RECORD 4 ]-------+--------------------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | localhost.localdoma-10713:0xd8fd request_id | 12 transaction_id | 45035996273733877 statement_id | 10 request_type | QUERY request | select * from storage_locations ; request_label | search_path | "$user", public, v_catalog, v_monitor, v_internal memory_acquired_mb | 100 success | t error_count | start_timestamp | 2013-12-05 10:02:13.425322-08 end_timestamp | 2013-12-05 10:02:13.49068-08 request_duration_ms | 65 is_executing | f ... See Also l QUERY_PROFILES REBALANCE_PROJECTION_STATUS Maintain history on rebalance progress for relevant projections. Column Name Data Type Description PROJECTION_ID INTEGER Identifier of the projection that will be, was, or is being rebalanced. PROJECTION_SCHEMA VARCHAR Schema of the projection that will be, was, or is being rebalanced. PROJECTION_NAME VARCHAR Name of the projection that will be, was, or is being rebalanced. ANCHOR_TABLE_ID INTEGER Anchor table identifier of the projection that will be, was, or is being rebalanced. ANCHOR_TABLE_NAME VARCHAR Anchor table name of the projection that will be, was, or is being rebalanced. HP Vertica Analytic Database (7.0.x) Page 1472 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description REBALANCE_METHOD VARCHAR Method that was, is, or will be used to rebalance the projection. Possible values are: l REFRESH: New projections are created according to the new segmentation definition. Data is copied via a refresh plan from projections with the previous segmentation to the new segments. This method is only used if specifically requested (using START_ REFRESH), by setting a configuration parameter, or if Elastic Cluster is disabled or if there is a change in desired k-safety. l REPLICATE: Unsegmented projection data is copied to new nodes and removed from ephemeral nodes. l ELASTIC_CLUSTER: The segmentation of existing segmented projections is altered to adjust to a new cluster topology and data is redistributed accordingly. DURATION_SEC INTERVAL SEC Length of time (seconds) rebalance has been working on this projection, including time to separate storage, if that work is required. SEPARATED_PERCENT NUMERIC (5,2) Percent of storage that has been separated for this projection. TRANSFERRED_PERCENT NUMERIC (5,2) Percent of storage that has been transferred, for this projection. SEPARATED_BYTES INTEGER Number of bytes, separated by the corresponding rebalance operation, for this projection. TO_SEPARATE_BYTES INTEGER Number of bytes that remain to be separated by the corresponding rebalance operation for this projection. TRANSFERRED_BYTES INTEGER Number of bytes transferred by the corresponding rebalance operation for this projection. TO_TRANSFER_BYTES INTEGER Number of bytes that remain to be transferred by the corresponding rebalance operation for this projection. IS_LATEST BOOLEAN True if this row pertains to the most recent rebalance activity, where elastic_cluster_version = (SELECT version FROM v_catalog.elastic_cluster); HP Vertica Analytic Database (7.0.x) Page 1473 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ELASTIC_CLUSTER_VERSION INTEGER The Elastic Cluster has a version, and each time the cluster topology changes, this version is incremented. This column reflects the version to which this row of information pertains. The TO_* fields (TO_ SEPARATE_* and TO_TRANSFER_*) are only valid for the current version. To view only rows from the current, latest or upcoming rebalance operation, use: WHERE elastic_cluster_version = (SELECT version FROM v_catalog.elastic_cluster); Permissions Must be a superuser. See Also l ELASTIC_CLUSTER l REBALANCE_TABLE_STATUS REBALANCE_TABLE_STATUS Maintain history on rebalance progress for relevant tables. Column Name Data Type Description TABLE_ID INTEGER Identifier of the table that will be, was, or is being rebalanced. TABLE_SCHEMA VARCHAR Schema of the table that will be, was, or is being rebalanced. TABLE_NAME VARCHAR Name of the table that will be, was, or is being rebalanced. REBALANCE_METHOD VARCHAR Method that will be, is, or was used to rebalance the projections of this table. Possible values are: HP Vertica Analytic Database (7.0.x) l REFRESH l REPLICATE l ELASTIC_CLUSTER Page 1474 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description DURATION_SEC INTERVAL SEC Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. SEPARATED_PERCENT NUMERIC (5,2) Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. TRANSFERRED_PERCENT NUMERIC (5,2) Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. SEPARATED_BYTES INTEGER Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. TO_SEPARATE_BYTES INTEGER Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. TRANSFERRED_BYTES INTEGER Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. TO_TRANSFER_BYTES INTEGER Aggregate, by table_id, rebalance_method, and elastic_ cluster_version, of the same in REBALANCE_ PROJECTION_STATUS. IS_LATEST BOOLEAN True if this row pertains to the most recent rebalance activity, where elastic_cluster_version = (SELECT version FROM v_catalog.elastic_cluster;) ELASTIC_CLUSTER_VERSION INTEGER The Elastic Cluster has a version, and each time the cluster topology changes, this version is incremented. This column reflects the version to which this row of information pertains. The TO_* fields (TO_ SEPARATE_* and TO_TRANSFER_*) are only valid for the current version. To view only rows from the current, latest or upcoming rebalance operation, use: WHERE elastic_cluster_version = (SELECT version FROM v_catalog.elastic_cluster;) Permissions Must be superuser. HP Vertica Analytic Database (7.0.x) Page 1475 of 1539 SQL Reference Manual HP Vertica System Tables See Also l ELASTIC_CLUSTER l REBALANCE_PROJECTION_STATUS RECOVERY_STATUS Provides the status of recovery operations, returning one row for each node. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. RECOVER_EPOCH INTEGER Epoch the recovery operation is trying to catch up to. RECOVERY_PHASE VARCHAR Current stage in the recovery process. Can be one of the following: l NULL l current l historical pass X, where X is the iteration count SPLITS_COMPLETED INTEGER Number of independent recovery SPLITS queries that have run and need to run. SPLITS_TOTAL INTEGER Total number of SPLITS queries that ran. Each query corresponds to one row in the PROJECTION_ RECOVERIES table. If SPLITS_TOTAL = 2, then there should be 2 rows added to PROJECTION_RECOVERIES, showing query details. HISTORICAL_COMPLETED INTEGER Number of independent recovery HISTORICAL queries that have run and need to run. HISTORICAL_TOTAL INTEGER Total number of HISTORICAL queries that ran. Each query corresponds to one row in the PROJECTION_ RECOVERIES table. If HISTORICAL_TOTAL = 2, then there should be 2 rows added to PROJECTION_ RECOVERIES, showing query details. CURRENT_COMPLETED INTEGER Number of independent recovery CURRENT queries that have run and need to run. HP Vertica Analytic Database (7.0.x) Page 1476 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CURRENT_TOTAL INTEGER Total number of CURRENT queries that ran. Each query corresponds to one row in the PROJECTION_ RECOVERIES table. If CURRENT_TOTAL = 2, then there should be 2 rows added to PROJECTION_ RECOVERIES, showing query details. IS_RUNNING BOOLEAN True (t) if the node is still running recovery; otherwise false (f). Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Note If you are interested in monitoring recovery progress when recovery seems to be taking a while, note that you cannot query system tables table during cluster recovery; the cluster must be UP to accept connections. Example => SELECT node_name, recover_epoch, recovery_phase, current_completed, current_total, is_ running FROM recovery_status; node_name | recover_epoch | recovery_phase | current_completed | current_total | is_r unning -----------+---------------+-------------------+-------------------+---------------+----------node01 | | | 0 | 0 | f node02 | 0 | historical pass 1 | 0 | 0 | t node03 | 1 | current | 0 | 0 | f See Also l PROJECTION_RECOVERIES RESOURCE_ACQUISITIONS Retains information about resources (memory, open file handles, threads) acquired by each running request for each resource pool in the system. HP Vertica Analytic Database (7.0.x) Page 1477 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR Node name for which information is listed. TRANSACTION_ID INTEGER Transaction identifier for this request. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. REQUEST_TYPE VARCHAR Type of request issued to a resource pool. Request type can be one of: l Reserve—related to queries l Acquire—[Internal] related to the optimizer and other internal services, such as the Database Designer l Acquire additional—[Internal] related to size adjustment of acquisitions obtained through the first two methods; unusual, outside the WOS POOL_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the resource pool. POOL_NAME VARCHAR Name of the resource pool. THREAD_COUNT INTEGER Number of threads in use by this request. OPEN_FILE_HANDLE_COUNT INTEGER Number of open file handles in use by this request. MEMORY_INUSE_KB INTEGER Amount of memory in kilobytes acquired by this request. See Notes section below this table. QUEUE_ENTRY_TIMESTAMP TIMESTAMPTZ Timestamp when the request was queued at the Resource Manager. ACQUISITION_TIMESTAMP TIMESTAMPTZ Timestamp when the request was admitted to run. See the Notes section below for the difference between these two timestamps. RELEASE_TIMESTAMP TIMESTAMPTZ Time when HP Vertica released this resource acquisition. DURATION_MS INTEGER Duration of the resource request in milliseconds. IS_EXECUTING BOOLEAN Denotes if the query holding the resource is still executing (t). HP Vertica Analytic Database (7.0.x) Page 1478 of 1539 SQL Reference Manual HP Vertica System Tables Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Notes l l The total memory reserved by the query is available in RESOURCE_ACQUISITIONS.MEMORY_ INUSE_KB. The difference between RESOURCE_ACQUISITIONS.MEMORY_INUSE_KB and QUERY_ PROFILES.EXTRA_MEMORY is the "essential memory." n RESOURCE_ACQUISITIONS.MEMORY_INUSE_KB is the total memory acquired. n QUERY_PROFILES.EXTRA_MEMORY is the unused portion of the acquired memory. n The difference gives you the memory in use. When monitoring resource pools and resource usage by queries, the “queue wait” time is the difference between acquisition_timestamp and queue_entry_timestamp. For example, to determine how long a query waits in the queue before it is admitted to run, you can get the difference between the acquisition_timestamp and the queue_entry_timestamp using a query like the following: => SELECT pool_name, queue_entry_timestamp, acquisition_timestamp, (acquisition_timestamp-queue_entry_timestamp) AS 'queue wait' FROM V_MONITOR.RESOURCE_ACQUISITIONS WHERE node_name ILIKE '%node0001'; l For the WOSDATA built-in pool, the queue_entry_timestamp column shows the time when data was first loaded into the WOS. The acquisition_timestamp reflects the last time the amount of data in the WOS changed. There is always a delay between when the data in WOS shrinks in size and when the resource system tables reflect the new size. Example vmartdb=> \x Expanded display is on. => SELECT * FROM resource_acquisitions; -[ RECORD 1 ]----------+-----------------------------node_name | v_onenode_node0001 transaction_id | 45035996273708628 statement_id | 1 request_type | Reserve pool_id | 45035996273718740 pool_name | sysquery thread_count | 4 open_file_handle_count | 2 memory_inuse_kb | 16384 queue_entry_timestamp | 2012-12-09 07:56:41.297533-05 HP Vertica Analytic Database (7.0.x) Page 1479 of 1539 SQL Reference Manual HP Vertica System Tables acquisition_timestamp | 2012-12-09 07:56:41.297536-05 release_timestamp | 2012-12-09 07:56:41.303201-05 duration_ms | 6 is_executing | f -[ RECORD 2 ]----------+-----------------------------... See Also l QUERY_PROFILES l RESOURCE_POOL_STATUS l RESOURCE_POOLS l RESOURCE_QUEUES l RESOURCE_REJECTIONS RESOURCE_POOL_STATUS Provides configuration settings of the various resource pools in the system, including internal pools. Column Name Data Type Description NODE_NAME VARCHAR The name of the node for which information is provided. POOL_OID INTEGER A unique numeric ID assigned by the HP Vertica catalog that identifies the pool. POOL_NAME VARCHAR The name of the resource pool. IS_INTERNAL BOOLEAN Denotes whether a pool is one of the Built-In Pools. MEMORY_SIZE_KB INTEGER Value of MEMORYSIZE setting of the pool in kilobytes MEMORY_SIZE_ACTUAL_KB INTEGER Current amount of memory in kilobytes allocated to the pool by the resource manager. Note that the actual size can be less than specified in the DDL, if the pool has been recently altered in a running system and the request to shuffle memory is pending. See ALTER RESOURCE POOL. MEMORY_INUSE_KB INTEGER Amount of memory in kilobytes acquired by requests running against this pool. HP Vertica Analytic Database (7.0.x) Page 1480 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description GENERAL_MEMORY_BORROWED_KB INTEGER Amount of memory in kilobytes borrowed from the General pool by requests running against this pool. The sum of MEMORY_INUSE_KB and GENERAL_ MEMORY_BORROWED_KB should be less than MAX_ MEMORY_SIZE_KB (see below). QUEUEING_THRESHOLD_KB INTEGER Calculated as MAX_MEMORY_SIZE_KB * 75%. When the amount of memory used by all requests against this queue exceed the QUEUEING_THRESHOLD_KB (but less than MAX_MEMORY_SIZE_KB), new requests against the pool will be queued until memory becomes available. MAX_MEMORY_SIZE_KB INTEGER Value of MAXMEMORYSIZE size parameter specified when defining the pool. Provides an upper limit on the amount of memory that can be taken up by requests running against this pool. Once this threshold is reached, new requests against this pool are rejected until memory becomes available. RUNNING_QUERY_COUNT INTEGER Number of queries actually running using this pool. PLANNED_CONCURRENCY INTEGER Value of PLANNEDCONCURRENCY parameter specified when defining the pool. MAX_CONCURRENCY INTEGER Value of MAXCONCURRENCY parameter specified when defining the pool. IS_STANDALONE BOOLEAN If the pool is configured to have MEMORYSIZE equal to MAXMEMORYSIZE, it does not borrow any memory from the General pool and hence said to be standalone. QUEUE_TIMEOUT_IN_SECONDS INTEGER Value of QUEUETIMEOUT parameter that was specified when defining the pool. HP Vertica Analytic Database (7.0.x) Page 1481 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description EXECUTION_PARALLELISM INTEGER [Default: AUTO] Limits the number of threads used to process any single query issued in this resource pool. When set to AUTO, HP Vertica sets this value based on the number of cores, available memory, and amount of data in the system. Unless data is limited, or the amount of data is very small, HP Vertica sets this value to the number of cores on the node. Reducing this value increases the throughput of short queries issued in the pool, especially if the queries are executed concurrently. If you choose to set this parameter manually, set it to a value between 1 and the number of cores. PRIORITY INTEGER Value of PRIORITY parameter specified when defining the pool. RUNTIME_PRIORITY VARCHAR Value of RUNTIME_PRIORITY specified when defining the pool. RUNTIME_PRIORITY_THRESHOLD INTEGER Value of RUNTIME_PRIORITY_THRESHOLD specified when defining the pool. SINGLE_INITIATOR BOOL Value of SINGLEINITIATOR parameter specified when defining the pool. QUERY_BUDGET_KB INTEGER The current amount of memory that queries are tuned to use. CPU_AFFINITY_SET VARCHAR The set of CPUs on which queries associated with this pool are executed. Can be a percentage of CPUs on the system, or zero-based list of CPUs (a four CPU system consists of CPUs 0, 1, 2, and 3). HP Vertica Analytic Database (7.0.x) Page 1482 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CPU_AFFINITY_MASK VARCHAR The bit mask of CPUs available for use in this pool. Values are encoded in hex and represent the binary value (read from right to left) for the CPUs on the system. For example, a pool that has exclusive use of CPUs 0 and 1 on a four CPU system is represented by the hex value of "3", which translates to "0011". The 1's indicate the that CPU 0 and 1 are available to this pool. Assuming no other resource pools are using exclusive CPU affinities, the remainder of the resource pools in the example above would have a mask of "3", which translates to "1100", and indicates that CPUs 2 and 3 of the four CPUs on the system are available to these resource pools. CPU_AFFINITY_MODE VARCHAR The mode for the CPU affinity. Values can be: l ANY - Any CPU not reserved as EXCLUSIVE by another pool. l EXCLUSIVE - Queries from this pool can only run on CPUs specified in CPU_AFFINITY_SET. These CPUs are reserved for exclusive use by this pool. l SHARED - Queries from this pool can only run on the CPUs specified in CPU_AFFINITY_SET. Other pools may also use the same CPUs in the set. Example The following command finds all the configuration settings of the various resource pools on node02: => SELECT * FROM resource_pool_status limit 2; -[ RECORD 1 ]--------------+-----------------node_name | v_db_node0001 pool_oid | 45035996273718660 pool_name | general is_internal | t memory_size_kb | 1265331 memory_size_actual_kb | 1265331 memory_inuse_kb | 0 general_memory_borrowed_kb | 0 queueing_threshold_kb | 1202064 max_memory_size_kb | 1265331 running_query_count | 0 planned_concurrency | 4 HP Vertica Analytic Database (7.0.x) Page 1483 of 1539 SQL Reference Manual HP Vertica System Tables max_concurrency | is_standalone | t queue_timeout_in_seconds | 300 execution_parallelism | AUTO priority | 0 runtime_priority | MEDIUM runtime_priority_threshold | 2 single_initiator | false query_budget_kb | 300516 cpu_affinity_set | cpu_affinity_mask | c cpu_affinity_mode | ANY -[ RECORD 2 ]--------------+-----------------node_name | v_db_node0001 pool_oid | 45035996273732654 pool_name | mypool is_internal | f memory_size_kb | 0 memory_size_actual_kb | 0 memory_inuse_kb | 0 general_memory_borrowed_kb | 0 queueing_threshold_kb | 1202064 max_memory_size_kb | 1265331 running_query_count | 0 planned_concurrency | 4 max_concurrency | is_standalone | f queue_timeout_in_seconds | 300 execution_parallelism | AUTO priority | 0 runtime_priority | MEDIUM runtime_priority_threshold | 2 single_initiator | false query_budget_kb | 300516 cpu_affinity_set | 0-1 cpu_affinity_mask | 3 cpu_affinity_mode | EXCLUSIVE See Also l CREATE RESOURCE POOL l RESOURCE_ACQUISITIONS l RESOURCE_POOLS l RESOURCE_QUEUES l RESOURCE_REJECTIONS l Managing Workload Resources l Monitoring Resource Pools and Resource Usage By Queries HP Vertica Analytic Database (7.0.x) Page 1484 of 1539 SQL Reference Manual HP Vertica System Tables RESOURCE_QUEUES Provides information about requests pending for various resource pools. Column Name Data Type Description NODE_NAME VARCHAR The name of the node for which information is listed. TRANSACTION_ID INTEGER Transaction identifier for this request STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID uniquely identifies a statement within a session. POOL_NAME VARCHAR The name of the resource pool MEMORY_REQUESTED_KB INTEGER Amount of memory in kilobytes requested by this request PRIORITY INTEGER Value of PRIORITY parameter specified when defining the pool. POSITION_IN_QUEUE INTEGER Position of this request within the pool’s queue QUEUE_ENTRY_TIMESTAMP TIMESTAMP Timestamp when the request was queued See Also l RESOURCE_ACQUISITIONS l RESOURCE_POOLS l RESOURCE_REJECTIONS RESOURCE_REJECTION_DETAILS Records an entry for each resource request that HP Vertica denies. This is useful for determining if there are resource space issues, as well as which users/pools encounter problems. Column Name Data Type REJECTED_TIMESTAMP TIMESTAMPTZ Time when HP Vertica rejected the resource. NODE_NAME VARCHAR HP Vertica Analytic Database (7.0.x) Description Name of the node that is reporting the requested information. Page 1485 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description USER_NAME VARCHAR Name of the user at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. REQUEST_ID INTEGER Unique identifier of the query request in the user session. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. STATEMENT_ID INTEGER Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID, STATEMENT_ID, and REQUEST_ID uniquely identifies a statement within a session. POOL_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the resource pool. POOL_NAME VARCHAR Name of the resource pool REASON VARCHAR Reason for rejecting this request; for example: HP Vertica Analytic Database (7.0.x) l Usage of single request exceeds high limit l Timed out waiting for resource reservation l Canceled waiting for resource reservation Page 1486 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description RESOURCE_TYPE VARCHAR Memory, threads, file handles or execution slots. The following list shows the resources that are limited by the resource manager. A query might need some amount of each resource, and if the amount needed is not available, the query is queued and could eventually time out of the queue and be rejected. l Number of running plans l Number of running plans on initiator node (local) l Number of requested threads l Number of requested file handles l Number of requested KB of memory l Number of requested KB of address space Note: Execution slots are determined by MAXCONCURRENCY parameter. REJECTED_VALUE INTEGER Amount of the specific resource requested by the last rejection Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. See Also l RESOURCE_REJECTIONS RESOURCE_REJECTIONS Monitors requests for resources that are rejected by the Resource Manager. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. POOL_ID INTEGER A unique numeric ID, assigned by the HP Vertica catalog, which identifies the resource pool. POOL_NAME VARCHAR The name of the resource pool. HP Vertica Analytic Database (7.0.x) Page 1487 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description REASON VARCHAR The reason for rejecting this request; for example: RESOURCE_TYPE VARCHAR l Usage of single request exceeds high limit l Timed out waiting for resource reservation l Canceled waiting for resource reservation Memory, threads, file handles or execution slots. The following list shows the resources that are limited by the resource manager. A query might need some amount of each resource, and if the amount needed is not available, the query is queued and could eventually time out of the queue and be rejected. l Number of running plans l Number of running plans on initiator node (local) l Number of requested threads l Number of requested file handles l Number of requested KB of memory l Number of requested KB of address space Note: Execution slots are determined by MAXCONCURRENCY parameter. REJECTION_COUNT INTEGER FIRST_REJECTED_TIMESTAMP TIMESTAMPTZ The time of the first rejection for this pool Number of requests rejected due to specified reason and RESOURCE_TYPE. Reasons for Rejection l Usage of single request exceeds high limit l Timed out waiting for resource reservation l Canceled waiting for resource reservation LAST_REJECTED_TIMESTAMP TIMESTAMPTZ The time of the last rejection for this pool LAST_REJECTED_VALUE INTEGER HP Vertica Analytic Database (7.0.x) The amount of the specific resource requested by the last rejection Page 1488 of 1539 SQL Reference Manual HP Vertica System Tables Notes Information is valid only as long as the node is up and the counters reset to 0 upon node restart. Example => SELECT node_name, pool_name, reason, resource_type, rejection_count AS count, last_rejected_value AS value FROM resource_rejections; node_name | pool_name | reason | resource_type | cou nt | value -----------+-------------+---------------------------------------+-------------------+-------------------------initiator | alsohassome | Request exceeded high limit | Memory(KB) | 1 | 102400 initiator | ceo | Timedout waiting for resource request | Memory(KB) | 1 | 102400 initiator | empty | Request exceeded high limit | Queries | 1 | 1 initiator | general | Request exceeded high limit | Address space(KB) | 2 | 45035996273704970 initiator | general | Request exceeded high limit | Memory(KB) | 24 | 8395584 initiator | sa | Request exceeded high limit | Memory(KB) | 3 | 102400 initiator | sa | Timedout waiting for resource request | Memory(KB) | 1 | 10 initiator | small | Request exceeded high limit | Memory(KB) | 26 | 102400 initiator | small | Timedout waiting for resource request | Memory(KB) | 2 | 122880 initiator | sysdata | Request exceeded high limit | Memory(KB) | 5 | 102400 (10 rows) The following command returns the type of resources currently running on the node: => SELECT resource_type FROM resource_rejections; resource_type --------------UPDATE_QUERY UPDATE_QUERY UPDATE_QUERY (3 rows) See Also l CLEAR_RESOURCE_REJECTIONS l DISK_RESOURCE_REJECTIONS HP Vertica Analytic Database (7.0.x) Page 1489 of 1539 SQL Reference Manual HP Vertica System Tables RESOURCE_USAGE Monitors system resource management on each node. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. REQUEST_COUNT INTEGER The cumulative number of requests for threads, file handles, and memory (in kilobytes). LOCAL_REQUEST_COUNT INTEGER The cumulative number of local requests. REQUEST_QUEUE_DEPTH INTEGER The current request queue depth. ACTIVE_THREAD_COUNT INTEGER The current number of active threads. OPEN_FILE_HANDLE_COUNT INTEGER The current number of open file handles. MEMORY_REQUESTED_KB INTEGER The memory requested in kilobytes. ADDRESS_SPACE_REQUESTED_KB INTEGER The address space requested in kilobytes. WOS_USED_BYTES INTEGER The size of the WOS in bytes. WOS_ROW_COUNT INTEGER The number of rows in the WOS. ROS_USED_BYTES INTEGER The size of the ROS in bytes. ROS_ROW_COUNT INTEGER The number of rows in the ROS. TOTAL_USED_BYTES INTEGER The total size of storage (WOS + ROS) in bytes. TOTAL_ROW_COUNT INTEGER The total number of rows in storage (WOS + ROS). RESOURCE_REQUEST_REJECT_COUNT INTEGER The number of rejected plan requests. RESOURCE_REQUEST_TIMEOUT_COUNT INTEGER The number of resource request timeouts. RESOURCE_REQUEST_CANCEL_COUNT INTEGER The number of resource request cancelations. DISK_SPACE_REQUEST_REJECT_COUNT INTEGER The number of rejected disk write requests. FAILED_VOLUME_REJECT_COUNT INTEGER The number of rejections due to a failed volume. TOKENS_USED INTEGER For internal use only. TOKENS_AVAILABLE INTEGER For internal use only. HP Vertica Analytic Database (7.0.x) Page 1490 of 1539 SQL Reference Manual HP Vertica System Tables Example =>\pset expanded Expanded display is on. => SELECT * FROM RESOURCE_USAGE; -[ RECORD 1 ]-------------------+--------------------------node_name | node01 request_count | 1 local_request_count | 1 request_queue_depth | 0 active_thread_count | 4 open_file_handle_count | 2 memory_requested_kb | 4352 address_space_requested_kb | 106752 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 10390319 ros_row_count | 324699 total_used_bytes | 10390319 total_row_count | 324699 resource_request_reject_count | 0 resource_request_timeout_count | 0 resource_request_cancel_count | 0 disk_space_request_reject_count | 0 failed_volume_reject_count | 0 tokens_used | 1 tokens_available | 7999999 -[ RECORD 2 ]-------------------+--------------------------node_name | node02 request_count | 0 local_request_count | 0 request_queue_depth | 0 active_thread_count | 0 open_file_handle_count | 0 memory_requested_kb | 0 address_space_requested_kb | 0 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 10359489 ros_row_count | 324182 total_used_bytes | 10359489 total_row_count | 324182 resource_request_reject_count | 0 resource_request_timeout_count | 0 resource_request_cancel_count | 0 disk_space_request_reject_count | 0 failed_volume_reject_count | 0 tokens_used | 0 tokens_available | 8000000 -[ RECORD 3 ]-------------------+--------------------------node_name | node03 request_count | 0 local_request_count | 0 request_queue_depth | 0 active_thread_count | 0 open_file_handle_count | 0 HP Vertica Analytic Database (7.0.x) Page 1491 of 1539 SQL Reference Manual HP Vertica System Tables memory_requested_kb | 0 address_space_requested_kb | 0 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 10355231 ros_row_count | 324353 total_used_bytes | 10355231 total_row_count | 324353 resource_request_reject_count | 0 resource_request_timeout_count | 0 resource_request_cancel_count | 0 disk_space_request_reject_count | 0 failed_volume_reject_count | 0 tokens_used | 0 tokens_available | 8000000 -[ RECORD 4 ]-------------------+--------------------------node_name | node04 request_count | 0 local_request_count | 0 request_queue_depth | 0 active_thread_count | 0 open_file_handle_count | 0 memory_requested_kb | 0 address_space_requested_kb | 0 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 10385744 ros_row_count | 324870 total_used_bytes | 10385744 total_row_count | 324870 resource_request_reject_count | 0 resource_request_timeout_count | 0 resource_request_cancel_count | 0 disk_space_request_reject_count | 0 failed_volume_reject_count | 0 tokens_used | 0 tokens_available | 8000000 SESSION_PROFILES Provides basic session parameters and lock time out data. To obtain information about sessions, see Profiling Database Performance. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. USER_NAME VARCHAR The name used to log in to the database or NULL if the session is internal. HP Vertica Analytic Database (7.0.x) Page 1492 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_HOSTNAME VARCHAR The host name and port of the TCP socket from which the client connection was made; NULL if the session is internal. LOGIN_TIMESTAMP TIMESTAMP The date and time the user logged into the database or when the internal session was created. This field is useful for identifying sessions that have been left open for a period of time and could be idle. LOGOUT_TIMESTAMP TIMESTAMP The date and time the user logged out of the database or when the internal session was closed. SESSION_ID VARCHAR A unique numeric ID assigned by the HP Vertica catalog, which identifies the session for which profiling information is captured. This identifier is unique within the cluster at any point in time but can be reused when the session closes. EXECUTED_STATEMENT_SUCCESS_COUNT INTEGER The number of successfully run statements. EXECUTED_STATEMENT_FAILURE_COUNT INTEGER The number of unsuccessfully run statements. LOCK_GRANT_COUNT INTEGER The number of locks granted during the session. DEADLOCK_COUNT INTEGER The number of deadlocks encountered during the session. LOCK_TIMEOUT_COUNT INTEGER The number of times a lock timed out during the session. LOCK_CANCELLATION_COUNT INTEGER The number of times a lock was canceled during the session. LOCK_REJECTION_COUNT INTEGER The number of times a lock was rejected during a session. LOCK_ERROR_COUNT INTEGER The number of lock errors encountered during the session. HP Vertica Analytic Database (7.0.x) Page 1493 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_TYPE VARCHAR The type of client from which the connection was made. Possible client type values: l ADO.NET Driver l ODBC Driver l JDBC Driver l vsql CLIENT_VERSION VARCHAR Returns the client version. CLIENT_OS VARCHAR Returns the client operating system. Example Query the SESSION_PROFILES Table: =>\pset expanded Expanded display on. => SELECT * FROM SESSION_PROFILES; -[ RECORD 1 ]-------------------+--------------------------------node_name | node04 user_name | dbadmin client_hostname | 192.168.1.1:46816 login_timestamp | 2009-09-28 11:40:34.01518 logout_timestamp | 2009-09-28 11:41:01.811484 session_id | myhost.verticacorp-20790:0x32f executed_statement_success_count | 51 executed_statement_failure_count | 1 lock_grant_count | 579 deadlock_count | 0 lock_timeout_count | 0 lock_cancellation_count | 0 lock_rejection_count | 0 lock_error_count | 0 client_type | vsql client_version | 07.00.0000 client_os | Linux 2.6.18-308.el5 x86_64 See Also l LOCKS SESSIONS Monitors external sessions. You can use this table to: HP Vertica Analytic Database (7.0.x) Page 1494 of 1539 SQL Reference Manual HP Vertica System Tables l Identify users who are running long queries l Identify users who are holding locks due to an idle but uncommitted transaction l Disconnect users in order to shut down the database l Determine the details behind the type of database security (Secure Socket Layer (SSL) or client authentication) used for a particular session l Identify client-specific information such as client version. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. USER_NAME VARCHAR The name used to log into the database or NULL if the session is internal. CLIENT_HOSTNAME VARCHAR The host name and port of the TCP socket from which the client connection was made; NULL if the session is internal. CLIENT_PID INTEGER The process identifier of the client process that issued this connection. Remember that the client process could be on a different machine than the server. LOGIN_TIMESTAMP TIMESTAMP The date and time the user logged into the database or when the internal session was created. This can be useful for identifying sessions that have been left open for a period of time and could be idle. SESSION_ID VARCHAR The identifier required to close or interrupt a session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. CLIENT_LABEL VARCHAR A user-specified label for the client connection that can be set when using ODBC. See Label in DSN Parameters in Programmer's Guide. An MC output value means there are is a client connection to an MC-managed database for that USER_NAME TRANSACTION_START DATE The date/time the current transaction started or NULL if no transaction is running. TRANSACTION_ID INTEGER A string containing the hexadecimal representation of the transaction ID, if any; otherwise NULL. HP Vertica Analytic Database (7.0.x) Page 1495 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description TRANSACTION_DESCRIPTION VARCHAR A description of the current transaction. STATEMENT_START TIMESTAMP The timestamp the current statement started execution, or NULL if no statement is running. STATEMENT_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the currently-executing statement. Note: NULL indicates that no statement is currently being processed. LAST_STATEMENT_DURATION_US INTEGER The duration of the last completed statement in microseconds. RUNTIME_PRIORITY VARCHAR Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to queries already running in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. CURRENT_STATEMENT VARCHAR The currently executing statement, if any. NULL indicates that no statement is currently being processed. LAST_STATEMENT VARCHAR NULL if the user has just logged in; otherwise the currently running statement or the most recently completed statement. HP Vertica Analytic Database (7.0.x) Page 1496 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description SSL_STATE VARCHAR Indicates if HP Vertica used Secure Socket Layer (SSL) for a particular session. Possible values are: l None – HP Vertica did not use SSL. l Server – Sever authentication was used, so the client could authenticate the server. l Mutual – Both the server and the client authenticated one another through mutual authentication. See Implementing Security and Implementing SSL. AUTHENTICATION_METHOD VARCHAR The type of client authentication used for a particular session, if known. Possible values are: l Unknown l Trust l Reject l Kerberos l Password l MD5 l LDAP l Kerberos-GSS See Implementing Security and Implementing Client Authentication. CLIENT_TYPE VARCHAR HP Vertica Analytic Database (7.0.x) The type of client from which the connection was made. Possible client type values: l ADO.NET Driver l ODBC Driver l JDBC Driver l vsql Page 1497 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_VERSION VARCHAR Returns the client version. CLIENT_OS VARCHAR Returns the client operating system. Notes l A superuser has unrestricted access to all session information, but users can only view information about their own, current sessions. l During session initialization and termination, you might see sessions running only on nodes other than the node on which you ran the virtual table query. This is a temporary situation that corrects itself as soon as session initialization and termination completes. Example =>\pset expanded Expanded display is on. => SELECT * FROM SESSIONS; -[ RECORD 1 ]--------------+--------------------------------------node_name | v_mcdb_node0001 user_name | dbadmin client_hostname | 00.00.000.00:xxxxx client_pid | 12345 login_timestamp | 2013-05-09 07:18:11.161721-04 session_id | myhost.verticacorp.-7695:0x4f337 client_label | MC transaction_start | 2013-05-09 07:18:16.051058-04 transaction_id | 49539595901174387 transaction_description | user dbadmin (select * from sessions;) statement_start | 2013-05-09 07:18:19.54812-04 statement_id | 2 last_statement_duration_us | 16508 runtime_priority | current_statement | select * from sessions; last_statement | select * from sessions; ssl_state | None authentication_method | Password See Also l CLOSE_SESSION l CLOSE_ALL_SESSIONS STORAGE_CONTAINERS Monitors information about WOS and ROS storage containers in the database. HP Vertica Analytic Database (7.0.x) Page 1498 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR Node name for which information is listed. SCHEMA_NAME VARCHAR Schema name for which information is listed. PROJECTION_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR Projection name for which information is listed on that node. STORAGE_TYPE VARCHAR Type of storage container: ROS or WOS. STORAGE_OID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the storage. TOTAL_ROW_COUNT VARCHAR Total rows in the storage container listed for that projection. DELETED_ROW_COUNT INTEGER Total rows in the storage container deleted for that projection. USED_BYTES INTEGER Total bytes in the storage container listed for that projection. START_EPOCH INTEGER Number of the start epoch in the storage container for which information is listed. END_EPOCH INTEGER Number of the end epoch in the storage container for which information is listed. GROUPING VARCHAR The group by which columns are stored: l ALL—All columns are grouped l PROJECTION—Columns grouped according to projection definition l NONE—No columns grouped, despite grouping in the projection definition l OTHER—Some grouping but neither all nor according to projection (e.g., results from add column) SEGMENT_LOWER_BOUND INTEGER Lower bound of the segment range spanned by the storage container or NULL if the corresponding projection is not elastic. SEGMENT_UPPER_BOUND INTEGER Upper bound of the segment range spanned by the storage container or NULL if the corresponding projection is not elastic. IS_SORTED BOOLEAN Whether the storage container's data is sorted (WOS containers only). HP Vertica Analytic Database (7.0.x) Page 1499 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description LOCATION_LABEL VARCHAR (128) The location label (if any) for the storage container is stored. DELETE_VECTOR_COUNT INTEGER The number of delete vectors in the storage container. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example The following command returns all the nodes on which a segmented projection has data on the TickStore database: TickStore=> SELECT node_name, projection_name, total_row_count FROM storage_containers ORDER BY projection_name; node_name | projection_name | total_row_count -----------------+--------------------------+----------------v_tick_node0001 | Quotes_Fact_tmp_node0001 | 512 v_tick_node0001 | Quotes_Fact_tmp_node0001 | 480176 v_tick_node0002 | Quotes_Fact_tmp_node0002 | 512 v_tick_node0002 | Quotes_Fact_tmp_node0002 | 480176 v_tick_node0003 | Quotes_Fact_tmp_node0003 | 480176 v_tick_node0003 | Quotes_Fact_tmp_node0003 | 512 v_tick_node0004 | Quotes_Fact_tmp_node0004 | 480176 v_tick_node0004 | Quotes_Fact_tmp_node0004 | 512 v_tick_node0001 | Trades_Fact_tmp_node0001 | 512 v_tick_node0001 | Trades_Fact_tmp_node0001 | 500334 v_tick_node0002 | Trades_Fact_tmp_node0002 | 500334 v_tick_node0002 | Trades_Fact_tmp_node0002 | 512 v_tick_node0003 | Trades_Fact_tmp_node0003 | 500334 v_tick_node0003 | Trades_Fact_tmp_node0003 | 512 v_tick_node0004 | Trades_Fact_tmp_node0004 | 500334 v_tick_node0004 | Trades_Fact_tmp_node0004 | 512 (16 rows) The following command returns information on inventory_fact projections on all nodes on the Vmart schema: => SELECT * FROM storage_containers WHERE projection_name LIKE 'inventory_fact_p%'; -[ RECORD 1 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | WOS storage_oid | 45035996273720173 total_row_count | 3000 HP Vertica Analytic Database (7.0.x) Page 1500 of 1539 SQL Reference Manual HP Vertica System Tables deleted_row_count | 100 used_bytes | 196608 start_epoch | 1 end_epoch | 2 grouping | ALL -[ RECORD 2 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS storage_oid | 45035996273722211 total_row_count | 500 deleted_row_count | 25 used_bytes | 5838 start_epoch | 1 end_epoch | 1 grouping | ALL -[ RECORD 3 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS storage_oid | 45035996273722283 total_row_count | 500 deleted_row_count | 25 used_bytes | 5794 start_epoch | 1 end_epoch | 1 grouping | ALL -[ RECORD 4 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS storage_oid | 45035996273723379 total_row_count | 500 deleted_row_count | 25 used_bytes | 5838 start_epoch | 1 end_epoch | 1 grouping | ALL -[ RECORD 5 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS storage_oid | 45035996273723451 total_row_count | 500 deleted_row_count | 25 used_bytes | 5794 start_epoch | 1 end_epoch | 1 grouping | ALL -[ RECORD 6 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS HP Vertica Analytic Database (7.0.x) Page 1501 of 1539 SQL Reference Manual HP Vertica System Tables storage_oid | 45035996273724547 total_row_count | 500 deleted_row_count | 0 used_bytes | 5838 start_epoch | 2 end_epoch | 2 grouping | ALL -[ RECORD 7 ]-----+-------------------------node_name | node01 schema_name | public projection_name | inventory_fact_p_node0001 storage_type | ROS storage_oid | 45035996273724619 total_row_count | 500 deleted_row_count | 0 used_bytes | 5794 start_epoch | 2 end_epoch | 2 grouping | ALL -[ RECORD 8 ]-----+-------------------------... STORAGE_POLICIES Monitors the current storage policies in effect for one or more database objects. Column Name Data Type Description SCHEMA_NAME VARCHAR Schema name for which information is listed. OBJECT_NAME VARCHAR The name of the database object associated through the storage policy. POLICY_DETAILS VARCHAR The object type of the storage policy. LOCATION_LABEL VARCHAR (128) The label for this storage location. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example The following query returns the current storage polices: VMART=> select * from v_monitor.storage_policies; schema_name | object_name | policy_details | location_label HP Vertica Analytic Database (7.0.x) Page 1502 of 1539 SQL Reference Manual HP Vertica System Tables -------------+-------------+----------------+---------------public | states | Table | LEVEL3 public | newstates | Table | LEVEL3 (2 rows) See Also l PARTITIONS l STORAGE_CONTAINERS l STORAGE_USAGE STORAGE_TIERS Provides information about all storage locations with the same label across all cluster nodes. This table lists data totals for all same-name labeled locations. The system table shows what labeled locations exist on the cluster, as well as other cluster-wide data about the locations. Column Name Data Type Description LOCATION_LABEL VARCHAR The label associated with a specific storage location. The storage_tiers system table includes data totals for unlabeled locations, which are considered labeled with empty strings (''). NODE_COUNT INTEGER The total number of nodes that include a storage location named location_label. LOCATION_COUNT INTEGER The total number of storage locations named location_ label. This value can differ from node_count if you create labeled locations with the same name at different paths on different nodes. For example: node01: Create one labeled location, FAST node02: Create two labeled locations, FAST, at different directory paths In this case, node_count value = 2, while location_count value = 3. ROS_CONTAINER_COUNT INTEGER The total number of ROS containers stored across all cluster nodes for location_label. TOTAL_OCCUPIED_SIZE INTEGER The total number of bytes that all ROS containers for location_label occupy across all cluster nodes. HP Vertica Analytic Database (7.0.x) Page 1503 of 1539 SQL Reference Manual HP Vertica System Tables Permissions Must be a superuser. Example VMart=> select * from v_monitor.storage_tiers; location_label | node_count | location_count | ros_container_count | total_occupied_size ----------------+------------+----------------+---------------------+-------------------| 1 | 2 | 17 | 297039391 SSD | 1 | 1 | 9 | 1506 Schema | 1 | 1 | 0 | 0 (3 rows) See Also l DISK_STORAGE l STORAGE_POLICIES l STORAGE_USAGE l Storage Management Functions STORAGE_USAGE Provides information about file system storage usage. This is useful for determining disk space usage trends. Column Name Data Type POLL_TIMESTAMP TIMESTAMPTZ Time when HP Vertica recorded the row. NODE_NAME VARCHAR Name of the node that is reporting the requested information. PATH VARCHAR Path where the storage location is mounted. DEVICE VARCHAR Device on which the storage location is mounted. FILESYSTEM VARCHAR Filesystem on which the storage location is mounted. USED_BYTES INTEGER Counter history of number of used bytes. FREE_BYTES INTEGER Counter history of number of free bytes. USAGE_PERCENT FLOAT Percent of storage in use. HP Vertica Analytic Database (7.0.x) Description Page 1504 of 1539 SQL Reference Manual HP Vertica System Tables Permissions Must be a superuser. Example => \x Expanded display is on. => select * from storage_usage; -[ RECORD 1 ]--+-----------------------------poll_timestamp | 2013-12-05 15:55:43.011662-08 node_name | v_vmart_node0001 path | device | filesystem | vertica used_bytes | 10964557824 free_bytes | 45094535168 usage_percent | 19.56 -[ RECORD 2 ]--+-----------------------------poll_timestamp | 2013-12-05 15:55:43.011659-08 node_name | v_vmart_node0001 path | /boot device | /dev/sda1 filesystem | ext3 used_bytes | 32920576 free_bytes | 269733888 usage_percent | 10.88 -[ RECORD 3 ]--+-----------------------------poll_timestamp | 2013-12-05 15:55:43.011651-08 node_name | v_vmart_node0001 path | / device | /dev/root filesystem | ext3 used_bytes | 10964557824 free_bytes | 45094535168 usage_percent | 19.56 (3 rows) See Also l DISK_STORAGE l STORAGE_CONTAINERS l STORAGE_POLICIES l STORAGE_TIERS l Storage Management Functions HP Vertica Analytic Database (7.0.x) Page 1505 of 1539 SQL Reference Manual HP Vertica System Tables STRATA Contains internal details of how the Tuple Mover combines ROS containers in each projection, broken down by stratum and classifies the ROS containers by size and partition. The related STRATA_STRUCTURES table provides a summary of the strata values. The STRATA table contains detailed information on For a brief overview of how the Tuple Mover combines ROS containers, see Tuple Mover in the Administrator's Guide. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed SCHEMA_NAME VARCHAR The schema name for which information is listed PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PROJECTION_NAME VARCHAR The projection name for which information is listed on that node PARTITION_KEY VARCHAR The data partition for which information is listed STRATA_COUNT INTEGER The total number of strata for this projection partition MERGING_STRATA_COUNT INTEGER The number of strata the Tuple Mover can merge out. STRATUM_CAPACITY INTEGER The maximum number of ROS containers for the stratum before they must be merged. STRATUM_HEIGHT FLOAT The size ratio between the smallest and largest ROS container in this stratum STRATUM_NO INTEGER The stratum number. Strata are numbered starting at 0, for the stratum containing the smallest ROS containers STRATUM_LOWER_SIZE VARCHAR The smallest ROS container size allowed in this stratum STRATUM_UPPER_SIZE VARCHAR The largest ROS container size allowed in this stratum ROS_CONTAINER_COUNT INTEGER The current number of ROS containers in the projection partition Example onenode=> SELECT * FROM strata; -[ RECORD 1 ]--------+------------------node_name | v_onenode_node0001 schema_name | public HP Vertica Analytic Database (7.0.x) Page 1506 of 1539 SQL Reference Manual HP Vertica System Tables projection_id | 45035996273718838 projection_name | trades_p partition_key | strata_count | 11 merging_strata_count | 4 stratum_capacity | 32 stratum_height | 28.8 stratum_no | 0 stratum_lower_size | 0B stratum_upper_size | 4MB ROS_container_count | 1 vmartdb=> \pset expanded Expanded display is on. vmartdb=> SELECT node_name, schema_name, projection_name, strata_count, stratum_capacity, stratum_height, stratum_no, stratum_lower_size, stratum_upper_size, ros_container_count FROM strata WHERE node_name ILIKE 'node01' AND stratum_upper_size < '15MB'; -[ RECORD 1 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | online_sales projection_name | call_center_dimension_DBD_32_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 19 stratum_height | 8.97589786696783 stratum_no | 0 stratum_lower_size | 0B stratum_upper_size | 13MB ROS_container_count | 1 -[ RECORD 2 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | online_sales projection_name | call_center_dimension_DBD_8_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 19 stratum_height | 8.97589786696783 stratum_no | 0 stratum_lower_size | 0B stratum_upper_size | 13MB ROS_container_count | 1 -[ RECORD 3 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | online_sales projection_name | online_sales_fact_DBD_33_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 13 stratum_height | 8.16338338718601 stratum_no | 1 stratum_lower_size | 19MB stratum_upper_size | 155.104MB ROS_container_count | 1 -[ RECORD 4 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | online_sales projection_name | online_sales_fact_DBD_9_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 13 stratum_height | 8.16338338718601 stratum_no | 1 HP Vertica Analytic Database (7.0.x) Page 1507 of 1539 SQL Reference Manual HP Vertica System Tables stratum_lower_size | 19MB stratum_upper_size | 155.104MB ROS_container_count | 1 -[ RECORD 5 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | public projection_name | promotion_dimension_DBD_16_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 19 stratum_height | 8.97589786696783 stratum_no | 0 stratum_lower_size | 0B stratum_upper_size | 13MB ROS_container_count | 1 -[ RECORD 6 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | public projection_name | promotion_dimension_DBD_17_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 19 stratum_height | 8.97589786696783 stratum_no | 0 stratum_lower_size | 0B stratum_upper_size | 13MB ROS_container_count | 1 -[ RECORD 7 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | store projection_name | store_sales_fact_DBD_29_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 16 stratum_height | 8.52187248329035 stratum_no | 1 stratum_lower_size | 16MB stratum_upper_size | 136.35MB ROS_container_count | 1 -[ RECORD 8 ]-------+----------------------------------------------------------node_name | v_vmartdb_node01 schema_name | store projection_name | store_sales_fact_DBD_5_seg_vmart_design_vmart_design strata_count | 5 stratum_capacity | 16 stratum_height | 8.52187248329035 stratum_no | 1 stratum_lower_size | 16MB stratum_upper_size | 136.35MB ROS_container_count | 1 STRATA_STRUCTURES This table provides an overview of Tuple Mover internal details. It summarizes how the ROS containers are classified by size. A more detailed view can be found in the STRATA virtual table. HP Vertica Analytic Database (7.0.x) Page 1508 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed SCHEMA_NAME VARCHAR The schema name for which information is listed PROJECTION_NAME VARCHAR The projection name for which information is listed on that node PROJECTION_ID INTEGER A unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. PARTITION_KEY VARCHAR The data partition for which the information is listed STRATA_COUNT INTEGER The total number of strata for this projection partition MERGING_STRATA_COUNT INTEGER In certain hardware configurations, a high strata could contain more ROS containers than the Tuple Mover can merge out; output from this column denotes the number of strata the Tuple Mover can merge out. STRATUM_CAPACITY INTEGER The maximum number of ROS containers that the strata can contained before it must merge them STRATUM_HEIGHT FLOAT The size ratio between the smallest and largest ROS container in a stratum. ACTIVE_STRATA_COUNT INTEGER The total number of strata that have ROS containers in them Example onenode=> SELECT * FROM strata_structures; -[ RECORD 1 ]--------+------------------node_name | v_onenode_node0001 schema_name | public projection_name | trades_p projection_id | 45035996273718838 partition_key | strata_count | 11 merging_strata_count | 4 stratum_capacity | 32 stratum_height | 28.8 active_strata_count | 1 vmartdb=> \pset expanded Expanded display is on. vmartdb=> SELECT node_name, schema_name, projection_name, strata_count, stratum_capacity, stratum_height, stratum_no, stratum_lower_size, stratum_upper_size, ros_container_count WHERE stratum_capacity > 60; -[ RECORD 1 ]-------+-------------------------------------------------------node_name | v_vmartdb_node01 schema_name | public HP Vertica Analytic Database (7.0.x) Page 1509 of 1539 SQL Reference Manual HP Vertica System Tables projection_name | shipping_dimension_DBD_22_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 2 ]-------+-------------------------------------------------------node_name | v_vmartdb_node01 schema_name | public projection_name | shipping_dimension_DBD_23_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 3 ]-------+-------------------------------------------------------node_name | v_vmartdb_node02 schema_name | public projection_name | shipping_dimension_DBD_22_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 4 ]-------+-------------------------------------------------------node_name | v_vmartdb_node02 schema_name | public projection_name | shipping_dimension_DBD_23_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 5 ]-------+-------------------------------------------------------node_name | v_vmartdb_node03 schema_name | public projection_name | shipping_dimension_DBD_22_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 6 ]-------+-------------------------------------------------------node_name | v_vmartdb_node03 schema_name | public projection_name | shipping_dimension_DBD_23_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 7 ]-------+-------------------------------------------------------node_name | v_vmartdb_node04 schema_name | public projection_name | shipping_dimension_DBD_22_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 HP Vertica Analytic Database (7.0.x) Page 1510 of 1539 SQL Reference Manual HP Vertica System Tables stratum_height | 25.6511590887058 active_strata_count | 1 -[ RECORD 8 ]-------+-------------------------------------------------------node_name | v_vmartdb_node04 schema_name | public projection_name | shipping_dimension_DBD_23_seg_vmart_design_vmart_design partition_key | strata_count | 4 stratum_capacity | 62 stratum_height | 25.6511590887058 active_strata_count | 1 See Also l STRATA SYSTEM Monitors the overall state of the database. Column Name Data Type Description CURRENT_EPOCH INTEGER The current epoch number. AHM_EPOCH INTEGER The AHM epoch number. LAST_GOOD_EPOCH INTEGER The smallest (min) of all the checkpoint epochs on the cluster. REFRESH_EPOCH INTEGER The oldest of the refresh epochs of all the nodes in the cluster DESIGNED_FAULT_TOLERANCE INTEGER The designed or intended K-safety level. NODE_COUNT INTEGER The number of nodes in the cluster. NODE_DOWN_COUNT INTEGER The number of nodes in the cluster that are currently down. CURRENT_FAULT_TOLERANCE INTEGER The number of node failures the cluster can tolerate before it shuts down automatically. CATALOG_REVISION_NUMBER INTEGER The catalog version number. WOS_USED_BYTES INTEGER The WOS size in bytes (cluster-wide). WOS_ROW_COUNT INTEGER The number of rows in WOS (cluster-wide). ROS_USED_BYTES INTEGER The ROS size in bytes (cluster-wide). HP Vertica Analytic Database (7.0.x) Page 1511 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description ROS_ROW_COUNT INTEGER The number of rows in ROS (cluster-wide). TOTAL_USED_BYTES INTEGER The total storage in bytes (WOS + ROS) (cluster-wide). TOTAL_ROW_COUNT INTEGER The total number of rows (WOS + ROS) (cluster-wide). Example Query the SYSTEM table: =>\pset expanded Expanded display is on. => SELECT * FROM SYSTEM; -[ RECORD 1 ]------------+---------current_epoch | 429 ahm_epoch | 428 last_good_epoch | 428 refresh_epoch | -1 designed_fault_tolerance | 1 node_count | 4 node_down_count | 0 current_fault_tolerance | 1 catalog_revision_number | 1590 wos_used_bytes | 0 wos_row_count | 0 ros_used_bytes | 443131537 ros_row_count | 21809072 total_used_bytes | 443131537 total_row_count | 21809072 If there are no projections in the system, LAST_GOOD_EPOCH returns the following: => SELECT get_last_good_epoch(); ERROR: Last good epoch not set And if there are projections in the system: => SELECT get_last_good_epoch(); get_last_good_epoch --------------------428 (1 row) SYSTEM_RESOURCE_USAGE Provides history about system resources, such as memory, CPU, network, disk, I/O. HP Vertica Analytic Database (7.0.x) Page 1512 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. END_TIME TIMESTAMP End time of the history interval. AVERAGE_MEMORY_USAGE_PERCENT FLOAT Average memory usage in percent of total memory (0-100) during the history interval. AVERAGE_CPU_USAGE_PERCENT FLOAT Average CPU usage in percent of total CPU time (0-100) during the history interval. NET_RX_KBYTES_PER_SECOND FLOAT Average number of kilobytes received from network (incoming) per second during the history interval. NET_TX_KBYTES_PER_SECOND FLOAT Average number of kilobytes transmitting to network (outgoing) per second during the history interval. IO_READ_KBYTES_PER_SECOND FLOAT Disk I/O average number of kilobytes read from disk per second during the history interval. IO_WRITTEN_KBYTES_PER_SECOND FLOAT Average number of kilobytes written to disk per second during the history interval. Permissions Must be a superuser. Example => SELECT * FROM system_resource_usage WHERE node_name = 'v_myvdb_node04'; -[ RECORD 1 ]----------------+-------------------node_name | v_myvdb_node04 end_time | 2012-03-30 17:43:00 average_memory_usage_percent | 3.6 average_cpu_usage_percent | 9.1 net_rx_kbytes_per_second | 12.75 net_tx_kbytes_per_second | 5.77 io_read_kbytes_per_second | 0 io_written_kbytes_per_second | 643.92 -[ RECORD 2 ]----------------+-------------------node_name | v_myvdb_node04 end_time | 2012-03-30 17:38:00 average_memory_usage_percent | 3.59 average_cpu_usage_percent | 10.4 net_rx_kbytes_per_second | 5.78 net_tx_kbytes_per_second | 0.88 io_read_kbytes_per_second | 0 io_written_kbytes_per_second | 650.28 HP Vertica Analytic Database (7.0.x) Page 1513 of 1539 SQL Reference Manual HP Vertica System Tables -[ RECORD 3 ]----------------+-------------------node_name | v_myvdb_node04 end_time | 2012-03-30 17:37:00 average_memory_usage_percent | 3.59 average_cpu_usage_percent | 8.47 net_rx_kbytes_per_second | 5.41 net_tx_kbytes_per_second | 0.77 io_read_kbytes_per_second | 0 io_written_kbytes_per_second | 621.39 -[ RECORD 4 ]----------------+-------------------node_name | v_myvdb_node04 end_time | 2012-03-30 17:31:00 average_memory_usage_percent | 3.59 average_cpu_usage_percent | 12.35 net_rx_kbytes_per_second | 5.71 net_tx_kbytes_per_second | 0.87 io_read_kbytes_per_second | 0 io_written_kbytes_per_second | 647.06 -[ RECORD 5 ]----------------+-------------------node_name | v_myvdb_node04 end_time | 2012-03-30 17:29:00 average_memory_usage_percent | 3.59 average_cpu_usage_percent | 8.52 net_rx_kbytes_per_second | 5.56 net_tx_kbytes_per_second | 0.81 io_read_kbytes_per_second | 0 io_written_kbytes_per_second | 631.21 ... SYSTEM_SERVICES Provides information about background system services that the Workload Analyzer monitors. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. SERVICE_TYPE VARCHAR Type of service; can be one of: l SYSTEM l TUPLE MOVER SERVICE_GROUP VARCHAR Group name, if there are multiple services of the same type. SERVICE_NAME VARCHAR Name of the service. SERVICE_INTERVAL_SEC INTEGER How often the service is executed (in seconds) during the history interval. HP Vertica Analytic Database (7.0.x) Page 1514 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_ENABLED BOOLEAN Denotes if the service is enabled. LAST_RUN_START TIMESTAMPTZ Denotes when the service was started last time. LAST_RUN_END TIMESTAMPTZ Denotes when the service was completed last time. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM system_services; -[ RECORD 1 ]--------+-----------------------------node_name | v_myvdb_node0004 service_type | System service_group | service_name | Ageout Session Profiling Data service_interval_sec | 86400 is_enabled | t last_run_start | 2012-04-03 11:36:54.001782-04 last_run_end | 2012-04-03 11:36:54.001793-04 -[ RECORD 2 ]--------+-----------------------------node_name | v_myvdb_node0004 service_type | System service_group | service_name | AgeOutEvents service_interval_sec | 3 is_enabled | t last_run_start | 2012-04-03 14:41:24.001538-04 last_run_end | 2012-04-03 14:41:24.001544-04 -[ RECORD 3 ]--------+-----------------------------node_name | v_myvdb_node0004 service_type | System service_group | service_name | CatalogCheckpointer service_interval_sec | 86400 is_enabled | t last_run_start | 2012-04-03 11:36:54.001788-04 last_run_end | 2012-04-03 11:36:54.002721-04 -[ RECORD 4 ]--------+-----------------------------node_name | v_myvdb_node0004 service_type | System service_group | service_name | Cluster Inviter service_interval_sec | 2 is_enabled | t last_run_start | 2012-04-03 14:41:25.002031-04 last_run_end | 2012-04-03 14:41:25.002671-04 -[ RECORD 5 ]--------+-----------------------------... HP Vertica Analytic Database (7.0.x) Page 1515 of 1539 SQL Reference Manual HP Vertica System Tables => SELECT service_type, last_run_start, last_run_end FROM system_services; service_type | last_run_start | last_run_end --------------+-------------------------------+------------------------------System | | System | 2012-03-01 08:10:05.010077-05 | 2012-03-01 08:10:05.010081-05 System | | System | 2012-03-01 08:10:06.003775-05 | 2012-03-01 08:10:06.00499-05 System | 2012-03-01 07:27:05.004958-05 | 2012-03-01 07:27:05.005376-05 System | 2012-03-01 06:32:45.001812-05 | 2012-03-01 06:32:45.002249-05 System | | System | 2012-03-01 08:10:05.006397-05 | 2012-03-01 08:10:05.006399-05 System | 2012-03-01 06:29:05.000905-05 | 2012-03-01 06:29:05.001517-05 System | 2012-03-01 08:10:05.006213-05 | 2012-03-01 08:10:05.006215-05 System | 2012-03-01 08:10:05.006379-05 | 2012-03-01 08:10:05.007055-05 System | 2012-03-01 08:10:05.009981-05 | 2012-03-01 08:10:05.009983-05 System | 2012-03-01 08:10:05.00988-05 | 2012-03-01 08:10:05.009882-05 Tuple Mover | 2012-03-01 08:10:05.006673-05 | 2012-03-01 08:10:05.006675-05 Tuple Mover | 2012-03-01 08:07:05.006837-05 | 2012-03-01 08:07:05.009541-05 Tuple Mover | 2012-03-01 08:09:05.001376-05 | 2012-03-01 08:09:05.001378-05 Tuple Mover | 2012-03-01 07:17:05.000908-05 | 2012-03-01 07:17:05.015156-05 Tuple Mover | 2012-03-01 08:07:05.00679-05 | 2012-03-01 08:07:05.007486-05 Tuple Mover | 2012-03-01 08:07:05.006673-05 | 2012-03-01 08:07:05.010128-05 Tuple Mover | 2012-03-01 08:07:05.002946-05 | 2012-03-01 08:07:05.010192-05 Tuple Mover | 2012-03-01 08:07:05.002946-05 | 2012-03-01 08:07:05.010192-05 Tuple Mover | 2012-03-01 08:07:05.002962-05 | 2012-03-01 08:07:05.007198-05 SYSTEM_SESSIONS Provides information about system internal session history by system task. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_NAME VARCHAR Name of the user at the time HP Vertica recorded the session. SESSION_ID INTEGER Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any. If a session is active but no transaction has begun, TRANSACTION_ID returns NULL. STATEMENT_ID VARCHAR Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID and STATEMENT_ID uniquely identifies a statement within a session. HP Vertica Analytic Database (7.0.x) Page 1516 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description SESSION_TYPE VARCHAR Session type. Can be one of: RUNTIME_PRIORITY VARCHAR l LICENSE_AUDIT l STARTUP l SHUTDOWN l VSPREAD Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to queries already running in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. DESCRIPTION VARCHAR SESSION_START_TIMESTAMP TIMESTAMPTZ Value of session at beginning of history interval. SESSION_END_TIMESTAMP TIMESTAMPTZ Value of session at end of history interval. IS_ACTIVE BOOLEAN Denotes if the session is still running. SESSION_DURATION_MS INTEGER Duration of the session in milliseconds. CLIENT_TYPE VARCHAR CLIENT_VERSION VARCHAR CLIENT_OS VARCHAR Columns not used in SYSTEM_SESSIONS system table. To view values for these columns, see the V_MONITOR schema system tables SESSIONS, USER_SESSIONS, CURRENT_ SESSION, and SESSION_PROFILES. Transaction description in this session. Permissions Must be a superuser.. Example => \x HP Vertica Analytic Database (7.0.x) Page 1517 of 1539 SQL Reference Manual HP Vertica System Tables Expanded display is on. => SELECT * FROM system_sessions;-[ RECORD 1 ]-----------+-----------------------------------------------------node_name | v_vmart_node0002 user_name | dbadmin session_id | xxxx02.verticacorp.-23295:0x2b7 transaction_id | 49539595901220372 statement_id | session_type | MERGEOUT runtime_priority | description | Txn: b0000000023614 'Mergeout: Tuple Mover' session_start_timestamp | 2012-12-10 06:41:03.025615-05 session_end_timestamp | 2012-12-10 06:41:03.030063-05 is_active | f session_duration_ms | 1 client_type | client_version | client_os | -[ RECORD 2 ]-----------+------------------------------------------------------node_name | v_vmart_node0003 user_name | dbadmin session_id | xxxx03.verticacorp.-22620:0x2bd transaction_id | 54043195528590868 statement_id | session_type | MOVEOUT runtime_priority | description | Txn: c0000000023614 'Moveout: Tuple Mover' session_start_timestamp | 2012-12-10 06:41:03.007496-05 session_end_timestamp | 2012-12-10 06:41:03.00844-05 is_active | f session_duration_ms | 1 client_type | client_version | client_os | -[ RECORD 3 ]-----------+------------------------------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | xxxx01.verticacorp.-30972:0x1f3 transaction_id | 45035996273960317 statement_id | session_type | REBALANCE_CLUSTER runtime_priority | description | Txn: a000000003e57d 'rebalance_cluster(background)' session_start_timestamp | 2012-12-10 06:37:26.015479-05 session_end_timestamp | 2012-12-10 06:37:26.033779-05 is_active | f session_duration_ms | 13 client_type | client_version | client_os | -[ RECORD 4 ]-----------+------------------------------------------------------... HP Vertica Analytic Database (7.0.x) Page 1518 of 1539 SQL Reference Manual HP Vertica System Tables See Also l CURRENT_SESSION l SESSION_PROFILES l SESSIONS l USER_SESSIONS TRANSACTIONS Records the details of each transaction. Column Name Data Type START_TIMESTAMP TIMESTAMPTZ Beginning of history interval. END_TIMESTAMP TIMESTAMPTZ End of history interval. NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_ID INTEGER Unique numeric ID assigned by the Vertica catalog, which identifies the user. USER_NAME VARCHAR Name of the user for which transaction information is listed. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. TRANSACTION_ID INTEGER Identifier for the transaction within the session, if any; otherwise NULL. DESCRIPTION VARCHAR Textual description of the transaction. START_EPOCH INTEGER Number of the start epoch for the transaction. END_EPOCH INTEGER Number of the end epoch for the transaction NUMBER_OF_STATEMENTS INTEGER Number of query statements executed in this transaction. ISOLATION VARCHAR Denotes the transaction mode as "READ COMMITTED" or "SERIALIZABLE". IS_READ_ONLY BOOLEAN Denotes "READ ONLY" transaction mode. HP Vertica Analytic Database (7.0.x) Description Page 1519 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_COMMITTED BOOLEAN Determines if the transaction was committed. False means ROLLBACK. IS_LOCAL BOOLEAN Denotes transaction is local (non-distributed). IS_INITIATOR BOOLEAN Denotes if the transaction occurred on this node (t). IS_DDL BOOLEAN Distinguishes between a DDL transaction (t) and nonDDL transaction (f). Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM transactions LIMIT 4; -[ RECORD 1 ]--------+----------------------------------------------------start_timestamp | 2012-03-30 17:25:16.025136-04 end_timestamp | 2012-03-30 17:25:16.029179-04 node_name | v_myvdb_node0004 user_id | 45035996273704962 user_name | dbadmin session_id | raster-s1-10295:0x389d transaction_id | 58546795155820007 description | Txn: d0000000000de7 'RemoteNodeLocalState_RowCounts' start_epoch | 4 end_epoch | 4 number_of_statements | 1 isolation | SERIALIZABLE is_read_only | f is_committed | f is_local | t is_initiator | t is_ddl | f -[ RECORD 2 ]--------+----------------------------------------------------start_timestamp | 2012-03-30 17:25:14.001833-04 end_timestamp | 2012-03-30 17:25:14.001915-04 node_name | v_myvdb_node0004 user_id | 45035996273704962 user_name | dbadmin session_id | raster-s4-22870:0x3b4b transaction_id | 58546795155820006 description | Txn: d0000000000de6 'Check LGE' start_epoch | 4 end_epoch | 4 number_of_statements | 1 isolation | SERIALIZABLE is_read_only | f is_committed | f HP Vertica Analytic Database (7.0.x) Page 1520 of 1539 SQL Reference Manual HP Vertica System Tables is_local | t is_initiator | t is_ddl | f -[ RECORD 3 ]--------+----------------------------------------------------start_timestamp | 2012-03-30 17:22:16.0105-04 end_timestamp | 2012-03-30 17:22:16.014883-04 node_name | v_myvdb_node0004 user_id | 45035996273704962 user_name | dbadmin session_id | raster-s1-10295:0x3839 transaction_id | 58546795155819998 description | Txn: d0000000000dde 'RemoteNodeLocalState_RowCounts' start_epoch | 4 end_epoch | 4 number_of_statements | 1 isolation | SERIALIZABLE is_read_only | f is_committed | f is_local | t is_initiator | t is_ddl | f -[ RECORD 4 ]--------+----------------------------------------------------start_timestamp | 2012-03-30 17:22:10.0063-04 end_timestamp | 2012-03-30 17:22:10.006571-04 node_name | v_myvdb_node0004 user_id | 45035996273704962 user_name | dbadmin session_id | raster-s1-10295:0x3835 transaction_id | 58546795155819997 description | Txn: d0000000000ddd 'ProjUtil::getLocalNodeLGE' start_epoch | 4 end_epoch | 4 number_of_statements | 1 isolation | SERIALIZABLE is_read_only | f is_committed | f is_local | t is_initiator | t is_ddl | f See Also l Transactions TUNING_RECOMMENDATIONS Returns the tuning recommendation results from the last ANALYZE_WORKLOAD() call. This information is useful for letting you build filters on the Workload Analyzer result set. HP Vertica Analytic Database (7.0.x) Page 1521 of 1539 SQL Reference Manual HP Vertica System Tables Column Data type Description observation_coun t INTEGER Integer for the total number of events observed for this tuning recommendation. For example, if you see a return value of 1, WLA is making its first tuning recommendation for the event in 'scope'. first_observatio n_time TIMESTAM PTZ Timestamp when the event first occurred. If this column returns a null value, the tuning recommendation is from the current status of the system instead of from any prior event. last_observatio n_time TIMESTAM PTZ Timestamp when the event last occurred. If this column returns a null value, the tuning recommendation is from the current status of the system instead of from any prior event. tuning_parameter VARCHAR Objects on which you should perform a tuning action. For example, a return value of: tuning_descripti on VARCHAR HP Vertica Analytic Database (7.0.x) l public.t informs the DBA to run Database Designer on table t in the public schema l bsmith notifies a DBA to set a password for user bsmith Textual description of the tuning recommendation from the Workload Analyzer to perform on the tuning_parameter object. Examples of some of the returned values include, but are not limited to: l Run database designer on table schema.table l Create replicated projection for table schema.table l Consider incremental design on query l Reset configuration parameter with SELECT set_config_ parameter('parameter', 'new_value') l Re-segment projection projection-name on highcardinality column(s) l Drop the projection projection-name l Alter a table's partition expression l Reorganize data in partitioned table l Decrease the MoveOutInterval configuration parameter setting Page 1522 of 1539 SQL Reference Manual HP Vertica System Tables Column Data type Description tuning_command VARCHAR Command string if tuning action is a SQL command. For example, the following example statements recommend that the DBA: Update statistics on a particular schema's table.column: SELECT ANALYZE_STATISTICS('public.table.column'); Resolve mismatched configuration parameter 'LockTimeout': SELECT * FROM CONFIGURATION_PARAMETERSWHERE parameter_name = 'LockTimeout'; Set the password for user bsmith: ALTER USER (user) IDENTIFIED BY ('new_password'); tuning_cost VARCHAR Cost is based on the type of tuning recommendation and is one of: l LOW—minimal impact on resources from running the tuning command l MEDIUM—moderate impact on resources from running the tuning command l HIGH—maximum impact on resources from running the tuning command Depending on the size of your database or table, consider running high-cost operations after hours instead of during peak load times. Permissions Must be a superuser. Examples For examples, see ANALYZE_WORKLOAD(). See Also l Analyzing Workloads l Understanding WLA Triggering Conditions TUPLE_MOVER_OPERATIONS Monitors the status of the Tuple Mover (TM) on each node. HP Vertica Analytic Database (7.0.x) Page 1523 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description OPERATION_START_TIMESTAMP TIMESTAMP Start time of a Tuple Mover operation. NODE_NAME VARCHAR Node name for which information is listed. OPERATION_NAME VARCHAR One of the following operations: MoveoutMergeout Analyze Statistics OPERATION_STATUS VARCHAR Returns Running or an empty string to indicate 'not running.' TABLE_SCHEMA VARCHAR Schema name for the specified projection. TABLE_NAME VARCHAR Table name for the specified projection PROJECTION_NAME VARCHAR Name of the projection being processed. PROJECTION_ID INTEGER Unique numeric ID assigned by the HP Vertica catalog, which identifies the projection. COLUMN_ID INTEGER Identifier for the column for the associated projection being processed. EARLIEST_CONTAINER_START_EPOCH INTEGER Populated for mergeout, purge and merge_ partitions operations only. For an ATM-invoked mergeout, for example, the returned value represents the lowest epoch of containers involved in the mergeout. LATEST_CONTAINER_END_EPOCH INTEGER Populated for mergeout, purge and merge_ partitions operations. For an ATM-invoked mergeout, for example, the returned value represents the highest epoch of containers involved in the mergeout. ROS_COUNT INTEGER Number of ROS containers. TOTAL_ROS_USED_BYTES INTEGER Size in bytes of all ROS containers in the mergeout operation. (Not applicable for other operations.) PLAN_TYPE VARCHAR One of the following values: MoveoutMergeout Analyze Replay Delete SESSION_ID HP Vertica Analytic Database (7.0.x) VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. Page 1524 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description IS_EXECUTING BOOLEAN Distinguishes between actively-running (t) and completed (f) tuple mover operations. RUNTIME_PRIORITY VARCHAR Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to running queries in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Notes Manual mergeouts are invoked using one of the following APIs: l DO_TM_TASK l PURGE Example => SELECT node_name, operation_status, projection_name, plan_type FROM TUPLE_MOVER_OPERATIONS; node_name | operation_status | projection_name | plan_type -----------+------------------+------------------+----------node0001 | Running | p1_b2 | Mergeout node0002 | Running | p1 | Mergeout node0001 | Running | p1_b2 | Replay Delete node0001 | Running | p1_b2 | Mergeout node0002 | Running | p1_b2 | Mergeout node0001 | Running | p1_b2 | Replay Delete node0002 | Running | p1 | Mergeout node0003 | Running | p1_b2 | Replay Delete node0001 | Running | p1 | Mergeout node0002 | Running | p1_b1 | Mergeout HP Vertica Analytic Database (7.0.x) Page 1525 of 1539 SQL Reference Manual HP Vertica System Tables See Also l DO_TM_TASK l PURGE UDX_FENCED_PROCESSES Provides information about processes HP Vertica uses to run user-defined extensions in fenced mode. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. PROCESS_TYPE VARCHAR Indicates what kind of side process this row is for and can be one of the following values: l UDxZygoteProcess — Master process that creates worker side processes, as needed, for queries. There will be, at most, 1 UP UDxZygoteProcess for each HP Vertica instance. l UDxSideProcess — Indicates that the process is a worker side process. There could be many UDxSideProcesses, depending on how many sessions there are, how many queries, and so on. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. LANGUAGE VARCHAR The language of the UDx. For example 'R' or 'C++'; PID INTEGER Linux process identifier of the side process (UDxSideProcess). PORT VARCHAR For HP Vertica internal use. The TCP port that the side process is listening on. STATUS VARCHAR Can be one of "UP" or "DOWN", depending on whether the process is alive or not. Note: If a process fails, HP Vertica will reap it some time in the future, but not necessarily immediately, so the status could appear as "DOWN." Also, once a process fails, HP Vertica restarts it only on demand. So after a process failure, there could be periods of time when no side processes are running. HP Vertica Analytic Database (7.0.x) Page 1526 of 1539 SQL Reference Manual HP Vertica System Tables Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => select * from udx_fenced_processes; node_name | process_type | session_id | language | pid | port | status ---------------+------------------+----------------------------------+----------+-------+ -------+-------v_db_node0001 | UDxZygoteProcess | | | 3137 | 56667 | UP v_db_node0001 | UDxSideProcess | localhost.localdoma-3117:0x15746 | R | 41821 | 34040 | UP (2 rows) USER_LIBRARIES Lists the user libraries that are currently loaded. Column Name Data Type Description SCHEMA_NAME VARCHAR (8192) The name of the schema containing the library LIB_NAME VARCHAR (8192) The name of the library LIB_OID INTEGER The object ID of the library AUTHOR VARCHAR (8192) The creator of the library file OWNER_ID INTEGER The object ID of the library's owner LIB_FILE_NAME VARCHAR (8192) The name of the shared library file MD5_SUM VARCHAR (8192) The MD5 checksum of the library file, used to ensure that the file was correctly copied to each node SDK_VERSION VARCHAR (8192) The version of the HP Vertica SDK used to compile the library. REVISION VARCHAR (8192) The revision of the HP Vertica SDK used to compile the library. HP Vertica Analytic Database (7.0.x) Page 1527 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description LIB_BUILD_TAG VARCHAR (8192) Internal information set by library developer to track the when the library was compiled LIB_VERSION VARCHAR (8192) The version of the library LIB_SDK_VERSION VARCHAR (8192) The version of the Vertica Analytic Database SDK with which the developer expects the library to be used. This value is manually set by the developer, and may differ from the value in the SDK_VERSION and REVISION, which is automatically set when the developer compiles the library. SOURCE_URL VARCHAR (8192) A URL that contains information about the library DESCRIPTION VARCHAR (8192) A description of the library LICENSES_REQUIRED VARCHAR (8192) The licenses required to use the library SIGNATURE VARCHAR (8192) The signature used to sign the library for validation EPOCH INTEGER The database epoch in which the library was created in the catalog USER_LIBRARY_MANIFEST Lists the user-defined fnctions contained in all of the loaded user libraries. Column Name Data Type Description SCHEMA_NAME VARCHAR The name of the schema containing the function. LIB_NAME VARCHAR The name of the library containing the UDF. LIB_OID INTEGER The object ID of the library containing the function. OBJ_NAME VARCHAR The name of the constructor class in the library for a function. OBJ_TYPE VARCHAR The type of user defined function (scalar function, transform function) ARG_TYPES VARCHAR A comma-delimited list of data types of the function's parameters. RETURN_TYPE VARCHAR A comma-delimited list of data types of the function's return values. HP Vertica Analytic Database (7.0.x) Page 1528 of 1539 SQL Reference Manual HP Vertica System Tables USER_SESSIONS Returns user session history on the system. Column Name Data Type Description NODE_NAME VARCHAR Name of the node that is reporting the requested information. USER_NAME VARCHAR Name of the user at the time HP Vertica recorded the session. SESSION_ID VARCHAR Identifier for this session. This identifier is unique within the cluster at any point in time but can be reused when the session closes. TRANSACTION_ID VARCHAR Identifier for the transaction within the session, if any. If a session is active but no transaction has begun, TRANSACTION_ID returns NULL. STATEMENT_ID VARCHAR Unique numeric ID for the currently-running statement. NULL indicates that no statement is currently being processed. The combination of TRANSACTION_ID and STATEMENT_ID uniquely identifies a statement within a session. RUNTIME_PRIORITY VARCHAR Determines the amount of run-time resources (CPU, I/O bandwidth) the Resource Manager should dedicate to queries already running in the resource pool. Valid values are: l HIGH l MEDIUM l LOW Queries with a HIGH run-time priority are given more CPU and I/O resources than those with a MEDIUM or LOW run-time priority. SESSION_START_TIMESTAMP TIMESTAMPTZ Value of session at beginning of history interval. SESSION_END_TIMESTAMP TIMESTAMPTZ Value of session at end of history interval. IS_ACTIVE BOOLEAN Denotes if the operation is executing. CLIENT_HOSTNAME VARCHAR IP address of the client system HP Vertica Analytic Database (7.0.x) Page 1529 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_PID INTEGER Linux process identifier of the client process that issued this connection. Note: The client process could be on a different machine from the server. CLIENT_LABEL VARCHAR User-specified label for the client connection that can be set when using ODBC. See Label in DSN Parameters in Programmer's Guide. SSL_STATE VARCHAR Indicates if HP Vertica used Secure Socket Layer (SSL) for a particular session. Possible values are: l None – Vertica did not use SSL. l Server – Sever authentication was used, so the client could authenticate the server. l Mutual – Both the server and the client authenticated one another through mutual authentication. See Implementing Security and Implementing SSL in the Administrator's Guide. AUTHENTICATION_METHOD VARCHAR Type of client authentication used for a particular session, if known. Possible values are: l Unknown l Trust l Reject l Kerberos l Password l MD5 l LDAP l Kerberos-GSS l Ident See Implementing Security and Implementing Client Authentication. HP Vertica Analytic Database (7.0.x) Page 1530 of 1539 SQL Reference Manual HP Vertica System Tables Column Name Data Type Description CLIENT_TYPE VARCHAR The type of client from which the connection was made. Possible client type values: l ADO.NET Driver l ODBC Driver l JDBC Driver l vsql CLIENT_VERSION VARCHAR Returns the client version. CLIENT_OS VARCHAR Returns the client operating system. Permissions No explicit permissions are required; however, users see only the records that correspond to tables they have permissions to view. Example => SELECT * FROM USER_SESSIONS; ... -[ RECORD 2 ]-----------+---------------------------------node_name | v_vmart_node0001 user_name | dbadmin session_id | 000000.verticacorp.-30972:0x15 transaction_id | statement_id | runtime_priority | session_start_timestamp | 2012-12-10 06:22:39.539826-05 session_end_timestamp | 2012-12-10 06:22:39.844873-05 is_active | f client_hostname | 10.20.100.62:41307 client_pid | 31517 client_label | ssl_state | None authentication_method | Password client_type | vsql client_version | 07.00.0000 client_os | Linux 2.6.18-308.el5 x86_64 See Also l CURRENT_SESSION l SESSION_PROFILES HP Vertica Analytic Database (7.0.x) Page 1531 of 1539 SQL Reference Manual HP Vertica System Tables l SESSIONS l SYSTEM_SESSIONS WOS_CONTAINER_STORAGE Monitors information about WOS storage, which is divided into regions. Each region allocates blocks of a specific size to store rows. Column Name Data Type Description NODE_NAME VARCHAR The node name for which information is listed. WOS_TYPE VARCHAR Returns one of the following: l system – for system table queries l user – for other user queries WOS_ALLOCATION_REGION VARCHAR The block size allocated by region in KB. The summary line sums the amount of memory used by all regions. REGION_VIRTUAL_SIZE_KB INTEGER The amount of virtual memory in use by region in KB. Virtual size is greater than or equal to allocated size, which is greater than or equal to in-use size. REGION_ALLOCATED_SIZE_KB INTEGER The amount of physical memory in use by a particular region in KB. REGION_IN_USE_SIZE_KB INTEGER The actual number of bytes of data stored by the region in KB. REGION_SMALL_RELEASE_COUNT INTEGER Internal use only. REGION_BIG_RELEASE_COUNT INTEGER Internal use only. EXTRA_RESERVED_BYTES INTEGER The amount of extra memory allocated to maintain WOS sort information. EXTRA_USED_BYTES INTEGER The amount of memory in use currently to maintain the WOS sort information. Notes l The WOS allocator can use large amounts of virtual memory without assigning physical memory. HP Vertica Analytic Database (7.0.x) Page 1532 of 1539 SQL Reference Manual HP Vertica System Tables l To see the difference between virtual size and allocated size, look at the REGION_IN_USE_SIZE column to see if the WOS is full. The summary line tells you the amount of memory used by the WOS, which is typically capped at one quarter of physical memory per node. Examples =>\pset expanded Expanded display is on. => SELECT * FROM WOS_CONTAINER_STORAGE; -[ RECORD 1 ]--------------+--------------------------node_name | host01 wos_type | user wos_allocation_region | 16 KB Region region_virtual_size_kb | 2045408 region_allocated_size_kb | 0 region_in_use_size_kb | 0 region_small_release_count | 656 region_big_release_count | 124 -[ RECORD 2 ]--------------+--------------------------node_name | host01 wos_type | system wos_allocation_region | 16 KB Region region_virtual_size_kb | 1024 region_allocated_size_kb | 960 region_in_use_size_kb | 0 region_small_release_count | 78 region_big_release_count | 9 -[ RECORD 3 ]--------------+--------------------------node_name | host01 wos_type | system wos_allocation_region | 64 KB Region region_virtual_size_kb | 1024 region_allocated_size_kb | 64 region_in_use_size_kb | 0 region_small_release_count | 19 region_big_release_count | 0 -[ RECORD 4 ]--------------+--------------------------node_name | host01 wos_type | system wos_allocation_region | Summary region_virtual_size_kb | 2048 region_allocated_size_kb | 1024 region_in_use_size_kb | 0 region_small_release_count | 97 region_big_release_count | 9 -[ RECORD 5 ]--------------+--------------------------node_name | host01 wos_type | user wos_allocation_region | Summary region_virtual_size_kb | 2045408 region_allocated_size_kb | 0 region_in_use_size_kb | 0 region_small_release_count | 656 region_big_release_count | 124 -[ RECORD 6 ]--------------+--------------------------- HP Vertica Analytic Database (7.0.x) Page 1533 of 1539 SQL Reference Manual HP Vertica System Tables node_name | host02 wos_type | user wos_allocation_region | 16 KB Region region_virtual_size_kb | 2045408 region_allocated_size_kb | 0 region_in_use_size_kb | 0 region_small_release_count | 666 region_big_release_count | 121 -[ RECORD 7 ]--------------+--------------------------node_name | host02 wos_type | system wos_allocation_region | 16 KB Region region_virtual_size_kb | 1024 region_allocated_size_kb | 960 region_in_use_size_kb | 0 region_small_release_count | 38 region_big_release_count | 2 -[ RECORD 8 ]--------------+--------------------------node_name | host02 wos_type | system wos_allocation_region | 64 KB Region region_virtual_size_kb | 1024 region_allocated_size_kb | 64 region_in_use_size_kb | 0 region_small_release_count | 10 region_big_release_count | 0 -[ RECORD 9 ]--------------+--------------------------... HP Vertica Analytic Database (7.0.x) Page 1534 of 1539 SQL Reference Manual Appendix: Compatibility with Other RDBMS Appendix: Compatibility with Other RDBMS This section describes compatibility of HP Vertica with other relational database management systems. Information in this appendix is intended to simplify database migration to HP Vertica. Data Type Mappings Between HP Vertica and Oracle Oracle uses proprietary data types for all main data types (for example, VARCHAR, INTEGER, FLOAT, DATE), if you plan to migrate your database from Oracle to HP Vertica, HP strongly recommends that you convert the schema—a simple and important exercise that can minimize errors and time lost spent fixing erroneous data issues. The following table compares the behavior of Oracle data types to HP Vertica data types. HP Vertica Analytic Database (7.0.x) Page 1535 of 1539 SQL Reference Manual Appendix: Compatibility with Other RDBMS Oracle NUMBER (no explicit precision) HP Vertica Notes In Oracle, the NUMBER data type with no explicit precision stores INT, NUMERIC or each number N as an integer M, together with a scale S. The scale can range from -84 to 127, while the precision of M is limited to 38 FLOAT digits. So N = M * 10^S. When precision is specified, precision/scale applies to all entries in the column. If omitted, the scale defaults to 0. For the common case where Oracle’s NUMBER with no explicit precision data type is used to store only integer values, INT is the best suited and the fastest HP Vertica data type. However, INT (the same as BIGINT) is limited to a little less than 19 digits, with a scale of 0; if the Oracle column contains integer values outside of the range [9223372036854775807, +9223372036854775807], use the HP Vertica data type NUMERIC(p,0) where p is the maximum number of digits required to represent the values of N. Even though no explicit scale is specified for an Oracle NUMBER column, Oracle allows non-integer values, each with its own scale. If the data stored in the column is approximate, HP Vertica recommends using the HP Vertica data type FLOAT, which is standard IEEE floating point, like ORACLE BINARY_DOUBLE. If the data is exact with fractional places, for example dollar amounts, HP Vertica recommends NUMERIC(p,s) where p is the precision (total number of digits) and s is the maximum scale (number of decimal places). HP Vertica conforms to standard SQL, which requires that p >= s and s >= 0. HP Vertica's NUMERIC data type is most effective for p=18, and increasingly expensive for p=37, 58, 67, etc., where p <= 1024. HP Vertica recommends against using the data type NUMERIC(38,s) as a default "failsafe" mapping to guarantee no loss of precision. NUMERIC(18,s) is better, and INT or FLOAT are better yet, if one of these data types will do the job. NUMBER (P,0), INT In Oracle, when precision is specified the precision/scale applies to all entries in the column. If omitted the scale defaults to 0. For the Oracle NUMBER data type with 0 scale, and a precision less than or equal to 18, use INT in HP Vertica. NUMERIC (p,0) An Oracle column precision greater than 18 is often more than an application really needs. P <= 18 NUMBER (P,0), P > 18 If all values in the Oracle column are within the INT range [-9223372036854775807,+9223372036854775807], use INT for best performance. Otherwise, use the HP Vertica data type NUMERIC(p, 0), where p = P. HP Vertica Analytic Database (7.0.x) Page 1536 of 1539 SQL Reference Manual Appendix: Compatibility with Other RDBMS Oracle HP Vertica Notes NUMBER (P,S) NUMERIC (p,s) When P >= S and S >= 0, use p = P and s = S, unless the data allows reducing P or using FLOAT as discussed above. all cases other than previous 3 rows or FLOAT If S > P, use p = S, s = S. If S < 0, use p = P – S, s = 0. NUMERIC (P,S) See notes --> Rarely used in Oracle. See notes for the NUMBER type. DECIMAL (P,S) See notes --> DECIMAL is a synonym for NUMERIC. See notes for the NUMBER type. BINARY_ FLOAT FLOAT Same as FLOAT(53) or DOUBLE PRECISION. BINARY_ DOUBLE FLOAT Same as FLOAT(53) or DOUBLE PRECISION. RAW VARBINARY The maximum size of RAW in Oracle is 2,000 bytes. (RAW) The maximum size of CHAR/BINARY in HP Vertica is 65000 bytes. In HP Vertica, RAW is a synonym for VARBINARY. LONG RAW VARBINARY The maximum size of Oracle’s LONG RAW is 2GB. (RAW) The maximum size of HP Vertica’s VARBINARY is 65000 bytes. HP Vertica users should exercise caution to avoid truncation during data migration from Oracle. CHAR(n) CHAR(n) The maximum size of CHAR in Oracle is 2,000 bytes. The maximum size of CHAR in HP Vertica is 65000 bytes. NCHAR(n) CHAR(n*3) HP Vertica supports national characters with CHAR(n) as variablelength UTF8-encoded UNICODE character string. UTF-8 represents ASCII in 1 byte, most European characters in 2 bytes, and most oriental and Middle Eastern characters in 3 bytes. VARCHAR2 (n) VARCHAR (n) The maximum size of VARCHAR2 in Oracle is 4,000 bytes. The maximum size of VARCHAR in HP Vertica is 65000 . Note: The behavior of Oracle’s VARCHAR2 and HP Vertica’s VARCHAR is semantically different. HP Vertica’s VARCHAR exhibits standard SQL behavior, whereas Oracle’s VARCHAR2 is not completely consistent with standard behavior – it treats an empty string as NULL value and uses non-padded comparison if one operand is VARCHAR2. HP Vertica Analytic Database (7.0.x) Page 1537 of 1539 SQL Reference Manual Appendix: Compatibility with Other RDBMS Oracle HP Vertica NVARCHAR2 VARCHAR (n) (n*3) DATE Notes See notes for NCHAR(). TIMESTAMP Oracle’s DATE is different from the SQL standard DATE data type or implemented by HP Vertica. Oracle’s DATE includes the time (no fractional seconds), while HP Vertica DATE type includes only date possibly per SQL specification. DATE TIMESTAMP TIMESTAMP TIMESTAMP defaults to six places, that is, to microseconds TIMESTAMP TIMESTAMP TIME ZONE defaults to the currently SET or system time zone. WITH WITH TIME ZONE TIME ZONE INTERVAL YEAR INTERVAL YEAR TO MONTH TO MONTH INTERVAL DAY INTERVAL DAY Per the SQL standard, INTERVAL can be qualified with YEAR TO MONTH sub-type in HP Vertica. In HP Vertica, DAY TO SECOND is the default sub-type for INTERVAL. TO SECOND TO SECOND CLOB, BLOB You can store a CLOB (character large object) or BLOB (binary large LONG VARCHAR, object) value in a table or in an external location. The maximum size of a CLOB or BLOB is 128 TB. LONG VARBINARY You can store HP Vertica LONG data types only in LONG VARCHAR and LONG VARBINARY columns. The maximum size of the LONG data types is 32,000,000 bytes. LONG, LONG RAW Oracle recommends using CLOB and BLOB data types instead of LONG VARCHAR, LONG and LONG RAW data types. LONG In Oracle, a table can contain only one LONG column, The maximum VARBINARY size of a LONG or LONG RAW data type is 2 GB. HP Vertica Analytic Database (7.0.x) Page 1538 of 1539 We appreciate your feedback! If you have comments about this document, you can contact the documentation team by email. If an email client is configured on this system, click the link above and an email window opens with the following information in the subject line: Feedback on SQL Reference Manual (Vertica Analytic Database 7.0.x) Just add your feedback to the email and click send. If no email client is available, copy the information above to a new message in a web mail client, and send your feedback to vertica-docfeedback@hp.com. HP Vertica Analytic Database (7.0.x) Page 1539 of 1539
Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Author                          : Hewlett-Packard Company, L.P.
Create Date                     : 2014:02:24 00:03:41-05:00
Modify Date                     : 2014:10:29 00:33:26+05:30
Subject                         : 
Language                        : en-us
XMP Toolkit                     : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26
Format                          : application/pdf
Creator                         : Hewlett-Packard Company, L.P.
Description                     : 
Title                           : HP Vertica Analytics Platform 7.0.x SQL Reference Manual
Metadata Date                   : 2014:10:29 00:33:26+05:30
Keywords                        : 
Producer                        : madbuild
Document ID                     : uuid:520082e1-9335-48a2-9c8e-270488c313f3
Instance ID                     : uuid:7ef30074-9012-4e7a-a67a-bdbf4d255a70
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 1539
EXIF Metadata provided by EXIF.tools

Navigation menu