--- title: "Basic usage" description: "Connect to Aerospike Graph Service using Gremlin Console, Python, Java, or Jupyter Notebooks with query examples." --- # Basic usage > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. ## Overview This page describes several options for connecting to, and interacting with, Aerospike Graph Service (AGS). - The [Gremlin Console](https://tinkerpop.apache.org/docs/3.6.1/reference/#gremlin-console), an interactive command-line terminal for sending queries and receiving responses. - A client application. This page provides code samples for Python and Java client code. - A [Jupyter Notebook](https://jupyter.org/). ## Working with graph data You can use a client application or the Gremlin Console to query an existing data set, or to add edges and vertices to a data set. The [examples](#examples) on this page demonstrate how to add vertices one at a time to a database. For instructions on how to load datasets into a Graph database, see [Bulk data loading](https://aerospike.com/docs/graph/2.6.0/develop/data-loading/overview). ### Binding to Docker [Kelvin Lawrence](https://www.kelvinlawrence.net/) has compiled and made public a [data set](https://github.com/krlawrence/graph/tree/master/sample-data) designed for use with a graph database. It contains information about airlines, airports around the world, and routes between them. The data set is large enough to be interesting and useful, but small enough to be practical for testing and experimentation purposes. To use the Gremlin console with the following examples, you must have a [Java runtime](https://www.java.com/). 1. Download the two .csv data files: - [air-routes-latest-edges.csv](https://raw.githubusercontent.com/krlawrence/graph/refs/heads/master/sample-data/air-routes-latest-edges.csv) - [air-routes-latest-nodes.csv](https://raw.githubusercontent.com/krlawrence/graph/refs/heads/master/sample-data/air-routes-latest-nodes.csv) 2. Place the file `air-routes-latest-edges.csv` in a directory called `edges` and the file `air-routes-latest-nodes.csv` in a directory called `vertices`. For more information about the required bulk loading directory structure, see [CSV format](https://aerospike.com/docs/graph/2.6.0/develop/data-loading/csv-format). 3. Start the [AGS Docker image](https://aerospike.com/docs/graph/2.6.0/install/docker), with the `-v` option to bind the parent directory of the `edges` and `vertices` directories to a directory in the Docker container. For example, if your `edges` and `vertices` directories are located at `/etc/data`, start the AGS Docker image with the `-v` option: Terminal window ```bash docker run -p 8182:8182 \ -e aerospike.client.namespace="test" \ -e aerospike.client.host="localhost:3000" \ -v /home/user/data/:/opt/aerospike-graph/data \ aerospike/aerospike-graph-service ``` After the Docker container starts, the .csv files are available in the Docker container at `/opt/aerospike-graph/data`. 4. From the Gremlin console, load the `air-routes` data set into AGS with the following command: ```plaintext g.with("evaluationTimeout", 24 * 60 * 60 * 1000) .call("aerospike.graphloader.admin.bulk-load.load") .with("aerospike.graphloader.vertices", "/opt/aerospike-graph/data/vertices") .with("aerospike.graphloader.edges", "/opt/aerospike-graph/data/edges").iterate() ``` ::: note The `air-routes` data set may take a few minutes to load depending on your host hardware and network configuration. ::: ## Examples - [Gremlin console](#tab-panel-3570) - [Client application](#tab-panel-3571) - [Jupyter notebook](#tab-panel-3572) 1. Download the [latest version of the Gremlin Console](https://tinkerpop.apache.org/download.html) from the Apache website. 2. After unzipping the package and navigating to the application folder, start the console with the following command: Terminal window ```bash ./bin/gremlin.sh ``` 3. Connect using the AGS Docker image. See the [instructions](https://aerospike.com/docs/graph/2.6.0/install/docker) if you haven’t yet started an AGS Docker image. ```plaintext g = traversal().withRemote(DriverRemoteConnection.using("GREMLIN_SERVER_IP_ADDRESS", 8182, "g")); ``` Replace `GREMLIN_SERVER_IP_ADDRESS` with the accessible IP address of your AGS Docker image. Expected output: ```plaintext graphtraversalsource[emptygraph[empty], standard] ``` 4. Add a vertex with the `addV` function: ```plaintext g.addV('foo').property('company','aerospike').property('scale','unlimited') ``` Expected output: ```plaintext v[-1] ``` 5. Return the ID of your newly-created vertex: ```plaintext g.V().has('company','aerospike') ``` Expected output: ```plaintext v[-1] ``` #### Sample Gremlin queries with the `air-routes` data set 1. Find the airport with code “DFW”: ```plaintext g.V().has('code','DFW') ``` 2. Find the number of airports in this graph: ```plaintext g.V().hasLabel('airport').count() ``` 3. Find the number of flights going out of the airport with code “SFO”: ```plaintext g.V().has('code','SFO').outE().count() ``` 4. Get all the cities with flights that are > 4000 miles: ```plaintext g.E().has("dist", P.gt(4000L)).inV().values("city").dedup() ``` 5. Find all the airports in the USA you can fly to from London Heathrow (LHR): ```plaintext g.V().has('code','LHR').out('route').has('country','US').values('code') ``` 6. Find all the unique locations in the world and in the US that I can get to from SFO through a 2 hop flight: ```plaintext g.V().has("code", "SFO").out().out().dedup().fold().project("totalAirportCountFromSFO", "USAirportCountFromSFO").by(__.unfold().count()).by(__.unfold().has("country", "US").count()) ``` To get performance metrics for a query, append `.profile()` to the end of the command. #### Additional resources - Gremlin uses [Groovy](http://www.groovy-lang.org/documentation.html) as its query language. - Kelvin Lawrence has written a thorough [Gremlin manual](https://kelvinlawrence.net/). #### Python 1. Install [Gremlin-Python](https://pypi.org/project/gremlinpython/), a Gremlin client library for Python, and the dependency [`async-timeout`](https://pypi.org/project/async-timeout/): Terminal window ```bash pip3 install gremlinpython async-timeout ``` 2. `Gremlin-Python` implements many of the functions found in Gremlin. The following example code establishes a connection with a remote Gremlin server, creates a vertex, and reads it back. Additional queries use the `air-routes` data set. ::: note Before running the following example Python application, load the `air-routes` data set, as described in the [Working with graph data](#working-with-graph-data) section. If you run the application with an empty database, it returns empty values. ::: ```python from gremlin_python.process.anonymous_traversal import traversal from gremlin_python.process.traversal import IO from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection if __name__ == '__main__': # Create GraphTraversalSource to remote server. g = traversal().with_remote(DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')) # Add a new vertex. g.add_v('foo').property('company','aerospike').property('scale','unlimited').iterate() # Read back the new vertex. result = g.V().has('company','aerospike').element_map().to_list() print(result) # Sample queries with the air-routes data set. To use these queries, download # the data set and load it with the following: # g.with_("evaluationTimeout", 24 * 60 * 60 * 1000).\ # io(PATH_TO_DATA_FILE).\ # with_(IO.reader, IO.graphml).\ # read().iterate() # Find the airport with code "DFW": result = g.V().has('code','DFW').element_map().next() print(result, '\n') # Find the number of airports in this graph: result = g.V().has_label('airport').count().next() print(result, '\n') # Find the number of flights going out of the airport with code "SFO": result = g.V().has('code','SFO').out_e().count().next() print(result, '\n') # Find all the airports in the USA you can fly to from London Heathrow (LHR): result = g.V().has('code','LHR').out('route').has('country','US').values('code').to_list() print(result, '\n') ``` #### Java ```java package com.aerospike.firefly.benchmark; import org.apache.tinkerpop.gremlin.driver.Cluster; import org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection; import org.apache.tinkerpop.gremlin.process.traversal.IO; import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource; import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__; import java.util.Map; import static org.apache.tinkerpop.gremlin.process.traversal.AnonymousTraversalSource.traversal; public class FireflySample { // Use the command: docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' CONTAINER_ID // to get the HOST IP address below. 172.17.0.3 is typical for Linux when Aerospike is running in Docker already // but there may be some variance. private static final String HOST = "172.17.0.3"; private static final int PORT = 8182; private static final Cluster.Builder BUILDER = Cluster.build().addContactPoint(HOST).port(PORT).enableSsl(false); public static void main(final String[] args) { System.out.println("Creating the Cluster."); final Cluster cluster = BUILDER.create(); System.out.println("Creating the GraphTraversalSource."); final GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using(cluster)); // Add a new vertex. g.addV("foo").property("company", "aerospike").property("scale","unlimited").iterate(); // Read the new vertex. Vertex ReadVertex = g.V().has("company","aerospike").next(); System.out.println(ReadVertex); // Find the number of airports in this graph: long airportCount = g.V().hasLabel("airport").count().next(); System.out.printf("Airport count: %d%n", airportCount); // Find the number of flights going out of the airport with code "SFO": long flightCount = g.V().has("code","SFO").outE().count().next(); System.out.printf("Flight count: %d%n", flightCount); // We can use .next() to terminate this traversal because it only returns 1 item Map SFO2Hop = g.V(). has("code", "SFO"). out().out().dedup().fold(). project("totalAirportCountFromSFO", "USAirportCountFromSFO"). by(__.unfold().count()). by(__.unfold().has("country", "US").count()). next(); System.out.println(SFO2Hop); // Find all the airports in the USA you can fly to from London Heathrow (LHR): GraphTraversal LHRCount = g.V(). has("code","LHR"). out("route"). has("country","US"). values("code"); LHRCount.forEachRemaining( e -> System.out.println(LHRCount.toList()) ); cluster.close(); } } ``` #### Jupyter notebook Jupyter Notebooks are a community standard for communicating and performing interactive computing. You can create a notebook with Aerospike Graph to provide a sandbox for experimentation purposes. To try out a notebook with Aerospike Graph capabilities, visit the [Graph Jupyter notebook](https://binder.aerospike.com/v2/gh/aerospike-examples/interactive-notebooks/sandbox-graph). The notebook uses the [air routes data set](https://github.com/krlawrence/graph/tree/master/sample-data).