relationalai.std.graphs.Edge

class relationalai.std.graphs.Edge

The Edge class is used to represent the set of edges in a graph. This class is automatically instantiated when you create a Graph object and is accessible via the graph’s .Edge attribute. It provides methods for adding and querying edges in the graph.

Example

import relationalai as rai
from relationalai.std import alias
from relationalai.std.graphs import Graph

# Create a model with a 'Person' and 'Message' types.
model = rai.Model("socialNetwork")
Person = model.Type("Person")
Message = model.Type("Message")

# Add people and messages to the model.
# People are connected by a multi-valued 'follows' property.
with model.rule():
    alice = Person.add(name="Alice")
    bob = Person.add(name="Bob")
    alice.follows.add(bob)
    Message.add(sender=alice, recipient=bob, text="Hey Bob!")

# Create a weighted, directed graph.
# Graphs are directed by default, so only the 'weighted' parameter is needed.
graph = Graph(model, weighted=True)

# Add edges using the 'Person.follows'. Person nodes are automatically added
# to the graph. The 'label' parameter is optional and sets the edge's label
# in the graph visualization.
graph.Edge.extend(Person.follows, label="follows")

# Alternatively, you can add specific edges in a rule using 'Edge.add()'.
# For example, this rule adds edges of type "message" between all senders and recipients.
with model.rule():
    message = Message()
    graph.Edge.add(from_=message.sender, to=message.recipient, label="message")

# You can query edges using 'graph.Edge', which behaves like a 'Type' object.
# It returns an 'EdgeInstance' object that can be used to access the edge's
# properties. Use the 'from_' and 'to' properties to access the nodes at
# either end of the edge.
with model.query() as select:
    edge = graph.Edge()
    response = select(edge.from_.name, edge.to.name, alias(edge.label, "label"))

print(response.results)
# Output:
#     name name2        v
# 0  Alice   Bob  follows
# 1  Alice   Bob  message

Methods

Name	Description	Returns
.__call__()	Query the edge set.	EdgeInstance
.add()	Add edges to the graph.	EdgeInstance
.extend()	Extend the edge set with edges from a Property.	EdgeInstance

.__call__()

Edge.__call__(
    from_: Producer | None = None,
    to: Producer | None = None,
    **kwargs
) -> EdgeInstance

Returns an EdgeInstance object that produces edges from the graph. Use the optional from_ and to arguments to filter edges by the nodes they connect. Must be called in a rule or query context.

Parameters

Name	Type	Description
from_	Producer	The initial node of the edge. If None, the edge can start from any node.
to	Producer	The terminal node of the edge. If None, the edge can end at any node.
**kwargs	Any	Keyword arguments to filter edges by their properties.

Returns

An EdgeInstance object.

Example

Call an Edge object in a rule or query context to get an EdgeInstance object that produces the graph’s edges:

import relationalai as rai
from relationalai.std.graphs import Graph

# Create a model with 'Person' and 'Transaction' types.
model = rai.Model("transactions")
Person = model.Type("Person")
Transaction = model.Type("Transaction")

# Add some people and transactions to the model.
with model.rule():
    alice = Person.add(name="Alice")
    bob = Person.add(name="Bob")
    carol = Person.add(name="Carol")
    Transaction.add(sender=alice, receiver=bob, amount=50.0)
    Transaction.add(sender=bob, receiver=alice, amount=100.0)
    Transaction.add(sender=alice, receiver=carol, amount=200.0)

# Create a weighted, directed graph from the model.
graph = Graph(model, weighted=True)

# Add edges to the graph from the 'Transaction' type.
with model.rule():
    transaction = Transaction()
    graph.Edge.add(
        from_=transaction.sender,
        to=transaction.receiver,
        weight=transaction.amount
    )

# Query all edges in the graph.
with model.query() as select:
    edge = graph.Edge()
    response = select(edge.from_.name, edge.to.name, edge.weight)

print(response.results)
# Output:
#     name  name2      v
# 0  Alice    Bob   50.0
# 1  Alice  Carol  200.0
# 2    Bob  Alice  100.0

