Reuse values and SQL with Parameters and snippets

What a Parameter is

A Parameter is a named value (a number, a text string or a date) that you plug into pipeline conditions, filters, calculations and step values. Instead of typing 100 into ten filters, you define a Max_Units parameter with value 100 and reference {Max_Units} everywhere. To change the threshold, you update the parameter once.

To reference a parameter, put curly braces around its name:

{Max_Units}

For example, a SQL rule like WHERE Discount < {Max_Discount} substitutes the parameter's current value at runtime. In most steps you don't type the braces: you pick the parameter from a picker, and Mammoth shows it as a {Max_Units} token.

What a Snippet is

A Snippet is a reusable block of SQL code. Where parameters hold one value, snippets hold logic, such as a SQL fragment, a subquery or a WHERE clause. You embed a snippet with double braces:

SELECT {{column_list}} FROM orders WHERE {{standard_date_filter}}

Snippets can reference parameters, so you can parameterise complex logic. A snippet's language is always SQL.

These Snippets live in the Data Library. The Snippets entry in Ask's navigation is unrelated: there, a snippet is a canvas of charts, numbers and notes saved from your chats.

Find Parameters and snippets in the library

Click Data in the left sidebar, then the Parameters tab in the Data Library tab bar (after Datasets, Connections and Automations). It shows every parameter and snippet for the current project.

The library groups items by category. Each row shows:

Stale rows are highlighted. A banner at the top, for example "2 parameters were updated. Rerun affected pipelines to apply changes.", offers Rerun stale pipelines.

Search and filter the library

• Use the Search parameters box to find by name.
• Click Filter to narrow by type (parameters or snippets), subtype (Date, Number, Text, SQL) or category.
• Group by switches the table between None, Category and Type. Category is the default.
• The Learn more icon links to help.

Who can manage Parameters and snippets

Creating, editing, duplicating and deleting parameters and snippets needs the Manage Parameters and Snippets permission, which Project Admin and Project Editor have. A Project Viewer can open the library and read every item, but New Parameter is disabled, with the tooltip "Your role doesn't have permission to perform this action". See Members, roles and custom roles.

Create a Parameter

1. On the Parameters tab, click New Parameter in the toolbar.
2. In the New Parameter dialog, choose the Parameter card.
3. Fill in the form (see the table below).
4. Click Create Parameter.

The parameter appears in the library under its category.

Every parameter created from this dialog is Project-scoped, so there's no Scope field. Names must be unique within their scope: you can't have two project-scoped parameters with the same name. See Project and workspace scope.

Create a Snippet

1. On the Parameters tab, click New Parameter and choose the Snippet card.
2. Set the Name. The rules are the same as for parameters.
3. Set the Value: the reusable SQL code. There's no language selector; snippets are always SQL. Type /param in the field to reference a parameter.
4. Optionally set Category and Description (under "More options").
5. Click Create Snippet.

The snippet appears in the library and can be referenced with {{name}}.

Snippet code can't reference other snippets. Saving fails with "Snippets cannot reference other snippets" if the code contains another snippet reference in double braces. Snippets can reference parameters, for example {Max_Units}.

Edit a Parameter or Snippet

Click any item in the library to open its detail panel, then click Edit. You can also click the edit icon that appears when you hover over a row.

You can update the value, description and category. The Name is read-only once the item exists ("Name can't be edited"), and the Type and Scope can't be changed.

When you save an edit:

• All pipelines that reference the item are flagged stale. The detail panel shows, for example, Stale in 3 pipelines with a Rerun button.
• Stale banners with a Rerun button also appear in the SQL rule, Apply Filter and Data check panels that use the changed value.
• The change is recorded in the item's history in the detail panel.

See which pipelines use a Parameter

Every parameter's detail panel has a Uses section listing each pipeline that references it, as a path of project, dataset and View. It shows exactly what a change will affect. Snippets show the same.

Use a Parameter in a filter condition

You need a parameter that already exists. When you add a condition to a filter in Builder mode, the small chip in front of the value reads Val by default.

