distinctRelatedItemField queries

distinctRelatedItemField query

Use a distinctRelatedItemField query to return the field values of related items in a named user collection.

Note: The distinctRelatedItemField query forms a wrapper over the simple query distinct method without the options.

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

{
  "$distinctRelatedItemField": {
    "collectionDesc": {
      //"<property to identify collection by>": "<value>"
    },
    "collectionProject": {
      //"<related item fields you want to appear in the response>": 1
    },
    "field": "<property you want to query>",
    "query": {
      //"<the value you put in the field property above>": {
        //simple query such as the following example
        //"$in": ["Steel", "Wood"]
      //}
    }
  }
}
   

distinctRelatedItemField 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
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.
query	Object	Optional	Add criteria to filter the related items in the collection you selected in the collectionDesc query.

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

Example query

{
  "$distinctRelatedItemField": {
    "collectionDesc": {
      "_userItemId": "11_new_ba_elem_1sjwcciumd",
      "_versions.all": true
    },
    "collectionProject": {
      "_id": 1,
      "_userItemId": 1
    },
    "field": "type_id",
    "query": {}
  }
}

Example response

{
  "_list": [
    {
      "_uri": "/nameduseritems/5cee7fee6505d6286dbca469",
      "_tipVersion": 2,
      "_itemClass": "NamedUserCollection",
      "_userItemId": "11_new_ba_elem_1sjwcciumd",
      "_tipId": "5cee814dfa298d0d3e34e246",
      "_versions": [
        {
          "_userItemDbId": "5cee7fee6505d6286dbca469",
          "_relatedItems": {
            "type_id": [
              1,
              26,
              55,
              60
            ]
          },
          "_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": {
            "type_id": [
              442,
              463,
              474,
              506,
              535,
              554,
              575,
              610
            ]
          },
          "_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": "20ms"
}