feat: default, pinned and required filters in explore

proto/gen/rill/runtime/v1/runtime.swagger.yaml

@@ -5316,6 +5316,18 @@ definitions:
         items:
           type: string
         description: Temporary to differentiate between "select" and "in list" modes. Expression will be replaced with UI specific state in the future.
+      pinnedFilters:
+        type: array
+        items:
+          type: string
+        title: Array of dimension or measure names
+      requiredFilters:
+        type: array
+        items:
+          type: string
+        description: |-
+          Array of dimension or measure names that must have a value before the explore can render.
+          Required filters are implicitly pinned.
       timeRange:
         type: string
         description: |-

proto/rill/runtime/v1/resources.proto

@@ -540,6 +540,11 @@ message ExplorePreset {
   optional Expression where = 11;
   // Temporary to differentiate between "select" and "in list" modes. Expression will be replaced with UI specific state in the future.
   repeated string dimensions_with_inlist_filter = 29;
+  // Array of dimension or measure names
+  repeated string pinned_filters = 40;
+  // Array of dimension or measure names that must have a value before the explore can render.
+  // Required filters are implicitly pinned.
+  repeated string required_filters = 41;
 
   // Time range for the explore.
   // It corresponds to the `range` property of the explore's `time_ranges`.

runtime/parser/parse_explore.go

@@ -7,6 +7,8 @@ import (
 	"time"
 
 	runtimev1 "github.com/rilldata/rill/proto/gen/rill/runtime/v1"
+	"github.com/rilldata/rill/runtime/metricsview"
+	"github.com/rilldata/rill/runtime/metricsview/metricssql"
 	"github.com/rilldata/rill/runtime/pkg/rilltime"
 	"golang.org/x/exp/maps"
 	"gopkg.in/yaml.v3"
@@ -30,8 +32,13 @@ type ExploreYAML struct {
 		Dimensions          *FieldSelectorYAML `yaml:"dimensions"`
 		Measures            *FieldSelectorYAML `yaml:"measures"`
 		TimeRange           string             `yaml:"time_range"`
+		TimeGrain           string             `yaml:"time_grain"`
+		ComparisonTimeRange string             `yaml:"comparison_time_range"`
 		ComparisonMode      string             `yaml:"comparison_mode"`
 		ComparisonDimension string             `yaml:"comparison_dimension"`
+		Filter              string             `yaml:"filter"`
+		PinnedFilters       []string           `yaml:"pinned_filters"`
+		RequiredFilters     []string           `yaml:"required_filters"`
 	} `yaml:"defaults"`
 	Embeds struct {
 		HidePivot bool `yaml:"hide_pivot"`
@@ -242,18 +249,48 @@ func (p *Parser) parseExplore(node *Node) error {
 		if tmp.Defaults.TimeRange != "" {
 			tr = &tmp.Defaults.TimeRange
 		}
+		var tg *string
+		if tmp.Defaults.TimeGrain != "" {
+			tg = &tmp.Defaults.TimeGrain
+		}
+
+		var ctr *string
+		if tmp.Defaults.ComparisonTimeRange != "" {
+			ctr = &tmp.Defaults.ComparisonTimeRange
+			// Only set comparison mode to time if not directly set
+			if tmp.Defaults.ComparisonMode == "" {
+				mode = runtimev1.ExploreComparisonMode_EXPLORE_COMPARISON_MODE_TIME
+			}
+		}
+
 		var compareDim *string
 		if tmp.Defaults.ComparisonDimension != "" {
 			compareDim = &tmp.Defaults.ComparisonDimension
 		}
+
+		var filter *runtimev1.Expression
+		if tmp.Defaults.Filter != "" {
+			expr, err := metricssql.ParseFilter(tmp.Defaults.Filter)
+			if err != nil {
+				return fmt.Errorf("invalid filter expression: %q: %w", tmp.Defaults.Filter, err)
+			}
+
+			filter = metricsview.ExpressionToProto(expr)
+		}
+
 		defaultPreset = &runtimev1.ExplorePreset{
 			Dimensions:          presetDimensions,
 			DimensionsSelector:  presetDimensionsSelector,
 			Measures:            presetMeasures,
 			MeasuresSelector:    presetMeasuresSelector,
 			TimeRange:           tr,
+			TimeGrain:           tg,
+			CompareTimeRange:    ctr,
 			ComparisonMode:      mode,
 			ComparisonDimension: compareDim,
+			Where:               filter,
+			PinnedFilters:       tmp.Defaults.PinnedFilters,
+			RequiredFilters:     tmp.Defaults.RequiredFilters,
 		}
 	}
 

runtime/reconcilers/explore.go

@@ -245,6 +245,22 @@ func (r *ExploreReconciler) validateAndRewrite(ctx context.Context, self *runtim
 		}
 		p.Measures = measures
 		p.MeasuresSelector = nil
+
+		// Validate that required filters reference a dimension or measure on the explore.
+		if len(p.RequiredFilters) > 0 {
+			known := make(map[string]bool, len(spec.Dimensions)+len(spec.Measures))
+			for _, d := range spec.Dimensions {
+				known[d] = true
+			}
+			for _, m := range spec.Measures {
+				known[m] = true
+			}
+			for _, name := range p.RequiredFilters {
+				if !known[name] {
+					return nil, nil, fmt.Errorf("required filter %q is not a dimension or measure on this explore", name)
+				}
+			}
+		}
 	}
 
 	// Done with rewriting

runtime/reconcilers/explore_test.go

@@ -114,6 +114,78 @@ defaults:
 	})
 }
 
