feat: filter & service corrections (#431)

## Summary

Closes a cluster of filter-correctness issues filed 2026-04-26 and adds the
first-party service base classes that downstream consumers have been
re-implementing.

- Closes #424 — `StatementFilter`s now emit qualified columns; dotted
  `field_name="users.name"` works without `AmbiguousColumnError` on joined
  SELECTs and the count-query path.
- Closes #425 — `SearchFilter` / `NotInSearchFilter` now raise `TypeError`
  for unsupported `field_name` types instead of silently dropping the WHERE
  clause, and accept `exp.Expression` (e.g. `LOWER(name)`) as a sort/search
  key — finishing the type widening started for #427.
- Closes #426 — `QueryBuilder.order_by(sql.raw("COL DESC"))` correctly
  emits `ORDER BY ... DESC` instead of treating `DESC` as a column alias.
- Closes #427 — `OrderByFilter.field_name` (and `SearchFilter.field_name`)
  accept `exp.Expression` for computed-column ordering/search; the wire
  surface (`?orderBy=`) stays `str`-only.
- Closes #428 — exposes `SearchFilter.like_pattern` and adds
  `SearchFilter.escape_like_value()` so consumers bypassing the standard
  filter pipeline can opt into safe `%`/`_` escaping.
- Closes #429 — adds first-party `SQLSpecAsyncService` /
  `SQLSpecSyncService` in `sqlspec/service.py`
  (`paginate`, `get_or_404`, `exists`, `begin`/`commit`/`rollback`,
  `begin_transaction`) and re-exports them from every framework
  extension package. Flask re-exports the sync class only.

Author: cofin

docs/recipes/service_layer.rst

@@ -39,7 +39,7 @@ Base Service
 
 
          class SQLSpecAsyncService(Generic[AsyncDriverT]):
-             """Base async service with pagination, get-or-404, and transactions."""
+             """Base async service with pagination, get-one, and transactions."""
 
              def __init__(self, driver: AsyncDriverT) -> None:
                  self.driver = driver
@@ -88,7 +88,7 @@ Base Service
                      total=total,
                  )
 
-             async def get_or_404(
+             async def get_one(
                  self,
                  statement: Statement | QueryBuilder,
                  /,
@@ -160,7 +160,7 @@ Base Service
 
 
          class SQLSpecSyncService(Generic[SyncDriverT]):
-             """Base sync service with pagination, get-or-404, and transactions."""
+             """Base sync service with pagination, get-one, and transactions."""
 
              def __init__(self, driver: SyncDriverT) -> None:
                  self.driver = driver
@@ -209,7 +209,7 @@ Base Service
                      total=total,
                  )
 
-             def get_or_404(
+             def get_one(
                  self,
                  statement: Statement | QueryBuilder,
                  /,
@@ -294,7 +294,7 @@ Filters from Litestar dependencies flow straight through ``*filters`` to the dri
                  )
 
              async def get_user(self, user_id: UUID) -> User:
-                 return await self.get_or_404(
+                 return await self.get_one(
                      sql.select("id", "email", "name").from_("users").where_eq("id", user_id),
                      schema_type=User,
                      error_message=f"User {user_id} not found",
@@ -338,7 +338,7 @@ Filters from Litestar dependencies flow straight through ``*filters`` to the dri
                  )
 
              def get_user(self, user_id: UUID) -> User:
-                 return self.get_or_404(
+                 return self.get_one(
                      sql.select("id", "email", "name").from_("users").where_eq("id", user_id),
                      schema_type=User,
                      error_message=f"User {user_id} not found",

docs/usage/filtering.rst

@@ -17,23 +17,59 @@ to get both the page data and the total matching count.
    :end-before: # end-example
    :dedent: 4
    :no-upgrade:
-
 Core Filter Types
 -----------------
 
 SQLSpec defines filter types in ``sqlspec.core`` that can be used independently
 or with framework integrations:
 
 - ``LimitOffsetFilter(limit, offset)`` -- pagination
-- ``OrderByFilter(field_name, sort_order)`` -- sorting
+- ``OrderByFilter(field_name, sort_order)`` -- sorting (supports expression mode)
 - ``SearchFilter(field_name, value, ignore_case)`` -- text search
 - ``BeforeAfterFilter(field_name, before, after)`` -- date range
 - ``InCollectionFilter(field_name, values)`` -- set membership
 - ``NotInCollectionFilter(field_name, values)`` -- set exclusion
 - ``NullFilter(field_name)`` -- IS NULL check
 - ``NotNullFilter(field_name)`` -- IS NOT NULL check
 
+Qualified Field Names
+~~~~~~~~~~~~~~~~~~~~~
+
+Every field-name-bearing filter supports table-qualified field names (e.g. ``p.name``).
+SQLSpec correctly parses these into qualified SQLGlot column references and sanitizes
+generated parameter names (e.g. ``p_name_search``), making filters safe to use in
+joined queries.
+
+.. code-block:: python
+
+    # Disambiguate columns in a JOIN
+    query = sql.select("p.name", "c.name").from_("parent p").join("child c", "p.id = c.parent_id")
+    filter_obj = SearchFilter(field_name="p.name", value="alice")
+    # Results in: WHERE p.name LIKE :p_name_search
+
+Expression Mode
+~~~~~~~~~~~~~~~
+
+Filters like ``OrderByFilter`` support passing a SQLGlot expression instead of a
+string field name. This allows complex sorting and filtering logic:
+
+.. code-block:: python
+
+    from sqlglot import exp
+
+    # Sort by COALESCE(lines, 0)
+    expr = exp.func("COALESCE", exp.column("lines"), exp.Literal.number(0))
+    filter_obj = OrderByFilter(field_name=expr, sort_order="desc")
+
+Search Patterns
+~~~~~~~~~~~~~~~
+
+``SearchFilter`` and ``NotInSearchFilter`` expose a ``like_pattern`` property
+that returns the percent-wrapped search value (e.g. ``%alice%``). This is useful
+when you need to use the pattern construction logic outside of the filter system.
+
 Litestar Filter Dependencies
+
 -----------------------------
 
 When using the Litestar extension, ``create_filter_dependencies()`` auto-generates
@@ -76,6 +112,27 @@ Using filters in a Litestar handler:
 The generated dependencies automatically handle query parameters for configured fields like
 ``?currentPage=2&pageSize=10&searchString=alice&orderBy=name&sortOrder=asc``.
 
+Service Layer
+-------------
+
+For common database operations and pagination in application services, SQLSpec provides
+base classes ``SQLSpecAsyncService`` and ``SQLSpecSyncService`` in ``sqlspec.service``.
+
+.. code-block:: python
+
+    from sqlspec.service import SQLSpecAsyncService
+    from sqlspec.core.filters import LimitOffsetFilter
+
+    class UserService(SQLSpecAsyncService):
+        async def list_users(self, filters: list[StatementFilter]) -> OffsetPagination[User]:
+            query = sql.select("*").from_("users")
+            return await self.paginate(query, *filters, schema_type=User)
+
+    async def some_handler(db_session: AsyncDriver, filters: list[StatementFilter]):
+        service = UserService(db_session)
+        page = await service.list_users(filters)
+        return page  # Returns OffsetPagination container
+
 Related Guides
 --------------
 

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.44.0"
+version = "0.45.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -264,7 +264,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.44.0"
+current_version = "0.45.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/builder/_select.py

@@ -425,7 +425,13 @@ def order_by(self, *items: Union[str, exp.Ordered, "Column"], desc: bool = False
                     order_item = order_item.desc()
             else:
                 extracted_item = extract_expression(item)
-                order_item = extracted_item.desc() if desc and not isinstance(item, exp.Ordered) else extracted_item
+                if isinstance(extracted_item, exp.Alias):
+                    alias_name = (extracted_item.alias or "").lower()
+                    if alias_name in {"asc", "desc"}:
+                        extracted_item = exp.Ordered(this=extracted_item.this, desc=alias_name == "desc")
+                order_item = (
+                    extracted_item.desc() if desc and not isinstance(extracted_item, exp.Ordered) else extracted_item
+                )
             current_expr = current_expr.order_by(order_item, copy=False)
         builder.set_expression(current_expr)
         return cast("Self", builder)