> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Import

> Records of import executions that track bulk data ingestion into the system

Import represents an individual execution of an ImportDefinition. Each Import record tracks the status, progress, and metadata of a bulk data import operation.

## Core Purpose

* **Execution Tracking**: Records each run of an import processor
* **Status Management**: Tracks progress from pending to completed/failed
* **Audit Trail**: Links imports to users and organizations
* **Error Handling**: Stores error messages when imports fail

## Entity Structure

```
Import {
  id: "imp-...",
  importDefinitionId: "impdef-...",  // The definition used
  userId: "user-...",                 // Who executed the import
  organizationId: "org-...",          // Organization context
  rowCount: 150,                      // Total rows in source file
  status: "completed",                // pending, processing, completed, failed
  error: null,                        // Error message if failed
  processedAt: "2024-01-15T10:30:00Z" // When processing completed
}
```

## Import Lifecycle

**1. Creation**: Import record created when user initiates an import

**2. Processing**: Status changes to "processing" during execution

**3. Completion**: Status becomes "completed" with processedAt timestamp

**4. Failure**: Status becomes "failed" with error message stored

## Status Values

| Status       | Description                        |
| ------------ | ---------------------------------- |
| `pending`    | Import created but not yet started |
| `processing` | Currently processing rows          |
| `completed`  | Successfully finished              |
| `failed`     | Encountered an error               |

## Relationships

**ImportDefinition**: Each Import uses one ImportDefinition for transformation rules

**User**: Tracks which user initiated the import

**Organization**: Scopes the import to an organization

**ImportResult**: One Import can have many ImportResult records (one per site/period)

## Row Count

The `rowCount` field stores the total number of rows in the source file before processing. This helps track:

* How much data was provided
* Progress during processing
* Comparison with actual results produced

## Error Handling

When an import fails, the error field contains details:

```json theme={null}
{
  "status": "failed",
  "error": "Invalid column mapping: 'consumption' not found in source file"
}
```

Common error scenarios:

* Missing required columns
* Invalid data types
* Processor code errors
* Database constraint violations

## Access Control

* Imports are scoped to organizations via RLS policies
* Users can only see imports from their current organization
* The executing user is recorded but doesn't restrict access

## Querying Imports

**Recent imports for an organization**:

```sql theme={null}
SELECT * FROM "Import"
WHERE "organizationId" = 'org-123'
ORDER BY "createdAt" DESC
LIMIT 10;
```

**Failed imports**:

```sql theme={null}
SELECT * FROM "Import"
WHERE status = 'failed'
  AND "organizationId" = 'org-123';
```

## Related Entities

* [ImportDefinition](/en/concepts/import-definition): Defines the transformation rules
* [ImportResult](/en/concepts/import-result): Per-site results from the import
* [FormElementSubmission](/en/concepts/form-element-submission): Values created by the import