diff --git a/docs/json_api.rst b/docs/json_api.rst index cd034568..1ea35672 100644 --- a/docs/json_api.rst +++ b/docs/json_api.rst @@ -176,10 +176,68 @@ querystring arguments: .. _table_arguments: -Special table arguments ------------------------ +Table arguments +--------------- -The Datasette table view takes a number of special querystring arguments: +The Datasette table view takes a number of special querystring arguments. + +Column filter arguments +~~~~~~~~~~~~~~~~~~~~~~~ + +You can filter the data returned by the table based on column values using a querystring argument. + +``?column__exact=value`` or ``?_column=value`` + Returns rows where the specified column exactly matches the value. + +``?column__not=value`` + Returns rows where the column does not match the value. + +``?column__contains=value`` + Rows where the string column contains the specified value (``column like "%value%"`` in SQL). + +``?column__endswith=value`` + Rows where the string column ends with the specified value (``column like "%value"`` in SQL). + +``?column__startswith=value`` + Rows where the string column starts with the specified value (``column like "value%"`` in SQL). + +``?column__gt=value`` + Rows which are greater than the specified value. + +``?column__gte=value`` + Rows which are greater than or equal to the specified value. + +``?column__lt=value`` + Rows which are less than the specified value. + +``?column__lte=value`` + Rows which are less than or equal to the specified value. + +``?column__like=value`` + Match rows with a LIKE clause, case insensitive and with ``%`` as the wildcard character. + +``?column__glob=value`` + Similar to LIKE but uses Unix wildcard syntax and is case sensitive. + +``?column__arraycontains=value`` + Works against columns that contain JSON arrays - matches if any of the values in that array match. + + This is only available if the ``json1`` SQLite extension is enabled. + +``?column__isnull=1`` + Matches rows where the column is null. + +``?column__notnull=1`` + Matches rows where the column is not null. + +``?column__isblank=1`` + Matches rows where the column is blank, meaning null or the empty string. + +``?column__notblank=1`` + Matches rows where the column is not blank. + +Special table arguments +~~~~~~~~~~~~~~~~~~~~~~~ ``?_labels=on/off`` Expand foreign key references for every possible column. See below. diff --git a/tests/test_docs.py b/tests/test_docs.py index 6f84832d..caf1cff3 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -4,6 +4,7 @@ Tests to ensure certain things are documented. from click.testing import CliRunner from datasette import app from datasette.cli import cli +from datasette.filters import Filters from pathlib import Path import pytest import re @@ -71,3 +72,20 @@ def documented_views(): @pytest.mark.parametrize("view_class", [v for v in dir(app) if v.endswith("View")]) def test_view_classes_are_documented(documented_views, view_class): assert view_class in documented_views + + +@pytest.fixture(scope="session") +def documented_table_filters(): + json_api_rst = (docs_path / "json_api.rst").read_text() + section = json_api_rst.split(".. _table_arguments:")[-1] + # Lines starting with ``?column__exact= are docs for filters + return set( + line.split("__")[1].split("=")[0] + for line in section.split("\n") + if line.startswith("``?column__") + ) + + +@pytest.mark.parametrize("filter", [f.key for f in Filters._filters]) +def test_table_filters_are_documented(documented_table_filters, filter): + assert filter in documented_table_filters