Data Modeling With XN

Brought to you by the good folks at

Introduction to

Traditional Data Modeling

• Object-oriented.
• Class-hierarchy tree.
• Interfaces and abstract classes.
• Flexible and powerful model.
  • Abstraction
  • Encapsulation
  • Inheritance
  • Polymorphism
• The "bread and butter" of any software engineer.

Traditional Data Modeling

• Any problems with the traditional model?
  • Single inheritance is limiting.
  • Multiple inheritance has its own issues. 
  • Some mistakes are too easy to make.
  • Not necessarily the best fit for every domain.

The XN model

• Parts
  • Ruby modules.
  • Contain getters, setters and other methods.
  • Also known as extensions.
• Models
  • Defined as a list of parts.
  • Do not contain any functionality.
  • You can think of models as types.
• We establish "has a" relation between a model and its parts, as opposed to "is a" relation between a class and its parent.

The XN model + Graph DB

• Graph DB
  • Flexible general-purpose structure.
  • Vertices & edges, both with (optional) properties.
  • Vertices = entities, edges = relations.
• Parts
  • Extend vertices with functionality.
  • Vertices store data, parts define methods.
• Models
  • Types, defined as a list of parts.
  • Each vertex belongs to one model, and can be extended by any part in its model's list.

More On The XN model

• A part can belong to multiple models.
• A model can have multiple parts.
• Can create/delete model object (i.e. entities), but not parts.
• Can read/view part(s) of a model object.

Let's Get Started

• Please make sure you have
  • Installed the xnlogic command-line tool,
  • Created an application,
  • And logged into the VM.

CRUD operations

The basics

Our Data Model

• Two types of objects:
  • User
    • username
    • email
  • Tweet
    • text
• In this simple example, the model is the part.

Create lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text
    property :email, type: :text
  end
end

Edit lib/my_app/models.rb

  client_models = {
     #...
     user: [User],
     #...
  }

In the host machine, using your favorite IDE

Load the application, and get ready to simulate API calls from the console.

HOST$ xnlogic ssh
$ xn-console

> PM.create_db 'my_app', 'db01'
> app = PM['db01']
> include app.console

In the VM, test API using the xn-console

More API Calls

Relations

Connecting entities...

Edit lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text
    property :email, type: :text

    to_many :Tweet
  end
end

Create lib/my_app/parts/tweet.rb

module MyApp
  module Tweet
    xn_part

    property :text, type: :text

    from_one :User

  end
end

Relating Users and Tweets

    to_many :Tweet

GET /model/user/id/73/rel/tweets
GET /model/tweet/id/82/rel/user/properties/email

The API

Get related objects

You may want to create some data first.

Relations, so far ...

• We've seen one-to-many.
  Other types can be defined using the from_one, from_many, to_one and to_many keywords.
• From and to relations are matched by type.
• Automatic plural inflection for many relations.
• API access by appending /rel/RELATION_NAME.

Edit lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text
    property :email, type: :text

    to_many :Tweet
    to_many   :User, to: :follows
    from_many :User, to: :follows, from: :followed_by

  end
end

Naming Relations

    to_many   :User, to: :follows
    from_many :User, to: :follows, from: :followed_by

1. Defines the name of a to-relation.
2. Matches from-relations with to-relations.

Actions

Modifying relations

Introducing Actions

• Instance methods,
• Available through the API.
• Use actions to create, update or delete relations.

Add the following to the User module in lib/my_app/parts/user.rb

Defining Our Action

At this point, lib/my_app/parts/user.rb should look this:

module MyApp
    module User
        xn_part

        property :username, type: :text
        property :email, type: :text

        to_many :Tweet
        to_many   :User, to: :follows
        from_many :User, to: :follows, from: :followed_by

        action :post_tweet, args: [{:t => :text}] do |context, t|
            self.post_tweet(t)
        end

        module Vertex
            def post_tweet(t)
                tweet = self.app.create(M::Tweet, {text: t})
                tweet.user = self
                tweet
            end
        end    

    end
end

Full Source Code

Perform Action Using The API

As before, we will simulate API calls using the xn-console.

Summarizing Actions

• Instance methods that are exposed to the API.
• Access via a POST request.
  • Append /action/ACTION_NAME to the URL.
  • Send data as JSON object.
• Defining an action involves:
  • Declaring the API interface.
  • Defining the logic.
• Good practices: Define the logic in an instance method (i.e. inside the Vertex module).
• Actions are automatically wrapped in a transaction.
• See additional examples of defining actions.

Custom Traversals

Extend the API with

The Problem

• Example: ​
• Inconvenient to implement graph queries.
• Hard to debug.
• Potentially limiting.

So far, we have seen the most basic API queries:

• Getting entities by type.
• Following an entity's relation.

The Solution

1. Defining the logic.
   
    
2. Exposing to the method to the API.

• Using Ruby.
• With the full power of Pacer.

Extend the API with custom traversals.

Add the following to the User module in lib/my_app/parts/user.rb

• Name
• Return type
• Block of code (self is a route).

Defining Our Traversals

• Inside a Route module.
• self is a route, think of it as a composable stream of vertices.

The API

Real World Example

Recommend new users to follow.

• Look at users who follow the same people as me.
• See who else they are following.

