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:

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

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