Skip to content

useMongocampFilterBuilder ​

Pure logic behind the visual filter builder: turns "field · operator · value" rows into one Lucene query string for the filter parameter of the document and file APIs. It has no UI and no Nuxt dependency — build the rows however you like and pass them in. (The builder component that edits these rows is a separate step.)

ts
const { buildFilterQuery } = useMongocampFilterBuilder()

const query = buildFilterQuery(
  {
    match: 'all', // 'all' = AND, 'any' = OR
    negate: false, // optional: true = exclude what the conditions match (NOT)
    conditions: [
      { id: '1', field: 'name', operator: 'contains', value: 'ali' },
      { id: '2', field: 'age', operator: 'between', value: '18', value2: '65' },
    ],
  },
  { name: 'string', age: 'number' }, // field → type; unknown fields count as 'string'
)
// => '(name:*ali* AND age:[18 TO 65])'

Operators per field type ​

TypeOperators
stringcontains, equals, notEquals, startsWith, endsWith, oneOf (comma list), isEmpty, isNotEmpty
numberequals, notEquals, gte, lte, between, oneOf, isEmpty, isNotEmpty
date-timegte, lte, between, isEmpty, isNotEmpty
booleanisTrue, isFalse
objectId (the document _id)equals, notEquals, oneOf — each value must be a 24-character hex id, otherwise the row is skipped
array, objectnone — operatorsFor returns [], so leave these fields out of the builder

gte/lte/between are inclusive. isEmpty / isNotEmpty ("does not exist" / "exists") use useMongocampQuery's typed exists / notExists; booleans, arrays and objects have none.

Functions ​

FunctionDescription
operatorsFor(type)Operators valid for a type (string operators for an unknown type)
valueCountFor(operator)How many value inputs the operator needs: 0, 1, or 2 (between)
buildCondition(condition, type)Lucene for one row, or '' if the row is incomplete or invalid
buildFilterQuery(group, fieldTypes)All valid rows joined with AND/OR; '' means "no filter"
countActiveConditions(group, fieldTypes)How many rows contribute to the query (for a "Filters (n)" badge)

Behaviour worth knowing ​

  • negate: true excludes what the combined conditions match. It is written with De Morgan (((-a) OR (-b)), see useMongocampQuery) because the server evaluates -(a AND b) wrongly. A negated group with no valid row is "no filter", not "match nothing".
  • Incomplete or invalid rows are skipped, never turned into "match everything": empty values, non-numeric numbers, non-ISO dates, an operator that doesn't fit the field type. A oneOf list with a single bad number is rejected as a whole.
  • Safe against query injection: values and field names are escaped by the query helpers (a field called first name works); range bounds are additionally accepted here only as plain numbers or ISO dates.
  • contains keeps * and ? as wildcards, so a*b matches "a…b". A leading wildcard (contains, endsWith) cannot use an index and is slow on large collections.
  • Numbers keep the digits as typed and are written unquoted (age:30); only plain decimals are accepted (no 1e3). Ids and account numbers beyond 2^53 therefore aren't rounded. Strings are written quoted (name:"ali").
  • Dates: a bare date means the whole day in UTC — gte 2024-01-01 is [2024-01-01T00:00:00Z …, lte 2024-01-01 ends at 2024-01-01T23:59:59.999Z. A full timestamp is used as given.
  • No open-ended ranges. gte / lte close the range with a far-away bound (the 64-bit integer limits for numbers, year 0001 / 9999 for dates) instead of *. The date and range handling lives in useMongocampQuery().inRange; this composable only validates what was typed.

Checked against a real server ​

These behaviours were verified against a MongoCamp server (1.5.x, re-checked on 1.6.1 and again on 1.6.3, 2026-11-03) and are why the operator tables look the way they do — see also useMongocampQuery:

WorksDoes not work
name:*x*, name:"x", name:x*, name:*x, name:("a" OR "b")n:[a TO *] / [* TO b] (open end) — the request fails; _id:*, _id:abc*, _id:*abc (wildcards on _id) — silently match nothing
n:12345 (unquoted number, exact digits), n:[a TO b] (closed range)n:>=x, n:>x — silently match nothing
d:[2018-01-01T00:00:00Z TO 2018-12-31T23:59:59.999Z]d:[2018-09-22 TO 2018-09-22] (a bare date as upper bound ends at midnight, so a one-day range matches nothing)
name:* / -name:* on a text field; a closed full-range for numbers and dates (as "exists")_exists_:field — matches nothing; -_exists_:field matches everything
(a OR b OR c) of the above; each clause negated and ANDed; since 1.6.1 also _id:"<oid>", _id:("a" OR "b"), -_id:"<oid>" (case-insensitive) and -(x) / NOT (x) around a single clause-( a AND b ) and NOT ( a AND b ) are evaluated like -a AND -b (written as ((-a) OR (-b)) instead, which works; MongoCamp/mongocamp-server#69); field:* on a number or date — matches nothing

Boolean terms (active:true, active:false, -active:true), oneOf on numbers (n:(1 OR 2 OR 3)), array elements (arr:x), array existence (arr:*) and nested paths (obj.k:v) were checked against server 1.6.3 (2026-11-03) and return the right counts.

See also useMongocampQuery.

Released under the MIT License.