Commits

Amirouche Boubekki committed c1772bf

add documentation in README.rst

Comments (0)

Files changed (1)

-ajgu-graphdb
-############
+==============
+ ajgu-graphdb
+==============
+
 
 :python: 3.3
-:dependency: msgpack
+:dependency: none
 
 
 .. image:: https://d2weczhvl823v0.cloudfront.net/python-graph-lovestory/ajgu-graphdb/trend.png
    :alt: Bitdeli badge
    :target: https://bitdeli.com/free
+
+Kesaco?
+#######
+
+Ajgu is a simple graph database power by BerkleyDB key-value store.
+
+``from ajgu import Graph``
+##########################
+
+This is the only import you need to do any other object, is created by the graph object you will create.
+
+Sensible default are used so that you only have to do the following to instantiate a graph::
+
+  graph = Graph('my-super-dupper-project')
+
+When you are finished you have to close the database::
+
+  graph.close()
+
+Every operation must happen in a transaction. For that matter there is context manager ``Graph.transaction()`` that handle does what must be done in most cases. If you want to do weird things, you can use ``Graph.txn()`` to create a transaction and manage it yourself.
+
+The transaction object works as a shadow copy of the graph. You perform operation against it, until the transaction is commited, then changes if any are persisted.
+
+To create a vertex use the following::
+
+  with graph.transaction() as txn:
+      vertex = txn.create_vertex()
+
+A vertex works kind of a ``dict`` but has not all its methods (yet). You can use subscript aka. ``[]`` to change or retrieve properties of the vertex. The handy ``Vertex.get(key, default)`` is also available. Once you are finished you have to call ``Vertex.save()``. You can also delete a vertex with ``Vertex.delete()``. You can use ``Vertex.id()`` to retrieve the unique identifier of the vertex. Those methods are the base methods of any graph element (vertex or edge). Remember that everything must happen in a transaction.
+
+For instance to create a vertex and give it a name you can do the following::
+
+  with graph.transaction() as txn:
+      vertex = txn.create_vertex()
+      vertex['name'] = "super-dupper-vertex"
+      vertex.save()  # don't forget to save before leaving the transaction
+
+Creating and mutating the vertex in two transaction is possible, only if you retrieve again the vertex for the current transaction::
+
+  with graph.transaction() as txn:
+      vertex = txn.create_vertex()
+      # in this case saving is useless
+
+  with graph.transaction() as txn:
+      vertex = txn.vertex(vertex.id())
+      vertex['name'] = "super-dupper-vertex"
+      vertex.save()  # don't forget to save before leaving the transaction
+
+In the above we introduced another method of ``Transaction``, ``Transaction.vertex(id)`` method. There is also a similar method for edge ``Transaction.edge(id)`` which allows to retrieve an element with its identifier.
+
+Vertex other methods ``Vertex.outgoings(label=None)`` and ``Vertex.incomings(label=None)``. They allow to retrieve edges. The label argument allows to filter based on the ``label`` of the edge. They returns a generator. They will be explained further below.
+
+Creating a edge is also very simple::
+
+  with graph.transaction() as txn:
+      start = txn.create_vertex()
+      end = txn.create_vertex()
+      edge = txt.create_edge(start, 'super-dupper-label', end)
+
+The edge is persisted, connected to both ``start`` and ``end``. For ``start`` it's an *outgoing* edge, because it starts there. For ``end`` it's an *incoming* edge, because it ends there. This is translated in terms of code as follow::
+
+  with graph.transaction() as txn:
+      start = txn.vertex(start.id())
+      unique_outgoing = next(start.outgoings())
+      assert unique_outgoing.id() == edge.id()
+
+Similarly::
+
+  with graph.transaction() as txn:
+      end = txn.vertex(end.id())
+      unique_incoming = next(start.incomings())
+      assert unique_incoming.id() == edge.id()
+
+``Edge`` as also a ``Edge.start()`` and ``Edge.end()`` methods which allows to retrieve the start and end vertex of the edge::
+
+  with graph.transaction() as txn:
+      edge = txn.edge(edge.txn())
+      assert start.id() == edge.start()
+
+Similarly::
+
+  with graph.transaction() as txn:
+      edge = txn.edge(edge.txn())
+      assert end.id() == edge.end()
+
+There is also a ``Edge.label()`` to retrieve the edge label.
+
+The graph works also as a key/value store via ``Transaction.get(key)`` and ``Transaction.set(key, value)``. A common pratice is to store a vertex identifier in an index to retrieve it later::
+
+  with graph.transaction() as txn:
+       txn.set('my-super-dupper-vertex', vertex.id())
+
+Later...::
+
+  with graph.transaction() as txn:
+       identifier = txn.get('my-super-dupper-vertex')
+       again = txn.vertex(identifier)
+       assert again.id() == vertex.id()
+
+That is all! Don't forget to read the code, it's not big.
+
+FAQ
+###
+
+#. **What ajgu means?**
+   
+   *ajgu* is a beam used in house construction in amazigh language.
+
+#. **Do you use ajgu in real product?**
+   
+   Yes, for an internal app at $WORK.
+
+#. **Where can I find a graph server with multithread and python querying?**
+   
+   `GraphitiDB <https://github.com/python-graph-lovestory/Java-GraphitiDB>`_ does just that.
+
+#. **Are GraphDBs useful beyond prototyping?**
+   
+   You tell me!
+
+#. **GraphDBs are awesome, where can I learn more?**
+   
+   There is not much information on the web on how to architecture programs using graphdbs. Patterns exists but they are very simple and you can guess them on your own. The API is not as complex as RDBMS and in this case *worse* is *better* holds True ;)
+
+#. **Why do ajgu use the Transaction object to mutate the Graph?** 
+   
+   Because it makes it possible to have several transctions in the same thread.