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