GRAPH.QUERY

Executes the given query against a specified graph.

Arguments: Graph name, Query, [timeout], [--compact], [version]

Returns: Result set

Optional argument	Description
timeout	Query-level timeout in milliseconds. See the configuration section.
--compact	Returns results in compact format.
version	Graph version number. When provided, the server rejects the query with a version mismatch error if the current graph version doesn’t match, allowing clients to invalidate cached schema mappings.

Queries and Parameterized Queries

The execution plans of queries, both regular and parameterized, are cached (up to CACHE_SIZE unique queries are cached). Therefore, it is recommended to use parameterized queries when executing many queries with the same pattern but different constants.

Query-level timeouts can be set as described in the configuration section.

Command structure

GRAPH.QUERY graph_name "query" [timeout value] [--compact] [version value]

example:

python javascript rust java shell

graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p")

const result = await graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p");
console.log(result);

let result = graph.query(r#"MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"#).execute().await?;
println!("{:?}", result);

ResultSet result = graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p");
System.out.println(result);

GRAPH.QUERY us_government "MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"

Parameterized query structure:

GRAPH.QUERY graph_name "CYPHER param=val [param=val ...] query"

example:

python javascript rust java shell

graph.query("MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p", {'state_name': 'Hawaii'})

const result = await graph.query(
  "MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p",
  { params: { state_name: "Hawaii" } }
);
console.log(result);

let params = std::collections::HashMap::from([
    ("state_name", "Hawaii")
]);
let result = graph.query_with_params(
    r#"MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p"#,
    &params
).execute().await?;
println!("{:?}", result);

Map<String, Object> params = new HashMap<>();
params.put("state_name", "Hawaii");
ResultSet result = graph.query(
  "MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p",
  params
);
System.out.println(result);

GRAPH.QUERY us_government "CYPHER state_name='Hawaii' MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p"

Query language

The syntax is based on Cypher. Most of the language is supported. See Cypher documentation.

Frequently Asked Questions 5

Why should I use parameterized queries instead of string interpolation?

Parameterized queries allow FalkorDB to cache and reuse execution plans across queries that differ only in their constant values. This significantly improves performance. They also prevent Cypher injection attacks.

What happens when a query exceeds the timeout?

When a query exceeds the configured timeout (in milliseconds), it is terminated and an error is returned to the client. You can set timeouts per-query using the TIMEOUT argument, or globally via GRAPH.CONFIG SET TIMEOUT_DEFAULT and TIMEOUT_MAX.

What does the --compact flag do?

The --compact flag returns results in a compact format that uses internal IDs instead of string labels and property names. This reduces network bandwidth and is intended for use by client libraries that maintain their own schema cache.

What is the version parameter used for?

The version parameter enables optimistic schema caching. When a client provides a version number that does not match the current graph version, the server returns a version mismatch error, signaling the client to refresh its cached schema mappings.

Are execution plans cached automatically?

Yes. FalkorDB caches execution plans for up to CACHE_SIZE unique queries (configurable). Both regular and parameterized queries benefit from plan caching.