Human-Friendly Filter
Write intuitively. Read clearly.
Website · Tutorials · Guides · Cookbook · Backends · Reference · Specification · Design Records
HFF is a small, type-safe filter language for people querying your service. Combine conditions, search nested data, and filter collections in expressions you can read at a glance. Choose the features your service exposes, with one language designed for local evaluation and translation to backends such as SQL.
name="Alice" age>=18
labels.app="api" labels.env="production"
status>=500 latency_ms>1000
status="open" priority:in("high","urgent")
assignee!.email~"@example\\.com$"
items:any(item=>item.price*item.quantity>=100)
- Built for Humans. Write compact conditions with familiar comparisons, spaces for AND, and methods for common filtering tasks. The syntax prioritizes how people read and write queries.
- Portable Across Backends. Use the same syntax and semantics for local evaluation and translation to SQL or other processing systems. Backend adapters map the language to each target without changing the query grammar.
- Lightweight and Flexible. Keep the runtime small and portable. Extend typed methods and backend adapters to fit different environments and service requirements.
- Pure and Type-Safe. Check variables and operations against a schema before evaluation. Filters have no side effects, and null-safe rules handle missing values without exception-handling expressions.
- Configurable Capabilities. Choose the operators and methods your service supports. The syntax stays fixed; unavailable features are rejected during compilation.
- Ready to Use. Supply a schema and capability set to a configurable engine. Typed Go parsing generated by PEGO, compilation, and execution form an integrated filter interface for your service.
HFF is deliberately a filter language, not a complete programming language.
Queries must depend on service data: age+10<20 is a filter, while 1+1,
10<20, and 10<age are rejected.
AIP-160 filtering addresses human-written service filters. HFF aims to cover needs beyond that model, including arithmetic, list indexing, and receiver methods. HFF uses AND-before-OR precedence, unlike AIP-160's OR-before-AND rule.
CEL is a portable, safe expression language for embedding in applications. HFF places its emphasis on quickly written filter queries, service-specific capability selection, and translation to arbitrary backends alongside its own runtime.
HFF syntax is defined in PEGO, with a typed Go parser generated from the grammar. The syntax-only parser is currently internal to this module; applications do not yet have a public parse-only API. The same grammar is used for every capability configuration. PEGO is a development-time parser generator, not a requirement to compile grammars at runtime.
This repository provides immutable values, schemas, capabilities, validated input, common query compilation, core local evaluation, scalar/string methods, and list/object methods and collection callbacks. Base64 and JSON conversion methods and local extension evaluators are also available. The SQL backend builds parameterized PostgreSQL predicates for documented scalar, schema-typed JSON/JSONB, and native composite profiles, and supports typed SQL method translators. Full JSONB type fidelity, broader structure and relation mapping, and additional dialects remain in progress. Start with the tutorials for a staged local-service example. Use the guides for feature behavior, the cookbook for practical filter recipes, backend documentation for local and PostgreSQL support, and the reference for exact method and Go API lookups.
Read the language specification, beginning with syntax, types and schemas, and evaluation. The normative method catalog defines the configurable library; the reference index provides a receiver-family lookup. Capabilities describe integration requirements.
Design records explain the rationale for individual language features.