Connect to NebulaGraph

NebulaGraph supports multiple types of clients, including a CLI client, a GUI client, and clients developed in popular programming languages. This topic provides an overview of NebulaGraph clients and basic instructions on how to use the native CLI client, Nebula Console.

NebulaGraph clients

You can use supported clients or console to connect to NebulaGraph.

Use Nebula Console to connect to NebulaGraph

Prerequisites

• You have started the NebulaGraph services. For how to start the services, see Start and Stop NebulaGraph.
• The machine you plan to run Nebula Console on has network access to the NebulaGraph services.

Steps

1. On the nebula-console page, select a Nebula Console version and click Assets.

   Note

   We recommend that you select the latest release.

   

2. In the Assets area, find the correct binary file for the machine where you want to run Nebula Console and download the file to the machine.

   

3. (Optional) Rename the binary file to nebula-console for convenience.

   Note

   For Windows, rename the file to nebula-console.exe.

4. On the machine to run Nebula Console, grant the execute permission of the nebula-console binary file to the user.

   Note

   For Windows, skip this step.

   $ chmod 111 nebula-console
   

5. In the command line interface, change the working directory to the one where the nebula-console binary file is stored.

6. Run the following command to connect to NebulaGraph.

   • For Linux or macOS:

   $ ./nebula-console -addr <ip> -port <port> -u <username> -p <password>
   [-t 120] [-e "nGQL_statement" | -f filename.nGQL]
   

   • For Windows:

   > nebula-console.exe -addr <ip> -port <port> -u <username> -p <password>
   [-t 120] [-e "nGQL_statement" | -f filename.nGQL]
   

   The description of the parameters is as follows.

   Option	Description
   -h	Shows the help menu.
   -addr	Sets the IP address of the graphd service. The default address is 127.0.0.1.
   -port	Sets the port number of the graphd service. The default port number is 9669.
   -u/-user	Sets the username of your NebulaGraph account. Before enabling authentication, you can use any existing username. The default username is root.
   -p/-password	Sets the password of your NebulaGraph account. Before enabling authentication, you can use any characters as the password.
   -t/-timeout	Sets an integer-type timeout threshold of the connection. The unit is second. The default value is 120.
   -e/-eval	Sets a string-type nGQL statement. The nGQL statement is executed once the connection succeeds. The connection stops after the result is returned.
   -f/-file	Sets the path of an nGQL file. The nGQL statements in the file are executed once the connection succeeds. You'll get the return messages and the connection stops then.

You can find more details in the Nebula Console Repository.

Nebula Console commands

Nebula Console can export CSV file, DOT file, and import too.

Note

The commands are case insensitive.

Export a CSV file

CSV files save the return result of a executed command.

Note

• A CSV file will be saved in the working directory, i.e., what linux command pwd show;

• This command only works for the next query statement.

The command to export a csv file.

nebula> :CSV <file_name.csv>

Export a DOT file

DOT files save the return result of a executed command, and the result information is different from CSV files.

Note

• A DOT file will be saved in the working directory, i.e., what linux command pwd show;

• You can copy the contents of DOT file, and paste in GraphvizOnline, to visualize the excution plan;

• This command only works for the next query statement.

The command to export a DOT file.

nebula> :dot <file_name.dot>

For example,

nebula> :dot a.dot
nebula> PROFILE FORMAT="dot" GO FROM "player100" OVER follow;

Importing a testing dataset

The testing dataset is named nba. Details about schema and data can be seen by commands SHOW.

Using the following command to import the testing dataset,

nebula> :play nba

Run a command multiple times

Sometimes, you want to run a command multiple times. Run the following command.

nebula> :repeat N

For example,

nebula> :repeat 3
nebula> GO FROM "player100" OVER follow;
+-------------+
| follow._dst |
+-------------+
| "player101" |
| "player125" |
+-------------+
Got 2 rows (time spent 2602/3214 us)

Fri, 20 Aug 2021 06:36:05 UTC

+-------------+
| follow._dst |
+-------------+
| "player101" |
| "player125" |
+-------------+
Got 2 rows (time spent 583/849 us)

Fri, 20 Aug 2021 06:36:05 UTC

+-------------+
| follow._dst |
+-------------+
| "player101" |
| "player125" |
+-------------+
Got 2 rows (time spent 496/671 us)

Fri, 20 Aug 2021 06:36:05 UTC

Executed 3 times, (total time spent 3681/4734 us), (average time spent 1227/1578 us)

Sleep to wait

Sleep N seconds.

It is usually used when altering schema. Since schema is altered in async way, and take effects in the next heartbeat cycle.

nebula> :sleep N

Disconnect Nebula Console from NebulaGraph

You can use :EXIT or :QUIT to disconnect from NebulaGraph. For convenience, Nebula Console supports using these commands in lower case without the colon (":"), such as quit.

nebula> :QUIT

Bye root!

FAQ

How can I install Nebula Console from the source code

To download and compile the latest source code of Nebula Console, follow the instructions on the nebula console GitHub page.

---

Last update: March 13, 2023