DataStax Graph Queries
======================

The driver executes graph queries over the Cassandra native protocol. Use
:meth:`.Session.execute_graph` or :meth:`.Session.execute_graph_async` for 
executing gremlin queries in DataStax Graph.

The driver defines three Execution Profiles suitable for graph execution:

* :data:`~.cluster.EXEC_PROFILE_GRAPH_DEFAULT`
* :data:`~.cluster.EXEC_PROFILE_GRAPH_SYSTEM_DEFAULT`
* :data:`~.cluster.EXEC_PROFILE_GRAPH_ANALYTICS_DEFAULT`

See :doc:`getting_started` and :doc:`execution_profiles`
for more detail on working with profiles.

In DSE 6.8.0, the Core graph engine has been introduced and is now the default. It
provides a better unified multi-model, performance and scale. This guide
is for graphs that use the core engine. If you work with previous versions of 
DSE or existing graphs, see :doc:`classic_graph`.

Getting Started with Graph and the Core Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, we need to create a graph in the system. To access the system API, we 
use the system execution profile ::

    from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_SYSTEM_DEFAULT

    cluster = Cluster()
    session = cluster.connect()

    graph_name = 'movies'
    session.execute_graph("system.graph(name).create()", {'name': graph_name},
                          execution_profile=EXEC_PROFILE_GRAPH_SYSTEM_DEFAULT)


Graphs that use the core engine only support GraphSON3. Since they are Cassandra tables under
the hood, we can automatically configure the execution profile with the proper options
(row_factory and graph_protocol) when executing queries. You only need to make sure that
the `graph_name` is set and GraphSON3 will be automatically used::

    from cassandra.cluster import Cluster, GraphExecutionProfile, EXEC_PROFILE_GRAPH_DEFAULT

    graph_name = 'movies'
    ep = GraphExecutionProfile(graph_options=GraphOptions(graph_name=graph_name))
    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep})
    session = cluster.connect()
    session.execute_graph("g.addV(...)")


Note that this graph engine detection is based on the metadata. You might experience
some query errors if the graph has been newly created and is not yet in the metadata. This
would result to a badly configured execution profile. If you really want to avoid that,
configure your execution profile explicitly::

    from cassandra.cluster import Cluster, GraphExecutionProfile, EXEC_PROFILE_GRAPH_DEFAULT
    from cassandra.graph import GraphOptions, GraphProtocol, graph_graphson3_row_factory

    graph_name = 'movies'
    ep_graphson3 = GraphExecutionProfile(
        row_factory=graph_graphson3_row_factory,
        graph_options=GraphOptions(
            graph_protocol=GraphProtocol.GRAPHSON_3_0,
            graph_name=graph_name))

    cluster = Cluster(execution_profiles={'core': ep_graphson3})
    session = cluster.connect()
    session.execute_graph("g.addV(...)", execution_profile='core')


We are ready to configure our graph schema. We will create a simple one for movies::

    # A Vertex represents a "thing" in the world.
    # Create the genre vertex
    query = """
        schema.vertexLabel('genre')
            .partitionBy('genreId', Int)
            .property('name', Text)
            .create()
    """
    session.execute_graph(query)

    # Create the person vertex
    query = """
        schema.vertexLabel('person')
            .partitionBy('personId', Int)
            .property('name', Text)
            .create()
    """
    session.execute_graph(query)

    # Create the movie vertex
    query = """
        schema.vertexLabel('movie')
            .partitionBy('movieId', Int)
            .property('title', Text)
            .property('year', Int)
            .property('country', Text)
            .create()
    """
    session.execute_graph(query)

    # An edge represents a relationship between two vertices
    # Create our edges
    queries = """
    schema.edgeLabel('belongsTo').from('movie').to('genre').create();
    schema.edgeLabel('actor').from('movie').to('person').create();
    """
    session.execute_graph(queries)

    # Indexes to execute graph requests efficiently

    # If you have a node with the search workload enabled (solr), use the following:
    indexes = """
        schema.vertexLabel('genre').searchIndex()
            .by("name")
            .create();

        schema.vertexLabel('person').searchIndex()
            .by("name")
            .create();

        schema.vertexLabel('movie').searchIndex()
            .by('title')
            .by("year")
            .create();
    """
    session.execute_graph(indexes)

    # Otherwise, use secondary indexes:
    indexes = """
        schema.vertexLabel('genre')
            .secondaryIndex('by_genre')
            .by('name')
            .create()

        schema.vertexLabel('person')
            .secondaryIndex('by_name')
            .by('name')
            .create()

        schema.vertexLabel('movie')
            .secondaryIndex('by_title')
            .by('title')
            .create()
    """
    session.execute_graph(indexes)

Add some edge indexes (materialized views)::

    indexes = """
        schema.edgeLabel('belongsTo')
            .from('movie')
            .to('genre')
            .materializedView('movie__belongsTo__genre_by_in_genreId')
            .ifNotExists()
            .partitionBy(IN, 'genreId')
            .clusterBy(OUT, 'movieId', Asc)
            .create()

        schema.edgeLabel('actor')
            .from('movie')
            .to('person')
            .materializedView('movie__actor__person_by_in_personId')
            .ifNotExists()
            .partitionBy(IN, 'personId')
            .clusterBy(OUT, 'movieId', Asc)
            .create()
    """
    session.execute_graph(indexes)

