Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions docs/specs/semantic/agent-query-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
65 changes: 59 additions & 6 deletions resolver/filter_value.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"reflect"
"strconv"
"strings"
"time"

"github.com/meaningforge/metis/ossie"
"github.com/meaningforge/metis/query"
Expand All @@ -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) {
Expand Down Expand Up @@ -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")
Expand All @@ -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:
Expand Down
102 changes: 102 additions & 0 deletions resolver/resolver_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"errors"
"fmt"
"reflect"
"strings"
"testing"
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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{
Expand Down
Loading