projections for faster queries, text index for faster searching

Author: peterrauscher

README.md

@@ -31,7 +31,7 @@ By default, all products in the database are returned when calling `/sneakers`.
 - releaseDate
 - released
 
-Filtering is case insensitive, but the search will start from the beginning of each field. For example, a search `/sneakers?brand=jordan` will return all sneakers with a brand starting with `Jordan`, `jordan`, `JOrdan`, etc... but a search `/sneakers?brand=ordan` will not find any `Jordan`s.
+Filtering is case insensitive, but the search will always start at the beginning of each field. For example, a search `/sneakers?brand=jordan` will return all sneakers with a brand starting with `Jordan`, `jordan`, `JORdan`, etc... but a search `/sneakers?brand=ordan` will not find any `Jordan` brand sneakers. For this reason, those needing more comprehensive "search" functionality should use the `/search` endpoint.
 
 ### Sorting
 

src/api/data/models.py

@@ -1,10 +1,10 @@
 from enum import Enum
 from typing import List
 
+from beanie import Document
 from pydantic import BaseModel
 
-from beanie import Document
-from core.models.shoes import Sneaker
+from core.models.shoes import Sneaker, SneakerView
 
 
 class Token(Document):
@@ -21,7 +21,7 @@ class PaginatedSneakersResponse(BaseModel):
     pageSize: int
     nextPage: str | None
     previousPage: str | None
-    items: List[Sneaker]
+    items: List[SneakerView]
 
 
 class SortKey(str, Enum):

src/api/main.py

@@ -10,14 +10,14 @@
     load_dotenv(os.path.join(os.getcwd(), ".env"))
 
 from beanie import init_beanie
-from core.models.shoes import Sneaker
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from mangum import Mangum
 from starlette.middleware.sessions import SessionMiddleware
 
 from api.data.instance import DATABASE_NAME, client
 from api.routes import auth, sneakers
+from core.models.shoes import Sneaker
 
 desc = """
 ### The Bloomberg Terminal of Sneakers
@@ -30,7 +30,7 @@
     redoc_url=None,  # Disable redoc, keep only swagger
     title="SoleSearch",
     version=__version__,
-    contact={"name": "SoleSearch Developer Support", "email": "support@solesearch.io"},
+    contact={"name": "SoleSearch Emails Support", "email": "support@solesearch.io"},
     description=desc,
     responses={404: {"description": "Not found"}},  # Custom 404 page
 )

src/api/routes/search.py

@@ -1,14 +1,13 @@
 import os
 from datetime import UTC, datetime
-import os
 from typing import Annotated
 
-from core.models.details import Audience
-from core.models.shoes import Sneaker
 from fastapi import APIRouter, HTTPException, Query, Request
 
 from api.data.models import PaginatedSneakersResponse, SortKey, SortOrder
 from api.util import url_for_query
+from core.models.details import Audience
+from core.models.shoes import Sneaker, SneakerView
 
 router = APIRouter(
     prefix="/sneakers",
@@ -21,16 +20,79 @@
 @router.get("/")
 async def get_sneakers(
     request: Request,
-    brand: str | None = None,
-    name: str | None = None,
-    colorway: str | None = None,
-    audience: Audience | None = None,
-    releaseDate: str | None = None,
-    released: bool | None = None,
-    sort: SortKey = SortKey.RELEASE_DATE,
-    order: SortOrder = SortOrder.DESCENDING,
-    page: Annotated[int | None, Query(gte=1)] = None,
-    pageSize: Annotated[int | None, Query(gte=1, lte=MAX_LIMIT)] = None,
+    brand: Annotated[
+        str | None,
+        Query(
+            title="Brand", description="Filter by the brand of the shoes.", min_length=3
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        Query(
+            title="Product Name",
+            description="Filter by the name of the shoes.",
+            min_length=3,
+        ),
+    ] = None,
+    colorway: Annotated[
+        str | None,
+        Query(
+            title="Colorway",
+            description="Filter by the colorway of the shoes.",
+            min_length=3,
+        ),
+    ] = None,
+    audience: Annotated[
+        Audience | None,
+        Query(
+            title="Audience",
+            description="Filter on the gender/audience of the shoes. See Audience for possible values.",
+            min_length=3,
+        ),
+    ] = None,
+    releaseDate: Annotated[
+        str | None,
+        Query(
+            title="Release Date",
+            description="Filter by the release date of the shoes. Can be a specific date or an inequality. Operators are (lt, lte, gt, gte). Example usage: lt:2021-01-01",
+        ),
+    ] = None,
+    released: Annotated[
+        bool | None,
+        Query(
+            title="Released?",
+            description="Filter by whether the shoes have been released or not. Overrides any filter on releaseDate if set.",
+        ),
+    ] = None,
+    sort: Annotated[
+        SortKey,
+        Query(
+            title="Sort By",
+            description="The field to sort by.",
+        ),
+    ] = SortKey.RELEASE_DATE,
+    order: Annotated[
+        SortOrder,
+        Query(
+            title="Sort Order",
+            description="The order to sort in based on the sort key.",
+        ),
+    ] = SortOrder.DESCENDING,
+    page: Annotated[
+        int | None,
+        Query(
+            gte=1, title="Page Number", description="The page number of the result set."
+        ),
+    ] = None,
+    pageSize: Annotated[
+        int | None,
+        Query(
+            gte=1,
+            lte=MAX_LIMIT,
+            title="Page Size",
+            description=f"The number of items on each page. Must be in the range [1-{MAX_LIMIT}] (inclusive).",
+        ),
+    ] = None,
 ) -> PaginatedSneakersResponse:
     query = Sneaker.find()
     if not page:
@@ -44,7 +106,9 @@ async def get_sneakers(
     if colorway:
         query = query.find({"colorway": {"$regex": f"^{colorway}", "$options": "i"}})
     if audience:
-        query = query.find({"audience": {"$regex": f"^{audience.value}"}})
+        query = query.find(
+            {"audience": {"$regex": f"^{audience.value}", "$options": "i"}}
+        )
     if released is not None:
         now = datetime.now(UTC)
         if released:
@@ -82,6 +146,7 @@ async def get_sneakers(
         await query.sort(f"{'+' if order == SortOrder.ASCENDING else '-'}{sort.value}")
         .skip((page - 1) * pageSize)
         .limit(pageSize)
+        .project(SneakerView)
         .to_list()
     )
     result = PaginatedSneakersResponse(

src/api/routes/sneakers.py

@@ -3,8 +3,8 @@
 from fastapi import Request
 
 
-def url_for_query(request: Request, name: str, **params: str) -> str:
-    url = str(request.url_for(name))
+def url_for_query(request: Request, fastapi_function_name: str, **params: str) -> str:
+    url = str(request.url_for(fastapi_function_name))
     parsed = urlparse(url)
     parsed = parsed._replace(query=urlencode(params))
     return urlunparse(parsed)