.. _is_connected_to: 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**. .. _is_connected_to-fields: Field contract ++++++++++++++ The value is a single relationship object or an object containing one ``all`` or ``any`` array of relationship objects. Wrapper keys cannot be mixed with direct fields. ``{}``, ``{"all": []}``, and ``{"any": []}`` add no relationship restriction. .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``ref`` - integer / required - A reference to objects selected earlier in this transaction. * - :ref:`class ` - object / optional - Match any of the stored connection's class names in ``src``, ``connection``, or ``dst``. * - ``target`` - object / optional - Match the stored connection's endpoint object types in ``src`` or ``dst``. * - ``connection_class`` - string / optional - Shorthand for a ``class`` object with only ``connection``. Supply one class selector per relationship. * - ``direction`` - string / optional - Default any; accepts in, out, or any. Direction is interpreted as described below. * - ``constraints`` - expression array / optional - Omitted: no property filter on the connections. Parameters ++++++++++ * :ref:`ref `: Reference to objects within the transaction. * [optional] connection_class: Indicates the class of the connection. * [optional] direction: Indicates direction of the connection (one of **any**, **in** or **out**; default is **any**). This constrains the direction of the connection with respect to the referenced objects. For example, if the **direction** is **out**, then the command will return objects that are the destination of a connection whose source is an object referenced by **ref**. * [optional] :ref:`constraints ` Indicates constraints over the properties of the connection. Details +++++++ Each relationship condition requires a connection to at least one object in its referenced set. The condition can also restrict the connection's class, direction, and properties. Multiple conditions appear in an **any** or **all** array. **any** matches an object when at least one condition holds; **all** requires every condition to hold. Each reference may identify one object or many objects. Examples ++++++++ The following query finds objects connected to an earlier selection: .. TESTED_EXAMPLE: is_connected_to_1 .. code-block:: json [{ "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, "class": { "src": "Person", "connection": "BestFriendForever", "dst": "Person" }, "target": { "src": "entity", "dst": "entity" }, "constraints": ["$since_year", ">=", 2005] }, "results": { "list": ["name"] } } }] Result from the query: .. TESTED_EXAMPLE: is_connected_to_1_response .. code-block:: json [{ "FindEntity": { "count": 1, "returned": 0, "status": 0 } }, { "FindEntity": { "entities": [{ "_class": "Person", "name": "Jon Doe" }], "returned": 1, "status": 0 } }] The second FindEntity selects ``Person`` entities named ``Jon Doe`` that are connected to the first command's results through a ``BestFriendForever`` connection with ``since_year`` at least 2005. Multiple **ref** values constrain a search by different sets of neighboring objects: .. TESTED_EXAMPLE: is_connected_to_2 .. code-block:: json [{ "FindEntity": { "with_class": "Person", "_ref": 1234, "constraints": [ "$name", "in", { "array": ["Jane", "Stana", "Keya"] } ], "results": { "list": ["name"] } } }, { "FindEntity": { "with_class": "City", "_ref": 234, "constraints": [ "$name", "in", { "array": ["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"] } } }] The last **FindEntity** returns people with a ``BestFriendForever`` connection to Jane, Stana, or Keya that has ``since_year`` at least 2005, or a ``LivesIn`` connection to Portland or San Francisco. The people belong to reference 1234; the cities belong to reference 234. With ``all`` in place of ``any``, a returned object must connect to at least one object from every referenced set in the array. .. TESTED_EXAMPLE: is_connected_to_2_response .. code-block:: json [{ "FindEntity": { "entities": [{ "_class": "Person", "name": "Jane" }, { "_class": "Person", "name": "Stana" }, { "_class": "Person", "name": "Keya" }], "returned": 3, "status": 0 } }, { "FindEntity": { "entities": [{ "_class": "City", "name": "San Francisco" }, { "_class": "City", "name": "Portland" }], "returned": 2, "status": 0 } }, { "FindEntity": { "entities": [{ "_class": "Person", "name": "Jane" }, { "_class": "Person", "name": "Stana" }, { "_class": "Person", "name": "Kate" }, { "_class": "Person", "name": "Morgan" }, { "_class": "Person", "name": "Freya" }], "returned": 5, "status": 0 } }]