UI deep links

Applies to: ✅ Azure Data Explorer

UI deep links are URIs that, when opened in a web browser, result in automatically opening a UI tool (such as Kusto.Explorer or Kusto.WebExplorer) in a way that preselects the desired Kusto cluster (and optionally database).

For example, when a user selects https://help.chinaeast2.kusto.chinacloudapi.cn/Samples?query=print%20123, Kusto.WebExplorer opens to the help.chinaeast2.kusto.chinacloudapi.cn cluster, select the Samples database as the default database, and run the associated query.

UI deep links work by having the user browser receive a redirect response when issuing a GET request to the URI, and depend on the browser settings to allow processing of this redirection. (For example, a UI deep link to Kusto.Explorer requires the browser to be configured to allow ClickOnce applications to start.)

The UI deep link must be a valid URI, and has the following format:

https:// Cluster / [DatabaseName] [? Parameters]

Where:

• Cluster is the base address of the cluster itself. This part is mandatory, but can be overridden by specifying the query parameter uri in Parameters.

• DatabaseName is the name of the database in Cluster to use as the database in scope. If this property isn't set, the UI tool decides which database to use, if at all. (If a query or a command is specified by Parameters, the recommendation is for the correct value for DatabaseName to be included in the URI.)

• Parameters can be used to specify other parameters to control the behavior of the UI deep link. Parameters that are supported by all Kusto "official" UI tools are indicated in the following table. Tool-specific parameters are noted later on in this document.

  Expand table

  Parameter	Description
  web	Selects the UI tool. By default, or if set to 1, Kusto.WebExplorer is used. If set to 0, Kusto.Explorer is used. If set to 3, Kusto.WebExplorer is used with no preexisting tabs.
  query	The text of the query or management command to start with when opening the UI tool.
  querysrc	A URI pointing at a web resource that holds the text of the query or management command to start with when opening the UI tool.
  name	The name of the connection to the cluster.
  autorun	If set to false, requires that the user actively run the query instead of autorunning it when the link is clicked.

  The value of query can use standard HTTP query parameter encoding. Alternatively, it can be encoded using the transformation base64(gzip(text)), which makes it possible to compress long queries or management commands to git in the default browser URI length limits.

Here are a few examples for links:

• https://help.chinaeast2.kusto.chinacloudapi.cn/: When a user agent (such as a browser) issues a GET / request it's redirected to the default UI tool configured to query the help cluster.
• https://help.chinaeast2.kusto.chinacloudapi.cn/Samples: When a user agent (such as a browser) issues a GET /Samples request it's redirected to the default UI tool configured to query the help cluster Samples database.
• http://help.chinaeast2.kusto.chinacloudapi.cn/Samples?query=StormEvents: When a user (such as a browser) issues a GET /Samples?query=StormEvents request it's redirected to the default UI tool configured to query the help cluster Samples database, and issue the StormEvents query.

This REST API performs redirection that installs and runs the Kusto.Explorer desktop client tool with specially crafted startup parameters that open a connection to a specific cluster and execute a query against that cluster.

See Deep-linking with Kusto.Explorer for a description of the redirect URI syntax for starting up Kusto.Explorer.

In addition to the query parameters already mentioned, the following parameters might appear in UI deep links to Kusto.WebExplorer:

To instruct Kusto.WebExplorer to sign-in a user from another Microsoft Entra tenant, specify login_hint and tenant for the user.

Redirection is to the following URI:

https:// BaseAddress /clusters/ Cluster [/databases/ DatabaseName] [? Parameters]

When the URI query string parameter query is specified, it must be encoded according to the URI query string encoding HTML rules. Alternatively, the text of the query or management command can be compressed by gzip, and then encoded via base64 encoding. This feature allows you to send longer queries or control commands (since the latter encoding method results in shorter URIs).

If the query or management command is long, even encoding it using gzip/base64 might exceed the maximum URI length of the user agent. Alternatively, the URI query string parameter querysrc is provided, and its value is a short URI pointing at a web resource that holds the query or management command text.

For example, this value can be the URI for a file hosted by Azure Blob Storage.