# Query Modes

SPARQLWorks™ provides two distinct modes for composing SPARQL queries, each designed to serve different user needs and skill levels.

## 📋 Overview

### Basic Mode
**Target Users**: Beginners, domain experts, quick exploration
- User-friendly interface for building queries
- Automatic CONSTRUCT query generation
- Focus on WHERE clause patterns
- Intuitive triple pattern editing

### Advanced Mode
**Target Users**: SPARQL experts, developers, complex queries
- Full SPARQL query editing with syntax highlighting
- Complete control over query structure
- Support for all SPARQL 1.1 features
- Manual CONSTRUCT template definition

## 🎯 Basic Mode

### Interface Elements
- **Triple Pattern Editor**: Large text area for WHERE clauses
- **LIMIT Control**: Slider to set result limit (1-10000)
- **Auto-Sync**: Changes automatically update Advanced mode

### Writing Basic Queries

#### Simple Triple Patterns
```
?person foaf:name ?name.
```
This creates a CONSTRUCT query finding all persons and their names.

#### Multiple Properties (Semicolon)
```
?person foaf:name ?name;
         foaf:knows ?friend.
```
Finds persons with both names and friends.

#### Multiple Objects (Comma)
```
?person foaf:name ?name, ?nickname.
```
Finds persons with multiple name variants.

#### Filters and Constraints
```
?movie dbo:creator ?creator;
       rdfs:label ?title.
FILTER(?creator = dbr:Spike_Lee)
```
Combines pattern matching with value constraints.

### Automatic CONSTRUCT Generation

Basic mode automatically generates CONSTRUCT queries from your WHERE patterns:

**Your Basic Input:**
```sparql
?movie dbo:creator ?creator;
       rdfs:label ?title.
FILTER(?creator = dbr:Spike_Lee)
```

**Generated CONSTRUCT Query:**
```sparql
CONSTRUCT {
  ?movie dbo:creator ?creator;
         rdfs:label ?title.
}
WHERE {
  ?movie dbo:creator ?creator;
         rdfs:label ?title.
  FILTER(?creator = dbr:Spike_Lee)
}
LIMIT 200
```

### Advanced Basic Features

#### Prefix Support
Use common prefixes directly:
```
?person foaf:name ?name.
?movie dbo:director dbr:Steven_Spielberg.
```

#### Inline LIMIT
Override UI limit in the query text:
```
?person foaf:name ?name.
LIMIT 50
```

#### Complex Patterns
```
?book dct:creator ?author;
      dct:title ?title;
      dct:subject ?topic.
FILTER(?topic = dbc:Literature)
```

## 🔧 Advanced Mode

### Interface Elements
- **Full Query Editor**: Syntax-highlighted SPARQL editor
- **Ace Editor**: Professional code editing features
- **Manual Control**: Complete query customization

### Writing Advanced Queries

#### Basic CONSTRUCT Structure
```sparql
CONSTRUCT {
  # Template for output triples
  ?subject ?predicate ?object.
}
WHERE {
  # Pattern matching
  ?subject ?predicate ?object.
}
```

#### Custom Templates
```sparql
CONSTRUCT {
  ?person foaf:name ?name;
          a foaf:Person.
}
WHERE {
  ?person foaf:name ?name.
}
```

#### Multiple Graph Patterns
```sparql
CONSTRUCT {
  ?movie dct:title ?title;
         dbo:director ?director.
}
WHERE {
  ?movie a dbo:Film;
         dct:title ?title.
  OPTIONAL { ?movie dbo:director ?director. }
}
```

### Advanced SPARQL Features

#### UNION Queries
```sparql
CONSTRUCT {
  ?entity rdfs:label ?label.
}
WHERE {
  { ?entity a dbo:Film; rdfs:label ?label. }
  UNION
  { ?entity a dbo:Person; rdfs:label ?label. }
}
```

#### Subqueries
```sparql
CONSTRUCT {
  ?movie dct:title ?title;
         :popularity ?rating.
}
WHERE {
  {
    SELECT ?movie (AVG(?rating) AS ?avgRating)
    WHERE {
      ?movie dbo:gross ?gross.
      BIND(?gross / 1000000 AS ?rating)
    }
    GROUP BY ?movie
  }
  ?movie dct:title ?title.
}
```

#### Property Paths
```sparql
CONSTRUCT {
  ?person foaf:name ?name;
          :colleague ?colleague.
}
WHERE {
  ?person foaf:knows+ ?colleague;
          foaf:name ?name.
  FILTER(?person != ?colleague)
}
```

### Prefix Declarations
```sparql
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX dbr: <http://dbpedia.org/resource/>

CONSTRUCT {
  ?person foaf:name ?name.
}
WHERE {
  ?person foaf:name ?name.
}
```

### Solution Modifiers
```sparql
CONSTRUCT {
  ?city dbo:populationTotal ?population.
}
WHERE {
  ?city a dbo:City;
        dbo:populationTotal ?population.
}
ORDER BY DESC(?population)
LIMIT 10
```

## 🔄 Mode Switching

### Basic to Advanced
- Click **"Advanced"** tab
- Basic WHERE clause converts to full CONSTRUCT query
- All patterns and filters preserved
- LIMIT setting applied

### Advanced to Basic
- Click **"Basic"** tab
- Warning appears if Advanced has custom edits
- WHERE clause extracted from CONSTRUCT query
- Prefixes and complex features may be simplified

### Synchronization
- Changes in Basic mode instantly update Advanced
- Advanced changes don't affect Basic (to prevent data loss)
- Manual sync by switching tabs

## 🎨 Visual Output

### Basic Mode Results
- Automatic graph generation
- All matched triples visualized
- Literal values included as nodes
- Type relationships shown

### Advanced Mode Results
- Exact CONSTRUCT template used
- Only specified triples in graph
- More control over visualization
- Can exclude unwanted relationships

## 📊 Use Cases

### Basic Mode Ideal For:
- **Data Exploration**: Quick browsing of datasets
- **Simple Queries**: Finding entities and properties
- **Learning SPARQL**: Gradual skill building
- **Domain Experts**: Focus on content, not syntax

### Advanced Mode Ideal For:
- **Complex Queries**: UNION, subqueries, property paths
- **Performance Tuning**: Optimized query patterns
- **Custom Visualization**: Specific graph structures
- **Integration**: API-like query construction

## 💡 Best Practices

### Starting with Basic
1. Begin in Basic mode for exploration
2. Refine patterns and filters
3. Switch to Advanced when needed
4. Use Advanced for complex logic

### Query Optimization
- Use LIMIT in Basic mode for testing
- Apply filters early in patterns
- Consider OPTIONAL vs. required patterns
- Test with small datasets first

### Mode Selection Guidelines
- **Basic**: Prototyping, exploration, simple patterns
- **Advanced**: Production queries, complex logic, custom output

## 🔧 Technical Details

### Basic Mode Processing
- Parses triple patterns from text
- Extracts FILTER and other clauses
- Generates minimal CONSTRUCT template
- Handles property paths and complex patterns

### Advanced Mode Processing
- Direct SPARQL execution
- No preprocessing or transformation
- Full SPARQL 1.1 compliance
- User has complete control

### Error Handling
- Basic mode: Pattern validation and suggestions
- Advanced mode: Standard SPARQL error reporting
- Cross-mode: Consistent error messaging

---

[← User Guide](User-Guide.md) | [Next: Graph Visualization →](Graph-Visualization.md)