Command line interface
mgconsole is Memgraph’s command-line client. Use it to run Cypher queries against Memgraph from a terminal, interactively or from a script.
mgconsole is included in the memgraph/memgraph and memgraph/memgraph-mage
Docker images, and is available as a separate Docker
image, as a
binary for macOS and Windows, and
as source code for Linux.
Install mgconsole
If Memgraph runs in Docker, the quickest way to start mgconsole is inside the
Memgraph container. For a container named memgraph:
docker exec -it memgraph mgconsoleTo run mgconsole from its own image or from a binary, follow the steps for your environment:
The memgraph/mgconsole image runs on any operating system. Inside its
container, localhost is the container itself, so always tell mgconsole where
Memgraph is.
To connect to Memgraph on the same machine on macOS or Windows, use
host.docker.internal, which Docker Desktop resolves to the host:
docker run -it memgraph/mgconsole:latest --host host.docker.internalOn Linux, share the host’s network instead:
docker run -it --network host memgraph/mgconsole:latestTo connect to a remote Memgraph instance, pass its IP address or DNS name and
its port (default 7687):
docker run -it memgraph/mgconsole:latest --host HOST --port PORTHOST is the address of the Memgraph instance and PORT its Bolt port.
Execute Cypher queries
When mgconsole starts, it shows a prompt similar to:
mgconsole X.X
Connected to 'memgraph://127.0.0.1:7687'
Type :help for shell usage
Quit the shell by typing Ctrl-D(eof) or :quit
memgraph>Type a Cypher query, end it with ; and press Enter to run it. Press TAB
to autocomplete commands. If you are new to Cypher, see
Querying.
Query execution time
After a query succeeds, mgconsole prints its execution time. To get a
breakdown, start mgconsole with -verbose_execution_info=true. The output then
also shows:
Query COST estimate: 3066
Query PARSING time: 0.000175982 sec
Query PLAN EXECUTION time: 0.0154524 sec
Query PLANNING time: 8.054e-05 secThe values show:
- COST estimate - Internal planner estimation on the cost of the query. When comparing two query executions, an order of magnitude larger COST estimates might indicate the query’s longer execution time.
- PARSING time - Time spent checking if the query is valid and normalizing it for cache.
- PLAN EXECUTION time - Time executing the plan.
- PLANNING time - Time it takes the query planner to create the optimal plan to execute the query.
Configure mgconsole
Start mgconsole with these flags to configure it:
Main
| Flag | Description | Type | Default |
|---|---|---|---|
| -csv_delimiter | Character used to separate fields. | string | ”,” |
| -csv_doublequote | Controls how instances of the quotechar(”) appearing inside a field should themselves be quoted. When true, the character is doubled. When false, the escapechar is used as a prefix to the quotechar. If csv_doublequote is false, csv_escapechar must be set. | bool | true |
| -csv_escapechar | Character used to escape the quote character (”) if csv_doublequote is false. | string | "" |
| -fit_to_screen | Fit output width to screen width. | bool | false |
| -history | Use the specified directory to save history. | string | ”~/.memgraph” |
| -host | Server address. It can be a DNS resolvable hostname. | string | “127.0.0.1” |
| -no_history | Do not save history. | bool | false |
| -output_format | Query output format. Can be csv, tabular or cypherl. If the output format is not tabular fit_to_screen flag is ignored. cypherl can currently only be used with the DUMP DATABASE query. | string | “tabular” |
| -password | Database password. | string | "" |
| -port | Server port. | int32 | 7687 |
| -term_colors | Use terminal colors syntax highlighting. | bool | false |
| -use_ssl | Use SSL when connecting to the server. | bool | false |
| -username | Database username. | string | "" |
| -verbose_execution_info | Output the additional information about query such as query cost, parsing, planning and execution times. | bool | false |
Flags
| Flag | Description | Type | Default |
|---|---|---|---|
| -flagfile | Load flags from a file. | string | "" |
| -fromenv | Set flags from the environment [example: ‘export FLAGS_flag1=value’]. | string | "" |
| -tryfromenv | Set flags from the environment if present. | string | "" |
| -undefok | Comma-separated list of flag names. These flags can be specified on the command line even if the program does not define a flag with that name. IMPORTANT: Flags from the list that have arguments MUST use the flag=value format. | string | "" |
| -tab_completion_columns | The number of columns used in output for tab completion. | int32 | 80 |
| -tab_completion_word | If non-empty, HandleCommandLineCompletions() will hijack the process and attempt to do bash-style command line flag completion on this value. | string | "" |
Help
| Flag | Description | Type | Default |
|---|---|---|---|
| -help | Show help on all flags [tip: all flags can have two dashes]. | bool | false |
| -helpfull | Show help on all flags — same as -help. | bool | false |
| -helpmatch | Show help on modules, names of which contain the specified substring. | string | "" |
| -helpon | Show help on the modules named by this flag value. | string | "" |
| -helppackage | Show help on all modules in the main package. | bool | false |
| -helpshort | Show help on the main module for this program only. | bool | false |
| -helpxml | Produce an .xml version of help. | bool | false |
| -version | Show version and build info then exit. | bool | false |
Non-interactive mode
Pipe queries into the memgraph/mgconsole image. Add the same --host flag or --network host option as in Install mgconsole, for example on macOS or Windows:
echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest --host host.docker.internalTo save the query results in a file, use the following command:
echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest --host host.docker.internal > results.txt