Skip to content

Query Parameters

This section explains how to extract and validate query parameters using Rapidy.

Remember, you can validate data using any type supported by pydantic.

Description

Query parameters are key-value pairs that appear after the ? in a URL, separated by &.

Example of a URL with a query string containing three parameters.

https://www.rapidy.com/search?query=database+tools&star_rating=4&order=alphabetical

Extracting a Single QueryParam

QueryParam extracts a single query parameter by its name.

from rapidy.http import get, QueryParam

@get('/')
async def handler(
    query: str = QueryParam(),
) -> ...:

from rapidy.http import get, QueryParam

@get('/')
async def handler(
    query: str = QueryParam(),
    star_rating: str = QueryParam(),
) -> ...:

Extracting All QueryParams

QueryParams extracts all query parameters at once.

You can validate the data using any type supported by pydantic.

Extracting into a Predefined Schema

pydantic.BaseModel

from pydantic import BaseModel
from rapidy.http import get, QueryParams

class QueryParamsData(BaseModel):
    query: str
    star_rating: str

@get('/')
async def handler(
    query_params_data: QueryParamsData = QueryParams(),
) -> ...:

dataclasses.dataclass

dataclasses.dataclass is supported as a model type, but you cannot set an alias using standard dataclasses tools.

from dataclasses import dataclass
from rapidy.http import get, QueryParams

@dataclass
class QueryParamsData:
    query: str
    star_rating: str

@get('/')
async def handler(
    query_params_data: QueryParamsData = QueryParams(),
) -> ...:

Extracting into a Dictionary

from rapidy.http import get, QueryParams

@get('/')
async def handler(
    query_params_data: dict[str, str] = QueryParams(),
) -> ...:
# {'query': ..., 'star_rating': ...}

Extraction Without Validation

Disabling validation is not recommended.

If validation is disabled, parameters will be returned in the base aiohttp structure:

  • QueryParam → str
  • QueryParams → MultiDictProxy[str]

Ways to Disable Validation

Explicit Disabling

from rapidy.http import get, QueryParam, QueryParams

@get('/')
async def handler_1(
    query: int = QueryParam(validate=False)
) -> ...:
    # ...

@get('/')
async def handler_2(
    query_params_data: int = QueryParams(validate=False)
) -> ...:
    # <MultiDictProxy('query': ..., 'star_rating', ...)>

Using Any

from typing import Any

@get('/')
async def handler_1(
    query: Any = QueryParam(),
) -> ...:
    # ...

@get('/')
async def handler_2(
    query_params_data: Any = QueryParams(),
) -> ...:
    # <MultiDictProxy('query': ..., 'star_rating', ...)>

No Type Annotation

If the type is not specified, it defaults to Any. 

@get('/')
async def handler_1(
    query=QueryParam(),
) -> ...:
    # ...

@get('/')
async def handler_2(
    query_params_data=QueryParams(),
) -> ...:
    # <MultiDictProxy('query': ..., 'star_rating', ...)>

Default Values

The default value for QueryParam is used if the incoming request does not contain the specified query parameter.

The default value for QueryParams is used if the request does not contain any query parameters.

Using default

@get('/')
async def handler(
    some_query_param: str = QueryParam(default='SomeValue'),
) -> None:

from typing import Annotated

@get('/')
async def handler(
    some_query_param: Annotated[str, QueryParam(default='SomeValue')],
) -> None:

from typing import Annotated

@get('/')
async def handler(
    some_query_param: Annotated[str, QueryParam()] = 'SomeValue',
) -> None:

Using default_factory

@get('/')
async def handler(
    some_query_param: str = QueryParam(default_factory=lambda: 'SomeValue'),
) -> None:

from typing import Annotated

@get('/')
async def handler(
    some_query_param: Annotated[str, QueryParam(default_factory=lambda:'SomeValue')],
) -> None:

You cannot use both default and default_factory at the same time.

Attempting to set both will raise a pydantic exception: 

TypeError('cannot specify both default and default_factory')

Warnings and Specifics

Using QueryParam and QueryParams Together

You cannot use QueryParam and QueryParams together in the same handler.

@get('/')
async def handler(
    query: str = QueryParam(),
    query_params_data: QueryParamsData = QueryParams(),
) -> ...:

When the application starts, an AnotherDataExtractionTypeAlreadyExistsError exception will be raised.

------------------------------
Attribute with this data extraction type cannot be added to the handler - another data extraction type is already used in the handler.

Handler path: `main.py`
Handler name: `handler`
Attribute name: `headers_data`
------------------------------

The alias Attribute in Headers

The alias attribute does not work in QueryParams().

@get('/')
async def handler(
    query_params_data: QueryParamsData = QueryParams(alias='SomeName'),  # <-- alias not working
) -> ...:

How Raw Data is Extracted

Rapidy uses the rel_url.query method of the Request object and then passes the retrieved data to a pydantic model for validation.

How Extraction Works Inside Rapidy

async def extract_query(request: Request) -> MultiDictProxy[str]:
    return request.rel_url.query

Rapidy uses built-in aiohttp mechanisms.

For more details on the aiohttp.Request object and data extraction methods, see here.