User Guide

User Guide

This guide provides step-by-step instructions for using SPARQLWorks™ to compose queries and visualize RDF data.

🚀 Getting Started

Accessing SPARQLWorks

1. Open your web browser
2. Navigate to the SPARQLWorks application URL
3. The interface loads with default settings

Initial Setup

The application opens with:

• Demo endpoint: https://demo.openlinksw.com/sparql (pre-configured)
• Basic mode: Selected by default
• Sample query: Pre-loaded example
• Empty graph: Ready for your first visualization

📝 Composing Queries

Step 1: Select SPARQL Endpoint

1. Locate the "SPARQL Endpoint" field in the query panel
2. Enter your endpoint URL (or choose from the datalist)
3. Popular endpoints include:
   • https://demo.openlinksw.com/sparql
   • https://query.wikidata.org/sparql
   • https://dbpedia.org/sparql

Step 2: Choose Query Mode

Basic Mode (Recommended for Beginners)

1. Click the "Basic" tab
2. Use the code editor to write triple patterns
3. Example basic query:

   ?movie dbo:creator ?creator;
          rdfs:label ?movieName.
   FILTER(?creator = dbr:Spike_Lee).
   

4. Adjust the LIMIT slider (default: 200)

Advanced Mode (For Experts)

1. Click the "Advanced" tab
2. Write complete SPARQL CONSTRUCT queries
3. Example advanced query:

   CONSTRUCT {
     ?movie dbo:creator ?creator;
            rdfs:label ?movieName.
   }
   WHERE {
     ?movie dbo:creator ?creator;
            rdfs:label ?movieName.
     FILTER(?creator = dbr:Spike_Lee).
   }
   LIMIT 200

Step 3: Run Your Query

1. Click the "Run Query" button
2. Wait for execution (progress shown in button text)
3. Results appear as an interactive graph
4. Success/error messages display as toast notifications

🎨 Exploring the Graph

Understanding Graph Elements

Nodes

• Blue circles: IRI entities (persons, places, concepts)
• Green circles: RDF classes/types
• Orange circles: Role-based entities
• Small gray circles: Literal values (strings, numbers, dates)

Edges

• Arrows: Directed relationships from subject to object
• Icons: Predicate representations (or full names)
• Colors: Match source node colors
• Double arrows: Symmetric predicates (e.g., owl:sameAs)

Graph Interactions

Navigation

• Zoom: Mouse wheel up/down
• Pan: Click and drag empty space
• Fit to screen: Click the "Fit" button
• Reset zoom: Double-click empty space

Node Interactions

• Hover: Highlight connected nodes and relationships
• Click: Open entity IRI in new browser tab
• Drag: Reposition nodes manually
• Double-click: Release pinned position

Edge Interactions

• Hover: Show full predicate IRI and relationship details
• Click: Open predicate IRI in new browser tab

Visual Controls

Physics Settings

1. Click the gear icon (⚙️) to open controls panel
2. Adjust "Physics: Charge Strength" (-1000 to 0)
   • Lower values = stronger repulsion
   • Higher values = weaker repulsion
3. Adjust "Physics: Link Distance" (10-300 pixels)
   • Controls spacing between connected nodes

Display Options

• Hover focus: Enable/disable highlight on hover
• Friendly labels: Show human-readable names vs. URIs
• IRI Labels: Toggle compact CURIE display
• Preferred Language: Set language preference for labels

🔍 Filtering Results

Node Group Filtering

1. In the controls panel, check/uncheck node types:
   • IRI: External entities and resources
   • Class: RDF type definitions
   • Category: Classification terms
   • Role: Functional roles
   • Literal: Data values

Type-Based Filtering

1. Click "Filter by rdf:type" accordion
2. Select "Select all" or choose specific types
3. Only nodes with selected types remain visible
4. Connected relationships automatically adjust

Property-Based Filtering

1. Click "Filter by property" accordion
2. Select "Select all" or choose specific predicates
3. Only relationships using selected properties appear
4. Graph focuses on filtered relationships

Additional Filters

• Hide rdf:type relationships: Remove type classification edges
• Edge annotations: Choose between icons or full predicate names

🔐 Setting Up Authentication

OAuth Authentication

1. Click the account icon (👤) in the top-right
2. Click "Log In"
3. Follow OAuth flow for your SPARQL endpoint
4. Credentials stored locally and automatically applied

Bearer Token Authentication

1. Click the account icon (👤)
2. Click "Provide Bearer token"
3. Enter your token in the modal
4. Click "Save & Authenticate"

OAuth Settings (Advanced)

1. Click "OAuth Settings" from account menu
2. Configure Client ID (if required by endpoint)
3. Set Redirect URI (defaults to current page)
4. Settings persist across sessions

🔗 Sharing Your Work

Creating Shareable Links

1. Configure your query and visualization settings
2. Click the link icon (🔗) next to the controls toggle
3. Link copies to clipboard automatically
4. Share with colleagues or bookmark for later

URL Parameters

Shareable links encode:

• Complete SPARQL query
• Endpoint URL
• Visualization settings
• Filter configurations
• Authentication state (secure)

🛠️ Advanced Usage

Customizing Labels

1. Click the gear icon next to "Use IRI Labels"
2. "Label priority settings" modal opens
3. Drag to reorder label predicate preferences
4. Changes apply immediately to current graph

Managing Query History

• Advanced mode: Full query editing history via Ace Editor
• Basic mode: Triple pattern history
• URL persistence: Settings saved in browser URL

Working with Large Datasets

• Progressive loading: Large result sets load incrementally
• Filtering first: Apply filters before full rendering
• Physics optimization: Adjust charge/link settings for performance

🐛 Troubleshooting

Common Issues

Query Fails

• Check endpoint URL: Ensure it's accessible and SPARQL-compliant
• Verify syntax: Use Advanced mode to validate SPARQL syntax
• Check authentication: Some endpoints require credentials

Graph Not Displaying

• Empty results: Query returned no data - try broadening WHERE clause
• Network timeout: Large queries may time out - reduce LIMIT
• CORS issues: Some endpoints block browser requests

Authentication Problems

• OAuth flow fails: Check redirect URI configuration
• Token rejected: Verify token validity and format
• CORS blocking: Some endpoints don't support browser authentication

Performance Tips

• Start with LIMIT: Use small limits (50-100) for testing
• Filter early: Apply type/property filters before running large queries
• Use Basic mode: For complex visualizations, start simple
• Close panels: Hide query panel when exploring large graphs

📚 Next Steps

• Query Modes - Deep dive into Basic vs Advanced
• Graph Visualization - Advanced visualization techniques
• Examples - Sample queries for different use cases
• Authentication - Detailed authentication setup

---

← Features | Next: Query Modes →