Structure your records

A search result represents one record. Algolia matches, ranks, filters, and updates , including values nested in arrays, so how you split your data into records determines what users can find, how they , and how you keep your index up to date. This guide helps you decide what one record represents, with examples from a games marketplace and an ecommerce catalog.

Record levels

An item is the smallest thing users could see as a separate result, such as a product variant, a listing, or a page section.
A parent is what items belong to, such as a product, a game, or a page.

You can represent items and parents at three levels:

Child-level records: one record per item. Each record holds its parent’s identifier and any parent attributes you need.
Group-level records: one record per group of items that share a value, such as one record per color of a product. Store shared attributes at the top level and attributes that differ between items in an array.
Parent-level records: one record per parent. Store all items in an array.

Choose a record level

Each level favors different requirements. Compare them before you decide:

Consideration	Child-level	Group-level	Parent-level
Filter on combinations of attributes	All conditions match the same item.	Conditions on top-level attributes match the same group. Conditions on attributes in the array can match different items.	Conditions can match different items.
Textual relevance	A query matches one item.	A query matches one group, including searchable attributes in the array.	A query matches the whole parent, including searchable attributes in the array.
Update one item	Send a partial update with the changed top-level attributes.	Resend the group’s array.	Resend the parent’s array.
Click and conversion events, and AI features such as Dynamic Re-Ranking	Algolia attributes events to each item.	Items in a group share events.	All items share the parent’s events.
Rules and merchandising	Target one item. To affect a parent, target all its items.	Target one group.	Target the parent.
Result analytics	Metrics apply to each item.	Metrics apply to each group.	Metrics apply to the parent.
Display the matching item	The matching item is the result. Use `distinct` to show one result per parent.	Top-level attributes, such as the color’s image, belong to the result. Your frontend picks other values from the array.	Your frontend picks which item to show.
Number of records	One per item.	One per group.	One per parent.
Record size	One item plus any copied parent data.	Grows with the number of items in the group.	Grows with the number of items in the parent.

If you use Recommend, child-level records can still give you recommendations per parent. With Recommend deduplication Algolia merges events from variants of the same item and uses one variant per item in the training dataset. Use this guidance to choose:

Use child-level records if users filter on combinations of item attributes or item data changes often.
Use parent-level records if users don’t filter on combinations of item attributes and you want events, rules, and analytics for the whole parent. When an item changes, you must update the parent record’s item array.
Use group-level records if users filter on a shared group attribute, such as color, and you want events, rules, and analytics for each group. Use this model only if it’s acceptable for filters on attributes in the item array to match different items.

Child-level records

Use child-level records when your source data has parents and children, such as a game and its listings, a product and its variants, or a page and its sections.

Index child records

Create one record per child. Don’t create records for parents in this index.
Store the parent’s identifier in each child, such as game_id or product_id.
Decide how much parent data to copy into each child:
- Copy the attributes users search, filter, rank, or display. For example, copy the game’s title into each listing. When the parent changes, update every child record that copies the changed attribute.
- Store only the identifier. You can change the parent’s details without reindexing its children, but users can’t search or filter on parent details that aren’t in the child.

For example, to let users search movies and group them by director, index one record per movie with a director attribute:

JSON

[
  {
    "objectID": "movie-1",
    "title": "Spirited Away",
    "score": 201.6,
    "director": "Hayao Miyazaki"
  },
  {
    "objectID": "movie-2",
    "title": "My Neighbor Totoro",
    "score": 196,
    "director": "Hayao Miyazaki"
  }
]

Because every record repeats the director, a search for miyazaki can return all his movies.

Show one result per parent

Set attributeForDistinct to the parent identifier and distinct to true. Algolia returns the best-ranked matching child from each group. Your ranking formula determines which child it selects. Each result remains one child record: Algolia doesn’t merge the records in the group. In the movie example, set attributeForDistinct to director and add desc(score) to customRanking. A search for miyazaki returns one movie per director. If his movies have equal scores for the earlier ranking criteria, Algolia returns his highest-scoring movie. Facet counts show how many matching records have each attribute value, such as a category. If you use distinct to show one result per parent, facet counts still count matching children by default. For attributes whose values are identical across all children of a parent, such as category, use the afterDistinct modifier in attributesForFaceting to count parents instead.

Plan for updates and record counts

Updates. To update a child record, send a partial update with the changed attributes. If a changed value is nested, include the entire top-level attribute that contains it.
Record count. Each child is a separate record. For example, 10,000 games with ten listings each require 100,000 listing records. Check your plan’s quotas and Algolia’s service limits before you choose this model.

Parent-level records

Use parent-level records when users search for the parent and you don’t need to treat its items as separate results. Put the shared attributes at the top level and the items in an array:

JSON

{
  "objectID": "game-1",
  "name": "Grand Theft Auto V",
  "sellers": [
    { "name": "Alice", "country": "France" },
    { "name": "Mass Effect Fan", "country": "United States" }
  ]
}

