How to Filter JSON Server Results Using Query Operators Like gt, lt, and eq

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 and the parsing logic in 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 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 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.

// 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 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

# 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

# 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

# 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

# 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:

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.
• Use the colon syntax (field:operator=value) to apply filters; omitting the operator defaults to eq.
• The parseWhere function in 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 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.

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, 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 using native JavaScript string methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}