Advanced Faceting

You can use the facet_advanced parameter to perform Advanced Faceting if you have a faceting need that is not addressed by Basic Faceting.

Supported Fields¶

You can apply advanced faceting to these supported fields.

Supported Fields for Advanced Faceting

tenant_id
language
created_at
updated_at
metadata subfields of the following field types:
- keyword
  - String fields that store one or more predefined values. For example: Brand, Category, Department, etc.
- integer
- float
- date
- geo_point

Important: Specify metadata fields using dot notation, for example: metadata.brand.

Gainly supports the following advanced facet types:

Terms¶

Groups documents based on exact values in a string (keyword) field. Useful for categorizing documents by discrete values like brands, categories, departments, or status.

Range¶

Creates buckets based on numeric ranges. Perfect for price ranges, age groups, or any numeric field where you want to group documents into intervals.

Date Range¶

Similar to Range faceting but specialized for date ranges. Supports both fixed dates and relative date ranges like "last 7 days" or "last month".

Geo Distance¶

Groups documents based on their geo-distance from a specified point. Ideal for location-based queries like "find stores within 5 miles" or "group customers by distance".

Terms Faceting¶

For "Terms" faceting, you can use any supported field that is a keyword field type (i.e. fields that store string values).

Request Format¶

{
  "facet_advanced": [
    {
      "type": "terms",              // advanced facet type
      "criteria": {
        "field": "metadata.brand",  // must be 'keyword' field type (i.e. string)
        "size": 10                  // Maximum number of buckets to return (default: 10)
      }
    }
  ]
}

Comparison with Basic Faceting

The terms facet type provides the same functionality as Basic Faceting with one key difference: you can control the maximum number of buckets returned using the size parameter (range: 1 - 100).

Response Format¶

{
  "facet_result": {
    "metadata.brand": {
      "buckets": [
        {
          "value": "nike",
          "doc_count": 150
        },
        {
          "value": "adidas",
          "doc_count": 120
        }
      ]
    }
  }
}

Range Faceting:¶

For "Range" faceting, you can use any supported field that is an integer or float field type.

Request Format¶

{
  "facet_advanced": [
    {
      "type": "range",              // advanced facet type
      "criteria": {
        "field": "metadata.price",  // must be 'integer' or 'float' field type
        "ranges": [                 // at least one 'from' or 'to' must be specified per range
          {"to": 50},
          {"from": 50, "to": 100},
          {"from": 100}
        ]
      }
    }
  ]
}

Response Format¶

{
  "facet_result": {
    "metadata.price": {
      "buckets": [
        {
          "value": "*-50",
          "to": 50,
          "doc_count": 120
        },
        {
          "value": "50-100",
          "from": 50,
          "to": 100,
          "doc_count": 80
        },
        {
          "value": "100-*",
          "from": 100,
          "doc_count": 70
        }
      ]
    }
  }
}

Date Range Faceting:¶

For "Date Range" faceting, you can use any supported field that is a date field type.

Request Format¶

{
  "facet_advanced": [
    {
      "type": "date_range",      // advanced facet type
      "criteria": {
        "field": "created_at",   // must be 'date' field type
        "format": "yyyy-MM-dd",  // (optional) format of date values
        "ranges": [              // at least one 'from' or 'to' must be specified per range
          {"to": "now"},
          {"from": "now-7d", "to": "now"},
          {"from": "now-30d", "to": "now"},
          {"from": "now-365d", "to": "now"}
        ]
      }
    }
  ]
}

Date Formats and Values

Format:

You can specify desired date format using the format parameter in the API request
- If format is not specified, default format is ISO 8601 UTC datetime. E.g., 2025-01-12T20:48:57.845Z
- If format is specified, please make sure any absolute date values in your API request match the specified format
How to specify format:
- yyyy - Year (e.g., 2025)
- MM - Month (01-12)
- dd - Day of month (01-31)
- HH - Hour in 24h format (00-23)
- mm - Minutes (00-59)
- ss - Seconds (00-59)
- Common combinations:
  - yyyy-MM-dd - Date only (e.g., 2025-01-12)
  - yyyy-MM-dd'T'HH:mm:ss'Z' - Full UTC datetime
  - yyyy-MM-dd'T'HH:mm:ssXXX - Datetime with timezone offset (e.g., yyyy-MM-dd'T'HH:mm:ss-06:00)

Date Values:

You can use absolute date values in ISO 8601 format:
- Full datetime: 2024-11-01T12:34:56Z
- Date only: 2024-11-01
- With timezone offset: 2024-11-01T12:34:56-07:00
You can use relative date values like now, now-1d, now-1M, etc. Supported date math units for relative date values:
- y (years)
- M (months)
- w (weeks)
- d (days)
- h (hours)
- m (minutes)
- s (seconds)
Supported date math operators:
- + (add)
- - (subtract)
- / (round down)
Examples of round down operator:
- now-1d/d (yesterday at 00:00:00 - rounds down to start of day)
- now/d (today at 00:00:00)
- now+1y/y (start of next year)

