GRAPH.QUERY - FalkorDB Docs

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:

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);

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

let result = graph.query(r#"MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"#).execute().await?;
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:

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);

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);

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);

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

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.

​Queries and Parameterized Queries

​Command structure

​Parameterized query structure:

​Query language

​Frequently Asked Questions

Queries and Parameterized Queries

Command structure

Parameterized query structure:

Query language

Frequently Asked Questions