Use Query Forms

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Applies from release 2021.2

Compose queries can be viewed and run as query forms in the catalog. See Query Forms for an overview, including details on how to access query forms. See Create a Query Form for help turning queries into runnable forms. Continue reading in this topic for help on opening and using query forms.

Open Query as Form

To open a query as a query form:

1. Open the Catalog page of the query.

2. On the top right of the query page, click Run Form:

   

3. The page of the query form that corresponds to the given query will open. The query form page displays the Catalog field values from the query page, such as the Title, Description, Authors, other built-in and custom fields, and the Data Quality Flags:

   

Understanding the Query Form Page

The Catalog fields you see on the query form page are in fact the fields of the corresponding query object. When you change a field value on the query form page, you modify this value for the query, and the changes will apply to the Catalog page of the query. A query form is not an independent Catalog object.

The default fields on the query form page are:

Field Name	Description
Title	The Title of the query.
Description	The Description of the query.
Authors	The Authors of the query.
Tags	List of Tags added to the query.
Relevant Articles	List of Articles where the query is referenced using @-mentions.
Properties	Data Source: data source for which the query is written Status: query status (Published or Unpublished) Created: date the query was created Last Saved: time the query was touched by the user last: either edited or published Run Info: number of times the query form has been executed and the user and time of when it was last executed
Domains	The Domain information for the query.

Note that you may see more fields on the query form page as your Catalog Admins may have added other custom fields to the query page template.

The ability to modify a field on the query form page depends on the role of the user and their access level to the query. The query Owner and Authors can edit the Title and all fields on the page. Server Admins can edit the Authors field even when they are not Authors. The query Owner, Authors, and Stewards and above can update the Description, add or remove tags, and set Data Quality Flags. All users who can open the query form page can view the fields, such as Properties, Relevant Articles, and assigned Domains.

Actions on the Query Form Page

The actions on the query form page are actions over the corresponding query:

1 - Star - You can favorite the query by clicking the Star option. Starring an object accelerates finding it in the Catalog: when using Alation Search, you can filter the search results to only show Starred objects, which will give you a list of your favorites in the Catalog.

2 - Share - You can share the form with other Catalog users. If you have the Author access level to the query, you can share the query with either Viewer or Author access level.

3 - View Query Page - You can return to the Catalog page of the query.

4 - Open in Compose - If your role has permission to use Compose, you will be able to open the query in Compose.

5 - Endorse, Warn, Deprecate - If your role has permission to set Data Quality Flags, you can add and Endorsement, Warning, or Deprecation on the query.

Run Form

You can run a query form and retrieve the results into the Catalog when:

• You have access to the required objects in the data source

• You have your own database credentials

To run a query form:

1. On the query form page, if you see a Filter Results section, enter or select any filters you would like to apply to the form. If there’s an information icon, hover over it for information about the filters.

   Starting in 2023.3.2, if there’s a Load Query button and a disabled multi-select picker, that means the multi-select picker’s options are dynamically determined. You have to run a pre-query to load the options. Hover over the disabled multi-select picker to see the query that will be used to determine the picker’s options. Click the Load Query button to enable the multi-select picker and load its options. If you prefer, you can click Enter values to enter your values manually. Don’t use the multi-select picker and manually entered values at the same time.

   You can use the Clear Form button to remove any data you have entered and revert back to the form’s default values.

2. By default, the form will run with the last connection settings you used in Compose. Hover over the information icon next to the Connection Settings button to see the current settings. To use different connection settings:

   1. Click the Connection Settings button. The Connection Settings dialog opens.

      

   2. Click the menu button next to Choose a Connection and choose the connection you want to use. When you hover over the connection name, you’ll see the connection URI in a popup so you can be sure you’re selecting the right connection.

      Note

      If you want to add or edit connection information, see Working with Data Source Connections.

   3. Click the menu button next to Connect as (Select User) and select the user you want to connect with. If you’re using SSO to connect, click the pencil icon next to the user. This will open the login screen for your identity provider in a new tab.

   4. Click the Set Active Connection button. Alation will attempt to connect using the selected connection and user.

3. Click the Run button to run the form. The query form will start running, and you will see the Running indicator:

   

   The results will be displayed in the Results area.

Clear Form

You can clear the input from the Query Form by clicking the Clear Form button under the filter fields:

This action clears the current input in the filter fields on the form.

Cancel the Query Form Run

Click the Cancel button next to the Run button on the Query Form page when the query is still in progress:

This way of cancelling will result in a Canceled message under the corresponding statement:

View the Results

All results retrieved by a user are displayed as a list under Workspace. The Workspace area stores the execution history of the query form. Every time you hit the Run Form button, Alation retrieves a new result set.

You can view previous results by clicking on the corresponding execution timestamp in the list of results. If a query form run fails, there will be a red warning indicator next to the failed result. The currently displayed result set will be highlighted:

If you click the Run Form button again after executing the form, it will reuse the entered credentials or token and will not require re-authentication.

Pivot, Export, or Expand the Results

The results can be sent to a Pivot table, downloaded as a CSV file or expanded to view in full screen mode. Find the corresponding controls on the top right of the result set: