docs - note on sandboxing and optional parameters (#30936) (#30982)

Co-authored-by: Jeff Bruemmer <jeff.bruemmer@gmail.com>

docs/permissions/data-sandbox-examples.md

@@ -79,7 +79,7 @@ Here's the table I'm going to filter:
 
 ![Original Orders table](images/advanced-example-2-orders-table.png)
 
-The filtering question that I'll create will exclude columns that I don't want these users to see, and I'll also add in an optional `WHERE` clause which defines a variable, `cid`, that I can then reference in my sandbox. Here's what it looks like:
+The filtering question that I'll create will exclude columns that I don't want these users to see, and I'll also add in a `WHERE` clause which defines a variable, `cid`, that I can then reference in my sandbox. Here's what it looks like:
 
 ![Filtering question](images/advanced-example-2-filtering-question.png)
 
@@ -95,7 +95,7 @@ SELECT
   user_id
 FROM
   orders
-[[WHERE user_id = {%raw%}{{cid}}{%endraw%}]]
+WHERE user_id = {%raw%}{{cid}}{%endraw%}
 ```
 
 Going back over to the Permissions section, when I open up the sandboxed access modal and select the second option and select my filtering question, I'll see an additional section which allows me to map the variable I defined in my question with a user attribute:

docs/permissions/data-sandboxes.md

@@ -161,7 +161,7 @@ You cannot add a column to a custom sandbox.
 5. Click on the dropdown under **Data access** for that group.
 6. Select "Sandboxed".
 7. Select "Use a saved question to create a custom view for this table".
-8. Select your saved question.
+8. Select your saved question. The question should be written in SQL. If the question contains parameters, those parameters must be required (they cannot be optional). 
 9. Optional: [restrict rows based on people's user attributes](#restricting-rows-in-an-custom-sandbox-with-user-attributes).
 
 > If you have saved SQL questions that use sandboxed data, make sure to move all of those questions to admin-only collections. For more info, see [Permissions conflicts: saved SQL questions](#saved-sql-questions).
@@ -174,7 +174,7 @@ You can set up an custom sandbox to restrict different rows for each person depe
 
 1. Make sure you've done all the [prerequisites for custom sandboxes](#prerequisites-for-custom-sandboxes).
 2. Go to the saved SQL question that will be displayed to the people in the custom sandbox.
-3. Add a [parameterized](../questions/native-editor/sql-parameters.md) `WHERE` clause to your SQL query, such as `{%raw%}[[ WHERE plan = {{ plan_variable }} ]]{%endraw%}`.
+3. Add a [parameterized](../questions/native-editor/sql-parameters.md) `WHERE` clause to your SQL query, such as `{%raw%}WHERE plan = {{ plan_variable }} {%endraw%}`.
 4. Save the SQL question.
 5. Go to **Admin settings** > **Permissions**.
 6. Find the group and table for your custom sandbox.
@@ -202,12 +202,20 @@ In step 2 of the [row restriction setup](#restricting-rows-in-an-custom-sandbox-
 WHERE plan = {%raw%}{{ plan_variable }}{%endraw%}
 ```
 
-In steps 9-10 of the [row restriction setup](#restricting-rows-in-an-custom-sandbox-with-user-attributes) above, you're telling Metabase to map the SQL variable `plan_variable` to a **user attribute key** (such as "User's Plan"). Metabase will user the key to look up the specific **user attribute value** (such as "Basic") associated with a person's Metabase account. When that person logs into Metabase and uses the sandboxed table, they'll see the query result that is filtered on:
+In steps 9-10 of the [row restriction setup](#restricting-rows-in-an-custom-sandbox-with-user-attributes) above, you're telling Metabase to map the SQL variable `plan_variable` to a **user attribute key** (such as "User's Plan"). Metabase will use the key to look up the specific **user attribute value** (such as "Basic") associated with a person's Metabase account. When that person logs into Metabase and uses the sandboxed table, they'll see the query result that is filtered on:
 
 ```
 WHERE plan = "Basic"
 ```
 
+Note that the parameters must be required for SQL questions used to create a custom sandbox. E.g., you cannot use an optional parameter; the following won't work:
+
+```
+[[WHERE plan = {%raw%}{{ plan_variable }}{%endraw%}]]
+```
+
+Learn more about [SQL parameters](../questions/native-editor/sql-parameters.md)
+
 ## Preventing data sandbox permissions conflicts
 
 Some Metabase permissions can conflict with data sandboxes to give more permissive or more restrictive data access than you intended.