# Nearest Analysis Worker

Processes nearest neighbor analysis jobs between two datasets.

## Overview

The nearest analysis worker finds the nearest features from a target dataset for each feature in a source dataset.

## Job Type

`nearest`

## Input Parameters

```json
{
  "source_dataset_id": 123,
  "target_dataset_id": 124,
  "max_distance": 5000,
  "limit": 1
}
```

### Parameters

- `source_dataset_id` (required): Source dataset ID
- `target_dataset_id` (required): Target dataset ID
- `max_distance` (optional): Maximum search distance in dataset units
- `limit` (optional): Maximum neighbors per feature (default: 1)

## Output

Creates a new dataset with nearest neighbor results:

- Original source feature geometry
- Nearest target feature information
- Distance to nearest neighbor
- Attributes from both source and target features

## Algorithm

The worker uses PostGIS functions to:

1. For each source feature, find nearest target features
2. Calculate distances using spatial indexes
3. Apply distance and limit constraints
4. Join attributes from both datasets
5. Store results in output table

## Example

```bash
# Enqueue a nearest analysis job via API
curl -X POST "https://example.com/api/nearest_run.php" \
  -H "Content-Type: application/json" \
  -d '{
    "source_dataset_id": 123,
    "target_dataset_id": 124,
    "max_distance": 5000,
    "limit": 1
  }'

# Worker processes the job automatically
```

## Background Jobs

This analysis runs as a background job. The worker:

1. Fetches queued `nearest` jobs
2. Validates input parameters
3. Executes PostGIS nearest neighbor queries
4. Creates output dataset
5. Marks job as completed

## Performance Considerations

- Processing time depends on dataset sizes
- Spatial indexes are critical for performance
- Large max_distance values may slow processing
- Consider limiting results per feature

## Related Documentation

- [Nearest Analysis Tool](../analysis-tools/nearest.md)
- [Analysis API](../api/analysis.md)
- [Workers Overview](index.md)

