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"}