{"_id":"5a73774fc037f5006b9c58ab","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":33,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"5b47b0b93d4a9e000378a33a","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-07-12T19:49:13.569Z","from_sync":false,"order":12,"slug":"features","title":"Features"},"user":"5a6a26281895510045b2cd40","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-01T20:23:43.719Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"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`","excerpt":"Narrow the results of responses.","slug":"filters","type":"basic","title":"Filters"}

Filters

Narrow the results of responses.

# Overview Filters are used to list resources that meet a specified criteria. If only one property of a resource is required, then instead of receiving all the devices in an environment and manually throwing away the undesired ones, a filter can be applied that will only provide the requested property. # Details Filters are applied to properties, such as `meta.$manufacturer`, to discriminate against the values of the properties. They are applied as a query parameter to the environment, device, zone, and user endpoints. Since they are a query parameter, invalid URL characters must be escaped. Filters 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. # Operations * **not**: Negate the value of the passed expression Check if: * **exists**: the property exists * **nexists**: the property does not exist * **eq**: the two given values are equivalent * **neq**: the two given values are different Return *true* if: * **and**: all the operations are true * **or**: at least one value is true * **nor**: no values are true * **contains**: the values are elements of the passed list * **ncontains**: the values are not elements of the passed list * **in**: the property is one of the listed values * **nin**: the property is not among the list of passed values * **lt**: the first value is less than the second value * **lte**: the first value is less than or equal to the second value * **gt**: the first value is greater than the second value * **gte**: the first value is greater than or equal to the second value # Operation Arguments * **property**: array of values * **value**: element of a property * **operation**: action that returns a boolean value (`not`, `in`, `contains`, etc.) # Formats ## Negation: not ``` ?filter=not(operation) ``` ## Logical Comparators: lt, lte, gt, gte, eq, neq ``` ?filter=comparator(property, value) ``` ## Logical Operators: and, or, nor ``` ?filter=operator(operation, operation) ``` ## Array Operators: contains, ncontains ``` ?filter=operator(property, value) ``` ## Existence Operators: exists, nexists ``` ?filter=operator(property) ``` ## Matching Operators: in, nin ``` ?filter=operator(property, value, value, ...) ``` # Examples Sample device `C5aw24f04teb96bfc12o6e2cb` aliased `stereo`: ``` { "id": "C5aw24f04teb96bfc12o6e2cb", "ecosystemId": "C5qebkf2627ab6vf4u2e39d2w", "environmentId": "E5k0j450a9m99y00c128te2cv", "type": "physical", "edgeId": "F2-50-BC-59-B9-C2", "alias": "stereo", "meta": { "$manufacturer": "FancyHome", "location": "LivingRoom", "testEquipment": false, "modelYear": 2017, "volumePresets": [23, 39, 51, 72, 88] } } ``` Sample device `D1a0b4f07228ea674ac07b9bc` aliased `light`: ``` { "id": "D1a0b4f07228ea674ac07b9bc", "ecosystemId": "C52eb9f2627ab6af412e39d27", "environment": "E5901450a9e99f00c128be2c1", "alias": "light", "type": "physical", "meta": { "$manufacturer": "FancyHome", "location": "Garage", "testEquipment": true, "modelYear": 2016, "successes": { "test1": false, "test2": false, "test3": true, "test4": false }, "colors": ["red", "white", "blue"], "brightnessPresets": [7, 23, 42, 69, 86] } } ``` ## Logical Comparison: ``` ?filter=lte(meta.testEquipment, false) ``` Returns `stereo` ``` ?filter=gte(meta.modelYear, 2016), eq(type, "physical") ``` Returns `stereo` and `light` [block:callout] { "type": "info", "title": "NOTE", "body": "Each applied filter is assumed to be required." } [/block] ## Logical Operations: ``` ?filter=nor(eq(meta.$manufacturer, "FancyFake"), lt(meta.modelYear, 2016)) ``` Returns `true` ``` ?filter=or(eq(meta[successes][test3], false), gt(meta.modelYear, 2017)) ``` Returns `false` ## Array Operations: ``` ?filter=contains(meta.brightnessPresets, 42) ``` Returns `true` ``` ?filter=ncontains(meta.colors, "white") ``` Returns `false` ## Existence Operations: ``` ?filter=exists(meta.successes) ``` Returns `light.json` ``` ?filter=nexists(meta.modelYear) ``` Returns `{}` ## Matching Operations: ``` ?filter=in(meta.location, "LivingRoom", "BedRoom") ``` Returns `stereo` ``` ?filter=nin(meta.location, "LivingRoom", "DiningRoom"), contains(meta.colors, "red") ``` Returns `light`