Monifold

Folds

system_integrations_neo4j_execute

Executes Neo4j Cypher queries with support for both single and batch operations, returning structured results and error handling.

details

ID: e37a4d91d2a6f0e9
URL: http://localhost:5173/v1/system/integrations/neo4j/execute
Version hash: 39d69a25fb2a6eb27b0eb36d398d8648cc7248539af43beae224d4bfa8683ca6

details

ID: e37a4d91d2a6f0e9
URL: http://localhost:5173/v1/system/integrations/neo4j/execute
Version hash: 39d69a25fb2a6eb27b0eb36d398d8648cc7248539af43beae224d4bfa8683ca6

No metrics yet.

Acceptance criteria

Must accept a valid Cypher query via the 'payload.query' field and execute it successfully against the Neo4j database when the query is syntactically and semantically correct.
Must properly handle optional 'payload.params' as query parameters using Neo4j's parameterized query mechanism, ensuring that user-supplied values are safely bound and not subject to injection attacks.
When a query executes successfully, must output an array of query result objects, where each object contains 'query', 'params', and 'results' properties, matching the expected structure of Neo4j's result format.
If the Cypher query contains a syntax or semantic error (e.g., invalid Cypher statement), must return an error message in 'payload.error' that clearly describes the nature of the failure.
If the Neo4j database connection fails or is unreachable, must return a descriptive error message in 'payload.error' indicating the connectivity issue, rather than silently failing.
Must reject or handle invalid input (e.g., missing 'payload.query' or malformed 'payload.params') by setting 'payload.error' to a meaningful message and not attempting to execute a query.
Must not expose sensitive information (like database credentials or internal error stack traces) in the 'payload.error' output, maintaining security best practices.
Must preserve the original structure of the query results (e.g., multiple records, nested objects) without unintended transformation or data loss.
Must support query types that return both single records and multiple records (e.g., MATCH, CREATE, MERGE), ensuring consistent handling of diverse Cypher operations.
After successful execution, must not modify the original input payload beyond the expected output structure, preserving immutability where intended.
Must support both single query objects and arrays of query objects in the payload, maintaining consistent input validation for both formats.
For batch operations, must return HTTP status 200 when all queries succeed, 207 when some queries succeed and others fail, and appropriate 4xx/5xx codes when all queries fail or system errors occur.
Must maintain consistent output format with an array of query result objects for successful operations and error objects for failed operations, ensuring predictable response structure.

13 item(s)

Out of scope

0 item(s)

