From 6473a7ecb089e50fddcc1a4286815f4e64c53511 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 3 Sep 2026 14:36:46 -0700
Subject: [PATCH] Clearly document relationship between execute-sql and facets

Refs GHSA-5fff-xcm9-q6vh

Co-authored-by: Alex Garcia <15178711+asg017@users.noreply.github.com>
---
 docs/authentication.rst | 4 ++++
 docs/facets.rst         | 2 ++
 docs/settings.rst       | 2 ++
 3 files changed, 8 insertions(+)

diff --git a/docs/authentication.rst b/docs/authentication.rst
index d720c4db..659c6989 100644
--- a/docs/authentication.rst
+++ b/docs/authentication.rst
@@ -771,6 +771,8 @@ Datasette defaults to allowing any site visitor to execute their own custom SQL
 
 Access to this ability is controlled by the :ref:`actions_execute_sql` permission.
 
+This permission does not apply to structured table-browsing operations where Datasette constructs the SQL, such as sorting, column filters and :ref:`facets`. Faceting is controlled separately by the :ref:`setting_allow_facet` setting.
+
 The easiest way to disable arbitrary SQL queries is using the :ref:`default_allow_sql setting <setting_default_allow_sql>` when you first start Datasette running.
 
 You can alternatively use an ``"allow_sql"`` block to control who is allowed to execute arbitrary SQL queries.
@@ -1521,6 +1523,8 @@ execute-sql
 
 Actor is allowed to run arbitrary read-only SQL queries against a specific database using the :ref:`custom SQL query page <pages_custom_sql_queries>`, e.g. https://latest.datasette.io/fixtures/-/query?sql=select+100
 
+This action also controls raw SQL supplied using ``?_where=``. It does not control structured table-browsing features such as :ref:`facets`, which use SQL generated by Datasette and are controlled by :ref:`setting_allow_facet`.
+
 ``resource`` - ``datasette.resources.DatabaseResource(database)``
     ``database`` is the name of the database (string)
 
diff --git a/docs/facets.rst b/docs/facets.rst
index 960ac03a..55802a9d 100644
--- a/docs/facets.rst
+++ b/docs/facets.rst
@@ -14,6 +14,8 @@ Here's `an example <https://congress-legislators.datasettes.com/legislators/legi
 
 Facets can be specified in two ways: using query string parameters, or in ``metadata.json`` configuration for the table.
 
+Facet queries are generated by Datasette and summarize rows the actor already has permission to view. They do not require the :ref:`actions_execute_sql` permission. Use the :ref:`setting_allow_facet` setting to control whether users can request facets using query string parameters.
+
 Facets in query strings
 -----------------------
 
diff --git a/docs/settings.rst b/docs/settings.rst
index 9c114e4a..5fd05d33 100644
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -71,6 +71,8 @@ Should users be able to execute arbitrary SQL queries by default?
 
 Setting this to ``off`` causes permission checks for :ref:`actions_execute_sql` to fail by default.
 
+This setting controls the ability to submit arbitrary SQL. It does not disable structured table-browsing features that use SQL generated by Datasette, such as sorting, column filters and :ref:`facets`. Use :ref:`setting_allow_facet` to control whether users can request facets.
+
 ::
 
     datasette mydatabase.db --setting default_allow_sql off