Optional match

.circleci/config.yml

@@ -27,7 +27,7 @@ jobs:
       - run:
           name: Install prerequisite
           command: >-
-            pip install git+https://github.com/RedisGraph/redisgraph-py.git@master &&
+            pip install git+https://github.com/RedisGraph/redisgraph-py.git@null-graph-entities &&
             pip install psutil behave &&
             pip install redis-py-cluster &&
             pip install git+https://github.com/RedisLabsModules/RLTest.git@master &&

docs/commands.md

@@ -23,6 +23,7 @@ supported.
 ### Query structure
 
 - MATCH
+- OPTIONAL MATCH
 - WHERE
 - RETURN
 - ORDER BY
@@ -128,6 +129,45 @@ The syntactic sugar `(person_a)<-[:KNOWS]->(person_b)` will return the same resu
 
 The bracketed edge description can be omitted if all relations should be considered: `(person_a)--(person_b)`.
 
+#### OPTIONAL MATCH
+
+The OPTIONAL MATCH clause is a MATCH variant that produces null values for elements that do not match successfully, rather than the all-or-nothing logic for patterns in MATCH clauses.
+
+It can be considered to fill the same role as LEFT/RIGHT JOIN does in SQL, as MATCH entities must be resolved but nodes and edges introduced in OPTIONAL MATCH will be returned as nulls if they cannot be found.
+
+OPTIONAL MATCH clauses accept the same patterns as standard MATCH clauses, and may similarly be modified by WHERE clauses.
+
+Multiple MATCH and OPTIONAL MATCH clauses can be chained together, though a mandatory MATCH cannot follow an optional one.
+
+```sh
+GRAPH.QUERY DEMO_GRAPH
+"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS_AT]->(c:Company)
+WHERE w.start_date > 2016
+RETURN p, w, c"
+```
+
+All `Person` nodes are returned, as well as any `WORKS_AT` relations and `Company` nodes that can be resolved and satisfy the `start_date` constraint. For each `Person` that does not resolve the optional pattern, the person will be returned as normal and the non-matching elements will be returned as null.
+
+Cypher is lenient in its handling of null values, so actions like property accesses and function calls on null values will return null values rather than emit errors.
+
+```sh
+GRAPH.QUERY DEMO_GRAPH
+"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS_AT]->(c:Company)
+RETURN p, w.department, ID(c) as ID"
+```
+
+In this case, `w.department` and `ID` will be returned if the OPTIONAL MATCH was successful, and will be null otherwise.
+
+Clauses like SET, CREATE, and DELETE will ignore null inputs and perform the expected updates on real inputs. One exception to this is that attempting to create a relation with a null endpoint will cause an error:
+
+```sh
+GRAPH.QUERY DEMO_GRAPH
+"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS_AT]->(c:Company)
+CREATE (c)-[:NEW_RELATION]->(:NEW_NODE)"
+```
+
+If `c` is null for any record, this query will emit an error. In this case, no changes to the graph are committed, even if some values for `c` were resolved.
+
 #### WHERE
 
 This clause is not mandatory, but if you want to filter results, you can specify your predicates here.

docs/cypher_support.md

@@ -42,11 +42,7 @@ We do not support any of these properties at the type level, meaning nodes and r
 ## Clauses
 ### Reading Clauses
 + MATCH
-
-  **Unsupported:**
-
-- OPTIONAL MATCH
-- MANDATORY MATCH
++ OPTIONAL MATCH
 
 ### Projecting Clauses
 + RETURN

src/arithmetic/arithmetic_expression.c

@@ -344,8 +344,12 @@ static bool _AR_EXP_UpdateEntityIdx(AR_OperandNode *node, const Record r) {
 
 static AR_EXP_Result _AR_EXP_EvaluateProperty(AR_ExpNode *node, const Record r, SIValue *result) {
 	RecordEntryType t = Record_GetType(r, node->operand.variadic.entity_alias_idx);
-	// Property requested on a scalar value.
-	if(!(t & (REC_TYPE_NODE | REC_TYPE_EDGE))) {
+	if(t == REC_TYPE_UNKNOWN) {
+		/* If we attempt to access a null value as a graph entity (due to a
+		 * scenario like a failed OPTIONAL MATCH), return a null value. */
+		*result = SI_NullVal();
+		return EVAL_OK;
+	} else if(!(t & (REC_TYPE_NODE | REC_TYPE_EDGE))) {
 		/* Attempted to access a scalar value as a map.
 		 * Set an error and invoke the exception handler. */
 		char *error;

src/arithmetic/entity_funcs/entity_funcs.c

@@ -15,12 +15,14 @@
 
 /* returns the id of a relationship or node. */
 SIValue AR_ID(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	GraphEntity *graph_entity = (GraphEntity *)argv[0].ptrval;
 	return SI_LongVal(ENTITY_GET_ID(graph_entity));
 }
 
 /* returns a string representations the label of a node. */
 SIValue AR_LABELS(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	char *label = "";
 	Node *node = argv[0].ptrval;
 	GraphContext *gc = QueryCtx_GetGraphCtx();
@@ -32,6 +34,7 @@ SIValue AR_LABELS(SIValue *argv, int argc) {
 
 /* returns a string representation of the type of a relation. */
 SIValue AR_TYPE(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	char *type = "";
 	Edge *e = argv[0].ptrval;
 	GraphContext *gc = QueryCtx_GetGraphCtx();
@@ -51,6 +54,7 @@ SIValue AR_EXISTS(SIValue *argv, int argc) {
 }
 
 SIValue _AR_NodeDegree(SIValue *argv, int argc, GRAPH_EDGE_DIR dir) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	Node *n = (Node *)argv[0].ptrval;
 	Edge *edges = array_new(Edge, 0);
 	GraphContext *gc = QueryCtx_GetGraphCtx();
@@ -79,11 +83,13 @@ SIValue _AR_NodeDegree(SIValue *argv, int argc, GRAPH_EDGE_DIR dir) {
 
 /* Returns the number of incoming edges for given node. */
 SIValue AR_INCOMEDEGREE(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	return _AR_NodeDegree(argv, argc, GRAPH_EDGE_DIR_INCOMING);
 }
 
 /* Returns the number of outgoing edges for given node. */
 SIValue AR_OUTGOINGDEGREE(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	return _AR_NodeDegree(argv, argc, GRAPH_EDGE_DIR_OUTGOING);
 }
 
@@ -92,34 +98,35 @@ void Register_EntityFuncs() {
 	AR_FuncDesc *func_desc;
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_NODE | T_EDGE);
+	types = array_append(types, T_NULL | T_NODE | T_EDGE);
 	func_desc = AR_FuncDescNew("id", AR_ID, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_NODE);
+	types = array_append(types, T_NULL | T_NODE);
 	func_desc = AR_FuncDescNew("labels", AR_LABELS, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_EDGE);
+	types = array_append(types, T_NULL | T_EDGE);
 	func_desc = AR_FuncDescNew("type", AR_TYPE, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, SI_ALL);
+	types = array_append(types, T_NULL | SI_ALL);
 	func_desc = AR_FuncDescNew("exists", AR_EXISTS, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 2);
-	types = array_append(types, T_NODE);
+	types = array_append(types, T_NULL | T_NODE);
 	types = array_append(types, T_STRING);
 	func_desc = AR_FuncDescNew("indegree", AR_INCOMEDEGREE, 1, VAR_ARG_LEN, types, false);
 	AR_RegFunc(func_desc);
 
-	types = array_new(SIType, 1);
-	types = array_append(types, T_NODE);
+	types = array_new(SIType, 2);
+	types = array_append(types, T_NULL | T_NODE);
 	types = array_append(types, T_STRING);
 	func_desc = AR_FuncDescNew("outdegree", AR_OUTGOINGDEGREE, 1, VAR_ARG_LEN, types, false);
 	AR_RegFunc(func_desc);
 }
+

src/arithmetic/list_funcs/list_funcs.c

@@ -144,6 +144,8 @@ SIValue AR_SIZE(SIValue *argv, int argc) {
 		return SI_LongVal(SIArray_Length(value));
 	case T_STRING:
 		return SI_LongVal(strlen(value.stringval));
+	case T_NULL:
+		return SI_NullVal();
 	default:
 		assert(false);
 	}
@@ -227,3 +229,4 @@ void Register_ListFuncs() {
 	func_desc = AR_FuncDescNew("tail", AR_TAIL, 1, 1, types, true);
 	AR_RegFunc(func_desc);
 }
+

src/arithmetic/path_funcs/path_funcs.c

@@ -23,6 +23,11 @@ SIValue AR_TOPATH(SIValue *argv, int argc) {
 	const cypher_astnode_t *ast_path = argv[0].ptrval;
 	uint nelements = cypher_ast_pattern_path_nelements(ast_path);
 	assert(argc == (nelements + 1));
+	for(uint i = 1; i < argc; i++) {
+		// If any element of the path does not exist, the entire path is invalid and NULL should be returned.
+		if(argv[i].type == T_NULL) return SI_NullVal();
+	}
+
 	SIValue path = SIPathBuilder_New(nelements);
 	for(uint i = 0; i < nelements; i++) {
 		SIValue element = argv[i + 1];
@@ -55,14 +60,17 @@ SIValue AR_TOPATH(SIValue *argv, int argc) {
 }
 
 SIValue AR_PATH_NODES(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	return SIPath_Nodes(argv[0]);
 }
 
 SIValue AR_PATH_RELATIONSHIPS(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	return SIPath_Relationships(argv[0]);
 }
 
 SIValue AR_PATH_LENGTH(SIValue *argv, int argc) {
+	if(argv[0].type == T_NULL) return SI_NullVal();
 	return SI_LongVal(SIPath_Length(argv[0]));
 }
 
@@ -72,22 +80,23 @@ void Register_PathFuncs() {
 
 	types = array_new(SIType, 2);
 	types = array_append(types, T_PTR);
-	types = array_append(types, T_NODE | T_EDGE | T_PATH);
+	types = array_append(types, T_NULL | T_NODE | T_EDGE | T_PATH);
 	func_desc = AR_FuncDescNew("topath", AR_TOPATH, 1, VAR_ARG_LEN, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_PATH);
+	types = array_append(types, T_NULL | T_PATH);
 	func_desc = AR_FuncDescNew("nodes", AR_PATH_NODES, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_PATH);
+	types = array_append(types, T_NULL | T_PATH);
 	func_desc = AR_FuncDescNew("relationships", AR_PATH_RELATIONSHIPS, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 
 	types = array_new(SIType, 1);
-	types = array_append(types, T_PATH);
+	types = array_append(types, T_NULL | T_PATH);
 	func_desc = AR_FuncDescNew("length", AR_PATH_LENGTH, 1, 1, types, false);
 	AR_RegFunc(func_desc);
 }
+

src/ast/ast_build_filter_tree.c

@@ -319,6 +319,8 @@ FT_FilterNode *AST_BuildFilterTree(AST *ast) {
 	if(match_clauses) {
 		uint match_count = array_len(match_clauses);
 		for(uint i = 0; i < match_count; i ++) {
+			// Optional match clauses are handled separately.
+			if(cypher_ast_match_is_optional(match_clauses[i])) continue;
 			const cypher_astnode_t *pattern = cypher_ast_match_get_pattern(match_clauses[i]);
 			_AST_ConvertGraphPatternToFilter(ast, &filter_tree, pattern);
 			const cypher_astnode_t *predicate = cypher_ast_match_get_predicate(match_clauses[i]);
@@ -362,3 +364,4 @@ FT_FilterNode *AST_BuildFilterTree(AST *ast) {
 
 	return filter_tree;
 }
+

src/ast/ast_mock.c

@@ -8,24 +8,43 @@
 #include "../query_ctx.h"
 #include "../util/rmalloc.h"
 
-AST *AST_MockMatchPattern(AST *master_ast, const cypher_astnode_t *original_path) {
+AST *AST_MockMatchClause(AST *master_ast, cypher_astnode_t *node, bool node_is_path) {
+	/* The AST node and its children must be reused directly,
+	 * as cloning causes annotations (entity names) to be lost.
+	 * TODO consider updating parser to improve this. */
 	AST *ast = rm_malloc(sizeof(AST));
 	ast->referenced_entities = master_ast->referenced_entities;
 	ast->anot_ctx_collection = master_ast->anot_ctx_collection;
 	ast->free_root = true;
+	ast->skip = NULL;
 	ast->limit = NULL;
+	cypher_astnode_t *pattern;
 	struct cypher_input_range range = {};
+	const cypher_astnode_t *predicate = NULL;
+	uint child_count = (node_is_path) ? 1 : cypher_astnode_nchildren(node);
+	cypher_astnode_t *children[child_count];
 
-	// Reuse the input path directly. We cannot clone, as this causes annotations (entity names) to be lost.
-	// TODO consider updating parser to improve this.
-	cypher_astnode_t *path = (cypher_astnode_t *)original_path;
+	if(node_is_path) {
+		/* MERGE clauses and path filters are comprised of a single path.
+		 * Construct a pattern node containing just this path. */
+		pattern = cypher_ast_pattern(&node, 1, &node, 1, range);
+		children[0] = pattern;
+	} else {
+		/* OPTIONAL MATCH clauses contain a pattern node
+		 * and possibly a predicate node (containing WHERE conditions). */
+		assert(cypher_astnode_type(node) == CYPHER_AST_MATCH);
+		pattern = (cypher_astnode_t *)cypher_ast_match_get_pattern(node);
+		predicate = cypher_ast_match_get_predicate(node);
 
-	// Build a pattern comprised of the input path.
-	cypher_astnode_t *pattern = cypher_ast_pattern(&path, 1, &path, 1, range);
+		// Explicitly collect all child nodes from the clause.
+		for(uint i = 0; i < child_count; i ++) {
+			children[i] = (cypher_astnode_t *)cypher_astnode_get_child(node, i);
+		}
+	}
 
 	// Build a new match clause that holds this pattern.
-	cypher_astnode_t *match_clause = cypher_ast_match(false, pattern, NULL, 0, NULL, &pattern, 1,
-													  range);
+	cypher_astnode_t *match_clause = cypher_ast_match(false, pattern, NULL, 0, predicate,
+													  children, child_count, range);
 
 	// Build a query node holding this clause.
 	ast->root = cypher_ast_query(NULL, 0, &match_clause, 1, &match_clause, 1, range);
@@ -35,14 +54,16 @@ AST *AST_MockMatchPattern(AST *master_ast, const cypher_astnode_t *original_path
 	return ast;
 }
 
-void AST_MockFree(AST *ast) {
-	/* When freeing the mock AST, we have to be careful to not free the shared path
+void AST_MockFree(AST *ast, bool free_pattern) {
+	/* When freeing the mock AST, we have to be careful to not free any shared node
 	 * or its annotations. We'll free every surrounding layer explicitly - the MATCH
-	 * pattern, the MATCH clause, and finally the AST root. */
+	 * pattern (if we constructed it), the MATCH clause, and finally the AST root. */
 	const cypher_astnode_t *clause = cypher_ast_query_get_clause(ast->root, 0);
 	assert(cypher_astnode_type(clause) == CYPHER_AST_MATCH);
-	const cypher_astnode_t *pattern = cypher_ast_match_get_pattern(clause);
-	cypher_astnode_free((cypher_astnode_t *)pattern);
+	if(free_pattern) {
+		const cypher_astnode_t *pattern = cypher_ast_match_get_pattern(clause);
+		cypher_astnode_free((cypher_astnode_t *)pattern);
+	}
 	cypher_astnode_free((cypher_astnode_t *)clause);
 	cypher_astnode_free((cypher_astnode_t *)ast->root);
 	rm_free(ast);

src/ast/ast_mock.h

@@ -8,9 +8,9 @@
 
 #include "ast.h"
 
-// Build a temporary AST with one MATCH clause that holds the given path.
-AST *AST_MockMatchPattern(AST *master_ast, const cypher_astnode_t *original_path);
+// Build a temporary AST with one MATCH clause that holds the given path or pattern.
+AST *AST_MockMatchClause(AST *master_ast, cypher_astnode_t *node, bool node_is_pattern);
 
 // Free a temporary AST.
-void AST_MockFree(AST *ast);
+void AST_MockFree(AST *ast, bool free_pattern);