Custom Models

How Prelude Collector represents collected data — fields, mappings, and the lifecycle of a model from creation to active subscription.

A data model is the schema that tells Prelude Collector what to collect and how to represent it. After this first mention, the rest of this section refers to Prelude Collector as "the collector". Every model defines a set of typed fields and one or more protocol mappings that translate raw protocol output into those fields.

You create models at runtime through the REST API or the web UI. The collector ships with a small starter catalogue, but those starter models are imported into the database on first startup and are edited, replaced, or deleted from there on like any other model — so in practice every model in your fleet is a custom model.

For the short definition of "model" in context with the other moving parts, see the Glossary.

What a model contains

Conceptually, a model is two ordered lists:

Model
├── Fields     (the typed columns of the output)
└── Mappings   (one per protocol + NetOS + version range)
    ├── Protocol paths   (gNMI paths, SNMP OIDs, NETCONF filters, CLI commands)
    ├── Field mappings   (raw source key → target field)
    ├── Transforms       (field transforms, value transforms, ignore values)
    └── Key field        (the field used as the unique row identifier)

When you bind a model to a device through a Subscription, the collection engine picks the single best-matching mapping for the device's reported NetOS and firmware version, and uses it to drive collection.

NetOS and version matching

Each mapping is bound to a network operating system value such as ios-xr. A model can carry multiple mappings — one per NetOS, and within the same NetOS one per version range. At collection time the engine selects, per protocol, the mapping whose version constraints have the highest specificity that still matches the device. If two equally-specific mappings match, both are skipped and an error is recorded.

The supported protocols are:

Protocol	Style
`gnmi`	Streaming subscription
`snmp`	Walk or scalar GET
`cli`	SSH plus a TTP template
`netconf`	XML subtree filter

For protocol-specific connection settings, see Collection protocols.

Completeness status

The API and UI report a completeness_status for each model:

Status	Meaning
`empty`	No fields and no mappings yet.
`incomplete`	Has fields but no mappings, or mappings but no fields.
`partial`	Both exist, but at least one mapping is missing a key field or paths.
`ready`	At least one field and one fully configured mapping.

Only ready models produce data. The web UI lets you create subscriptions against any model, but a subscription bound to a non-ready model stays in an error state and emits no rows until the missing fields, mappings, key field, or paths are filled in. Saving a change that brings the model to ready clears the error on the next reload (~500 ms), without recreating the subscription.

How collection uses a model

When a Subscription becomes active, the engine does the following on every poll cycle:

Resolve the mapping for the device's current NetOS and version.
Run the protocol client against the configured paths or OIDs.
Pass each raw update through the model's parser, which applies field mappings, transforms, type coercion, and format validation.
Emit a Snapshot containing one row per unique key field value.

The full mapping mechanics — field mappings, transform pipelines, ignore lists — are documented in Fields & Mappings.

Reference pages in this section

Fields & Mappings — schema and mapping rules in detail, with a complete JSON example.
Workflow — end-to-end API workflow to create, test, and subscribe to a model.

For request and response schemas of every endpoint mentioned in this section, see the API reference.