Step Reference
Every step of the DSL has a page of its own, listed in alphabetical order under this chapter in the sidebar and by category below. This page is the short guide to what every query shares: where it starts, how it runs, how much it returns and how it is shown.
g and __
g is the graph you query; a query starts with a start step on it, such as v() (vertices),
e() (edges) or inject(..) (values). __ starts an anonymous traversal: the child of a step
such as where, repeat, union or by, which runs once for every element that reaches it.
g.v().has_label("person").where(__.out("created")).values("name") // marko, josh, peter
Every step has a snake_case name and its Gremlin camelCase twin (has_label and hasLabel,
out_e and outE); they are the same function. Strings are written in double quotes, maps as
#{key: value}, lists as [1, 2]. Tokens are written with their class: P.gt(30),
Order.desc, T.label, Scope.local, Column.keys (see Predicates and
Functions, Tokens and Values).
Running a query
A query runs when it reaches a terminal. A query without one, at the end of a script, is run and shown (a table in the command line and the playground).
| Terminal | Returns |
|---|---|
to_list() | all results, as a list |
next() | the first result |
iterate() | nothing: runs the query for what it writes |
to_graph() | the edges reached and their vertices, as a graph |
profile() | the optimized plan with timings and counts |
execute() | results, error and profile together, never throws |
g.v().values("name").next() // marko
g.v().has("name", "marko").property("age", 30).iterate() // a write, nothing returned
Every query is one unit: when a step fails, nothing the query wrote stays (Transactions).
How many results
The data a query returns is never cut. To ask for less, use the steps that select a part:
limit(n), range(low, high), tail(n),
skip(n), dedup(), sample(n).
g.v().has_label("person").values("name").limit(2) // marko, vadas
g.v().has_label("person").values("name").range(1, 3) // vadas, josh
What is shown is bounded: a displayed result has at most 100 rows and 100 items per nested
list or map, with a notice when more exist. One query changes it with an argument of its
visualizer or a g.with() option; the command line has --max-rows, --max-items and
--no-limit (Displaying Results).
g.v().to_table(#{max_rows: 2}) // two rows and a notice that more exist
g.with("render.max_rows", 2).v().values("name") // the same for one query
Showing results
| Visualizer | Shows |
|---|---|
to_table() | a table (the default) |
to_markdown() | a Markdown table |
to_json() | JSON |
to_tree() | a tree of nested values |
to_mermaid(), to_plantuml(), to_json_schema() | a diagram or a JSON Schema of a schema, for example of infer_schema() |
visualize(V.Json) | any of them by token: V.Table, V.Markdown, V.Json, V.Tree, V.Mermaid, ... |
g.v().has_label("person").value_map("name", "age").to_markdown()
g.v().infer_schema().to_mermaid()
Options of one query
g.with(key, value) sets an option for the query that follows it: a time limit, the loop limit,
the display limits, the spelling of the profile, which optimizer rules run. Every key is in the
Execution Options Reference; a host can lock them
(Running Queries Safely).
g.with("evaluationTimeout", 1000).v().count() // stops after one second
g.with("repeat.max_loops", 10).v("1").repeat(__.out()).until(__.has("name", "ripple")).values("name")
Help inside the tools
The text of every step page is also where you write queries:
- in the REPL:
/help <name>(/help has_label,/help hasLabel),/help steps,/help tokens; - in the web playground: the completion of the query editor;
- over MCP: the
graphersal://dsl-referenceresource of the dev server.
Steps follow the Apache TinkerPop reference documentation unless a page says otherwise; the differences are collected in TinkerPop Deviations.
Steps by category
Start
Walking the graph
out · in · both · out_e · in_e · both_e · out_v · in_v · both_v · other_v · to_e · to_v · glob_path
Filters
has · has_id · has_key · has_label · has_not · has_p · has_value · has_value_any · has_value_p · is · where · where_p · where_t · filter · and · or · not · dedup · limit · range · skip · tail · coin · sample · simple_path · cyclic_path · none · discard · all · any
Values and properties
values · value_map · element_map · properties · id · label · labels · key · value · constant · element · json_path · index · identity
Strings and type conversion
to_lower · to_upper · trim · l_trim · r_trim · substring · replace · concat · format · split · length · as_string · as_bool · as_number · cast
Lists and ordering
fold · unfold · combine · conjoin · difference · disjunct · intersect · merge · product · reverse · order
Aggregation
count · sum · min · max · mean · median · group · group_count · tree · aggregate · store · cap · barrier
Labels and paths
as · select · path · project · math
Branches and loops
union · choose · branch · option · coalesce · optional · repeat · times · until · emit · loops · local · map · flat_map
Modulators and options
by · from · to · with · with_path · with_bulk
Sack and side effects
sack · with_sack · with_side_effect · side_effect · subgraph
Changing the graph
add_v · add_e · property · property_json · drop · remove_property · add_label · drop_label · set_label · merge_v · merge_e · fail
Running and showing results
to_list · next · iterate · execute · profile · profile_with · to_graph · to_table · to_json · to_markdown · to_tree · to_mermaid · to_plantuml · to_json_schema · visualize · set_visualizer
Schema
get_schema · set_schema · patch_schema · validate_schema · validate_schema_patch · infer_schema · diff_schema
Saved queries
define_query · define_queries · query · queries · get_query · drop_query · move_query · describe_query
Compressed properties
define_compression · drop_compression · compressions · recompress
Graph information and files
statistics · memory_usage · mark · import_graphml · import_graphson · export_graphml · export_graphson · export_snapshot
Predicates, tokens and test data
Predicates · Functions, Tokens and Values · Test Data Functions