Prev |  | Next

## 19.2. Core API

This section describes how get get up and running, and how to do basic operations.

### 19.2.1. Getting started

#### Creating a database

    from neo4j import GraphDatabase

    # Create db
    db = GraphDatabase(folder_to_put_db_in)

    # Always shut down your database
    db.shutdown()

#### Creating a database, with configuration

Please see Chapter 21, Configuration & Performance for what options you can use here.

    from neo4j import GraphDatabase

    # Example configuration parameters
    db = GraphDatabase(folder_to_put_db_in, string_block_size=200, array_block_size=240)

    db.shutdown()

#### JPype JVM configuration

You can set extra arguments to be passed to the JVM using the `NEO4J_PYTHON_JVMARGS` environment variable. This can be used to, for instance, increase the max memory for the database.

Note that you must set this before you import the neo4j package, either by setting it before you start python, or by setting it programatically in your app.

    import os
    os.environ['NEO4J_PYTHON_JVMARGS'] = '-Xms128M -Xmx512M'
    import neo4j

You can also override the classpath used by neo4j-embedded, by setting the `NEO4J_PYTHON_CLASSPATH` environment variable.

### 19.2.2. Transactions

All write operations to the database need to be performed from within transactions. This ensures that your database never ends up in an inconsistent state.

See Chapter 12, Transaction Management for details on how Neo4j handles transactions.

We use the python `with` statement to define a transaction context. If you are using an older version of Python, you may have to import the `with` statement:

    from __future__ import with_statement

Either way, this is how you get into a transaction:

    # Start a transaction
    with db.transaction:
        # This is inside the transactional
        # context. All work done here
        # will either entirely succeed,
        # or no changes will be applied at all.

        # Create a node
        node = db.node()

        # Give it a name
        node['name'] = 'Cat Stevens'

    # The transaction is automatically
    # commited when you exit the with
    # block.

### 19.2.3. Nodes

This describes operations that are specific to node objects. For documentation on how to handle properties on both relationships and nodes, see Section 19.2.5, “Properties”.

#### Creating a node

    with db.transaction:
        # Create a node
        thomas = db.node(name='Thomas Anderson', age=42)

#### Fetching a node by id

    # You don't have to be in a transaction
    # to do read operations.
    a_node = db.node[some_node_id]

    # Ids on nodes and relationships are available via the "id"
    # property, eg.:
    node_id = a_node.id

#### Fetching the reference node

    reference = db.reference_node

#### Removing a node

    with db.transaction:
        node = db.node()
        node.delete()

| Tip
See also Section 12.5, “Delete semantics”.

#### Removing a node by id

    with db.transaction:
        del db.node[some_node_id]

#### Accessing relationships from a node

For details on what you can do with the relationship objects, see Section 19.2.4, “Relationships”.

    # All relationships on a node
    for rel in a_node.relationships:
        pass

    # Incoming relationships
    for rel in a_node.relationships.incoming:
        pass

    # Outgoing relationships
    for rel in a_node.relationships.outgoing:
        pass

    # Relationships of a specific type
    for rel in a_node.mayor_of:
        pass

    # Incoming relationships of a specific type
    for rel in a_node.mayor_of.incoming:
        pass

    # Outgoing relationships of a specific type
    for rel in a_node.mayor_of.outgoing:
        pass

#### Getting and/or counting all nodes

Use this with care, it will become extremely slow in large datasets.

    for node in db.nodes:
        pass

    # Shorthand for iterating through
    # and counting all nodes
    number_of_nodes = len(db.nodes)

### 19.2.4. Relationships

This describes operations that are specific to relationship objects. For documentation on how to handle properties on both relationships and nodes, see Section 19.2.5, “Properties”.

#### Creating a relationship

    with db.transaction:
        # Nodes to create a relationship between
        steven = self.graphdb.node(name='Steve Brook')
        poplar_bluff = self.graphdb.node(name='Poplar Bluff')

        # Create a relationship of type "mayor_of"
        relationship = steven.mayor_of(poplar_bluff, since="12th of July 2012")

        # Or, to create relationship types with names
        # that would not be possible with the above
        # method.
        steven.relationships.create('mayor_of', poplar_bluff, since="12th of July 2012")

#### Fetching a relationship by id

    the_relationship = db.relationship[a_relationship_id]

#### Removing a relationship

    with db.transaction:
        # Create a relationship
        source = db.node()
        target = db.node()
        rel = source.Knows(target)

        # Delete it
        rel.delete()

| Tip
See also Section 12.5, “Delete semantics”.

#### Removing a relationship by id

    with db.transaction:
        del db.relationship[some_relationship_id]

#### Relationship start node, end node and type

    relationship_type = relationship.type

    start_node = relationship.start
    end_node = relationship.end

#### Getting and/or counting all relationships

Use this with care, it will become extremely slow in large datasets.

    for rel in db.relationships:
        pass

    # Shorthand for iterating through
    # and counting all relationships
    number_of_rels = len(db.relationships)

### 19.2.5. Properties

Both nodes and relationships can have properties, so this section applies equally to both node and relationship objects. Allowed property values include strings, numbers, booleans, as well as arrays of those primitives. Within each array, all values must be of the same type.

#### Setting properties

    with db.transaction:
        node_or_rel['name'] = 'Thomas Anderson'
        node_or_rel['age'] = 42
        node_or_rel['favourite_numbers'] = [1,2,3]
        node_or_rel['favourite_words'] = ['banana','blue']

#### Getting properties

    numbers = node_or_rel['favourite_numbers']

#### Removing properties

    with db.transaction:
        del node_or_rel['favourite_numbers']

#### Looping through properties

    # Loop key and value at the same time
    for key, value in node_or_rel.items():
        pass

    # Loop property keys
    for key in node_or_rel.keys():
        pass

    # Loop property values
    for value in node_or_rel.values():
        pass

### 19.2.6. Paths

A path object represents a path between two nodes in the graph. Paths thus contain at least two nodes and one relationship, but can reach arbitrary length. It is used in various parts of the API, most notably in traversals.

#### Accessing the start and end nodes

    start_node = path.start
    end_node = path.end

#### Accessing the last relationship

    last_relationship = path.last_relationship

#### Looping through the entire path

You can loop through all elements of a path directly, or you can choose to only loop through nodes or relationships. When you loop through all elements, the first item will be the start node, the second will be the first relationship, the third the node that the relationship led to and so on.

    for item in path:
        # Item is either a Relationship,
        # or a Node
        pass

    for nodes in path.nodes:
        # All nodes in a path
        pass

    for nodes in path.relationships:
        # All relationships in a path
        pass

Copyright © 2012 Neo Technology

Prev | Up | Next
| Home |