Docs are not available for mobile use. Please use a desktop computer to view the documentation.

Signals

Signal definitions, configuration, and metadata

Purpose

The signals table defines the various data signals that users can track. Each signal represents a specific type of measurement or data point from a source, with its own configuration, visualization settings, and synchronization schedule.

Schema Definition

Field	Type	Description	Constraints
`id`	uuid	Unique signal identifier	Primary key, auto-generated
`userId`	uuid	Signal owner	Foreign key to users.id
`sourceName`	varchar	Source providing this signal	Foreign key to sources.name
`signalName`	varchar	Internal signal name	Not null
`displayName`	varchar	Human-readable signal name	Not null
`unit`	varchar	Measurement unit	Not null
`archetype`	varchar	Signal archetype	Must be: ambient, episodic, semantic
`status`	varchar	Signal setup status	Default: ‘pending_setup’
`syncSchedule`	varchar	Cron sync schedule	Optional
`fidelityScore`	real	Data quality score (0-1)	Not null
`description`	varchar	Signal description	Optional
`visualizationType`	varchar	How to display the signal	Default: ‘continuous’
`lastSuccessfulIngestionAt`	timestamptz	Last successful data sync	Optional
`syncToken`	varchar	Sync state token	Optional
`settings`	json	Signal-specific settings	Optional
`createdAt`	timestamptz	Signal creation timestamp	Auto-generated
`updatedAt`	timestamptz	Last update timestamp	Auto-updated

Relationships

Referenced by:

ambient_signals.signalId - Ambient data points for this signal
episodic_signals.signalId - Episodic events for this signal
ingestion_runs.signalId - Data ingestion history

References:

users.id via userId - Signal owner (cascade delete)
sources.name via sourceName - Data source (restrict delete)

Indexes

signals_user_id_idx - B-tree index on userId for user queries
signals_source_name_idx - B-tree index on sourceName for source queries
signals_signal_name_idx - B-tree index on signalName for name lookups

Constraints

signals_fidelity_score_check - Fidelity score must be between 0.0 and 1.0
signals_archetype_check - Archetype must be ‘ambient’, ‘episodic’, or ‘semantic’
signals_visualization_type_check - Must be ‘continuous’, ‘binary’, ‘categorical’, ‘spatial’, or ‘episodic’
unique_signal_per_user - Each user can only have one signal with a given signalName

Usage Examples

Find all signals for a user

SELECT signalName, displayName, archetype, status
FROM signals 
WHERE userId = 'user-uuid'
ORDER BY displayName;

Get signals needing sync

SELECT id, signalName, syncSchedule, lastSuccessfulIngestionAt
FROM signals 
WHERE status = 'active' 
  AND syncSchedule IS NOT NULL
  AND (lastSuccessfulIngestionAt IS NULL 
       OR lastSuccessfulIngestionAt < NOW() - INTERVAL '1 hour');

Find signals by archetype

SELECT signalName, displayName, unit, fidelityScore
FROM signals 
WHERE userId = 'user-uuid' 
  AND archetype = 'ambient'
  AND status = 'active';

Update signal sync status

UPDATE signals 
SET lastSuccessfulIngestionAt = NOW(), 
    status = 'active',
    updatedAt = NOW()
WHERE id = 'signal-uuid';

Get signal visualization settings

SELECT signalName, displayName, visualizationType, settings
FROM signals 
WHERE userId = 'user-uuid' 
  AND visualizationType IN ('spatial', 'episodic');