1. Open a pipeline and add or edit a filter condition.
2. Click the Val chip in front of the value and select Parameter ("Bind to a project parameter"). The chip changes to #.
3. In the picker, search for and select the parameter. The picker shows the parameters whose type matches the column. To create one without leaving the condition, use the New Parameter link in the picker.
4. Save the condition. To unbind the parameter later, click the X on its token.

The filter uses the parameter's current value each time the pipeline runs. Parameters can also be used as inputs in Data check. See Filter rows.

A Conditional Filter in SQL mode does not read parameters, and {Max_Units} text in it stays plain text. Use Builder mode for a parameter-driven filter.

Where you can use a Parameter

In Math Function, the parameter is written into the expression as {name}. Two errors can appear:

• "Parameter ... not found": the formula names a parameter that doesn't exist.
• "Only numeric parameters allowed, ... is not one": a Text or Date parameter is in a formula.

For the full formula syntax, see Calculate with formulas.

Use a Snippet in a SQL rule

In a SQL rule, click Insert Snippet and pick the snippet. Choose how to insert it:

SELECT customer_id, SUM(amount)
FROM transactions
WHERE {{standard_date_filter}}
GROUP BY 1

At run time, Mammoth substitutes the snippet's code in place of {{standard_date_filter}}. When the snippet code changes, its detail panel flags the pipelines that use it as stale. Use Rerun to apply the change.

Rerun stale pipelines after a change

Saving a new value doesn't change any data straight away. Every pipeline that uses the item, in any of the steps above, is marked stale: its output may no longer reflect the current value. Mammoth does not rerun stale pipelines on its own; you start the rerun.

• Stale parameters are highlighted in the library, and the banner at the top offers Rerun stale pipelines.
• The detail panel shows a count such as Stale in 3 pipelines with a Rerun button.
• The SQL rule, Apply Filter and Data check panels show their own stale banner with Rerun.

A rerun reads the current value again and starts from the first task that uses the changed parameter, not from the beginning. Unchanged upstream tasks are not rerun.

Group Parameters into categories

Parameters and snippets can be grouped into categories. By default, all items go into General.

• Category headings in the library have inline rename and delete icons.
• To add or manage categories, click + Manage next to the category pills under More options when you create or edit an item.
• The Manage categories dialog lets you name categories and give them colours.

Deleting a category moves its items back to General. It does not delete the parameters or snippets.

Duplicate a Parameter or Snippet

1. Open the detail panel (or hover over a row) and click the duplicate icon next to Edit.
2. The Duplicate Parameter or Duplicate Snippet dialog opens with _copy added to the name (for example, Max_Units_copy).
3. Change the name or value if you like.
4. Click Create Duplicate. Nothing is created until you click it.

If the _copy name is already taken, you get "Name already in use", so choose another name.

Delete a Parameter or Snippet

Deleting a parameter or snippet is immediate and permanent. It has no Trash entry and no restore.

1. Open the detail panel and click the trash icon at the right of the header.
2. If no pipeline references the item, Delete parameter (or Delete snippet) asks "Are you sure you want to delete" followed by the name, for example Max_Units, and warns that this can't be undone.
3. Click Delete to confirm.

If a pipeline references the item, Cannot delete parameter (or Cannot delete snippet) says it "is used by pipelines and cannot be deleted". It lists each View with its task count and offers only Close. Remove the references first, then delete.

Project and workspace scope

The New Parameter dialog always creates a Project-scoped item; there is no Scope selector. Workspace-scoped parameters and snippets can exist in your workspace (for example, created through the API). Once they exist, you see and reference them like any other. A project-scoped Threshold and a workspace-scoped Threshold can coexist.

Scope can't be changed after an item is created.

See the history of a Parameter

Every parameter and snippet keeps a history of changes in its detail panel. Each entry shows how long ago the change happened, with the old value struck through, followed by the new value. Use it to trace why a downstream dataset changed back to a specific edit.

Limits

Troubleshooting

Related

• Filter rows: build the conditions parameters plug into.
• Calculate with formulas: Math Function and formula syntax.
• Write SQL with AI: SQL rules where snippets go.
• Find your way around the Data Library: the tab bar that holds Parameters.
• Get things back from Trash: what Trash covers, and why parameters aren't in it.