Visii Documentation

# Queries & Filters

This section describes the method of querying to filter results across the Vision API endpoints.

If you wish to query an array type field in your metadata it must be enabled for querying with the datasets settings resource endpoint.

# Query Parameter

When you have a large dataset and you want an additional way of filtering through all the content, you can take advantage of the filter functionality by using the query (q) parameter. The dataset content can have an attached metadata attribute (specified when adding the content to a dataset using datasets content resource) which is a map of key - values specific to the resource.

An example of such a metadata attribute is:

  "metadata": {
    "title": "Lighthouse on a summer day",
    "category": "art",
    "quantity": 10,
    "price": 99.99,
    "available": true,
    "sizes": ["small", "medium", "large"],
    "colours": ["red","white","blue"]
  }

# Filter Operations

The query (q) parameter can specify multiple filters that all have to match in order for the content to be taken into consideration for the potential result. The filters are separated by the comma character and each filter is specified in the form <key>:<value> (both parameters are required).

The text key is a reserved field and query parameter used in Search By Text functionality. All string metadata fields are searched when the feature is enabled on your dataset.

The field referenced by <key> must be of types: boolean, number, string or array*.

If the same <key> is passed in for types that don't support AND, only the last filter will be used.

Special note for *array* type metadata fields

To index an array field, it must be enabled for querying with the datasets settings resource endpoint.

Encoding Values

Each individual value needs to be encoded (e.g. using encodeURIComponent(value)) before added to the q parameter.

When using negation, the operator (!) in considered part of the value, so it needs to be encoded as well.

# Filter: AND

<key>:<value>,<key>:<value>
---------------------------
<key> string
<value> string or number

Ensure results have all values specified for the same key.

Supported metadata type: array (see note above)

# Examples

  • colours:blue,colours:red - return results with colours matching blue AND red
  • sizes:small,sizes:medium,sizes:large - return results with sizes small,medium AND large
  • tags:brown,tags:cat - return results that match the tags field brown AND cat
  • category:dogs,category:cats - as this is not a array field, the results will only match the last category field cats

# Filter: Equality

<key>:<value>
-------------
<key> string
<value> boolean, string, number

Ensure results have a particular value.

Supported metadata types: boolean, string, number or array (see note above)

# Examples

  • category:animals - return results with category string matching animals
  • height:5 - return results with height number equal to 5
  • tags:brown,tags:cat - return results that match the tags field brown AND cat (See AND)

# Filter: Range

<key>:<min-value>:<max-value>
-----------------------------
<key> string
<min-value> number or empty *
<max-value> number or empty *

* at least 1 required

For cases where a value must be within a range, at least one min-value or max-value is required. An empty value indicates infinity.

Both range values are included, as the operation is min-value >= result-value <= max-value.

Supported metadata types: number

# Examples

  • price:49.99:99.99: for a price of 49.99 and above until 99.99.
  • width:2.5:: for a width including 2.5 to infinity (and beyond!).

# Filter: OR

<key>:<value>|<value>[|<value>...]
----------------------------------
<key> string
<value> boolean, string or number

Ensure results have at least 1 particular value that is provided as an array separated by |.

Supported metadata types: boolean, string, number or array (see note above)

# Examples

  • category:animals|paintings - results will have category with value animals or paintings.
  • sizes:small|medium|large - results will have sizes of small, medium or large

# Filter: Negation

<key>:!<value>
-------------
<key> string
<value> boolean, string, number

Ensure results don't have a particular value.

Supported metadata types: boolean, string, number or array (see note above)

# Examples

  • category:!animals - results will be any category except animals.
  • width:!2.5 - results will be any width except 2.5.
  • tags:animal,tags:!cat - return results that match the tags field animal when the cat value is missing.
  • tags:!cat,tags:!dog - chain multiple negations for array fields

# Substring filtering

<key>:*<value>*
-------------
<key> string
<value> string

Ensure results start with, end with or contain a substring value. Results are case insensitive.

# Examples

  • title:*house - results will be any title that ends with house.
  • title:Lighthouse* - results will be any title that starts with Lighthouse.
  • title:*house* - results will be any title that contains the substring house.

In case your query value starts or ends with the * character, that character needs to be escaped by using repetition (** instead of *).

# Combined Examples

  • Get only results in the art category where the price is between 10 and 100: q=category:art,price:10:100.
  • Get only results in the furniture category with colours red or blue that are available: q=category:furniture,colours:red|blue,available:true.
  • Get only results in large quantity of 5 or more and inside a specific budget: q=quantity:5:,price:5:15.
  • Get only results with tags that match funny and humour that are small or large: q=tags:funny,tags:humour,sizes:small|large.

# Filter Errors

When we detect invalid or unknown filter parameters, two additional fields are added to the response to help you understand the reason and easily retry the request without the filters that caused the error:

  • errors - a list of objects detailing the offending field / value and the reason
  • links - an object containing links to follow depending on how you want to recover from the error
    • valid - the initial request URL without the invalid filter fields

For the following request URL (https://api.visii.com/orgs/my-org/datasets/my-dataset/explore?limit=3&q=category:animals,score:a12,price:fff:,categories:unknown,status:1) the output will be:

{
  "errors": [
    {
      "field": "category",
      "message": "There is no field with this name"
    },
    {
      "expected_type": "float",
      "field": "score",
      "message": "Invalid type for filter value",
      "value": "a12"
    },
    {
      "field": "price",
      "message": "Filtering by range can only be done on numbers",
      "value": "fff"
    },
    {
      "field": "categories",
      "message": "Array value is not enabled for field in the dataset settings",
      "value": "unknown"
    }
  ],
  "links": {
    "valid": "https://api.visii.com/orgs/my-org/datasets/my-dataset/explore?limit=3&q=status:1"
  },
  "message": "Unable to return results due to filter errors",
  "status": "error"
}
Last Updated: 6/30/2022, 12:24:16 PM

← Advanced configuration →