# Field Types Reference

Complete reference for all AtomIngest field types.

## Table of Contents
- [String Fields](#string-fields)
- [Numeric Fields](#numeric-fields)
- [Date & Time Fields](#date--time-fields)
- [Boolean Field](#boolean-field)
- [Structured Data Fields](#structured-data-fields)
- [Encrypted Fields](#encrypted-fields)
- [Field Options](#field-options)

## String Fields

### CharField
Fixed-length character field.

**SQL Type:** VARCHAR

**Options:**
- `max_length` (int, required): Maximum string length
- `nullable` (bool): Allow None (default: true)
- `unique` (bool): Enforce uniqueness (default: false)
- `default` (str): Default value

**YAML:**
```yaml
username:
  type: CharField
  max_length: 50
  nullable: false
  unique: true
```

**Python:**
```python
from atomsql.orm import fields

class User(Model):
    username = fields.CharField(max_length=50, nullable=False, unique=True)
```

### StringField
Alias for CharField.

**YAML:**
```yaml
title:
  type: StringField
  nullable: false
```

### TextField
Unlimited-length text field.

**SQL Type:** TEXT

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (str): Default value

**YAML:**
```yaml
description:
  type: TextField
  nullable: true
```

**Python:**
```python
description = fields.TextField(nullable=True)
```

### EmailField
Email address with validation.

**SQL Type:** VARCHAR(255)

**Built-in Validation:** Email format regex

**YAML:**
```yaml
email:
  type: EmailField
  unique: true
  validation:
    - type: email_format
```

**Python:**
```python
email = fields.EmailField(unique=True)
```

### URLField
URL with validation.

**SQL Type:** TEXT

**Built-in Validation:** URL format regex

**YAML:**
```yaml
website:
  type: URLField
  nullable: true
```

**Python:**
```python
website = fields.URLField(nullable=True)
```

## Numeric Fields

### IntegerField
Integer numbers.

**SQL Type:** INTEGER

**Options:**
- `nullable` (bool): Allow None (default: true)
- `unique` (bool): Enforce uniqueness (default: false)
- `default` (int): Default value

**YAML:**
```yaml
age:
  type: IntegerField
  nullable: false
  validation:
    - type: range
      min: 0
      max: 150
```

**Python:**
```python
age = fields.IntegerField(nullable=False)
```

**Range:** -2,147,483,648 to 2,147,483,647 (32-bit)

### FloatField
Floating-point decimal numbers.

**SQL Type:** REAL / DOUBLE

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (float): Default value

**YAML:**
```yaml
price:
  type: FloatField
  nullable: false
  validation:
    - type: range
      min: 0.0
```

**Python:**
```python
price = fields.FloatField(nullable=False)
```

**Precision:** Double precision (15-17 decimal digits)

**Note:** For exact decimal arithmetic (financial calculations), store as integers (cents) or use string fields.

## Date & Time Fields

### DateField
Date without time component.

**SQL Type:** DATE

**Format:** YYYY-MM-DD

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (date): Default value

**YAML:**
```yaml
birth_date:
  type: DateField
  nullable: true
```

**Python:**
```python
from datetime import date

birth_date = fields.DateField(nullable=True)

# Usage
user.birth_date = date(1990, 1, 15)
```

### DateTimeField
Date and time without timezone.

**SQL Type:** DATETIME / TIMESTAMP

**Format:** YYYY-MM-DD HH:MM:SS

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (datetime): Default value

**YAML:**
```yaml
created_at:
  type: DateTimeField
  nullable: false
```

**Python:**
```python
from datetime import datetime

created_at = fields.DateTimeField(nullable=False)

# Usage
user.created_at = datetime.now()
```

### DateTimeTZField
Date and time with timezone awareness.

**SQL Type:** TIMESTAMP WITH TIME ZONE

**Format:** YYYY-MM-DD HH:MM:SS+TZ

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (datetime): Default value

**YAML:**
```yaml
transaction_time:
  type: DateTimeTZField
  nullable: false
```

**Python:**
```python
from datetime import datetime, timezone

transaction_time = fields.DateTimeTZField(nullable=False)

# Usage
user.transaction_time = datetime.now(timezone.utc)
```

### TimeStampField
Unix timestamp (seconds since epoch).

**SQL Type:** INTEGER

**Format:** Unix timestamp (seconds)

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (int): Default value

**YAML:**
```yaml
event_timestamp:
  type: TimestampField
  nullable: false
```

**Python:**
```python
import time

event_timestamp = fields.TimeStampField(nullable=False)

# Usage
user.event_timestamp = int(time.time())
```

## Boolean Field

### BooleanField
True/False values.

**SQL Type:** BOOLEAN / INTEGER (0/1)

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (bool): Default value

**YAML:**
```yaml
is_active:
  type: BooleanField
  default: true
```

**Python:**
```python
is_active = fields.BooleanField(default=True)

# Usage
user.is_active = True
```

**Accepted Values (CSV/JSON):**
- True: `"true"`, `"True"`, `"1"`, `"yes"`, `"Yes"`
- False: `"false"`, `"False"`, `"0"`, `"no"`, `"No"`

## Structured Data Fields

### JSONField
Stores JSON objects.

**SQL Type:** TEXT

**Serialization:** Automatic JSON encoding/decoding

**Options:**
- `nullable` (bool): Allow None (default: true)
- `default` (dict): Default value

**YAML:**
```yaml
metadata:
  type: JSONField
  nullable: true
```

**Python:**
```python
metadata = fields.JSONField(nullable=True)

# Usage
user.metadata = {
    "preferences": {"theme": "dark"},
    "settings": {"notifications": True}
}

# Stored as: '{"preferences":{"theme":"dark"},...}'
```

### UUIDField
Universally unique identifiers.

**SQL Type:** VARCHAR(36) or UUID

**Format:** 8-4-4-4-12 hex digits (e.g., `550e8400-e29b-41d4-a716-446655440000`)

**Options:**
- `nullable` (bool): Allow None (default: true)
- `unique` (bool): Enforce uniqueness (default: false)
- `default`: Default value

**YAML:**
```yaml
transaction_id:
  type: UUIDField
  unique: true
  nullable: false
```

**Python:**
```python
import uuid

transaction_id = fields.UUIDField(unique=True, nullable=False)

# Usage
user.transaction_id = uuid.uuid4()
```

## Encrypted Fields

All encrypted fields require `key_id` configuration.

### EncryptedStringField
Encrypted variable-length string.

**SQL Type:** TEXT (stores encrypted ciphertext)

**Options:**
- `key_id` (str, required): Encryption key identifier
- `nullable` (bool): Allow None (default: true)

**YAML:**
```yaml
ssn:
  type: EncryptedStringField
  key_id: "pii_encryption_key"
  nullable: false
```

**Python:**
```python
# Auto-decrypts on access
user = User.objects().get(id=1)
print(user.ssn)  # "123-45-6789" (decrypted)

# Stored in DB: "gAAAAABhkO5X..." (encrypted)
```

### EncryptedCharField
Encrypted fixed-length string.

**SQL Type:** TEXT

**Options:**
- `key_id` (str, required): Encryption key identifier
- `max_length` (int): Maximum plaintext length
- `nullable` (bool): Allow None (default: true)

**YAML:**
```yaml
credit_card:
  type: EncryptedCharField
  max_length: 255
  key_id: "payment_encryption_key"
```

### EncryptedTextField
Encrypted unlimited-length text.

**SQL Type:** TEXT

**Options:**
- `key_id` (str, required): Encryption key identifier
- `nullable` (bool): Allow None (default: true)

**YAML:**
```yaml
medical_notes:
  type: EncryptedTextField
  key_id: "medical_data_key"
```

### EncryptedEmailField
Encrypted email address.

**SQL Type:** TEXT

**Options:**
- `key_id` (str, required): Encryption key identifier
- `nullable` (bool): Allow None (default: true)

**YAML:**
```yaml
private_email:
  type: EncryptedEmailField
  key_id: "email_encryption_key"
```

### EncryptedJSONField
Encrypted JSON data.

**SQL Type:** TEXT

**Options:**
- `key_id` (str, required): Encryption key identifier
- `nullable` (bool): Allow None (default: true)

**YAML:**
```yaml
sensitive_metadata:
  type: EncryptedJSONField
  key_id: "metadata_encryption_key"
```

**Python:**
```python
# Access as normal dict (auto-decrypted)
user.sensitive_metadata = {"api_key": "secret123"}
```

## Field Options

### Common Options

All fields support these options:

#### nullable
Allow None/NULL values.

```yaml
field_name:
  type: FieldType
  nullable: true  # default
```

```python
field_name = fields.FieldType(nullable=True)
```

#### unique
Enforce uniqueness constraint.

```yaml
field_name:
  type: FieldType
  unique: true  # default: false
```

```python
field_name = fields.FieldType(unique=True)
```

#### default
Default value if not provided.

```yaml
status:
  type: CharField
  default: "pending"

quantity:
  type: IntegerField
  default: 0

is_active:
  type: BooleanField
  default: true
```

```python
status = fields.CharField(default="pending")
quantity = fields.IntegerField(default=0)
is_active = fields.BooleanField(default=True)
```

## Type Mapping

### CSV to Python

| CSV Value | Python Type | Notes |
|-----------|-------------|-------|
| "123" | int | When parsed as IntegerField |
| "123.45" | float | When parsed as FloatField |
| "true" | bool | When parsed as BooleanField |
| "2026-01-20" | date | When parsed as DateField |
| "2026-01-20 10:30:00" | datetime | When parsed as DateTimeField |
| '{"key":"value"}' | dict | When parsed as JSONField |

### Python to SQL

| Python Type | SQL Type (SQLite) | SQL Type (PostgreSQL) |
|-------------|-------------------|----------------------|
| str | TEXT | VARCHAR(n) / TEXT |
| int | INTEGER | INTEGER |
| float | REAL | DOUBLE PRECISION |
| bool | INTEGER (0/1) | BOOLEAN |
| date | TEXT | DATE |
| datetime | TEXT | TIMESTAMP |
| dict | TEXT (JSON) | JSONB |
| uuid.UUID | TEXT | UUID |
| bytes | BLOB | BYTEA |

## Validation

Fields can have validation rules:

```yaml
age:
  type: IntegerField
  validation:
    - type: range
      min: 18
      max: 120

email:
  type: EmailField
  validation:
    - type: email_format

password:
  type: CharField
  max_length: 128
  validation:
    - type: length
      min: 8
    - type: regex
      pattern: "^(?=.*[A-Z])(?=.*[0-9])"
```

See [Validation Guide](validation.md) for complete validation reference.

## Complete Example

```yaml
target_table: users

schema:
  # Primary key
  id:
    type: UUIDField
    unique: true
    nullable: false

  # String fields
  username:
    type: CharField
    max_length: 50
    unique: true
    nullable: false

  email:
    type: EmailField
    unique: true
    nullable: false

  bio:
    type: TextField
    nullable: true

  website:
    type: URLField
    nullable: true

  # Numeric fields
  age:
    type: IntegerField
    nullable: true
    validation:
      - type: range
        min: 18
        max: 120

  account_balance:
    type: FloatField
    default: 0.0

  # Date & Time fields
  birth_date:
    type: DateField
    nullable: true

  created_at:
    type: DateTimeField
    nullable: false

  last_login:
    type: DateTimeTZField
    nullable: true

  # Boolean field
  is_active:
    type: BooleanField
    default: true

  # Structured data
  preferences:
    type: JSONField
    nullable: true

  # Encrypted PII
  ssn:
    type: EncryptedStringField
    key_id: "user_pii"

  credit_card:
    type: EncryptedCharField
    max_length: 255
    key_id: "payment_data"
```

## Related Documentation

- [Schema Definition](schema_definition.md) - Complete schema guide
- [Validation](validation.md) - Field validation rules
- [Security](security.md) - Encrypted fields guide

## Quick Reference

| Field Type | Use For | SQL Type | Encrypted |
|------------|---------|----------|-----------|
| CharField | Short text | VARCHAR | No |
| TextField | Long text | TEXT | No |
| EmailField | Email addresses | VARCHAR | No |
| URLField | URLs | TEXT | No |
| IntegerField | Whole numbers | INTEGER | No |
| FloatField | Decimals | REAL/DOUBLE | No |
| DateField | Dates | DATE | No |
| DateTimeField | Timestamps | TIMESTAMP | No |
| DateTimeTZField | TZ timestamps | TIMESTAMPTZ | No |
| TimeStampField | Unix timestamps | INTEGER | No |
| BooleanField | True/False | BOOLEAN | No |
| JSONField | JSON data | TEXT | No |
| UUIDField | UUIDs | UUID/VARCHAR | No |
| EncryptedStringField | PII text | TEXT | Yes |
| EncryptedCharField | PII short text | TEXT | Yes |
| EncryptedTextField | PII long text | TEXT | Yes |
| EncryptedEmailField | PII email | TEXT | Yes |
| EncryptedJSONField | PII JSON | TEXT | Yes |
