Class FilterBuilder

fluent builder for creating content selection filters

provides chainable api for constructing complex filter conditions. supports must (required), should (optional/or), and must_not (exclusion) filter types. use with search(), getRecommendations(), and other content selection methods.

filter types:

  • must: all conditions must match (AND logic)
  • should: at least one condition should match (OR logic)
  • must_not: conditions must not match (NOT logic)

Example

const filter = new FilterBuilder()
  .match("category", "electronics")
  .range("price", { gte: 100, lte: 500 })
  .match("out_of_stock", false, "must_not")
  .build();

Constructors

constructor

Properties

must should must_not

Methods

match range datetimeRange geoRadius build

Constructors

constructor

Properties

Privatemust

must: FilterCondition[] = []

Privateshould

should: FilterCondition[] = []

Privatemust_not

must_not: FilterCondition[] = []

Methods

match

  • match(field, value, type?): this

  • add exact match filter condition

    filters items where field exactly matches the specified value. supports string, number, and boolean values.

    Parameters

    • field: string

      field name to filter on

    • value: string | number | boolean

      value to match (string | number | boolean)

    • type: "must" | "should" | "must_not" = "must"

      filter type: "must" (required), "should" (optional), or "must_not" (exclude). default: "must"

    Returns this

    this filter builder for method chaining

    Example

    // required match
    builder.match("category", "electronics");

    // optional match (or condition)
    builder.match("brand", "nike", "should")
           .match("brand", "adidas", "should");

    // exclusion
    builder.match("status", "deleted", "must_not");

range

  • range(field, value, type?): this

  • add numeric range filter condition

    filters items where numeric field falls within specified range. supports gte (>=), lte (<=), gt (>), and lt (<) operators.

    Parameters

    • field: string

      numeric field name to filter on

    • value: {
          gte?: number;
          lte?: number;
          gt?: number;
          lt?: number;
      }

      range specification with operators

      • Optionalgte?: number

        greater than or equal to

      • Optionallte?: number

        less than or equal to

      • Optionalgt?: number

        greater than

      • Optionallt?: number

        less than

    • type: "must" | "should" | "must_not" = "must"

      filter type: "must", "should", or "must_not". default: "must"

    Returns this

    this filter builder for method chaining

    Example

    // price between 100 and 500
    builder.range("price", { gte: 100, lte: 500 });

    // rating above 4
    builder.range("rating", { gt: 4 });

    // exclude expensive items
    builder.range("price", { gte: 1000 }, "must_not");

datetimeRange

  • datetimeRange(field, value, type?): this

  • add datetime range filter condition

    filters items where datetime field falls within specified range. values should be RFC 3339 formatted strings (e.g., "2025-12-15T00:00:00Z").

    Parameters

    • field: string

      datetime field name to filter on

    • value: {
          gte?: string;
          lte?: string;
          gt?: string;
          lt?: string;
      }

      range specification with operators (RFC 3339 strings)

      • Optionalgte?: string

        greater than or equal to

      • Optionallte?: string

        less than or equal to

      • Optionalgt?: string

        greater than

      • Optionallt?: string

        less than

    • type: "must" | "should" | "must_not" = "must"

      filter type: "must", "should", or "must_not". default: "must"

    Returns this

    this filter builder for method chaining

    Example

    // events between two dates
    builder.datetimeRange("start_date", {
      gte: "2025-12-15T00:00:00Z",
      lte: "2025-12-31T23:59:59Z"
    });

    // events after a specific date
    builder.datetimeRange("created_at", { gt: "2025-01-01T00:00:00Z" });

geoRadius

  • geoRadius(field, lat, lon, radius, type?): this

  • add geo-radius filter condition

    filters items where geo-location field falls within specified radius from a center point. useful for location-based filtering.

    Parameters

    • field: string

      geo-location field name

    • lat: number

      latitude of center point (degrees, -90 to 90)

    • lon: number

      longitude of center point (degrees, -180 to 180)

    • radius: number

      search radius in meters

    • type: "must" | "should" | "must_not" = "must"

      filter type: "must", "should", or "must_not". default: "must"

    Returns this

    this filter builder for method chaining

    Example

    // items within 5km of new york city
    builder.geoRadius("location", 40.7128, -74.0060, 5000);

    // exclude items near specific location
    builder.geoRadius("warehouse", 37.7749, -122.4194, 10000, "must_not");

build

  • build(): ContentSelectionFilter

  • build final filter object

    constructs the complete filter object from all added conditions. call this method last after chaining all filter methods.

    Returns ContentSelectionFilter

    content selection filter ready to use with client methods

    Example

    const filter = new FilterBuilder()
      .match("category", "clothing")
      .range("price", { gte: 20, lte: 100 })
      .match("brand", "nike", "should")
      .match("brand", "adidas", "should")
      .build();

    const results = await client.search("red shoes", "product-search", {
      filters: filter
    });

Settings

Member Visibility

On This Page

Constructors
Properties
Methods