Grouping

Orama supports groupBy operations. That allows you to group results in groups calculating an aggregation on the item that belongs to the same bucket.

const results = await search(db, {
  term: "t-shirt",
  groupBy: {
    properties: ["design"], // required: property on which we want to group on
    maxResult: 1, // optional: for every group, how many results we want
    reduce: {
      // optional: customize the aggregation logic
      reducer: Function,
      getInitialValue: Function,
    },
  },
});

By default, Orama doesn’t limit the number of items inside a group.

By default, Orama groups all the matched documents into an array.

Simple usage

If we consider the following schema:

const db = await create({
  schema: {
    id: "string",
    type: "string",
    design: "string",
    color: "string",
    rank: "number",
    isPromoted: "boolean",
  },
});
const ids = await insertMultiple(db, [
  {
    id: "0",
    type: "t-shirt",
    design: "A",
    color: "blue",
    rank: 3,
    isPromoted: true,
  },
  {
    id: "1",
    type: "t-shirt",
    design: "A",
    color: "green",
    rank: 5,
    isPromoted: false,
  },
  {
    id: "2",
    type: "t-shirt",
    design: "A",
    color: "red",
    rank: 4,
    isPromoted: false,
  },
  {
    id: "3",
    type: "t-shirt",
    design: "B",
    color: "blue",
    rank: 4,
    isPromoted: false,
  },
  {
    id: "4",
    type: "t-shirt",
    design: "B",
    color: "green",
    rank: 4,
    isPromoted: true,
  },
  {
    id: "5",
    type: "t-shirt",
    design: "B",
    color: "white",
    rank: 5,
    isPromoted: false,
  },
  {
    id: "6",
    type: "t-shirt",
    design: "B",
    color: "gray",
    rank: 5,
    isPromoted: true,
  },
  {
    id: "7",
    type: "sweatshirt",
    design: "A",
    color: "yellow",
    rank: 3,
    isPromoted: true,
  },
  {
    id: "8",
    type: "sweatshirt",
    design: "A",
    color: "green",
    rank: 4,
    isPromoted: false,
  },
]);

We will be able to have the documents per design ordered by rank:

const results = await search(db, {
  term: "t-shirt",
  groupBy: {
    properties: ["design"], // property on which we want to group on
  },
  sortBy: {
    property: "rank", // inside a group, the result is ordered following this property
    order: "DESC", // with this order
  },
});

If you want only the top-ranked document per design, you can specify the maxResult:

const results = await search(db, {
  term: "t-shirt",
  groupBy: {
    properties: ["design"],
    maxResult: 1, // for every group, how many results we want
  },
  sortBy: {
    property: "rank",
    order: "DESC",
  },
});

The above query returns something like this:

{
  groups: [
    {
      values: ['A'], // list of the values the group is referring to
      result: [
        {
          id: '1',
          score: 0,
          document: { ... } // the doc with id '1'
        }
      ]
    },
    {
      values: ['B'], // list of the values the group is referring to
      result: [
        {
          id: '5',
          score: 0,
          document: { ... } // the doc with id '5'
        }
      ]
    }
  ],
  // The other common properties like `hits` and `elapsed`
}

You can group on multiple properties as follows:

const results = await search(db, {
  term: "red t-shirt",
  groupBy: {
    properties: ["design", "rank", "isPromoted"], // group on the combination of the values
  },
  sortBy: {
    property: "id",
    order: "ASC",
  },
});

Custom reducer

Orama supports custom aggregator as follows:

// The document interface
interface Doc extends Document {
  type: string;
  design: string;
  rank: number;
  color: string;
  isPromoted: boolean;
}
// The aggregation interface
interface AggregationValue {
  type: string;
  design: string;
  colors: string[];
  ranks: number[];
  isPromoted: boolean;
}

const results = await search(db, {
  term: "red t-shirt",
  groupBy: {
    properties: ["type", "design"], // group on both properties
    reduce: {
      // the accumulator function
      reducer: (
        values: ScalarSearchableValue[],
        acc: AggregationValue,
        item: Result
      ) => {
        const doc = item.document as Doc;
        acc.type ||= doc.type;
        acc.design ||= doc.design;
        acc.isPromoted ||= doc.isPromoted;
        acc.colors.push(doc.color);
        acc.ranks.push(doc.rank);
        return acc;
      },
      // The initial value: this is called for every group
      getInitialValue: (): AggregationValue => ({
        type: "",
        design: "",
        colors: [],
        ranks: [],
        isPromoted: false,
      }),
    },
  },
  sortBy: {
    property: "rank",
    order: "DESC",
  },
});

Where the accumulator function receives the following parameters:

1. the value of the current groups
2. the accumulator returned by the previous invocation
3. the item to accumulate

The reducer is called for every item for every group.