File size: 2,700 Bytes
f14b4e9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | # Working with relationships
The power of Firm comes from connecting entities together to build a graph of your business. You create relationships using reference fields.
## Types of references
Firm supports two kinds of references:
### Entity references
Entity references point to an entire entity using the format `type.id`. This is the primary way to connect entities in Firm:
```firm
task design_homepage {
assignee_ref = person.john_doe
}
```
### Field references
Field references point to a specific field on an entity using the format `type.id.field`:
```firm
task design_homepage {
assignee_name = person.john_doe.name
}
```
Currently, Firm primarily uses entity references.
## Creating a reference
A reference field links one entity to another. Here's a simple example:
```firm
person john_doe {
name = "John Doe"
email = "john@example.com"
}
task design_homepage {
name = "Design new homepage"
assignee_ref = person.john_doe
completed = false
}
```
The `assignee_ref` field contains a reference to `person.john_doe`, creating a connection from the task to the person.
## Multiple references
An entity can reference multiple other entities:
```firm
contact john_at_acme {
person_ref = person.john_doe
organization_ref = organization.acme_corp
role = "CTO"
}
```
This creates two relationships:
- From `contact.john_at_acme` to `person.john_doe`
- From `contact.john_at_acme` to `organization.acme_corp`
## Building a connected graph
By connecting entities with references, you build a graph that represents your business relationships:
```firm
organization acme_corp {
name = "Acme Corp"
}
person jane_smith {
name = "Jane Smith"
}
contact jane_at_acme {
person_ref = person.jane_smith
organization_ref = organization.acme_corp
role = "CEO"
}
project website_redesign {
name = "Website Redesign"
organization_ref = organization.acme_corp
}
task design_mockups {
name = "Design mockups"
project_ref = project.website_redesign
assignee_ref = person.jane_smith
}
```
Now you can explore these relationships:
- Find all projects for Acme Corp
- Find all tasks assigned to Jane
- Find all contacts at Acme Corp
- Find all tasks for projects at Acme Corp
## Querying relationships
Use `firm related` to explore connections:
```bash
firm related organization acme_corp
```
This shows all entities connected to the organization.
For more complex queries, use `firm query`:
```bash
# Find all tasks for projects at Acme Corp
firm query 'from organization | where name contains "Acme" | related project | related task'
```
See the [Querying data](./querying.md) guide for more examples.
|