# Histogram


# Description

A histogram can be used to return the number of items that fall within a set of intervals as configured in a 1search implementation.

Histogram indexes are built on range indexes and you need to specify range index in your histogram configuration. To learn more about ranges, see here.

You also need to provide dynamic bin options or static bin options in histogram configuration. With dynamic bin options, histogram bins will be generated dynamically according to your current filter, or you will get static bins with static bin options.

Add histogram into Navigation Configuration and you will get histogram results within navigation response.

# Syntax

"HistogramOptions": [
    {
      "Name": "Dynamic Bin Histogram",
      "RangeIndex": "Price",
      "DynamicBinOptions": {
        "MaxCount": 2,
        "Round": "1000",
        "ClampMin": "",
        "ClampMax": "1000000",
        "MinExclusive": true,
        "MaxExclusive": false
      }
    },
    {
      "Name": "Static Bin Histogram",
      "RangeIndex": "Price",
      "StaticBinOptions": [
        {
          "Label": "one",
          "Min": "0",
          "Max": "5000",
          "MinExclusive": false,
          "MaxExclusive": false
        },
        {
          "Label": "two",
          "Min": "5000",
          "Max": "10000",
          "MinExclusive": false,
          "MaxExclusive": false
        },
        {
          "Label": "three",
          "Min": "10000",
          "Max": "1000000",
          "MinExclusive": false,
          "MaxExclusive": false
        }
      ]
    }
  ]

# Attributes

Note: attributes marked with * are required.

  • Name* (string) :
    • The name of your histogram. This value must be unique across all histogram names.
  • RangeIndex* (string) :
    • The range index that your histogram is built on.

# Dynamic Bin Options

  • MaxCount* (integer) :
    • The maximum number of bins/intervals configured for your histogram.
  • Round* (string) :
    • Round is the minimum size of an interval/bin configured in your histogram
    • Round value must have same type as range index type except System.DateTime. For System.DateTime, round should be a time span (opens new window) value.
    • Histogram interval boundaries can only be times of round value. For example, your interval boundaries can only be 2, 4, 6, ..., if round is 2.
  • ClampMin (string) :
    • The minimum value of your range index that can be included in your histogram.
  • ClampMax (string) :
    • The maximum value of your range index that can be included in your histogram.
  • MinExclusive (Boolean) (default: false) :
    • When true, min is excluded from histogram bins except the first bin.
  • MaxExclusive (Boolean) (default: false) :
    • When true, max is excluded from histogram bins except the last bin.

# Static Bin Options

  • Label (string) :
    • Label of the bin.
  • Min (string) :
    • Min of bin interval.
    • Min value should have same type as range index type.
    • For type System.DateTime, you can also use relative value to now with NOW, NOW-<Time Span value> or NOW+<Time Span value>
  • Max (string) :
    • Max of bin interval.
    • Value type restriction is same with Min.
  • MinExclusive (Boolean) (default: false) :
    • When true, min is excluded from histogram bin.
  • MaxExclusive (Boolean) (default: false) :
    • When true, max is excluded from histogram bin.

# Response

"Histograms": [
    {
        "Name": "Dynamic Bin Histogram",
        "Bins": [
            {
                "Min": 0.0,
                "Max": 2000.0,
                "Count": 59,
                "Action": "Price.range(0..2000)."
            },
            {
                "Min": 2000.0,
                "Max": 4000.0,
                "Count": 14,
                "Action": "(And.Price.range(2000..4000)._.(not.Price.range(2000..2000).))"
            }
        ]
    },
    {
        "Name": "Static Bin Histogram",
        "Bins": [
            {
                "Label": "one",
                "Min": 0.0,
                "Max": 5000.0,
                "Count": 50,
                "Action": "Price.range(0..5000)."
            },
            {
                "Label": "two",
                "Min": 5000.0,
                "Max": 10000.0,
                "Count": 9,
                "Action": "Price.range(5000..10000)."
            },
            {
                "Label": "three",
                "Min": 10000.0,
                "Max": 1000000.0,
                "Count": 35,
                "Action": "Price.range(10000..1000000)."
            }
        ]
    }
]