Add the following inside Route module of the User part.

def recommended_users_to_follow(limit)
    self.similar_users.follows
        .except(self).except(self.follows)
        .most_frequent(0...limit)
end

Implementing The Query

1. Use the similar_users method and follows relation.
2. Exclude myself, and users I am already following, from the result.
3. Include only the most frequent users.

• ​Users who are more similar to me occur more times in self.simlar_users.
• And people that they follow occur more times in self.simlar_users.follows.

Custom Traversals - Summary

• Define custom traversals in the Route module.
• Expose traversals to the API.
• Extend the API with your domain-specific language.

• Construct URLs using /to/traversal_name.
• Chain traversals.

A Few More Data Modeling Features ...

Edit lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text
    property :email, type: :text

    # ...

Filtering/Searching

Edit lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text
    property :email, type: :text




    # ...

Display Properties

Edit the User module in lib/my_app/parts/user.rb

    action :post_tweet, args: [{:t => :text}],                           do |context, t|
        self.post_tweet(t)
    end

Guarding Actions

    module Vertex







        #...

Edit the User module in lib/my_app/parts/user.rb

    document :stats do |context|
        self.statistics_report()
    end

Documents

        def statistics_report
            {'follows_count'     => self.follows.count, 
             'followed_by_count' => self.followed_by.count}
        end

    module Vertex







        #...

Source Code

The full source code in lib/my_app/parts/user.rb

module MyApp
  module User
    xn_part

    property :username, type: :text, filter: true
    property :email, type: :text

    display :badge do
        self.followed_by.count > 10 ? "Popular" : "--"
    end


    to_many :Tweet

    to_many   :User, to: :follows
    from_many :User, to: :follows, from: :followed_by


    action :follow, args: [{:user_id => :numeric}] do |context, user_id|
		self.follow(user_id)
	end

	action :unfollow, args: [{:user_id => :numeric}] do |context, user_id|
		self.unfollow(user_id)
	end

    action :post_tweet, args: [{:t => :text}], 
        guard: :guard_post_tweet do |context, t|
		    self.post_tweet(t)
	end


    document :stats do |context|
      self.statistics_report()
    end


    route_traversal :similar_users, return_parts: :User do
        self.similar_users.uniq
    end

    route_traversal :should_follow, return_parts: :User do
        self.recommended_users_to_follow(10)
    end


	module Route

    	def similar_users()
    		self.follows.followed_by.except(self)
    	end

    	def recommended_users_to_follow(limit)
    		self.similar_users.follows.except(self).except(self.follows).most_frequent(0...limit)
    	end

	end


    module Vertex

        def statistics_report
            {'follows_count'     => self.follows.count, 
             'followed_by_count' => self.followed_by.count}
        end

        def guard_post_tweet(errors, context, t)
            if t.length > 140
                errors.add(:t, "Tweet is too long.")
            end
        end

    	def post_tweet(t)
    		tweet = self.app.create(M::Tweet, {text: t})
			tweet.user = self
			tweet
    	end

    	def follow(user_id)
    		self.add_follows(self.app.graph.vertex(user_id, M::User))
    	end

    	def unfollow(user_id)
    		self.remove_follows(self.app.graph.vertex(user_id, M::User))
    	end

    end

  end
end

The full source code in lib/my_app/parts/tweet.rb

module MyApp
  module Tweet
    xn_part

    property :text, type: :text

    from_one :User

  end
end

Patterns

Working With Parts & Models

The Model Is The Part

• The simple pattern we've seen so far.
• No real distinction between a part or a model.
• Good for defining simple types.

The Aspect

• The part describes one aspect of the model.
• For example, a Computer part might

• Have properties like processor, memory, etc.
• Have various relations.
• Be a part of models such as Server, Desktop, SmartWatch or SmartPhone.

The Quality

• The part describes a quality/feature of the model.
• For example, a LivingCreature part can belong to models such as Person, Dog and Cat.
• Allows efficient search by part.
  For example, find all living creatures.
• Describes an aspect of the model, not a specific entity.

• We can always ask whether a person is alive.
• Although some people might be dead.
• Chairs, on the other hand, don't have the notion of being dead or alive. 
• Therefore, a Chair model would not have a LivingCreature part.

The Tag

• The part indicates some quality/category of the model.
• Similar to the previous pattern (aspect), only without any properties or relations.
• For example, a Perishable part that belongs to models like Apple, Orange or Milk.

The Relator

• A part whose sole purpose is to enable some relations.
• For example:

• We may want to attach notes to entities of different, unrelated types.
  Types such as Phone, Song, Person or Article.
• We can define a HasNotes part with a relation to many Note objects.
• Every model, with a HasNotes part, will have a relation to many notes.

• Marked as                               .

Summary

• Basic building blocks:
  • Part - A module with functionality.
  • Model - A Type, defined as a list of part.
• Parts 
  • Properties & relations.
  • Instance methods (for vertices and routes).
  • Expose method to the API as actions and traversals.
• API gives us:
  • CRUD operations for entities.
  • Following relations.
  • Actions for modifying relations.
• Traversals are composable. 
  Extend the API with our domain-specific language.

Summary

Resources

• xnlogic.com
• Getting Started Tutorial
• Pacer docs
• XN Framework docs
• us@xnlogic.com