+func TestExploreRequiredFilters(t *testing.T) {
+	rt, id := testruntime.NewInstance(t)
+	testruntime.PutFiles(t, rt, id, map[string]string{
+		"models/m1.sql": `SELECT 'foo' as foo, 'bar' as bar, 1 as x`,
+		"metrics_views/mv1.yaml": `
+version: 1
+type: metrics_view
+model: m1
+dimensions:
+- column: foo
+- column: bar
+measures:
+- name: x
+  expression: sum(x)
+security:
+  access: true
+`,
+	})
+
+	// A required filter naming an unknown field should fail validation.
+	testruntime.PutFiles(t, rt, id, map[string]string{
+		"explores/e1.yaml": `
+type: explore
+metrics_view: mv1
+dimensions: '*'
+measures: '*'
+defaults:
+  required_filters: ['doesnt_exist']
+`,
+	})
+	testruntime.ReconcileParserAndWait(t, rt, id)
+	testruntime.RequireReconcileState(t, rt, id, 4, 1, 0)
+	e1 := testruntime.GetResource(t, rt, id, runtime.ResourceKindExplore, "e1")
+	require.Nil(t, e1.GetExplore().State.ValidSpec)
+	require.Contains(t, e1.Meta.ReconcileError, `required filter "doesnt_exist"`)
+
+	// A required filter that names a dimension omitted from the explore should also fail.
+	testruntime.PutFiles(t, rt, id, map[string]string{
+		"explores/e1.yaml": `
+type: explore
+metrics_view: mv1
+dimensions:
+  exclude: ['bar']
+measures: '*'
+defaults:
+  required_filters: ['bar']
+`,
+	})
+	testruntime.ReconcileParserAndWait(t, rt, id)
+	testruntime.RequireReconcileState(t, rt, id, 4, 1, 0)
+	e1 = testruntime.GetResource(t, rt, id, runtime.ResourceKindExplore, "e1")
+	require.Nil(t, e1.GetExplore().State.ValidSpec)
+	require.Contains(t, e1.Meta.ReconcileError, `required filter "bar"`)
+
+	// A required filter that names a valid explore field should succeed.
+	testruntime.PutFiles(t, rt, id, map[string]string{
+		"explores/e1.yaml": `
+type: explore
+metrics_view: mv1
+dimensions: '*'
+measures: '*'
+defaults:
+  required_filters: ['foo', 'x']
+`,
+	})
+	testruntime.ReconcileParserAndWait(t, rt, id)
+	testruntime.RequireReconcileState(t, rt, id, 4, 0, 0)
+	e1 = testruntime.GetResource(t, rt, id, runtime.ResourceKindExplore, "e1")
+	require.NotNil(t, e1.GetExplore().State.ValidSpec)
+	require.Equal(t, []string{"foo", "x"}, e1.GetExplore().State.ValidSpec.DefaultPreset.RequiredFilters)
+}
+
 func TestExploreTheme(t *testing.T) {
 	// Create source and model
 	rt, id := testruntime.NewInstance(t)

web-admin/src/features/alerts/metadata/AlertFilters.svelte

@@ -54,8 +54,16 @@
     whereFilter,
     dimensionsWithInlistFilter,
     metricsViewName,
+    // Not supported in alerts/reports as of now
+    new Set(),
+    new Set(),
+  );
+  $: currentMeasureFilters = getMeasureFilters(
+    measureIdMap,
+    havingFilter, // Not supported in alerts/reports  as of now
+    new Set(),
+    new Set(),
   );
