Querying Your Graph

Tutorial

Querying Your Graph

Execute Cypher queries and work with results

30 min Intermediate

CypherQueriesResultsDataFrames

What You'll Learn

• Basic Queries - Execute MATCH and RETURN statements
• Parameters - Use parameterized queries safely
• Result Handling - Process query results as rows or DataFrames
• Aggregations - Use COUNT, SUM, COLLECT and other aggregations

Setup

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst

print(f"Connected | {conn.query_scalar('MATCH (n) RETURN count(n)')} nodes")

1

Basic Query Execution

Using conn.query()

# Basic query execution
result = conn.query("""
    MATCH (c:Customer)
    RETURN c.id AS name, c.bk_sectr AS sector
    ORDER BY c.id
    LIMIT 5
""")

result.show()

2

Parameterized Queries

Safe parameter passing

# Parameterized queries (safe from injection)
result = conn.query(
    "MATCH (c:Customer {id: $name}) RETURN c.bk_sectr AS sector",
    parameters={"name": "MR LAU XIAOMING"}
)
result.show()

# Never do this (Cypher injection risk):
# conn.query(f"MATCH (c) WHERE c.id = '{user_input}' RETURN c")

3

Working with Results

Rows, scalars, and DataFrames

# Get results as a Polars DataFrame
df = conn.query_df("""
    MATCH (a:Customer)-[:SHARES_ACCOUNT]->(b:Customer)
    RETURN a.id AS customer, b.id AS shares_account_with
    ORDER BY a.id
""")

df

4

Aggregation Queries

Counting, summing, collecting

# Get single value with query_scalar
total = conn.query_scalar("MATCH (c:Customer) RETURN count(c)")
print(f"Total customers: {total}")

# Multiple aggregations
result = conn.query("""
    MATCH (c:Customer)
    RETURN
        count(c) AS total,
        count(DISTINCT c.bk_sectr) AS sectors,
        count(DISTINCT c.acct_stus) AS id_types
""")
row = result.rows[0]
print(f"Customers: {row[0]}, Sectors: {row[1]}, ID types: {row[2]}")

Key Takeaways

• conn.query() executes Cypher and returns QueryResult
• Always use parameters for user input (prevents injection)
• query_df() returns Polars DataFrame for analysis
• query_scalar() returns single value for aggregations