.. _is_connected_to: is_connected_to =============== **is_connected_to** specifies connection(s)-based constraint that must be satisfied in a Find* command. It returns object(s) that are connected to the objects referenced by **ref**. Parameters ++++++++++ * [optional] :ref:`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] :ref:`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: .. code-block:: python [ { "FindEntity" : { "with_class" : "Person", "_ref": 1234, "constraints" : { "name" : ["==", "Jane Doe"] } } },{ "FindEntity" : { "with_class" : "Person", "constraints" : { "name" : ["==", "Jon Doe"] }, "is_connected_to": { # searching over just one connection. "ref": 1234, "connection_class": "BestFriendForever", "constraints": { "since_year": [">=", 2005] } } } }] In this case, 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. .. code-block:: python [ { "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" } ] } } }] 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.