findWithRelated
findWithRelated query
Use the $findWithRelated query to look up related items in multiple named user collections at a depth of one relationship level. You can use the query on parent items and child items in the following manner:
- Parent-child: Query a parent’s child related items in the
parentsection - Child-parent: Filter a child’s parent related items based on the criteria you provide for the child related items in the
relatedsection
Note: You can also use the following related queries and filters within your findWithRelated query: relatedFilter, relatedDistinctFilter, and related query. For more information, see Combining queries and filters with your findWithRelated query.
For more information on how to structure a $findWithRelated query request, see the following example code structure with reference to Table 1:
{
"$findWithRelated": {
"parent": {
"collectionDesc": {
//"<property to identify a collection by>": "<value>"
},
"query": {
//"<property to query>": "<simple query to find parent related items in
//the collections you query in collectionDesc>"
},
"collectionProject": {
//"<collection property fields you want to appear in the response>": 1
},
"options": {
"project": {
//"<parent related item fields you want to appear in the response>": 1
},
"page": {
"_pageSize": //<page size value you want as integer>
"_offset": //<offset size value you want as integer>
},
"sort": {
//"<property you want to sort by in the response>": 1
}
}
},
"related": [
{
"relatedDesc": {
//"<criteria to look up parent-child relationship>": "<value>"
},
"query": {
//"<property to query>": "<value to query child related items>"
},
"options": {
"project": {
//"<child related item field to appear in the response>": 1
},
"page": {
"_pageSize": //<page size value you want as integer>
"_offset": //<offset size value you want as integer>
},
"sort": {
//"<property you want to sort by in the response>": 1
}
},
"as": "<field name for the child item results in the response>"
}
]
}
}
Table 1: $findWithRelated query fields table
| Field | Type | Required | Description |
|---|---|---|---|
parent | Object | Required | Add the following look up criteria for the parent collection and related items. |
parent.collectionDesc | Object | Required | Enter a valid simple query to run on your collections list. The collections lookup filters by the user’s namespaces. |
parent.collectionDesc._versions.all | Boolean | Optional | Insert property and set to true to search all versions, rather than only the tip version. |
parent.collectionDesc._versions | Object | Optional | Enter a valid query to filter properties by version. parent.collectionDesc._versions.all must be set to true when using this filter. |
parent.query | Object | Optional | Enter a valid simple query to find parent related items in the collections you query in collectionDesc. |
parent.collectionProject | Object | Optional | Simple query projection to enable or disable collection fields in the response |
parent.readingsFilter | Object | Optional | Query telemetry data. For more information, see Using a readingsFilter in the parent section of a findWithRelated query. |
parent.options | Object | Optional | Insert query control options, such as pagination, sorting, and projection in an options object. |
parent.options.page | Object | Optional | Set the _pageSize and _offset in the options.page object. If you do not, the default for page size is 200 and for offset, 0. |
parent.options.project | Object | Optional | Simple query projection to enable or disable parent related item fields in the response |
parent.options.sort | Object | Optional | Simple query sort to sort your results by related item fields |
related | Object | Conditional | Enter your criteria to look up child related items. You must include at least one of the following in a findWithRelated query: related, relatedFilter. You can combine findWithRelated with relatedFilter but not relatedDistinctFields. |
related.relatedDesc | Object | Required | Add your relationship query for parent related items as a valid simple query. For more information on query operators, see Supported query operators. |
related.query | Object | Conditional | Add criteria to filter the child related items you selected in the related.relatedDesc query. You must enter a valid simple query. For more information on query operators, see Supported query operators. You must include at least one of the following fields in a findWithRelated query:related, relatedFilter |
related.readingsFilter | Object | Required | Add a telemetry readings query or filter. For more information, see Using a readingsFilter in the related section of a $findWithRelated query. |
related.options | Object | Optional | Pass an object that can contain the following response options parameters for the results of the criteria you define in related.query: "page", "project", "sort", "as". |
related.options.page | Object | Optional | Set the response pagination options, such as _offset and _pageSize. The default value for _offset is 0 and for _pageSize is 1000. |
related.options.project | Object | Optional | Enable or disable the child related item fields in the response with simple query projection. |
related.options.sort | Object | Optional | Sort the results in the response based on the related items fields with simple query sort |
related.options.as | String | Required | Name the property that contains the relatedFilter results in the response. |
For more information, see the following $findWithRelated query request and response examples:
Example query
{
"$findWithRelated": {
"parent": {
"collectionDesc": {
"_userItemId": "1mb_4222225_ba_elem_OYK5UKTTTl",
"_versions.all": true
},
"query": {
"type_id": 12130
},
"collectionProject": {
"_userItemId": 1,
"_name": 1
},
"options": {
"project": {
"source_id": 1,
"package_id": 12143
},
"page": {
"_pageSize": 2,
"_offset": 0
},
"sort": {
"_metadata._updatedAt": 1
}
}
},
"related": [
{
"relatedDesc": {
"_relatedUserType": "rvt_type_elements"
},
"query": {
"properties.OmniClass Title.val": "Beams"
},
"options": {
"project": {
"properties.Revit Category.val": 1,
"properties.baBIMAssureType.val": 1
},
"page": {
"_pageSize": 100,
"_offset": 0
},
"sort": {
"_metadata._updatedAt": 1
}
},
"as": "type_elements"
}
]
}
}
Example response
{
"_list": [
{
"_uri": "/nameduseritems/5ced0ce85502b659e49cad12",
"_name": "1Mb_4222225_elements",
"_tipVersion": 2,
"_itemClass": "NamedUserCollection",
"_userItemId": "1mb_4222225_ba_elem_OYK5UKTTTl",
"_tipId": "5cee29f98702dd0b75f7983d",
"_versions": [
{
"_userItemDbId": "5ced0ce85502b659e49cad12",
"_relatedItems": {
"_pageSize": 2,
"_list": [
{
"_id": "5ced0cdea717bb1892f81a93",
"source_id": "150f10e7-70e9-40e4-86e8-4fb92aa169a8-000bd95a",
"package_id": 12143,
"type_elements": {
"_pageSize": 2,
"_list": [
{
"_id": "5ced0cdea717bb1892f81464",
"properties": {
"Revit Category": {
"val": "OST_StructuralFraming"
},
"baBIMAssureType": {
"val": "Beams"
}
}
},
{
"_id": "5ced0cdea717bb1892f81464",
"properties": {
"Revit Category": {
"val": "OST_StructuralFraming"
},
"baBIMAssureType": {
"val": "Beams"
}
}
}
],
"_offset": 0,
"_total": 2
}
},
{
"_id": "5ced0cdea717bb1892f81a94",
"source_id": "e5db3719-101e-4bac-b26e-161a11a108f3-000fc8f5",
"package_id": 15208,
"type_elements": {
"_pageSize": 2,
"_list": [
{
"_id": "5ced0cdea717bb1892f81464",
"properties": {
"Revit Category": {
"val": "OST_StructuralFraming"
},
"baBIMAssureType": {
"val": "Beams"
}
}
},
{
"_id": "5ced0cdea717bb1892f81464",
"properties": {
"Revit Category": {
"val": "OST_StructuralFraming"
},
"baBIMAssureType": {
"val": "Beams"
}
}
}
],
"_offset": 0,
"_total": 2
}
}
],
"_offset": 0,
"_total": 14
},
"_id": "5ced191a91816a6d369aacaa",
"_isTip": false,
"_metadata": {
"_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
"_createdAt": 1559039208862,
"_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
"_updatedAt": 1559112185463
},
"_version": 1
},
{
"_userItemDbId": "5ced0ce85502b659e49cad12",
"_relatedItems": {
"_pageSize": 2,
"_list": [
{
"_id": "5ced0cdea717bb1892f81a92",
"source_id": "150f10e7-70e9-40e4-86e8-4fb92aa169a8-000bd958",
"package_id": 12138,
"type_elements": {
"_pageSize": 0,
"_list": [],
"_offset": 0,
"_total": 0
}
},
{
"_id": "5ced0cdea717bb1892f81a93",
"source_id": "150f10e7-70e9-40e4-86e8-4fb92aa169a8-000bd95a",
"package_id": 12143,
"type_elements": {
"_pageSize": 0,
"_list": [],
"_offset": 0,
"_total": 0
}
}
],
"_offset": 0,
"_total": 15
},
"_id": "5cee29f98702dd0b75f7983d",
"_isTip": true,
"_metadata": {
"_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
"_createdAt": 1559039208862,
"_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
"_updatedAt": 1559112185464
},
"_version": 2
}
],
"_irn": "itemsvc:nameduseritem:5ced0ce85502b659e49cad12",
"_id": "5ced0ce85502b659e49cad12",
"_kind": "collection"
}
],
"_time": "107ms"
}