Skip to content
VioGraph Docs

Sharing Mappings

Tutorial

Sharing Mappings

Collaborate on mappings through list, copy, and admin-bypass patterns

20 min Advanced
MappingsCollaborationPermissionsOwnership

What You'll Learn

  • Read any mapping - The catalogue is a shared reference; every analyst can list and inspect every mapping
  • Fork by copy - client.mappings.copy(...) creates an independent mapping owned by you
  • Admin-bypass edits - Admin or Ops can update() any mapping for in-place team-wide changes
  • Permission boundaries - Why update() on a teammate's mapping raises PermissionDeniedError

Background: the platform has no ACLs, grants, ownership transfer, or “share” feature. Every mapping has exactly one owner, set at creation time and immutable. Collaboration happens through the three patterns below — see the SDK Manual — Working With Other Users’ Mappings for the full narrative.

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running
# Cell 2 — Connect and provision personas
from graph_olap import GraphOLAPClient
from graph_olap.exceptions import PermissionDeniedError


from notebook_setup import provision


personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]


# Pick a mapping from the catalogue — treat this as "a teammate's mapping"
teammate_mapping = analyst.mappings.list(search="tutorial-customer-graph").items[0]
print(f"Teammate's mapping: {teammate_mapping.name} (id={teammate_mapping.id}, owner={teammate_mapping.owner_username})")
1

Pattern 1 — Read Any Mapping

The mapping catalogue is a shared reference. Read operations work on any mapping regardless of owner.

# list() returns every mapping on the platform, not just yours
all_mappings = analyst.mappings.list(limit=5)
print(f"Catalogue size: {all_mappings.total}")
for m in all_mappings.items:
    print(f"  [{m.id}] {m.name} (owner: {m.owner_username})")


# get() and list_versions() work on any mapping id
versions = analyst.mappings.list_versions(teammate_mapping.id)
print(f"\n{teammate_mapping.name} has {len(versions)} version(s)")
2

Pattern 2 — Fork by Copy

Build on a teammate's mapping without modifying the original. The copy is yours to evolve.

# copy() creates a new mapping owned by the caller, seeded from the source's current version
my_fork = analyst.mappings.copy(teammate_mapping.id, "MyFork-CustomerGraph")
print(f"Source:   [{teammate_mapping.id}] {teammate_mapping.name} (owner: {teammate_mapping.owner_username})")
print(f"My fork:  [{my_fork.id}] {my_fork.name} (owner: {my_fork.owner_username}, version: v{my_fork.current_version})")


# The fork is fully independent — no upstream link, no automatic sync.
# If the source mapping evolves, call copy() again to catch up.
# You own the fork, so you can update it
updated = analyst.mappings.update(
    my_fork.id,
    change_description="Customised description for my analysis",
    description="My forked copy of the customer graph",
)
print(f"Updated fork to v{updated.current_version}: {updated.description}")
3

Pattern 3 — Admin-Bypass for Shared Edits

When a mapping the whole team uses needs to change in place, only Admin or Ops can do it.

# Calling update() on a mapping you don't own raises PermissionDeniedError (HTTP 403)
# Here we simulate trying to update a mapping owned by someone else.
# To demo the boundary we temporarily act as admin, who owns different resources.
admin_mapping = admin.mappings.list(owner=admin._config.username, limit=1).items


if admin_mapping:
    target = admin_mapping[0]
    try:
        analyst.mappings.update(
            target.id,
            change_description="analyst trying to edit admin's mapping",
            description="This will fail",
        )
    except PermissionDeniedError as e:
        print(f"Analyst cannot update admin's mapping: {e}")


    # Admin bypasses the ownership check
    bypassed = admin.mappings.update(
        target.id,
        change_description="admin in-place edit on behalf of team",
        description="Updated by admin for everyone",
    )
    print(f"Admin updated {target.name} to v{bypassed.current_version}")
else:
    print("(No admin-owned mapping available to demo the bypass)")
4

What You Cannot Do

Collaboration features that don't exist on the platform

The platform intentionally does not provide:

  • Sharing a mapping with specific teammates (no ACLs or grants)
  • Transferring ownership of a mapping
  • Merging two mappings
  • Querying across multiple mappings in one call
  • An upstream/downstream link between a fork and its source

For policy and rationale, see Authorization — §4.1 Collaboration Patterns.

# Cleanup — delete the fork you created
analyst.mappings.delete(my_fork.id)
print(f"Deleted fork {my_fork.name}")

Key Takeaways

  • The mapping catalogue is shared reference data — every analyst can list(), get(), and list_versions() on any mapping
  • mappings.copy(id, new_name) is the collaboration primitive — it creates an independent mapping owned by you
  • A fork has no upstream link — call copy() again to pick up the source's latest changes
  • update() on another user's mapping raises PermissionDeniedError; only Admin or Ops can bypass ownership
  • There is no "share with user X" feature, no ACL, no transfer of ownership — collaboration is by copy or by admin

See also: