sqlspec 0.46.1__tar.gz → 0.46.2__tar.gz

{sqlspec-0.46.1 → sqlspec-0.46.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.46.1
+Version: 0.46.2
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.46.1 → sqlspec-0.46.2}/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.46.1"
+version = "0.46.2"
 
 [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.46.1"
+current_version = "0.46.2"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec-0.46.2/sqlspec/extensions/_filter_aliases.py

@@ -0,0 +1,112 @@
+"""Shared filter alias helpers for framework extensions."""
+
+from collections.abc import Mapping
+from typing import NamedTuple
+
+from sqlspec.utils.text import camelize
+
+__all__ = ("SortField", "SortFieldResolution", "resolve_sort_field_aliases")
+
+SortField = str | set[str] | list[str]
+
+
+class SortFieldResolution(NamedTuple):
+    """Resolved sort-field alias metadata.
+
+    Args:
+        default_field: Internal SQL-facing field used when no query value is supplied.
+        default_query_value: API-facing default value exposed on the query parameter.
+        allowed_fields: Internal SQL-facing allowlist.
+        inbound_aliases: API-facing query values mapped to internal field names.
+        field_display_names: Internal field names mapped to their preferred API-facing display names.
+        allowed_display_names: Display names ordered to match the configured sort fields.
+    """
+
+    default_field: str
+    default_query_value: str
+    allowed_fields: frozenset[str]
+    inbound_aliases: dict[str, str]
+    field_display_names: dict[str, str]
+    allowed_display_names: tuple[str, ...]
+
+    def normalize(self, value: str | None) -> str | None:
+        """Normalize a query value to an internal field name.
+
+        Args:
+            value: API-facing query value, or ``None`` to request the default field.
+
+        Returns:
+            The internal field name if the value is configured, otherwise ``None``.
+        """
+        if value is None:
+            return self.default_field
+        return self.inbound_aliases.get(value)
+
+
+def resolve_sort_field_aliases(
+    sort_field: SortField, sort_field_aliases: Mapping[str, str] | None = None, sort_field_camelize: bool = True
+) -> SortFieldResolution:
+    """Resolve sort-field aliases to a closed allowlist map.
+
+    Args:
+        sort_field: Configured SQL-facing sort field or fields.
+        sort_field_aliases: Optional API-facing alias to SQL-facing field mapping.
+        sort_field_camelize: Whether to generate camel-case aliases for configured fields. Defaults to ``True``.
+
+    Returns:
+        Precomputed alias metadata for framework filter providers.
+
+    Raises:
+        ValueError: If an alias targets an unknown field or collides with a different field.
+    """
+    fields = _coerce_fields(sort_field)
+    allowed_fields = frozenset(fields)
+    inbound_aliases: dict[str, str] = {}
+    field_display_names = {field: field for field in fields}
+
+    for field in fields:
+        _add_alias(inbound_aliases, alias=field, field=field)
+
+    if sort_field_camelize:
+        for field in fields:
+            alias = camelize(field)
+            _add_alias(inbound_aliases, alias=alias, field=field)
+            field_display_names[field] = alias
+
+    if sort_field_aliases:
+        for alias, field in sort_field_aliases.items():
+            if field not in allowed_fields:
+                msg = f"sort field alias '{alias}' targets unknown sort field '{field}'"
+                raise ValueError(msg)
+            _add_alias(inbound_aliases, alias=alias, field=field)
+            field_display_names[field] = alias
+
+    allowed_display_names = tuple(field_display_names[field] for field in fields)
+    return SortFieldResolution(
+        default_field=fields[0],
+        default_query_value=field_display_names[fields[0]],
+        allowed_fields=allowed_fields,
+        inbound_aliases=inbound_aliases,
+        field_display_names=field_display_names,
+        allowed_display_names=allowed_display_names,
+    )
+
+
+def _coerce_fields(sort_field: SortField) -> tuple[str, ...]:
+    if isinstance(sort_field, str):
+        return (sort_field,)
+    fields = tuple(sorted(sort_field)) if isinstance(sort_field, set) else tuple(sort_field)
+    if not fields:
+        msg = "sort_field must include at least one field"
+        raise ValueError(msg)
+    return fields
+
+
+def _add_alias(inbound_aliases: dict[str, str], *, alias: str, field: str) -> None:
+    existing_field = inbound_aliases.get(alias)
+    if existing_field is None or existing_field == field:
+        inbound_aliases[alias] = field
+        return
+
+    msg = f"ambiguous sort field alias '{alias}' maps to both '{existing_field}' and '{field}'"
+    raise ValueError(msg)

{sqlspec-0.46.1 → sqlspec-0.46.2}/sqlspec/extensions/fastapi/extension.py

@@ -374,7 +374,7 @@ class SQLSpecPlugin(_StarlettePlugin):
                         "search": "name,email",
                         "search_ignore_case": True,
                         "pagination_type": "limit_offset",
-                        "sort_field": "created_at",
+                        "sort_field": ["created_at", "uploaded_collections"],
                     })
                 ),
             ):

{sqlspec-0.46.1 → sqlspec-0.46.2}/sqlspec/extensions/fastapi/providers.py

@@ -24,6 +24,7 @@ from sqlspec.core import (
     OrderByFilter,
     SearchFilter,
 )
+from sqlspec.extensions._filter_aliases import resolve_sort_field_aliases
 from sqlspec.utils.singleton import SingletonMeta
 from sqlspec.utils.text import camelize
 
@@ -88,36 +89,45 @@ class FieldNameType(NamedTuple):
 
 
 class FilterConfig(TypedDict):
-    """Configuration for generating dynamic filters for FastAPI."""
+    """Configuration for generated FastAPI filter dependencies.
+
+    All keys are optional. A filter dependency is created only for each enabled
+    key. Field names are SQL-facing allowlist values; generated query parameter
+    names and order-by aliases remain API-facing.
+    """
 
     id_filter: NotRequired[type[UUID | int | str]]
-    """Type of ID filter to enable (UUID, int, or str). When set, enables collection filtering by IDs."""
+    """Type of ID filter to enable. When set, creates an ``ids`` collection filter."""
     id_field: NotRequired[str]
-    """Field name for ID filtering. Defaults to 'id'."""
+    """SQL-facing field name for ID filtering. Defaults to ``"id"``."""
     sort_field: NotRequired[SortField]
-    """Allowed field(s) to use for sorting."""
+    """Allowed SQL-facing field or fields for ``orderBy`` sorting."""
+    sort_field_aliases: NotRequired[dict[str, str]]
+    """Additional API-facing ``orderBy`` aliases mapped to configured ``sort_field`` values."""
+    sort_field_camelize: NotRequired[bool]
+    """Whether to accept camel-case aliases for configured sort fields. Defaults to ``True``."""
     sort_order: NotRequired[SortOrder]
-    """Default sort order ('asc' or 'desc'). Defaults to 'desc'."""
+    """Default sort order. Defaults to ``"desc"``."""
     pagination_type: NotRequired[Literal["limit_offset"]]
-    """When set to 'limit_offset', enables pagination with page size and current page parameters."""
+    """Pagination strategy to enable. Currently supports ``"limit_offset"``."""
     pagination_size: NotRequired[int]
-    """Default pagination page size. Defaults to DEFAULT_PAGINATION_SIZE (20)."""
+    """Default page size for limit/offset pagination."""
     search: NotRequired[str | set[str]]
-    """Field(s) to enable search filtering on. Can be comma-separated string or set of field names."""
+    """SQL-facing field or fields to search. Strings may be comma-separated."""
     search_ignore_case: NotRequired[bool]
-    """When True, search is case-insensitive. Defaults to False."""
+    """Whether search filtering is case-insensitive. Defaults to ``False``."""
     created_at: NotRequired[bool]
-    """When True, enables created_at date range filtering. Uses 'created_at' field by default."""
+    """Whether to enable ``created_at`` before/after range filtering."""
     updated_at: NotRequired[bool]
-    """When True, enables updated_at date range filtering. Uses 'updated_at' field by default."""
+    """Whether to enable ``updated_at`` before/after range filtering."""
     not_in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
-    """Fields that support not-in collection filtering. Can be single field or set of fields with type info."""
+    """Field or fields that support ``NOT IN`` collection filtering."""
     in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
-    """Fields that support in-collection filtering. Can be single field or set of fields with type info."""
+    """Field or fields that support ``IN`` collection filtering."""
     null_fields: NotRequired[str | set[str]]
-    """Fields that support IS NULL filtering. Can be single field name or set of field names."""
+    """Field or fields that support ``IS NULL`` filtering."""
     not_null_fields: NotRequired[str | set[str]]
-    """Fields that support IS NOT NULL filtering. Can be single field name or set of field names."""
+    """Field or fields that support ``IS NOT NULL`` filtering."""
 
 
 class DependencyCache(metaclass=SingletonMeta):
@@ -154,13 +164,6 @@ def _empty_filter_list() -> "list[FilterTypes]":
     return []
 
 
-def _resolve_sort_fields(sort_field: SortField) -> tuple[str, set[str]]:
-    if isinstance(sort_field, str):
-        return sort_field, {sort_field}
-    fields = tuple(sorted(sort_field)) if isinstance(sort_field, set) else tuple(sort_field)
-    return fields[0], set(fields)
-
-
 def provide_filters(
     config: FilterConfig, dep_defaults: DependencyDefaults = DEPENDENCY_DEFAULTS
 ) -> "Callable[..., list[FilterTypes]]":
@@ -456,19 +459,26 @@ def _create_filter_aggregate_function_fastapi(  # noqa: C901
 
     if sort_field := config.get("sort_field"):
         sort_order_default = config.get("sort_order", "desc")
-        default_field, allowed_fields = _resolve_sort_fields(sort_field)
-        allowed_field_names = ", ".join(sorted(allowed_fields))
+        sort_resolution = resolve_sort_field_aliases(
+            sort_field,
+            sort_field_aliases=config.get("sort_field_aliases"),
+            sort_field_camelize=config.get("sort_field_camelize", True),
+        )
+        allowed_field_names = ", ".join(sort_resolution.allowed_display_names)
 
         def provide_order_by(
-            field_name: Annotated[str, Query(alias="orderBy", description="Field to order by.")] = default_field,
+            field_name: Annotated[str, Query(alias="orderBy", description="Field to order by.")] = (
+                sort_resolution.default_query_value
+            ),
             sort_order: Annotated[
                 SortOrder | None, Query(alias="sortOrder", description="Sort order ('asc' or 'desc').")
             ] = sort_order_default,
         ) -> OrderByFilter:
-            if field_name not in allowed_fields:
+            resolved_field = sort_resolution.normalize(field_name)
+            if resolved_field is None:
                 msg = f"Invalid orderBy field '{field_name}'. Allowed fields: {allowed_field_names}"
                 raise RequestValidationError(errors=[{"loc": ("query", "orderBy"), "msg": msg, "type": "value_error"}])
-            return OrderByFilter(field_name=field_name, sort_order=sort_order or sort_order_default)
+            return OrderByFilter(field_name=resolved_field, sort_order=sort_order or sort_order_default)
 
         param_name = dep_defaults.ORDER_BY_FILTER_DEPENDENCY_KEY
         params.append(

{sqlspec-0.46.1 → sqlspec-0.46.2}/sqlspec/extensions/litestar/providers.py

@@ -26,6 +26,7 @@ from sqlspec.core import (
     OrderByFilter,
     SearchFilter,
 )
+from sqlspec.extensions._filter_aliases import resolve_sort_field_aliases
 from sqlspec.utils.singleton import SingletonMeta
 from sqlspec.utils.text import camelize
 
@@ -85,24 +86,45 @@ class FieldNameType(NamedTuple):
 
 
 class FilterConfig(TypedDict):
-    """Configuration for generating dynamic filters."""
+    """Configuration for generated Litestar filter dependencies.
+
+    All keys are optional. A filter dependency is created only for each enabled
+    key. Field names are SQL-facing allowlist values; generated query parameter
+    names and order-by aliases remain API-facing.
+    """
 
     id_filter: NotRequired[type[UUID | int | str]]
+    """Type of ID filter to enable. When set, creates an ``ids`` collection filter."""
     id_field: NotRequired[str]
+    """SQL-facing field name for ID filtering. Defaults to ``"id"``."""
     sort_field: NotRequired[SortField]
+    """Allowed SQL-facing field or fields for ``orderBy`` sorting."""
+    sort_field_aliases: NotRequired[dict[str, str]]
+    """Additional API-facing ``orderBy`` aliases mapped to configured ``sort_field`` values."""
+    sort_field_camelize: NotRequired[bool]
+    """Whether to accept camel-case aliases for configured sort fields. Defaults to ``True``."""
     sort_order: NotRequired[SortOrder]
+    """Default sort order. Defaults to ``"desc"``."""
     pagination_type: NotRequired[Literal["limit_offset"]]
+    """Pagination strategy to enable. Currently supports ``"limit_offset"``."""
     pagination_size: NotRequired[int]
+    """Default page size for limit/offset pagination."""
     search: NotRequired[str | set[str] | list[str]]
+    """SQL-facing field or fields to search. Strings may be comma-separated."""
     search_ignore_case: NotRequired[bool]
+    """Whether search filtering is case-insensitive. Defaults to ``False``."""
     created_at: NotRequired[bool]
+    """Whether to enable ``created_at`` before/after range filtering."""
     updated_at: NotRequired[bool]
+    """Whether to enable ``updated_at`` before/after range filtering."""
     not_in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
+    """Field or fields that support ``NOT IN`` collection filtering."""
     in_fields: NotRequired[FieldNameType | set[FieldNameType] | list[str | FieldNameType]]
+    """Field or fields that support ``IN`` collection filtering."""
     null_fields: NotRequired[str | set[str] | list[str]]
-    """Fields that support IS NULL filtering."""
+    """Field or fields that support ``IS NULL`` filtering."""
     not_null_fields: NotRequired[str | set[str] | list[str]]
-    """Fields that support IS NOT NULL filtering."""
+    """Field or fields that support ``IS NOT NULL`` filtering."""
 
 
 class DependencyCache(metaclass=SingletonMeta):
@@ -164,13 +186,6 @@ def _make_hashable(value: Any) -> HashableType:
     return str(value)
 
 
-def _resolve_sort_fields(sort_field: SortField) -> tuple[str, set[str]]:
-    if isinstance(sort_field, str):
-        return sort_field, {sort_field}
-    fields = tuple(sorted(sort_field)) if isinstance(sort_field, set) else tuple(sort_field)
-    return fields[0], set(fields)
-
-
 def _build_in_collection_provider(field: FieldNameType, *, negated: bool) -> Callable[..., Any]:
     """Build a per-field `IN` / `NOT IN` filter provider with a unique parameter name.
 
@@ -338,21 +353,25 @@ def _create_statement_filters(
         filters[dep_defaults.SEARCH_FILTER_DEPENDENCY_KEY] = Provide(provide_search_filter, sync_to_thread=False)
 
     if sort_field := config.get("sort_field"):
-        default_field, allowed_fields = _resolve_sort_fields(sort_field)
-        allowed_field_names = ", ".join(sorted(allowed_fields))
+        sort_resolution = resolve_sort_field_aliases(
+            sort_field,
+            sort_field_aliases=config.get("sort_field_aliases"),
+            sort_field_camelize=config.get("sort_field_camelize", True),
+        )
+        allowed_field_names = ", ".join(sort_resolution.allowed_display_names)
         sort_order_default = config.get("sort_order", "desc")
 
         def provide_order_by(
             field_name: StringOrNone = Parameter(
-                title="Order by field", query="orderBy", default=default_field, required=False
+                title="Order by field", query="orderBy", default=sort_resolution.default_query_value, required=False
             ),
             sort_order: SortOrderOrNone = Parameter(
                 title="Field to search", query="sortOrder", default=sort_order_default, required=False
             ),
         ) -> OrderByFilter:
-            resolved_field = field_name or default_field
-            if resolved_field not in allowed_fields:
-                msg = f"Invalid orderBy field '{resolved_field}'. Allowed fields: {allowed_field_names}"
+            resolved_field = sort_resolution.normalize(field_name) if field_name else sort_resolution.default_field
+            if resolved_field is None:
+                msg = f"Invalid orderBy field '{field_name}'. Allowed fields: {allowed_field_names}"
                 raise ValidationException(detail=msg)
             return OrderByFilter(field_name=resolved_field, sort_order=sort_order or sort_order_default)
 

{sqlspec-0.46.1 → sqlspec-0.46.2}/tests/integration/extensions/fastapi/test_filters_integration.py

@@ -181,6 +181,45 @@ def test_fastapi_order_by_filter_dependency() -> None:
         assert response.status_code == 422
 
 
+def test_fastapi_order_by_filter_accepts_camelized_alias_dependency() -> None:
+    """Camelized orderBy values normalize to SQL-facing fields."""
+    sqlspec = SQLSpec()
+    config = AiosqliteConfig(
+        connection_config={"database": ":memory:"}, extension_config={"fastapi": {"commit_mode": "manual"}}
+    )
+    sqlspec.add_config(config)
+
+    app = FastAPI()
+    db_ext = SQLSpecPlugin(sqlspec, app=app)
+
+    @app.get("/users")
+    async def list_users(
+        filters: Annotated[
+            list[FilterTypes], Depends(db_ext.provide_filters({"sort_field": ["created_at", "uploaded_collections"]}))
+        ],
+    ) -> dict[str, Any]:
+        order_by = next((f for f in filters if isinstance(f, OrderByFilter)), None)
+        if order_by:
+            return {"field": order_by.field_name, "order": order_by.sort_order}
+        return {"field": None, "order": None}
+
+    with TestClient(app) as client:
+        response = client.get("/users?orderBy=uploadedCollections&sortOrder=asc")
+        assert response.status_code == 200
+        assert response.json() == {"field": "uploaded_collections", "order": "asc"}
+
+        response = client.get("/users?orderBy=uploaded_collections&sortOrder=desc")
+        assert response.status_code == 200
+        assert response.json() == {"field": "uploaded_collections", "order": "desc"}
+
+        response = client.get("/users?orderBy=uploadedCollectionz&sortOrder=asc")
+        assert response.status_code == 422
+        error = response.json()["detail"][0]
+        assert error["loc"] == ["query", "orderBy"]
+        assert "Allowed fields: createdAt, uploadedCollections" in error["msg"]
+        assert "uploaded_collections" not in error["msg"]
+
+
 def test_fastapi_date_range_filter_dependency() -> None:
     """Test date range filter dependency with actual HTTP request."""
     sqlspec = SQLSpec()
@@ -371,6 +410,34 @@ def test_fastapi_openapi_schema_includes_filter_params() -> None:
     assert "pageSize" in param_names  # Pagination
 
 
+def test_fastapi_openapi_schema_uses_order_by_alias_default() -> None:
+    """Alias mode keeps orderBy string-shaped and exposes the alias default."""
+    sqlspec = SQLSpec()
+    config = AiosqliteConfig(
+        connection_config={"database": ":memory:"}, extension_config={"fastapi": {"commit_mode": "manual"}}
+    )
+    sqlspec.add_config(config)
+
+    app = FastAPI()
+    db_ext = SQLSpecPlugin(sqlspec, app=app)
+
+    @app.get("/users")
+    async def list_users(
+        filters: Annotated[
+            list[FilterTypes], Depends(db_ext.provide_filters({"sort_field": ["created_at", "uploaded_collections"]}))
+        ],
+    ) -> dict[str, Any]:
+        return {"filters": len(filters)}
+
+    openapi_schema = app.openapi()
+    user_endpoint = openapi_schema["paths"]["/users"]["get"]
+    order_by_param = next(param for param in user_endpoint.get("parameters", []) if param["name"] == "orderBy")
+    schema = order_by_param["schema"]
+
+    assert schema["default"] == "createdAt"
+    assert schema["type"] == "string"
+
+
 def test_fastapi_filter_validation_error() -> None:
     """Test that invalid filter values return proper validation errors."""
     sqlspec = SQLSpec()

{sqlspec-0.46.1 → sqlspec-0.46.2}/tests/integration/extensions/litestar/test_in_fields_filters.py

@@ -265,6 +265,103 @@ async def test_litestar_qualified_column_order_by_filter() -> None:
             assert items[1]["name"] == "a"
 
 
+@pytest.mark.anyio
+async def test_litestar_order_by_accepts_camelized_sort_field_alias() -> None:
+    """Camelized orderBy values normalize to SQL-facing fields before filtering."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        sql = SQLSpec()
+        config = AiosqliteConfig(connection_config={"database": tmp.name})
+        sql.add_config(config)
+
+        async with sql.provide_session(config) as session:
+            await session.execute_script("""
+                CREATE TABLE upload_stats (id INTEGER PRIMARY KEY, uploaded_collections INTEGER);
+                INSERT INTO upload_stats (id, uploaded_collections) VALUES (1, 2);
+                INSERT INTO upload_stats (id, uploaded_collections) VALUES (2, 3);
+                INSERT INTO upload_stats (id, uploaded_collections) VALUES (3, 1);
+            """)
+            await session.commit()
+
+        filter_deps = create_filter_dependencies({"sort_field": ["created_at", "uploaded_collections"]})
+
+        @get("/ordered", dependencies=filter_deps)
+        async def ordered_route(filters: list[Any] = Dependency(skip_validation=True)) -> dict[str, Any]:
+            async with sql.provide_session(config) as session:
+                query = sql_builder.select("id", "uploaded_collections").from_("upload_stats")
+                results = await session.select(query, *filters)
+                return {"items": results}
+
+        app = Litestar(route_handlers=[ordered_route], plugins=[SQLSpecPlugin(sqlspec=sql)])
+
+        async with AsyncTestClient(app=app) as client:
+            response = await client.get("/ordered", params={"orderBy": "uploadedCollections", "sortOrder": "asc"})
+            assert response.status_code == 200
+            items = response.json()["items"]
+            assert [item["id"] for item in items] == [3, 1, 2]
+
+
+@pytest.mark.anyio
+async def test_litestar_order_by_accepts_dotted_camelized_sort_field_alias() -> None:
+    """Qualified dotted orderBy fields accept dotted camel aliases."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        sql = SQLSpec()
+        config = AiosqliteConfig(connection_config={"database": tmp.name})
+        sql.add_config(config)
+
+        async with sql.provide_session(config) as session:
+            await session.execute_script("""
+                CREATE TABLE parent (id INTEGER PRIMARY KEY, name TEXT, created_at TEXT);
+                INSERT INTO parent (id, name, created_at) VALUES (1, 'middle', '2024-02-01');
+                INSERT INTO parent (id, name, created_at) VALUES (2, 'first', '2024-01-01');
+                INSERT INTO parent (id, name, created_at) VALUES (3, 'last', '2024-03-01');
+            """)
+            await session.commit()
+
+        filter_deps = create_filter_dependencies({"sort_field": ["p.created_at", "p.name"]})
+
+        @get("/ordered", dependencies=filter_deps)
+        async def ordered_route(filters: list[Any] = Dependency(skip_validation=True)) -> dict[str, Any]:
+            async with sql.provide_session(config) as session:
+                query = sql_builder.select("p.id", "p.name", "p.created_at").from_("parent p")
+                results = await session.select(query, *filters)
+                return {"items": results}
+
+        app = Litestar(route_handlers=[ordered_route], plugins=[SQLSpecPlugin(sqlspec=sql)])
+
+        async with AsyncTestClient(app=app) as client:
+            camel_response = await client.get("/ordered", params={"orderBy": "p.createdAt", "sortOrder": "asc"})
+            assert camel_response.status_code == 200
+            assert [item["id"] for item in camel_response.json()["items"]] == [2, 1, 3]
+
+            snake_response = await client.get("/ordered", params={"orderBy": "p.created_at", "sortOrder": "asc"})
+            assert snake_response.status_code == 200
+            assert [item["id"] for item in snake_response.json()["items"]] == [2, 1, 3]
+
+
+@pytest.mark.anyio
+async def test_litestar_order_by_invalid_alias_error_uses_display_aliases() -> None:
+    """Invalid alias errors list wire aliases instead of raw snake_case fields."""
+    sql = SQLSpec()
+    config = AiosqliteConfig(connection_config={"database": ":memory:"})
+    sql.add_config(config)
+
+    filter_deps = create_filter_dependencies({"sort_field": ["created_at", "uploaded_collections"]})
+
+    @get("/ordered", dependencies=filter_deps)
+    async def ordered_route(filters: list[Any] = Dependency(skip_validation=True)) -> dict[str, Any]:
+        return {"items": []}
+
+    app = Litestar(route_handlers=[ordered_route], plugins=[SQLSpecPlugin(sqlspec=sql)])
+
+    async with AsyncTestClient(app=app) as client:
+        response = await client.get("/ordered", params={"orderBy": "uploadedCollectionz", "sortOrder": "asc"})
+
+    assert response.status_code == 400
+    assert "Invalid orderBy field 'uploadedCollectionz'" in response.text
+    assert "Allowed fields: createdAt, uploadedCollections" in response.text
+    assert "uploaded_collections" not in response.text
+
+
 def test_litestar_order_by_openapi_schema() -> None:
     """OrderByFilter must appear as a string in OpenAPI even with expression support."""
     from typing import Any
@@ -316,6 +413,52 @@ def test_litestar_order_by_openapi_schema() -> None:
     assert is_string_type(sort_order_param.schema)
 
 
+def test_litestar_order_by_openapi_schema_uses_alias_default() -> None:
+    """Alias mode keeps orderBy as a string and exposes the alias-shaped default."""
+    from typing import Any
+
+    sql = SQLSpec()
+    config = AiosqliteConfig(connection_config={"database": ":memory:"})
+    sql.add_config(config)
+
+    filter_deps = create_filter_dependencies({"sort_field": ["created_at", "uploaded_collections"]})
+
+    @get("/ordered", dependencies=filter_deps)
+    async def ordered_route(filters: list[Any] = Dependency(skip_validation=True)) -> dict[str, Any]:
+        return {"items": []}
+
+    app = Litestar(route_handlers=[ordered_route], plugins=[SQLSpecPlugin(sqlspec=sql)])
+
+    schema = app.openapi_schema
+    paths = schema.paths
+    assert paths is not None
+
+    operation = paths["/ordered"].get
+    assert operation is not None
+    params = operation.parameters
+    assert params is not None
+
+    order_by_param = next((p for p in params if getattr(p, "name", None) == "orderBy"), None)
+    assert order_by_param is not None
+    order_by_schema = getattr(order_by_param, "schema", None)
+    assert order_by_schema is not None
+    assert getattr(order_by_schema, "default", None) == "createdAt"
+
+    def is_string_type(schema: Any) -> bool:
+        if not schema:
+            return False
+        stype = schema.type
+        if isinstance(stype, list):
+            return any("string" in str(t).lower() for t in stype)
+        if stype:
+            return "string" in str(stype).lower()
+        if schema.one_of:
+            return any(is_string_type(s) for s in schema.one_of)
+        return False
+
+    assert is_string_type(order_by_schema)
+
+
 # Regression tests for issue #435 (cross-binding across providers in the same family).