A maintenance search result is useful only if it applies to the equipment in front of the technician. Two machines can share a similar name while requiring different procedures. A text match alone cannot establish that a guide belongs to the selected model or revision.

This walkthrough designs a small equipment model for OriginChainDB. SQL provides inspectable source records, while declared graph relationships can express explicit connections between those records. Search remains a separate discovery step. The example is an information-management exercise, not operating or safety guidance for physical equipment.

1. Start with the relationship question

Use three fictional asset IDs: press-a, press-b and pump-c. Give each a model identifier and a site. A service job points to one asset. A guide is approved for a stated model and revision range. Those links answer different questions and should not be collapsed into one generic “related to” edge.

The first application question is narrow: “Which service jobs belong to press-a?” A second question asks: “Which approved guide applies to this asset’s model?” Write those separately before designing the schema.

2. Keep the source records readable

An illustrative SQL fixture is:

CREATE SCHEMA maintenance_demo_20261011;

CREATE TABLE maintenance_demo_20261011.assets (
  id TEXT PRIMARY KEY, model TEXT, site TEXT
);
CREATE TABLE maintenance_demo_20261011.jobs (
  id TEXT PRIMARY KEY, asset_id TEXT, status TEXT, summary TEXT
);
INSERT INTO maintenance_demo_20261011.assets (id,model,site)
VALUES ('press-a','PX1','north'),('press-b','PX2','north'),('pump-c','PU1','south');
INSERT INTO maintenance_demo_20261011.jobs (id,asset_id,status,summary)
VALUES
  ('j1','press-a','open','Review the current service record'),
  ('j2','press-a','closed','Document inspection outcome'),
  ('j3','press-b','open','Confirm guide revision');

Read the tables ordered by ID. The intended counts are two jobs for press-a, one for press-b and none for pump-c. These numbers form a small test oracle for the relationship workflow.

3. Verify the connection with SQL first

SELECT a.id AS asset_id,a.model,j.id AS job_id,j.status
FROM maintenance_demo_20261011.assets a
JOIN maintenance_demo_20261011.jobs j ON j.asset_id = a.id
WHERE a.id = 'press-a'
ORDER BY job_id;

Expect j1 and j2. This check establishes that the source values support the relationship you intend to traverse. If the stored reference is wrong, a graph display cannot repair the meaning for you.

Use a LEFT JOIN when the screen needs to preserve an asset with no jobs. Distinguish “no jobs recorded” from “no maintenance required”; the database cannot infer the second conclusion from an empty result.

4. Declare the graph relationship explicitly

Follow the OriginChainDB graph schema guide when creating a graph-enabled version of the fixture. Register the target asset schema before the referencing job schema. Declare a named relationship based on the job’s asset reference, using the supported manifest fields and key types.

Do not assume that adding a similarly named SQL column automatically declares a graph relationship. The source values and the relationship declaration both matter. Use a separate fresh namespace for the graph exercise if the registered schema differs from the SQL-only fixture above.

The stored meaning is “job belongs to asset.” Traversing outward from a job and inward from an asset asks different questions about that same relationship. Verify both directions against the known IDs instead of choosing a direction by how an arrow looks on screen.

5. Add guides without confusing relevance and applicability

Store a guide ID, model identifier, revision and approved state. An FTS query can help discover passages by terminology. A vector query can help with paraphrased questions. Neither score proves that a procedure is approved for a particular asset.

Apply the model and revision rules using authoritative records. Only then present permitted, applicable guidance. Keep the exact source revision beside the result so a technician or reviewer can inspect the original document.

6. Rehearse a relationship change

In the synthetic graph fixture, intentionally change one job’s asset reference using the supported row-write workflow. Re-run the source query and both relevant traversals. The old asset should no longer be presented as owning the moved job if the documented relationship maintenance applies to that operation.

Also test a missing target reference in isolation. Record whether the schema rejects it, stores it without a resolvable target or behaves differently under your selected constraints. Do not generalize from a diagram to an untested write guarantee.

7. Deliver an explainable maintenance screen

Show the asset identity, model, job status and source guide revision clearly. Keep operational instructions in approved source material, not in an inferred graph label. Protect the data using the access controls supported by the deployment and the application’s authorization rules.

The useful outcome is a small explorer whose results can be traced to source records. SQL checks the facts, graph traversal follows explicitly modeled connections and search helps locate evidence. Each modality has a job you can explain and test.

Turn the source model into a graph-enabled fixture

Use a separate namespace such as maintenance_graph_demo for the graph exercise. Register an assets schema with a single string primary key id and string fields model and site. Register a jobs schema with id, asset_id, status and summary as string fields, then add this relation block to the jobs manifest:

[[relations]]
name = "belongs_to"
from_col = "asset_id"
target = { namespace = "maintenance_graph_demo", table = "assets", pk = "id" }
bidirectional = true

Copy the three synthetic assets and jobs into those registered tables using the documented row-write workflow. The relation lives on jobs because that is where the asset reference is stored. The relation name is the verb used by traversal; it is not automatically inferred from the column name.

After insertion, this forward request asks which asset owns job j1:

curl --fail-with-body --get \
  "https://$OC_HOST/v1/tenants/$OC_TENANT/graph/maintenance_graph_demo.jobs/neighbors" \
  -H "Authorization: Bearer $OC_TOKEN" \
  --data-urlencode "rel=belongs_to" \
  --data-urlencode "pk=j1"

The intended target key is press-a. Resolve it to the asset row and confirm model PX1 and site north. The reverse question starts from that target identity and asks for the referring jobs under the configured relation. Compare the observed result with j1 and j2 rather than assuming that any two returned rows are correct. Follow the graph reference for the exact reverse addressing supported by the deployment.

Model guide applicability as a separate business rule

An asset-to-job relationship records ownership of a maintenance record. A guide-to-model relationship records applicability of documentation. Reusing one broad related_to label for both makes a diagram look connected but weakens the meaning of each path.

For a prototype, keep guide ID, model ID, revision and approved state as inspectable fields. Choose a fictional guide approved for PX1 and another approved for PX2. A search for a shared phrase may retrieve both. The application must still select only guidance applicable to press-a’s model and the intended revision. A high-ranking PX2 passage is not made suitable for PX1 by its score.

When the source guide changes, decide whether existing assets point to a fixed revision or a controlled current revision. Retain enough history to explain which guidance was used for a recorded job. This is a document-control decision for the application, not a property that can be read from a line between two boxes.

Use the zero-job asset as a deliberate test

Pump-c has no jobs in the fixture. An inner join from assets to jobs omits it; a left join preserves it with missing job values. A graph reverse lookup can also produce no referring jobs. None of those outcomes means the equipment is safe, compliant or does not need service. It means this dataset contains no matching job record under the selected relation.

Make that distinction visible in the UI. Show “No jobs recorded” and offer the permitted next step for inspecting or creating a record. If the query failed, show an error state instead of the zero-job state. If the target asset itself is missing, treat that as a different data-quality problem.

Finish with a regression table covering j1→press-a, j2→press-a, j3→press-b, pump-c with no jobs, one moved reference and one unavailable target. Keep the results with the schema version and write route used. This produces an explainable relationship explorer whose source facts, graph paths and documentation rules can each be checked independently.