Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

Get started with GQL: Create a graph and run CRUD operations

Create a practice graph in the NebulaGraph Studio console and use GQL to define its structure, insert data, query relationships, update properties, and delete data. You will create two nodes representing Alice and Bob, and a directed relationship indicating that Alice knows Bob.

Before you start

Sign in to NebulaGraph Studio as root, then select CONSOLE in the top navigation bar. For other clients, see Use ngql or the built-in web console. You do not need to load the movie dataset.

This page creates graph type gql_practice_type and graph gql_practice. Both names must be available. To repeat the full exercise, choose new names.

Run the code blocks in order. Paste each statement into the query editor and select the run button. After it succeeds, replace the editor contents with the next statement. The result tables show the table view in NebulaGraph Studio, where strings appear in double quotation marks.

1. Define the graph structure

A graph type defines the allowed nodes, edges, and properties. A graph stores data that follows that type. This exercise uses the following structure:

Element Type Properties Purpose
Node Person id, name, age id uniquely identifies a Person node within the graph
Edge Knows since Connects one Person to another; since is the year they met

This page uses the default Schema /default_schema. A Schema is similar to a folder that organizes graph types and graphs.

Switch back to the default Schema

If you previously switched Schemas in the console, run this statement before creating the graph type:

SESSION SET SCHEMA /default_schema

Run this statement to create graph type gql_practice_type:

CREATE GRAPH TYPE gql_practice_type AS {
  NODE Person (LABEL Person {id INT64 PRIMARY KEY, name STRING, age INT32}),
  EDGE Knows (Person)-[:Knows {since INT32}]->(Person)
}

The statement uses these elements:

  • NODE Person defines a node type; EDGE Knows defines an edge type.
  • INT64 and INT32 are integer types; STRING is a string type.
  • PRIMARY KEY makes id the primary key. Two Person nodes in the same graph cannot have the same id.
  • LABEL Person and :Knows define the node and edge labels. In this example, each type and its label share the same name.

See Graph data concepts for more explanations.

Use ngql or the built-in web console

Follow the connection steps for ngql or the built-in web console. Skip the sample data loading steps, then run the statements on this page in the same client.

In ngql, place each ''' delimiter on its own line around a multiline statement. For example, enter the graph type definition as follows:

'''
CREATE GRAPH TYPE gql_practice_type AS {
  NODE Person (LABEL Person {id INT64 PRIMARY KEY, name STRING, age INT32}),
  EDGE Knows (Person)-[:Knows {since INT32}]->(Person)
}
'''

Enter the closing ''' and press Enter to submit. Use the same delimiters for the other multiline statements on this page. In ngql's default table output, strings such as Alice and Bob appear without surrounding quotation marks. The property values are the same as in this page's result tables.

In the built-in web console, paste multiline statements directly into the editor and select the run button.

2. Create and select the graph

Create a practice graph using the graph type:

CREATE GRAPH gql_practice TYPED gql_practice_type

Set it as the working graph for the current session so subsequent read and write statements access this graph:

SESSION SET GRAPH gql_practice
Reconnect or specify a graph for one statement

After reconnecting or switching clients, run SESSION SET GRAPH gql_practice again in the new session.

You can also use USE at the start of an individual read or write statement to specify its graph:

USE gql_practice
MATCH (p@Person)
RETURN p.name

USE applies only to that statement and does not change the session working graph. See USE.

3. Insert nodes and an edge

Insert Alice and Bob. Run each insert statement once, executing each code block separately:

INSERT (p@Person {id: 1, name: "Alice", age: 30})

INSERT (p@Person {id: 2, name: "Bob", age: 28})

@Person specifies the node type. The braces contain property names and values. p is a variable name within the statement; another statement can use a different variable name to refer to the same node.

Find these existing nodes and insert an edge between them:

MATCH (a@Person {id: 1}), (b@Person {id: 2})
INSERT (a)-[r@Knows {since: 2024}]->(b)

MATCH finds Alice and Bob by their primary keys and binds them to variables a and b. INSERT creates a Knows edge between the two nodes. The arrow points from Alice to Bob.

Repeated inserts

Do not repeat an insert that has already succeeded. Plain INSERT reports a conflict if a node with the same primary key, or a Knows edge with the same source and destination, already exists. See INSERT for other conflict handling options.

4. Query nodes and relationships

List the people in the graph

MATCH (p@Person)
RETURN p.id AS id, p.name AS name, p.age AS age
ORDER BY id

Expected result:

id name age
1 "Alice" 30
2 "Bob" 28

MATCH (p@Person) matches all Person nodes. RETURN selects the result columns, AS names them, and ORDER BY id sorts the rows by ID.

Filter by a property

Find people older than 28 by adding a WHERE condition:

MATCH (p@Person)
WHERE p.age > 28
RETURN p.name AS name, p.age AS age

Expected result:

name age
"Alice" 30

Follow a relationship

Find whom Alice knows and the year they met:

MATCH (a@Person {id: 1})-[r@Knows]->(b@Person)
RETURN a.name AS person,
       b.name AS friend,
       r.since AS known_since

Expected result:

person friend known_since
"Alice" "Bob" 2024

Parentheses represent nodes, and brackets represent an edge. Variable r refers to the edge, so r.since reads its property. This pattern starts from Alice and follows the direction of the Knows edge to its destination.

5. Update properties

Change Alice's age to 31:

MATCH (p@Person {id: 1})
SET p.age = 31

MATCH locates the node, and SET assigns a new property value. Query the node again after the update:

MATCH (p@Person {id: 1})
RETURN p.name AS name, p.age AS age

Expected result:

name age
"Alice" 31

Next, change the year Alice and Bob met to 2023:

MATCH (a@Person {id: 1})-[r@Knows]->(b@Person {id: 2})
SET r.since = 2023

Run the relationship query again. known_since should now be 2023. You cannot update the primary key property id with SET.

6. Delete the edge and a node

First, delete the Knows edge from Alice to Bob:

MATCH (a@Person {id: 1})-[r@Knows]->(b@Person {id: 2})
DELETE r

Run the relationship query again. It should no longer return that relationship. Both Alice and Bob still exist after the edge is deleted.

Then delete Alice. Plain DELETE can delete a node only when it has no connected edges, so delete the edge first as shown above:

MATCH (p@Person {id: 1})
DELETE p

Check the remaining nodes:

MATCH (p@Person)
RETURN p.id AS id, p.name AS name, p.age AS age
ORDER BY id

Only Bob should remain:

id name age
2 "Bob" 28

The graph gql_practice and graph type gql_practice_type remain available.

Delete a node and its connected edges together

If Alice and the edge still exist, this single statement can replace the two deletion steps in this section. Skip it if you have already completed those steps:

MATCH (p@Person {id: 1})
DETACH DELETE p

DETACH DELETE removes Alice and all of her connected edges while keeping Bob.

Repeat the exercise

To repeat the full exercise, choose graph type and graph names that have not been used. For example, replace the following names throughout the statements on this page, then start again from step 1:

Original name Name for the next exercise
gql_practice_type gql_practice_type_2
gql_practice gql_practice_2

To query the existing practice graph, first run SESSION SET GRAPH gql_practice, then run your queries. The data retains your earlier changes. After completing the deletion steps, only Bob remains, so queries will not return the initial results.

Next steps