Read materialized facts

Materialized reads retrieve the entities, properties, relationships and source identities already persisted through an ontology fact-store capability. Use them when a pipeline has built durable ontology state. An ordinary Postgres table endpoint is not an ontology store.

You need a Semogram account with access to the workspace and a project in it. Definition and binding changes, query publication, execution and assertion review require their respective permissions. External reads and writes also require the selected plugin installation's credentials and access.

Prepare the fact-store capability

Use a reachable test PostgreSQL database. In workspace Plugins → Explore, install Postgres (@craven/postgres) ontology-store, a fact-store capability distinct from raw-table read/write. Enter Host, Port (usually 5432), Database, User, Password and Ssl in the installation controls. Its database user needs the schema/table creation, materialization and read privileges required by the plugin. Check the connection. The Postgres guide explains installation options.

Create a dedicated schema using your database SQL client:

CREATE SCHEMA IF NOT EXISTS ontology_demo_facts;

Create workspace endpoint demo_facts, namespace ontology_demo, direction Materialization, contract ontology_fact_store, selecting the installed fact-store capability. Set Type postgres_ontology_fact_store, Schema ontology_demo_facts, Table prefix orders. Save/check it and keep its actual endpoint UUID. These settings select generated fact storage, not the source orders table. Saving the endpoint does not insert facts.

Prepare the model

Create project definition operations-demo, namespace https://example.com/operations#, with the complete model.ttl as its model entrypoint and no shapes/imports. Save/validate it and inspect the compiled package UUID and numeric version. This model declares Order, orderId, status and total with string/string/decimal ranges. Use the exact full IRIs below; labels are not interchangeable with compiled identifiers.

A complete read configuration

Your selected store must contain Order entities under the class IRI https://example.com/operations#Order, IDs https://example.com/orders/1 and /2, and the orderId/status/total property values. A blank store correctly returns no entities. To produce this exact fixture, use the complete materialization example, which includes source SQL, model, installation, endpoint, mapping and readback. The read configuration below does not require that you copy its unrelated settings.

Create or inspect an Active Materialized default wildcard binding for the actual compiled package/version and demo_facts endpoint. Set term *, term kind *, cardinality Unknown, default enabled, resolution {}. Specific term bindings are available when a term needs a different source/policy.

Author this complete YAML under Ontology → Queries, replacing package placeholders. Validate, save, publish the exact draft version and Execute with {} input and limit 10.

Create a materialized read of Order, orderId, status and total from the selected fact-store endpoint and compiled operations model. Inspect existing bindings, use the full IRIs, validate the complete query and show the reviewed version before publication.

query_definition:
  name: Demo orders
  slug: demo-orders
  ontology_package_id: <COMPILED_PACKAGE_UUID>
  ontology_package_version: <COMPILED_PACKAGE_VERSION_NUMBER>
  target:
    kind: materialized
  input_schema:
    type: object
    additionalProperties: false
  root:
    term_ref: https://example.com/operations#Order
    cardinality: many
  output_schema:
    type: object
    properties:
      id: { type: string }
      order_id: { type: string }
      status: { type: string }
      total: { type: number }
    required: [id, order_id, status, total]
  output_mapping:
    id: { term_ref: https://example.com/operations#Order }
    order_id: { term_ref: https://example.com/operations#orderId }
    status: { term_ref: https://example.com/operations#status }
    total: { term_ref: https://example.com/operations#total }

Expect the two known order values after materialization. Verify class membership, entity IDs, inactive/deleted state where applicable, and property datatypes. Inspect freshness and store snapshots; a retained fact is not automatically current just because the source system changed.

Store boundaries

Postgres ontology-store and Apache Jena provide plugin-backed storage with their own contracts. The binding selects an endpoint, not arbitrary platform tables. Relationship reads need the correct subject/object IDs; a model relationship declaration contains no actual links by itself. Check the store's supported readback and materialization semantics before assuming parity across plugins.