# How to Filter JSON Server Results Using Query Operators Like gt, lt, and eq > Easily filter JSON Server results with query operators like gt, lt, and eq. Learn the simple colon syntax field:operator=value for powerful data manipulation. Get better API control today. - Repository: [typicode/json-server](https://github.com/typicode/json-server) - Tags: how-to-guide - Published: 2026-03-01 --- **Use the colon syntax (`field:operator=value`) in your HTTP request to filter JSON Server results using query operators such as `gt`, `lt`, `eq`, `contains`, and `in`.** JSON Server provides a powerful query language that allows you to filter JSON data without writing custom backend code. By leveraging the operator definitions in [`src/where-operators.ts`](https://github.com/typicode/json-server/blob/main/src/where-operators.ts) and the parsing logic in [`src/parse-where.ts`](https://github.com/typicode/json-server/blob/main/src/parse-where.ts), you can construct precise filters using comparison, equality, and string-matching operators. ## Supported Query Operators in JSON Server The complete list of supported operators is defined in [`src/where-operators.ts`](https://github.com/typicode/json-server/blob/main/src/where-operators.ts) as a TypeScript union type: `lt | lte | gt | gte | eq | ne | in | contains | startsWith | endsWith`. ### Numeric and Equality Operators These operators handle mathematical comparisons and exact matching: - **`eq`** – Equal to (default when no operator is specified) - **`ne`** – Not equal to - **`gt`** – Greater than - **`gte`** – Greater than or equal to - **`lt`** – Less than - **`lte`** – Less than or equal to ### String Matching Operators These operators perform partial string comparisons: - **`contains`** – Substring match (case-sensitive) - **`startsWith`** – Prefix match - **`endsWith`** – Suffix match ### List Membership Operators - **`in`** – Checks if value exists within a comma-separated list (e.g., `id:in=1,2,3`) ## How JSON Server Parses Filter Queries When a request arrives at JSON Server, the `parseWhere` function in [`src/parse-where.ts`](https://github.com/typicode/json-server/blob/main/src/parse-where.ts) transforms URL query parameters into a structured filter object. ### Field and Operator Extraction The `splitKey` function (lines 6-29) handles the syntax `field:operator` or the legacy `field_operator` format. It separates the field name from the operator, defaulting to `eq` if only the field name is provided. ```javascript // Internal parsing logic (simplified) // "views:gt=100" becomes { field: "views", operator: "gt", value: "100" } // "id=5" becomes { field: "id", operator: "eq", value: "5" } ``` ### Type Coercion The `coerceValue` function (lines 45-55) automatically converts string values from the URL into appropriate JavaScript types: - Numeric strings become numbers - `"true"`/`"false"` become booleans - `"null"` becomes `null` - Comma-separated strings become arrays when used with the `in` operator The `setPathOp` helper (lines 31-44) constructs the nested filter object structure, resulting in objects like `{ "views": { "gt": 100 } }`. ## How JSON Server Evaluates Filter Conditions After parsing, the `matchesWhere` function in [`src/matches-where.ts`](https://github.com/typicode/json-server/blob/main/src/matches-where.ts) evaluates each resource against the filter object. ### Comparison Logic The core comparison block (lines 46-71) implements the operator semantics: - For numeric operators (`gt`, `lt`, etc.), it performs mathematical comparisons - For string operators (`contains`, `startsWith`, `endsWith`), it uses native JavaScript string methods - For `eq` and `ne`, it handles deep equality checks ### Logical Composition The function handles nested objects recursively, allowing filters on nested properties (e.g., `author.name:eq=John`). It also supports logical `or` operations through special array syntax in the `_where` parameter. ## Practical Examples of Filtering JSON Server Results ### Basic Numeric Comparisons ```bash # Greater than curl "http://localhost:3000/posts?views:gt=100" # Less than or equal to curl "http://localhost:3000/posts?views:lte=50" # Range query (combine operators) curl "http://localhost:3000/posts?views:gt=100&views:lt=500" ``` ### Equality and Inequality ```bash # Explicit equality curl "http://localhost:3000/posts?id:eq=2" # Implicit equality (shorthand) curl "http://localhost:3000/posts?id=2" # Not equal curl "http://localhost:3000/posts?status:ne=archived" ``` ### String Matching ```bash # Contains substring curl "http://localhost:3000/posts?title:contains=hello" # Starts with prefix curl "http://localhost:3000/posts?title:startsWith=Intro" # Ends with suffix curl "http://localhost:3000/posts?title:endsWith=Guide" ``` ### List Membership ```bash # Match any ID in list curl "http://localhost:3000/posts?id:in=1,3,5,7" ``` ### Complex Logical Filters For advanced queries combining OR logic or nested property filtering, use the `_where` parameter with JSON: ```bash curl "http://localhost:3000/posts?_where={\"or\":[{\"views\":{\"gt\":100}},{\"author\":{\"name\":{\"lt\":\"m\"}}}]}" ``` ## Summary - JSON Server supports eight query operators—`gt`, `gte`, `lt`, `lte`, `eq`, `ne`, `in`, `contains`, `startsWith`, and `endsWith`—defined in [`src/where-operators.ts`](https://github.com/typicode/json-server/blob/main/src/where-operators.ts). - Use the colon syntax (`field:operator=value`) to apply filters; omitting the operator defaults to `eq`. - The `parseWhere` function in [`src/parse-where.ts`](https://github.com/typicode/json-server/blob/main/src/parse-where.ts) handles query string parsing, field extraction via `splitKey`, and automatic type coercion via `coerceValue`. - The `matchesWhere` function in [`src/matches-where.ts`](https://github.com/typicode/json-server/blob/main/src/matches-where.ts) executes the filter logic, performing comparisons in the block at lines 46-71 and supporting nested objects and logical `or` via the `_where` parameter. ## Frequently Asked Questions ### How do I filter for values greater than or less than a number in JSON Server? Append the operator to the field name using colon syntax. For greater than, use `field:gt=value`. For less than, use `field:lt=value`. For example, `GET /posts?views:gt=100` returns posts where the views field is greater than 100, processed by the `matchesWhere` function in [`src/matches-where.ts`](https://github.com/typicode/json-server/blob/main/src/matches-where.ts). ### What is the difference between the eq and ne operators in JSON Server? The `eq` operator checks for equality (and is the default when no operator is specified), while `ne` checks for inequality. According to the operator definitions in [`src/where-operators.ts`](https://github.com/typicode/json-server/blob/main/src/where-operators.ts), `eq` performs a deep equality comparison, whereas `ne` returns resources where the field value does not match the query value. ### Can I use multiple query operators in a single JSON Server request? Yes, you can combine multiple operators by including multiple query parameters. JSON Server treats these as logical AND conditions. For example, `GET /posts?views:gt=100&views:lt=500&published:eq=true` filters for posts with views between 100 and 500 that are also published. For logical OR conditions, use the `_where` parameter with a JSON payload containing an `or` array. ### How do I filter for partial string matches in JSON Server? Use the string-specific operators `contains`, `startsWith`, or `endsWith`. For example, `GET /posts?title:contains=hello` returns posts where the title includes the substring "hello". These operators are implemented in the comparison block of [`src/matches-where.ts`](https://github.com/typicode/json-server/blob/main/src/matches-where.ts) using native JavaScript string methods.