Scenario	Description	Code
Batch queries all succeed	Multiple queries in array format all execute successfully	200
Database connection is established successfully	Neo4j service is running and accessible	200
Execution results in no rows	The query was valid but returned zero results	200
Query returns a single record	The query returns a single record	200
Query returns multiple records	The query returns a list of multiple records	200
Successfully executes a Cypher query with parameters	The subflow accepts a query with parameters, binds them correctly, and returns the results	200
Successfully executes a query with no parameters	The query doesn't require any parameters and executes successfully	200
Batch queries with mixed results	Some queries succeed, some fail in batch operation	207
Batch with invalid query syntax	One or more queries in batch have syntax errors	207
Batch with missing required parameters	Some queries in batch are missing required parameters	207
Batch queries all fail	All queries in batch operation fail	400
Data type mismatch in query	An operation attempted to use incompatible data types	400
Database schema mismatch	The database structure does not match the query (e.g., missing node labels)	400
Empty batch array	Empty array provided as input	400
Incorrect data type for parameter	A parameter value has incorrect type (e.g., string instead of integer)	400
Invalid Cypher syntax	Syntax error in the query string	400
Invalid Cypher syntax in parameters	Parameters contain invalid values causing syntax issues	400
Invalid node label in query	The query refers to a node label that doesn't exist in the schema	400
Invalid parameter key (contains special characters)	A parameter key includes invalid characters for Neo4j	400
Invalid property type	A property value is of incorrect type for the node/relationship	400
Missing required query parameter	The query expects a parameter but it was not provided	400
Parameter value too large	A parameter value exceeds database limits (e.g., string length)	400
Query attempts to return a nonexistent field	The query references a field name that doesn't exist in the result	400
Query with incomplete pattern	The MATCH pattern has missing relationships or nodes	400
Query with incorrect MERGE clause	The MERGE clause was used incorrectly resulting in a syntax error	400
Unsupported Cypher feature	The query uses a Neo4j version-specific feature not supported by the current version	400
Authentication failure for Neo4j	Incorrect credentials used to connect to Neo4j	401
Authorization failure for Neo4j	User lacks permission to execute the query or access the database	403
Read-only Neo4j instance	The Neo4j instance is configured as read-only, but a write query was attempted	403
Attempted to delete a non-existent node	A DELETE operation targeted a node that doesn't exist	404
Constraint violation during write operation	A write operation (e.g., CREATE) violated a database constraint	409
Neo4j driver not installed	Required Neo4j driver is missing from Node-RED	500
Neo4j instance configuration error	Neo4j has incorrect configuration (e.g., binding to wrong port)	500
Neo4j server configuration issue	The Neo4j instance has misconfigured parameters	500
Query execution failed due to server-side error	Unpredictable error from Neo4j server	500
Result set size exceeds memory limits	The query returned too many results for Neo4j to handle	500
Unexpected response from Neo4j	Neo4j returned a response not conforming to expected structure	502
Connection reset during query execution	The network connection was reset while the query was processing	503
Database backup in progress	Neo4j is performing a backup operation, blocking queries	503
Database connection pool exhausted	All available database connections are in use	503
Database lock contention	The query was blocked due to another transaction holding locks	503
Neo4j instance in read-only mode due to failure	Neo4j entered a read-only state due to a disk error or other failure	503
Neo4j server is down	Neo4j service crashed or stopped	503
Neo4j server is unreachable	Network issues prevent connecting to Neo4j	503
Neo4j server overloaded	The server is too busy to handle the query	503
Network packet loss during query execution	Network issues caused interruption mid-query	503
Query timeout	The query execution took longer than the allowed timeout period	504

Input schema

{

"type": "object",

"properties": {

"payload": {

"oneOf": [

{

"type": "object",

"properties": {

"query": {

"type": "string",

"description": "Cypher query. For parametrized queries, use the following format in conjunction with `params` property: `MATCH (m:Movie {title: $moviename}) return m`"

"params": {

"type": "object",

"description": "Use key-value pairs like this: `{\"moviename\": \"Forrest Gump\"}` when executing parametrized queries",

"additionalProperties": true

}

"required": [

"query"

]

{

"type": "array",

"items": {

"type": "object",

"properties": {

"query": {

"type": "string",

"description": "Cypher query. For parametrized queries, use the following format in conjunction with `params` property: `MATCH (m:Movie {title: $moviename}) return m`"

"params": {

"type": "object",

"description": "Use key-value pairs like this: `{\"moviename\": \"Forrest Gump\"}` when executing parametrized queries",

"additionalProperties": true

}

"required": [

"query"

]

}

]

}

"required": [

"payload"

]

}

Applicable status codes:200207

Status codes

Success schema

{

"type": "object",

"properties": {

"payload": {

"type": "array",

"description": "Array of objects representing each executed query and the returned results",

"items": {

"type": "object",

"properties": {

"query": {

"type": "string",

"description": "Contents of the query executed"

"params": {

"type": "object"

"results": {

"type": "array",

"description": "Array of objects returned by the database as the result of query execution",

"items": {

"type": "object"

}

"required": [

"payload"

]

}

Applicable status codes:400401403404409422500502503504

Error schema (standard)

{

"type": "object",

"properties": {

"payload": {

"type": "object",

"properties": {

"type": {

"type": "string",

"const": "error"

"error": {

"type": "string"

}

"required": [

"type",

"error"

]

}

"required": [

"payload"

]

}

Request

Request body (inner payload)

{

}