Trait Evaluation

Trait evaluation is the process by which SignalSmith computes trait values and materializes the results into your warehouse. This page covers the evaluation pipeline, scheduling, dependency resolution, materialization, and monitoring.

How Evaluation Works

When a trait is evaluated, SignalSmith performs the following steps:

SQL Generation — The trait definition (SQL query, aggregation config, or formula expression) is compiled into a warehouse-native SQL statement
Query Execution — The SQL is executed against your data warehouse through the configured warehouse connection
Materialization — Results are written to a dedicated trait table in your warehouse’s SignalSmith schema
Status Update — The trait’s evaluation status, row count, and timestamp are recorded

The entire pipeline runs warehouse-native. No data is extracted from your warehouse during evaluation — the SQL runs inside your warehouse, and results are written to a table within the same warehouse.

Materialization

Trait results are materialized into a trait table in your warehouse. The trait table is structured as:

Column	Description
`entity_key`	The entity identifier (e.g., `user_id`)
`trait_slug`	The slug of the trait being evaluated
`trait_value`	The computed value (stored as a variant/JSON type for type flexibility)
`evaluated_at`	Timestamp of when this value was computed

This table is maintained in the CDP_PLANNER schema (or equivalent, depending on your warehouse). SignalSmith creates and manages this schema automatically when you first connect a source.

During materialization, SignalSmith uses a full replace strategy for the given trait: all existing rows for that trait slug are replaced with the new results. This ensures the trait table always reflects the latest evaluation.

Scheduling

Each trait can be configured with an evaluation schedule:

Schedule	Description
Manual	Only evaluated when you explicitly trigger it from the UI or API
Hourly	Runs every hour at a fixed minute offset
Daily	Runs once per day at a configured time (UTC)
Weekly	Runs once per week on a configured day and time (UTC)
Custom Cron	Arbitrary cron expression for fine-grained control

Choosing a Schedule

Consider these factors when setting a schedule:

Data freshness — How often does the underlying source data change? There’s no point evaluating a trait hourly if the source table is only updated daily.
Warehouse cost — Each evaluation runs a SQL query against your warehouse. More frequent evaluation means more compute credits consumed.
Downstream dependencies — If an audience sync runs daily at 8 AM, the traits it depends on should be evaluated before that time.

Dependency Resolution

Traits can depend on other traits. The most common case is formula traits that reference other traits, but the dependency graph can also include traits that feed into audience definitions.

When multiple traits are scheduled for evaluation at the same time, SignalSmith resolves the dependency graph and evaluates them in topological order:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ total_revenue│     │ order_count  │     │ days_active  │
│ (SQL Trait)  │     │ (Agg Trait)  │     │ (SQL Trait)  │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       ▼                    ▼                    │
┌──────────────────────────────────┐             │
│ avg_order_value                  │             │
│ (Formula: total_revenue /       │             │
│          order_count)            │             │
└──────────────┬───────────────────┘             │
               │                                 │
               ▼                                 ▼
       ┌───────────────────────────────────────────┐
       │ engagement_score                          │
       │ (Formula: avg_order_value * 0.5 +         │
       │          days_active * 0.3)               │
       └───────────────────────────────────────────┘

In this example, total_revenue and order_count are evaluated first (they have no dependencies). Then avg_order_value is evaluated (it depends on both). Then engagement_score is evaluated last (it depends on avg_order_value and days_active).

Cascade Evaluation

When a trait is re-evaluated, all traits that depend on it are automatically queued for re-evaluation. This cascade follows the dependency graph. You can view the dependency chain for any trait on its detail page.

Circular Dependencies

SignalSmith prevents circular dependencies at creation time. If you attempt to create a formula trait that would form a cycle (e.g., A depends on B, B depends on A), the save operation fails with a validation error.

Evaluation Statuses

Each trait evaluation run has one of the following statuses:

Status	Description
Pending	The evaluation is scheduled but has not started yet
Running	The SQL query is currently executing against the warehouse
Completed	The evaluation finished successfully and results are materialized
Failed	The evaluation encountered an error (query error, permission issue, timeout, etc.)
Skipped	The evaluation was skipped because a dependency failed

Monitoring Evaluations

Trait Detail Page

Each trait’s detail page shows:

Last evaluated at — Timestamp of the most recent successful evaluation
Last evaluation status — Whether the last run succeeded or failed
Row count — Number of entity instances that received a value
Evaluation history — A log of recent evaluation runs with status, duration, and row counts

Evaluation Errors

When an evaluation fails, SignalSmith captures and displays:

Error message — The error returned by the warehouse (e.g., SQL syntax error, permission denied, table not found)
Failed SQL — The exact SQL that was executed, useful for debugging
Duration — How long the query ran before failing

Common failure causes:

Cause	Resolution
Table or column not found	The source table was renamed or dropped. Update the trait definition.
Permission denied	The warehouse credentials no longer have access. Check your warehouse configuration.
Query timeout	The query is too expensive. Optimize the SQL or increase your warehouse timeout.
Division by zero	A formula trait divided by a trait that returned zero. Add null/zero handling with `IF` or `COALESCE`.
Dependency failed	A trait this formula depends on failed to evaluate. Fix the upstream trait first.

Manual Evaluation

You can trigger an immediate evaluation for any trait:

From the UI — Click the Evaluate Now button on the trait detail page
From the API — POST /api/v1/traits/{id}/evaluate

Manual evaluation bypasses the schedule and runs the trait immediately. If the trait has dependencies, they are also evaluated first (if their current values are stale or missing).

Bulk Evaluation

When you need to re-evaluate all traits for an entity type (e.g., after a schema change or source migration), use Evaluate All from the entity type’s trait list page. This triggers evaluation for all traits in dependency order.

Performance Considerations

Query complexity — Complex SQL traits with many joins or large table scans will take longer and cost more. Monitor execution times in the evaluation history.
Materialization volume — Traits that produce millions of rows take longer to materialize. The pipeline uses batch inserts to manage this efficiently.
Concurrent evaluations — SignalSmith limits concurrent warehouse queries to avoid overwhelming your warehouse. Traits are queued and evaluated as capacity becomes available.
Warehouse sizing — If evaluations are consistently slow, consider scaling up your warehouse compute resources. SignalSmith respects your warehouse’s resource limits.

Next Steps

SQL Traits — Write custom SQL for trait computation
Aggregation Traits — Visual builder for common metrics
Formula Traits — Combine traits with expressions
Audiences — Use traits to build customer segments

Formula Traits Overview