Plugin command to stream a filtered dataset from the remote storage system to stdout .
plugin_executable restore_data_subset plugin_config_file data_filenamekey offsets_file
gprestore invokes a plugin's restore_data or restore_data_subset command to restore a backup. gprestore invokes the more performant restore_data_subset plugin command on each segment host to perform a filtered restore operation when all of the following conditions hold:
- The backup is an uncompressed, single-data-file backup (the gpbackup command was invoked with the --no-compression and --single-data-file flags).
- Filtering options (--include-table, --exclude-table, --include-table-file, or ‑‑exclude-table-file) are specified on the gprestore command line.
- The plugin_config_file specifies the restore_subset: "on" property setting.
gprestore invokes the restore_data_subset plugin command with an offsets_file that it automatically generates based on the filters specified. The restore_data_subset implementation should extract the start and end byte offsets for each relation specified in offsets_file, use this information to selectively read from a potentially large data file named or mapped to data_filenamekey on the remote storage system, and write the contents to stdout.
- The absolute path to the plugin configuration YAML file. This file must specify the restore_subset: "on" property setting.
- The mapping key to a backup file on the remote storage system. data_filenamekey is the same key provided to the backup_data command.
- The absolute path to the relation offsets file generated by gprestore. This file specifies the number of relations, and the start and end byte offsets for each relation, that the plugin should restore. gprestore specifies this information on a single line in the file. For example, if the file contents specified 2 1001 2007 4500 6000, the plugin restores two relations; relation 1 with start offset 1001 and end offset 2007, and relation 2 with start offset 4500 and end offset 6000.
The restore_data_subset command must exit with a value of 0 on success, non-zero if an error occurs. In the case of a non-zero exit code, gprestore displays the contents of stderr to the user.