Skip to main content

How to return results

You can use the methods return_(), limit(), skip() and order_by() to construct queries that will return data from the database.

  • return_(results: Optional[Union[str, Tuple[str, str], Dict[str, str], List[Union[str, Tuple[str, str]]], Set[Union[str, Tuple[str, str]]]]] = None) - Return data from the database with aliases formatted as key AS value.
  • limit(integer_expression: Union[str, int]) - Limits the number of returned results equal to integer_expression.
  • skip(integer_expression: Union[str, int]) - Skip the number of results to be returned equal to integer_expression.
  • order_by(properties: Union[str, Tuple[str, Order], List[Union[str, Tuple[str, Order]]]]) - Order the returned results either descending or ascending.

Return all variables from a query​

To return all the variables from a query, just use the return_() method at the end of your query:

from gqlalchemy import Match

query = Match().node(labels="Person", variable="p").return_().execute()

Return specific variables from a query​

To return only a subset of variables from a query, specify them in the return() method:

from gqlalchemy import Match

query = Match()
        .node(labels="Person", variable="p1")
        .to()
        .node(labels="Person", variable="p2")
        .return_(results=[("p1", "first"), "p2"])
        .execute()

Limit the number of returned results​

To limit the number of returned results, use the limit() method after the return_() method:

from gqlalchemy import Match

query = match().node(labels="Person", variable="p").return_().limit(10).execute()

Order the returned results​

You can order the returned results by one or more values in an ascending or descending order. The default ordering in the Cypher query language is ascending (ASC or ASCENDING), and if you want the descending order, you need to add the DESC or DESCENDING keyword to the ORDER BY clause.

Order by one value​

To order the return results by one value, use the order_by(properties) method, where properties can be a string (a property) or a tuple of two strings (a property and an order).

The following query will order the results in an ascending (default) order by the property id of a node.

from gqlalchemy import Match

query = Match().node(variable="n").return_().order_by(properties="n.id").execute()

You can also emphasize that you want an ascending order:

from gqlalchemy import Match
from gqlalchemy.query_builders.memgraph_query_builder import Order

query = Match().node(variable="n").return_().order_by(properties=("n.id", Order.ASC).execute()

The same can be done with the keyword ASCENDING:

from gqlalchemy import Match
from gqlalchemy.query_builders.memgraph_query_builder import Order

query = Match().node(variable="n").return_().order_by(properties=("n.id", Order.ASCENDING).execute()
info

Order is an enumeration class defined in the query_module.py. It will help you in adding the correct order. If you don't want to import it, you can use strings: "ASC", "ASCENDING", "DESC" or "DESCENDING".

To order the query results in descending order, you need to specify the DESC or DESCENDING keyword. Hence, the argument of the order_by() method must be a tuple.

from gqlalchemy import Match
from gqlalchemy.query_builders.memgraph_query_builder import Order

query = Match().node(variable="n").return_().order_by(properties=("n.id", Order.DESC).execute()

Similarly, you can use Order.DESCENDING to get DESCENDING keyword in ORDER BY clause.

Order by a list of values​

To order the returned results by more than one value, use the order_by(properties) method, where properties can be a list of strings or tuples of strings (list of properties with or without order).

The following query will order the results in ascending order by the property id, then again in ascending (default) order by the property name of a node. After that, it will order the results in descending order by the property last_name, then in ascending order by the property age of a node. Lastly, the query will order the results in descending order by the node property middle_name.

from gqlalchemy import Match
from gqlalchemy.query_builders.memgraph_query_builder import Order

query = Match()
        .node(variable="n")
        .return_()
        .order_by(
            properties=[
                ("n.id", Order.ASC),
                "n.name",
                ("n.last_name", Order.DESC),
                ("n.age", Order.ASCENDING),
                ("n.middle_name", Order.DESCENDING),
            ]
        )

Hopefully, this guide has taught you how to return the query results. If you have any more questions, join our community and ping us on Discord.