@SnapshotScan

Documentation

VoltDB Home » Documentation » Using VoltDB

@SnapshotScan

@SnapshotScan — Lists information about existing native snapshots in a given directory path.

Synopsis

@SnapshotScan String directory-path

Description

The @SnapshotScan system procedure provides information about any native snapshots that exist within the specified directory path for all nodes on the cluster. The procedure reports the name (prefix) of the snapshot, when it was created, how long it took to create, and the size of the individual files that make up the snapshot(s).

@SnapshotScan does not include CSV format snapshots in its output. Only native format snapshots are listed.

Return Values

On successful completion, this system procedure returns three VoltTables providing the following information:

  • A summary of the snapshots found

  • Available space in the directories scanned

  • Details concerning the Individual files that make up the snapshots

The first table contains one row for every snapshot found.

NameDatatypeDescription
PATHSTRINGThe directory path where the snapshot resides.
NONCESTRINGThe unique identifier for the snapshot.
TXNIDBIGINTThe transaction ID of the snapshot.
CREATEDBIGINTThe timestamp when the snapshot was created (in milliseconds).
SIZEBIGINTThe total size, in bytes, of all the snapshot data.
TABLES_REQUIREDSTRINGA comma-separated list of all the table names listed in the snapshot digest file. In other words, all of the tables that make up the snapshot.
TABLES_MISSINGSTRINGA comma-separated list of database tables for which no data can be found. (That is, the corresponding files are missing or unreadable.)
TABLES_INCOMPLETESTRINGA comma-separated list of database tables with only partial data saved in the snapshot. (That is, data from some partitions is missing.)
COMPLETESTRINGA string value indicating whether the snapshot as a whole is complete ("TRUE") or incomplete ("FALSE"). If this column is "FALSE", the preceding two columns provide additional information concerning what is missing.
PATHTYPESTRINGA string value indicating the type of snapshot and its location, where the type can be "SNAP_PATH" for manual snapshots, "SNAP_CL" for command log snapshots, and "SNAP_AUTO" for automated snapshots.

The second table contains one row for every host.

NameDatatypeDescription
HOST_IDINTEGERNumeric ID for the host node.
HOSTNAMESTRINGServer name of the host node.
PATHSTRINGThe directory path specified in the call to the procedure.
TOTALBIGINTThe total space (in bytes) on the device.
FREEBIGINTThe available free space (in bytes) on the device.
USEDBIGINTThe total space currently in use (in bytes) on the device.
RESULTSTRINGString value indicating the success ("SUCCESS") or failure ("FAILURE") of the request.
ERR_MSGSTRINGIf the result is FAILURE, this column contains a message explaining the cause of the failure.

The third table contains one row for every file in the snapshot collection.

NameDatatypeDescription
HOST_IDINTEGERNumeric ID for the host node.
HOSTNAMESTRINGServer name of the host node.
PATHSTRINGThe directory path where the snapshot file resides.
NAMESTRINGThe file name.
TXNIDBIGINTThe transaction ID of the snapshot.
CREATEDBIGINTThe timestamp when the snapshot was created (in milliseconds).
TABLESTRINGThe name of the database table the data comes from.
COMPLETEDSTRINGA string indicating whether all of the data was successfully written to the file ("TRUE") or not ("FALSE").
SIZEBIGINTThe total size, in bytes, of the file.
IS_REPLICATEDSTRINGA string indicating whether the table in question is replicated ("TRUE") or partitioned ("FALSE").
PARTITIONSSTRINGA comma-separated string of partition (or site) IDs from which data was taken during the snapshot. For partitioned tables where there are multiple sites per host, there can be data from multiple partitions in each snapshot file. For replicated tables, data from only one copy (and therefore one partition) is required.
TOTAL_PARTITIONSBIGINTThe total number of partitions from which data was taken.
READABLESTRINGA string indicating whether the file is accessible ("TRUE") or not ("FALSE").
RESULTSTRINGString value indicating the success ("SUCCESS") or failure ("FAILURE") of the request.
ERR_MSGSTRINGIf the result is FAILURE, this column contains a message explaining the cause of the failure.

If the system procedure fails because it cannot access the specified path, it returns a single VoltTable with one row and one column.

NameDatatypeDescription
ERR_MSGSTRINGA message explaining the cause of the failure.

Examples

The following example uses @SnapshotScan to list information about the snapshots in the directory /tmp/voltdb/backup/.

$ sqlcmd
1> exec @SnapshotScan /tmp/voltdb/backup/;

The following program example performs the same function, using the VoltTable toString() method to display the results of the procedure call:

VoltTable[] results = null;

try { results = client.callProcedure("@SnapshotScan",
                       "/tmp/voltdb/backup/").getResults();
}
catch (Exception e) { e.printStackTrace(); }

for (VoltTable t: results) { 
   System.out.println(t.toString()); 
}

In the return value, the first VoltTable in the array lists the snapshots and certain status information. The second element of the array provides information about the directory itself (such as used, free, and total disk space). The third element of the array lists specific information about the individual files in the snapshot(s).