Command line interface

The easiest way to execute Cypher queries against Memgraph is by using Memgraph's command-line tool, mgconsole.

It is available as Docker image (opens in a new tab) and as a binary (opens in a new tab) for macOS, and Windows.

Install mgconsole

To install or start mgconsole to query a running Memgraph database instance, use the following steps:

You can use mgconsole on any OS from the Docker container. To connect to a remote Memgraph instance you need to provide the --host flag with the IP address or DNS name of the Memgraph instance and the --port flag with the port number, default 7687.

docker run -it memgraph/mgconsole:latest [--host HOST] [--port PORT]

If you want to connect to your local Memgraph instance, you can use the following command on Linux host:

docker run -it  memgraph/mgconsole:latest

If you are using MacOS or Windows, you can use the following command to start mgconsole:

docker run -it memgraph/mgconsole:latest --host host.docker.internal

On MacOS and Windows, host.docker.internal is a special DNS name that resolves to the host machine from a container. It is necessary to use it to connect to a Memgraph instance running on the host machine.

Execute Cypher queries

After the client has started, it should present a command 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>

At this point, it is possible to execute Cypher queries against a running Memgraph database instance.

💡

You can use the TAB key to autocomplete commands in mgconsole.

If you are new to Cypher, check out how to query the database.

Query execution time

Upon successful execution of a query, Memgraph will return the execution time.

To get a breakdown of the execution time, set the -verbose_execution_info flag to true.

It will extend the information about the execution time with the following data:

Query COST estimate: 3066
Query PARSING time: 0.000175982 sec
Query PLAN EXECUTION time: 0.0154524 sec
Query PLANNING time: 8.054e-05 sec

The 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

Below are configurational flags you can use with mgconsole:

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

If you want to use interactive mode with a mgconsole in a docker container, use the following command:

echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest

To save the query results in a file, use the following command:

echo "MATCH (n:Person) RETURN n;" | docker run -i memgraph/mgconsole:latest > results.txt