overlaps

Generic Description

Inspects or reshapes lists, maps, document-style payloads, or property containers. It is documented separately because list shape, map shape, and property-container behavior directly affect planner-visible row contracts.

Simple example:

WITH ['billing','migration'] AS ticket_tags RETURN ticket_tags OVERLAPS ['retention','billing'] AS route_to_billing

Consumer-Level Explanation

Use it when semi-structured values should stay inside the Cypher pipeline instead of being unpacked by client code. Prefer this function when the query should keep payload shaping close to graph matching instead of deferring interpretation to the client.

More Detailed Explanation

overlaps should be understood by the value shape it expects and the row shape it returns. It composes with MATCH, WHERE, WITH, RETURN, and procedure output, so planner-facing documentation should describe both the immediate value transformation and why it belongs in the database query.

Advanced Example

This example uses overlaps inside a named row pipeline so the value shape is clear to both the planner and reviewers.

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, e, d,
     d.metadata AS metadata,
     date_trunc('day', e.ts) AS day_bucket
WITH u, d, day_bucket,
     unpivot(metadata) AS metadata_rows,
     keys(metadata) OVERLAPS ['kind', 'category'] AS focused_value
RETURN u.user_id AS user_id,
       d.title AS document_title,
       day_bucket,
       metadata_rows,
       focused_value
ORDER BY user_id, document_title
LIMIT 10

Real Use Cases

Real Limitations And Tradeoffs