Run prepared Cypher statements

Just like we have SQL injection in relational databases, we can also have Cypher injection in graph databases. This is when a user can manipulate the query to execute arbitrary code that can threaten the integrity of the data. As a best practice, it’s generally to provide parameters to your Cypher queries instead of using string literals in your code.

This section shows to run prepared Cypher statements with parameters while working with a client API in Kùzu.

Why use parameters?

Consider a scenario where you want to retrieve all persons in a database who are older than a certain age. Instead of hardcoding the age value into a Cypher query, it would make more sense to pass it as a parameter to the query, so that the same query can be reused for other values.

Another situation where parameters are useful is when you want to loop through a list of records and write each record to the database. Because records may have differnt values for a given property, it’s a good idea to use parameters to provide the values dynamically.

Syntax

Parameterized variables in Cypher are marked using the $ symbol. The below query asks for only persons who are between a minimum and maximum age in the database. In the Python API, the example shows how to specify the parameters as a dictionary in the parameters argument of the execute method of the connection object.

✅ Recommended

The $min_age and $max_age variables in the Cypher query are mapped to the min_age and max_age keys in the parameters dictionary, which then retrieve the values from the declared Python variables.

min_age = 18
max_age = 30

conn.execute(
    """
    MATCH (p:Person)
    WHERE p.age > $min_age and p.age < $max_age
    RETURN p.name
    """,
    parameters={"min_age": min_age, "max_age": max_age}
)

If you’re working with other client APIs, similar principles apply.

❌ Not recommended

Although it’s possible to pass the min_age and max_age variables directly into the query as string literals, this is strongly discouraged in practice.

min_age = 18
max_age = 30

conn.execute(
    f"""
    MATCH (p:Person)
    WHERE p.age > {min_age} and p.age < {max_age}
    RETURN p.name
    """
)