Graph DML Statements

Statements for manipulating graph relationships, node positions, and content in RaisinDB.

RELATE

Create a relationship between two nodes.

Syntax

RELATE source_node TO target_node
    [ TYPE relationship_type ]
    [ WEIGHT weight_value ]
    [ IN BRANCH branch_name ]
    [ IN WORKSPACE workspace_name ]

Examples

-- Create a basic relationship
RELATE '/content/page1' TO '/content/page2';

-- Create a typed relationship
RELATE '/users/alice' TO '/projects/alpha'
    TYPE 'member';

-- Create a weighted relationship
RELATE '/products/widget' TO '/categories/electronics'
    TYPE 'belongs_to'
    WEIGHT 1.0;

-- Create relationship in a specific branch
RELATE '/content/page1' TO '/content/page2'
    TYPE 'links_to'
    IN BRANCH feature_branch;

-- Create relationship in a specific workspace
RELATE '/docs/intro' TO '/docs/guide'
    TYPE 'see_also'
    IN WORKSPACE documentation;

---

UNRELATE

Remove a relationship between two nodes.

Syntax

UNRELATE source_node FROM target_node
    [ TYPE relationship_type ]
    [ IN BRANCH branch_name ]
    [ IN WORKSPACE workspace_name ]

Examples

-- Remove all relationships between two nodes
UNRELATE '/content/page1' FROM '/content/page2';

-- Remove a specific relationship type
UNRELATE '/users/alice' FROM '/projects/alpha'
    TYPE 'member';

-- Remove relationship in a specific branch
UNRELATE '/content/page1' FROM '/content/page2'
    TYPE 'links_to'
    IN BRANCH feature_branch;

---

MOVE

Move a node to a new position in the hierarchy.

Syntax

MOVE source_path TO destination_path

Examples

-- Move a node to a new parent
MOVE '/content/drafts/post1' TO '/content/published/post1';

-- Move a section
MOVE '/docs/old-section' TO '/archive/old-section';

---

COPY

Copy a node, optionally with all its descendants.

Syntax

COPY source_path TO destination_path
    [ RECURSIVE ]

Examples

-- Copy a single node
COPY '/templates/page-template' TO '/content/new-page';

-- Copy a node and all descendants recursively
COPY '/content/blog/2024' TO '/archive/blog/2024'
    RECURSIVE;

---

ORDER

Set the order of nodes within a parent.

Syntax

ORDER node_path position

Examples

-- Set node order position
ORDER '/content/menu/item1' 1;
ORDER '/content/menu/item2' 2;
ORDER '/content/menu/item3' 3;

---

RESTORE

Restore a node from a previous revision.

Syntax

RESTORE node_path [ AT REVISION revision_number ]

Examples

-- Restore a node to its previous state
RESTORE '/content/page1';

-- Restore a node at a specific revision
RESTORE '/content/page1' AT REVISION 5;

---

TRANSLATE

Create or update translations for node content, per locale. Translations are stored as an overlay on the base node — only the fields you set are translated; everything else falls back to the base content.

Syntax

UPDATE <workspace> FOR LOCALE '<locale>' [IN BRANCH '<branch>']
    SET <path> = <value> [, ...]
    WHERE <path = '...' | id = '...'> [AND node_type = '...']

• <workspace> is the workspace name — NOT a node type. It is the same table identifier you use in SELECT … FROM <workspace>; RaisinDB SQL tables are workspaces. So UPDATE Page … means "translate in the workspace named Page", not "translate nodes of type Page". To restrict by node type, add AND node_type = '...' to the WHERE clause.
• FOR LOCALE takes a locale code such as 'de', 'fr', 'en-US'.
• IN BRANCH is optional; without it the current branch is used.
• A WHERE clause is required to identify the target node (by path or id).

Paths

A SET target is a path into the node's content:

Path form	Targets
title	a top-level field
metadata.author	a nested object field
blocks[uuid='b1'].text	a field on a repeatable item, addressed by uuid
sections[uuid='s1'].features[uuid='f1'].title	a field nested inside two array levels

array[uuid='…'] addressing works to any depth — a composite inside a multivalue element field, a composite inside a composite, and so on. Each array item along the path must carry a uuid (see the Translations guide for how to model translatable composites). The path flattens to a JSON pointer (/sections/s1/features/f1/title) that the resolver walks by matching each uuid against array items, so nested fields round-trip without replacing the surrounding array.

Examples

In the examples below, Page is a workspace name (as in SELECT … FROM Page), not a node type.

-- Translate top-level fields to Spanish
UPDATE Page FOR LOCALE 'es'
    SET title = 'Bienvenidos',
        description = 'Pagina principal'
    WHERE path = '/content/homepage';

-- Translate a field inside a repeatable composite item
UPDATE Page FOR LOCALE 'fr'
    SET blocks[uuid='hero-1'].heading = 'Bonjour'
    WHERE path = '/content/homepage';

-- Translate a field nested two array levels deep
-- (a composite inside a multivalue element field)
UPDATE Page FOR LOCALE 'de'
    SET sections[uuid='s1'].features[uuid='f1'].title = 'Schnelle Entwicklung'
    WHERE path = '/home';

---

Examples

Building a Navigation Structure

-- Create pages and establish relationships
INSERT INTO pages (title, status) VALUES ('Home', 'published');
INSERT INTO pages (title, status) VALUES ('About', 'published');
INSERT INTO pages (title, status) VALUES ('Contact', 'published');

-- Create navigation relationships
RELATE '/pages/home' TO '/pages/about' TYPE 'nav_link' WEIGHT 1.0;
RELATE '/pages/home' TO '/pages/contact' TYPE 'nav_link' WEIGHT 2.0;

-- Order the navigation items
ORDER '/pages/about' 1;
ORDER '/pages/contact' 2;

Content Reorganization

-- Move old content to archive
MOVE '/content/2023' TO '/archive/2023';

-- Copy template for new year
COPY '/templates/year-template' TO '/content/2025' RECURSIVE;

Multi-Language Content

-- Create base content
INSERT INTO products (name, description)
VALUES ('Premium Widget', 'High-quality widget for professionals');

-- Add translations
UPDATE Product FOR LOCALE 'es'
    SET name = 'Widget Premium',
        description = 'Widget de alta calidad para profesionales'
    WHERE path = '/products/premium-widget';

UPDATE Product FOR LOCALE 'de'
    SET name = 'Premium Widget',
        description = 'Hochwertiges Widget fuer Profis'
    WHERE path = '/products/premium-widget';

Version-Controlled Relationships

-- Create relationships on a feature branch
USE BRANCH feature_new_links;

RELATE '/docs/quickstart' TO '/docs/advanced-guide'
    TYPE 'next_step';

RELATE '/docs/advanced-guide' TO '/docs/reference'
    TYPE 'next_step';

COMMIT MESSAGE 'Add documentation navigation flow';

-- Merge to main
MERGE BRANCH feature_new_links INTO main;

---

Notes

• RELATE and UNRELATE manage graph edges between nodes
• MOVE changes the hierarchical position; the node's __path is updated
• COPY with RECURSIVE duplicates the entire subtree
• ORDER sets explicit ordering for sibling nodes
• RESTORE uses the version control system to revert node state
• TRANSLATE stores localized field values associated with a language code
• All graph DML operations are version-controlled and can be part of transactions