Skip to main content

Querying and search

Vox makes query behavior explicit in the entity model. A property is filterable, sortable or searchable only when the model says it is, and the same metadata drives storage, the API, permissions and generic clients.

Query fields​

[VoxFilterable] creates an indexed field for equality and range filters. It supports scalar values and collections of strings, numbers, booleans, dates, GUIDs and enums, including values inside nested objects or collections.

[VoxSortable] makes a scalar value available for ordering. [VoxSearchable] sends strings and rich text to the full-text index:

public class Product : IVoxEntity
{
    [VoxFilterable]
    [VoxSortable]
    public required string Sku { get; set; }

    [VoxSearchable]
    public VoxVarying<Language, string> Name { get; set; } = new();

    [VoxFilterable]
    public List<string> Tags { get; set; } = [];
}

The same capabilities can be attached to permanent data-defined fields. Consumers therefore discover what is queryable from the model instead of maintaining a separate list of database columns.

Filters, sorting and paging​

Filters support equality and the usual greater-than and less-than comparisons. They can be combined with AND, OR and NOT in application code. The HTTP API expresses common filters through query parameters, for example:

GET /api/products?tags=coffee&price[lt]=100&sort=-updatedAtUtc,sku&skip=0&take=50

A collection matches when it contains a matching value. Reference properties are queried by their referenced IDs, so relations participate without loading the target entities. Property paths such as pim.categories and variants.sizes address fields inside owned structures.

Vox applies a stable created-time and ID order after explicit sorts. That makes offset paging deterministic even when several entities have the same sort value. A query can request the total matching count when a client needs page controls.

Context-aware queries​

For a varying property, a filter or sort can name a stored context explicitly or use the contexts selected for the request. This lets the same product query sort by the Swedish product name in one request and the English name in another.

Context membership also constrains which entities belong in a selected market, channel or other dimension. Read permissions are applied before counting and paging, including :My ownership and allowed context scopes, so a client cannot infer inaccessible entities from totals.

Queries can select published, draft or release content. Editors can additionally filter by draft state, such as changed, scheduled, conflicting or failed publication.

Full-text search​

Full-text search is separate from structured filtering. Every complete search term must occur in the searchable document, while the final term is treated as a prefix. A query for coffee mu can therefore match “Coffee mug.” Rich text is indexed as visible text rather than HTML.

Search results contain relevance scores and plain-text highlight ranges. Supplying an explicit sort replaces relevance ordering. Structured filters, contexts, content modes, relation expansion and authorization continue to apply to search results.

Consistency​

Search indexing is durable and asynchronous. Vox records pending index work in the same transaction as an entity change, so an unavailable search engine delays visibility but does not lose the update.

The dependency graph decides which derived results became stale, while the search outbox makes every resulting document update durable. An early entity version may be indexed before its calculations settle; later calculated versions are indexed again, and version checks prevent stale work from replacing a newer document. See Dependency and change tracking.

Most entity types can use eventual consistency. A type that must appear in search immediately after an action can use read-after-write consistency; its action waits for indexing and reports separately if the entity was saved but could not yet be made searchable. Published and draft content are indexed independently so editorial search does not leak draft values into public results.

See API overview, Languages, markets and channels and Users, roles and permissions.