is_connected_to

is_connected_to specifies one or more connection-based constraints that must be satisfied in a Find* command. It returns object(s) that are connected to the objects referenced by ref.

Parameters

• ref: Reference to objects within the transaction.
• [optional] connection_class: Indicates the class of the connection.
• [optional] direction: Indicates direction of the connection (Default: any).
• [optional] constraints Indicates constraints over the properties of the connection.

Details

is_connected_to can be used to filter objects based on their neighbors. One or many neighbors can be specified. any or all must be used when multiple ref values are specified. When multiple ref values are specified, the search will return: a) all the objects that have a connection to at least one of the objects referenced by each ref parameter in the is_connected_to array, when any is used, OR b) all the objects that have a connection to some object(s) in every ref, when all is specified.

Examples

For instance, we can search for objects connected to another set of objects referenced by ref as follows:

[{
    "FindEntity": {
        "with_class": "Person",
        "_ref": 1234,
        "constraints": {
            "name": ["==", "Jane Doe"]
        },
        "results": {
            "count": true
        }
    }
}, {
    "FindEntity": {
        "with_class": "Person",
        "constraints": {
            "name": ["==", "Jon Doe"]
        },
        "is_connected_to": {
            "ref": 1234,
            "connection_class": "BestFriendForever",
            "constraints": {
                "since_year": [">=", 2005]
            }
        },
        "results": {
            "list": ["name"]
        }
    }
}]

Result from the query:

[{
    "FindEntity": {
        "count": 1,
        "returned": 0,
        "status": 0
    }
}, {
    "FindEntity": {
        "entities": [{
            "name": "Jon Doe"
        }],
        "returned": 1,
        "status": 0
    }
}]

The second FindEntity command aims to retrieve ONLY those entities of the class "Person" that have the name = "Jon Doe" AND are connected to the result of the first FindEntity, with that connection being of the class "BestFriendForever" and having a its "since_year" property greater than 2005.

Now if we want to constrain the search by multiple different sets of neighbor objects, we can specify multiple ref values.

[{
    "FindEntity": {
        "with_class": "Person",
        "_ref": 1234,
        "constraints": {
            "name": [
                "in",
                ["Jane", "Stana", "Keya"]
            ]
        },
        "results": {
            "list": ["name"]
        }
    }
}, {
    "FindEntity": {
        "with_class": "City",
        "_ref": 234,
        "constraints": {
            "name": [
                "in",
                ["Portland", "San Francisco"]
            ]
        },
        "results": {
            "list": ["name"]
        }
    }
}, {
    "FindEntity": {
        "with_class": "Person",
        "is_connected_to": {
            "any": [{
                "ref": 1234,
                "connection_class": "BestFriendForever",
                "constraints": {
                    "since_year": [">=", 2005]
                }
            }, {
                "ref": 234,
                "connection_class": "LivesIn"
            }]
        },
        "results": {
            "list": ["name"]
        }
    }
}]

In the example above, the last FindEntity will return objects of class "Person" that are connected to any of the objects in ref 1234 ["Jane", "Stana", "Keya"] by a "BestFriendForever" connection OR has a "LivesIn" connection to any of the objects represented by 234 ["Portland", "San Francisco"]. Each ref can represent multiple objects that match when a Find* is executed. In case we had "all" instead of "any" in the example above for the last FindEntity, the objects returned will need to be connected to at least one object per ref across all the given ref values in the "all" array.

[{
    "FindEntity": {
        "entities": [{
            "name": "Jane"
        }, {
            "name": "Stana"
        }, {
            "name": "Keya"
        }],
        "returned": 3,
        "status": 0
    }
}, {
    "FindEntity": {
        "entities": [{
            "name": "San Francisco"
        }, {
            "name": "Portland"
        }],
        "returned": 2,
        "status": 0
    }
}, {
    "FindEntity": {
        "entities": [{
            "name": "Jane"
        }, {
            "name": "Stana"
        }, {
            "name": "Kate"
        }, {
            "name": "Morgan"
        }, {
            "name": "Freya"
        }],
        "returned": 5,
        "status": 0
    }
}]