Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs(sql): document workarounds for refreshing SQL cells in app mode (#10418)

Shahmir Varqha24d17d8ad072
diff --git a/docs/guides/working_with_data/sql.md b/docs/guides/working_with_data/sql.md
index cec7bbab06..8717c71497 100644
--- a/docs/guides/working_with_data/sql.md
+++ b/docs/guides/working_with_data/sql.md
@@ -145,6 +145,46 @@ SELECT * FROM read_parquet('path/to/example.parquet');
For a full list you can check out the [duckdb extensions](https://duckdb.org/docs/extensions/overview).
You can also check out our [examples on GitHub](https://github.com/marimo-team/marimo/tree/main/examples/sql).
+## Refreshing SQL queries
+
+If you'd like to refresh your SQL cells automatically, you can wire a UI element into the SQL cell's dependency graph.
+
+### Periodic refresh with `mo.ui.refresh`
+
+Add a [`mo.ui.refresh`][marimo.ui.refresh] control and reference it in your SQL query. Because SQL cells use f-strings, include the refresh control in a SQL comment so it does not affect the query:
+
+```python
+refresh = mo.ui.refresh(default_interval="30s")
+refresh
+```
+
+```sql
+SELECT * FROM my_table
+-- {refresh}
+```
+
+Each time the refresh timer fires, the SQL cell re-runs. See the [refresh recipe](../../recipes.md#run-a-cell-on-a-timer) for more details.
+
+### Manual refresh with a button
+
+For on-demand refresh, add a [`mo.ui.button`][marimo.ui.button] and reference it in the cell that runs your query.
+
+In a **SQL cell**, reference the button in a comment:
+
+```python
+refresh_button = mo.ui.button(label="Refresh data")
+refresh_button
+```
+
+```sql
+SELECT * FROM my_table
+-- {refresh_button}
+```
+
+### Other UI elements
+
+SQL queries can interpolate any Python value, so dropdowns, sliders, text inputs, and other UI elements already trigger re-queries when their values change. See the [`parametrizing_sql_queries.py` example](https://github.com/marimo-team/marimo/blob/main/examples/sql/parametrizing_sql_queries.py) on GitHub.
+
## Escaping SQL brackets
Our "SQL" cells are really just Python under the hood to keep notebooks as pure Python scripts. By default, we use `f-strings` for SQL strings, which allows for parameterized SQL like `SELECT * from table where value < {min}`.