findInCollections

findInCollections query

Use the findInCollections query to look up named user collections and their related items based on your criteria.

For more information on the structure and fields of a findInCollections query, see the following example code structure with reference to Table 1.

{
  "$findInCollections": {
    "collectionDesc": {
        "<property to identify collection by>": "<value>"
    },
    "collectionProject": {
      "<collection property fields you want to appear in the response>": 1
    },
    "query": {
      "<property to query>": "<criteria to filter the related items in the collection you selected in the collectionDesc query>"
    },
    "options": {
      "project": {
        "<related item fields you want to appear in the response>": 1
      },
    "page": {
      "_pageSize": <the number of collections to return on a page>,
      "_offset": <the index you want to start returing results for>,
      "sort": {
        "<property you want to sort by in the response>": 1
      }
    }
  }
}
   

findInCollections query request fields table

Field	Type	Required	Description
collectionDesc	Object	Required	Enter a valid simple query to run on your collections list. 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
query	Object	Optional	Add criteria to filter the related items in the collection you selected in the collectionDesc query.
readings	Object	Optional	Query telemetry data. For more information, see readings query in a findInCollections query.
options	Object	Optional	Insert query control options, such as pagination, sorting, and projection in an options object.
options.page	Object	Optional	Set the _pageSize and _offset in the options.page object. <b>Note:</b> If you do not, the default for page size is 200 and for offset, 0.
options.project	Object	Optional	Simple query projection to enable or disable related item fields in the response
options.sort	Object	Optional	Simple query sort to sort your results by related item fields

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

Example query

{
  "$findInCollections": {
    "collectionDesc": {
      "_itemClass": "NamedUserCollection",
      "_versions.all": true
    },
    "collectionProject": {
      "_userItemId": 1,
      "_name": 1
    },
    "query": {
      "type_id": 278
    },
    "options": {
      "project": {
        "source_id": 1
      },
      "page": {
        "_pageSize": 100,
        "_offset": 0
      },
      "sort": {
        "_metadata._updatedAt": 1
      }
    }
  }
}

Example response

{
  "_list": [
    {
      "_uri": "/nameduseritems/5cee7fef6505d6286dbca46a",
      "_name": "11_new_geom_view",
      "_tipVersion": 1,
      "_itemClass": "NamedUserCollection",
      "_userItemId": "11_new_geom_view_4LeaYYWpsz",
      "_tipId": "5cee80c1fa298d0d3e34e23c",
      "_versions": [
        {
          "_userItemDbId": "5cee7fef6505d6286dbca46a",
          "_relatedItems": {
            "_pageSize": 0,
            "_list": [],
            "_offset": 0,
            "_total": 0
          },
          "_id": "5cee80c1fa298d0d3e34e23c",
          "_isTip": true,
          "_metadata": {
            "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_createdAt": 1559134191563,
            "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_updatedAt": 1559134191563
          },
          "_version": 1
        }
      ],
      "_irn": "itemsvc:nameduseritem:5cee7fef6505d6286dbca46a",
      "_id": "5cee7fef6505d6286dbca46a",
      "_kind": "collection"
    },
    {
      "_uri": "/nameduseritems/5cee7fee6505d6286dbca468",
      "_name": "11_new_elem_props",
      "_tipVersion": 1,
      "_itemClass": "NamedUserCollection",
      "_userItemId": "11_new_elprops_qagnj32kE7",
      "_tipId": "5cee80c1fa298d0d3e34e23a",
      "_versions": [
        {
          "_userItemDbId": "5cee7fee6505d6286dbca468",
          "_relatedItems": {
            "_pageSize": 0,
            "_list": [],
            "_offset": 0,
            "_total": 0
          },
          "_id": "5cee80c1fa298d0d3e34e23a",
          "_isTip": true,
          "_metadata": {
            "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_createdAt": 1559134190147,
            "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_updatedAt": 1559134190147
          },
          "_version": 1
        }
      ],
      "_irn": "itemsvc:nameduseritem:5cee7fee6505d6286dbca468",
      "_id": "5cee7fee6505d6286dbca468",
      "_kind": "collection"
    },
    {
      "_uri": "/nameduseritems/5cee7fee6505d6286dbca469",
      "_name": "11_new_elements",
      "_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"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef59",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038450"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef5a",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038463"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef5b",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038933"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef5c",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038950"
              }
            ],
            "_offset": 0,
            "_total": 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": 3,
            "_list": [
              {
                "_id": "5cee7fe8c27e69cd0209ef58",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-0003842e"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef59",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038450"
              },
              {
                "_id": "5cee7fe8c27e69cd0209ef5b",
                "source_id": "dd7a8b4b-7241-4687-87aa-fd7906f76354-00038933"
              }
            ],
            "_offset": 0,
            "_total": 3
          },
          "_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"
    },
    {
      "_uri": "/nameduseritems/5cee7fef6505d6286dbca46b",
      "_name": "11_new_type_el",
      "_tipVersion": 1,
      "_itemClass": "NamedUserCollection",
      "_userItemId": "11_new_type_el_uUUlgM1sn4",
      "_tipId": "5cee80c1fa298d0d3e34e23d",
      "_versions": [
        {
          "_userItemDbId": "5cee7fef6505d6286dbca46b",
          "_relatedItems": {
            "_pageSize": 0,
            "_list": [],
            "_offset": 0,
            "_total": 0
          },
          "_id": "5cee80c1fa298d0d3e34e23d",
          "_isTip": true,
          "_metadata": {
            "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_createdAt": 1559134191623,
            "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
            "_updatedAt": 1559134191623
          },
          "_version": 1
        }
      ],
      "_irn": "itemsvc:nameduseritem:5cee7fef6505d6286dbca46b",
      "_id": "5cee7fef6505d6286dbca46b",
      "_kind": "collection"
    }
  ],
  "_time": "22ms"
}