# Use the 'from_' and 'to' properties to filter edges by
# the nodes they connect. For example, to get all edges
# starting from Alice:
with model.query() as select:
    edge = graph.Edge(from_=Person(name="Alice"))
    response = select(edge.to.name, edge.weight)

print(response.results)
# Output:
#     name      v
# 0    Bob   50.0
# 1  Carol  200.0

# To get all edges ending at Alice:
with model.query() as select:
    edge = graph.Edge(to=Person(name="Alice"))
    response = select(edge.from_.name, edge.weight)

print(response.results)
# Output:
#   name      v
# 0  Bob  100.0

# To get all edges between Alice and Bob:
with model.query() as select:
    edge = graph.Edge(
        from_=Person(name="Alice"),
        to=Person(name="Bob")
    )
    response = select(edge.weight)

print(response.results)
# Output:
#       v
# 0  50.0

# You can also filter edges by their properties. For example,
# to get all transactions with an amount equal to 100.0:
with model.query() as select:
    edge = graph.Edge(weight=100.0)
    response = select(edge.from_.name, edge.to.name)

print(response.results)
# Output:
#   name  name2
# 0  Bob  Alice

.add()

Edge.add(from_: Producer, to: Producer, **kwargs: Any) -> EdgeInstance

Adds edges to the graph from objects produced by from_ to objects produced by to. Edge properties may be passed as keyword arguments to **kwargs. Objects produced by from_ and to are automatically added to the graph’s nodes. Must be called in a rule or query context.

Parameters

Name	Type	Description
from_	Producer	The node at the start of the edge.
to	Producer	The node at the end of the edge.
**kwargs	Any	Keyword arguments to set the edge’s properties.

Returns

An EdgeInstance object.

Example

Use Edge.add() to add edges to the graph:

import relationalai as rai
from relationalai.std.graphs import Graph

# Create a model with 'Person' and 'Transaction' types.
model = rai.Model("transactions")
Person = model.Type("Person")
Transaction = model.Type("Transaction")

# Add some people and transactions to the model.
with model.rule():
    alice = Person.add(name="Alice")
    bob = Person.add(name="Bob")
    Transaction.add(sender=bob, receiver=alice, amount=100.0)

# Create a directed graph.
graph = Graph(model)

# Add transactions to the graph as edges.
# The 'weight' parameter sets the weight property of each edge.
with model.rule():
    transaction = Transaction()
    graph.Edge.add(
        from_=transaction.sender,
        to=transaction.receiver,
        weight=transaction.amount
    )

# Query the edges in the graph.
with model.query() as select:
    edge = graph.Edge()
    response = select(edge.from_.name, edge.to.name, edge.weight)

print(response.results)
# Output:
#   name  name2      v
# 0  Bob  Alice  100.0

.extend()

Edge.extend(prop: Property, **kwargs: Any) -> None

Add pairs of objects from a Property to a graph’s edges. Edge properties may be passed as keyword arguments to **kwargs. Objects produced by the property are automatically added to the graph’s nodes.

Parameters

Name	Type	Description
prop	Property	The property to extend the graph’s edges with.
**kwargs	Any	Keyword arguments to set the edge’s properties.

Returns

None.

Example

Use Edge.extend() to add edges to the graph from a property. You do not need to call .extend() in a rule or query context.

import relationalai as rai
from relationalai.std.graphs import Graph

# Create a model with a 'Person' type.
model = rai.Model("socialNetwork")
Person = model.Type("Person")

# Add people to the model connected by a multi-valued 'follows' property.
with model.rule():
    alice = Person.add(name="Alice")
    bob = Person.add(name="Bob")
    alice.follows.add(bob)

# Create a directed graph.
graph = Graph(model)

# Extend the graph's edges with the 'Person.follows' property.
graph.Edge.extend(Person.follows)

# Query the edges in the graph.
with model.query() as select:
    edge = graph.Edge()
    response = select(edge.from_.name, edge.to.name)

print(response.results)
# Output:
#     name name2
# 0  Alice   Bob