-  $: currentMeasureFilters = getMeasureFilters(measureIdMap, havingFilter);
 </script>
 
 <div class="flex flex-col gap-y-3" aria-label="Alert filters">

web-common/src/features/canvas/CanvasDashboardWrapper.svelte

@@ -2,11 +2,11 @@
   import { dynamicHeight } from "@rilldata/web-common/layout/layout-settings.ts";
   import { useRuntimeClient } from "@rilldata/web-common/runtime-client/v2";
   import CellInspector from "@rilldata/web-common/components/CellInspector.svelte";
-  import WarningIcon from "@rilldata/web-common/components/icons/WarningIcon.svelte";
   import CanvasFilters from "./filters/CanvasFilters.svelte";
   import { getCanvasStore } from "./state-managers/state-managers";
   import ThemeProvider from "../dashboards/ThemeProvider.svelte";
   import CanvasPdfExportView from "../exports/pdf/CanvasPdfExportView.svelte";
+  import RequiredFiltersMessage from "@rilldata/web-common/features/dashboards/filters/required/RequiredFiltersMessage.svelte";
 
   const client = useRuntimeClient();
 
@@ -87,34 +87,7 @@
       }}
     >
       {#if hasMissingRequired}
-        <div class="w-full flex justify-center px-6 pt-24 pb-12">
-          <div
-            class="flex flex-col items-center text-center gap-y-3 px-8 py-10 rounded-lg border border-gray-200 bg-surface-subtle shadow-sm w-full max-w-lg"
-            role="alert"
-          >
-            <WarningIcon size="32px" className="text-amber-500" />
-            <h2 class="text-lg font-semibold text-fg-primary">
-              Select a value to continue
-            </h2>
-            <p class="text-sm text-fg-secondary">
-              This dashboard requires values for the following filter{missingRequiredFilters.length >
-              1
-                ? "s"
-                : ""}:
-            </p>
-            <ul
-              class="text-sm text-fg-primary flex flex-wrap justify-center gap-x-2 gap-y-1"
-            >
-              {#each missingRequiredFilters as missing (missing.key)}
-                <li
-                  class="px-2 py-0.5 rounded-md bg-red-50 border border-red-200 text-red-700"
-                >
-                  {missing.label}
-                </li>
-              {/each}
-            </ul>
-          </div>
-        </div>
+        <RequiredFiltersMessage {missingRequiredFilters} />
       {:else}
         <div
           class="w-full h-fit flex flex-col items-center row-container relative"

web-common/src/features/canvas/stores/canvas-entity.ts

@@ -37,7 +37,7 @@ import {
   isChartComponentType,
   isTableComponentType,
 } from "../components/util";
-import { FilterManager, flattenExpression } from "./filter-manager";
+import { FilterManager } from "./filter-manager";
 import { getFilterParam } from "./filter-state";
 import { Grid } from "./grid";
 import { TabGroup, type LayoutBlock } from "./tab-group";
@@ -50,6 +50,7 @@ import { DEFAULT_DASHBOARD_WIDTH, namePrefixFromPath } from "../layout-util";
 import { createCustomMapStore } from "@rilldata/web-common/lib/custom-map-store";
 import type { RuntimeClient } from "@rilldata/web-common/runtime-client/v2";
 import { queryServiceConvertExpressionToMetricsSQL } from "@rilldata/web-common/runtime-client";
+import { flattenExpression } from "@rilldata/web-common/features/dashboards/stores/filter-utils.ts";
 
 export const lastVisitedState = new Map<string, string>();