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