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:
A description of all the subcommand's options and some usage examples follows.
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.
The import, export, delete, status, restart, and stop actions support the following options, which select the queries to operate on. The reload, leader, check-repo, and selection-provider actions do not accept them. For import, these options filter the queries in the input file.
| 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. To specify multiple names, list them as separate arguments (e.g., --name PersistentQuery1 PersistentQuery2). |
-o,--owner <arg> ... | Owner of the queries to filter. To specify multiple owners, list them as separate arguments (e.g., --owner user1 user2). |
-s,--serial <arg> ... | Serial IDs to operate on. To specify multiple serials, list them as separate arguments (e.g., --serial 1234 5678). Cannot be combined with --name, --owner, --include-temporary, or --include-non-displayable. |
import
The import action imports a set of Persistent Queries from an XML file. See Import Persistent Queries for examples. 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). To specify multiple overrides, list them as separate arguments (e.g., --server-override old1:new1 old2:new2). |
-x,--replace-existing | Imported queries replace any existing queries with matching serials. Requires --retain-serial. |
Usage examples:
Import queries from an XML file, retaining serials:
Import queries from an XML file, retaining serials and replacing any existing queries with the same serials:
Import only the queries in the file owned by a specific user, including temporary queries. The imported queries are assigned new serials:
export
The export action exports queries from the system to an XML file. See Export all Persistent Queries for an example. This command requires the --file option.
| Option | Description |
|---|---|
-f,--file <arg> | Name of the file to export to. |
Usage examples:
Export all configurations:
Export the queries owned by a specific user, including temporary queries:
delete
The delete action stops and permanently deletes queries from the system.
| Option | Description |
|---|---|
--allow-nuke | Allow delete to run when none of --name, --owner, or --serial is given, 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. If you give no selection options, it applies to all non-temporary, displayable queries.
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 the enabled ones. Disabled queries are skipped. If you give no selection options, it applies to all non-temporary, displayable queries.
| Option | Description |
|---|---|
-C,--continue-after-error | Continue after an error. Processing halts if not set |
-r,--replica <arg> ... | Replica numbers to restart. If not specified, all replicas will restart. To specify multiple replicas, list them as separate arguments (e.g., --replica 0 1 2). Requires exactly one --serial or --name. Use -1, -2, and so on for spares. |
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 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. If not specified, the status of all replicas will be displayed. To specify multiple replicas, list them as separate arguments (e.g., --replica 0 1 2). Requires exactly one --serial or --name. |
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 without restarting. Only members of the groups in the configuration.reload.userGroups property (superuser by default) may run it, and the Controller rejects it on Kubernetes deployments.
Usage examples:
leader
The leader action prints the address 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/iris_controller.
Usage:
check-repo
The check-repo action validates the Git repository configuration. This is useful after updating Git configuration properties to verify that the configuration can be loaded successfully before restarting the controller.
Usage:
The output indicates whether the configuration implied by the properties can be loaded. If there are errors, they will be displayed.
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.
| Option | Description |
|---|---|
--command <arg> | Administrative command to send to the selection provider (for example, up or down). Requires at least one --node. |
--command-json <arg> | Administrative command to send to the selection provider, as raw JSON. Cannot be combined with --command or --node. |
-f,--file <arg> | Name of the file to write the selection provider output to. If not set, output is written to stdout. |
-n,--node <arg> | Name of a node to operate on (for example, Query_1). Required with --command; invalid otherwise. |
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. The --node option is not valid with --command-json; include the nodes in the JSON instead:
Write the selection provider status to a file: