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 |
|---|---|---|
|
integer / required |
A reference to objects selected earlier in this transaction. |
object / optional |
Match any of the stored connection’s class names in |
|
|
object / optional |
Match the stored connection’s endpoint object types in |
|
string / optional |
Shorthand for a |
|
string / optional |
Default any; accepts in, out, or any. Direction is interpreted as described below. |
|
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,
"class": {
"src": "Person",
"connection": "BestFriendForever",
"dst": "Person"
},
"target": {
"src": "entity",
"dst": "entity"
},
"constraints": ["$since_year", ">=", 2005]
},
"results": {
"list": ["name"]
}
}
}]
Result from the query:
[{
"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:
[{
"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": [{
"_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
}
}]