Skip to content

data.md

Latest commit

 

History

History
114 lines (86 loc) · 2.88 KB

data.md

File metadata and controls

114 lines (86 loc) · 2.88 KB

Data Seeding Metadata

Data source files allow you to seed the database with initial data. This is useful for lookup tables, configuration, or demo content.

1. Overview

File Naming Convention: <object_name>.data.yml

The filename (without the .data.yml extension) automatically identifies which object to seed data into. This is the recommended approach as it eliminates redundancy.

Examples:

  • status.data.yml → Seeds data into object: status
  • users.data.yml → Seeds data into object: users
  • product_categories.data.yml → Seeds data into object: product_categories

Features:

  • Implicit object mapping: Object name inferred from filename
  • Auto-deduplication: Duplicate key errors are typically ignored (depending on driver implementation), allowing for basic idempotency
  • Order matters: Files loaded alphabetically, so ensure parent data is seeded before child data

2. File Format

Recommended Format: Filename-based (Implicit)

File: status.data.yml

# File: status.data.yml
# Object "status" is inferred from filename!

- code: "draft"
  label: "Draft"
  is_active: true

- code: "published"
  label: "Published"
  is_active: true

- code: "archived"
  label: "Archived"
  is_active: false

File: users.data.yml

# File: users.data.yml
# Object "users" is inferred from filename!

- _id: admin_001
  name: "System Administrator"
  email: "admin@company.com"
  role: "admin"
  is_active: true

- _id: user_001
  name: "John Doe"
  email: "john@company.com"
  role: "user"
  is_active: true

Alternative Format: Explicit Object (Legacy)

For backwards compatibility, you can still explicitly specify the object:

# File: initial_setup.data.yml
# Explicit object specification

object: status
records:
  - code: "draft"
    label: "Draft"
  
  - code: "published"
    label: "Published"

Note: The filename-based approach is preferred as it reduces redundancy and makes file organization clearer.

3. Best Practices

  1. Use Immutable IDs: Provide explicit IDs (_id) to ensure consistent referencing across environments:

    - _id: admin_role_001
  name: "Administrator"
  permissions: ["all"]

  2. Versioning: Include a metadata field if you need to track data versions:

    - code: "feature_x"
  enabled: true
  version: "1.0"

  3. Order Matters: ObjectQL loads data files in alphabetical order. If you have relationships, ensure parent data loads first:

    01_users.data.yml        # Parent data
02_departments.data.yml  # Parent data
03_employees.data.yml    # Child data (references users and departments)

  4. Use Prefix Numbering: For complex dependencies, use numeric prefixes:

    data/
  01_core/
    01_users.data.yml
    02_roles.data.yml
  02_business/
    01_customers.data.yml
    02_orders.data.yml