|
|
|
|
|
# Maintaining the Memo Filter Engine
|
|
|
|
|
|
|
|
|
|
|
|
The engine is memo-specific; any future field or behavior changes must stay
|
|
|
|
|
|
consistent with the memo schema and store implementations. Use this guide when
|
|
|
|
|
|
extending or debugging the package.
|
|
|
|
|
|
|
|
|
|
|
|
## Adding a New Memo Field
|
|
|
|
|
|
|
|
|
|
|
|
1. **Update the schema**
|
|
|
|
|
|
- Add the field entry in `schema.go`.
|
|
|
|
|
|
- Define the backing column (`Column`), JSON path (if applicable), type, and
|
|
|
|
|
|
allowed operators.
|
|
|
|
|
|
- Include the CEL variable in `EnvOptions`.
|
|
|
|
|
|
2. **Adjust parser or renderer (if needed)**
|
|
|
|
|
|
- For non-scalar fields (JSON booleans, lists), add handling in
|
|
|
|
|
|
`parser.go` or extend the renderer helpers.
|
|
|
|
|
|
- Keep validation in the parser (e.g., reject unsupported operators).
|
|
|
|
|
|
3. **Write a golden test**
|
|
|
|
|
|
- Extend the dialect-specific memo filter tests under
|
|
|
|
|
|
`store/db/{sqlite,mysql,postgres}/memo_filter_test.go` with a case that
|
|
|
|
|
|
exercises the new field.
|
|
|
|
|
|
4. **Run `go test ./...`** to ensure the SQL output matches expectations across
|
|
|
|
|
|
all dialects.
|
|
|
|
|
|
|
|
|
|
|
|
## Supporting Dialect Nuances
|
|
|
|
|
|
|
|
|
|
|
|
- Centralize differences inside `render.go`. If a new dialect-specific behavior
|
|
|
|
|
|
emerges (e.g., JSON operators), add the logic there rather than leaking it
|
|
|
|
|
|
into store code.
|
|
|
|
|
|
- Use the renderer helpers (`jsonExtractExpr`, `jsonArrayExpr`, etc.) rather than
|
|
|
|
|
|
sprinkling ad-hoc SQL strings.
|
|
|
|
|
|
- When placeholders change, adjust `addArg` so that argument numbering stays in
|
|
|
|
|
|
sync with store queries.
|
|
|
|
|
|
|
|
|
|
|
|
## Debugging Tips
|
|
|
|
|
|
|
|
|
|
|
|
- **Parser errors** – Most originate in `buildCondition` or schema validation.
|
|
|
|
|
|
Enable logging around `parser.go` when diagnosing unknown identifier/operator
|
|
|
|
|
|
messages.
|
|
|
|
|
|
- **Renderer output** – Temporary printf/log statements in `renderCondition` help
|
|
|
|
|
|
identify which IR node produced unexpected SQL.
|
|
|
|
|
|
- **Store integration** – Ensure drivers call `filter.DefaultEngine()` exactly once
|
|
|
|
|
|
per process; the singleton caches the parsed CEL environment.
|
|
|
|
|
|
|
|
|
|
|
|
## Testing Checklist
|
|
|
|
|
|
|
|
|
|
|
|
- `go test ./store/...` ensures all dialect tests consume the engine correctly.
|
|
|
|
|
|
- Add targeted unit tests whenever new IR nodes or renderer paths are introduced.
|
|
|
|
|
|
- When changing boolean or JSON handling, verify all three dialect test suites
|
|
|
|
|
|
(SQLite, MySQL, Postgres) to avoid regression.
|
