Skip to main content

Incremental Summary

caution

The APIs described on this page are currently @alpha and may change in future releases. These APIs should not be used in production. See API Support Levels for more information.

Incremental summary is an optimization that avoids re-summarizing parts of the tree that have not changed between summaries. Fields in a schema can opt into incremental summarization through the summarizeIncrementally field option. These fields are tracked as independent chunks in the summary. During summarization, if their content has not changed since the last summary, their previously generated summaries are reused. As a result, their data does not need to be re-encoded (saving processing time), and their summary trees do not need to be uploaded again (reducing summary upload size).

How to Enable​

Enabling incremental summary requires two steps: marking fields in your schema and configuring the SharedTree with the required options.

1. Mark Fields in Your Schema​

sf.required(allowedTypes, options) is the explicit way to define a required field. Passing allowed types directly in an object schema is syntactic sugar for sf.required(allowedTypes). Use the explicit form with { summarizeIncrementally: true } to opt a field in to incremental summarization. Use sf.optional(allowedTypes, options) for an optional field. For recursive allowed types, use sf.requiredRecursive(...) or sf.optionalRecursive(...) with the same option. The SchemaFactoryAlpha.stagedOptional and stagedOptionalRecursive constructors accept the same option.

import { SchemaFactoryAlpha } from "@fluidframework/tree/alpha";

const sf = new SchemaFactoryAlpha("my-app");

class Item extends sf.object("Item", {
    id: sf.number,
    // This field will be incrementally summarized.
    payload: sf.required(sf.string, { summarizeIncrementally: true }),
}) {}

class ItemList extends sf.array("ItemList", Item) {}

class Root extends sf.object("Root", {
    // This field will be tracked as a separate incremental chunk.
    items: sf.required(ItemList, { summarizeIncrementally: true }),
}) {}
note

Incremental summarization is applied to fields, not node kinds. Leaf values (string, number, boolean, null) can be incrementally summarized when they are stored in a field whose summarizeIncrementally option is enabled. Root fields themselves cannot be incrementally summarized, and leaf node kinds do not expose child fields for the policy to apply to.

2. Configure the SharedTree​

Pass all four required options when creating the SharedTree using configuredSharedTreeAlpha:

import {
    configuredSharedTreeAlpha,
    ForestTypeOptimized,
    TreeCompressionStrategy,
    TreeViewConfigurationAlpha,
    incrementalEncodingPolicyForAllowedTypes,
    FluidClientVersion,
} from "@fluidframework/tree/alpha";

const config = new TreeViewConfigurationAlpha({ schema: Root });

const TreeFactory = configuredSharedTreeAlpha({
    forest: ForestTypeOptimized,
    treeEncodeType: TreeCompressionStrategy.CompressedIncremental,
    shouldEncodeIncrementally: incrementalEncodingPolicyForAllowedTypes(config),
    minVersionForCollab: FluidClientVersion.v2_74,
});

const sharedTree = TreeFactory.create(runtime, "tree");

All four of the following configuration options must be set for incremental summary to take effect:

OptionValue
forestForestTypeOptimized
treeEncodeTypeTreeCompressionStrategy.CompressedIncremental
shouldEncodeIncrementallyResult of incrementalEncodingPolicyForAllowedTypes(config)
minVersionForCollabFluidClientVersion.v2_74 or higher

How incrementalEncodingPolicyForAllowedTypes Works​

incrementalEncodingPolicyForAllowedTypes accepts a TreeViewConfigurationAlpha and returns a callback. During summarization, the callback is invoked for each field in the tree with the node identifier and field key. It returns true if the field was opted in through FieldPropsAlpha.summarizeIncrementally, directing the summarizer to encode that field as a separate, reusable chunk.

Fields that are not opted in are encoded into the main summary blob as usual.

Limitations​

  • Root fields cannot be incrementally summarized (the callback always returns false for them).
  • If the view schema does not recognize a node type (for example, due to schema mismatch or unknown optional fields), that node falls back to non-incremental encoding.

See Also​