Skip to main content
Filters let you narrow search results based on document attributes. Only attributes with is_filterable: true in the namespace schema can be used in filters.

​
Basic filters

A filter is a JSON object where keys are attribute names and values are the match conditions. 
{"status": "open"}
This is shorthand for an equality check. It’s equivalent to: 
{"status": {"$eq": "open"}}

​
Operators

​
Comparison

OperatorDescriptionExample
$eqEqual to{"status": {"$eq": "open"}}
$neqNot equal to{"status": {"$neq": "closed"}}
$gtGreater than{"priority": {"$gt": 3}}
$gteGreater than or equal to{"priority": {"$gte": 3}}
$ltLess than{"priority": {"$lt": 5}}
$lteLess than or equal to{"priority": {"$lte": 5}}

​
Set membership

OperatorDescriptionExample
$inValue is in the list{"status": {"$in": ["open", "pending"]}}
$not_inValue is not in the list{"status": {"$not_in": ["closed", "archived"]}}

​
Contains

OperatorDescriptionExample
$containsArray attribute contains the value{"tags": {"$contains": "bug"}}
$contains_anyArray attribute contains any of the values{"tags": {"$contains_any": ["bug", "critical"]}}

​
Logical operators

Combine multiple conditions with $and and $or.

​
$and

All conditions must match: 
{
  "$and": [
    {"status": "open"},
    {"priority": {"$gte": 3}},
    {"tags": {"$contains": "production"}}
  ]
}

​
$or

At least one condition must match: 
{
  "$or": [
    {"severity": "critical"},
    {"severity": "high"}
  ]
}

​
Nesting

Logical operators can be nested: 
{
  "$and": [
    {"status": "open"},
    {
      "$or": [
        {"severity": "critical"},
        {"priority": {"$gte": 4}}
      ]
    }
  ]
}

​
Filter values

Filter values can be:
TypeExample
String"open"
Number42, 3.14
Booleantrue, false
Nullnull
curl -X POST https://api.withcharcoal.com/v1/namespaces/support-tickets/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Find unresolved authentication issues",
    "context": "Looking for open tickets related to authentication failures in the production environment.",
    "filters": {
      "$and": [
        {"status": {"$in": ["open", "in_progress"]}},
        {"environment": "production"},
        {"tags": {"$contains": "auth"}}
      ]
    }
  }'