# FHIR R4 Query Guide

## Table of Contents

- [Patient Resource](#patient-resource)
- [Coverage Resource](#coverage-resource)
- [CarePlan Resource](#careplan-resource)
- [Common Query Parameters](#common-query-parameters)
- [Advanced Query Techniques](#advanced-query-techniques)
- [Pagination](#pagination)


## Patient Resource

### Overview

The Patient resource contains demographic and administrative information about individuals receiving healthcare services.

### Key Elements

- Demographics (name, birthdate, gender)
- Contact information
- Language preferences
- Primary care provider
- Communication preferences
- Marital status
- Address history


### Basic Queries


```http
# Search by name
GET [base]/Patient?name=Smith

# Search by birth date
GET [base]/Patient?birthdate=1970-01-01

# Search by identifier (e.g., SSN, MRN)
GET [base]/Patient?identifier=12345

# Combined demographic search
GET [base]/Patient?
  given=John&
  family=Smith&
  gender=male&
  birthdate=ge1960-01-01
```

### Common Filter Options

- `name`: Full, given, or family name
- `birthdate`: Exact date or range
- `gender`: male, female, other, unknown
- `address`: City, state, postal code
- `active`: true/false
- `language`: Preferred language
- `identifier`: Various ID types


## Coverage Resource

### Overview

The Coverage resource details insurance or payment information for healthcare services.

### Key Elements

- Coverage status
- Subscriber information
- Benefit period
- Payor details
- Network information
- Cost-sharing details
- Coverage type


### Basic Queries


```http
# Active coverage for patient
GET [base]/Coverage?
  patient=12345&
  status=active

# Coverage with specific payor
GET [base]/Coverage?
  patient=12345&
  payor=Organization/789

# Coverage within date range
GET [base]/Coverage?
  patient=12345&
  period=ge2023-01-01&
  period=le2023-12-31
```

### Common Filter Options

- `status`: active, cancelled, draft
- `type`: Insurance type (medical, dental, etc.)
- `period`: Coverage dates
- `payor`: Insurance company
- `subscriber`: Primary insurance holder
- `beneficiary`: Covered individual
- `class`: Coverage classification


## CarePlan Resource

### Overview

The CarePlan resource documents the intended care strategy and goals for a patient.

### Key Elements

- Care goals
- Planned activities
- Care team members
- Treatment protocols
- Progress notes
- Status updates
- Care instructions


### Basic Queries


```http
# Active care plans
GET [base]/CarePlan?
  patient=12345&
  status=active

# Care plans by condition
GET [base]/CarePlan?
  patient=12345&
  condition=Condition/567

# Care plans by date
GET [base]/CarePlan?
  patient=12345&
  date=ge2023-01-01&
  _sort=-date
```

### Common Filter Options

- `status`: draft, active, completed, cancelled
- `category`: Type of care plan
- `condition`: Related health conditions
- `date`: Plan creation or update date
- `author`: Care plan creator
- `care-team`: Involved healthcare providers
- `goal`: Treatment goals


## Common Query Parameters

### Search Result Control

- `_count`: Number of results per page
- `_sort`: Sort order of results
- `_include`: Include related resources
- `_revinclude`: Include referring resources
- `_summary`: Return only summary information


### Date Parameters

- `eq`: Equals
- `ne`: Not equals
- `gt`: Greater than
- `lt`: Less than
- `ge`: Greater than or equals
- `le`: Less than or equals


### String Parameters

- `:exact`: Exact match
- `:contains`: Contains substring
- `:text`: Text search


## Advanced Query Techniques

### Chained Parameters


```http
# Patient with specific condition
GET [base]/Patient?
  _has:Condition:patient:code=http://snomed.info/sct|73211009
```

### Combined Resources


```http
# Patient with coverage and care plan
GET [base]/Patient?
  _id=12345&
  _include=Patient:general-practitioner&
  _revinclude=Coverage:patient&
  _revinclude=CarePlan:patient
```

### Composite Parameters


```http
# Search by name and birthdate combination
GET [base]/Patient?
  given-family-birthdate=John$Smith$1970-01-01
```

### Multi-Resource Search


```http
# Find all resources for a patient
GET [base]/Patient/12345/$everything
```

### Filtering Extensions


```http
# Search using custom extensions
GET [base]/Coverage?
  patient=12345&
  extension-custom-benefit-type=dental
```

### Resource References


```http
# Find care plans referencing specific practitioners
GET [base]/CarePlan?
  patient=12345&
  performer:Practitioner=Practitioner/789
```

## Pagination

### Overview

The API implements pagination using two key parameters:

- `_count`: Specifies the number of results per page
- `_page_token`: Token for accessing subsequent pages


### Response Structure

The API returns pagination information in the `link` array of the response:


```json
{
    "link": [
        {
            "relation": "search",
            "url": "[base]/Patient/?_count=1"
        },
        {
            "relation": "next",
            "url": "[base]/Patient/?_count=1&_page_token=AUAcb7bUcVAqcd..."
        },
        {
            "relation": "first",
            "url": "[base]/Patient/?_count=1"
        },
        {
            "relation": "self",
            "url": "[base]/Patient/?_count=1"
        }
    ]
}
```

### Link Relations

- `search`: Base search URL
- `next`: URL for the next page of results (includes page token)
- `first`: URL for the first page
- `self`: Current page URL


### Pagination Examples

#### Initial Query


```http
GET [base]/Patient?_count=1
```

#### Next Page Query


```http
GET [base]/Patient?_count=1&_page_token=AUAcb7bUcVAqcd...
```

### Best Practices

1. Always specify `_count` to control page size
2. Store the complete `_page_token` for subsequent requests
3. Handle cases where `next` link might not be present (last page)
4. Don't modify other query parameters while paginating
5. Page tokens are opaque and should not be modified


### Implementation Example


```javascript
async function fetchAllPatients() {
    let url = '[base]/Patient?_count=100';
    let allResults = [];
    
    while (url) {
        const response = await fetch(url);
        const data = await response.json();
        
        // Add results to collection
        allResults = allResults.concat(data.entry || []);
        
        // Find next page URL
        const nextLink = data.link.find(link => link.relation === 'next');
        url = nextLink ? nextLink.url : null;
    }
    
    return allResults;
}
```

### Common Pagination Scenarios

#### Large Dataset Navigation


```http
# First page
GET [base]/Patient?_count=100

# Use next link from response for subsequent pages
GET [base]/Patient?_count=100&_page_token=[token]
```

#### Filtered Results with Pagination


```http
# First page of filtered results
GET [base]/Patient?_count=50&name=Smith

# Subsequent pages maintain filters
GET [base]/Patient?_count=50&name=Smith&_page_token=[token]
```