Resolvers

Resolvers are the mechanism Aspected uses to convert structured data into numeric embedding vectors. When you create an index, you define a schema — a list of aspects — and each aspect is powered by a resolver.

Every aspect has four properties:

Property	Description
name	A unique name for this aspect within the index.
type	The resolver type to use (enum, text, number, datetime, or raw).
path	A JSONPath expression that extracts the value from a training document.
settings	A resolver-specific settings object (see the sections below).

During training, each document is passed through every aspect's resolver. The resolver uses the path to extract a value from the document, converts it to a fixed-length float vector, and the resulting vectors are concatenated to form the full composite vector stored in the index.

During search, you supply a query containing values for any subset of aspects. Dimensions for aspects you omit are left undefined (sparse), so only the aspects you specify contribute to the similarity calculation.

Available Resolvers

Resolver	Input type	Description
Enum	string	Maps a categorical value to a radial embedding.
Text	string	Generates a semantic embedding using a GGUF model.
Number	number	Maps a numeric value within a range to a radial embedding.
DateTime	string	Maps a date/time string to a radial embedding.
Raw	array of numbers	Pass-through for pre-computed embedding vectors.

JSONPath Expressions

The path property on each aspect uses a JSONPath expression to extract a value from a training document. This allows you to use nested or complex document structures.

Examples

Given the following training document:

{
  "id": "item-1",
  "doc": {
    "name": "Widget",
    "category": "tools",
    "details": {
      "description": "A handy widget for everyday use"
    }
  }
}

Path	Extracted value
$.category	"tools"
$.details.description	"A handy widget for everyday use"
$.name	"Widget"

Combining Resolvers

An index can use multiple aspects with different resolver types. For example, you might combine an enum aspect for categorical filtering, a text aspect for semantic search, and a number aspect for price similarity:

{
  "idSize": 36,
  "aspects": [
    {
      "name": "category",
      "type": "enum",
      "path": "$.category",
      "settings": {
        "values": [
          "electronics",
          "clothing",
          "food",
          "tools"
        ]
      }
    },
    {
      "name": "description",
      "type": "text",
      "path": "$.description",
      "settings": {
        "model": "nomic-embed-text-v1.5.f16.gguf"
      }
    },
    {
      "name": "price",
      "type": "number",
      "path": "$.price",
      "settings": {
        "min": 0.0,
        "max": 500.0
      }
    }
  ]
}

When searching, you can query with any combination of aspects:

{
  "k": 5,
  "query": {
    "category": "electronics"
  }
}

This searches only on the category aspect — all other dimensions are ignored.

{
  "k": 5,
  "query": {
    "description": "a durable outdoor tool"
  }
}

This searches only on the description aspect — the enum and number dimensions are ignored.

{
  "k": 5,
  "query": {
    "category": "tools",
    "description": "a durable outdoor tool"
  }
}

This searches on both aspects simultaneously.