GROOM TABLE

GROOM TABLE
Use the GROOM TABLE command to reclaim disk space for deleted or outdated rows, and reorganize tables based on the clustered base table organizing keys, or to migrate data for tables that have multiple stored versions. This command replaces the nzreclaim command. For more information, see Grooming Tables in the Netezza System Administrators Guide.

Synopsis
Syntax for granting an object privilege:
GROOM TABLE <name> <mode-choice> <reclaim-choice>

Where
<mode-choice>:= RECORDS READY | RECORDS ALL | PAGES ALL | PAGES START | VERSIONS <reclaim-choice>:= RECLAIM BACKUPSET { NONE | DEFAULT | <backupsetid>

Inputs
The GROOM TABLE command takes the following inputs: Table B-79: GROOM TABLE Input Input Description

RECORDS READY Specifies to reclaim and reorganize records in the table that have not been groomed, as well as those previously groomed but marked for regrooming. RECORDS ALL PAGES ALL PAGES START VERSIONS RECLAIM BACKUPSET Specifies to reclaim and reorganize all records in a table. Identifies and marks as Empty data pages in the table with no visible record, to free up disk extents. Identifies and marks as Empty leading data pages in the table with no visible record, stopping when it finds a non-empty data page. Specifies to migrate records from previous table versions. Dropped columns will not appear, and added columns will show default values. Can be set to the following:
NONE No backup-reclaim synchronization, which means the

next backup may not be able to incrementally backup the table, and require a full backup.
DEFAULT This is the default if no reclaim-choice is specified,

and uses the default backup set, if one exists, for the given database for backup-reclaim synchronization.
<backupsetid> Use the most recent backup in the specified

backup set for backup-reclaim synchronization.

20284-14

Rev.1

B-89

Netezza Database Users Guide

Outputs
The GROOM TABLE command has the following output Table B-80: GROOM TABLE Output Output NOTICE: GROOM processed <#> pages; released <#> pages; purged <#> records. Table size grew/shrunk/unchanged from <#> extents to <#> extents. Description Message returned when the command has been completed.

Description
The GROOM TABLE command has the following features:

Privileges Required
While nzreclaim required an administrator privilege, GROOM TABLE requires a GROOM object privilege.

Common Tasks
Use the GROOM TABLE command to remove outdated and deleted records from tables while allowing access to all tables in the system. The GROOM TABLE command does not lock a table while it is running; you can continue to read, update, and write/insert to the groomed table while the table is being groomed. Note: You cannot execute the GROOM TABLE command inside a transaction block (begin/ commit pair). Note: Grooming a table is done as a user, not an administrator, so to run GROOM TABLE requires that you have object privileges on that table as well.

Related Commands
See nzreclaim in the Netezza System Administrators Guide.

Usage
The following provides sample usage. To migrate data for a versioned table, enter:
system(admin)=> GROOM TABLE <table_name> VERSIONS;

To reclaim deleted records in a table (equivalent to nzreclaim -records), enter:

system(admin)=> GROOM TABLE <table_name> RECORDS ALL;

To identify data pages containing only deleted records and to reclaim extents that are empty as a result (an extension of nzreclaim -startEndBlocks), enter:
system(admin)=> GROOM TABLE <table_name> PAGES ALL;

To organize data not already organized in a clustered base table, enter:

system(admin)=> GROOM TABLE <table_name> RECORDS READY;

B-90

20284-14

Rev.1

Grooming Tables

If the table is evenly distributed, or if a change in distribution would affect queries, you could split the table into two or more smaller tables, and then combine them into a view with a UNION ALL operation.

Grooming Tables
As part of your routine database maintenance activities, you should plan to recover disk space occupied by outdated or deleted rows. In normal Netezza operation, an update or delete of a table row does not remove the old tuple (version of the row). This approach benefits multiversion concurrency control by retaining tuples that could potentially be visible to other transactions. Over time however, the outdated or deleted tuples are of no interest to any transaction. After you have captured them in a backup, you can reclaim the space they occupy using the SQL GROOM TABLE command. Note: Starting in Release 6.0, you use the GROOM TABLE command to maintain the user tables by reclaiming disk space for deleted or outdated rows, as well as to reorganize the tables by their organizing keys. The GROOM TABLE command does not lock a table while it is running; you can continue to read, update, and write/insert to the groomed table while the table is being groomed. For details about the GROOM TABLE command, see the Netezza Database Users Guide. Note the following best practices when you groom tables to reclaim disk space: You should groom tables that receive frequent updates or deletes more often than tables that are seldom updated. If you have a mixture of large tables, some of which are heavily updated and others that are seldom updated, you might want to set up periodic tasks that routinely groom the frequently updated tables. Grooming deleted records has no effect on your database statistics, because the process physically removes records that were already logically deleted. When you groom a table, the system leaves the min/max, null, and estimated dispersion values unchanged. For more information on when to run the GENERATE STATISTICS command, see Running the GENERATE STATISTICS Command on page 9-16. Physically reclaiming the records, however, does affect where the remaining records in the table are located. So when you physically reclaim records, the system updates the zone map. Note: When you delete a tables contents completely, consider using the TRUNCATE rather than the DELETE command, which eliminates the need to run the GROOM TABLE command.

GROOM and the nzreclaim Command

When you run the GROOM TABLE command, it removes outdated and deleted records from tables while allowing access to all tables in the system. In previous releases, the nzreclaim command could be used to perform reclaims. Starting in Release 6.0, the nzreclaim command is deprecated, although it is still available for backward compatibility. As a best practice, you should transition to using the GROOM TABLE command. If you have scripts that use the nzreclaim command, you should migrate them to use GROOM TABLE as well. Note that the nzreclaim command syntax has changed

20282-14

Rev.1

9-19

Netezza System Administrators Guide

in Release 6.0. For example, the -scanblocks and -scanrecords options are not supported and will return an error. For details on the supported command syntax, see nzreclaim on page A-34. Several examples follow: To use the GROOM TABLE command in a SQL session:
MYDB(USER1)=> GROOM TABLE ORDERS; NOTICE: Groom processed 25 pages; purged 9 records; scan size shrunk by 9 pages; table size shrunk by 9 extents. GROOM RECORDS ALL

If you have created scripts to run nzreclaim from the command line as in the previous example, you can update those scripts to use the new SQL GROOM TABLE command as in the following example:
[nz@nzhost ~]$ nzsql mydb -u user1 -pw password -c "groom table mynation"

If you use the nzreclaim command to groom a table:

[nz@nzhost ~]$ nzreclaim -db mydb -u user1 -pw password -t mynation nzsql -u user1 -pw password mydb -c"groom table mynation " 2>&1 NOTICE: Groom processed 25 pages; purged 9 records; scan size shrunk by 9 pages; table size shrunk by 9 extents. GROOM RECORDS ALL

As shown in the example, the nzreclaim command calls the GROOM TABLE command to update and reclaim the table. You should migrate to using the GROOM TABLE command directly.

Groom and Backup Synchronization

By default, the system synchronizes your GROOM TABLE request with the most recent backup set to avoid reclaiming rows that are not yet captured by incremental backups. In other words, GROOM TABLE will not remove any data that has been deleted or is outdated but which has not yet been saved in a backup. For example: 1. Run a full backup. 2. Delete data B. 3. Run an incremental backup which captures data B marked as deleted. 4. Delete D. 5. Run GROOM TABLE which removes B but not D, because D was not captured in the last backup. If you maintain two backup sets for a database and you do not want the GROOM TABLE command to use the default backup set, you can use the backupset option to specify another backup set. Run the backup history report to learn the ID of the backup set you want to specify. For more information about the backup history report, see Backup History Report on page 10-18. Note: If you disable this synchronization and a subsequent incremental backup needs information that you removed with a reclaim, nzbackup will perform a full backup instead of the incremental you requested for any reclaimed tables.

9-20

20282-14

Rev.1