===================== Using ipython-gremlin ===================== The following guide demonstrates the usage of ipython-gremlin through an example interactive live session. It assumes that an instance of Gremlin Server version 3.2.4 is running is running at `localhost:8182` using the `gremlin-server-modern.yaml` configuration file:: $ ./bin/gremlin-server.sh conf/gremlin-server-modern.yaml Using Gremlin Magic =================== The first thing to do is load the extension:: In [1]: %load_ext gremlin By default, `ipython-gremlin` will connect to `ws://localhost:8182/gremlin`. This can be changed at the beginning of the session by configuring the :py:class:`GremlinMagic` object, but the easy way to do this is to simply set the current connection to the desired url:: In [2]: %gremlin.connection.set_current ws://localhost:8182/gremlin Alias-- localhost --created for database at ws://localhost:8182/gremlin Notice the output stating that an alias has been created for this connection. Connection aliases will be further discussed later in this document. Line Magic ---------- The first two statements shown here use what is called "line magic", which is denoted by the `%` symbol followed by a command name as well as any number of arguments. Line magic is generally the best way to use `ipython-gremlin`, as it allows you to bind the results of a magic traversal to a variable, or integrate with Python code in other ways:: In [3]: verts = %gremlin g.V() In [4]: verts Out[4]: [v[1], v[2], v[3], v[4], v[5], v[6]] In [5]: for v in verts: ...: vid = v.id ...: props = %gremlin g.V(vid).properties() ...: print(props) [vp[name->marko], vp[age->29]] [vp[name->vadas], vp[age->27]] [vp[name->lop], vp[lang->java]] [vp[name->josh], vp[age->32]] [vp[name->ripple], vp[lang->java]] [vp[name->peter], vp[age->35]] Notice that `ipython-gremlin` can detect bindings stored in the user namespace:: In [6]: vid = 1 In [7]: %gremlin g.V(vid) Out[7]: [v[1]] Cell Magic ---------- `ipython-gremlin` also supports "cell magic", denoted by `%%`. This allows multi-line traversals to be submitted to the server. The downside to cell magic is that the results cannot be bound to a variable in the IPython namespace. Regardless, it can be useful for things like creating elements or executing management commands:: In [8]: %%gremlin ...: graph.addVertex('dog').property('name', 'ewok') ...: // ... do stuff ... Out[8]: [v[13]] Integration with :py:mod:`pandas` and :py:mod:`networkx` ======================================================== When possible, results generated by traversal can be converted into :py:class:`pandas.DataFrame` and :py:class:`networkx.MultiDiGraph` objects. This helps facilitate plotting, transformation, and analysis. :py:mod:`pandas` ---------------- Gremlin traversals can produce complex results and nested datastructures that are difficult to map to a two dimensional table. Despite this, many traversals return relatively simple results that are easy to translate to a tabular structure. For example:: In [9]: values = %gremlin g.V().valueMap(true) In [10]: values.dataframe Out[10]: age id label lang name 0 [29] 1 person NaN [marko] 1 [27] 2 person NaN [vadas] 2 NaN 3 software [java] [lop] 3 [32] 4 person NaN [josh] 4 NaN 5 software [java] [ripple] 5 [35] 6 person NaN [peter] In [11]: edges = %gremlin g.E() In [12]: edges.dataframe Out[12]: id inV label outV 0 7 2 knows 1 1 8 4 knows 1 2 9 3 created 1 3 10 5 created 4 4 11 3 created 4 5 12 3 created 6 :py:mod:`NetworkX` ------------------ When a traversal returns a collection of elements, they can be used to produce a NetworkX graph. Typically a container of edges or paths is the best way to utilize this functionality:: In [13]: edges.graph Out[13]: In [14]: paths = %gremlin g.V().outE().inV().outE().inV().path() In [15]: paths.graph Out[15]: Managing Connections ==================== Typically, :py:mod:`Gremlin-Python` manages connections using a :py:class:`Cluster` object that maintains connection pools to a series of hosts specified using configuration parameters. :py:mod:`ipython-gremlin` has a simpler use case than many apps using :py:mod:`Gremlin-Python` or :py:mod:`aiogremlin`, and therefore doesn't use a :py:class:`Cluster` under the hood. Instead, it manages a registry of simple connections to individual hosts. To add a new host, simply use the line magic shown above:: In [16]: %gremlin.connection.set_current ws://davebshow@myhost:8182/gremlin Alias-- davebshow@myhost --created for database at ws://localhost:8182/gremlin If necessary, this creates a new connection to the specified host, and sets this connection as the current connection to be used by :py:mod:`ipython-gremlin`. An alias for this connection is created automagically, which can be used to refer to this connection. For example, to switch back to the default `localhost` connection:: In [17]: %gremlin.connection.set_current localhost Now using connection at ws://localhost:8182/gremlin Connection Aliases ------------------ :py:mod:`ipython-gremlin` allows the creation of custom aliases. If it is the first time a connection is created (using `%gremlin.connection.set_current`), the alias can be set during creation:: In [18]: %gremlin.connection.set_current ws://localhost:8182/gremlin as TestDB Alias-- TestDB --created for database at ws://localhost:8182/gremlin Now using connection at ws://localhost:8182/gremlin For an existing connection, an alias can be set using the `$gremlin.connection.set_alias` line magic:: In [19]: %gremlin.connection.set_alias ws://localhost:8182/gremlin as TestDB2 Alias-- TestDB2 --created for database at ws://localhost:8182/gremlin Getting the Current Connection ------------------------------ The current connection can be accessed using the line magic `%gremlin.connection.current`:: In [20]: %gremlin.connection.current Out[20]: Connection at ws://localhost:8182/gremlin aliased as localhost Cell Magic and Connection Management ------------------------------------ Connections can also be managed using cell magic (`%%gremlin`). Connections are created, aliased, and set as current simply by passing a connection string on the first line of the cell:: In [21]: %%gremlin ws://localhost:8182/gremlin as MyHost ...: g.V() ...: Out[21]: [v[1], v[2], v[3], v[4], v[5], v[6]] In [22]: %%gremlin MyHost ...: g.V() ...: Out[22]: [v[1], v[2], v[3], v[4], v[5], v[6]] Closing Connections ------------------- :py:mod:`ipython-gremlin` tries to clean up conextions using the :py:mod:`atexit` module, but it is a good idea to explicitly close connections at the end of the interactive session. This is done using line magic:: In [23]: %gremlin.connection.close Or, more simply: In [24]: %gremlin.close To close an individual connection, pass a valid connection string as an argument to `%gremlin.connection.close`:: In [25]: %gremlin.connection.close localhost Configuration ============= :py:class:`GremlinMagic` also supports the :py:class:`Configurable` interface. It provides a range of connection configuration options. These options are displayed using the `%config` cell magic:: In [26]: %config GremlinMagic GremlinMagic options ------------------ GremlinMagic.aliases= Current: {'g': 'g'} Aliases for underlying graph GremlinMagic.password= Current: '' Password used in SASL authentication GremlinMagic.response_timeout= Current: None Timeout for server response GremlinMagic.ssl_context= Current: None `ssl.SSLContext` object for SSL GremlinMagic.uri= Current: 'ws://localhost:8182/gremlin' Default database URI if none is defined inline GremlinMagic.username= Current: '' Username used in SASL authentication Changing this configuration is easy:: In [27]: %config GremlinMagic.username = 'davebshow' In [28]: %config GremlinMagic.username Out[28]: 'davebshow' **NOTE** Configuration changes do not affect connections that have already been established. Please update configuration before performing other `%gremlin` line magic. That's it! I hope you enjoy using :py:mod:`ipython-gremlin`!