Make Field Filter usage more clear, when used with Optional Clauses (#10168)

* Make Field Filter usage more clear, when used with Optional Clauses

* Update text - thanks Victoria!

* Add note about table alias limitation - credit Victoria

docs/users-guide/13-sql-parameters.md

@@ -25,6 +25,8 @@ Setting a variable to the `field filter` type allows you to map it to a field in
 
 A field filter variable inserts SQL similar to that generated by the GUI query builder when adding filters on existing columns. This is useful because it lets you do things like insert dynamic date range filters into your native query. When adding a field filter, you should link that variable to a specific column. Field filter variables should be used inside of a `WHERE` clause.
 
+**Note:** Table aliases are not supported. This is because field filters generate SQL based on the mapped field.
+
 Example:
 
 ```
@@ -102,6 +104,18 @@ WHERE True
   [[AND category = {% raw %}{{category}}{% endraw %}]]
 ```
 
+When using a field filter, the column name should not be included in the SQL. Instead, the variable should be mapped to a field in the side panel.
+
+Example:
+
+```
+SELECT count(*)
+FROM products
+WHERE True
+  [[AND {% raw %}{{id}}{% endraw %}]]
+  [[AND {% raw %}{{category}}{% endraw %}]]
+```
+
 ---
 
 ## Next: automated x-ray explorations

frontend/src/metabase/query_builder/components/template_tags/TagEditorHelp.jsx

@@ -31,6 +31,7 @@ const EXAMPLES = {
           display_name: "Created At",
           type: "dimension",
           dimension: null,
+          required: false,
         },
       },
     },
@@ -58,7 +59,12 @@ const EXAMPLES = {
       query:
         "SELECT count(*)\nFROM products\nWHERE 1=1\n  [[AND id = {{id}}]]\n  [[AND category = {{category}}]]",
       "template-tags": {
-        id: { name: "id", display_name: "ID", type: "number", required: false },
+        id: {
+          name: "id",
+          display_name: "ID",
+          type: "number",
+          required: false,
+        },
         category: {
           name: "category",
           display_name: "Category",
@@ -68,6 +74,23 @@ const EXAMPLES = {
       },
     },
   },
+  optionalDimension: {
+    database: null,
+    type: "native",
+    native: {
+      query:
+        "SELECT count(*)\nFROM products\nWHERE 1=1\n  [[AND {{category}}]]",
+      "template-tags": {
+        category: {
+          name: "category",
+          display_name: "Category",
+          type: "dimension",
+          dimension: null,
+          required: false,
+        },
+      },
+    },
+  },
 };
 
 const TagExample = ({ datasetQuery, setDatasetQuery }) => (
@@ -126,11 +149,14 @@ const TagEditorHelp = ({ setDatasetQuery, sampleDatasetId }) => {
       <p>
         {t`When adding a Field Filter variable, you'll need to map it to a specific field. You can then choose to display a filter widget on your question, but even if you don't, you can now map your Field Filter variable to a dashboard filter when adding this question to a dashboard. Field Filters should be used inside of a "WHERE" clause.`}
       </p>
-      <TagExample datasetQuery={EXAMPLES.dimension} />
+      <TagExample
+        datasetQuery={EXAMPLES.dimension}
+        setDatasetQuery={setQueryWithSampleDatasetId}
+      />
 
       <h4 className="pt2">{t`Optional Clauses`}</h4>
       <p>
-        {jt`brackets around a ${(
+        {jt`Brackets around a ${(
           <Code>{"[[{{variable}}]]"}</Code>
         )} create an optional clause in the template. If "variable" is set, then the entire clause is placed into the template. If not, then the entire clause is ignored.`}
       </p>
@@ -147,6 +173,12 @@ const TagEditorHelp = ({ setDatasetQuery, sampleDatasetId }) => {
         setDatasetQuery={setQueryWithSampleDatasetId}
       />
 
+      <p>{t`When using a Field Filter, the column name should not be included in the SQL. Instead, the variable should be mapped to a field in the side panel.`}</p>
+      <TagExample
+        datasetQuery={EXAMPLES.optionalDimension}
+        setDatasetQuery={setQueryWithSampleDatasetId}
+      />
+
       <p className="pt2 link">
         <a
           href={MetabaseSettings.docsUrl("users-guide/13-sql-parameters")}