Query Editor

Run your Query

To run your query, simply click on . G.V() will attempt running your query against your server, and display the results window indicating the output of your query. More information is available at Results View

You can have multiple queries specified in the same Query Editor. If there is more than one query in your editor, clicking on Run Query will run the query nearest to your mouse cursor. You can easily swap between queries to run by clicking on the query you would like to run before running it.

WARNING

When running your query, remember to specify a terminal step (e.g. toList, next, iterate). Not specifying the terminal step will allow the query to run, but will not extract any results.

Error Management

Using Apache TinkerPop™'s ANTLR grammar, G.V() will attempt to proactively warn of any syntax error in your query. Syntax errors in your query are highlighted in the code editor and listed below it. Note that at this moment, G.V() will not warn of any semantic error (e.g. using the select step with an unknown select key), but will in future versions.

Autocomplete Features

Using Apache TinkerPop™'s ANTLR grammar, G.V() will provide smart autocomplete suggestions as you're typing your query. Additionally, G.V() loads the structure of your graph data in the background and will make suggestions on Edge, Vertex and Property labels. Additionally when entering a specific step in your query, a Javadoc style popup will display above the line you're typing in showing the available parameters and variations of the step.

Translate a Query to a target Gremlin Language Variant

To translate your query directly to a target Gremlin Language Variant (GLV), click on and select your target language in the resulting modal window. Note that if there are any syntax errors in your query, this feature will be unavailable.

Debug Query

For more details, go to the Gremlin Query Debugging documentation.

Formatting using Gremlint

To format your query using Gremlint, click on

Fetch All Edges Between Vertices

By default, when fetching vertices only from your Gremlin Server, the resulting graph visualisation will not include any edges. Toggling on will cause all edges found between resulting vertices to also be returned, allowing for a more useful graph visualisation experience. This is equivalent to adding the .bothE() step to your graph traversal when it returns vertices.

Fetch Vertex Meta Properties

By default, when fetching vertices, only direct properties will be returned by your Gremlin Server. For convenience purposes, toggling on will automatically append any meta properties on vertices returned by your query. Note that this is modifying the results of your query and therefore doesn't represent the effective response returned by Gremlin Server, but it allows to quickly visualize the entire data appended to your vertices.

Console Mode / Groovy Mode

If enabled, submits your query as a script using Gremlin Client as opposed to running it as bytecode.

This is primarily useful to submit scripts that aren't Gremlin queries (e.g. JanusGraph Schema Management commands). This may also be useful in situations where your server implementation contains custom code that doesn't bundle with the default Apache TinkerPop code, to prevent serialisation issues. This may also be required to submit complex lambdas. This option is off by default and can be toggled by clicking on

In Console Mode, G.V() will not attempt to parse the results beyond just their console output. In Groovy Mode, G.V() will still parse the output as it would for a regular query, meaning this can be used to output a Graph display. Groovy Mode is intended for users that need to run complex scripts with functions whilst needing the full output display that G.V() offers for query results.

TIP

This option is not applicable to Azure Cosmos DB/Azure Cosmos DB Emulator which does not support Bytecode, nor G.V()'s Playground where custom code/serialization is not applicable. Amazon Neptune also does not need this feature as you custom groovy scripts cannot be submitted to their Gremlin endpoint.

TIP

When using Console Mode or Groovy Mode, autocomplete features and syntax checking are both disabled as G.V() does not support autocomplete for provider specific server language feature (e.g. JanusGraph Schema Management API)

Default Results Tab

Located at the bottom right of the query editor, this option allows you to choose which Output tab to default to once the query is run. If the query you're running does not output a result that satisfies the conditions of the default results tab, it will default to the Query Output. The output tab options are:

• Default (automatically detects which output tab to use)
• Graph View
• Large Graph View
• Vertex View
• Edge View
• Profile View
• Traversal Explanation

View Query History

To view previous queries run in your query editor, click on . The query history view allows to to navigate previously ran queries.

Toggle Editor Autocomplete Suggestions

Autocomplete popups can be dismissed by pressing the Escape key or clicking away from them. Alternatively, they can be enabled/disabled on an editor by clicking on . The default value for this setting when opening a new query editor is determined by the Enable Query Editor Smart Autocomplete setting in the Application Settings

Keyboard Shortcuts

The following keyboard shortcuts are currently available on the query editor:

• Ctrl+Space: Toggle Autocomplete
• Escape: Close Autocomplete Window
• Alt+Enter: Submit Query
• Ctrl+F: Format Query
• Ctrl+T: Translate Query
• Ctrl-S: Save Query
• Ctrl-W: Close Query

