filterql-builder

FilterQL Builder

Purpose

Translate structured conditions into valid FilterQL syntax. Takes field/operator/value tuples with AND/OR grouping and produces a syntactically correct FilterQL string.

Environment

• None required (pure construction, no API calls)

Inputs

• Conditions: list of (field, operator, value) tuples
• Grouping: AND/OR/NOT composition
• Table: target table (default: user)
• Alias: segment slug name

Behavior

Step 1: Map Each Condition to FilterQL Syntax

For each condition, use the type-operator compatibility matrix from ../references/field-types.md:

Field Type	Natural Language	FilterQL
string	equals "X"	field = "X"
string	not "X"	field != "X"
string	contains "X"	field CONTAINS "X"
string	like pattern	field LIKE "pattern*"
string	one of A,B,C	field IN ("A", "B", "C")
bool	is true	field = true
bool	is false	field = false
int/number	more than N	field > N
int/number	at least N	field >= N
int/number	less than N	field < N
date	after N days ago	field > "now-Nd"
date	before N days ago	field < "now-Nd"
date	within last N hours	field > "now-Nh"
[]string (set)	has "X"	field INTERSECTS ("X")
[]string (set)	doesn't have "X"	field NOT INTERSECTS ("X")
any	has any value	EXISTS field
any	is empty	NOT EXISTS field

Step 2: Compose Conditions

Wrap conditions in AND/OR/NOT:

FILTER AND (
  condition1,
  condition2,
  OR (condition3, condition4)
) FROM table ALIAS slug_name

Rules:

• Single condition: FILTER condition FROM table ALIAS slug
• Multiple conditions default to AND
• NOT can wrap any single condition or group
• Parentheses required for AND/OR groups
• Comma-separate conditions within groups

Step 3: Generate Slug Name

Convert the alias to a valid slug:

• Lowercase
• Replace spaces with underscores
• Remove special characters
• Keep it descriptive but concise

Step 4: Output

Return the complete FilterQL string:

FILTER AND (country = "US", visitct > 5) FROM user ALIAS us_active_visitors

Date Math Reference

Period	Syntax	Example
Hours	"now-Nh"	"now-24h" = 1 day ago
Days	"now-Nd"	"now-30d" = 30 days ago
Weeks	"now-Nw"	"now-4w" = 4 weeks ago
Months	"now-NM"	"now-6M" = 6 months ago
Years	"now-Ny"	"now-1y" = 1 year ago

Common conversions:

• 1 year = "now-1y" or "now-8760h" or "now-365d"
• 90 days = "now-90d" or "now-2160h"
• 1 week = "now-1w" or "now-7d" or "now-168h"

Error Handling

• If a field type is incompatible with the requested operator, suggest the correct operator
• If values contain quotes, escape them
• If the FilterQL is syntactically invalid, identify and fix the issue

Dependencies

• References: ../references/filterql-grammar.md, ../references/field-types.md