Advanced Mappings

Tutorial

Advanced Mappings

Copy mappings and work with mapping hierarchies

25 min Advanced

MappingsCopyHierarchyVersioning

What You'll Learn

• Copying Mappings - Duplicate and modify mappings
• Mapping Trees - Version hierarchy
• Version Tracking - Update mappings with change descriptions
• Version Diffing - Compare versions to see what changed

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst

mapping = client.mappings.list(search="tutorial-customer-graph").items[0]
print(f"Connected to: {client._config.api_url}")
print(f"Using mapping: {mapping.name} (id={mapping.id})")

1

Copying Mappings

Duplicate with modifications

# Copy a mapping to create a variation without starting from scratch
# copy(mapping_id, new_name) -- positional args, not keyword
copied = client.mappings.copy(mapping.id, "CustomerGraph-v2")
print(f"Original:  {mapping.name} (id={mapping.id})")
print(f"Copy:      {copied.name} (id={copied.id})")
print(f"Version:   {copied.current_version}")

2

Mapping Hierarchy

Versions and instances as a tree

# get_tree() returns the mapping's version/snapshot/instance hierarchy
tree = client.mappings.get_tree(mapping.id, include_instances=True)

# tree is a dict keyed by version number
for version_num, version_info in tree.items():
    print(f"Version {version_num}: {version_info['name']}")
    for snap in version_info.get("snapshots", []):
        print(f"  Snapshot: {snap['id']}")
        for inst in snap.get("instances", []):
            print(f"    Instance: {inst}")

3

Version Tracking

Update mappings and track changes

# Updating a mapping creates a new version automatically.
# Always provide a change_description for audit trail.
from graph_olap.models.mapping import NodeDefinition, EdgeDefinition, PropertyDefinition

# Add a Location node to the copied mapping
location_node = NodeDefinition(
    label="Location",
    sql="SELECT 'HK' as id, 'Hong Kong' as name",
    primary_key={"name": "id", "type": "STRING"},
    properties=[PropertyDefinition(name="name", type="STRING")],
)

updated = client.mappings.update(
    copied.id,
    change_description="Add Location node",
    node_definitions=copied.node_definitions + [location_node],
    edge_definitions=copied.edge_definitions,
)
print(f"Updated mapping: {updated.name}")
print(f"New version:     {updated.current_version}")
print(f"Node labels:     {[n.label for n in updated.node_definitions]}")

4

Version Diffing

Compare versions to see what changed

# Diff two versions of a mapping to see exactly what changed
diff = client.mappings.diff(copied.id, from_version=1, to_version=2)
print(f"Nodes added:   {diff.summary['nodes_added']}")
print(f"Nodes removed: {diff.summary['nodes_removed']}")
print(f"Edges added:   {diff.summary['edges_added']}")
print(f"Edges removed: {diff.summary['edges_removed']}")

# See the detailed notebook 04_version_diffing for advanced diffing workflows

Key Takeaways

• client.mappings.copy(id, new_name=...) duplicates a mapping for experimentation
• get_tree(id) shows the version → snapshot → instance hierarchy
• update(id, change_description=..., ...) creates a new version with an audit trail
• diff(id, from_version, to_version) shows exactly what changed between versions
• See 04_version_diffing for advanced diff workflows