You can view the currently available keyboard shortcuts directly from the query editor by clicking the icon.

TIP

For macOS users, you can also substitute Ctrl with Cmd.

Save a Query

To save your query, click on . If you haven't previously saved your query, you will also be prompted to specify a name for it. If your query can be saved, this will be signified by a * displayed next to the query's name.

When saving a query, all of the settings and variables set on the query will also be saved, this includes the value of:

• Fetch All Edges Between Vertices
• Fetch Vertex Meta Properties
• Console Mode
• Default Results Tab

When saving a query, you will be prompted with a choice to save it either locally on your G.V() installation, or remotely against the database itself for other users to access (with the exception of G.V() Playground queries which can only be saved locally).

TIP

G.V() will automatically remember all the queries you've previously opened. You can safely close G.V() and return to your queries when you next re-open the application.

How does Remote Query Saving Work?

When saving a query remotely, G.V() will create a vertex directly against your database containing the details of the query as input on G.V(). When a user connects to the same database using G.V(), the same queries will be pulled down from the database and available to the user from the connection sidebar. This feature allows you to create for instance pre-defined reports and queries that can be accessed and managed centrally by all users connecting to your graph database via G.V().

Details

Remote Queries will be saved under the gdotv_query vertex label and contain the following properties:

• gdotv_id: String
• gdotv_schemaVersion: Integer
• gdotv_name: String
• gdotv_description: String
• gdotv_query: String
• gdotv_folderId: String
• gdotv_extendEdgeResults: Boolean
• gdotv_fetchMetaProperties: Boolean
• gdotv_variablesJson: String
• gdotv_outputTab: String
• gdotv_consoleMode: Boolean

All properties use a cardinality of "single".

TIP

For Azure Cosmos DB, G.V() will also automatically add a property to the gdotv_query vertex that corresponds to your collection's partition key and assigns a randomly generated value to it.

TIP

For JanusGraph, if using schema constraints, you will first need to run a schema definition for the gdotv_query label. G.V() will automatically detect if the configured constraints are available and if not prompt you with a script that you can either run from G.V() directly or copy to run from your own tooling.

WARNING

Remote Gremlin Queries are currently not supported for DataStax Enterprise Graph

Updating or Deleting a Remote Query

When updating or deleting a remote query from your database, the update/deletion will take effect for all users that are using G.V() against the same database. G.V() refreshes remote queries client-side every 5 minutes. You can trigger a refresh or remote queries and folders by clicking on on the Connections sidebar.

WARNING

If you drop your entire database (or the gdotv_query vertices) then the queries will no longer be available on G.V(). You should follow your usual data backup processes to ensure queries can be recovered if accidentally deleted.

Uploading an existing Local Query to your Remote Database

If you already have a collection of queries saved locally that you want to make available directly on your database, simply click the icon. Your query will be saved remotely on your database and the local version will be deleted.

Organize your Queries Into Folders

G.V() allows you to organize your queries into folders. You can manage folders from the Connection side menu. From there, you can perform the following folder actions:

• Create a new folder
• Delete a folder
• Move a folder into another
• Move a query to a folder

Additionally when saving a query, you will be given the option to choose a folder to save the query to. Optionally, you can save your folder remotely against your database by clicking on before saving your new folder.

TIP

You cannot add a local query to a remote folder, nor a local folder to a remote folder, and vice versa.

How does Remote Folder Saving Work?

When saving a folder remotely, G.V() will create a vertex directly against your database containing the details of the folder as input on G.V(). When a user connects to the same database using G.V(), the same folders will be pulled down from the database and available to the user from the connection sidebar. This feature allows you to create for instance organized reports into folders that can be accessed and managed centrally by all users connecting to your graph database via G.V().

Details

Remote Folders will be saved under the gdotv_folder vertex label and contain the following properties:

• gdotv_id: String
• gdotv_schemaVersion: Integer
• gdotv_name: String
• gdotv_folderId: String

All properties use a cardinality of "single".

TIP

For Azure Cosmos DB, G.V() will also automatically add a property to the gdotv_query vertex that corresponds to your collection's partition key and assigns a randomly generated value to it.

TIP

For JanusGraph, if using schema constraints, you will first need to run a schema definition for the gdotv_query label. G.V() will automatically detect if the configured constraints are available and if not prompt you with a script that you can either run from G.V() directly or copy to run from your own tooling.

WARNING

Remote Gremlin Queries are currently not supported for DataStax Enterprise Graph

About the gdotv_query and gdotv_folder vertex labels

