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 or equal than)
• "==" (equal to)
• "!=" (different than)
• ">" (greater than)
• ">=" (greater or equal than)
• "in" (is in)
• "not in" (is not in)

NOTE: Only the "==", "in", and "not in" operators are supported for "_uniqueid".

For instance, if we want to insert a new object if and only if there is no other object with a connection to another object, we can do the following:

    [ {
        "FindEntity": {
            "_ref": 1
            "class": "Person",
            "constraints": {
                "name": ["==", "John Salchi"]
            }
        }
    }, {
        "FindImage": {
            "_ref": 2,
            "constraints": {
                "id": ["==", 321]
            },
            "is_connected_to": {
                "ref": 1,
                "connection_class": "has_profile_photo"
            }
        }
    }, {
        "AddImage": {
            "if_not_found": 2,
            "properties": {
                "id":     21,
                "height": 224,
                "width":  224
            }
        }
    }]

Successful response:

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.