Basics

Here we will try to describe our first graph. To begin with we will need to setup an environment:

$ pip install hiku

Simplest one-field graph

Note

Source code of this example can be found on GitHub.

Let’s define graph with only one field, which is easy to compute, for example it would be a current time:

from datetime import datetime

from hiku.graph import Graph, Root, Field

GRAPH = Graph([
    Root([
        Field('now', None, lambda _: [datetime.now().isoformat()]),
    ]),
])

This is the simplest Graph with one Field in the Root node.

Note

We are using lambda-function and ignoring it’s first argument because this function is used to load only one field and this field in the Root node. In other cases you will need to use this and possibly other required arguments.

Then this field could be queried using this query:

{ now }

To perform this query let’s define a helper function execute:

from hiku.engine import Engine
from hiku.result import denormalize
from hiku.executors.sync import SyncExecutor
from hiku.readers.graphql import read

hiku_engine = Engine(SyncExecutor())


def execute(graph, query_string):
    query = read(query_string)
    result = hiku_engine.execute(graph, query)
    return denormalize(graph, result)

Then we will be ready to execute our query:

result = execute(GRAPH, '[:now]')
assert result == {'now': '2015-10-21T07:28:00'}

You can also test this graph using special web console application, this is how to setup and run it:

from hiku.console.ui import ConsoleApplication

app = ConsoleApplication(GRAPH, hiku_engine, debug=True)

if __name__ == '__main__':
    from wsgiref.simple_server import make_server
    http_server = make_server('localhost', 5000, app)
    http_server.serve_forever()

Then just open http://localhost:5000/ url in your browser and perform query from the console.

Introducing nodes and links

Note

Source code of this example can be found on GitHub.

This is cool, but what if we want to return some application data? First of all lets define our data:

data = {
    'Character': {
        1: dict(name='James T. Kirk', species='Human'),
        2: dict(name='Spock', species='Vulcan/Human'),
        3: dict(name='Leonard McCoy', species='Human'),
    },
}

Note

For simplicity we will use in-memory data structures to store our data. How to load data from more sophisticated sources like databases will be explained in the next chapters.

Then lets define our graph with one Node and one Link:

from hiku.graph import Graph, Root, Field, Node, Link
from hiku.types import TypeRef, Sequence
from hiku.engine import Engine
from hiku.result import denormalize
from hiku.readers.graphql import read
from hiku.executors.sync import SyncExecutor

def character_data(fields, ids):
    result = []
    for id_ in ids:
        character = data['Character'][id_]
        result.append([character[field.name] for field in fields])
    return result

def to_characters_link():
    return [1, 2, 3]

GRAPH = Graph([
    Node('Character', [
        Field('name', None, character_data),
        Field('species', None, character_data),
    ]),
    Root([
        Link('characters', Sequence[TypeRef['Character']],
             to_characters_link, requires=None),
    ]),
])

character_data function ^[8] is used to resolve values for two fields in the Character node. As you can see, it returns basically a list of lists with values in the same order as it was requested in arguments (order of ids and fields should be preserved).

This function used twice in the graph ^[20-21] – for two fields, this is how Hiku understands that both these fields can be loaded using this one function and one function call. Hiku groups fields by function, to load them together.

This gives us ability to resolve many fields for many objects (ids) using just one simple function (when possible) to efficiently load data without introducing lots of queries (to eliminate N+1 problem, for example).

to_characters_link function ^[15] is used to make a link ^[24-25] from the Root node to the Character node. This function should return character ids.

So now you are able to try this query in the console:

{ characters { name species } }

Or in the program:

result = execute(GRAPH, "{ characters { name species } }")
assert result == {
    "characters": [
        {
            "species": "Human",
            "name": "James T. Kirk",
        },
        {
            "species": "Vulcan/Human",
            "name": "Spock",
        },
        {
            "species": "Human",
            "name": "Leonard McCoy",
        },
    ],
}

Linking node to node

Note

Source code of this example can be found on GitHub.

Let’s extend our data with one more entity - Actor:

data = {
    'Character': {
        1: dict(id=1, name='James T. Kirk', species='Human'),
        2: dict(id=2, name='Spock', species='Vulcan/Human'),
        3: dict(id=3, name='Leonard McCoy', species='Human'),
    },
    'Actor': {
        1: dict(id=1, character_id=1, name='William Shatner'),
        2: dict(id=2, character_id=2, name='Leonard Nimoy'),
        3: dict(id=3, character_id=3, name='DeForest Kelley'),
        4: dict(id=4, character_id=1, name='Chris Pine'),
        5: dict(id=5, character_id=2, name='Zachary Quinto'),
        6: dict(id=6, character_id=3, name='Karl Urban'),
    },
}