Both the gdotv_query and gdotv_folder vertex labels will be purposefully ommitted from graph visualizations and the data model editor. This is to ensure that your graph visualization experience is not impacted by the existence of these special labels on your database. You can still query those labels from your database but they will be made less prominent in all result views.

Text to Gremlin

G.V() offers an experimental OpenAI integration that allows generating Gremlin queries via the OpenAI API.

The prompt G.V() sends to the OpenAI API contains details of your graph database's data model to give it the best chance of generating a Gremlin query that will work for your graph database.

It is therefore important to understand first and foremost that when using this feature, you will be sending details of the structure of your data to the OpenAI API, but not any of the data itself contained within your database itself.

For a reference of what information is generated as part of G.V()'s data model, please refer to the Data Model Management documentation.

When converting a text prompt to a Gremlin Query, you will be offered two options:

• OpenAI Prompt: The text prompt to send to the OpenAI API to be converted to a Gremlin query
• Query Output Format: The output format for the query that the OpenAI API will generate. Currently can be set to Raw, which lets the OpenAI API decide on the appropriate format to use, of Graph, which adds additional information in the prompt to force the OpenAI API to generate a query that will output in a format that leads to a graph visualisation in G.V().

TIP

This is an experimental feature. OpenAI is an evolving tool that is getting increasingly better at generating accurate Gremlin queries, but will not always get it right. If a generated query does not meet the criteria of your prompt, try and make your prompt more detailed.

TIP

The OpenAI API will have information of your graph's data model and therefore understand language that is derivative or synonym to the labels and property keys available in your graph database. Your prompt should include keywords that match your graph database's labels and property keys. Here are some examples of prompts:

• get all countries with at least 50 airports
• show all payments made to account 0008-7960-9302-7255 and the merchants for the transactions
• show all payments made to account 0008-7960-9302-7255 and the ip addresses in the transactions

Query Variables

You can set variables in your Gremlin Query to allow running reports against your databases based on simple configurable prompts. Query variables can be entered instead of any parameter to any step in your query. The naming convention for variables is as follows:

{{ variable_name }}

TIP

Variable tags should not be enclosed in quotes as they will otherwise not be recognized. If your variable value should be enclosed in quotes, you can either enter its value between quotes OR toggle the "Enclose In Quotes" option.

When you enter add a variable to your query it will then automatically display in the Gremlin Query Assistant on the right handside of the query editor. Your query can have as many variables as it needs and you can enter the same variable names in multiple places. See below an example of a query with variables:

g.V().
  has('code', {{ source_airport }}).
  repeat(outE().inV().simplePath()).until(has('code', {{ target_airport }})).
  path().
  limit({{ maximum_paths }})

This query contains three variables:

• source_airport
• target_airport
• maximum_paths

The variables can then be configured from the Gremlin Query Assistant, as shown below:

When entering a value for your variable, G.V() will replace the variable tag with the value you've specified as is. You can set the variable value to be enclosed in quotes by clicking (instead of entering the value including quotes). There are multiple additional settings you can set on your variable by clicking on . You'll be presented with two more options:

• Default variable value: the value the variable should be set to if no value is specified when running the saved query as a report.
• Variable label: the label to be displayed above the variable's input when running the saved query as a report. Both options above are meant to customize the report running experience for users you may deploy the report to.

Looking back at our example above, we will use the following configuration and values:

• source_airport, Enclose in Quotes enabled, value: JFK
• target_airport, Enclose in Quotes enabled, value: GLA
• maximum_paths, Enclose in Quotes disabled, value 5

This will result in the following query being run:

g.V().
  has('code', "JFK").
  repeat(outE().inV().simplePath()).until(has('code', "GLA")).
  path().
  limit(5)

When saving your query, either remotely or locally, your variable settings will also be saved and made available to other users of your database wishing to run the query.

Running a report

If you have saved a query, you can then choose to run it as a report. This is particularly useful if you're saving your query remotely on the database for other users of your graph to access or if you are using query variables in your query. To run a query as a report, select Run Query from the dropdown of options on your saved query in the connection sidebar, as shown below:

If your query contains no variables, it will immediately run and display the output in fullscreen mode. Otherwise, you will be prompted to enter the query variables' values. Looking back at our previous example, we get the following prompt:

Once you fill in the variable values (or use the default values, if available), click on Run Query to view the report results. In our example above, this next screenshot shows a sample result against our dataset for source_airport=GLA, target_airport=JFK and maximum_paths=5:

You can open any number of report tabs for the same query, or you can edit and re-run your report by clicking on "Edit Report Parameters".