{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Filters","type":"basic","slug":"filters","excerpt":"Narrow the results of responses.","body":"# Overview\n\nFilters are used to list resources that meet a specified criteria. If only one\nproperty of a resource is required, then instead of receiving all the devices in\nan environment and manually throwing away the undesired ones, a filter can be\napplied that will only provide the requested property.\n\n# Details\n\nFilters are applied to properties, such as `meta.$manufacturer`, to discriminate\nagainst the values of the properties. They are applied as a query parameter to the\nenvironment, device, zone, and user endpoints. Since they are a query parameter,\ninvalid URL characters must be escaped.\n\nFilters are supported on every property, except `id`, for the [list devices](doc:devices-list), [list environments](doc:environments-list), and [list zones](doc:zones-list) endpoints. \n\n# Operations\n\n* **not**: Negate the value of the passed expression\n\nCheck if:\n\n* **exists**: the property exists\n\n* **nexists**: the property does not exist\n\n* **eq**: the two given values are equivalent\n\n* **neq**: the two given values are different\n\nReturn *true* if:\n\n* **and**: all the operations are true\n\n* **or**: at least one value is true\n\n* **nor**: no values are true\n\n* **contains**: the values are elements of the passed list\n\n* **ncontains**: the values are not elements of the passed list\n\n* **in**: the property is one of the listed values\n\n* **nin**: the property is not among the list of passed values\n\n* **lt**: the first value is less than the second value\n\n* **lte**: the first value is less than or equal to the second value\n\n* **gt**: the first value is greater than the second value\n\n* **gte**: the first value is greater than or equal to the second value\n\n# Operation Arguments\n\n* **property**: array of values\n\n* **value**: element of a property\n\n* **operation**: action that returns a boolean value (`not`, `in`, `contains`, etc.)\n\n# Formats\n\n## Negation:\n\nnot\n\n```\n?filter=not(operation)\n```\n\n## Logical Comparators:\n\nlt, lte, gt, gte, eq, neq\n\n```\n?filter=comparator(property, value)\n```\n\n## Logical Operators:\n\nand, or, nor\n\n```\n?filter=operator(operation, operation)\n```\n\n## Array Operators:\n\ncontains, ncontains\n\n```\n?filter=operator(property, value)\n```\n\n## Existence Operators:\n\nexists, nexists\n\n```\n?filter=operator(property)\n```\n\n## Matching Operators:\n\nin, nin\n\n```\n?filter=operator(property, value, value, ...)\n```\n\n\n# Examples\n\nSample device `C5aw24f04teb96bfc12o6e2cb` aliased `stereo`:\n\n```\n{\n    \"id\": \"C5aw24f04teb96bfc12o6e2cb\",\n    \"ecosystemId\": \"C5qebkf2627ab6vf4u2e39d2w\",\n    \"environmentId\": \"E5k0j450a9m99y00c128te2cv\",\n    \"type\": \"physical\",\n    \"edgeId\": \"F2-50-BC-59-B9-C2\",\n    \"alias\": \"stereo\",\n    \"meta\": {\n        \"$manufacturer\": \"FancyHome\",\n        \"location\": \"LivingRoom\",\n        \"testEquipment\": false,\n        \"modelYear\": 2017,\n        \"volumePresets\": [23, 39, 51, 72, 88]\n    }\n}\n```\n\nSample device `D1a0b4f07228ea674ac07b9bc` aliased `light`:\n```\n{\n    \"id\": \"D1a0b4f07228ea674ac07b9bc\",\n    \"ecosystemId\": \"C52eb9f2627ab6af412e39d27\",\n    \"environment\": \"E5901450a9e99f00c128be2c1\",\n    \"alias\": \"light\",\n    \"type\": \"physical\",\n    \"meta\": {\n        \"$manufacturer\": \"FancyHome\",\n        \"location\": \"Garage\",\n        \"testEquipment\": true,\n        \"modelYear\": 2016,\n        \"successes\": {\n            \"test1\": false,\n            \"test2\": false,\n            \"test3\": true,\n            \"test4\": false\n        },\n        \"colors\": [\"red\", \"white\", \"blue\"],\n        \"brightnessPresets\": [7, 23, 42, 69, 86]\n    }\n}\n```\n\n## Logical Comparison:\n\n```\n?filter=lte(meta.testEquipment, false)\n```\nReturns `stereo`\n\n```\n?filter=gte(meta.modelYear, 2016), eq(type, \"physical\")\n```\nReturns `stereo` and `light`\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"NOTE\",\n  \"body\": \"Each applied filter is assumed to be required.\"\n}\n[/block]\n## Logical Operations:\n\n```\n?filter=nor(eq(meta.$manufacturer, \"FancyFake\"), lt(meta.modelYear, 2016))\n```\nReturns `true`\n\n```\n?filter=or(eq(meta[successes][test3], false), gt(meta.modelYear, 2017))\n```\nReturns `false`\n\n\n## Array Operations:\n\n```\n?filter=contains(meta.brightnessPresets, 42)\n```\nReturns `true`\n\n```\n?filter=ncontains(meta.colors, \"white\")\n```\nReturns `false`\n\n## Existence Operations:\n\n```\n?filter=exists(meta.successes)\n```\nReturns `light.json`\n\n```\n?filter=nexists(meta.modelYear)\n```\nReturns `{}`\n\n## Matching Operations:\n\n```\n?filter=in(meta.location, \"LivingRoom\", \"BedRoom\")\n```\nReturns `stereo`\n\n```\n?filter=nin(meta.location, \"LivingRoom\", \"DiningRoom\"), contains(meta.colors, \"red\")\n```\nReturns `light`","updates":[],"order":3,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5a73774fc037f5006b9c58ab","project":"568bdc1483d2061900d86cdc","version":{"version":"0","version_clean":"0.0.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e","5b258091bc7a6700033b9cb5","5b26e48e024807000315a740","5b44edff3306680003663f5c","5b468abd3d4a9e0003789111","5b468d8f3dcb6a0003c6e374","5b47b0b93d4a9e000378a33a","5b538d114ea24f00033c726f","5b6a0efe402b32000336c33f","5bba5e5d7ba7710003bd902a","5bc2703349ac3a0013eec3e5","5c351061191e2b002b4988a8","5c8b01b199b56e00440aa018"],"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","__v":35},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Features","slug":"features","order":12,"from_sync":false,"reference":false,"_id":"5b47b0b93d4a9e000378a33a","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","createdAt":"2018-07-12T19:49:13.569Z","__v":0},"user":"5a6a26281895510045b2cd40","createdAt":"2018-02-01T20:23:43.719Z","githubsync":"","__v":0,"parentDoc":null}