PROFILE

Generic Description

Execute the query and collect operator-level metrics.

Simple example:

PROFILE MATCH (p:Person) RETURN p

Consumer-Level Explanation

Use PROFILE when the query must execute the query and collect operator-level metrics and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

PROFILE is the runtime counterpart to EXPLAIN. It is for understanding where the real cost sits in a query: scans, expansions, aggregation, sorting, procedure output, or other operators.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after PROFILE must be clear
• it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
• planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Advanced Example

This example keeps PROFILE inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

PROFILE MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, d, cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, score
ORDER BY score DESC
LIMIT 10

Real Use Cases

• diagnosing slow queries
• comparing before/after optimization changes
• verifying where row explosion actually happens

Real Limitations And Tradeoffs

• it executes the query, so it is not free
• profiling mutations should be treated carefully in live contexts
• interpreting profile output still requires plan literacy