Response Format¶

{
  "facet_result": {
    "created_at": {
      "buckets": [
        {
          "value": "*-2025-01-12",
          "doc_count": 4500,
          "to": "2025-01-12"
        },
        {
          "value": "2025-01-05-2025-01-12",
          "doc_count": 500,
          "from": "2025-01-05",
          "to": "2025-01-12"
        },
        {
          "value": "2024-12-13-2025-01-12",
          "doc_count": 1500,
          "from": "2024-12-13",
          "to": "2025-01-12"
        },
        {
          "value": "2024-01-13-2025-01-12",
          "doc_count": 3400,
          "from": "2024-01-13",
          "to": "2025-01-12"
        }
      ]
    }
  }
}

Geo-Distance Faceting¶

For "Geo-Distance" faceting, you can use any supported field that is a geo_point field type.

Request Format¶

{
  "facet_advanced": [
    {
      "type": "geo_distance",                     // advanced facet type
      "criteria": {
        "field": "metadata.location_geo_point",   // must be 'geo_point' field type
        "origin": {
          "lat": 37.7749,                         // latitude of the specified point
          "lon": -122.4194                        // longitude of the specified point
        },
        "unit": "mi",                             // default is "km"
        "ranges": [                               // at least one 'from' or 'to' must be specified per range
          {"to": 5},
          {"from": 5, "to": 10},
          {"from": 10}
        ]
      }
    }
  ]
}

Geo Distance Units

The following units are supported for the unit parameter:

mi (miles)
nmi (nautical miles)
km (kilometers)
m (meters)

Example: "unit": "km" for kilometers or "unit": "mi" for miles

Response Format¶

{
  "facet_result": {
    "metadata.location_geo_point": {
      "buckets": [
        {
          "value": "*-5",
          "unit": "mi",
          "from": 0,
          "to": 5,
          "doc_count": 12
        },
        {
          "value": "5-10",
          "unit": "mi",
          "from": 5,
          "to": 10,
          "doc_count": 17
        },
        {
          "value": "10-*",
          "unit": "mi",
          "from": 10,
          "doc_count": 25
        }
      ]
    }
  }
}

You can combine multiple facet types in a single request:

{
  "facet_advanced": [
    {
      "type": "terms",
      "criteria": {
        "field": "metadata.brand",
        "size": 10
      }
    },
    {
      "type": "range",
      "criteria": {
        "field": "metadata.price",
        "ranges": [
          {"to": 50},
          {"from": 50, "to": 100},
          {"from": 100}
        ]
      }
    }
  ]
}

Endpoints¶

The following endpoints support the facet_advanced parameter:

Common Pitfalls¶

Field names and types:
- Always use dot notation for metadata fields (e.g., metadata.brand not just brand)
- Ensure fields used for faceting have appropriate field type in your metadata schema
- Each facet type requires specific field types, as explained above
Range facets:
- At least one range must have either from or to specified
- Ranges should not have gaps or overlaps for most use cases
- For open-ended ranges, omit from (for "up to") or to (for "and above")
- Consider using meaningful range intervals for better user experience
Date range facets:
- Use ISO 8601 format for absolute dates
- When using date math expressions:
  - Ensure proper syntax (e.g., now-1M/d for start of day one month ago)
  - Be aware of timezone implications
  - Use rounding operators (/d, /M, /y) for clean boundaries
Geo-distance facets:
- Field must be of type geo_point
- Both lat and lon must be specified in the origin point
- Use appropriate distance units based on your use case
- Consider the performance impact of geo-distance calculations
Performance considerations:
- Each facet type has different performance characteristics:
  - Terms faceting on high-cardinality fields will impact performance
  - Range calculations are generally faster than geo-distance
  - Complex date math expressions may be slower than absolute dates
- Consider using filters to reduce the dataset before applying facets
Response handling:
- Always check the structure of facet_result
- Handle empty buckets appropriately in your UI
- Sort buckets in your application based on your needs, for example:
  - By doc_count for popularity-based display
  - By value for alphabetical/numerical ordering
- Format values appropriately for display (especially dates and geo-distances)

Advanced Faceting

Supported Fields¶

Advanced Facet Types¶

Terms¶

Range¶

Date Range¶

Geo Distance¶

Terms Faceting¶

Request Format¶

Response Format¶

Range Faceting:¶

Request Format¶

Response Format¶

Date Range Faceting:¶

Request Format¶

Response Format¶

Geo-Distance Faceting¶

Request Format¶

Response Format¶

Combining Facet Types¶

Endpoints¶

Common Pitfalls¶