yau-plant-assistant/cube/model/equipment.yml

# =============================================================================
# equipment.yml — alias resolution at equipment and tag level.
#
# SOURCE: pg-ai public.equipment and public.tags. These live in pg-ai whatever
# happens to imh, so this file does not change at Phase 4.
#
# WHY IT IS IN CUBE AT ALL: so that a question about "Pump 02" can be answered
# without the caller knowing that its data is on PS_PU302_RUNNING,
# PS_PU302_TRIPPED and PS_PU302_RUN_HOURS. Without equipment-level joins every
# equipment question fails, because no historian point is called "Pump 02".
#
# Alias matching itself is done in the API (api/tools/equipment.py) against the
# GIN-indexed alias arrays, not here - Cube is the aggregation layer, not the
# entity resolver. What Cube provides is the join, so that once the API has
# resolved "Pump 02" to PU-302 the measures in the other cubes can be filtered
# by equipment rather than by a list of tags the model would have to hardcode.
# =============================================================================

cubes:
  - name: equipment
    sql: >
      SELECT
        equipment_id,
        display_name,
        equipment_type,
        unit_name,
        description,
        array_to_string(aliases, ' | ') AS alias_list
      FROM public.equipment
    description: >
      Plant equipment at the Waterloo Road Pump Station - the station itself,
      the wet well, three pumps, the discharge manifold, the spill weir and the
      switchboard.

    dimensions:
      - name: equipment_id
        sql: equipment_id
        type: string
        primary_key: true
        description: Canonical identifier - PU-302, WW-101, STN-001.

      - name: display_name
        sql: display_name
        type: string
        description: What to call it in an answer - "Pump 02", not "PU-302".

      - name: equipment_type
        sql: equipment_type
        type: string

      - name: unit_name
        sql: unit_name
        type: string

      - name: alias_list
        sql: alias_list
        type: string
        description: >
          Pipe-separated aliases, for display and debugging. Resolution happens
          in the API against the array column with a GIN index; this string is
          for showing an operator why "pump2" was understood as PU-302.

      - name: description
        sql: description
        type: string

    measures:
      - name: count
        type: count

  - name: tags
    sql_table: public.tags
    description: >
      Historian points and field instruments, their units, ranges and
      setpoints. Read the description column before interpreting any value -
      it records the historian-versus-PLC unit conversion and, critically,
      whether the tag is historised at all.

    joins:
      - name: equipment
        sql: "{CUBE}.equipment_id = {equipment}.equipment_id"
        relationship: many_to_one

    dimensions:
      - name: tag_id
        sql: tag_id
        type: string
        primary_key: true

      - name: equipment_id
        sql: equipment_id
        type: string

      - name: display_name
        sql: display_name
        type: string

      - name: signal_type
        sql: signal_type
        type: string
        description: level, flow, pressure, vibration, status, state, speed, hours.

      - name: engineering_unit
        sql: engineering_unit
        type: string
        description: >
          The unit the HISTORIAN stores, which is not always the unit the PLC
          works in. Wet well level is historised as percent of the spill weir
          crest (raw mm / 60). Always report the unit with the number.

      - name: range_low
        sql: range_low
        type: number

      - name: range_high
        sql: range_high
        type: number

      - name: alarm_setpoint_hi
        sql: alarm_setpoint_hi
        type: number
        description: >
          The configured alarm setpoint at the time this reference data was
          loaded. Setpoints are writable from SCADA - if a question compares
          two periods, check PS_STN_HIGH_LEVEL_ALARM_SP for a change before
          attributing a difference in alarm counts to the process.

      - name: alarm_setpoint_lo
        sql: alarm_setpoint_lo
        type: number

      - name: trip_setpoint
        sql: trip_setpoint
        type: number

      - name: description
        sql: description
        type: string

    measures:
      - name: count
        type: count

views:
  - name: equipment_reference
    description: >
      Equipment joined to its tags - the lookup behind "what does the PVHI
      alarm on the wet well mean" and "which pump is PU-302".
    cubes:
      - join_path: tags
        includes:
          - tag_id
          - display_name
          - signal_type
          - engineering_unit
          - range_low
          - range_high
          - alarm_setpoint_hi
          - alarm_setpoint_lo
          - trip_setpoint
          - description
      - join_path: tags.equipment
        prefix: true
        includes:
          - equipment_id
          - display_name
          - equipment_type
          - alias_list