Active Graph Documentation

Active Graph is an Active Model compliant Ruby/JRuby wrapper for the Neo4j graph database. It provides a high-level interface for managing data stored in nodes and relationships.

Key features include:

• A high-level query building interface for complex graph traversals.
• Integration with neo4j-ruby-driver and active_attr gems.
• Support for transactional operations.

ActiveGraph (formerly known as Neo4j.rb) is an Object-Graph-Mapper (OGM) for the Neo4j graph database. It is designed for Ruby developers, following API conventions established by ActiveRecord to provide a familiar experience when working with graph data.

Key features include:

• Object Model: Support for Properties, Indexes/Constraints, Callbacks, Validations, and Associations.
• First-class Relationships: Unlike many other OMs, ActiveGraph allows you to create models for both nodes and relationships.
• Query Builder: A chainable query builder inspired by Arel.
• Transactions: Support for transactional operations.
• Migration Framework: A dedicated framework for managing graph schema changes.

When using ActiveGraph with a database populated externally (e.g., via Cypher or legacy migration), ensure every Node model has a unique ID property.

By default, ActiveGraph expects a property named uuid to be the unique identifier. If your external data uses a different property, you must either:

1. Define and constrain that property as unique in Cypher during data loading.
2. Override the default ID property in your ActiveGraph models.

To use ActiveGraph effectively, you must understand how it maps Neo4j concepts to Ruby abstractions:

Neo4j Concepts

• Node: An entity with a distinct identity that can store arbitrary properties.
• Label: A way to identify nodes. A single node can have multiple labels (e.g., :Person and :Teacher).
• Relationship: A link between nodes that has a direction and can store properties.
• Type: The single identifier for a relationship (e.g., FRIEND_OF).

ActiveGraph Abstractions

• Model: A Ruby class that includes either ActiveGraph::Node (for nodes) or ActiveGraph::Relationship (for relationships). Models support properties, associations, validations, and callbacks.
• Association: A high-level abstraction defined on a Node model using has_one or has_many to define relationships to other models.

Relationship models are ideal for centralizing logic when multiple associations share the same relationship type but connect different node labels. This prevents 'shoehorning' complex logic into Node models.

By using to_class :any, a single Relationship model can manage connections between various types of nodes, allowing you to centralize validations and callbacks for all connections of that type.

class ManagedRel
  include ActiveGraph::Relationship
  after_create :update_user_stats
  validate :manageable_object
  from_class :User
  to_class :any
  type 'MANAGES'

  def update_user_stats
    from_node.update_stats
  end

  def manageable_object
    errors.add(:to_node) unless to_node.respond_to?(:managed_by)
  end
end

Active Graph uses AssociationProxy and QueryProxy to allow building complex Cypher queries via method chaining. You can start a chain in three ways:

1. Model.all
2. Model.association (Class-level scope)
3. model_object.association (Instance-level scope)

An AssociationProxy allows for eager loading and further association calls. A QueryProxy is returned when using methods like where, allowing for filtering, sorting, and limiting before the query is executed.

lesson.teachers.where(name: /.* smith/i, age: 34).order(:name).limit(2)

The ActiveGraph::Core::Query class provides a Ruby DSL for building Cypher queries with several key benefits:

• Method Chaining: Build parts of a query incrementally and pass the query object to other methods for further construction.
• Automatic Parameterization: Automatically uses parameters in queries whenever possible to improve security and performance.
• Data Integration: Allows passing data directly from Ruby sources, such as using a Hash to match keys and values.
• Native Ruby Object Mapping: Translates native Ruby objects into Cypher syntax (e.g., translating nil to IS NULL or Ruby regular expressions to Cypher-style regular expression matches).

Behavior of association creation (<< or =) depends on the persistence state of the nodes:

1. Both nodes persisted: Relationship is created immediately in the database.
2. Calling node is unpersisted: No database changes occur until save is called on the parent node. A cascading save will then persist the child and create the relationship within a transaction.
3. Target node is unpersisted: If you associate an unpersisted node with a persisted one (e.g., student.lessons << new_lesson), the unpersisted node is saved and the relationship is created immediately.