.. _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
++++++++++

* :ref:`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 <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.