if_not_found

When using if_not_found, an Add* command (AddEntity, AddBoundingBox, etc) will become a "conditional add". This is, the object will be inserted into the database if and only if there is no other element of the same type that fulfills the specified constraints. The most common use case is making sure we do not add an object twice, using some specific properties.

For instance, if we want to make sure that a new object is only inserted if there is no other object with the "id" property equal to 21, and the "height" property greater or equal to 200, we can use if_not_found as follows:

    [{
        "AddImage": {
            "if_not_found": {
                "id": ["==", 21],
                "height": [">=", 200]
            },
            "properties": {
                "id": 21,
                "height": 224,
                "width": 224
            }
        }
    }]

Successful response:

    [{
        "AddImage": {
            "status": 0
        }
    }]

Supported operators are the same as in the constraints parameter for Find* commands, which are:

• < (less than)
• <= (less than or equal to)
• == (equal to)
• != (not equal to)
• > (greater than)
• >= (greater than or equal to)
• in (is in)
• not_in (is not in)
• like (pattern match)
• ilike (case-insensitive pattern match; array expressions only)
• regex (regular expression match)
• contains (substring match)
• icontains (case-insensitive substring match; array expressions only)
• starts_with (prefix match)
• istarts_with (case-insensitive prefix match; array expressions only)
• ends_with (suffix match)
• iends_with (case-insensitive suffix match; array expressions only)
• is_missing (missing property)
• is_finite (finite numeric value)

NOTE: The "_uniqueid" field supports only the "==", "in", and "not_in" operators.

if_not_found also accepts the array expression language described in constraints, including nested all, any, and not, scalar functions, and pattern matching:

    [{
        "AddEntity": {
            "class": "Person",
            "properties": {"email": "alice@example.com"},
            "if_not_found": ["all",
                [{"lower": "$email"}, "==", "alice@example.com"],
                ["not", ["$disabled", "==", true]]
            ]
        }
    }]

Expressions inspect existing objects. For entity adds, a match skips creation, and _ref, when provided, refers to all matching objects. An omitted if_not_found does not perform this check; an empty object {} matches every object in the applicable scope. 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.