# Knowledge Graph Linking Best Practices

This directory contains proven methodologies for connecting entities in AGS (AnzoGraph Services) knowledge graphs using SPARQL transformations.

## 📁 Documentation Structure

### Core Methodologies
- **[INTERNAL_LINKING_BEST_PRACTICES.md](./INTERNAL_LINKING_BEST_PRACTICES.md)** - Connect entities within a single domain ontology
- **[CROSS_DOMAIN_LINKING_BEST_PRACTICES.md](./CROSS_DOMAIN_LINKING_BEST_PRACTICES.md)** - Connect entities across multiple domain ontologies

### Architectural Guides
- **[AGS_Architecture_Guide.md](./AGS_Architecture_Guide.md)** - Overall AGS architecture patterns
- **[ONTOLOGY_DATA_LAYER_BEST_PRACTICES.md](./ONTOLOGY_DATA_LAYER_BEST_PRACTICES.md)** - Data layer design principles

## 🎯 When to Use Each Guide

### Internal Linking
**Use when:** You have a single domain with "islands" - entities that reference each other via string foreign keys but lack object property relationships.

**Examples:**
- CRM: Opportunities reference Customers via `customerId` string
- ERP: Invoices reference Cost Centers via `costCenter` string  
- PLM: Parts reference BOMs via `bomId` string

**Result:** Navigate relationships using object properties instead of string matching.

### Cross-Domain Linking  
**Use when:** You have multiple well-linked domains that need connections between them using shared identifiers.

**Examples:**
- PLM Parts and Manufacturing Orders both have `productId`
- CRM Customer Equipment and Service Work Orders both have `equipmentId`
- Quality Issues and Supply Chain Components both have `componentId`

**Result:** Enable cross-domain queries spanning multiple business domains.

## 🏗️ Architectural Patterns

### Single Domain Architecture (Internal Linking)
```
Source Data → Domain Data Layer → Domain Internal Linking Layer
```
- **One linking ontology per domain** (e.g., `CRMLinking`, `ERPLinking`)
- **One transformation layer per domain** (e.g., "CRM Internal Linking")
- **Result:** Well-connected domain with rich object property navigation

### Multi-Domain Architecture (Cross-Domain Linking)
```
Domain 1 Internal Linking ──┐
Domain 2 Internal Linking ──┤
Domain 3 Internal Linking ──┼─→ Cross-Domain Linking (Unified)
Domain 4 Internal Linking ──┤
Domain N Internal Linking ──┘
```
- **One unified cross-domain ontology** (`CrossDomainLinking`)
- **One unified transformation layer** ("Cross-Domain Linking")  
- **Result:** Fully connected knowledge graph enabling cross-domain analytics

## ⚡ Quick Start Checklist

### For Internal Linking (Single Domain)
- [ ] Identify string foreign keys within domain
- [ ] Create `{Domain}Linking` ontology  
- [ ] Import source domain ontology
- [ ] Add object properties for each FK relationship
- [ ] Create transformation layer with INSERT steps
- [ ] Validate with SELECT queries first
- [ ] Register ontology with graphmart
- [ ] Refresh (never reload unless requested)

### For Cross-Domain Linking (Multiple Domains)  
- [ ] Complete internal linking for all domains first
- [ ] Identify shared identifiers across domains (e.g., `productId`)
- [ ] Design minimum spanning tree for connectivity
- [ ] Create unified `CrossDomainLinking` ontology (one-time)
- [ ] Import all domain ontologies (one-time)
- [ ] Add cross-domain properties for each relationship
- [ ] Create unified transformation layer (one-time)
- [ ] Test coverage and validate with SELECT queries
- [ ] Execute transformations and validate connectivity

## 🚨 Critical Success Rules

### Universal Rules (Both Internal and Cross-Domain)
1. **Never modify auto-generated ontologies** - they get recreated on reload
2. **Always test with SELECT before INSERT** - validate query logic first
3. **Always register ontologies** - unregistered ontologies won't work  
4. **Use `refresh_graphmart` by default** - only use `reload_graphmart` if explicitly requested
5. **Validate link counts** - watch for cartesian products or insufficient matches
6. **Import dependencies** - linking ontologies must import source ontologies

### Internal Linking Specific Rules
7. **One ontology per domain** - separate linking concerns by business domain
8. **One layer per domain** - pair each linking ontology with its own transformation layer
9. **Expect 70-95% coverage** - string foreign keys usually have high match rates

### Cross-Domain Specific Rules  
10. **One unified ontology for all cross-domain links** - don't create multiple cross-domain ontologies
11. **One unified layer for all cross-domain transformations** - don't create multiple cross-domain layers
12. **Accept 20-60% coverage** - cross-domain matches have lower coverage (expected)
13. **Design minimum spanning tree** - use (N-1) links to connect N domains efficiently

## 📊 Success Metrics

### Internal Linking Success
- ✅ 70%+ entity coverage within domain
- ✅ Object property navigation replaces string matching
- ✅ Domain-specific business queries enabled
- ✅ Fast query performance (<2 seconds)

### Cross-Domain Linking Success  
- ✅ All domains reachable from any other domain
- ✅ 40%+ cross-domain coverage (excellent for Phase 1)
- ✅ Cross-domain business queries enabled
- ✅ No orphaned domain islands
- ✅ Minimum number of cross-domain links used

## 🔧 Tools & Commands Reference

### Core AGS MCP Commands
```bash
# Ontology Management
mcp_ags-sparql-ag_create_ontology
mcp_ags-sparql-ag_register_ontology  
mcp_ags-sparql-ag_add_ontology_import
mcp_ags-sparql-ag_add_ontology_property

# Layer Management  
mcp_ags-sparql-ag_create_transformation_layer
mcp_ags-sparql-ag_add_transformation_step

# Execution & Validation
mcp_ags-sparql-ag_refresh_graphmart
mcp_ags-sparql-ag_execute_sparql_query
mcp_ags-sparql-ag_get_layer_status

# Discovery & Analysis
mcp_ags-sparql-ag_list_transformation_layers
mcp_ags-sparql-ag_discover_available_ontologies
mcp_ags-sparql-ag_list_ontology_structure_classes
```

### SPARQL Query Templates
Available in each methodology guide:
- Entity counting queries
- Coverage analysis queries  
- Link validation queries
- Business validation queries
- Cross-domain navigation queries

## 🎓 Learning Path

1. **Start with Internal Linking** - Master single-domain linking first
2. **Complete all domains** - Ensure each domain is well-linked internally  
3. **Move to Cross-Domain** - Connect domains using minimum spanning tree approach
4. **Iterate and expand** - Add more cross-domain relationships based on business needs

## 💡 Tips for Success

- **Start small** - Begin with highest-coverage, most obvious relationships
- **Test frequently** - Validate every step with SELECT queries
- **Document gaps** - Real-world data has quality issues (expected and acceptable)
- **Think business value** - Focus on relationships that enable important questions
- **Be patient** - Knowledge graph linking is iterative - perfection comes with time

---

*These methodologies have been proven on large-scale enterprise knowledge graphs with millions of entities and hundreds of thousands of successful links.*