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": {
        "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.