diff --git a/docs/users-guide/13-sql-parameters.md b/docs/users-guide/13-sql-parameters.md
index 40f78e5d66c78a39c48d2ab36984feea3b4ac7ac..0bf03996ec3114e6cf892fadc6747505c18505b9 100644
--- a/docs/users-guide/13-sql-parameters.md
+++ b/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
diff --git a/frontend/src/metabase/query_builder/components/template_tags/TagEditorHelp.jsx b/frontend/src/metabase/query_builder/components/template_tags/TagEditorHelp.jsx
index 6f729d704586c230d4d1c5497e45e0441d8e42ed..f373ab7ee386a5890947e560acc4b7641afdd4ee 100644
--- a/frontend/src/metabase/query_builder/components/template_tags/TagEditorHelp.jsx
+++ b/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")}