Querying Aspected: A Code Tutorial with Multi-Aspect Searches

How to query the Aspected Database across text, metadata, and contextual dimensions.

TL;DR

Most vector search tutorials start the same way: turn text into a vector, look for nearby vectors, and return the closest matches. That works when relevance is mostly about semantic similarity. In enterprise search, though, text is rarely the whole story. A useful result is not always just the closest text match. It might also need to be recent, have the right file type, or be visible to the right user group.

This is the kind of retrieval the Aspected Database is built for. Instead of treating metadata as filters around a text embedding, it allows documents and queries to be represented through multiple aspects. For example, one aspect can represent the document text, while others represent fields such as file type, domain, or access scope.

This article walks through a simplified developer example: creating a multi-aspect index, ingesting structured documents through aspect resolvers, and running a query that combines semantic similarity with contextual relevance.

Why Multi-Aspect Queries Matter

One vector can represent everything that matters for retrieval. That is the assumption that a typical vector search has. The traditional flow is simple: embed the query, search the vector index, and return the nearest documents. But is this really enough?

In enterprise systems, that assumption often breaks down. A user may want documents similar to a report, but only if they are recent, belong to a certain content type, or match a specific operational context. In most vector search stacks, these signals end up outside the main search step, handled with filters, reranking, or application code.

The Aspected Database uses a different model. It supports sparse-like vector queries, where some dimensions of the search vector may be left undefined. This means a query can include the aspects that matter for a specific search and ignore the ones that do not. Context becomes part of the retrieval representation instead of being applied only before or after search.

Example Scenario

Imagine a corporate knowledge system storing internal documents. Let’s suppose that each document has a textual description, a file type, a business domain, and access metadata. Then, a user opens a financial risk report and wants to find related documents that match both the content of the report and the surrounding context.

The actual intent is not just:

“Find semantically similar documents.”

It is closer to:

“Find documents similar to this financial risk report, preferably in the finance domain, and prioritize reports over other file types.”

In a traditional setup, this might require a semantic search, a date filter, a file-type filter, and possibly a reranking step. With a multi-aspect index, the same intent can be represented more directly and unified.

For this tutorial, we will use three aspects that map to a simple enterprise document scenario:

• description: the text aspect, representing the semantic content of the document.

• file_type: an enum aspect, representing the document type.

• domain: an enum aspect, representing the business area or topic domain.

The examples below use the Aspected REST API directly, translated into Python with requests. The documents are simplified so the API flow is easy to read.

Creating a Multi-Aspect Index

The API allows to create an index with multiple aspects. Each aspect describes part of the representation that can participate in retrieval, like is normally done with text content.

This example keeps the schema small so the tutorial is easy to follow. The important part is the shape of the index: instead of defining one field for everything, we define separate aspects that represent different dimensions of relevance.

Ingesting Documents through Aspected Resolvers

Once the index exists, documents can be inserted as structured rows. The configured resolvers extract the fields defined by each aspect and convert them into the stored representation. A real ingestion pipeline would parse the document, compute a text embedding, normalize metadata fields, and map categorical values such as file type into vectors.

Here is a simplified example of one document:

What matters here is that the document is not represented only by its textual description. Its file type and domain are also part of the retrieval representation.

That changes what the system can search for. A future query can now compare documents not only by meaning, but also by contextual alignment

Running a Multi-Aspect Query

Now suppose the user wants reports related to financial risk, within the finance domain, and preferably of the same file type. The query can include all three aspects:

This query is more expressive than a standard text-only vector search. It does not just say “find similar content.” It also says that the document type and business domain matter for this retrieval task.

In a traditional system, the text embedding would go to the vector database, while fields such as file type or domain would likely become filters or reranking features.

Leaving Aspects Undefined

At the same time, not every query needs every aspect. A user may only provide text, while the application may know the domain but not the file type, or the file type may simply be irrelevant for that search.

This is different from forcing a default value or applying a hard filter. The search can operate over the aspects that are actually present in the query, while leaving other parts of the representation undefined. That is useful in enterprise applications, where user intent is often incomplete and context may come from different sources, such as the query, the current workflow, or application state.

When Context Should Be a Filter

Multi-aspect retrieval does not mean every condition should become part of similarity. Some constraints define eligibility, not relevance.

Access control is the clearest example. If a user is not allowed to see a document, the document should not appear in the results, even if it is semantically close. That is why the search request can still include an accessFilter.

This distinction is important. Contextual signals such as recency, document type, or domain often influence relevance. Security permissions, tenant boundaries, or hard access rules define whether a document can be returned at all. A good retrieval architecture needs both.

A Note on Aspect Weighting

Different searches may care about aspects differently. A “related documents” search may care mostly about semantic content, while a compliance-oriented search may give more importance to document type, classification, validity, or ownership.

In the API structure shown here, aspect weighting is expressed through the multiplier setting in the aspect configuration. This is defined when the index is created, not as an ad-hoc parameter on each search request. In other words, weighting is part of how the index is designed and trained, rather than something that is tuned independently for every query.

For example, an index can give more influence to file_type than to description by configuring different multipliers:

The main idea is simple: metadata does not always have to behave like a binary include-or-exclude condition. In many retrieval tasks, it is better modeled as a signal that influences ranking.

Why this Changes the Developer Experience

The biggest change for developers is that retrieval intent becomes easier to express. Instead of building a pipeline where semantic search, filters, rerankers, and custom scoring all compete with each other, the query can represent multiple dimensions of relevance in a direct and simultaneous way.

This approach does not remove the need for good data preparation. Documents still need to be parsed, embedded, normalized, and mapped into aspects. But once that representation exists, searches become cleaner. A developer can express “similar content, close in time, same document type” as a multi-aspect query instead of coordinating several separate retrieval stages.

It also makes the system easier to reason about. When results are unexpected, the question becomes which aspect contributed to the match, rather than which filter or reranker changed the result downstream.

Conclusion

Most retrieval systems start with a single embedding and then add filters around it. That approach works, but it becomes limiting when relevance depends on several dimensions at once.

The Aspected Database provides a different way to model retrieval. By representing documents and queries across multiple aspects, it allows content and context to contribute to similarity together. Some aspects can be included, others can be left undefined, and strict constraints such as access control can remain filters.

For developers building enterprise search, RAG systems, or AI assistants, the shift is simple: retrieval no longer has to mean “semantic search first, context later.” It can become a query over a richer representation.

Team @ Aspected