Filters

Scribe supports four filter formats. It auto-detects which one you’re using, so pick whatever fits your context. If you’re deciding which format to use, see Choosing a Filter Format.

Filters are detected in this order:

All four formats work identically in REST and GraphQL queries.

Timestamp attributes (createTimestamp, modifyTimestamp, verifiedTimestamp) accept flexible temporal references instead of absolute timestamps. Works with all filter formats.

Day keywords: yesterday, today, tomorrow

Period keywords: this week, last week, this month, last month, this year, last year (Also: this_week, thisweek, last-month, etc.)

Relative periods: last N units where units can be days, hours, minutes, weeks, etc.

FleX (Flexible Filter Expressions) is a query language that reads like plain English. Values rarely need quoting, whitespace is lenient, and every operator has a natural-language form alongside short symbols and SCIM keywords.

# Reads like a sentence — no quotes, no special syntax
department is Engineering
name starts with John
modified after 2024-01-01

# Same queries, terse style
department=Engineering
name ^= John
modified > 2024-01-01

# Or use SCIM-style operator keywords
department eq Engineering
name sw John
modified gt 2024-01-01

Values like Engineering, John, numbers, dates, UUIDs, IPs, and durations (50ms, 5s) need no quoting. Quote only when a value contains spaces — backticks, single quotes, or double quotes all work: cn = `John Doe`.

# Combine with AND (implicit) and OR
department is Engineering status is active
role in (admin, editor) or department is Engineering

# Natural negation
status isnt disabled
name not starts with Test
role not in (guest, anonymous)

# Phonetic and pattern matching
sn sounds like Smith
cn like John*
mail ends with @example.com

Whitespace between conditions implies AND. Use or, ,, |, or || for OR. AND binds tighter than OR — use parentheses to override:

# Implicit AND
result=ok duration<=50ms

# Explicit OR
result=ok or result=warn

# Parentheses override precedence
channel=LDAP (op=Search or op=Bind)

FleX treats is, not, and ! as modifier words you can drop in front of operators for more natural phrasing.

is is optional before comparison, set, presence, and approximate operators — it reads better but changes nothing:

count is at least 10          # same as: count >= 10
status is in (a, b, c)        # same as: status in (a, b, c)
name is present               # same as: name exists
name is similar to john       # same as: name ~= john

Standalone is means equals: status is active is the same as status = active.

not and ! negate any operator:

result != ok
cn not starts with 'Test'
status not in (admin, root)
!(result = ok)
not(result = ok)

is not, isnt, isn't combine both — natural negation for the same operators is supports:

status isnt active             # same as: status != active
count is not greater than 5    # same as: count <= 5
name isn't present             # same as: name not exists

Simple values need no quotes. Use backticks, single quotes, or double quotes for values with spaces:

status = active
cn = `John Doe`

Special values: null and nil map to “not exists”; true and false are booleans. Quote them to match the literal string.

FleX recognizes unquoted numbers, hex (0xFF), durations (50ms, 5s), timestamps (2024-01-15), UUIDs, IPs, and emails.

Search across multiple attributes with a single condition. Exclusive to FleX and JSON — LDAP and SCIM require explicit OR clauses.

# Pipe syntax (no whitespace around |)
sn|givenName|cn|mail contains 'admin'

# Brace syntax (whitespace allowed)
{sn, givenName, cn, mail} contains 'admin'

Both expand to the same OR expression. Use pipe for compact inline filters; use braces for readability with many attributes.

status in (active, pending, review)
role not in (admin, superuser)

Empty sets check presence: status in () is equivalent to status exists, and status not in () is equivalent to status not exists.

For DN-based matching (LDAP :dn modifier):

member:dn := "cn=John,ou=users,dc=example,dc=com"
ou:dn := Engineering

FleX works in log filtering rules and HOCON config files too.

Structured, programmatic filters for SDKs and code generation.

// Simple equality
{"cn": "john"}

// Multiple conditions (AND)
{"cn": "john", "sn": "doe"}

// Array of values (OR)
{"cn": ["john", "jane"]}

// Operator with value
{"cn": {"sw": "A"}}

// Explicit logical operators
{"_or_": [{"cn": "a"}, {"cn": "b"}]}
{"_not_": {"disabled": "true"}}

• Object {...}: Keys are combined with AND
• Array [...]: Elements are combined with AND

Use _and_, _or_, and _not_ (or without underscores):

{"_or_": [{"status": "active"}, {"status": "pending"}]}
{"_not_": {"disabled": "true"}}
{"_and_": [
  {"type": "user"},
  {"_or_": [{"role": "admin"}, {"role": "operator"}]}
]}

Pipe syntax works identically to FleX:

{"sn|givenName|cn": {"co": "admin"}}

SCIM 2.0 filter syntax (RFC 7644). Basic SCIM filters work through FleX parsing. Complex value filters (emails[type eq "work"]), dotted paths, and URN-qualified attributes are not supported.

cn eq "john"
cn sw "A" and sn pr
not (disabled eq "true")
userName eq "john" or email co "@example.com"

Logical operators: and, or, not (...). Group with parentheses.

SCIM operators are valid FleX syntax. FleX adds aliases like = for eq, != for ne, >= for ge, contains for co, and implicit AND via whitespace. See the FleX operators table for the full mapping.

Standard LDAP filter syntax (RFC 4515) for existing LDAP infrastructure.

(cn=john)
(cn=john*)
(&(objectClass=user)(cn=john*))
(|(cn=john)(cn=jane))
(!(disabled=true))

Composite filters: (&(...)(...)) for AND, (|(...)(...)) for OR, (!(...)) for NOT. Nest freely.

DN-component matching:

(member:dn:=cn=John,ou=users,dc=example,dc=com)
(ou:dn:=Engineering)

• REST Channel — filter parameter, pagination, request headers
• GraphQL Channel — filter argument, collection queries
• Logging — FleX filters in log filtering rules
• Configuration — FleX in HOCON config files
• Error Codes — FILTER_INVALID_SYNTAX, FILTER_UNKNOWN_ATTRIBUTE