📝 Clarify that HTTP query params cannot be Python None
Add a note to the "Required, can be None" section explaining that
HTTP query parameters are always strings over the network, and clients
cannot explicitly send a Python `None`. The `None` type annotation
reflects Python-level typing, not what clients can actually transmit.
Closes#12419
@ -222,12 +222,18 @@ So, when you need to declare a value as required while using `Query`, you can si
### Required, can be `None` { #required-can-be-none }
### Required, can be `None` { #required-can-be-none }
You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send a value, even if the value is `None`.
You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send the parameter, but the value can be `None` in your Python code if the client sends no value for it.
To do that, you can declare that `None` is a valid type but simply do not declare a default value:
To do that, you can declare that `None` is a valid type but simply do not declare a default value:
HTTP query parameters are always strings when sent by clients over the network. There is no way for a client to explicitly send a Python `None` as a query parameter — the parameter is either present as a string or absent entirely. The `None` in the type annotation tells FastAPI (and Python) that the value is allowed to be `None` at the Python level, but if the parameter is required (no default value), FastAPI will return a validation error when the client omits it.
///
## Query parameter list / multiple values { #query-parameter-list-multiple-values }
## Query parameter list / multiple values { #query-parameter-list-multiple-values }
When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.
When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.