.. _rdflib_graph: Navigating Graphs

=================
Navigating Graphs
=================

An RDF Graph is a set of RDF triples, and we try to mirror exactly this in RDFLib. The Python :meth:`~rdflib.graph.Graph` tries to emulate a container type.

Graphs as Iterators
-------------------

RDFLib graphs override :meth:`~rdflib.graph.Graph.__iter__` in order to support iteration over the contained triples:

.. code-block:: python

    for subject, predicate, object in someGraph:
        if not (subject, predicate, object) in someGraph:
            raise Exception("Iterator / Container Protocols are Broken!!")

Contains check
--------------

Graphs implement :meth:`~rdflib.graph.Graph.__contains__`, so you can check if a triple is in a graph with ``triple in graph`` syntax:

.. code-block:: python

    from rdflib import URIRef
    from rdflib.namespace import RDF
    bob = URIRef("http://example.org/people/bob")
    if (bob, RDF.type, FOAF.Person) in graph:
        print("This graph knows that Bob is a person!")
	 
Note that this triple does not have to be completely bound:

.. code-block:: python

    if (bob, None, None) in graph:
        print("This graph contains triples about Bob!")

.. _graph-setops:

Set Operations on RDFLib Graphs 
-------------------------------

Graphs override several pythons operators: :meth:`~rdflib.graph.Graph.__iadd__`, :meth:`~rdflib.graph.Graph.__isub__`, etc. This supports addition, subtraction and other set-operations on Graphs:

============ ==================================================
operation    effect
============ ==================================================
``G1 + G2``  return new graph with union
``G1 += G1`` in place union / addition
``G1 - G2``  return new graph with difference
``G1 -= G2`` in place difference / subtraction
``G1 & G2``  intersection (triples in both graphs)
``G1 ^ G2``  xor (triples in either G1 or G2, but not in both)
============ ==================================================

.. warning:: Set-operations on graphs assume Blank Nodes are shared between graphs. This may or may not do what you want. See :doc:`merging` for details.

Basic Triple Matching
---------------------

Instead of iterating through all triples, RDFLib graphs support basic triple pattern matching with a :meth:`~rdflib.graph.Graph.triples` function. 
This function is a generator of triples that match the pattern given by the arguments.  The arguments of these are RDF terms that restrict the triples that are returned.  Terms that are :data:`None` are treated as a wildcard. For example:

.. code-block:: python

    g.load("some_foaf.rdf")
    for s, p, o in g.triples((None, RDF.type, FOAF.Person)):
        print("{} is a person".format(s))

    for s, p, o in g.triples((None,  RDF.type, None)):
        print("{} is a {}".format(s, o))

    bobgraph = Graph()

    bobgraph += g.triples((bob, None, None))

If you are not interested in whole triples, you can get only the bits you want with the methods :meth:`~rdflib.graph.Graph.objects`, :meth:`~rdflib.graph.Graph.subjects`, :meth:`~rdflib.graph.Graph.predicates`, :meth:`~rdflib.graph.Graph.predicate_objects`, etc. Each take parameters for the components of the triple to constraint:

.. code-block:: python

    for person in g.subjects(RDF.type, FOAF.Person):
        print("{} is a person".format(person))

Finally, for some properties, only one value per resource makes sense (i.e they are *functional properties*, or have max-cardinality of 1). The :meth:`~rdflib.graph.Graph.value` method is useful for this, as it returns just a single node, not a generator:

.. code-block:: python

    name = g.value(bob, FOAF.name) # get any name of bob
    # get the one person that knows bob and raise an exception if more are found
    mbox = g.value(predicate = FOAF.name, object=bob, any=False)


:class:`~rdflib.graph.Graph` methods for accessing triples
-----------------------------------------------------------

Here is a list of all convenience methods for querying Graphs:

.. automethod:: rdflib.graph.Graph.label
    :noindex:
.. automethod:: rdflib.graph.Graph.preferredLabel
    :noindex:
.. automethod:: rdflib.graph.Graph.triples
    :noindex:
.. automethod:: rdflib.graph.Graph.value
    :noindex:
.. automethod:: rdflib.graph.Graph.subjects
    :noindex:
.. automethod:: rdflib.graph.Graph.objects
    :noindex:
.. automethod:: rdflib.graph.Graph.predicates
    :noindex:
.. automethod:: rdflib.graph.Graph.subject_objects
    :noindex:
.. automethod:: rdflib.graph.Graph.subject_predicates
    :noindex:
.. automethod:: rdflib.graph.Graph.predicate_objects
    :noindex: