relatedFilter
relatedFilter in a $findWithRelated query#
Insert a relatedFilter in your findWithRelated query to filter for parent items that match a child item query across named user collections. To include the child items that match in your response, insert “includeResult”: true in your relatedFilter.
For more information on the relatedFilter structure and fields and how you insert the relatedFilter in a findWithRelated query request, see the following example code structure with reference to Table 1:
{ "$findWithRelated": { "parent": { //see table 1 and the findWithRelated code example }, "relatedFilter": { "includeResult": true, "$or" | "$and": [ { "relatedDesc": { //"<criteria to look up parent-child relationship>": "<value>" }, "query": { //"<criteria to filter the child related items you selected in the //related.relatedDesc query>": "<property value to query>" }, "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": "<property name for the path query results in the response>" } ] } }} Table 1: relatedFilter in findWithRelated query fields
| Field | Type | Required | Description |
|---|---|---|---|
| parent | Object | Required | You must add a parent object that contains the look up criteria for the parent collection and related items. For more information, see parent in the FindWithRelated query fields table. |
relatedFilter | Object | Required | Filter for parent items that match a child item query. You can also use relatedFilter in combination with a related query or a relatedDistinctFields query |
relatedFilter.includeResult | Boolean | Optional | Enter "includeResult" = true to include the child item filter results in the response |
relatedFilter.[$or|$and] | List | Required | In a list, enter the child item filter arguments you want either the OR or AND logical operator to evaluate. |
relatedFilter.[$or|$and].relatedDesc | Object | Required | Add your relationship query as a valid simple query. For more information on query operators, see Supported Query Operators |
relatedFilter.[$or|$and].query | Object | Optional | Add criteria to filter the child related items you selected in the related.relatedDesc query. For more information on query operators, see Supported Query Operators |
relatedFilter.[$or|$and].options | Object | Optional | Add projection, page, and sort options for the relatedFilter response |
relatedFilter.[$or|$and].options.project | Object | Optional | Enable or disable the child related item fields in the response with simple query projection |
relatedFilter.[$or|$and].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 200. |
relatedFilter.[$or|$and].options.as | String | Required | Name the property that contains the relatedFilter results in the response. This property is required if you set relatedFilter.includeResult to true. |
For real world examples, see the following example query and response:
Example query
{ "$findWithRelated": { "parent": { "collectionDesc": { "_userItemId": "11_new_ba_elem_1sjwcciumd", "_versions.all":true }, "collectionProject": { "_userItemId": 1 }, "query": { "type_id": 278 }, "options": { "project": { "source_id": 1 }, "page": { "_pageSize": 100, "_offset": 0 }, "sort": { "_metadata._updatedAt": 1 } } }, "relatedFilter": { "includeResult": true, "$or": [ { "relatedDesc": { "_relatedUserType": "rvt_type_elements" }, "query": { "properties.Revit Category.val": "OST_Windows" }, "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/5cee7fee6505d6286dbca469", "_tipVersion": 2, "_itemClass": "NamedUserCollection", "_userItemId": "11_new_ba_elem_1sjwcciumd", "_tipId": "5cee814dfa298d0d3e34e246", "_versions": [ { "_userItemDbId": "5cee7fee6505d6286dbca469", "_relatedItems": { "_pageSize": 5, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef58", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-0003842e", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef59", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038450", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5a", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038463", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5b", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038933", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5c", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038950", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } } ], "_offset": 0, "_total": 5, "_filteredSize": 5 }, "_id": "5cee80c1fa298d0d3e34e23b", "_isTip": false, "_metadata": { "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c", "_createdAt": 1559134191035, "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c", "_updatedAt": 1559134542075 }, "_version": 1 }, { "_userItemDbId": "5cee7fee6505d6286dbca469", "_relatedItems": { "_pageSize": 5, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef59", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038450", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5a", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038463", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5b", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038933", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } }, { "_id": "5cee7fe8c27e69cd0209ef5c", "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038950", "type_elements": { "_pageSize": 1, "_list": [ { "_id": "5cee7fe8c27e69cd0209ef39", "properties": { "Revit Category": { "val": "OST_Windows" } } } ], "_offset": 0, "_total": 1 } } ], "_offset": 0, "_total": 5, "_filteredSize": 4 }, "_id": "5cee814dfa298d0d3e34e246", "_isTip": true, "_metadata": { "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c", "_createdAt": 1559134191035, "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c", "_updatedAt": 1559134542086 }, "_version": 2 } ], "_irn": "itemsvc:nameduseritem:5cee7fee6505d6286dbca469", "_id": "5cee7fee6505d6286dbca469", "_kind": "collection" } ], "_time": "37ms"}