GRAPHQL_EXAMPLES.md

# Example GraphQL Queries for Cancer@Home v2

## Basic Queries

### Get all genes
```graphql
query {
  genes(limit: 10) {
    gene_id
    symbol
    name
    chromosome
    gene_type
  }
}
```

### Get specific gene by symbol
```graphql
query {
  gene(symbol: "TP53") {
    gene_id
    symbol
    name
    chromosome
    start_position
    end_position
  }
}
```

### Get mutations for a specific gene
```graphql
query {
  mutations(gene: "TP53", limit: 20) {
    mutation_id
    chromosome
    position
    reference
    alternate
    consequence
    variant_type
    quality
  }
}
```

### Get mutations on a chromosome
```graphql
query {
  mutations(chromosome: "chr17", limit: 50) {
    mutation_id
    position
    reference
    alternate
    consequence
  }
}
```

## Patient Queries

### Get all patients
```graphql
query {
  patients(limit: 100) {
    patient_id
    project_id
    age
    gender
    race
    vital_status
  }
}
```

### Get patients by project
```graphql
query {
  patients(project_id: "TCGA-BRCA") {
    patient_id
    age
    gender
    vital_status
  }
}
```

### Get patients by cancer type
```graphql
query {
  patients(cancer_type: "BRCA", limit: 50) {
    patient_id
    age
    gender
    race
  }
}
```

## Cancer Type Queries

### Get all cancer types
```graphql
query {
  cancerTypes {
    cancer_type_id
    name
    tissue
    disease_type
  }
}
```

### Get statistics for a cancer type
```graphql
query {
  cancerStatistics(cancer_type_id: "BRCA") {
    cancer_type
    total_patients
    total_mutations
    avg_mutations_per_patient
  }
}
```

## Mutation Analysis

### Get mutation frequency
```graphql
query {
  mutationFrequency(mutation_id: "MUT-TP53-001") {
    mutation_id
    patients_with_mutation
    total_patients
    frequency
  }
}
```

## Complex Queries

### Combined gene and mutation data
```graphql
query {
  gene(symbol: "BRCA1") {
    symbol
    name
    chromosome
  }
  
  mutations(gene: "BRCA1") {
    mutation_id
    position
    consequence
    quality
  }
}
```

### Multiple cancer statistics
```graphql
query {
  breastCancer: cancerStatistics(cancer_type_id: "BRCA") {
    cancer_type
    total_patients
    total_mutations
  }
  
  lungCancer: cancerStatistics(cancer_type_id: "LUAD") {
    cancer_type
    total_patients
    total_mutations
  }
}
```

## Using Variables

### Query with variables
```graphql
query GetGeneInfo($geneSymbol: String!) {
  gene(symbol: $geneSymbol) {
    symbol
    name
    chromosome
  }
  
  mutations(gene: $geneSymbol) {
    mutation_id
    position
    consequence
  }
}
```

Variables:
```json
{
  "geneSymbol": "TP53"
}
```

### Pagination example
```graphql
query GetMutations($limit: Int = 10) {
  mutations(limit: $limit) {
    mutation_id
    chromosome
    position
  }
}
```

Variables:
```json
{
  "limit": 25
}
```

## Filtering Examples

### Get high-quality mutations
```graphql
query {
  mutations(gene: "KRAS", limit: 100) {
    mutation_id
    quality
    consequence
  }
}
```

### Get patients by demographics
```graphql
query {
  patients(project_id: "TCGA-BRCA") {
    patient_id
    age
    gender
    race
    vital_status
  }
}
```

## Tips for Using GraphQL

1. **Use the GraphQL Playground**: Navigate to http://localhost:5000/graphql for an interactive interface with autocomplete and documentation

2. **Request only needed fields**: GraphQL allows you to request exactly the data you need, improving performance

3. **Combine multiple queries**: Use aliases to fetch different datasets in a single request

4. **Use variables**: Make queries reusable by parameterizing them with variables

5. **Explore the schema**: Use the GraphQL Playground's "Docs" panel to see all available queries and fields