Node/Relationship Properties, Orientation, Filtering, Graph Schema, and Projection Verification

Learning outcomes

1. The projection is the model the algorithm actually sees

AtlasMart has accumulated enough connected customer/product behavior that analysts want graph algorithms, but running “an algorithm” is not one operation. The analytical graph must first be selected, copied into a GDS representation, sized, verified, executed, and removed or refreshed deliberately. AtlasMart’s source graph contains customer segments, product margins, VIEWED and PURCHASED relationships. If the projection drops weights or reverses an edge, a perfectly implemented algorithm can still answer the wrong business question.

The safety rule for this chapter is therefore: treat projection definition, memory allocation, algorithm mode, and lifecycle as part of the analytical result. A score without those inputs is not reproducible evidence.

2. Properties: persisted source values become analytical inputs only if projected

GDS does not automatically expose every Neo4j property. Project only values the algorithm needs. Relationship properties used as weights must be supported numeric values; node properties used by downstream algorithms/features likewise need compatible types. A missing projected property is not “null from the database”—it is absent from the analytical schema.

3. Orientation changes graph semantics and memory

Do not choose UNDIRECTED merely because it “finds more.” Direction is part of the hypothesis. In a Customer→Product interaction graph, PageRank with NATURAL orientation largely transfers importance toward products; reversing it asks a different question.

4. Create and verify the full bounded schema

CYPHER 25
// Chapter 23 fixture: bounded and safe to delete by labTag.
CREATE CONSTRAINT ch23_customer_id IF NOT EXISTS
FOR (c:Customer) REQUIRE c.customerId IS UNIQUE;
CREATE CONSTRAINT ch23_product_id IF NOT EXISTS
FOR (p:Product) REQUIRE p.productId IS UNIQUE;

UNWIND [
 {id:'C-2301',segment:'LOYAL',value:92.0},
 {id:'C-2302',segment:'LOYAL',value:78.0},
 {id:'C-2303',segment:'NEW',value:35.0},
 {id:'C-2304',segment:'NEW',value:28.0},
 {id:'C-2305',segment:'B2B',value:96.0},
 {id:'C-2306',segment:'B2B',value:84.0}
] AS row
MERGE (c:Customer {customerId:row.id})
SET c.segment=row.segment,c.customerValue=row.value,c.labTag='ch23';

UNWIND [
 {id:'P-2301',name:'Trail Camera Pro',margin:0.31},
 {id:'P-2302',name:'Action Camera 4K',margin:0.27},
 {id:'P-2303',name:'Solar Trail Charger',margin:0.24},
 {id:'P-2304',name:'Indoor Security Camera',margin:0.29},
 {id:'P-2305',name:'Hydration Vest',margin:0.22},
 {id:'P-2306',name:'Wildlife Field Guide',margin:0.35}
] AS row
MERGE (p:Product {productId:row.id})
SET p.name=row.name,p.margin=row.margin,p.labTag='ch23';

MATCH (c:Customer {labTag:'ch23'}),(p:Product {labTag:'ch23'})
WITH c,p WHERE
 (c.customerId='C-2301' AND p.productId IN ['P-2301','P-2303','P-2306']) OR
 (c.customerId='C-2302' AND p.productId IN ['P-2301','P-2302']) OR
 (c.customerId='C-2303' AND p.productId IN ['P-2302','P-2305']) OR
 (c.customerId='C-2304' AND p.productId IN ['P-2304','P-2305']) OR
 (c.customerId='C-2305' AND p.productId IN ['P-2301','P-2303','P-2304']) OR
 (c.customerId='C-2306' AND p.productId IN ['P-2303','P-2306'])
MERGE (c)-[r:VIEWED]->(p)
SET r.weight = CASE c.segment WHEN 'LOYAL' THEN 2.0 WHEN 'B2B' THEN 1.5 ELSE 1.0 END,
    r.labTag='ch23';

MATCH (c:Customer {labTag:'ch23'}),(p:Product {labTag:'ch23'})
WHERE (c.customerId='C-2301' AND p.productId='P-2301') OR
      (c.customerId='C-2302' AND p.productId='P-2302') OR
      (c.customerId='C-2305' AND p.productId='P-2303') OR
      (c.customerId='C-2306' AND p.productId='P-2306')
MERGE (c)-[r:PURCHASED]->(p)
SET r.weight=3.0,r.labTag='ch23';


CALL gds.graph.exists('atlasmart-ch23') YIELD exists
WITH exists WHERE exists
CALL gds.graph.drop('atlasmart-ch23') YIELD graphName
RETURN graphName;


CALL gds.graph.project(
  'atlasmart-ch23',
  {
    Customer:{properties:['customerValue']},
    Product:{properties:['margin']}
  },
  {
    VIEWED:{orientation:'NATURAL',properties:['weight']},
    PURCHASED:{orientation:'NATURAL',properties:['weight']}
  },
  {readConcurrency:2}
)
YIELD graphName,nodeCount,relationshipCount,projectMillis,configuration
RETURN graphName,nodeCount,relationshipCount,projectMillis,configuration;
// Expected deterministic counts: nodeCount=12, relationshipCount=18.

CALL gds.graph.list('atlasmart-ch23')
YIELD graphName,nodeCount,relationshipCount,schemaWithOrientation,degreeDistribution,memoryUsage,configuration
RETURN graphName,nodeCount,relationshipCount,schemaWithOrientation,degreeDistribution,memoryUsage,configuration;

Acceptance criteria are structural: 12 nodes, 18 relationships, Customer/Product labels, VIEWED/PURCHASED relationship types, NATURAL direction, and projected numeric properties. The catalog listing is stronger evidence than an algorithm score because it proves the input contract.

5. Filtering is analytical scope, not source deletion

CALL gds.graph.exists('atlasmart-ch23') YIELD exists
WITH exists WHERE exists
CALL gds.graph.drop('atlasmart-ch23') YIELD graphName
RETURN graphName;


CYPHER 25
MATCH (source:Customer {labTag:'ch23'})-[r:VIEWED]->(target:Product {labTag:'ch23'})
WHERE source.segment IN ['LOYAL','B2B'] AND target.margin >= 0.24
RETURN gds.graph.project(
  'atlasmart-ch23', source,target,
  {
    sourceNodeLabels:['Customer'],
    targetNodeLabels:['Product'],
    sourceNodeProperties:{customerValue:source.customerValue},
    targetNodeProperties:{margin:target.margin},
    relationshipType:'VIEWED',
    relationshipProperties:{weight:r.weight}
  },
  {readConcurrency:2}
)
YIELD graphName,nodeCount,relationshipCount,projectMillis
RETURN *;
// Counts now prove projection scope, not source-store deletion.

CALL gds.graph.list('atlasmart-ch23')
YIELD graphName,nodeCount,relationshipCount,schemaWithOrientation,degreeDistribution,memoryUsage,configuration
RETURN graphName,nodeCount,relationshipCount,schemaWithOrientation,degreeDistribution,memoryUsage,configuration;

After the filtered projection, the transactional fixture still contains all Chapter 23 nodes and relationships. Only the in-memory analytical population changed. This distinction is crucial for cohort analysis: filters are a reproducible selection predicate, not a mutation of source truth.

6. Parallel relationships and aggregation are modeling choices

Neo4j can store multiple relationships between the same nodes. GDS native projection preserves parallel relationships by default. Some algorithms can use them directly; others require or benefit from aggregation. Native projection supports aggregation such as SINGLE, COUNT, SUM, MIN, or MAX depending on property configuration. Aggregation changes analytical topology/weights and must be treated as preprocessing, not a harmless optimization.

7. Deliberately wrong: use one undirected projection for every algorithm

Concrete problem: the algorithm now receives a different graph from the stored customer→product behavior. Relationship count/memory and degree distributions change, and a centrality score may measure reciprocal connectivity rather than directional influence. Repair: version projection names/configs by analytical intent and assert schemaWithOrientation before execution.

8. Verification checklist before any algorithm

Production judgment and bridge

The next lesson moves from logical correctness to resource correctness. Once the projection is semantically right, its memory, concurrency, lifetime and coexistence with the transactional workload must be proven.

Summary and next step

Node/Relationship Properties, Orientation, Filtering, Graph Schema, and Projection Verification is useful only when its assumptions and observed evidence stay attached to the decision. The examples above establish a reproducible mechanism and boundary; they do not turn one lab result into a universal production rule.

Next, continue to Estimate Memory, Control Concurrency, Manage Graph Lifecycles, and Avoid Production Memory Starvation. Carry forward the verified assumptions, fixture state, version/edition boundaries, and measurements from this lesson instead of treating the next topic as an isolated recipe.

Authoritative references

• GDS Manual v2026.07 — Current Graph Data Science manual and versioned feature baseline.
• GDS 2026.07 release notes — Current GDS release line; 2026.07.0 is compatible with Neo4j 2026.07.
• Supported Neo4j versions — Compatibility matrix between Neo4j Database and GDS.
• GDS editions and graph catalog — Community/Enterprise boundaries, graph catalog model, all-algorithms availability, concurrency and model-catalog limits.
• Neo4j Server GDS installation — Bundled products-to-plugins installation path and required GDS procedure security configuration.
• GDS on Docker — Container-based installation examples and plugin activation.
• System requirements — Heap/native-memory/CPU guidance and Community maximum concurrency of four.
• Native projection — Current gds.graph.project procedure, label/type/property/orientation configuration and lifecycle.
• Cypher projection — Current gds.graph.project aggregation-function projection from Cypher query context.
• Legacy Cypher projection — deprecated — Deprecated gds.graph.project.cypher procedure and migration boundary.
• Graph creation and schema — Supported projection types, relationship direction, properties, parallel relationships, and algorithm traits.
• Graph catalog operations — Current graph project/list/exists/drop and graph-property operations.
• Listing graphs — Graph metadata, schemaWithOrientation, degree distribution and configuration inspection.
• Memory estimation — Projection and algorithm estimate syntax, requiredMemory and byte-range evidence.
• Algorithm syntax and execution modes — stream/stats/mutate/write/estimate semantics.
• Running algorithms — Operational meaning and tradeoffs of algorithm execution modes.
• PageRank — Production-tier algorithm used only to demonstrate execution modes and memory estimates in this foundations chapter.
• Neo4j current versions — Current Neo4j Database release and 5.26 LTS line.