feat(query): pluggable family-based plan rendering — registry, routing, VictoriaMetrics + ClickHouse

[qiansheng91]

Makes EntitySet plan generation pluggable, so the storage / query-syntax layer is no longer a fixed switch. External stores and query languages are many; this layer should extend without a code change for each one. Four commits build the mechanism and prove it against two new backends.

1. Family registry

Replace the hardcoded switch (storage.Kind) in the executor with a planrender.Registry, mirroring how GraphStore providers sit behind a contract — the one part of the query path that wasn't yet provider-ised. Prometheus and Elasticsearch rendering move behind two built-in family renderers (label-timeseries, document-search) that wrap the existing functions unchanged. Renderers are pure string builders (the OSS service returns a plan, never connecting to storage), so there are no heavy deps and no build tags.

2. Family-based routing

Route by family, not storage kind. planrender.Renderer drops Handles(kind, method) for Family() + SupportsMethod(method). Registry.Find is keyed by (family, method). The query package owns the kind→family bridge (defaultFamilyForKind), and a storage overrides it by declaring spec.family.

3. VictoriaMetrics — same family, configuration only

VictoriaMetrics speaks the Prometheus query API, so it shares label-timeseries. Declaring kind: victoriametrics + spec.family: label-timeseries renders it through the existing renderer with no Go code.

4. A sql-table family + ClickHouse — a different query syntax

ClickHouse uses SQL, a query model entirely different from PromQL. This is where the shared IR earns its keep:

• ResolveConstraints extracts entity binding + filter parsing into a syntax-neutral Constraint{Field, Op, Values} IR, reusing the existing filter parser and field mappers. Each family just formats the resolved constraints.
• The sql-table renderer formats them as a SQL WHERE clause and renders get_metrics as SELECT toStartOfInterval(…), avg(…) … GROUP BY …, with {from}/{to} placeholders the caller fills from the plan's time_range (mirroring how the PromQL plan pairs a query with a separate time range).
• The Prometheus/Elasticsearch renderers are untouched — they can migrate to ResolveConstraints in a behavior-preserving follow-up.

Adding the victoriametrics and clickhouse kinds was schema-only — the Go / Python / Java SDK types and reference docs are generated by make expand and make docs-schema. examples/extensible-storage/ is a validated walkthrough of both paths (same-family config, and new-family one-renderer-then-config).

Zero behavior change

Existing kinds resolve to the same family and render byte-identical output — the full pre-existing suite passes unmodified. New tests cover the registry, family resolution, the constraint IR, SQL formatting, and end-to-end config-only routing to both new families (TestFamilyOverrideRoutesNewBackendWithoutCode, TestClickHouseRoutesViaSQLFamilyWithoutCode).

Verified: go test ./... (21 pkgs, 0 fail) · make guard verify-go test-service example-validate check-manifest schemas-embed-check docs-schema-check build-service.

Scope

The executor side is untouched — the dialect / query shape is byte-identical, so existing plan consumers are unaffected. Migrating the Prometheus/Elasticsearch renderers onto ResolveConstraints is a natural behavior-preserving follow-up.

[Mr-Xzz]

Reviewed the plan-renderer registry and SQL-table renderer. The registry direction looks good, but I found two blocking issues before this is safe to merge:

1. Unsupported/raw filters are silently omitted from the generated SQL. ResolveConstraints returns unsupported filters in raw, but sqlTableRenderer.Render only echoes them as raw_filters; buildSQLMetricQuery receives only where, so the actual queries[].sql can drop parts of search_filter, data_filter, entity_query, or method query. That can make downstream execution much broader than requested. Please either render all accepted filter shapes into SQL or fail the SQL renderer when raw is non-empty. If returning an error, the executor should not silently fall back to passthrough, because that also hides an unsafe plan-render failure.

2. SQL identifiers and interval tokens are interpolated without validation/quoting. table, time_column, value_column, metric_column, and constraint field names come from schema/mapping config, while step can come from the query parameter. Values are quoted, but identifiers and INTERVAL text are not, so a malformed mapping or step can produce injectable SQL in the generated plan. Please validate/quote identifiers for the ClickHouse dialect and parse step into a strict numeric duration + allowlisted unit before formatting it.

Once those are fixed, I am happy to re-review the updated patch.