Relationships

Relationships connect nodes to form a knowledge graph. They represent how pieces of information relate to each other.

What is a Relationship?

A relationship is a directed connection between two nodes:

[Node A] ──── relationship_type ────> [Node B]

For example:

• Meeting Note → references → Project Document
• Contact: John → works_at → Company: Acme
• Task → depends_on → Other Task

Relationship Structure

{
  "id": "rel_a1b2c3d4",
  "source_node_id": "node_meeting123",
  "target_node_id": "node_project456",
  "relationship_type": "references",
  "weight": 0.8,
  "metadata": {
    "context": "Mentioned in Q4 planning"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Field	Type	Description
source_node_id	string	Starting node
target_node_id	string	Ending node
relationship_type	string	Type of connection
weight	float	Strength (0-1), optional
metadata	object	Custom data

Relationship Types

Common relationship types:

Type	Description	Example
references	One node mentions another	Note → Document
related_to	General association	Topic → Topic
parent_of	Hierarchical	Folder → File
depends_on	Dependency	Task → Prerequisite
created_by	Authorship	Document → Person
occurred_at	Location/time	Event → Place
knows	Social connection	Person → Person

You can use any string as a relationship type.

Working with Relationships

Create a Relationship

relationship = client.relationships.create(
    user_id="user-123",
    source_node_id="node_meeting",
    target_node_id="node_project",
    relationship_type="references",
    weight=0.9
)

List Relationships

# All relationships involving a node
result = client.relationships.list(
    user_id="user-123",
    node_id="node_meeting"
)

for rel in result['items']:
    print(f"{rel['source_node_id']} → {rel['relationship_type']} → {rel['target_node_id']}")

Filter by Type

# Only "references" relationships
result = client.relationships.list(
    user_id="user-123",
    relationship_type="references"
)

Get Node's Relationships

# Get relationships directly from a node
relationships = client.nodes.get_relationships(
    user_id="user-123",
    node_id="node_meeting"
)

Update a Relationship

updated = client.relationships.update(
    user_id="user-123",
    relationship_id="rel_abc",
    weight=1.0,
    metadata={"updated_reason": "Verified connection"}
)

Delete a Relationship

client.relationships.delete(
    user_id="user-123",
    relationship_id="rel_abc"
)

Building a Knowledge Graph

Relationships enable you to build rich knowledge graphs:

# Create nodes
person = client.nodes.create(
    user_id=user_id,
    title="John Doe",
    node_type="entity",
    node_metadata={"entity_type": "person"}
)

company = client.nodes.create(
    user_id=user_id,
    title="Acme Corp",
    node_type="entity",
    node_metadata={"entity_type": "company"}
)

meeting = client.nodes.create(
    user_id=user_id,
    title="Intro Meeting",
    node_type="event"
)

# Create relationships
client.relationships.create(
    user_id=user_id,
    source_node_id=person['id'],
    target_node_id=company['id'],
    relationship_type="works_at"
)

client.relationships.create(
    user_id=user_id,
    source_node_id=meeting['id'],
    target_node_id=person['id'],
    relationship_type="attended_by"
)

Result:

          ┌─────────────┐
          │   Meeting   │
          └──────┬──────┘
                 │ attended_by
                 ▼
          ┌─────────────┐
          │  John Doe   │
          └──────┬──────┘
                 │ works_at
                 ▼
          ┌─────────────┐
          │  Acme Corp  │
          └─────────────┘

Visualizing the Graph

Get a snapshot for visualization:

graph = client.graph.snapshot(user_id="user-123")

# Use with D3.js, vis.js, react-force-graph, etc.
print(f"Nodes: {len(graph['nodes'])}")
print(f"Edges: {len(graph['edges'])}")

Relationship Weight

The weight field (0-1) indicates relationship strength:

Weight	Meaning
1.0	Strong, explicit connection
0.7-0.9	Clear relationship
0.4-0.6	Moderate connection
0.1-0.3	Weak or inferred connection

Use weight for:

• Ranking search results
• Filtering graph visualizations
• Prioritizing connections

Best Practices

1. Use Consistent Relationship Types

Define a vocabulary for your app:

RELATIONSHIP_TYPES = [
    "references",
    "related_to",
    "parent_of",
    "child_of",
    "depends_on",
    "blocked_by",
    "created_by"
]

2. Make Relationships Bidirectional When Needed

Some relationships imply an inverse:

# If A parent_of B, consider also creating B child_of A
client.relationships.create(..., relationship_type="parent_of")
client.relationships.create(..., relationship_type="child_of")

3. Use Metadata for Context

client.relationships.create(
    ...,
    relationship_type="references",
    metadata={
        "context": "Mentioned in section 3",
        "confidence": 0.95,
        "extracted_by": "my-ai-app"
    }
)

4. Don't Over-Connect

Too many relationships create noise. Only create meaningful connections.

Next Steps

• Graph Visualization - Visualize the knowledge graph
• Proposals - Create relationships via user approval