# Dashboard Exact-Name Search

## Background and goal

The shared Dashboard search currently falls back to a cross-table fuzzy predicate over cluster and tenant names. Exact names should avoid that scan by using indexed equality lookups first, while retaining the existing fuzzy behavior for partial-name searches.

## Current behavior

- Numeric `query` values first probe cluster, parent, project, and external tenant IDs.
- Text `query` values otherwise use `c.name LIKE '%query%' OR o.name LIKE '%query%'`.
- `clusters.name` is `LONGTEXT` and previously had no index; the observed maximum stored value is 64 characters and 64 bytes.
- The Dashboard fuzzy-search policy can exclude high-cardinality organizations and fails closed when its snapshot is unavailable.

## Target contract

- Keep numeric ID lookup as the highest-priority search path.
- Before fuzzy search, probe exact cluster names and exact tenant names through separate indexed branches.
- Resolve exact tenant names to every matching internal organization ID, then query clusters through the existing `(org_id, created_at)` index.
- Use `UNION` to deduplicate rows that match both exact-name branches.
- If either exact-name branch matches, return only exact matches. Fall back to fuzzy search only when both miss.
- Consult the fuzzy-search policy only when the request actually reaches the fuzzy fallback. An available exact-name result must not depend on that policy snapshot.
- Preserve filters, stable pagination, `include_total`, and `has_more` behavior.

## Affected modules and routes

- Go module: repository root, `github.com/pingcap-inc/clinic`.
- Packages: `pkg/datasource` and `pkg/db`.
- Entrypoint: `cmd/server/main.go`.
- Routes: `/dashboard/clusters` and `/dashboard/clusters2` through their shared datasource.
- Schema: migration 95 adds the non-unique `idx_clusters_name_created_at` BTREE index on `(name(64), created_at)`.

Deployment chain: root module -> `cmd/server` -> `clinic` image -> Clinic CD `components=clinic` -> app-delivery `clinic-api` -> Clinic Deployment.

No deployment of Internal API, Task Manager, Uploader, Importer, Clinic Data Service, Cloud Server, NGM, or Kong is required. No app-delivery configuration change is required; staging and production only need the Clinic image bump.

## Implementation steps

1. Add the cluster-name prefix/created-at index to the schema and migration records.
2. Generalize the existing numeric equality UNION builder for numeric and exact-name branches.
3. Resolve tenant names with `organizations.name = ?` and combine that cluster branch with `clusters.name = ?`.
4. Bound each list branch before the outer stable sort and use one-row probes for `include_total=false` existence checks.
5. Move fuzzy-policy validation to the fuzzy fallback after numeric and exact-name misses.
6. Add focused SQL-shape, deduplication, pagination, existence, and policy-ordering regression tests.

## Exclusions and compatibility

- Do not split the UI search box in this change.
- Do not add `cluster_name`, `org_name`, or `org_id` request parameters.
- Do not remove or change the shared `query` parameter.
- Do not add a cache or change total-count semantics.
- Cluster names are not globally unique; exact results may contain matching clusters from multiple organizations, as the existing global search contract permits.

## Test plan

- `go test ./pkg/datasource ./pkg/api/cloud ./pkg/db -count=1`
- `go vet ./pkg/datasource ./pkg/api/cloud ./pkg/db`
- Verify generated exact-name SQL uses the intended indexes, separate bounded branches, parameterized values, `UNION` deduplication, and stable outer ordering.
- Verify an unavailable fuzzy-policy snapshot does not block a successful exact-name lookup, but still fails closed after an exact miss.

## Staging verification and release boundary

- Deploy the final feature-branch Clinic image to staging with Clinic CD using `environment=staging` and `components=clinic`.
- Confirm migration 95 and the expected image, then verify exact cluster name, exact tenant name, and exact-miss fallback behavior on `/dashboard/clusters2`.
- Check the Clinic workload readiness/restarts when approved staging EKS access is available; use API evidence when it is not.
- The source PR still requires normal CI and review plus explicit user authorization before merge.
- Production requires a separate Clinic CD `prod-cloud` release and explicit authorization to merge its generated app-delivery PR.