Next, we'll add some data::

    session.execute_graph("""
        g.addV('genre').property('genreId', 1).property('name', 'Action').next();
        g.addV('genre').property('genreId', 2).property('name', 'Drama').next();
        g.addV('genre').property('genreId', 3).property('name', 'Comedy').next();
        g.addV('genre').property('genreId', 4).property('name', 'Horror').next();
    """)

    session.execute_graph("""
        g.addV('person').property('personId', 1).property('name', 'Mark Wahlberg').next();
        g.addV('person').property('personId', 2).property('name', 'Leonardo DiCaprio').next();
        g.addV('person').property('personId', 3).property('name', 'Iggy Pop').next();
    """)

    session.execute_graph("""
        g.addV('movie').property('movieId', 1).property('title', 'The Happening').
            property('year', 2008).property('country', 'United States').next();
        g.addV('movie').property('movieId', 2).property('title', 'The Italian Job').
            property('year', 2003).property('country', 'United States').next();

        g.addV('movie').property('movieId', 3).property('title', 'Revolutionary Road').
            property('year', 2008).property('country', 'United States').next();
        g.addV('movie').property('movieId', 4).property('title', 'The Man in the Iron Mask').
            property('year', 1998).property('country', 'United States').next();

        g.addV('movie').property('movieId', 5).property('title', 'Dead Man').
            property('year', 1995).property('country', 'United States').next();
    """)

Now that our genre, actor and movie vertices are added, we'll create the relationships (edges) between them::

    session.execute_graph("""
        genre_horror = g.V().hasLabel('genre').has('name', 'Horror').id().next();
        genre_drama = g.V().hasLabel('genre').has('name', 'Drama').id().next();
        genre_action = g.V().hasLabel('genre').has('name', 'Action').id().next();

        leo  = g.V().hasLabel('person').has('name', 'Leonardo DiCaprio').id().next();
        mark = g.V().hasLabel('person').has('name', 'Mark Wahlberg').id().next();
        iggy = g.V().hasLabel('person').has('name', 'Iggy Pop').id().next();

        the_happening = g.V().hasLabel('movie').has('title', 'The Happening').id().next();
        the_italian_job = g.V().hasLabel('movie').has('title', 'The Italian Job').id().next();
        rev_road = g.V().hasLabel('movie').has('title', 'Revolutionary Road').id().next();
        man_mask = g.V().hasLabel('movie').has('title', 'The Man in the Iron Mask').id().next();
        dead_man = g.V().hasLabel('movie').has('title', 'Dead Man').id().next();

        g.addE('belongsTo').from(__.V(the_happening)).to(__.V(genre_horror)).next();
        g.addE('belongsTo').from(__.V(the_italian_job)).to(__.V(genre_action)).next();
        g.addE('belongsTo').from(__.V(rev_road)).to(__.V(genre_drama)).next();
        g.addE('belongsTo').from(__.V(man_mask)).to(__.V(genre_drama)).next();
        g.addE('belongsTo').from(__.V(man_mask)).to(__.V(genre_action)).next();
        g.addE('belongsTo').from(__.V(dead_man)).to(__.V(genre_drama)).next();

        g.addE('actor').from(__.V(the_happening)).to(__.V(mark)).next();
        g.addE('actor').from(__.V(the_italian_job)).to(__.V(mark)).next();
        g.addE('actor').from(__.V(rev_road)).to(__.V(leo)).next();
        g.addE('actor').from(__.V(man_mask)).to(__.V(leo)).next();
        g.addE('actor').from(__.V(dead_man)).to(__.V(iggy)).next();
    """)

We are all set. You can now query your graph. Here are some examples::

    # Find all movies of the genre Drama
    for r in session.execute_graph("""
      g.V().has('genre', 'name', 'Drama').in('belongsTo').valueMap();"""):
        print(r)

    # Find all movies of the same genre than the movie 'Dead Man'
    for r in session.execute_graph("""
      g.V().has('movie', 'title', 'Dead Man').out('belongsTo').in('belongsTo').valueMap();"""):
        print(r)

    # Find all movies of Mark Wahlberg
    for r in session.execute_graph("""
      g.V().has('person', 'name', 'Mark Wahlberg').in('actor').valueMap();"""):
        print(r)

To see a more graph examples, see `DataStax Graph Examples <https://github.com/datastax/graph-examples/>`_.

Graph Types for the Core Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are the supported graph types with their python representations:

============   =================
DSE Graph      Python Driver
============   =================
text           str
boolean        bool
bigint         long
int            int
smallint       int
varint         long
double         float
float          float
uuid           UUID
bigdecimal     Decimal
duration       Duration (cassandra.util)
inet           str or IPV4Address/IPV6Address (if available)
timestamp      datetime.datetime
date           datetime.date
time           datetime.time
polygon        Polygon
point          Point
linestring     LineString
blob           bytearray, buffer (PY2), memoryview (PY3), bytes (PY3)
list           list
map            dict
set            set or list
               (Can return a list due to numerical values returned by Java)
tuple          tuple
udt            class or namedtuple
============   =================

Named Parameters
~~~~~~~~~~~~~~~~

Named parameters are passed in a dict to :meth:`.cluster.Session.execute_graph`::

    result_set = session.execute_graph('[a, b]', {'a': 1, 'b': 2}, execution_profile=EXEC_PROFILE_GRAPH_SYSTEM_DEFAULT)
    [r.value for r in result_set]  # [1, 2]

All python types listed in `Graph Types for the Core Engine`_ can be passed as named parameters and will be serialized
automatically to their graph representation:

Example::

    session.execute_graph("""
      g.addV('person').
      property('name', text_value).
      property('age', integer_value).
      property('birthday', timestamp_value).
      property('house_yard', polygon_value).next()
    """, {
      'text_value': 'Mike Smith',
      'integer_value': 34,
      'timestamp_value': datetime.datetime(1967, 12, 30),
      'polygon_value': Polygon(((30, 10), (40, 40), (20, 40), (10, 20), (30, 10)))
    })


As with all Execution Profile parameters, graph options can be set in the cluster default (as shown in the first example)
or specified per execution::

    ep = session.execution_profile_clone_update(EXEC_PROFILE_GRAPH_DEFAULT,
                                                graph_options=GraphOptions(graph_name='something-else'))
    session.execute_graph(statement, execution_profile=ep)

CQL collections, Tuple and UDT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a very interesting feature of the core engine: we can use all CQL data types, including
list, map, set, tuple and udt. Here is an example using all these types::

    query = """
        schema.type('address')
            .property('address', Text)
            .property('city', Text)
            .property('state', Text)
            .create();
    """
    session.execute_graph(query)

    # It works the same way than normal CQL UDT, so we
    # can create an udt class and register it
    class Address(object):
        def __init__(self, address, city, state):
            self.address = address
            self.city = city
            self.state = state

    session.cluster.register_user_type(graph_name, 'address', Address)

    query = """
        schema.vertexLabel('person')
            .partitionBy('personId', Int)
            .property('address', typeOf('address'))
            .property('friends', listOf(Text))
            .property('skills', setOf(Text))
            .property('scores', mapOf(Text, Int))
            .property('last_workout', tupleOf(Text, Date))
            .create()
    """
    session.execute_graph(query)

    # insertion example
    query = """
         g.addV('person')
            .property('personId', pid)
            .property('address', address)
            .property('friends', friends)
            .property('skills', skills)
            .property('scores', scores)
            .property('last_workout', last_workout)
            .next()
    """

    session.execute_graph(query, {
        'pid': 3,
        'address': Address('42 Smith St', 'Quebec', 'QC'),
        'friends': ['Al', 'Mike', 'Cathy'],
        'skills': {'food', 'fight', 'chess'},
        'scores': {'math': 98, 'french': 3},
        'last_workout': ('CrossFit', datetime.date(2018, 11, 20))
    })

Limitations
-----------

Since Python is not a strongly-typed language and the UDT/Tuple graphson representation is, you might 
get schema errors when trying to write numerical data. Example::

    session.execute_graph("""
        schema.vertexLabel('test_tuple').partitionBy('id', Int).property('t', tupleOf(Text, Bigint)).create()
    """)

    session.execute_graph("""
        g.addV('test_tuple').property('id', 0).property('t', t)
          """, 
          {'t': ('Test', 99))}
    )

    # error: [Invalid query] message="Value component 1 is of type int, not bigint"

This is because the server requires the client to include a GraphSON schema definition
with every UDT or tuple query. In the general case, the driver can't determine what Graph type
is meant by, e.g., an int value, and so it can't serialize the value with the correct type in the schema.
The driver provides some numerical type-wrapper factories that you can use to specify types:

* :func:`~.to_int`
* :func:`~.to_bigint`
* :func:`~.to_smallint`
* :func:`~.to_float`
* :func:`~.to_double`

Here's the working example of the case above::

    from cassandra.graph import to_bigint

     session.execute_graph("""
        g.addV('test_tuple').property('id', 0).property('t', t)
          """, 
          {'t': ('Test', to_bigint(99))}
    )

Continuous Paging
~~~~~~~~~~~~~~~~~

This is another nice feature that comes with the core engine: continuous paging with
graph queries. If all nodes of the cluster are >= DSE 6.8.0, it is automatically
enabled under the hood to get the best performance. If you want to explicitly
enable/disable it, you can do it through the execution profile::

    # Disable it
    ep = GraphExecutionProfile(..., continuous_paging_options=None))
    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep})

    # Enable with a custom max_pages option
    ep = GraphExecutionProfile(...,
        continuous_paging_options=ContinuousPagingOptions(max_pages=10)))
    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep})