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.
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:
Which prints the following:
...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:
Import queries owned by a specific user, replacing serials, with temporaries:
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:
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:
Delete queries by serial:
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:
Stop all temporary queries for a specific user:
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:
Restart Spare 0, and replicas 0 and 2 of a query:
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:
Show the status of all queries for a specific user, including temporaries:
Show the status of a few queries by serial in JSON format to a file:
reload
The reload action commands the Controller to reload its configuration from disk.
Usage examples:
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:
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:
You can also issue commands to the provider. The default provider allows backend servers to be marked up or down. For example:
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.