Skip to content

vesoft-inc/nebula-console

Repository files navigation

NebulaGraph Console

This repository contains the NebulaGraph Console for NebulaGraph 3.x. NebulaGraph Console (Console for short) is a console for NebulaGraph. With Console, you can create a graph schema, import the demonstration basketballplayer dataset, and retrieve data.

Compatibility Matrix

Console version NebulaGraph Version
v2.0.1 2.0.x
v2.5.0 2.5.x
v2.6.0 2.6.x
v3.0.0 3.x
v3.1.x 3.x
v3.2.x 3.x
v3.3.x 3.x
v3.4.x 3.x
v3.5.x 3.x
v3.6.x 3.x
master nightly

Features

  • Supports interactive and non-interactive mode.
  • Supports viewing the history statements.
  • Supports autocompletion.
  • Supports multiple OS and architecture (We recommend Linux/AMD64).

How to Install

From Source Code

  1. Build NebulaGraph Console

    To build NebulaGraph Console, make sure that you have installed Go.

    NOTE: Go version provided with apt on ubuntu is usually "outdated".

    Run the following command to examine if Go is installed on your machine.

    $ go version

    The version should be newer than 1.13.

    Use Git to clone the source code of NebulaGraph Console to your host.

    $ git clone https://github.com/vesoft-inc/nebula-console

    Run the following command to build NebulaGraph Console.

    $ cd nebula-console
    $ make

    You can find a binary named nebula-console.

  2. Connect to NebulaGraph

    To connect to your Nebula Graph services, use the following command.

    $ ./nebula-console -addr <ip> -port <port> -u <username> -p <password>
        [-t 120] [-e "nGQL_statement" | -f filename.nGQL]
    Option Description
    -h Shows the help menu.
    -addr/-address Sets the IP/HOST address of the graphd service.
    -P/-port Sets the port number of the graphd service.
    -u/-user Sets the username of your NebulaGraph account. See authentication.
    -p/-password Sets the password of your NebulaGraph account.
    -t/-timeout Sets an integer-type timeout threshold for the connection. The unit is millisecond. 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.
    -enable_ssl Enable SSL when connecting to NebulaGraph
    -ssl_root_ca_path Sets the path of the certification authority file
    -ssl_cert_path Sets the path of the certificate file
    -ssl_private_key_path Sets the path of the private key file
    -ssl_insecure_skip_verify Controls whether a client verifies the server's certificate chain and host name

    E.g.,

    $./nebula-console -addr=192.168.10.111 -port 9669 -u root -p nebula
    2021/03/15 15:21:43 [INFO] connection pool is initialized successfully
    Welcome to NebulaGraph!

    Check options for ./nebula-console -h:

    • try ./nebula-console in interactive mode directly.

    • And try ./nebula-console -e 'show hosts' for the direct script mode.

    • And try ./nebula-console -f demo.nGQL for the script file mode.

From Binary

  • Download the binaries on the Releases page

  • Add execute permissions to the binary file of NebulaGraph

  • Connect to your NebulaGraph services:

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

Docker

Assumed we would like to run console in docker attached to NebulaGraph's docker-compose network, which is by default nebula-docker-compose_nebula-net and we would like to use the master console version: nightly.

note: we could replace nightly with i.e. v3.0.0 for specific console version.

Option 0: we could access the container's shell with nebulagraph console installed with:

$ docker run --rm -ti --network nebula-docker-compose_nebula-net --entrypoint=/bin/sh vesoft/nebula-console:nightly

And then call it like:

docker> nebula-console -u <user> -p <password> --address=<graphd> --port=9669

Option 1: or call console directly with:

docker run --rm -ti --network nebula-net vesoft/nebula-console:nightly -addr graphd -port 9669 -u root -p nebula

Console side commands:

NOTE: The following commands are case insensitive.

  • Export the result of the following statement to a csv file:
nebula> :csv a.csv
  • Export the execution plan in graphviz format to a dot file when profiling a statement with format "dot" or "dot:struct":
nebula> :dot a.dot
nebula> PROFILE FORMAT="dot" GO FROM "player102" OVER serve YIELD dst(edge);

You can paste the content in the dot file to https://dreampuf.github.io/GraphvizOnline/ to show the execution plan.

  • Export the execution plan in ASCII Table to a file when profiling a statement :
nebula> :profile profile.log
nebula> PROFILE GO FROM "player102" OVER serve YIELD dst(edge);
nebula> :explain explain.log
nebula> EXPLAIN GO FROM "player102" OVER serve YIELD dst(edge);
  • Load the demonstration basketballplayer dataset:
nebula> :play basketballplayer
Start loading dataset basketballplayer...

Load dataset succeeded!
  • Repeat to execute a statement n times, the average execution time will also be printed:
nebula> :repeat 3
  • Sleep for some seconds, it's just used in :play basketballplayer:
nebula> :sleep 3
  • Exit the console

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!

nebula> :EXIT

Bye root!

nebula> quit

Bye root!

nebula> exit

Bye root!

Keyboard Shortcuts

Key Binding Description
Ctrl-A, Home Move cursor to beginning of line
Ctrl-E, End Move cursor to end of line
Ctrl-B, Left Move cursor one character left
Ctrl-F, Right Move cursor one character right
Ctrl-Left, Alt-B Move cursor to previous word
Ctrl-Right, Alt-F Move cursor to next word
Ctrl-D, Del (if line is not empty) Delete character under cursor
Ctrl-D (if line is empty) End of File --- quit from the console
Ctrl-C Reset input (create new empty prompt)
Ctrl-L Clear screen (line is unmodified)
Ctrl-T Transpose previous character with current character
Ctrl-H, BackSpace Delete character before cursor
Ctrl-W, Alt-BackSpace Delete word leading up to cursor
Alt-D Delete word following cursor
Ctrl-K Delete from cursor to end of line
Ctrl-U Delete from start of line to cursor
Ctrl-P, Up Previous match from history
Ctrl-N, Down Next match from history
Ctrl-R Reverse Search history (Ctrl-S forward, Ctrl-G cancel)
Ctrl-Y Paste from Yank buffer (Alt-Y to paste next yank instead)
Tab Next completion
Shift-Tab (after Tab) Previous completion

TODO

  • CI/CD
  • batch process to reduce memory consumption and speed up IO