Query operators

Reference for the public filter operators supported by the unified query grammar and filesystem provider.

Use these operators inside the where option accepted by many(), paginate(), and navigation(). Import the QueryWhere type from @lupinum/ginko-content/client or @lupinum/ginko-content/server.

Provider-backed queries may use only comparison operators advertised by that provider. $and, $or, and $not are mandatory structural nodes in the provider wire rather than optional capabilities.

Operators

Operator	Purpose	Example
`$eq`	Equal	`{ status: { $eq: 'published' } }`
`$ne`	Not equal	`{ draft: { $ne: true } }`
`$gt`	Greater than	`{ order: { $gt: 10 } }`
`$gte`	Greater than or equal	`{ order: { $gte: 10 } }`
`$lt`	Less than	`{ order: { $lt: 20 } }`
`$lte`	Less than or equal	`{ order: { $lte: 20 } }`
`$in`	Value belongs to a set	`{ status: { $in: ['draft', 'review'] } }`
`$nin`	Value does not belong to a set	`{ status: { $nin: ['archived'] } }`
`$contains`	String or array contains a value	`{ tags: { $contains: 'nuxt' } }`
`$containsAny`	Array contains at least one value	`{ tags: { $containsAny: ['nuxt', 'vue'] } }`
`$icontains`	Case-insensitive string containment	`{ title: { $icontains: 'ginko' } }`
`$exists`	Field presence matches a boolean	`{ image: { $exists: true } }`
`$type`	Runtime value has the requested type	`{ order: { $type: 'number' } }`
`$prefix`	String begins with a prefix	`{ path: { $prefix: '/blog/2026' } }`

$type accepts string, number, boolean, object, or undefined.

Logical groups

const result = await many(posts, {
  where: {
    $and: [
      { draft: { $ne: true } },
      {
        $or: [
          { tags: { $contains: 'nuxt' } },
          { title: { $icontains: 'content' } }
        ]
      }
    ]
  }
})

Negation is a logical group rather than a field operator:

await many(posts, {
  where: {
    $not: { tags: { $contains: 'internal' } }
  }
})

Direct equality

A field may use a direct value when no operator is needed:

await many(posts, {
  where: { featured: true }
})

This is equivalent to $eq for that value.

Provider capabilities

The filesystem provider supports the public operator set documented here plus provider-internal regex matching. External providers advertise a subset in capabilities.query.operators and must prove each advertised operator through the provider contract suite. Every v4 provider also interprets structural and, or, and not plan nodes. Provider capabilities do not expand the public TypeScript or HTTP grammar.

Requesting an unsupported operator is an error. Ginko does not fetch all records and emulate provider behavior silently.

Non-public operators

Internal query transport names and legacy fluent-builder operators are not part of the unified public grammar. Public queries reject caller-provided $regex and $options; string SQL-style operators are also not public where syntax.

The query API documents which operations accept where. Provider authors must keep advertised capabilities synchronized with the provider contract suite.