A maintenance team often knows the machine ID but not which manual applies to it. Keyword search can find documents containing the machine’s name, yet the strongest answer may already exist as a precise relationship: this machine uses this guide.

This walkthrough models that connection in OriginChainDB. The example uses fictional equipment and documentation, not operating instructions for a real machine. Its purpose is to show how an explicit relationship can make information retrieval easier to inspect.

1. Choose stable identities

Create two tables in a fresh demo namespace: guides and equipment. Use string primary keys such as g1 and m1. Names are labels; IDs are the stable connection. If a guide title changes from “Pump guide” to “Pump maintenance guide,” the equipment row should still point to the same guide ID.

Open the schema designer for your development instance or use the documented schema registration endpoint. Register the target table first. Save the following manifest as guides.toml:

namespace = "maintenance_demo"
table = "guides"
primary_key = ["id"]

[[columns]]
name = "id"
ty = "str"
required = true

[[columns]]
name = "title"
ty = "str"

Register it with POST /v1/tenants/:tenant/schemas, using Content-Type: text/plain and the TOML as the body, as shown in the schema guide.

2. Declare the connection on the equipment table

Save and register this second manifest:

namespace = "maintenance_demo"
table = "equipment"
primary_key = ["id"]

[[columns]]
name = "id"
ty = "str"
required = true

[[columns]]
name = "name"
ty = "str"

[[columns]]
name = "guide_id"
ty = "str"

[[relations]]
name = "uses_guide"
from_col = "guide_id"
target = { namespace = "maintenance_demo", table = "guides", pk = "id" }
bidirectional = true

The relation name describes the connection. from_col identifies the column on the equipment row containing the target ID. In OriginChainDB’s documented model, declaring a separate table with src and dst columns would not by itself create a traversable relation.

3. Add two records and inspect them

In the SQL workbench, run:

INSERT INTO maintenance_demo.guides (id, title)
VALUES ('g1', 'Pump maintenance guide');

INSERT INTO maintenance_demo.equipment (id, name, guide_id)
VALUES ('m1', 'Training pump', 'g1');

SELECT id, name, guide_id
FROM maintenance_demo.equipment
ORDER BY id;

The equipment row should reference g1. Inspect the guide table too and confirm that this ID exists. A relation declaration is a model of a connection; do not assume it also enforces every business rule or rejects every missing target.

4. Follow the relationship and verify the destination

Use the console’s Graph workbench with the declared uses_guide relation and equipment ID m1. The direction is from the equipment to its guide. Follow the current graph reference for the console or API query format supported by your instance. Resolve the returned guide ID to its row and verify the title rather than treating an edge ID as a complete document.

The expected conceptual result is m1 → uses_guide → g1. Reverse lookup is useful when you need to find equipment associated with one guide. Reverse edges depend on the relation configuration and existing writes; changing that configuration later should not be assumed to backfill historical data.

5. Test a realistic failure

In a disposable demo record, reference a guide ID that does not exist and inspect how the application handles it. It should report that the guide is unavailable rather than quietly substitute a similar title. Repair the reference, then repeat the lookup. Your validation should check both the link and the record it identifies.

For a larger knowledge base, keep guide version and review status alongside the document. An AI assistant can use the relationship to choose candidate evidence, but the application still needs permission checks and a current source. This makes graph retrieval a practical way to connect records, without asking similarity alone to determine which manual belongs to which machine. Consult the graph relation schema reference for the supported declaration fields and modelling limits.

Run the forward lookup as an explicit request

The graph reference documents a neighbor lookup addressed by source table, relation name and primary key. With the manifests and rows above already registered, the following Bash request asks the precise question “which guide does equipment m1 reference?” Supply the host, tenant and a correctly scoped token through your existing secure environment; the host variable is the hostname without https://.

curl --fail-with-body --get \
  "https://$OC_HOST/v1/tenants/$OC_TENANT/graph/maintenance_demo.equipment/neighbors" \
  -H "Authorization: Bearer $OC_TOKEN" \
  --data-urlencode "rel=uses_guide" \
  --data-urlencode "pk=m1"

Inspect the returned neighbor identity and confirm that its primary key is g1. Then resolve the source row:

SELECT id, title
FROM maintenance_demo.guides
WHERE id = 'g1';

The expected title is Pump maintenance guide. These are two different checks: graph traversal establishes the declared connection, while the SQL read confirms the document record being presented. Neither check establishes that the guide is approved for a real machine; that business rule requires version and applicability data chosen by the application.

Add another synthetic row to make the relationship less trivial:

INSERT INTO maintenance_demo.equipment (id, name, guide_id)
VALUES ('m2', 'Second training pump', 'g1');

Now both m1 and m2 refer to g1. Renaming the guide should not require changing either equipment identity. For the reverse question, use the reference’s reverse operation and the same relation configuration; verify that the returned source identities correspond to both equipment rows. Do not infer a reverse result merely from the shape of the diagram.

Build an equipment-to-guide screen a person can trust

Start the screen with the equipment ID, name and model rather than a generic search box. Next show the chosen guide ID, title, revision, approval state and source location. The link from equipment to guide should remain visible so an editor can explain why this document appeared. Keep these fields as structured source data; an embedding score should not stand in for an approval flag.

When the guide is unavailable, show that precise state. Do not silently choose a similarly titled guide, because that changes a deterministic relationship into a relevance guess. If the user lacks permission to read the target, display an appropriate unavailable/access state without disclosing restricted titles or content. Log enough non-sensitive identifiers for an authorized operator to investigate the broken path.

For a versioned library, distinguish the stable guide family from the revision used by an equipment configuration. One possible application design stores a guide family ID and a separate approved revision reference. Another pins each equipment record directly to an immutable revision. Choose deliberately: automatically following “latest” can make a previously reviewed relationship point to different content without a new approval.

Test a move, an omission and a missing target

Create a second fictional guide g2, then use the documented row-write path to change m2’s guide reference. Verify the source row, the new forward lookup and the corresponding reverse lookups. The desired application outcome is that m2 resolves to g2 and is no longer presented under g1. Record what the chosen write route actually does before treating it as a guarantee in a production integration.

Also test an equipment row with no guide reference and one with a reference to an unavailable target. These are different states and should have different repair actions. The graph schema reference specifies string node identities and relation behavior; use those constraints when designing the fixture. A successful lesson ends with inspectable source rows, a working forward request, verified reverse behavior and an explicit plan for unavailable or superseded guides.