Graph Definition Language (GraphDL) - semantic expansion connecting data to workflows

graph

GraphDL - Graph Definition Language that provides semantic expansion connecting data operations to workflow orchestration through graph-based relationships and traversal patterns.

Overview

The graph primitive implements GraphDL (Graph Definition Language) - the semantic layer that connects:

Data (see data) - Semantic triples and entity relationships
Workflows (see workflows) - Multi-step business process orchestration
Context (see context) - Semantic vocabulary and grounding information

Core Principle: GraphDL enables semantic expansion by treating all data as an interconnected graph where entities are nodes, relationships are edges, and workflows traverse these connections to orchestrate business logic.

The Connection: While data provides semantic triples ($.Subject.predicate.Object), graph provides the traversal language and relationship definitions that enable complex queries and workflow orchestration across those triples.

GraphDL Fundamentals

Entity Definitions

Define entities as graph nodes with properties and relationships:

import { graph, $ } from 'sdk.do'

// Define User entity
const User = graph.entity('User', {
  properties: {
    id: 'string',
    name: 'string',
    email: 'string',
    createdAt: 'datetime',
  },
  relationships: {
    has: ['Order', 'Profile', 'Subscription'],
    works: ['Organization', 'Team'],
    manages: ['Project', 'Team'],
  },
})

// Define Order entity
const Order = graph.entity('Order', {
  properties: {
    id: 'string',
    total: 'number',
    status: 'string',
    createdAt: 'datetime',
  },
  relationships: {
    belongs: ['User'],
    contains: ['Item'],
    ships: ['Address'],
  },
})

// Access via semantic triples
const user = await $.User.get('user-123')
const orders = await $.User.has.Orders({ userId: user.id })

Relationship Definitions

Define relationships as graph edges with properties:

import { graph } from 'sdk.do'

// Define 'has' relationship: User → Order
graph.relationship('has', {
  from: 'User',
  to: 'Order',
  cardinality: 'one-to-many',
  inverse: 'belongs',
  properties: {
    since: 'datetime',
    status: 'string',
  },
})

// Define 'works' relationship: User ↔ Organization
graph.relationship('works', {
  from: 'User',
  to: 'Organization',
  cardinality: 'many-to-many',
  properties: {
    role: 'string',
    startDate: 'date',
    endDate: 'date',
    department: 'string',
  },
})

// Define 'manages' relationship: User → Project
graph.relationship('manages', {
  from: 'User',
  to: 'Project',
  cardinality: 'many-to-many',
  properties: {
    responsibilities: 'string[]',
    startDate: 'date',
  },
})

Graph Traversal

Traverse graph relationships to discover connected data:

import { graph, $ } from 'sdk.do'

// Single-hop traversal
const orders = await graph.from($.User.get('user-123')).traverse($.User.has.Orders)

// Multi-hop traversal
const orderItems = await graph.from($.User.get('user-123')).traverse($.User.has.Orders).traverse($.Order.contains.Items)

// Filtered traversal
const activeProjects = await graph.from($.User.get('user-123')).traverse($.User.manages.Projects).where($.Project.status.equals('active'))

// Deep traversal
const teamProjects = await graph
  .from($.Organization.get('org-456'))
  .traverse($.Organization.has.Teams)
  .traverse($.Team.has.Members)
  .traverse($.User.works.Projects)
  .where($.Project.status.equals('active'))

Semantic Expansion

GraphDL expands semantic triples into complex graph queries:

Triple Expansion

Basic triples expand into graph traversals:

import { $, graph } from 'sdk.do'

// Triple: $.User.has.Orders
const triple = $.User.has.Orders

// Expands to graph traversal
const orders = await graph.from($.User.get('user-123')).follow(triple).all()

// Equivalent to:
const orders = await graph.from($.User.get('user-123')).traverse('has').to('Order').all()

Relationship Chains

Chain multiple relationships for complex queries:

import { graph, $ } from 'sdk.do'

// Find all products ordered by team members
const products = await graph
  .from($.Team.get('team-456'))
  .chain([
    $.Team.has.Members, // Team → Users
    $.User.has.Orders, // Users → Orders
    $.Order.contains.Items, // Orders → Items
    $.Item.references.Product, // Items → Products
  ])
  .unique()

// With filtering at each step
const expensiveProducts = await graph
  .from($.Team.get('team-456'))
  .traverse($.Team.has.Members)
  .where($.User.active.equals(true))
  .traverse($.User.has.Orders)
  .where($.Order.total.greaterThan(1000))
  .traverse($.Order.contains.Items)
  .traverse($.Item.references.Product)
  .where($.Product.price.greaterThan(100))

Multi-Path Expansion

Explore multiple relationship paths simultaneously:

import { graph, $ } from 'sdk.do'

// Find all related entities
const related = await graph.from($.User.get('user-123')).expand({
  orders: $.User.has.Orders,
  teams: $.User.works.Teams,
  projects: $.User.manages.Projects,
  colleagues: [$.User.works.Organizations, $.Organization.has.Teams, $.Team.has.Members],
})

// Result: {
//   orders: [Order[], ...],
//   teams: [Team[], ...],
//   projects: [Project[], ...],
//   colleagues: [User[], ...]
// }

Connecting Data to Workflows

GraphDL bridges semantic data operations with workflow orchestration:

Workflow Data Gathering

Use graph traversal to gather workflow context:

import { workflow, graph, $ } from 'sdk.do'

workflow('process-order', async ({ order }) => {
  // Gather all related data via graph traversal
  const context = await graph.from($.Order.get(order.id)).expand({
    customer: $.Order.belongs.User,
    items: $.Order.contains.Items,
    products: [$.Order.contains.Items, $.Item.references.Product],
    shippingAddress: $.Order.ships.Address,
    paymentMethod: $.Order.uses.PaymentMethod,
  })

  // Workflow uses expanded context
  await validateOrder(context)
  await processPayment(context)
  await createShipment(context)
})

Workflow Routing

Route workflows based on graph relationships:

import { workflow, graph, $, on } from 'sdk.do'

on($.Order.created, async ({ order }) => {
  // Find responsible team via graph traversal
  const team = await graph
    .from($.Order.get(order.id))
    .traverse($.Order.belongs.User)
    .traverse($.User.works.Organizations)
    .traverse($.Organization.has.Teams)
    .where($.Team.role.equals('fulfillment'))
    .first()

  // Route to appropriate workflow
  await workflow('fulfill-order', { order, team })
})

Workflow Dependencies

Discover workflow dependencies via graph:

import { workflow, graph, $ } from 'sdk.do'

workflow('deploy-project', async ({ project }) => {
  // Find all dependent projects
  const dependencies = await graph.from($.Project.get(project.id)).traverse($.Project.depends.Projects)

  // Execute dependency workflows first
  for (const dep of dependencies) {
    await workflow('deploy-project', { project: dep })
  }

  // Then deploy this project
  await deployProject(project)
})

Graph Patterns

Shortest Path

Find shortest path between entities:

import { graph, $ } from 'sdk.do'

// Find connection between two users
const path = await graph.shortestPath($.User.get('user-123'), $.User.get('user-456'), {
  maxDepth: 6,
  via: [$.User.works.Organizations, $.Organization.has.Teams, $.Team.has.Members],
})

// Result: [User, Organization, Team, User]

Neighborhood Discovery

Discover entity neighborhoods:

import { graph, $ } from 'sdk.do'

// Find all entities within 2 hops
const neighborhood = await graph.from($.User.get('user-123')).neighborhood({
  depth: 2,
  relationships: [$.User.has.Orders, $.User.works.Teams, $.User.manages.Projects],
})

// Result: { users: [], orders: [], teams: [], projects: [] }

Subgraph Extraction

Extract relevant subgraphs:

import { graph, $ } from 'sdk.do'

// Extract order fulfillment subgraph
const subgraph = await graph.subgraph($.Order.get('order-123'), {
  include: [$.Order.belongs.User, $.Order.contains.Items, $.Item.references.Product, $.Order.ships.Address, $.Order.uses.PaymentMethod],
  depth: 3,
})

// Use subgraph in workflow
workflow('fulfill-order', async () => {
  await processSubgraph(subgraph)
})

Similarity Discovery

Find similar entities via graph patterns:

import { graph, $ } from 'sdk.do'

// Find users similar to target user
const similarUsers = await graph.similar($.User.get('user-123'), {
  via: [$.User.has.Orders, $.User.works.Organizations, $.User.references.Interests],
  threshold: 0.7,
  limit: 10,
})

// Workflow uses similar users
workflow('recommend-products', async ({ user }) => {
  const similar = await graph.similar($.User.get(user.id))
  const recommendations = await generateRecommendations(similar)
  return recommendations
})

Graph Queries

Cypher-Style Queries

Express complex patterns using Cypher-inspired syntax:

import { graph } from 'sdk.do'

// Find users who ordered same products
const query = graph.query(`
  MATCH (u1:User)-[:has]->(o1:Order)-[:contains]->(i1:Item)-[:references]->(p:Product)
  MATCH (u2:User)-[:has]->(o2:Order)-[:contains]->(i2:Item)-[:references]->(p)
  WHERE u1.id = 'user-123' AND u1.id != u2.id
  RETURN DISTINCT u2, p
  LIMIT 10
`)

const results = await query.execute()