Where actor will have a reference to the played character – character_id. We will also need id fields in both nodes in order to link them with each other.

Here is our extended graph definition:

from collections import defaultdict

from hiku.graph import Graph, Root, Field, Node, Link
from hiku.types import TypeRef, Sequence

def character_data(fields, ids):
    result = []
    for id_ in ids:
        character = data['Character'][id_]
        result.append([character[field.name] for field in fields])
    return result

def actor_data(fields, ids):
    result = []
    for id_ in ids:
        actor = data['Actor'][id_]
        result.append([actor[field.name] for field in fields])
    return result

def character_to_actors_link(ids):
    mapping = defaultdict(list)
    for row in data['Actor'].values():
        mapping[row['character_id']].append(row['id'])
    return [mapping[id_] for id_ in ids]

def actor_to_character_link(ids):
    mapping = {}
    for row in data['Actor'].values():
        mapping[row['id']] = row['character_id']
    return [mapping[id_] for id_ in ids]

def to_characters_link():
    return [1, 2, 3]

GRAPH = Graph([
    Node('Character', [
        Field('id', None, character_data),
        Field('name', None, character_data),
        Field('species', None, character_data),
        Link('actors', Sequence[TypeRef['Actor']],
             character_to_actors_link, requires='id'),
    ]),
    Node('Actor', [
        Field('id', None, actor_data),
        Field('name', None, actor_data),
        Link('character', TypeRef['Character'],
             actor_to_character_link, requires='id'),
    ]),
    Root([
        Link('characters', Sequence[TypeRef['Character']],
             to_characters_link, requires=None),
    ]),
])

Here actors Link ^[40-41], defined in the Character node ^[36], requires='id' field ^[37] to map characters to actors. That’s why id field ^[37] was added to the Character node ^[36]. The same work should be done in the Actor node ^[43] to implement backward character link ^[46-47].

requires argument can be specified as a list of fields, in this case Hiku will resolve all of them and pass a list of dict to resolver.

character_to_actors_link function ^[20] accepts ids of the characters and should return list of lists – ids of the actors, in the same order, so every character id can be associated with a list of actor ids. This is how one to many links works.

actor_to_character_link function ^[26] requires/accepts ids of the actors and returns ids of the characters in the same order. This is how many to one links works.

So now we can include linked node fields in our query:

result = execute(GRAPH, "{ characters { name actors { name } } }")
assert result == {
    'characters': [
        {'name': 'James T. Kirk',
         'actors': [{'name': 'William Shatner'},
                    {'name': 'Chris Pine'}]},
        {'name': 'Spock',
         'actors': [{'name': 'Leonard Nimoy'},
                    {'name': 'Zachary Quinto'}]},
        {'name': 'Leonard McCoy',
         'actors': [{'name': 'DeForest Kelley'},
                    {'name': 'Karl Urban'}]},
    ],
}

We can go further and follow character link from the Actor node and return fields from Character node. This is an example of the cyclic links, which is normal when this feature is desired, as long as query is a hierarchical finite structure and result follows it’s structure.

result = execute(GRAPH, "{ characters { name actors { name character { name } } } }")
assert result == {
    'characters': [
        {'name': 'James T. Kirk',
         'actors': [{'name': 'William Shatner',
                     'character': {'name': 'James T. Kirk'}},
                    {'name': 'Chris Pine',
                     'character': {'name': 'James T. Kirk'}}]},
        {'name': 'Spock',
         'actors': [{'name': 'Leonard Nimoy',
                     'character': {'name': 'Spock'}},
                    {'name': 'Zachary Quinto',
                     'character': {'name': 'Spock'}}]},
        {'name': 'Leonard McCoy',
         'actors': [{'name': 'DeForest Kelley',
                     'character': {'name': 'Leonard McCoy'}},
                    {'name': 'Karl Urban',
                     'character': {'name': 'Leonard McCoy'}}]},
    ],
}

As you can see, there are duplicate entries in the result ^[11,13,15] – this is how our cycle can be seen, the same character Spock seen multiple times.