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

NebulaGraph Database Developer Edition GQL FAQ

Find answers to common questions about using GQL in NebulaGraph Database Developer Edition.

Graphs and queries

Must graph algorithms run on temporary graphs?

Not always. It depends on the operations performed by the algorithm or procedure:

  • Ordinary GQL queries and some procedures can run on persistent graphs. For example, the built-in algo.subgraph procedure requires the name of a persistent graph.
  • Match computation can only run on temporary graphs. Therefore, a custom procedure containing match computation statements such as MATCH ... PER PATH or MATCH ... PER NODE must be called on a temporary graph.
  • Node-attached aggregator value variables and active set variables can also be used only with the same temporary graph on which the procedure is called.

In short, a procedure is a container for statements. The statements in the procedure determine whether a temporary graph is required. For more information, see Match computation, Procedures, and algo.subgraph.

What is a cross-graph query?

A cross-graph query accesses multiple graphs in one GQL request and combines the tabular or scalar values produced by those graphs. It usually uses multiple USE clauses to switch graphs and NEXT, UNION, or variables to pass or combine results.

For example, the following query reads graph_a and graph_b and combines their results:

USE graph_a
MATCH (v:player)
RETURN v.name AS name

UNION ALL

USE graph_b
MATCH (v:player)
RETURN v.name AS name

You can also use USE inside a VALUE {} or EXISTS {} subquery to switch graphs. The following query returns users in graph_a that also exist in graph_b:

USE graph_a
MATCH (a:player)
WHERE EXISTS {
  USE graph_b
  MATCH (b:player)
  WHERE b.id = a.id
  RETURN b
}
RETURN a.id

To retrieve a single value from another graph, use VALUE {}:

USE graph_a
MATCH (a:player)
RETURN a.id,
       VALUE {
         USE graph_b
         MATCH (b:player)
         WHERE b.id = a.id
         RETURN b.name
         LIMIT 1
       } AS name_in_graph_b

The subquery must use USE to specify the graph to access. If USE is omitted, the subquery continues to use the working graph of the outer query. VALUE {} must return a single value, whereas EXISTS {} returns a Boolean indicating whether the subquery result is non-empty.

A cross-graph query does not mean that an edge can span two graphs. In a linear query connected by NEXT, if the preceding statement outputs a graph element variable to the next statement, you cannot use that variable to bind a graph element from another graph after switching graphs. Each UNION branch has an independent variable scope, so variable names can be reused as shown in the preceding example. To associate data from two graphs, pass properties such as names or business IDs and use different graph element variables in different graphs. For more information, see USE and Subquery expressions.

Why do I get Current working graph not found?

No working graph is set for the current session, and the query does not specify one with USE.

Add USE <graph_name> at the beginning of the query, or run SESSION SET GRAPH <graph_name> to set the default graph for the session. Use SHOW CURRENT_GRAPH to view the current working graph. For more information, see SESSION SET GRAPH and SHOW CURRENT_GRAPH.

What is the difference between v.id and element_id(v)?

  • v.id reads the business property named id from vertex v. It is defined by the user and is preferred in query results and documentation examples.
  • element_id(v) returns the internal ID maintained by NebulaGraph Database Developer Edition for a graph element. Use it only when the internal identifier is explicitly required.

Except when demonstrating internal-ID functions such as element_id(), queries and examples should return business properties. This makes results easier to understand and avoids dependencies on internal implementation details. For more information, see Graph element functions.

Statements and variables

What is the difference between an ordinary MATCH and match computation?

An ordinary MATCH finds data that conforms to a pattern. In NebulaGraph Database Developer Edition, it can query either a persistent graph or a temporary graph and usually returns the result with RETURN.

Match computation uses MATCH ... PER PATH or MATCH ... PER NODE to perform iterative computation over paths or vertices in a temporary graph. It can run only on a temporary graph. For more information, see MATCH and Match computation.

Why is a variable unavailable after NEXT?

NEXT passes the output table of the preceding statement to the next statement. It does not pass every variable defined by the preceding statement. Before NEXT, use RETURN to explicitly output every value needed by the following statement.

For more information, see LET and NEXT.

Procedures and data import

Why does a procedure call require a final output?

A query that calls a named procedure must end with RETURN or FINISH. YIELD selects columns produced by the procedure; it is not the final output of the entire query.

For more information, see Calling a procedure with CALL.

Why can't data be imported into a temporary graph?

Common causes include:

  • When importing an entire graph from NebulaGraph Database Developer Edition, the source graph type definition does not match the temporary graph type definition.
  • When importing an entire graph or selected nodes or edges from NebulaGraph Database Developer Edition, the source graph and target temporary graph run on the same Graph service.
  • When importing from a file or table variable, or importing only selected node or edge types from NebulaGraph Database Developer Edition, an edge type in the temporary graph does not declare MULTIEDGE KEY().
  • A node type's primary key structure, an edge type's topology, or property types do not satisfy the target graph type definition.
  • A property declared NOT NULL without a default value is not mapped, or column names and property mappings referenced by the import statement are incorrect.

First inspect the temporary graph type, and then compare its definition with the columns and properties in the imported data. For more information, see IMPORT and Persistent graphs and temporary graphs.