Skip to main content

Understanding Graph Relationships

One of Fluree's most powerful features is how naturally it handles relationships between entities.

Entities Reference Each Other​

In Fluree, entities can reference other entities directly using @id:


[
{
"@id": "ex:alice",
"name": "Alice",
"worksAt": {"@id": "ex:acme-corp"}
},
{
"@id": "ex:acme-corp",
"name": "Acme Corporation",
"industry": "Technology"
}
]

Alice's worksAt property points directly to the Acme Corporation entity. This creates a graph edge connecting them.

Beyond Foreign Keys​

If you're coming from relational databases, this might look like a foreign key. But there are key differences:

RelationalFluree Graph
Foreign key references a row in a specific tableReference points to an entity anywhere
Must define relationship in schema firstRelationships are flexible
JOINs required to traverseNavigate naturally in queries

When you query Alice, you can traverse the relationship to get company details:


{
"select": {"ex:alice": ["name", {"worksAt": ["name", "industry"]}]},
"from": "my-ledger"
}

Result:


{
"@id": "ex:alice",
"name": "Alice",
"worksAt": {
"@id": "ex:acme-corp",
"name": "Acme Corporation",
"industry": "Technology"
}
}

Reverse Relationships​

You can also traverse relationships in reverse. Find all people who work at Acme:


{
"select": ["?person"],
"where": {
"@id": "?person",
"worksAt": {"@id": "ex:acme-corp"}
},
"from": "my-ledger"
}

Multi-Hop Traversal​

Relationships can chain: Alice works at Acme, which is located in a city, which is in a country. Fluree queries can traverse multiple hops naturally.

Next Steps​