Topic Browser GraphQL API

Early Access. The GraphQL API lets developers query the Unified Namespace programmatically. It's experimental and off by default. To turn it on, set agent.graphql.enabled: true in the agent: block of your umh-core instance configuration. See Configuration for all options. Tell us what you think.

Overview

Query Unified Namespace topics and metadata in real-time.

• Endpoint: http://localhost:8090/graphql

• Default: Disabled; opt in with agent.graphql.enabled: true

• Authentication: None (open by default)

Schema

Queries

type Query {
  topics(filter: TopicFilter, limit: Int): [Topic!]!
  topic(topic: String!): Topic
}

Types

type Topic {
  topic: String!
  metadata: [MetadataEntry!]!
  lastEvent: Event    # Latest event only
}

union Event = TimeSeriesEvent | RelationalEvent

type TimeSeriesEvent {
  producedAt: String!
  scalarType: String!
  numericValue: Float
  stringValue: String
  booleanValue: Boolean
}

type RelationalEvent {
  producedAt: String!
  json: String!
}

input TopicFilter {
  text: String
  meta: [MetaExpr!]
}

input MetaExpr {
  key: String!
  eq: String!
}

Example Queries

All topics:

{ topics { topic metadata { key value } } }

Filter by text:

{ topics(filter: { text: "temperature" }) { topic } }

Filter by metadata:

{
  topics(filter: { 
    meta: [{ key: "data_contract", eq: "_pump" }] 
  }) {
    topic
    lastEvent {
      ... on TimeSeriesEvent {
        producedAt
        numericValue
      }
    }
  }
}

Single topic:

{
  topic(topic: "umh.v1.acme.plant1.line4.sensor1._raw.temperature") {
    metadata { key value }
    lastEvent {
      ... on TimeSeriesEvent {
        producedAt
        numericValue
        scalarType
      }
    }
  }
}

Using curl

Basic query:

curl -X POST http://localhost:8090/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ topics(limit: 3) { topic } }"}'

Filter query:

curl -X POST http://localhost:8090/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ topics(filter: { text: \"pump\" }) { topic lastEvent { ... on TimeSeriesEvent { numericValue } } } }"}'

Limitations

• History: Latest event only (no historical data)

• Subscriptions: Not supported (queries only)

• Rate Limiting: None (use responsibly)

• Scope: Single UMH instance only

Multi-Instance Behavior

• Each UMH Core instance has its own Topic Browser

• GraphQL API returns topics from local instance only

• Management Console aggregates all instances into unified view

Configuration

agent:
  graphql:
    enabled: false   # Default: false; set true to opt in
    port: 8090      # Default: 8090
    debug: false    # Set true for GraphiQL UI
    corsOrigins: [] # Default: allows all origins

Security

• Authentication: Currently open (no tokens required)

• CORS: Configurable via corsOrigins setting

• Network Security: Recommended for production deployments

• Port Access: Ensure port 8090 is appropriately secured