UNS OpenHubDocumentation

Data Catalog

Try a Data Catalog offer over demo history

Install the public uns-hrm-catalog-demo and use one furnace temperature through JSON preview, CSV and Parquet operations. The offer describes a reusable API; the service performs the query.

Applies to
Compatible Runtime containing Controller 2.2.31 · Catalog demo 0.1.4 · locally reviewed 24 October 2026
Guide version
1.1

Worked example

Example: one measurement, three representations

The public 0.1.4 demo reads forge-group/novasteel/hot-rolling/hrm-pusher-furnace/equipment/zone-1/temperature and returns time, temperatureC and uom.

JSON preview At most 500 rows + hasMore

Use the flag to distinguish a preview from the full result.

CSV / Parquet Incremental file preparation

Seven-day range, 128 MiB file and two concurrent preparations bound this demo.

Caller access The caller’s authorized history

The service does not widen access through its machine token.

Procedure

Follow the task in order

  1. 1
    Prepare a source with archived valuesRun rtt-demo-app, Archiver and API Global for the configured furnace topic. Confirm that Explore can read a window with actual measurements before trying this offer. Review the demo provider namespace in Asset identity before approving it; the example does not automatically approve a source. Use the device-to-data guide if this is your first local data source.
  2. 2
    Install from the official signed catalogOpen Micro services → Deploy new service, choose uns-hrm-catalog-demo · uns-openhub-public in Service package, then v0.1.4 in Version. This is the official signed catalog entry. Install the version on the controller that will run it. A custom repository source is not required for this official entry. If it is absent, check the official source, catalog verification and compatibility in the existing repository/catalog settings rather than bypassing the signature. Install/create a normal instance and leave it stopped until its configuration is saved.
  3. 3
    Configure the stopped instanceOpen Configure and choose config-development-podman.json for the standard Runtime container layout. Its uns.graphql and uns.rest point to localhost:3200, its JWKS URL is http://localhost:3200/api/.well-known/jwks.json, and infra.host is mosquitto. These addresses are resolved by the service inside the controller Runtime, not by your browser or desktop. If your Controller or broker uses a different layout, review its reachable address, MQTT port, authentication and TLS settings. Keep credentials outside source control. Controller-managed instances receive normal routing metadata; do not copy a direct-development .env file into them.
  4. 4
    Save and start the instanceSave the configuration, close the editor and confirm the instance row shows it as configured. Start that instance and wait for the registered offer to become available. If saving reports an error, resolve it before starting. Use the existing Refresh and instance Log/diagnostics when the displayed state or registration has not updated; a process being started alone does not prove that the offer is ready.
  5. 5
    Open the registered offerOpen Data Catalog → Novasteel furnace zone 1 temperature. Review the description, required parameters, response schema and three operations. If it is missing, check the instance, service registration, current availability and caller permissions. The caller needs access to the configured furnace source; a machine identity must not be used to widen that caller’s read access.
  6. 6
    Choose a range that contains your dataSupply from and to as ISO 8601 timestamps including a timezone. Use the same known window you just checked in Explore. The README’s historical dates are examples, not data installed with this add-on. A successfully queried empty period remains a valid empty result.
  7. 7
    Compare the preview and the two downloadsTry JSON preview and inspect count, hasMore and data. The preview returns at most 500 rows; hasMore means there are additional rows. Download CSV and Parquet for the same range. File preparation splits limited history requests and writes incrementally. Range, request-count, size, concurrency and upstream failures are reported explicitly rather than delivered as a successful partial file. The complete CSV/Parquet implementation is in the normal service; the optional single-file learning example only provides a smaller JSON preview.
  8. 8
    Keep the source contract distinctThis offer reads one configured concrete furnace topic. It is separate from the identity-aware Catalog offer for moving equipment. Other services may declare different parameters and schemas; Data Catalog does not generate or reinterpret their business queries.

Expected result

What you should have

One published source is reusable as a documented API preview and two file formats, with the caller’s permissions and explicit query limits.

Boundaries

Important boundaries

  • This guide uses the official signed-catalog release 0.1.4. Repository visibility and catalog inclusion are separate facts; this project is now included in that catalog.
  • For direct source development, follow the versioned v0.1.4 README instead. Directly started processes must supply their own reachable Controller routing metadata and JWKS configuration. The package.json private flag prevents npm publication; it does not make the GitHub repository private.
  • The demo keeps its existing limits: seven days, at most 2,000 history requests per file, a 128 MiB prepared download and two concurrent preparations. More than one raw API page of readings at one millisecond is explicitly rejected instead of silently skipping data.
  • An empty preview or file is not a source error until the time window, archival path and permissions have been checked. Do not weaken caller permissions to bypass a 403.

This versioned public guide is maintained with the UNS OpenHub website and linked directly from the controller where the task applies.