if_not_found
if_not_found makes an Add* command conditional: the command inserts an object only when no existing object of the same type matches the condition. A condition on identifying properties can prevent repeated insertion of the same object.
The following command inserts an image only when no existing image has
id equal to 21 and height at least 200. The request requires one valid
encoded image in its input blob array. The response assumes no matching image
exists. Repeated requests still require the image blob and must pass input
validation; the duplicate lookup does not bypass those requirements.
[{
"AddImage": {
"class": "Images",
"if_not_found": [
"all",
["$id", "==", 21],
["$height", ">=", 200]
],
"properties": {
"id": 21,
"height": 224,
"width": 224
}
}
}]
Successful response:
[{
"AddImage": {
"status": 0
}
}]
if_not_found uses the array expression language described in
constraints, including nested all, any, and not,
scalar functions, and pattern matching. Positive max_edits in fulltext
is restricted to read queries and cannot be used here; exact-token full-text
matching still requires a ready index on the searched class and property.
Grouped conditions use array expressions:
[{
"AddEntity": {
"class": "Person",
"properties": {"email": "alice@example.com"},
"if_not_found": ["all",
[{"lower": "$email"}, "==", "alice@example.com"],
["not", ["$disabled", "==", true]]
]
}
}]
Expressions inspect existing objects. A matching node causes the add to return
status: 2 without applying the new properties or creating the requested
connections. _ref, when provided, refers to all matching objects, so later
commands using it may affect more than one object. It is not an update or a
uniqueness constraint: existing duplicates remain. A newly inserted object
returns status: 0. An omitted if_not_found
does not perform this check. To match every existing object in the applicable
scope, use an always-true expression such as [1, "==", 1]. Array expressions
must contain a valid condition; an empty array is not a match-all filter.
For AddEntity, if_not_found only looks at existing entities with the same class. For instance, the following entities will not conflict with each other:
[{
"AddEntity": {
"class": "City",
"properties": {
"name": "Washington"
},
"if_not_found": ["$name", "==", "Washington"]
}
}, {
"AddEntity": {
"class": "State",
"properties": {
"name": "Washington"
},
"if_not_found": ["$name", "==", "Washington"]
}
}]
Successful response:
[{
"AddEntity": {
"status": 0
}
}, {
"AddEntity": {
"status": 0
}
}]
Similarly, in AddConnection, if_not_found only considers existing
connections with the same class, src, and dst.
When src or dst references multiple entities, this check runs for each
directed pair. Connections are created for pairs with no match, and _ref
includes both existing matches and newly created connections.
For AddConnection, status: 2 means every pair already had a matching
connection. A mix of existing and newly created connections returns
status: 0. The check does not update properties on the existing matches.