Filter Operators

Filters are JSON objects passed to search endpoints. They compose with and, or, and not to form arbitrarily complex queries.

ThogitFilter Operators

Top-level operators for filtering thogits.

Operator	Format	Description
search	{"search": "text"}	Full-text search on name + description (case-insensitive)
name	{"name": <TextFilter>}	Filter on thogit name
description	{"description": <TextFilter>}	Filter on description
has_tag	{"has_tag": "TagName"} or {"has_tag": "ULID"}	Tag presence check (by name or ID)
field predicate	{"TagName.field": <FieldFilter>}	Field value check using dot notation
reference traversal	{"Tag.ref->Target.field": <op>}	Follow a reference field, filter the target’s field
and	{"and": [f1, f2, ...]}	All conditions must match
or	{"or": [f1, f2, ...]}	Any condition can match
not	{"not": <filter>}	Negation

Examples

Full-text search

{ "search": "schema validation" }

Matches thogits whose name or description contains “schema validation”.

Tag presence

{ "has_tag": "Project Tracker" }

Matches thogits that have the “Project Tracker” tag applied.

Field predicate

{ "Project Tracker.story_points": { "gte": 5 } }

Matches thogits where the story_points field on the “Project Tracker” tag is >= 5.

Reference traversal

{ "Task.parent->Project.status": { "eq": "Active" } }

Follows the parent reference field on the “Task” tag to the target thogit, then checks the status field on the “Project” tag of that target.

Compound filter

{
  "and": [
    { "has_tag": "Project Tracker" },
    { "Project Tracker.story_points": { "gte": 3 } },
    { "or": [
      { "Project Tracker.status": { "eq": "Active" } },
      { "Project Tracker.status": { "eq": "Backlog" } }
    ]}
  ]
}

---

TextFilter Operators

Used with name and description fields on both ThogitFilter and TagFilter.

Operator	Format	Description
eq	{"eq": "text"}	Exact string match
neq	{"neq": "text"}	Not equal to
gt	{"gt": "text"}	Lexicographically greater than
gte	{"gte": "text"}	Lexicographically greater than or equal
lt	{"lt": "text"}	Lexicographically less than
lte	{"lte": "text"}	Lexicographically less than or equal
regex	{"regex": "^pattern$"}	ECMAScript regular expression match

Examples

// Thogits whose name equals exactly "Sprint 12"
{ "name": { "eq": "Sprint 12" } }

// Thogits whose name matches a regex
{ "name": { "regex": "^2024-" } }

// Thogits whose description matches a regex
{ "description": { "regex": "^\\[DRAFT\\]" } }

---

FieldFilter Operators

Used in field predicates ("TagName.field": <FieldFilter>). The available operators depend on the field’s schema type.

Bare Value Shorthand

A bare value (not wrapped in an operator object) is shorthand for eq:

Value	Equivalent	Applicable types
"text"	{"eq": "text"}	String, Select
42	{"eq": 42}	Number
true	{"eq": true}	Boolean
null	{"exists": false}	All types

// These are equivalent:
{ "Project.priority": 3 }
{ "Project.priority": { "eq": 3 } }

Comparison Operators

Operator	Format	Description
eq	{"eq": value}	Equal to
neq	{"neq": value}	Not equal to
gt	{"gt": value}	Greater than
gte	{"gte": value}	Greater than or equal
lt	{"lt": value}	Less than
lte	{"lte": value}	Less than or equal

Works with: String (lexicographic), Number, Date, Select/MultiSelect (ordinal by variant position)

// Numbers
{ "Project.story_points": { "gt": 5 } }

// Dates
{ "Project.due_date": { "lt": "2024-12-31" } }

// Date range (combine with and)
{ "and": [
  { "Project.due_date": { "gte": "2024-01-01" } },
  { "Project.due_date": { "lte": "2024-12-31" } }
]}

// Select ordinal comparison (by position in variants array)
{ "Project.status": { "gte": "InProgress" } }

Note

For Select and MultiSelect fields, eq and neq compare by variant name. The ordinal operators gt, gte, lt, lte compare by the variant’s position in the schema’s variants array. If a Select has variants ["Backlog", "Active", "Done"], then Backlog (0) < Active (1) < Done (2). For MultiSelect, a match succeeds if any selected variant satisfies the condition.

Regex

Operator	Format	Description
regex	{"regex": "pattern"}	ECMAScript regular expression match

Works with: String, Select (matches variant name), MultiSelect (matches any variant name)

{ "Project.name": { "regex": "^API-" } }

Existence Operators

Operator	Format	Description
exists	{"exists": true}	Field value is present and not null
exists	{"exists": false}	Field value is null or missing

Works with: All field types

// Thogits where due_date is set
{ "Project.due_date": { "exists": true } }

// Thogits where due_date is not set (equivalent to bare null)
{ "Project.due_date": { "exists": false } }
{ "Project.due_date": null }

Set Operators

Operator	Format	Description
in	{"in": [v1, v2, ...]}	Value is one of the given values

Works with: String, Number, Select (matches variant name), MultiSelect (matches any variant name)

{ "Project.story_points": { "in": [1, 2, 3, 5, 8] } }

Type Compatibility Matrix

Operator	String	Number	Boolean	Date	Reference	Select	MultiSelect
eq	Yes	Yes	Yes	Yes	—	Yes (name)	Yes (name)
neq	Yes	Yes	Yes	Yes	—	Yes (name)	Yes (name)
gt / gte	Yes	Yes	—	Yes	—	Yes (ordinal)	Yes (ordinal)
lt / lte	Yes	Yes	—	Yes	—	Yes (ordinal)	Yes (ordinal)
regex	Yes	—	—	—	—	Yes (name)	Yes (name)
in	Yes	Yes	—	—	—	Yes (name)	Yes (name)
exists	Yes	Yes	Yes	Yes	Yes	Yes	Yes

---

TagFilter Operators

Used to filter tags (e.g., in tag search endpoints).

Operator	Format	Description
search	{"search": "text"}	Full-text search on tag name + description
name	{"name": <TextFilter>}	Filter on tag name (uses TextFilter operators)
description	{"description": <TextFilter>}	Filter on tag description
and	{"and": [f1, f2, ...]}	All conditions must match
or	{"or": [f1, f2, ...]}	Any condition can match
not	{"not": <filter>}	Negation

Examples

// Tags whose name equals "project"
{ "name": { "eq": "project" } }

// Tags with "tracker" in name or description
{ "search": "tracker" }

// Combine filters
{ "and": [
  { "name": { "regex": "^Project" } },
  { "not": { "name": { "eq": "Project Archive" } } }
]}

---

Composition

All filter types support and, or, and not for arbitrary nesting.

Combinator	Behavior
and	All child filters must match. Short-circuits on first failure.
or	At least one child filter must match. Short-circuits on first success.
not	Inverts the child filter.

{
  "and": [
    { "has_tag": "Task" },
    { "not": { "Task.status": { "eq": "Done" } } },
    { "or": [
      { "Task.priority": { "gte": 3 } },
      { "Task.labels": { "in": ["Urgent"] } }
    ]}
  ]
}

Tip

A single filter object with no combinator is implicitly a one-condition and. You only need explicit and/or when combining multiple conditions.