Introduction

These tutorials build an HFF filter into a small Go service, one step at a time. They use Go 1.27.1 and only APIs available in this repository. For a quick browser experiment, try the Playground in Local mode, or inspect a parameterized PostgreSQL predicate with a version-1 configuration document. See serialized HFF configuration for the document format.

1. Write your first filter: configure a schema, compile a human-authored query, build a local filter, and match records.
2. Use a filter in a service: compile and build once, validate records at ingestion, reuse validated inputs, and handle rejected queries as configuration errors.
3. Add a service-specific method: declare a typed signature, select its capability, and register a local evaluator.
4. Translate a method to PostgreSQL: register a typed backend translator, build a parameterized predicate, and inspect execution guarantees without opening a database connection.
5. Bind a Go record type: infer an HFF schema and build a typed local filter from an application record type.
6. Bind PostgreSQL data to HFF records: map related database rows to an HFF list, bind native bytea values, and execute generated predicates with caller-owned SQL. Continue with the PostgreSQL cookbook recipes for flattened nullable parents, nested relations, JSONB metadata, and many-to-many views.

Run each complete example from the repository root:

go run ./examples/tutorial-first-filter
go run ./examples/tutorial-service
go run ./examples/extensions
go run ./examples/sql-extensions
go run ./examples/go-binding
go run ./examples/sql-relations
go run ./examples/sql-bytes

For feature explanations, continue with the guides. Use the cookbook for focused filter recipes, the reference for exact contracts, and Backends for local and PostgreSQL behavior. The language specification is normative.