Design search UI user experience

[scotwells]

Summary

We need to define the UX that platform operators can expect from the search service when it's integrated into a UI.

This should include exposing index policies so platform operators can understand which resources are indexed by the search service and how.

Acceptance Criteria

• Markdown document created in the docs folder of the service repo that describes the user experience that's expected and how users can use the search service.
• Include renderings / screenshots of user experience w/ text describing any important decisions on why

[JoseSzycho]

Once #17 and #33 are approved, I will ping the front team to start the design process.

Will wait both of this PR to be approved, as most of the API definitions were made there.

[drewr]

Unless we weren't confident that we could build search APIs, this work should have kicked the project off and it could have been happening in parallel. We don't work forwards from the platform; we work backwards from the user experience and then build the APIs to support.

@kevwilliams and @mattdjenkinson heads-up.

[JoseSzycho]

@kevwilliams @mattdjenkinson any updates? Next week I'd like to implement the search query API

[kevwilliams]

Yes as we discussed it should be a simple user search to search across entities.

As a user in the staff portal I should be able to enter a string in the search and have it search across the top indexes to find entities on the platform. Here is a PoC video of how i would expect it to work, when there are actually results this would populate with anything that matches the string the user types in.

Screencast.From.2026-02-20.10-10-49.mp4

[JoseSzycho]

@kevwilliams that looks great! Does the actual API design for querying satisfy your needs? If so, we’ll proceed with implementing that API.

[kevwilliams]

If we are agreeing on the contract being something like this, and I can do CEL expressions etc it should work perfectly. I should be able to request other resourceTypes than user but this is an example that I think conforms to the spec in the search service already.

Request

POST /apis/search.miloapis.com/v1alpha1/resourcesearchqueries
Content-Type: application/json
Authorization: Bearer <token>  (handled by /api/internal proxy)

{
  "apiVersion": "search.miloapis.com/v1alpha1",
  "kind": "ResourceSearchQuery",
  "spec": {
    "query": "alice@example",
    "resourceTypes": ["iam.miloapis.com/v1alpha1/User"],
    "limit": 5
  }
}

Response

{
  "apiVersion": "search.miloapis.com/v1alpha1",
  "kind": "ResourceSearchQuery",
  "spec": { ... },
  "status": {
    "results": [
      {
        "resource": { /* full K8s resource object */ },
        "relevanceScore": 0.97
      }
    ],
    "continue": "...",
    "estimatedTotalHits": 3
  }
}

Additional field filtering via CEL expressions:

spec.filters: e.g., "resource.spec.email.startsWith('alice@')"
spec.sort: { field: "spec.email", order: "asc" }

[drewr]

Love the simplicity of the design. It's coming together! 🐎

[scotwells]

And it's got a keyboard shortcut! Love it

[JoseSzycho]

Great, Under the SearchQuerySpec

search/pkg/apis/search/v1alpha1/types.go

Lines 38 to 57 in caea645

	type SearchQuerySpec struct {
	// Query is the search query string.
	//
	// +required
	Query string `json:"query"`
	// Limit sets the maximum number of results per page.
	// Default: 10, Maximum: 100.
	//
	// +optional
	Limit int32 `json:"limit,omitempty"`
	// Continue is the pagination cursor for fetching additional pages.
	//
	// Leave empty for the first page. If status.continue is non-empty after a query,
	// copy that value here in a new query with identical parameters to get the next page.
	//
	// +optional
	Continue string `json:"continue,omitempty"`
	}

I'm going to add a TargetResource, that will allow to scope the query to a specific resource type:

search/pkg/apis/search/v1alpha1/policy_types.go

Lines 62 to 77 in caea645

	type TargetResource struct {
	// Group is the API group of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Group string `json:"group"`
	// Version is the API version of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Version string `json:"version"`
	// Kind is the kind of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Kind string `json:"kind"`
	}

As for the sorting, that would require to make some changes into the ResourceIndexPolicy, as the sorting must be declared there and sync with the Meilisearch index.

In order to iterate faster, I will not add the sorting capability yet, and will create a Issue for tackling that in the future.

• Extend the existing search API request handlers to support result sorting #49