View Experiences

A View Experience is a named, reusable configuration for finding content in a Vertesia project. Instead of building search UI and writing Elasticsearch queries by hand, you describe what users should be able to browse and search — the content scope, the facets, the search behavior, and the result layouts — and Vertesia renders and executes it for you.

Persist a View once, then open it through the generic /view/<id> route or embed it in an application with the ViewExperience React component.

Anatomy of a View

Every View Experience is four parts. Most of the documentation is organized around them:

View Experience
├── scope        which content the View covers — content types, locations, collections, a fixed filter
├── navigation   how users narrow down — property facets, hierarchies, ranges, collections, location
├── search       how users search — deterministic (keywords + key terms) or agentic (natural language)
└── results      how matches are shown — list, table, cards, gallery, or board displays, plus sorting

A View author configures these four sections; the runtime turns them into a secure Elasticsearch query and a normalized result set that the reusable UI renders.

How a View runs, end to end

   AUTHOR                        PERSIST                     EXECUTE                    RENDER
 ┌──────────┐   client.views   ┌───────────────┐  resolve  ┌──────────┐   execute()   ┌──────────┐
 │  Studio  │ ───────────────▶ │ studio-server │ ────────▶ │   Zeno   │ ────────────▶ │   your   │
 │  editor  │   create/update  │   (MongoDB)   │  by id    │   (ES)   │  /view/:id or │   app    │
 │ + Agent  │   or an app's    │   versioned   │           │  secure  │  ViewExperience│   UI     │
 └──────────┘   in-code View   └───────────────┘           └──────────┘               └──────────┘

1. Authoring happens in the Studio editor (with help from Studio Assistant), or an application ships a View in code. See Configuration.
2. Persistence is owned by studio-server: project-scoped, separately revisioned View resources under /api/v1/views. The platform includes read-only sys:* Views, and apps can contribute in-code definitions that resolve as app:<app-name>:<view-id>.
3. Execution is owned by Zeno at POST /api/v1/view-executions/:id/execute. It loads the authoritative configuration, composes the query, and returns normalized results.
4. Rendering uses the generic /view/<id> route or the ViewExperience component. See Embedding in applications.

The client only ever sends user-controlled state — the text query, selected facets, chosen display, sort, and page. It never sends a raw Elasticsearch request.

Security model

View execution is safe to expose to end users because the server, not the client or the model, owns the dangerous parts of the query:

• The View's scope (content types, locations, collections, fixed filter) and the caller's content-security and project filters are always composed on the server, outside anything a user or an agent supplied.
• Agentic search asks a model to produce a query, but the result is checked against a validated allowlist of query types and fields before the immutable scope and security filters are added around it.
• Only head revisions are searched by default, and callers can only select authored sort options — never arbitrary Elasticsearch sort clauses.
• Generated Elasticsearch DSL and security filters are never placed in the URL. Execution diagnostics may expose the validated model-authored query subtree, but never the server-owned scope or content-security filters.

When to use a View

Use a View Experience when you want a reusable, shareable, permission-aware way to browse and search project content — an internal document library, an operational worklist, a customer-facing search page, or an agent-authored browsing surface. Prefer a direct content search call when you need a one-off query with no reusable UI, and a collection when you only need to group a fixed set of objects without search or navigation.

In this section

• Quickstart — create your first View in three steps.
• Configuration — scope, navigation, search, and result displays in depth, with a complete example.
• Search & agentic planning — deterministic versus natural-language search, and the typed-indexing prerequisite for numeric and date facets.
• Embedding in applications — the route, the ViewExperience component, deep links, custom renderers, and in-code (app-contributed) Views.
• API & validation reference — REST endpoints, draft preview, permissions, and configuration validation.
• Troubleshooting — common problems and how to fix them.