SapienStream

Semantic Tags

Semantic Tags provide domain-aware abstractions over raw machine data, enabling higher-level operational insights through structured tag classification and validation.

What are Semantic Tags?

Domain Abstractions

Semantic Tags represent meaningful operational concepts rather than raw sensor data. They provide context and validation for industrial measurements.

  • • Transform raw tags into operational metrics
  • • Apply validation rules and limits
  • • Classify by semantic type and criticality
  • • Enable domain-specific queries

Real Implementation

Raw TagSemantic Tag
pump_01_temp_celsius
↓
"Pump Temperature" (Analog, High Criticality)

Semantic Types

Analog
Continuous numerical measurements with validation ranges
Examples:Temperature, Pressure, Flow Rate
Validation:Min/Max limits, Rate of change
{
  "semantic_type": "ANALOG",
  "validation_rules": {
    "min_value": 0,
    "max_value": 150,
    "max_rate_change": 5.0
  }
}
Digital
Binary states representing equipment status or conditions
Examples:Motor Running, Valve Open, Alarm Active
Validation:Boolean values, State transitions
{
  "semantic_type": "DIGITAL",
  "validation_rules": {
    "valid_states": [true, false],
    "state_labels": {
      "true": "Running",
      "false": "Stopped"
    }
  }
}
State
Enumerated values representing specific operational modes
Examples:Auto/Manual Mode, Production Phase
Validation:Allowed state values, Transitions
{
  "semantic_type": "STATE",
  "validation_rules": {
    "allowed_states": [
      "auto", "manual", "maintenance"
    ],
    "default_state": "manual"
  }
}
Counter
Accumulating values that increment over time
Examples:Production Count, Runtime Hours, Cycle Count
Validation:Monotonic increase, Reset detection
{
  "semantic_type": "COUNTER",
  "validation_rules": {
    "min_value": 0,
    "reset_threshold": 0.9,
    "monotonic": true
  }
}

Criticality Levels

LOW

Informational

Nice-to-know data, no immediate action required

MEDIUM

Monitoring

Important for operations, trend monitoring

HIGH

Operational

Critical for normal operations

CRITICAL

Safety

Safety-critical, immediate attention

API Usage

Creating Semantic Tags
Transform raw machine tags into semantic abstractions
# Create an analog semantic tag for temperature monitoring
curl -X POST "https://sapienstream.com/api/semantic-tags/machine_001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pump Temperature",
    "description": "Main pump bearing temperature monitoring",
    "semantic_type": "ANALOG",
    "criticality_level": "HIGH",
    "source_tag_name": "pump_01_temp_celsius",
    "validation_rules": {
      "min_value": 0,
      "max_value": 120,
      "warning_threshold": 80,
      "alarm_threshold": 100
    },
    "unit": "°C"
  }'
Querying by Semantic Type
Filter and search semantic tags by operational characteristics
# Get all high-criticality analog tags
curl -X GET "https://sapienstream.com/api/semantic-tags/machine_001?semantic_type=ANALOG&criticality_level=HIGH" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get all counter-type tags for production monitoring
curl -X GET "https://sapienstream.com/api/semantic-tags/machine_001?semantic_type=COUNTER" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Search by semantic meaning
curl -X GET "https://sapienstream.com/api/semantic-tags/machine_001?search=temperature" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Benefits

Data Organization
  • • Structured classification by operational meaning
  • • Criticality-based prioritization
  • • Validation rules for data quality
  • • Semantic search capabilities
Operational Value
  • • Domain-specific monitoring dashboards
  • • Alarm prioritization by criticality
  • • Maintenance scheduling by tag type
  • • Compliance reporting by categories
Current Implementation
Semantic Tags are domain abstractions, not AI-powered analysis
  • • Manual classification and rule definition
  • • Static validation rules (no adaptive learning)
  • • Basic semantic types (no custom extensions)
  • • Simple criticality levels (no dynamic scoring)
  • • No automated pattern recognition or anomaly detection