A query matches the whole record. Because the array holds several items, keep these two effects in mind:

Filter conditions on array attributes can match different items. For how this works and how to avoid it, see Filters and arrays of objects.
Your frontend decides which item to show. For an example, see Display the matching element.

Group-level records

Use group-level records when items split naturally by one attribute, and users filter or select on that attribute first. For example, you can create one record per color of a product. Put the shared attributes and the grouping attribute at the top level, and put the attributes that differ between items in an array. This keeps filters on the grouping attribute exact while giving you events, rules, and analytics per group. Conditions on attributes inside the array can still match different items in the same group. For a worked example, see Ecommerce records.

Record structure examples

The following examples show each level for a games marketplace and an ecommerce catalog.

Marketplace records

In a games marketplace, a listing is one seller’s offer for one game. A listing belongs to both a game and a seller, so you can treat either as the parent. Which record level fits depends on what users search for:

Seller records (parent-level) when users want to find sellers and browse their games.
Game records (parent-level) when users want to find games and see who sells them.
Listing records (child-level) when users want to compare offers, rank them by seller attributes, or filter on combinations of listing attributes.

Seller records
Game records
Listing records

Create one record per seller. Keep only the attributes users search, filter, or display, and list the titles of the games they sell in a games array:

JSON

[
  {
    "objectID": "seller-1",
    "name": "Alice",
    "popularity": 1000,
    "country": "France",
    "games": [
      "Grand Theft Auto V",
      "The Legend of Zelda: Ocarina of Time"
    ]
  },
  {
    "objectID": "seller-2",
    "name": "Bob",
    "popularity": 900,
    "country": "United States",
    "games": [
      "Mass Effect 3"
    ]
  },
  {
    "objectID": "seller-3",
    "name": "Mass Effect Fan",
    "popularity": 800,
    "country": "United States",
    "games": [
      "Grand Theft Auto V"
    ]
  }
]

To give matches in seller names higher attribute priority than matches in game titles, list name before games in searchableAttributes.Users can’t filter on anything about a game beyond its title.

Create one record per game with its sellers in a sellers array:

JSON

[
  {
    "objectID": "game-1",
    "name": "Grand Theft Auto V",
    "sellers": [
      {
        "name": "Alice",
        "popularity": 1000,
        "country": "France"
      },
      {
        "name": "Mass Effect Fan",
        "popularity": 800,
        "country": "United States"
      }
    ]
  },
  {
    "objectID": "game-2",
    "name": "The Legend of Zelda: Ocarina of Time",
    "sellers": [
      {
        "name": "Alice",
        "popularity": 1000,
        "country": "France"
      }
    ]
  },
  {
    "objectID": "game-3",
    "name": "Mass Effect 3",
    "sellers": [
      {
        "name": "Bob",
        "popularity": 900,
        "country": "United States"
      }
    ]
  }
]

To favor game titles, list name before sellers.name in searchableAttributes.Each object in the sellers array represents one seller. Algolia can match a country filter against one seller and a popularity filter against another. Use listing records when both conditions must match the same seller’s offer.

Create one record per listing:

JSON

[
  {
    "objectID": "listing-1-1",
    "game_id": 1,
    "game_title": "Grand Theft Auto V",
    "seller_name": "Alice",
    "seller_popularity": 1000,
    "seller_country": "France"
  },
  {
    "objectID": "listing-1-3",
    "game_id": 1,
    "game_title": "Grand Theft Auto V",
    "seller_name": "Mass Effect Fan",
    "seller_popularity": 800,
    "seller_country": "United States"
  },
  {
    "objectID": "listing-2-1",
    "game_id": 2,
    "game_title": "The Legend of Zelda: Ocarina of Time",
    "seller_name": "Alice",
    "seller_popularity": 1000,
    "seller_country": "France"
  },
  {
    "objectID": "listing-3-2",
    "game_id": 3,
    "game_title": "Mass Effect 3",
    "seller_name": "Bob",
    "seller_popularity": 900,
    "seller_country": "United States"
  }
]

All filter conditions apply to the same listing. You can rank and update each listing independently.To prioritize game matches over seller matches, list game_title before seller_name in searchableAttributes. A search for “mass effect” then shows listings for Mass Effect 3 before listings by the seller Mass Effect Fan.To rank listings by seller popularity when preceding ranking criteria are equal, set customRanking to ["desc(seller_popularity)"].To show only the best listing for each game, set attributeForDistinct to game_id and distinct to true. With the preceding customRanking, the listing from the most popular seller appears when the listings have equal scores for the earlier ranking criteria. For more information, see Child-level records.

Ecommerce records

Consider a t-shirt sold in white in sizes M and L, and in blue in size L. Each available color-and-size combination is a variant, so this product has three variants. You can store this variant data in Algolia at three levels:

Variant-level records (child-level). Create one record for each variant.
Product-level records (parent-level). Create one record for each base product. The common attributes sit at the top level. The varying attributes, such as image and price, sit in a variants array.
Grouped variant records (group-level). Create one record for each value of a chosen attribute, such as color. Store shared attributes at the top level and size-specific attributes in a variants array.

Variant-level records
Product-level records
Grouped variant records

JSON

[
  {
    "objectID": "v-neck-t-shirt-white-m",
    "product_id": "v-neck-t-shirt",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "size": "M",
    "image": "v-neck-t-shirt-white.jpg",
    "price": 19.99
  },
  {
    "objectID": "v-neck-t-shirt-white-l",
    "product_id": "v-neck-t-shirt",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "size": "L",
    "image": "v-neck-t-shirt-white.jpg",
    "price": 19.99
  },
  {
    "objectID": "v-neck-t-shirt-blue-l",
    "product_id": "v-neck-t-shirt",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "Blue",
    "size": "L",
    "image": "v-neck-t-shirt-blue.jpg",
    "price": 22.99
  }
]

To show one result per product, set attributeForDistinct to product_id and distinct to true.If results show color swatches or image carousels, your frontend needs data about sibling variants. You can copy that data into each variant record, but doing so increases record size.

JSON

{
  "objectID": "v-neck-t-shirt",
  "name": "V-neck t-shirt",
  "category": "Sport",
  "variants": [
    {
      "variantID": "v-neck-t-shirt-white-m",
      "color": "White",
      "size": "M",
      "image": "v-neck-t-shirt-white.jpg",
      "price": 19.99
    },
    {
      "variantID": "v-neck-t-shirt-white-l",
      "color": "White",
      "size": "L",
      "image": "v-neck-t-shirt-white.jpg",
      "price": 19.99
    },
    {
      "variantID": "v-neck-t-shirt-blue-l",
      "color": "Blue",
      "size": "L",
      "image": "v-neck-t-shirt-blue.jpg",
      "price": 22.99
    }
  ]
}

A refinement on variants.color returns the whole product. Your frontend must choose which variant’s image and price to show. For an example, see Display the matching element.

JSON

[
  {
    "objectID": "v-neck-t-shirt-white",
    "product_id": "v-neck-t-shirt",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "White",
    "image": "v-neck-t-shirt-white.jpg",
    "variants": [
      {
        "variantID": "v-neck-t-shirt-white-m",
        "size": "M",
        "price": 19.99
      },
      {
        "variantID": "v-neck-t-shirt-white-l",
        "size": "L",
        "price": 19.99
      }
    ]
  },
  {
    "objectID": "v-neck-t-shirt-blue",
    "product_id": "v-neck-t-shirt",
    "name": "V-neck t-shirt",
    "category": "Sport",
    "color": "Blue",
    "image": "v-neck-t-shirt-blue.jpg",
    "variants": [
      {
        "variantID": "v-neck-t-shirt-blue-l",
        "size": "L",
        "price": 22.99
      }
    ]
  }
]

By default, each result is one color. To show one result per product, set attributeForDistinct to product_id and distinct to true.Grouped variant records are a good compromise between the other two models. They give you events, rules, and analytics per color while staying more granular than product-level records. For example, when a search for blue t-shirt returns the blue record, you can display its top-level image attribute without selecting an image from the variants array.

Color and size filters

To filter these examples by color and size, set attributesForFaceting for the record model you use:

Variant-level records: ["color", "size"]
Product-level records: ["variants.color", "variants.size"]. With product-level records, variants.color:Blue AND variants.size:M matches v-neck-t-shirt. One variant supplies Blue and another supplies M, although the product doesn’t have a blue variant in size M.
Grouped variant records: ["color", "variants.size"]. With grouped variant records, color:Blue AND variants.size:M doesn’t match v-neck-t-shirt-blue, because that record contains only a blue variant in size L. Within a color group, conditions on variants.size and variants.price can still match different variants.

To decide between these models, see Choose a record level. Record level is one of several data modeling decisions. For the others, see:

Choose how many indices to use to decide whether to use one index or several, for example to show movies and actors in one results list, to add Query Suggestions, or to sort by price
Rework your data to select the attributes to include for searching, display, filtering, and ranking
Split long pages into smaller records to index long documents
Reduce record size to stay within record size limits
Create nested attributes to structure values inside a record
Set object IDs to identify records for updates and events

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Structure your records

Record levels

Choose a record level

Child-level records

Index child records

Show one result per parent

Plan for updates and record counts

Parent-level records

Group-level records

Record structure examples

Marketplace records

Ecommerce records

Color and size filters

Record levels

Choose a record level

Child-level records

Index child records

Show one result per parent

Plan for updates and record counts

Parent-level records

Group-level records

Record structure examples

Marketplace records

Ecommerce records

Color and size filters

Related modeling choices