Use simple parsing
An application needs standard Node-compatible query-string parsing.
Express.js · Const
query parser
The query parser application setting determines how Express parses URL query strings into req.query. It can disable parsing, select simple or extended mode, or use a custom parser.
How it works
The application setting controls how Express converts a request URL’s query string into the object exposed as req.query. It accepts false, the simple or extended parser names, or a custom function that receives the complete query string and returns an object containing query keys and values.
Syntax
app.set('query parser', value)Parameters
| Name | Type | Description |
|---|---|---|
value | Boolean | String | Function | Application setting value: false, "simple", "extended", or a function accepting the complete query string and returning an object. |
Returns
The configured parser determines the object available as req.query; a custom parser returns an object of query keys and values.
Key points
- The setting accepts a Boolean, String, or Function, and its Express 4 default is "extended".
- Assign false to turn off query-string parsing.
- The string modes select Express’s simple or extended parsing behavior.
- Simple mode delegates its parsing model to Node’s native querystring parser.
- Extended mode uses the qs library’s parsing model.
- A custom parser’s result must be an object mapping query keys to their values.
Common mistakes
- Disabling the parser leaves req.query as an empty object rather than parsing URL parameters.
- A custom parser must handle the complete raw query string itself, including any decoding and structure it needs.
Example: Configure a custom query parser
const express = require('express');
const app = express();
app.set('query parser', (value) => {
const result = Object.create(null);
for (const part of value.split('&')) {
const [key, raw = ''] = part.split('=');
result[decodeURIComponent(key)] = decodeURIComponent(raw.replace(/\+/g, ' '));
}
return result;
});
app.get('/search', (req, res) => {
res.json(req.query);
});
app.listen(3000);Configures a custom parser and returns parsed query parameters from /search.
When to use it
Use extended parsing
An application needs nested objects or arrays represented by query parameters.
Provide a custom parser
An application must apply custom decoding, validation, or parser options.
Disable parsing
An application does not use URL query parameters.
Interview questions
QWhat does the query parser application setting control?
The setting chooses how Express parses URL query strings before exposing them through req.query. It accepts false, simple, extended, or a custom function.
Follow-up: What happens when it is false? req.query is an empty object, so application code cannot obtain parsed query parameters from it.
QHow do the simple and extended parsers differ?
The simple parser uses Node’s native querystring parser, while the extended parser uses qs. In Express 4, the documented default is extended.
Follow-up: When would a custom function be useful? When the application needs parsing behavior or options that the built-in choices do not provide.
QHow do you implement a custom query parser?
Set the application value to a function. Express passes that function the complete query string, and the function must return an object mapping query keys to their values.
Follow-up: What contract must the function satisfy? It must return an object; otherwise req.query cannot represent the parsed query parameters as documented.
Related
req.queryapp.set()querystringqs