JSON Tree Introduction in v16.9

Introduction

Goal

After upgrading to 16.9 and enabling JSON Tree feature, make large taxonomy trees performant.

Background

This feature introduces a JSON-based taxonomy tree storage model as an opt-in alternative to the existing JCR node-tree representation. When enabled, the entire category hierarchy of a taxonomy document is serialized as a single hippotaxonomy:categories binary property rather than as a tree of child hippotaxonomy:category JCR nodes.

JSON Tree Introduction

Before 16.9, the category representation of a hippotaxonomy:taxonomy node is as follows:

/content/taxonomies/exampletaxonomy/exampletaxonomy:
  /main-category:
    jcr:primaryType: hippotaxonomy:category
    hippotaxonomy:key: main-category
    locale.en.name: Main category
    locale.en.description: Description of main category
    locale.en.synonyms: [Synonym 1, Synonym 2]
    locale.nl.name: Hoofdcategorie
    locale.nl.description: Beschrijving van hoofdcategorie
  /secondary-category:
    jcr:primaryType: hippotaxonomy:category
    hippotaxonomy:key: secondary-category
    locale.en.name: Secondary category
    locale.en.description: Description of secondary category
    locale.en.synonyms: [Synonym 1, Synonym 2]
    locale.nl.name: Secundaire categorie
    locale.nl.description: Beschrijving van secundaire categorie 

From 16.9 and up, the category representation of a taxonomy is stored in the binary hippotaxonomy:categories property as follows:

/content/taxonomies/exampletaxonomy/exampletaxonomy/hippotaxonomy:categories:
[
  {
    "key": "main-category",
    "name": "Main category",
    "children": [],
    "infosByLocale": {
      "en": {
        "name": "Main category",
        "description": "Description of main category",
        "synonyms": [ "Synonym 1", "Synonym 2" ]
      },
      "nl": {
        "name": "Hoofdcategorie",
        "description": "Beschrijving van hoofdcategorie"
      }
    }
  },
  {
    "key": "secondary-category",
    "name": "Secondary category",
    "children": [],
    "previous": "main-category",
    "infosByLocale": {
      "en": {
        "name": "Secondary category",
        "description": "Description of secondary category",
        "synonyms": [ "Synonym 1", "Synonym 2" ]
      },
      "nl": {
        "name": "Secundaire categorie",
        "description": "Beschrijving van secundaire categorie"
      }
    }
  }
]

Using the latter model is much more performant because no category nodes are involved, meaning less database records and less database queries.

Configuration

To enable the JSON tree for a taxonomy plugin instance, add the following property to the CMS plugin configuration node:

/hippo:configuration/hippo:frontend/cms/cms-services/taxonomyService:
  taxonomy.json.tree.enabled: true

When this flag is false or missing (the default), both Taxonomies perspective and delivery tier uses the existing JCR category tree as is.

When the flag is true and a taxonomy document has not yet been migrated, both Taxonomies perspective and delivery tier uses the existing JCR category tree as is.

When the flag is true and a taxonomy document has been migrated, both Taxonomies perspective and delivery tier uses the JSON tree.

Upgrade Considerations

Once a system has been upgraded to 16.9, it is recommended, but not mandatory to use the new model for taxonomy documents with large trees. Not every project has large trees and performance problems. 

Both the CMS and the Delivery Tier supports both models.

Groovy Updater Script

Version 16.9 comes with a Groovy script TaxonomyJsonMigrator that is added to the Updater Editor. It has some inner documentation and when configured correctly, it will visit all hippotaxonomy:taxonomy nodes, will convert their JCR category tree to JSON tree then will remove the category nodes for performance gain.

For very large trees, it is recommended to use this method, although no entry is made in the revision history.

With default settings, the script takes around 15-20 seconds to convert a JCR tree of around 4000 categories to JSON tree.