- What is a Parameter?
- Creating a Parameter on a Filtered View
- Editing a Parameter
- Adding a Parameter to a Query
- Important Notes About Parameters
What is a Parameter?
Parameters allow you to change a variable, such as a number, date, string, or Boolean, in the definition of a query, which can dynamically change the results of the query. You can use a parameter to change the values in a column, to change the logic of a calculated column or change the terms of a select in a query. This is a very powerful capability that can be used in an infinite number of ways to make your filtered view more flexible and capable of serving many use cases.
Creating a Parameter on a Filtered View
Parameters are attached to any derived view in the Exploration Canvas. When a parameter is created on a derived view it can be used on that view in the SoQL query. Any child views created from that parent view will also inherit the parameter from the parent view.
Add a Parameter
You can add a parameter to any draft derived view in Exploration Canvas, either when you are creating a new view or editing an existing view. To create a parameter:
Open a draft by clicking “Edit” on an existing view or selecting “Create View” from the Exploration Canvas
Navigate to the Parameters tab in the lower part of the Exploration Canvas
Click “New Parameter”
When the new parameter modal opens, choose an API field name
API field names must be all lower case and have no spaces
Choose a display name for your parameter. This display name will be shown where parameter controls are present, like in the Global Filter bar in Stories.
Choose a parameter data type
The Exploration Canvas allows for 4 types of Parameters to be used in your query:
Set a default value for your parameter. This is the value that will be evaluated by default on your view until it is overridden in a parameter control such as in stories.
Once you create the parameter you can copy the SoQL snippet in the modal to make it easier to add to your SoQL query. When you are finished click “Save”.
You will now see your newly created parameter listed in the Parameters tab with the name, type, and default value.
Note: You can also create a new parameter directly from the SoQL tab by clicking "Create New" directly from the Insert Parameter button in the SoQL Query Editor
Editing a Parameter
To edit a parameter, select the Actions button in the row to the right of the parameter you want to change. Select “Edit” from the dropdown.
From here you can change the display name and default value for your parameter. API field names and types cannot be modified after the parameter has been created. Changing the default value and saving will also change the results in the table of the Exploration Canvas.
Adding a Parameter to a Query
Once you have created a parameter, you need to add it to your SoQL query to use it. You can easily add parameters to your query in a couple of ways:
Use the “insert parameter” button in the SoQL Query Editor
Select the “copy” button from the SoQL Usage section of the create/edit modal for your parameter and paste the snippet into your query.
You can add a parameter in a number of different ways to change your query. For example, you can add it to a case statement in your SELECT to change values in a calculated column, or use it in a WHERE clause to change the data returned based on the parameter value.
Check out this article on Parameters Use Cases for more ideas on how you can use parameters to make your filtered views even more powerful!
Important Notes About Parameters
- When a parameter is created, it's attached to the view it's created on, and can only be used in that derived view, a child view of that derived view, or as a joined view. Any related views will inherit the parameter of the parent view, and the value in that view will be applied to related views using that parameter.
- Parameters cannot be deleted until they are removed from the query. This is to ensure that the query won't fail after a parameter is used.
- Once a parameter has been created you can change the Display name or the default value, but the API field name and the type of parameter cannot be changed once it is created.