Filtering Data

When returning result sets, it is generally possible to include filtering criteria to avoid downloading the whole result set (especially useful for things that accumulate over time, like CDRs).




Suppose you have JSON objects like:



Root-level matching

To match on a root-level key, simply use the key name prepended by filter_. The query may look similar to:

GET /v1/accounts/{account_id}/endpoint?filter_key1=c-vox

This will return all objects where the value of Object["key1"] is equal to "c-vox".

  Currently, only direct, case-sensitive matching is supported. So "C-Vox" is different to "c-vox", and "vox" will not match "c-vox".


Sub-key matching

To match a sub-key, one needs only include the dot-delimited key path in the query string. The query may look similar to:

GET /v1/accounts/{account_id}/endpoint?filter_key2.subkey1=conversant

This will return all objects where the value of Object["key2"]["subkey1"] == "conversant".


Inverse matching

If you want a negative filter, try using filter_not_{key}

GET /v1/accounts/{account_id}/endpoint?filter_not_key2.subkey1=conversant

This will include documents which have "key2.subkey1" not equal to "conversant".


Key and value existence

has_key - Does the key exist on the document

key_missing - Is the key not on the document

has_value - is the value not an empty value. Empty values include:

  • The number 0
  • The empty list, [ ]
  • The string "0"
  • The boolean false
  • The string "false"
  • null
  • The string "NULL"
  • The string "undefined"
  • The float 0.0
  • The empty JSON object \{ }


Specialised range queries

C-Vox documents include "created" and "modified" timestamp fields (in Gregorian seconds) as part of saving the document. These fields are usable for filtering as well. To do so, you will need to know the range of timestamps you wish to use. *tip To convert from Gregorian seconds to Unix timestamp, subtract 62167219200.

There are two query parameters available: "created_from" and "created_to". If one wants a list of all documents created before a timestamp, use "created_to"; for documents created after a timestamp, use "created_from". The query may look similar to:

GET /v1/accounts/{account_id}/endpoint?created_from=63489748075&created_to=63492595200

This will filter documents created after 63489748075 (2011-11-29 01:07:55 UTC) but before 63492595200 (2012-01-01 00:00:00 UTC).

Use "modified_from" and "modified_to" to retrieve documents by their last update timestamp.


Chaining filters

Using more than one filter or range query is possible. All valid filters/range queries are logically ANDed together to determine if a document should be included. To match the document at the top by both fields used in the examples, the query would look similar to:

GET /v1/accounts/{account_id}/endpoint?filter_key1=c-vox&filter_key2.subkey1=conversant