A parameter is a placeholder in your SQL whose value you fill in before a run. Use one when you run the same query again with different inputs, such as a customer ID or a date, without editing the SQL each time.
WHERE order_date >= .user_id. Choose a Type, and optionally enter a Value.Add writes the {name:Type} placeholder into the SQL at the cursor. A parameter reaches the query only through its placeholder.
SELECT * FROM <database>."<table>" WHERE order_date >= {from:Date}You can also type {name:Type} straight into the SQL. Its chip appears in the Parameters strip as From query.
Every chip carries a small dot. Hover over the chip to read where the parameter came from, and open it for the short explanation:
If the same name comes from more than one place, you still see one chip: the placeholder in the SQL wins over a required parameter, and a required parameter wins over a manual one.
Some screens open the Editor in a popup with parameters of their own. There, Add parameter is locked and Ctrl+P does nothing, and the origin notes are hidden, because the popup decides which parameters exist. An info icon beside the strip title can explain the popup's own rules.
The Parameters strip shows one chip for each parameter, and a badge beside its title counts them: it reads {n} parameter(s), and turns red with {n} missing while a required value is still empty. Each chip shows the parameter's name, type and value.
A chip with no value shows empty; a Required chip whose value is missing shows required and turns red. The popover shows the {name:Type} text with a button titled Copy parameter format, and a From query or Required chip also shows a lock icon and the note about its origin.
Parameters and their values save with the console a moment after you change them, and straight away when you switch consoles. When you reopen the console, the values are still there. Consoles are private to you. See Consoles, saving and history.
Each run in the console's History tab shows the query with the values it used, so you can check what ran. See Console history and run log.
Remove takes the parameter out of the editor's parameter list; it does not change your SQL text.
A From query chip has no Remove button. To remove that parameter, delete its {name:Type} placeholder from the SQL; the chip disappears with it. A Required parameter comes from the screen that opened the editor and cannot be removed here.
| Setting | What it does | Default |
|---|---|---|
| Name | The name inside the placeholder. Letters, digits and underscores only, starting with a letter or underscore. Required. | None |
| Type | The type the database converts the value to. Pick it from the searchable list. | String |
| Value | The value used for the run. You can leave it empty and fill it in on the chip later. | Empty, shown as empty |
Parameters need no permission of their own. You use them wherever you can open the Editor. See Editor for who can open it.
{customer}, counts as String.Array(String), is not detected as a parameter, so it gets no chip.{name:Type} placeholders, so a query with parameters is checked like any other. See Write and check SQL.Write {name:Type}, for example {customer_id:UInt64} or {from:Date}. You choose the name. The type comes after the colon; if you leave it out, the parameter counts as String.
No. Write {name:String} without quotes, and type the text as it is in the Value field. The database converts the value to the type of the placeholder.
The name may use only letters, digits and underscores, and must start with a letter or underscore. The same message appears for any name that breaks these rules, including one with a hyphen. Use user_id instead of user-id.
For a Manual parameter, click Remove on its chip. For a From query parameter, delete its placeholder from the SQL; its chip disappears with it. A Required parameter cannot be removed here: it comes from the screen that opened the editor.
Yes. Parameters and their values are saved with the console, so they are there when you come back to it. Consoles are private to you. See Consoles, saving and history.
Yes. Write the same {name:Type} placeholder in both places. The strip shows one chip, and its value fills both places.
String, UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, Float32, Float64, Date, DateTime, DateTime64, Bool, UUID, IPv4 and IPv6. String is the default.
The dot's colour and hover text show where the parameter came from: From query for a placeholder in your SQL, Required for a parameter the screen that opened the editor needs, and Manual for one you added. Open the chip to read the explanation.
A parameter marked Required comes from the screen that opened the editor, and the run stays unavailable until every required parameter has a value. Hover over the run button to see Fill required parameters: followed by the names that are still missing.
The strip shows only while the console has a parameter. When the last one is gone, it hides. Press Ctrl+P to add a parameter; the strip returns with the New parameter form, showing None - add one or use {name:Type} in the query until you click Add. On a screen that locks the parameter list, the strip with no parameters reads No parameters provided.
Yes. While you type, autocomplete offers your parameters in their full {name:Type} form. See Write and check SQL.