dhconfig pq
The pq configuration data type of the dhconfig tool is used to interact with the Persistent Query Controller. You may import, export, delete, stop, and restart queries using the following actions. Authentication is required for most pq actions.
Usage: dhconfig pq [import|export|delete|status|restart|stop|reload|check-repo|selection-provider|leader] [arguments]
As with other dhconfig configuration data types, the --help argument provides detailed information on the available actions and arguments, as well as usage examples. Use --help whenever you need more information about the available options. For example, if you want information about the import action, you can run:
dhconfig pq import --help
Which prints the following:
usage: dhconfig pq import [-C] [-D] [--dry-run <arg>] [-f <arg>] [-h] [-k <arg> | -user <arg>] [-n <arg>] [--new-owner
<arg>] [-o <arg>] [--override-xml <arg>] [-pf <arg>] [-R] [-s <arg>] [--server-override <arg>] [-T] [-v] [-x]
Import query configurations from disk.
...followed by a description of all of the subcommand's arguments and some usage examples.
Due to the number of available options and combinations, and the robust in-tool documentation via --help, an exhaustive list of all possible commands is not provided here. Instead, we will elaborate on some of the more complex arguments below, and then give some usage examples. We recommend that you use the --help argument as needed for more information.
All actions except for reload and leader support the following options:
| Option | Description |
|---|---|
-D,--include-non-displayable | Include non-displayable (helper) queries. Non-Displayable queries are excluded if not set. |
-T,--include-temporary | Include temporary queries. Temporary queries are excluded if not set. |
-n,--name <arg> | Name of the query to filter. Multiple may be set, separated by spaces. |
-o,--owner <arg> | Owner of the queries to filter. Multiple may be set, separated by spaces. |
-s,--serial <arg> | Serial IDs to operate on. Multiple may be set, separated by spaces. When set, this option overrides all other filtering options |
import
The import action imports a set of Persistent Queries from an XML file. This command requires the --file option to specify the input file, and responds to the following options:
| Option | Description |
|---|---|
-C,--continue-after-error | Continue after an error. Processing halts at the first error if not set. |
--dry-run <arg> | Dry run the command. Specify basic for local validation or full for local and controller verification. |
-f,--file <arg> | Name of the file to import from. |
--new-owner <arg> | New owner to be used on an import instead of the existing query owner. |
--override-xml <arg> | A file with partial configuration overrides that supersede config values in the full XML file. |
-R,--retain-serial | Retain the serial of an imported query. Unless --replace-existing is provided imports fail if the serial already exists. When not set, all imported queries are assigned new serials. |
--server-override <arg> | Update existing server names with new ones (oldName:newName); May be set multiple times, separated by spaces. |
-x,--replace-existing | When --retain-serial is set, imported queries replace any matching serials. |
Usage examples:
Import queries from an XML file, retaining serials:
dhconfig pq import --file QueryCollection.xml --retain-serial
Import queries owned by a specific user, replacing serials, with temporaries:
dhconfig pq import --file QueryCollection.xml --owner TestUser --include-temporary
export
The export action exports queries from the system to an XML file.
| Option | Description |
|---|---|
-f,--file <arg> | Name of the file to import from, export to, or write status to. |
Usage examples:
Export all configurations:
dhconfig pq export
delete
The delete action stops and permanently deletes queries from the system.
| Option | Description |
|---|---|
--allow-nuke | Allow delete to run without any parameters, deleting all visible queries. |
Usage examples:
Delete a query by name:
dhconfig pq delete --name TheQuery
Delete queries by serial:
dhconfig pq delete --serial 1234 4321 1111
stop
The stop action stops the selected queries if they are running.
Note
The stop action is not pertinent to individual replicas or slots, only the entire group.
| Option | Description |
|---|---|
-C,--continue-after-error | Continue after an error. Processing halts if not set |
Usage examples:
Stop a query by name:
dhconfig pq stop --name TheQuery
Stop all temporary queries for a specific user:
dhconfig pq stop --owner TestUser --include-temporary
restart
The restart action stops the selected queries if they are running, then starts them all.
| Option | Description |
|---|---|
-C,--continue-after-error | Continue after an error. Processing halts if not set |
-r,--replica <arg> | Replica numbers to restart. Multiple may be set, separated by spaces. |
Usage examples:
Restart a query by name:
dhconfig pq restart --name TheQuery
Restart Spare 0, and replicas 0 and 2 of a query:
dhconfig pq restart --serial 1234 --replica -1 0 2
status
The status action displays the current status of queries either as a Table, or as JSON, optionally to a file. When a file is specified JSON is written by default.
| Option | Description |
|---|---|
-f,--file <arg> | Name of the file to import from, export to, or write status to. JSON is the default format |
-j,--as-json | Write status as JSON data stream instead of formatted table to stdout |
-r,--replica <arg> | Replica numbers to display. Multiple may be set, separated by spaces. |
Usage examples:
Show the status of all queries:
dhconfig pq status
Show the status of all queries for a specific user, including temporaries:
dhconfig pq status --owner TestUser --include-temporary
Show the status of a few queries by serial in JSON format to a file:
dhconfig pq status --serial 123456 654321 1111 2222 --file stats.json
reload
The reload action commands the Controller to reload its configuration from disk.
Usage examples:
dhconfig pq reload
leader
The leader action prints the IP of the leader controller's host and the port on which it is listening. This is useful, for example, to determine which host is running the currently active controller to examine the logs in /var/log/deephaven/controller.
Usage:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq leader
selection-provider
The active Server Selection Provider provides internal status for debugging in an arbitrary string format. The default Simple Server Selection Provider produces JSON information.
Usage examples:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq selection-provider
You can also issue commands to the provider. The default provider allows backend servers to be marked up or down. For example:
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq selection-provider --command up --node Query_1
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig pq selection-provider --command down --node Query_2
The controller responds with JSON indicating the changes made to each backend query server's state.
You can also issue JSON-formatted commands to the provider using the --command-json argument instead of the --command option. Using a raw JSON argument is necessary for a custom server selection provider that uses different fields than the default simple server selection provider.