update Client.Evaluate call to version 1.2alpha1 (breaking)

this introduces a breaking change in `Evaluate` requiring users of
this function to update as follows:
```
Evaluate(items, calculations, data)
        ↓
Evaluate(data).
    Items(items...).
    Calculations(calculations...)
```
the type `AggregateMethod` has been updated as follows:
```
AggregateMethod → TimeAggregationMethod
```
with new value names:
```
AggregateDefault          → TimeAggregationDefault
AggregateCount            → TimeAggregationCount
AggregateMin              → TimeAggregationMin
AggregateMax              → TimeAggregationMax
AggregateSum              → TimeAggregationSum
AggregateAvg              → TimeAggregationAvg
AggregateStateHistSeconds → TimeAggregationSeconds
AggregateStateHistPercent → TimeAggregationPercent
AggregateStateHistRate    → TimeAggregationRate
```
the type `ItemAggregation` has been updated as follows:
```
ItemAggregation → EvaluateItem
```

automation/routine_evaluate_actions.go

@@ -1,4 +1,4 @@
-// Copyright 2023 Searis AS
+// Copyright 2023-2024 Searis AS
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -27,7 +27,7 @@ import (
 // well as annotations for passing on to actions.
 type Evaluation struct {
 	// Items lists item aggregations for items with known IDs.
-	Items []fields.ItemAggregation
+	Items []fields.EvaluateItem
 
 	// Calculations lists calculations to perform. A calculation can reference
 	// items or previous calculations.
@@ -75,7 +75,9 @@ func (e EvaluateActions) Do(ctx context.Context, cfg *Config) error {
 	}
 
 	selection, err := client.Clarify().
-		Evaluate(e.Evaluation.Items, e.Evaluation.Calculations, dataQuery).
+		Evaluate(dataQuery).
+		Items(e.Evaluation.Items...).
+		Calculations(e.Evaluation.Calculations...).
 		Do(ctx)
 	if err != nil {
 		return err

client.go

@@ -1,4 +1,4 @@
-// Copyright 2022-2023 Searis AS
+// Copyright 2022-2024 Searis AS
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -15,6 +15,8 @@
 package clarify
 
 import (
+	"context"
+
 	"github.com/clarify/clarify-go/fields"
 	"github.com/clarify/clarify-go/internal/request"
 	"github.com/clarify/clarify-go/jsonrpc"
@@ -29,6 +31,7 @@ const (
 	paramFormat         jsonrpc.ParamName = "format"
 	paramIntegration    jsonrpc.ParamName = "integration"
 	paramItems          jsonrpc.ParamName = "items"
+	paramGroups         jsonrpc.ParamName = "groups"
 	paramItemsBySignal  jsonrpc.ParamName = "itemsBySignal"
 	paramQuery          jsonrpc.ParamName = "query"
 	paramSignalsByInput jsonrpc.ParamName = "signalsByInput"
@@ -256,27 +259,72 @@ var methodDataFrame = request.RelationalMethod[DataFrameResult]{
 
 // Evaluate returns a new request for retrieving aggregated data from Clarify
 // and perform calculations.
-func (ns ClarifyNamespace) Evaluate(items []fields.ItemAggregation, calculations []fields.Calculation, data fields.DataQuery) EvaluateRequest {
-	return methodEvaluate.NewRequest(ns.h,
-		paramItems.Value(items),
-		paramCalculations.Value(calculations),
-		paramData.Value(data),
-		paramFormat.Value(views.SelectionFormat{
-			GroupIncludedByType: true,
-		}),
-	)
+func (ns ClarifyNamespace) Evaluate(data fields.DataQuery) EvaluateRequest {
+	return EvaluateRequest{
+		data: data,
+		h:    ns.h,
+	}
 }
 
-type (
-	// EvaluateRequest describe an initialized clarify.evaluate RPC request with
-	// access to a request handler.
-	EvaluateRequest = request.Relational[EvaluateResult]
+func (er EvaluateRequest) Items(items ...fields.EvaluateItem) EvaluateRequest {
+	newItems := make([]fields.EvaluateItem, len(er.items)+len(items))
+	newItems = append(append(newItems, er.items...), items...)
+	er.items = newItems
 
-	// EvaluateResult describe the result format for a EvaluateRequest.
-	EvaluateResult = views.Selection[views.DataFrame, views.DataFrameInclude]
-)
+	return er
+}
+
+func (er EvaluateRequest) Groups(groups ...fields.EvaluateGroup) EvaluateRequest {
+	newGroups := make([]fields.EvaluateGroup, len(er.groups)+len(groups))
+	newGroups = append(append(newGroups, er.groups...), groups...)
+	er.groups = newGroups
+
+	return er
+}
+
+func (er EvaluateRequest) Calculations(calculations ...fields.Calculation) EvaluateRequest {
+	newCalculations := make([]fields.Calculation, len(er.calculations)+len(calculations))
+	newCalculations = append(append(newCalculations, er.calculations...), calculations...)
+	er.calculations = newCalculations
+
+	return er
+}
+
+func (er EvaluateRequest) Include(relationships ...string) EvaluateRequest {
+	newRelationships := make([]string, len(er.relationships)+len(relationships))
+	newRelationships = append(append(newRelationships, er.relationships...), relationships...)
+	er.relationships = newRelationships
+
+	return er
+}
+
+func (er EvaluateRequest) Do(ctx context.Context) (*EvaluateResult, error) {
+	r := methodEvaluate.NewRequest(er.h,
+		paramData.Value(er.data),
+		paramItems.Value(er.items),
+		paramGroups.Value(er.groups),
+		paramCalculations.Value(er.calculations))
+
+	r.Include(er.relationships...)
+
+	return r.Do(ctx)
+}
+
+// EvaluateRequest describe an initialized clarify.evaluate RPC request with
+// access to a request handler.
+type EvaluateRequest struct {
+	data          fields.DataQuery
+	items         []fields.EvaluateItem
+	groups        []fields.EvaluateGroup
+	calculations  []fields.Calculation
+	relationships []string
+	h             jsonrpc.Handler
+}
+
+// EvaluateResult describe the result format for a EvaluateRequest.
+type EvaluateResult = views.Selection[views.DataFrame, views.DataFrameInclude]
 
 var methodEvaluate = request.RelationalMethod[EvaluateResult]{
-	APIVersion: apiVersion,
+	APIVersion: "1.2alpha1",
 	Method:     "clarify.evaluate",
 }

examples/automation_cli/routines.go

@@ -181,8 +181,8 @@ func transformLabelValuesToTitle(item *views.ItemSave) {
 
 var detectFire = automation.EvaluateActions{
 	Evaluation: automation.Evaluation{
-		Items: []fields.ItemAggregation{
-			{Alias: "fire_rate", ID: os.Getenv("CLARIFY_EXAMPLE_STATUS_ITEM_ID"), Aggregation: fields.AggregateStateHistRate, State: 1},
+		Items: []fields.EvaluateItem{
+			{Alias: "fire_rate", ID: os.Getenv("CLARIFY_EXAMPLE_STATUS_ITEM_ID"), TimeAggregation: fields.TimeAggregationRate, State: 1},
 		},
 		Calculations: []fields.Calculation{
 			{Alias: "has_fire", Formula: "fire_rate > 0"}, // return 1.0 when true.

examples/devdata_cli/commands.go

@@ -722,7 +722,7 @@ func (p *program) evaluateCommand() *ffcli.Command {
 }
 
 func (p *program) evaluate(ctx context.Context, config evaluateConfig) error {
-	var items []fields.ItemAggregation
+	var items []fields.EvaluateItem
 	if err := json.Unmarshal([]byte(config.items), &items); err != nil {
 		return fmt.Errorf("-items: %w", err)
 	}
@@ -746,7 +746,9 @@ func (p *program) evaluate(ctx context.Context, config evaluateConfig) error {
 		data = data.Last(config.last)
 	}
 
-	req := p.client.Clarify().Evaluate(items, calculations, data)
+	req := p.client.Clarify().Evaluate(data).
+		Items(items...).
+		Calculations(calculations...)
 	if config.includeItems {
 		req = req.Include("items")
 	}

examples/evaluate/main.go

@@ -40,16 +40,19 @@ func main() {
 	if len(selection.Data) == 0 {
 		panic("this example require your organization to expose at least one item")
 	}
-	items := []fields.ItemAggregation{
-		{Alias: "i1", ID: selection.Data[0].ID, Aggregation: fields.AggregateAvg},
+	items := []fields.EvaluateItem{
+		{Alias: "i1", ID: selection.Data[0].ID, TimeAggregation: fields.TimeAggregationAvg},
 	}
 	calculations := []fields.Calculation{
 		{Alias: "c1", Formula: "sin(a)"},
 		{Alias: "c2", Formula: "sin(2*PI*time_seconds/3600)"},
 		{Alias: "c3", Formula: "max(c1,c2)"},
 	}
 
-	result, err := client.Clarify().Evaluate(items, calculations, data).Do(ctx)
+	result, err := client.Clarify().Evaluate(data).
+		Items(items...).
+		Calculations(calculations...).
+		Do(ctx)
 	if err != nil {
 		panic(err)
 	}