Creating an index

Runtime Framework
1

Designing Versioned Catalog Storage + Indexing Strategy in Nakama Storage

Details

Hi! I’m trying to design a clean way to store a versioned item catalog in Nakama Storage and also figure out how to efficiently index and query items based on attributes like category, rarity, type, etc.

By design, I’m storing the entire catalog version as one JSON value, not individual per-item records. Example:

{
  "catalog_v1_inventory": [
    {
      "item_id": "ITEM_001",
      "version": 1,
      "name": "Starter Item",
      "display_name": "Starter Item",
      "description": "Sample item for catalog v1.",

      "category": "tool",
      "type": "equipment",
      "linker": "SHOP_GENERAL",

      "enabled": true,
      "is_deleted": false,

      "start_at": "2025-01-01T00:00:00Z",
      "end_at": "2026-01-01T00:00:00Z",

      "stackable": true,
      "max_stack_size": 5,
      "max_count": 12,

      "consumable": false,
      "tradable": true,
      "bind_on_equip": true,
      "keep_zero": false,

      "attributes": {
        "rarity": "rare",
        "faction": "A"
      },

      "metadata": {
        "season": "2025",
        "tier": "base"
      },

      "string_properties": {
        "material": "composite",
        "slot": "hand"
      },
      "numeric_properties": {
        "power": 85,
        "control": 80
      }
    }
  ]
}

I store this whole JSON under:

bucket: catalog
collection: global
key: catalog_v1_inventory
value: {full catalog json}

Later versions will be:

catalog_v2_inventory
catalog_v3_inventory
...

What I’m Trying to Solve

Since my entire catalog lives inside a single JSON value per version, I’m trying to understand the best approach for indexing so I can quickly query items by:

  • category

  • rarity

  • type

  • faction

  • combinations of the above

Because the data is stored as one blob, I can’t use Nakama’s StorageList query filters which work only on bucket/collection/key—not on the internal JSON fields.

What I’m Considering (Looking for Guidance)

I’m thinking of generating parallel index keys per version, such as:

bucket: catalog_index
collection: category_tool
key: v1
value: ["ITEM_001", "ITEM_005", ...]

Or:

collection: rarity_rare
key: v1
value: ["ITEM_001", ...]

Or composite:

collection: category_tool_rarity_rare
key: v1
value: ["ITEM_001"]

This would give me:

  1. Load index → get item IDs

  2. Load catalog JSON → extract matching items

Has anyone followed a similar pattern?
Is this the recommended way for versioned catalog systems?
Any alternative ideas or patterns using Nakama Storage that work well in production?

Versions

  • Nakama: v3.28.0

  • Runtime Language: Go 1.24.5

  • Database: PostgreSQL

  • Environment: Self-hosted (Linux)

Media / Code Snippets

Happy to share more code if needed — keeping snippets minimal for the post.

2

Hi @namanjain,

Depending on the size of your inventory catalog, you may want to split it across multiple keys, since a single blob may become too large, but it depends on how many items are part of the catalog. Perhaps you could have a key per category, or something similar. Then you can use StorageList to go through the multiple keys if needed.

For the indices, any of your approaches works, but shouldn’t need to hand roll them, have a look at: Storage Search - Heroic Labs Documentation.

Alternatively, we also provide an abstraction for all of this in Hiro, should you be interested (licensed product).

Best