Quickstart¶

Start Neo4j Server¶

Change to the directory where you installed Neo4j Server, and start it with its default configuration:

$ cd /path/to/neo4j-<version>
$ bin/neo4j start

Browse Neo4j Server¶

Now check to see that you can browse the Neo4j Web admin using this URL:

If you can, then success! Neo4j Server is up and running.

The Neo4j Web Admin is a browser-based interface to Neo4j Server that allows you to view elements in the graph and simulate a Gremlin-console session. See the Neo4j Tools documentation for details.

Create the Graph Object¶

Here’s how you create the Graph object, your primary interface to Neo4j Server:

>>> from bulbs.neo4jserver import Graph
>>> g = Graph()

If you don’t pass a Config object to Graph(), Graph will use the default URI and Config.

You you can pass in a custom config, with a uri, username, and password (a username and password is not required by default):

>>> from bulbs.neo4jserver import Graph, Config, NEO4J_URI
>>> config = Config(NEO4J_URI, "james", "secret")
>>> g = Graph(config)

We used the default Neo4j URI:

>>> print NEO4J_URI

If you ever change the URI in the server config, you should use your URI instead:

>>> config = Config('http://example.dev:7777/db/data/')
>>> g = Graph(config)

Create Vertices and Edges¶

Here is a basic example that creates two Vertex objects and an Edge object that links them together:

>>> james = g.vertices.create(name="James")
>>> julie = g.vertices.create(name="Julie")
>>> g.edges.create(james, "knows", julie)

Return a Property¶

>>> james.name

Update an Existing Property¶

>>> james.name = "James Thornton"
>>> james.save()

Add New Properties¶

>>> james.city = "Dallas"
>>> james.age = 34
>>> james.save()

Return the Property Data Map¶

>>> james.data()

Get Vertex by ID¶

>>> james.eid
1
>>> james2 = g.vertices.get(1)
>>> assert james == james2

Update Vertex by ID¶

>>> data = dict(age=34, city="Dallas")
>>> g.vertices.update(1, data)

Display Vertices¶

Display all the vertices in the graph:

>>> g.V

This returns a list all the Vertex objects in the graph.

This method is primarily used for testing because you won’t normally want to do this for a large database containing millions (or billions) of vertices.

You can see how many vertices were returned by checking the length of the list:

>>> vertices = g.V
>>> len(vertices)

Display Edges¶

Display all the edges in the graph:

>>> g.E

Like g.V, this method is primarily used for testing because you won’t normally want to do this for a large database.

Look Up Indexed Vertices¶

The default Bulbs Config class has autoindex set to True, with “vertex” as the name of the default Vertex index. When autoindex is True, it will automatically index vertices when you create or update them.

Everytime you create a new vertex, it’s automatically added to vertex index, and you can look it up by its properties.

This will return all the vertices that have a “name” property with a value of “James”:

>>> g.vertices.index.lookup(name="James")

As you can see, the return value is a Python generator.

A generator is iterable like a list, but it’s more memory friendly because it’s not copying the entire list around – it lazy loads items as needed:

>>> vertices = g.vertices.index.lookup(name="James")
>>> for vertex in vertices: print vertex

Get the next Vertex in the generator:

>>> vertices = g.vertices.index.lookup(name="James")
>>> james = vertices.next()

To convert a generator into a list, do this:

>>> vertices = g.vertices.index.lookup(name="James")
>>> list(vertices)

Get Adjacent Edges¶

Get all outgoing edges:

>>> james.outE()

Get outgoing edges labeled “knows”:

>>> james.outE("knows")

Get incoming edges (there shouldn’t be any):

>>> james.inE()

Get all the incoming and outgoing edges:

>>> james.bothE()

Get Adjacent Vertices¶

An adjacent vertex is a vertex connected to another vertex by an edge.

Get all the outgoing vertices:

>>> james.outV()

Get outgoing vertices connected by edges labeled “knows”:

>>> james.outV("knows")

Get incoming vertices (there shouldn’t be any):

>>> james.inV()

Get all the incoming and outgoing vertices:

>>> james.bothV()

Enable Debugging¶

Bulbs uses the Python logging facility, and by default it sets the logger to use StreamHandler with log level set to ERROR

To display DEBUG info, set the log level to DEBUG:

>>> from bulbs.config import DEBUG
>>> g.config.set_logger(DEBUG)

Disable Debugging¶

To disable DEBUG info, set the log level back to ERROR:

>>> from bulbs.config import ERROR
>>> g.config.set_logger(ERROR)

Model Declaration¶

You can also use Bulbs to create type-checked, domain-specific models:

# people.py

from bulbs.model import Node, Relationship
from bulbs.property import String, Integer, DateTime
from bulbs.utils import current_datetime

class Person(Node):

    element_type = "person"

    name = String(nullable=False)
    age = Integer()


class Knows(Relationship):

    label = "knows"

    created = DateTime(default=current_datetime, nullable=False)

Example Usage¶

Models provide type checking and validation to ensure that your database properties are stored properly.

Here’s how you would use the models to create and connect Person objects:

>>> from people import Person, Knows
>>> from bulbs.neo4jserver import Graph
>>> g = Graph()

Add proxy interfaces to the Graph object for each custom Model:

>>> g.add_proxy("people", Person)
>>> g.add_proxy("knows", Knows)

Create two Person nodes, which are automatically saved in the DB:

>>> james = g.people.create(name="James")
>>> julie = g.people.create(name="Julie")

Lookup people using the Person model’s primary index:

>>> nodes = g.people.index.lookup(name="James")

Connect James and Julie by creating a “knows” relationship between them:

>>> relationship = g.knows.create(james, julie)

Get the people James knows (the outgoing vertices labeled “knows”):

>>> friends = james.outV('knows')

Get the people that know Julie (the incoming vertices labeled “knows”):

>>> friends = julie.inV('knows')

Return the relationship element’s ID:

>>> relationship.eid

Return the created property:

>>> relationship.created

Return all the property data:

>>> relationship.data()

Return the label:

>>> relationship.label()

Return the outgoing vertex:

>>> relationship.outV()

Return the incoming vertex:

>>> relationship.inV()

Return the outgoing vertex ID:

>>> relationship._outV

Return the incoming vertex ID:

>>> relationship._inV