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.

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.

Field	Type / required	Behavior
ref	integer / required	A reference to objects selected earlier in this transaction.
connection_class	string / optional	Omitted: do not filter connections by class.
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: 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] 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:

[{
    "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 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:

[{
    "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.

[{
    "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
    }
}]