From b37878d7b3c705a7b1a046b572b755ad156caf9b Mon Sep 17 00:00:00 2001 From: forger <325344250+meaningforger@users.noreply.github.com> Date: Sat, 10 Oct 2026 08:46:57 +0800 Subject: [PATCH] feat(query): validate typed filter operators --- README.md | 4 + docs/specs/semantic/agent-query-contract.md | 10 ++ resolver/filter_value.go | 65 +++++++++++-- resolver/resolver_test.go | 102 ++++++++++++++++++++ 4 files changed, 175 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 90ac60b..166403f 100644 --- a/README.md +++ b/README.md @@ -146,6 +146,10 @@ For example, an Integer filter value of `9007199254740993` and a Decimal filter value of `0.10000000000000000001` are parameterized without first passing through float64. Incompatible or out-of-range operands return `INVALID_FILTER_VALUE` without disclosing the value. +The Resolver also rejects ordered comparisons for Boolean and Opaque fields and +validates Date, Time, DateTime, and DateTimeTz literals before planning. A query +targets one selected data source; Metis does not perform cross-database query +execution. Explain generates SQL without executing it. To filter source metrics by matching rows on one declared detail relationship diff --git a/docs/specs/semantic/agent-query-contract.md b/docs/specs/semantic/agent-query-contract.md index e08b901..c5c5623 100644 --- a/docs/specs/semantic/agent-query-contract.md +++ b/docs/specs/semantic/agent-query-contract.md @@ -38,6 +38,16 @@ this path. Thus `9007199254740993` and `0.10000000000000000001` reach compatible Integer/Decimal database parameters without float64 rounding; precision already lost by a caller before JSON encoding cannot be recovered. +Filter operators are also checked against the resolved semantic datatype before +planning. Boolean and Opaque fields support equality, membership, and null +tests, but not ordered comparison or `between`. String, numeric, and temporal +fields support the full operator vocabulary. Date, Time, DateTime, and +DateTimeTz operands must respectively use `YYYY-MM-DD`, ISO local time, ISO +date-time (with an optional explicit offset), and RFC3339 forms; invalid +calendar or clock values fail with `INVALID_FILTER_VALUE` without echoing the +operand. These are semantic query rules for one selected source target. Core +does not coordinate types, joins, or execution across databases. + `attribute_metric` contains no dialect, DataSource, target, Renderer, Driver, limit, ordering, top-k, or raw predicate field. Its periods are exact RFC3339 instants with explicit offsets. Agents select refs and periods, but must not diff --git a/resolver/filter_value.go b/resolver/filter_value.go index 240e959..71fb5fb 100644 --- a/resolver/filter_value.go +++ b/resolver/filter_value.go @@ -7,6 +7,7 @@ import ( "reflect" "strconv" "strings" + "time" "github.com/meaningforge/metis/ossie" "github.com/meaningforge/metis/query" @@ -16,21 +17,45 @@ import ( const maxFilterDecimalPrecision = 38 func normalizeFilterValue(filter query.Filter, datatype ossie.DataType) (query.Filter, error) { + if !filterOperatorSupportsDatatype(filter.Operator, datatype) { + return query.Filter{}, invalidFilterValue(filter, datatype, "filter operator is incompatible with the semantic datatype") + } if filter.Operator == query.FilterIsNull || filter.Operator == query.FilterIsNotNull { return filter, nil } value, err := normalizeFilterOperand(filter.Value, datatype, filter.Operator) if err != nil { - return query.Filter{}, &serrors.Error{ - Code: serrors.ErrInvalidFilterValue, - Message: "filter operand is incompatible with the semantic datatype", - Details: map[string]any{"field": filter.Field, "datatype": datatype, "operator": filter.Operator}, - } + return query.Filter{}, invalidFilterValue(filter, datatype, "filter operand is incompatible with the semantic datatype") } filter.Value = value return filter, nil } +func invalidFilterValue(filter query.Filter, datatype ossie.DataType, message string) error { + return &serrors.Error{ + Code: serrors.ErrInvalidFilterValue, + Message: message, + Details: map[string]any{"field": filter.Field, "datatype": datatype, "operator": filter.Operator}, + } +} + +func filterOperatorSupportsDatatype(operator query.FilterOperator, datatype ossie.DataType) bool { + switch datatype { + case ossie.DataTypeBoolean, "", ossie.DataTypeOpaque: + switch operator { + case query.FilterEQ, query.FilterNEQ, query.FilterIN, query.FilterNotIn, query.FilterIsNull, query.FilterIsNotNull: + return true + default: + return false + } + case ossie.DataTypeString, ossie.DataTypeInteger, ossie.DataTypeDecimal, ossie.DataTypeFloat, + ossie.DataTypeDate, ossie.DataTypeTime, ossie.DataTypeDateTime, ossie.DataTypeDateTimeTz: + return true + default: + return false + } +} + func normalizeFilterOperand(value any, datatype ossie.DataType, operator query.FilterOperator) (any, error) { reflected := reflect.ValueOf(value) if reflected.IsValid() && (reflected.Kind() == reflect.Slice || reflected.Kind() == reflect.Array) { @@ -61,11 +86,17 @@ func normalizeFilterScalar(value any, datatype ossie.DataType) (any, error) { return nil, fmt.Errorf("non-null operand required") } switch datatype { - case ossie.DataTypeString, ossie.DataTypeDate, ossie.DataTypeTime, ossie.DataTypeDateTime, ossie.DataTypeDateTimeTz: + case ossie.DataTypeString: if _, ok := value.(string); !ok { return nil, fmt.Errorf("string operand required") } return value, nil + case ossie.DataTypeDate, ossie.DataTypeTime, ossie.DataTypeDateTime, ossie.DataTypeDateTimeTz: + text, ok := value.(string) + if !ok || !validTemporalFilterLiteral(datatype, text) { + return nil, fmt.Errorf("valid temporal operand required") + } + return value, nil case ossie.DataTypeBoolean: if _, ok := value.(bool); !ok { return nil, fmt.Errorf("boolean operand required") @@ -84,6 +115,28 @@ func normalizeFilterScalar(value any, datatype ossie.DataType) (any, error) { } } +func validTemporalFilterLiteral(datatype ossie.DataType, text string) bool { + var layouts []string + switch datatype { + case ossie.DataTypeDate: + layouts = []string{"2006-01-02"} + case ossie.DataTypeTime: + layouts = []string{"15:04:05.999999999"} + case ossie.DataTypeDateTime: + layouts = []string{"2006-01-02T15:04:05.999999999", time.RFC3339Nano} + case ossie.DataTypeDateTimeTz: + layouts = []string{time.RFC3339Nano} + default: + return false + } + for _, layout := range layouts { + if _, err := time.Parse(layout, text); err == nil { + return true + } + } + return false +} + func normalizeIntegerOperand(value any) (any, error) { switch v := value.(type) { case json.Number: diff --git a/resolver/resolver_test.go b/resolver/resolver_test.go index 446e2a7..2aa8ba0 100644 --- a/resolver/resolver_test.go +++ b/resolver/resolver_test.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "errors" + "fmt" "reflect" "strings" "testing" @@ -55,6 +56,22 @@ semantic_model: expression: dialects: [{dialect: ANSI_SQL, expression: orders.order_date}] dimension: {} + - name: order_time + datatype: Time + expression: + dialects: [{dialect: ANSI_SQL, expression: orders.order_time}] + - name: created_at + datatype: DateTime + expression: + dialects: [{dialect: ANSI_SQL, expression: orders.created_at}] + - name: occurred_at + datatype: DateTimeTz + expression: + dialects: [{dialect: ANSI_SQL, expression: orders.occurred_at}] + - name: native_value + datatype: Opaque + expression: + dialects: [{dialect: ANSI_SQL, expression: orders.native_value}] - name: customer source: sales.public.customer fields: @@ -67,6 +84,10 @@ semantic_model: expression: dialects: [{dialect: ANSI_SQL, expression: customer.region}] dimension: {} + - name: vip + datatype: Boolean + expression: + dialects: [{dialect: ANSI_SQL, expression: customer.vip}] relationships: - name: orders_to_customer from: orders @@ -251,6 +272,87 @@ func TestResolveRejectsDatatypeIncompatibleFilterOperandsWithoutDisclosure(t *te } } +func TestResolveRejectsDatatypeIncompatibleFilterOperators(t *testing.T) { + r := newResolver(t) + for _, filter := range []query.Filter{ + {Field: "active", Operator: query.FilterGT, Value: true}, + {Field: "active", Operator: query.FilterBetween, Value: []bool{false, true}}, + {Field: "native_value", Operator: query.FilterLTE, Value: "vendor-value"}, + {Field: "native_value", Operator: query.FilterBetween, Value: []string{"a", "z"}}, + } { + _, err := r.Resolve(context.Background(), query.SemanticQuery{Model: "sales", Metrics: []query.MetricRef{{Name: "total_revenue"}}, Filters: []query.Filter{filter}}) + assertErrorCode(t, err, serrors.ErrInvalidFilterValue) + } +} + +func TestResolveRejectsDatatypeIncompatibleOperatorsAcrossPredicateForms(t *testing.T) { + r := newResolver(t) + queries := []query.SemanticQuery{ + { + Model: "sales", + Metrics: []query.MetricRef{{Name: "total_revenue"}}, + Filters: query.Predicate{query.Logical(query.PredicateOr, + query.Leaf("active", query.FilterGT, true), + query.Leaf("active", query.FilterEQ, true), + )}, + }, + { + Model: "sales", + Metrics: []query.MetricRef{{Name: "total_revenue"}}, + Filters: query.Predicate{query.Exists("orders_to_customer", + query.Leaf("customer.vip", query.FilterLT, true), + )}, + }, + } + for _, semanticQuery := range queries { + _, err := r.Resolve(context.Background(), semanticQuery) + assertErrorCode(t, err, serrors.ErrInvalidFilterValue) + } +} + +func TestResolveAcceptsSupportedBooleanAndOpaqueFilterOperators(t *testing.T) { + r := newResolver(t) + filters := []query.Filter{ + {Field: "active", Operator: query.FilterEQ, Value: true}, + {Field: "active", Operator: query.FilterIN, Value: []bool{false, true}}, + {Field: "active", Operator: query.FilterIsNotNull}, + {Field: "native_value", Operator: query.FilterEQ, Value: "vendor-value"}, + {Field: "native_value", Operator: query.FilterNotIn, Value: []string{"a", "b"}}, + {Field: "native_value", Operator: query.FilterIsNull}, + } + if _, err := r.Resolve(context.Background(), query.SemanticQuery{Model: "sales", Metrics: []query.MetricRef{{Name: "total_revenue"}}, Filters: filters}); err != nil { + t.Fatal(err) + } +} + +func TestResolveValidatesTemporalFilterLiterals(t *testing.T) { + r := newResolver(t) + valid := []query.Filter{ + {Field: "order_date", Operator: query.FilterEQ, Value: "2026-09-09"}, + {Field: "order_time", Operator: query.FilterBetween, Value: []string{"12:30:45", "12:30:45.123456789"}}, + {Field: "created_at", Operator: query.FilterGTE, Value: "2026-09-09T12:30:45.123"}, + {Field: "created_at", Operator: query.FilterLT, Value: "2026-09-09T12:30:45Z"}, + {Field: "occurred_at", Operator: query.FilterLT, Value: "2026-09-09T12:30:45+08:00"}, + } + if _, err := r.Resolve(context.Background(), query.SemanticQuery{Model: "sales", Metrics: []query.MetricRef{{Name: "total_revenue"}}, Filters: valid}); err != nil { + t.Fatal(err) + } + + for _, filter := range []query.Filter{ + {Field: "order_date", Operator: query.FilterEQ, Value: "2026-02-30"}, + {Field: "order_time", Operator: query.FilterEQ, Value: "25:00:00"}, + {Field: "created_at", Operator: query.FilterEQ, Value: "2026-09-09 12:30:45"}, + {Field: "occurred_at", Operator: query.FilterEQ, Value: "2026-09-09T12:30:45"}, + {Field: "order_date", Operator: query.FilterIN, Value: []string{"2026-09-09", "not-a-date"}}, + } { + _, err := r.Resolve(context.Background(), query.SemanticQuery{Model: "sales", Metrics: []query.MetricRef{{Name: "total_revenue"}}, Filters: []query.Filter{filter}}) + assertErrorCode(t, err, serrors.ErrInvalidFilterValue) + if strings.Contains(err.Error(), fmt.Sprint(filter.Value)) { + t.Fatalf("error disclosed operand: %v", err) + } + } +} + func TestResolveBooleanPredicateSameDataset(t *testing.T) { r := newResolver(t) resolved, err := r.Resolve(context.Background(), query.SemanticQuery{