distinctRelatedItemFields

distinctRelatedItemFields query

Use a distinctRelatedItemFields query to return the distinct values of more than one field for related items in a named user collection. You can also use "query" and "count" parameters.

Note: The distinctRelatedItemFields query does not include response options.

For more information on the structure and fields of a distinctRelatedItemFields query, see the following example code structure with reference to distinctRelatedItemFields query request fields table.

{
   	"$distinctRelatedItemFields": {
   		"collectionDesc": {
   			//"<property to identify collections>": "<value>",
   		},
   		"collectionProject": {
   			//"<related item fields you want to appear in the response>": 1
   		},
   		//An array of objects that can contain your "field", "query", and "count" parameters for each field
   		"fieldDesc": [
   			{
   				"field": "<property you want to query>",
   				"count": "<set to true to return the count of distinct items>"
   			},
   			{
   				"field": "properties.dtType.val",
   				"query": {
   					//"<the value you put in the field property above>": {
   							//simple query such as the following example
   							//"$in": ["Steel", "Wood"]
   					//}
   				},
   				"count": "<set to true to return the count of distinct items>"
   			}
   		]
   	}
}

distinctRelatedItemFields query request fields table

Field	Type	Required	Description
collectionDesc	Object	Required	Enter a valid simple query to run on your collections list. <b>Note:</b> The collections lookup filters by the user’s namespaces.
collectionDesc._versions.all	Boolean	Optional	Insert property and set to true to search all versions, rather than only the tip version.
collectionDesc._versions	Object	Optional	Enter a valid query to filter properties by version. collectionDesc._versions.all must be set to true when using this filter.
collectionProject	Object	Optional	Simple query projection to enable or disable collection fields in the response
fieldDesc	Object	Required	Pass an array of objects that can contain your "field", "query", and "count" parameters for each field.
fieldDesc.field	String	Required	The field name you want to look up. To look up fields in subdocuments or arrays of subdocuments, use dot notation, such as properties.name.
fieldDesc.count	Boolean	Optional	Enter true to include the distinct item count in the result.
fieldDesc.query	Object	Optional	Pass a valid simple query to filter the related items before the distinct field value lookup.

For real world request and response examples, see the following example query and response:

Example query

{
	"$distinctRelatedItemFields": {
		"collectionDesc": {
			"_userItemId": "asset_coll_1dB8xLuu8o"
		},
		"collectionProject": {
			"_id": 1,
			"_userItemId": 1
		},
		"fieldDesc": [
			{
				"field": "properties.dtCategory.val",
				"count": "true"
			},
			{
				"field": "properties.dtType.val",
				"query": {},
				"count": "true"
			}
		]
	}
}

Sample response

 
{
	"_list": [
		{
			"_uri": "/nameduseritems/63d8d029bf52431c9cd6783d",
			"_tipVersion": 1,
			"_itemClass": "NamedUserCollection",
			"_userItemId": "asset_coll_1dB8xLuu8o",
			"_tipId": "63d8d029bf52431c9cd6783e",
			"_versions": [
				{
					"_userItemDbId": "63d8d029bf52431c9cd6783d",
					"_relatedItems": {
						"properties.dtType.val": [
							{
									"count": 2,
									"value": "Plaster Board"
							},
							{
									"count": 1,
									"value": "Tea and Canteen Tiling"
							}
					],
					"properties.dtCategory.val": [
							{
									"count": 1,
									"value": "Wall & Ceiling Finish"
							},
							{
									"count": 2,
									"value": "Ceiling"
							}
						]
					},
					"_id": "63d8d029bf52431c9cd6783e",
					"_isTip": true,
					"_metadata": {
						"_updatedById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",
						"_createdAt": 1675153449743,
						"_createdById": "057ce6fd-a306-4bdc-8514-0a45c453f7ec",
						"_updatedAt": 1675153449743
					},
					"_version": 1
				}
			],
			"_irn": "itemsvc:nameduseritem:63d8d029bf52431c9cd6783d",
			"_id": "63d8d029bf52431c9cd6783d",
			"_kind": "collection"
		}
	],
	"_time": "28ms"
}