Filters

Most API endpoints support filtering to retrieve or edit a subset of resources that match certain criteria, such as:

• Filtering actions by Thng ID
• Filtering Thngs by product ID
• Find products that are named 'x'
• Find places tagged 'ACME Inc'

📘

Note

Any update or delete operations that use filters are limited to 500 resources. If more than 500 resources match the specified filter, an error is returned and no resource is changed.

To modify many resources, paginate them and carry out the desired operation on each page of items. You can also do this using the SDKs.

Explicit ID-based Filtering

Many API endpoints allow you to specify the IDs of resources that are to be returned. This is particularly useful when you want to edit a set of resources (for example, update the names of a few Thngs). To explicitly select a few Thngs, use the ?ids=X query parameter, where X is a list of (existing) URL-encoded comma-separated resource IDs (up to 100). For example, to update the name of multiple products by id, use the following request:

PUT /products?ids=:productId1,:productId2,:productId3
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ProductDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.io.v2/products?ids%3DU2E9hmyCVg8atpRwwXgTqcrt%2CUFEsATFh63PhhqwaRhEdeAek%2CUFcMeG6e5gwhWGSsE4gccKfk' \
  -d '{
    "name": "Updated name"
  }'

const ids = [
  'U2E9hmyCVg8atpRwwXgTqcrt',
  'UFEsATFh63PhhqwaRhEdeAek',
  'UFcMeG6e5gwhWGSsE4gccKfk',
];

const payload = { name: 'Updated name' };
const params = { ids: ids.join(',') };

user.product().update(payload, { params })
  .then(console.log);

Iterator<PVector<Thng>> iterator = apiManager.thngService().iterator()
    .filter("name=Original name").execute();

🚧

Warning

The filter query string must be URL-encoded.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "U2E9hmyCVg8atpRwwXgTqcrt",
    "name": "Updated name",
    ...
  }, {
    "id": "UFEsATFh63PhhqwaRhEdeAek",
    "name": "Updated name",
    ...
  }, {
    "id": "UFcMeG6e5gwhWGSsE4gccKfk",
    "name": "Updated name",
    ...
  }
]

Query-based Filtering

Filters retrieve or edit multiple resources that match a particular condition. You can append ?filter=X to the endpoint URL when doing a GET, PUT, or DELETE operation (where X is a query). Note that the ?filter is mutually exclusive with ?ids where a list of existing resource IDs must be given.

📘

Note

Filters that include multiple conditions (for example, name=test&tags=device) are evaluated from left to right. In the example, name is matched, and the results are filtered for tags.

Query Structure

Our queries are of the form X AND Y AND Z only. We don't support the OR operator. Other operators supported are listed in the table below.

🚧

Warning

The available operators vary depending on the type of resource being filtered. See Available Fields for more information about resource filterable fields.

Simple Field Filtering Examples

You can search for any field of a Thng or product.

Most API endpoints support the ?filter=X query parameter that limits the results returned to only the resources that match the query criteria. See the following examples:

• /thngs?filter=name%3Dtv
  Find all Thngs named tv

• /products?filter=name%3Dmilk%2Cegg
  Find all products named milk OR egg

• /thngs?filter=name%3Dsensor*
  Find all Thngs whose name start with sensor

• /thngs?filter=tags%3DUK
  Find all Thngs that contain the tag UK

• /thngs?filter=tags%3DUK%2Cshipped
  Find all Thngs that contain the tags UK OR shipped

• /thngs?filter=tags%3DUK%26tags%3Dshipped
  Find all Thngs that contain the tag UK AND shipped

• /actions/all?filter=timestamp%3E1477323564350
  Find all actions created after 1477323564350 (timestamp is larger than 1477323564350)

• /actions/all?filter=timestamp%3D1477323564350..1478871333924
  Find all actions by timestamp created after 1477323564350 and before 1478871333924 (inclusive).

Available Fields

Depending on the resource being filtered, a separate set of filter fields is available. These are described for each resource's respective page in the API Reference after the resource's main definition.

For example, for the ThngDocument resource type, the filterable fields are listed.

Filtering in evrythng.js

Filtering in evrythng.js works the same way as parameters, with some additional helpers:

// Simple string - same as the REST API
user.product().setFilter('name=Actuator,Sensor&tags=shipped')
  .read()
  .then(console.log);

// Object notation
const filter = { name: 'Actuator,Sensor', tags: 'shipped' };
user.product().setFilter(filter)
  .read()
  .then(console.log);

// Find by identifiers key
const factoryId = 'f2323786';
const filter = `identifiers.gs1:414=${factoryId}`;
user.place().setFilter(filter)
  .read()
  .then(console.log);