Pattern Matching

Match complex graph patterns:

import { graph } from 'sdk.do'

// Find collaboration patterns
const collaborators = await graph.match({
  pattern: [
    { type: 'User', id: 'user-123' },
    { rel: 'works', direction: 'out' },
    { type: 'Organization' },
    { rel: 'has', direction: 'out' },
    { type: 'Team' },
    { rel: 'has', direction: 'out' },
    { type: 'User', where: { active: true } },
  ],
})

Aggregation Queries

Aggregate data across graph:

import { graph, $ } from 'sdk.do'

// Calculate total orders per team
const teamOrders = await graph
  .from($.Organization.get('org-456'))
  .traverse($.Organization.has.Teams)
  .aggregate({
    by: 'team',
    metrics: {
      orderCount: graph.count($.Team.has.Members).traverse($.User.has.Orders),
      totalRevenue: graph.sum($.Team.has.Members.traverse($.User.has.Orders).property('total')),
    },
  })

Schema Integration

GraphDL integrates with schema.org.ai vocabularies:

Vocabulary-Based Entities

Define entities using schema.org.ai types:

import { graph } from 'sdk.do'

// Define Business using schema.org vocabulary
const Business = graph.entity('Business', {
  '@context': 'https://schema.org.ai/',
  '@type': 'Organization',
  properties: {
    name: 'schema:name',
    industry: {
      '@type': 'schema:industry',
      '@context': 'https://industries.org.ai/',
    },
    employees: 'schema:employee',
    revenue: 'schema:annualRevenue',
  },
  relationships: {
    has: ['Employee', 'Department', 'Product'],
    operates: ['Facility', 'Store'],
  },
})

Semantic Relationships

Define relationships using semantic vocabulary:

import { graph } from 'sdk.do'

// Use schema.org predicates
graph.relationship('employs', {
  '@id': 'schema:employee',
  from: 'Business',
  to: 'Person',
  cardinality: 'one-to-many',
  inverse: 'worksFor',
})

graph.relationship('worksFor', {
  '@id': 'schema:worksFor',
  from: 'Person',
  to: 'Business',
  cardinality: 'many-to-one',
})

SDK Object Integration

GraphDL integrates with data and workflow primitives:

import { graph, $, workflow, on, db } from 'sdk.do'

// DB - Graph queries over database (db is 1 of 8 core SDK objects)
const users = await db.graph.traverse($.Organization.get('org-123'), $.Organization.has.Teams, $.Team.has.Members)

// WORKFLOW - Graph-driven workflow orchestration
workflow('sync-teams', async ({ org }) => {
  const teams = await graph.from($.Organization.get(org.id)).traverse($.Organization.has.Teams)

  for (const team of teams) {
    await syncTeam(team)
  }
})

// ON - Event-driven graph operations (on is 1 of 8 core SDK objects)
on($.User.created, async ({ user }) => {
  // Find recommended teams via graph
  const teams = await graph.similar($.User.get(user.id), {
    via: [$.User.references.Interests],
    entity: 'Team',
  })

  await assignToTeams(user, teams)
})

Core Capabilities

Entity Definitions - Define graph nodes with properties
Relationship Definitions - Define graph edges with constraints
Graph Traversal - Navigate entity relationships
Semantic Expansion - Expand triples into graph queries
Pattern Matching - Match complex graph patterns
Shortest Path - Find optimal connection paths
Subgraph Extraction - Extract relevant portions
Schema Integration - Use schema.org.ai vocabularies
Workflow Connection - Bridge data to workflows

Access Methods

SDK

TypeScript/JavaScript library for GraphDL operations

await graph.from($.User.get('user-123')).traverse($.User.has.Orders)

→ SDK Documentation

CLI

Command-line tool for graph queries

do graph traverse "$.User.get('user-123')" "$.User.has.Orders"

→ CLI Documentation

API

REST/RPC endpoints for graph operations

curl -X POST https://api.do/v1/graph/traverse -d '{"from":"user-123","via":"$.User.has.Orders"}'

→ API Documentation

MCP

Model Context Protocol for AI-driven graph queries

Traverse from user user-123 following $.User.has.Orders relationship

→ MCP Documentation

Parent Concept

semantics - GraphDL implements semantic patterns

Core Integration

data - GraphDL provides traversal over semantic triples
workflows - Graph connects data to workflow orchestration
context - Graph uses semantic vocabulary (@context)

SDK Object Mappings

db - Database with graph query layer (SDK object - 1 of 8 core)
on - Event-driven graph operations (SDK object - 1 of 8 core)

functions - Functions use graph for data access
agents - Agents traverse graphs for context
schema - Entity and relationship schemas
database - Graph storage layer

graph

On this page