Relations Graph

Relations model connections between objects in Terragnos Core. Use relations to build graph structures like supply chains, ownership hierarchies, spatial containment, or any other object-to-object relationships.

What are Relations?

A relation is a directed link between two objects with:

• From object – Source object
• To object – Target object
• Relation type – Category of relationship (e.g., "contains", "supplies", "owns")
• Metadata – Additional information about the relation
• Geometry inheritance – Option to inherit geometry from source object

Creating Relations

Via API

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromObjectId": "object-123",
    "toObjectId": "object-456",
    "relationType": "contains",
    "metadata": {
      "description": "Building contains room",
      "area": 50.5
    },
    "inheritsGeometry": false
  }' \
  https://core.example.com/v1/relations

Via Admin Console

1. Navigate to an object's detail page
2. Click Add Relation
3. Select target object and relation type
4. Add metadata if needed
5. Save the relation

Relation Types

Relation types are strings that categorize relationships. Common patterns:

• Spatial: contains, within, adjacent, overlaps
• Hierarchical: parent, child, part-of, composed-of
• Temporal: precedes, follows, succeeds
• Functional: supplies, depends-on, triggers, blocks
• Ownership: owns, manages, operates

Choose relation types that match your domain model.

Querying Relations

List Relations

# All relations for an object
GET /v1/relations?fromObjectId=object-123

# Relations pointing to an object
GET /v1/relations?toObjectId=object-456

# Relations of a specific type
GET /v1/relations?relationType=contains

# Combined filters
GET /v1/relations?fromObjectId=object-123&relationType=contains

Get Object Graph

Retrieve objects with their relations:

POST /v1/queries/objects/run
Content-Type: application/json

{
  "filters": [
    {
      "field": "id",
      "operator": "in",
      "value": ["object-123"]
    }
  ],
  "graph": {
    "objectIds": ["object-123"],
    "maxDepth": 2,
    "relationTypes": ["contains", "supplies"]
  }
}

Response:

{
  "objects": [
    {
      "id": "object-123",
      "typeId": "building",
      "attributes": {...}
    }
  ],
  "relations": [
    {
      "id": "rel-1",
      "fromObjectId": "object-123",
      "toObjectId": "object-456",
      "relationType": "contains",
      "metadata": {...}
    }
  ]
}

Geometry Inheritance

When inheritsGeometry: true, the relation's target object can use the source object's geometry for rendering:

{
  "fromObjectId": "building-123",
  "toObjectId": "room-456",
  "relationType": "contains",
  "inheritsGeometry": true
}

This is useful for:

• Room objects that appear at building locations
• Sub-features that share parent geometry
• Annotations that inherit spatial context

Relation Metadata

Store additional information about relations:

{
  "metadata": {
    "strength": "strong",
    "confidence": 0.95,
    "verified": true,
    "notes": "Verified by inspection on 2024-01-15"
  }
}

Query relations by metadata:

GET /v1/relations?metadata.verified=true

Updating Relations

curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "verified": true,
      "verifiedAt": "2024-01-15T10:30:00Z"
    }
  }' \
  https://core.example.com/v1/relations/{relationId}

Deleting Relations

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/relations/{relationId}

Relations are soft-deleted (marked with deletedAt timestamp).

Graph Traversal

Finding Related Objects

# Get all objects related to an object
GET /v1/objects/{objectId}/relations

# Get objects at specific depth
POST /v1/queries/objects/run
{
  "graph": {
    "objectIds": ["object-123"],
    "maxDepth": 3,
    "relationDirection": "outgoing"
  }
}

Direction Options

• outgoing – Relations where object is the source
• incoming – Relations where object is the target
• all – Both directions (default)

Use Cases

Supply Chain

{
  "fromObjectId": "supplier-123",
  "toObjectId": "product-456",
  "relationType": "supplies",
  "metadata": {
    "quantity": 100,
    "unit": "pieces",
    "deliveryDate": "2024-02-01"
  }
}

Spatial Containment

{
  "fromObjectId": "building-123",
  "toObjectId": "room-456",
  "relationType": "contains",
  "inheritsGeometry": true
}

Workflow Dependencies

{
  "fromObjectId": "task-123",
  "toObjectId": "task-456",
  "relationType": "depends-on",
  "metadata": {
    "dependencyType": "blocking"
  }
}

Best Practices

1. Use consistent relation types – Define a standard set of relation types
2. Document relation types – Maintain a glossary of relation types and their meanings
3. Use metadata wisely – Store domain-specific information in metadata
4. Consider geometry inheritance – Use inheritsGeometry for spatial relationships
5. Query efficiently – Use specific filters to limit relation queries
6. Maintain integrity – Ensure relations make sense in your domain
7. Monitor graph depth – Limit maxDepth in graph queries to avoid performance issues