Crate hedl_neo4j 

Bidirectional conversion between HEDL documents and Neo4j graph databases.

This crate provides functionality to:

• Export HEDL documents to Cypher queries for Neo4j import
• Import Neo4j graph data back to HEDL documents

Mapping Strategy

HEDL → Neo4j

HEDL Concept	Neo4j Representation
MatrixList type	Node label
Node ID	_hedl_id property (configurable)
Node fields	Node properties
Reference (@Type:id)	Relationship to target node
NEST hierarchy	HAS_<CHILDTYPE> relationships
Tensor	JSON string property
Expression	String property with $() preserved

Neo4j → HEDL

Neo4j Concept	HEDL Representation
Node label	Struct type / MatrixList type
Node properties	Field values
Relationship	Reference field or NEST hierarchy
HAS_* relationship	Inferred NEST

Example: Export to Cypher

use hedl_core::Document;
use hedl_neo4j::{to_cypher, ToCypherConfig};

fn example(doc: &Document) -> Result<(), hedl_neo4j::Neo4jError> {
    // Using default configuration
    let cypher = hedl_neo4j::hedl_to_cypher(doc)?;
    println!("{}", cypher);

    // With fluent configuration API
    let config = ToCypherConfig::new()
        .with_create()  // Use CREATE instead of MERGE
        .with_id_property("nodeId")
        .without_constraints();

    let cypher = to_cypher(doc, &config)?;
    println!("{}", cypher);

    // With builder pattern
    let config = ToCypherConfig::builder()
        .use_merge(false)
        .create_constraints(false)
        .id_property("nodeId")
        .batch_size(500)
        .build();

    let cypher = to_cypher(doc, &config)?;
    println!("{}", cypher);

    Ok(())
}

Example: Import from Neo4j

use hedl_neo4j::{Neo4jRecord, Neo4jNode, Neo4jRelationship, neo4j_to_hedl};

fn example() -> Result<(), hedl_neo4j::Neo4jError> {
    // Build records from Neo4j query results
    let records = vec![
        Neo4jRecord::new(
            Neo4jNode::new("User", "alice")
                .with_property("name", "Alice Smith")
        ).with_relationship(
            Neo4jRelationship::new("User", "alice", "HAS_POST", "Post", "p1")
        ),
        Neo4jRecord::new(
            Neo4jNode::new("Post", "p1")
                .with_property("content", "Hello World")
        ),
    ];

    let doc = neo4j_to_hedl(&records)?;
    println!("Imported {} structs", doc.structs.len());

    Ok(())
}

Generated Cypher Format

The generated Cypher uses best practices for Neo4j imports:

• Constraints: Creates uniqueness constraints for ID properties
• UNWIND batching: Uses UNWIND for efficient bulk operations
• MERGE by default: Uses MERGE for idempotent imports
• Parameterized queries: Returns statements with parameters for security

Example output:

// Ensure unique User IDs
CREATE CONSTRAINT user__hedl_id IF NOT EXISTS FOR (n:User) REQUIRE n._hedl_id IS UNIQUE;

// Create User nodes from users
UNWIND $rows AS row
MERGE (n:User {_hedl_id: row._hedl_id})
SET n.name = row.name;

// Create AUTHOR relationships from Post to User
UNWIND $rows AS row
MATCH (from:Post {_hedl_id: row.from_id})
MATCH (to:User {_hedl_id: row.to_id})
MERGE (from)-[rel:AUTHOR]->(to);

Re-exports

pub use config::BatchSizeStrategy;

pub use config::FromNeo4jConfig;

pub use config::FromNeo4jConfigBuilder;

pub use config::IsolationLevel;

pub use config::ObjectHandling;

pub use config::RelationshipNaming;

pub use config::ToCypherConfig;

pub use config::ToCypherConfigBuilder;

pub use config::TransactionStrategy;

pub use config::DEFAULT_FROM_NEO4J_BATCH_SIZE;

pub use config::DEFAULT_MAX_STRING_LENGTH;

pub use config::DEFAULT_TRANSACTION_BATCH_SIZE;

pub use config::DEFAULT_TRANSACTION_ROW_LIMIT;

pub use cypher::CypherScript;

pub use cypher::CypherStatement;

pub use cypher::CypherValue;

pub use cypher::RenderMode;

pub use cypher::StatementType;

pub use error::Neo4jError;

pub use error::Result;

pub use from_neo4j::build_record;

pub use from_neo4j::build_relationship;

pub use from_neo4j::from_neo4j_records;

pub use from_neo4j::from_records_iter;

pub use from_neo4j::from_records_streaming;

pub use from_neo4j::neo4j_to_hedl;

pub use from_neo4j::Neo4jRecord;

pub use from_neo4j::query_multi_label_batch;

pub use from_neo4j::query_nodes_batch;

pub use from_neo4j::query_nodes_with_relationships_batch;

pub use batch_read::BatchQuery;

pub use batch_read::BatchReadConfig;

pub use async_client::AsyncNeo4jClient;

pub use mapping::Neo4jNode;

pub use mapping::Neo4jRelationship;

pub use to_cypher::hedl_to_cypher;

pub use to_cypher::node_to_cypher_inline;

pub use to_cypher::to_cypher;

pub use to_cypher::to_cypher_statements;

pub use to_cypher::to_cypher_stream;

pub use batching::batch_statements;

pub use batching::TransactionBatch;

Modules

async_client

Async Neo4j client for executing HEDL operations. Async Neo4j client for executing HEDL operations.

batch_executor

Batch execution strategies for Neo4j write operations. Batch execution strategies for Neo4j write operations.

batch_read

Batch read operations for efficient Neo4j queries. Batch read operations for efficient Neo4j queries.

batching

Adaptive batching utilities for optimal memory and performance. Adaptive batching utilities for optimal memory and performance.

config

Configuration types for Neo4j conversion operations. Configuration types for Neo4j conversion operations.

constants

Constants used throughout the hedl-neo4j library. Constants used throughout the hedl-neo4j library.

cypher

Cypher query building utilities. Cypher query building utilities.

error

Error types for hedl-neo4j conversions. Error types for hedl-neo4j conversions.

from_neo4j

Convert Neo4j records to HEDL documents. Convert Neo4j records to HEDL documents.

mapping

Mapping between HEDL types and Neo4j graph structures. Mapping between HEDL types and Neo4j graph structures.

safe_arithmetic

Safe arithmetic operations for hedl-neo4j. Safe arithmetic operations for hedl-neo4j.

to_cypher

Convert HEDL documents to Cypher queries. Convert HEDL documents to Cypher queries.