Skip to main content

Filtering and Facets

Filters narrow search results to a specific subset of your catalog. Facets return aggregated counts for field values, enabling faceted navigation interfaces where users can refine results by category, brand, price range, and other attributes.

filter_by Parameter​

Add a filter_by string to your search request to restrict results. Filters do not affect relevance scoring -- they only include or exclude documents.

Exact Match​

filter_by: "brand:Nike"

Numeric Comparison​

filter_by: "price:>50"
filter_by: "price:>=50"
filter_by: "price:<200"
filter_by: "price:<=200"

Range​

filter_by: "price:[50..200]"

Negation​

filter_by: "brand:!Nike"

Multiple Values (OR within a field)​

filter_by: "brand:[Nike,Adidas,Puma]"

Boolean Operators​

Combine multiple filter clauses with && (AND) or || (OR):

filter_by: "brand:Nike && price:[50..200]"
filter_by: "category:Running || category:Training"

Full Example​

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "shoes",
    "filter_by": "brand:[Nike,Adidas] && price:[50..200] && in_stock:true",
    "per_page": 10
  }'

This returns shoes from Nike or Adidas, priced between $50 and $200, that are currently in stock.

Facets​

Facets return the distinct values for specified fields along with the count of matching documents for each value. They are essential for building filter sidebars.

facet_by​

Pass a comma-separated list of field names to facet_by:

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "shoes",
    "facet_by": "brand,category,color",
    "max_facet_values": 20
  }'

Facet Response​

The response includes a facet_counts array alongside the usual hits:

{
  "found": 312,
  "hits": [ ... ],
  "facet_counts": [
    {
      "field_name": "brand",
      "counts": [
        { "value": "Nike", "count": 87 },
        { "value": "Adidas", "count": 64 },
        { "value": "New Balance", "count": 45 },
        { "value": "Puma", "count": 38 }
      ]
    },
    {
      "field_name": "category",
      "counts": [
        { "value": "Running", "count": 120 },
        { "value": "Training", "count": 89 },
        { "value": "Casual", "count": 63 },
        { "value": "Basketball", "count": 40 }
      ]
    },
    {
      "field_name": "color",
      "counts": [
        { "value": "Black", "count": 98 },
        { "value": "White", "count": 76 },
        { "value": "Blue", "count": 52 },
        { "value": "Red", "count": 41 }
      ]
    }
  ]
}

max_facet_values​

Controls how many distinct values are returned per facet. Defaults to 10.

{
  "q": "shoes",
  "facet_by": "brand",
  "max_facet_values": 50
}

Standalone Filter Endpoints​

Seekora provides dedicated endpoints for filter-related queries independent of a full search.

POST /v1/filters​

Retrieve facet counts without performing a search query. Useful for pre-populating filter sidebars on collection pages.

curl -X POST https://api.seekora.ai/v1/filters \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "facet_by": "brand,category,price,color",
    "filter_by": "category:Running",
    "max_facet_values": 30
  }'

POST /v1/filters/{facetName}/values​

Retrieve values for a specific facet with typeahead support. This is useful for building searchable dropdowns within a filter panel.

curl -X POST https://api.seekora.ai/v1/filters/brand/values \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "ni",
    "filter_by": "category:Running"
  }'

Response:

{
  "values": [
    { "value": "Nike", "count": 87 },
    { "value": "Ninewest", "count": 12 }
  ]
}

GET /v1/filters/schema​

Discover which fields are available for filtering and their types.

curl https://api.seekora.ai/v1/filters/schema \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret"

Response:

{
  "fields": [
    { "name": "brand", "type": "string", "facet": true },
    { "name": "category", "type": "string", "facet": true },
    { "name": "price", "type": "float", "facet": true },
    { "name": "color", "type": "string", "facet": true },
    { "name": "in_stock", "type": "bool", "facet": false },
    { "name": "rating", "type": "float", "facet": true }
  ]
}

Combining Filters with Facets​

A common pattern is to apply the user's selected filters while still returning facet counts so the sidebar updates dynamically:

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "sneakers",
    "filter_by": "brand:Nike && price:[50..150]",
    "facet_by": "brand,category,color,price",
    "max_facet_values": 20,
    "per_page": 12
  }'

The facet counts in the response reflect the filtered result set, allowing your UI to show accurate counts for each remaining filter option.

Next Steps​