Spec Files

Spec files are used for creating a schema-like definition file for using static-typing within Titan as defined on the Titan Types Overview.

Example

If we have a system connecting users to their messages via a "received" edge with a date on it then we might like to have these messages pre-sorted on disk so that they can be efficiently queried and slices of messages over date ranges efficiently taken using Vertex Centric Queries. The following is a potential spec defining a schema on the received edge:

(spec.thunderdome)

[
    {"type": "defaults", "spec_type": "property", "functional": false, "indexed": false, "locking": false},
    {"type": "property", "name": "date", "data_type": "Double", "functional": true, "locking": false},
    {"type": "edge", "label": "received", "primary_key": "date"}
]

IMPORTANT To use specs you must make sure that you are calling thunderdome.connection.setup with index_all_fields=False.

Now that we have defined our spec we have to sync it with the graph database before we write anything to it. We can do that with the following simple script:

(sync_spec.py)

from thunderdome.connection import sync_spec

sync_spec('~/spec.thunderdome', 'localhost', 'mygraphname')

This will generate and execute the Gremlin for defining the properties and edge labels in your spec file. We can now begin to define our models:

(spec_test.py)

import thunderdome

class User(thunderdome.Vertex):
    gremlin_path = 'user.groovy'

    name = thunderdome.Text()

    get_all_messages = thunderdome.GremlinMethod()


class Message(thunderdome.Vertex):
    text = thunderdome.Text()


class Received(thunderdome.Edge):
    date = thunderdome.DateTime()


# Efficiently query for all the users messages
u = User.get('...')
# Thunderdome will automatically convert the datetimes for us before sending them as Gremlin parameters
msgs = u.get_all_messages(start=datetime.datetime(day=13, month=4, year=2008),
                          end=datetime.datetime(day=13, month=4, year=2013))

We can also define a vertex-centric query for retrieving the users messages in Gremlin:

(user.groovy)

def get_messages(eid, start, end) {
    q = g.v(eid).query()
    q.labels('received').direction(Direction.OUT).interval('date', start, end).vertices()
}

Important notes

Spec files should only be appended to once they are created and synced for the first time. This avoids a whole host of issues in attempting to figure out what things have and have not been executed. Arbitrarily ordered spec-files are not currently supported.