Filter by Metadata

Optionally use the filters parameter of the query API to provide metadata filters to narrow search results.

For details and the full list of parameters accepted by the query API, see Semantic Search.

The filters parameter is used to filter search results. The following operators are supported:

Operator Input Type Description Example

$eq

String, Number, Boolean

Equal to operator for single values

Retrieves records where a field value equals the specified value.

 
{
  "genre": {
    "$eq": "documentary"
  }
}

$ne

String, Number, Boolean

Not equal to operator

Retrieves records where a field value does not equal the specified value.

 
{
  "genre": {
    "$ne": "drama"
  }
}

$gt

Number

Greater than operator

Retrieves records where a field value is greater than the specified value.

 
{
  "year": {
    "$gt": 2019
  }
}

$gte

Number

Greater than or equal to operator

Retrieves records where a field value is greater than or equal to the specified value.

 
{
  "year": {
    "$gte": 2020
  }
}

$lt

Number

Less than operator

Retrieves records where a field value is less than the specified value.

 
{
  "year": {
    "$lt": 2020
  }
}

$lte

Number

Less than or equal to operator

Retrieves records where a field value is less than or equal to the specified value.

 
{
  "year": {
    "$lte": 2020
  }
}

$in

Non-empty array of primitives

In an array operator

Retrieves records where a field value corresponds to any value in the specified array.

 
{
  "genre": {
    "$in": [
      "comedy",
      "documentary"
    ]
  }
}

$nin

Non-empty array of primitives

Not in an array operator

Retrieves records where a field value does not correspond to any values in the specified array.

 
{
  "genre": {
    "$nin": [
      "comedy",
      "documentary"
    ]
  }
}

$exists

Boolean

Field existence operator

Retrieves records that contain (if set to True) or do not contain (if set to False) a specified value. 

{
  "genre": {
    "$exist": true
  }
}
{
  "genre": {
    "$exist": false
  }
}

$and

Non-empty array of filters

Logical AND operator

Retrieves records that contain all specified values or conditions.

 
{
  "$and": [
    {
      "genre": {
        "$eq": "drama"
      }
    },
    {
      "year": {
        "$gte": 2020
      }
    }
  ]
}

$or

Non-empty array of filters

Logical OR operator

Retrieves records that contain at least one of the specified values or conditions. 

{
  "$or": [
    {
      "genre": {
        "$eq": "drama"
      }
    },
    {
      "year": {
        "$gte": 2020
      }
    }
  ]
}

See the following for an example of a semantic search using filters to specify that results must have a category equal to electronics and a price less than 200. This example uses the Python query API: 

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>", # or username="<user>", password="<pass>"
))

#search by text with filtering
text_filter_results = client.query(
    table_name='products',
    query_by={'text': 'wireless headphones'},
    top_k=5,
    filters={
        '$and': [
            {'category': {'$eq': 'electronics'}},
            {'price': {'$lt': 200}}
        ]
    }
)
print(text_filter_results)

Examples with filters using Curl and PL/SQL can be found at Semantic Search.