Metadata structure version and caching

View as Markdown

Almost every client needs the metadata structure: object types, classes, property definitions, workflows. It changes rarely, so read it once and cache it. The server tells you when to drop the cache: the vault's metadata structure version changes whenever the structure changes.

The metadata structure version

The metadata structure version is a 32-bit counter. It reaches you in two ways:

• In the trailer of most calls. Methods with returns_metadata_structure_version in their (mfiles.api.method) options (about 260 of the published methods, including SearchObjects, the object operations and the structure reads) send the trailing metadata mfiles-metadata-version-bin: 4 bytes, a little-endian signed 32-bit integer. The Sample Vault sent 00 04 00 00, which is 1024.
• On request. GetMetadataStructureVersion returns it in metadata_structure_version (1024 in the Sample Vault, the same value as the trailer), plus property_defs_version, a separate counter for property definitions. This call itself sends no trailer.

gRPC libraries expose the trailer after the call completes, as the call's trailing metadata (in Python, call the method with with_call(); the second return value has trailing_metadata()). Most libraries hand you -bin values already base64-decoded, as raw bytes. A failed call sends no metadata structure version trailer. Call metadata lists all metadata keys.

The server increments the version when the structure changes, for example when an administrator changes object types or value list definitions, property definitions, classes and class groups, workflows, named ACLs or languages. It does not change when objects change or when value list items are added: adding an item to the Countries list left it at 1024.

Finer-grained versions

Some reads have their own version number, which lets you skip unchanged data entirely:

Send the current_version you received last time as known_version. If nothing has changed, the response repeats the same current_version and contains no items: an empty list here means "unchanged", not "empty". In the Sample Vault, GetPropertyDefs with known_version 483 returned 0 property definitions; Countries with known_version 17 returned 0 items, and after an item was added, allow_delta true returned just that item with is_delta true and version 18. Value list items are not covered by the metadata structure version, so this is how to keep a cached value list current.

What to cache

The metadata structure version tracks the structure only, not object data. Cache by these rules:

A safe structure cache

start:        v = GetMetadataStructureVersion().metadata_structure_version
              load the structure you need; store it under key (vault, user, language, v)
every call:   if the trailer mfiles-metadata-version-bin is present and differs from v:
                  drop the cached structure; set v to the new value; reload on next use
value lists:  refresh with known_version / allow_delta when you need current items

Key the cache by user and language, not only by vault: structure responses carry the caller's permissions (for example ObjectClass.current_user_permissions) and names in the session's language. A cache shared between users can show one user's view of the structure to another.

Hold IDs that you resolved from aliases or GUIDs in the same cache. They change only with the structure, so a changed metadata structure version is also the signal to resolve them again.