tablefaker

name	tablefaker
description	Generate YAML configs for Tablefaker to create synthetic datasets with tables, relationships, and faker data.

Skill: Tablefaker YAML Generator

Purpose

Help an agent generate valid Tablefaker YAML configurations that follow the actual runtime behavior and schema constraints.

Inputs

• User intent and domain (tables, relationships, volumes, locales)
• Optional constraints: determinism, distributions, plugin usage, LLM options

Outputs

• YAML config (version 1) suitable for Tablefaker
• Short usage notes if requested

Core Constraints

• Parent tables must be defined before child tables.
• Each table needs table_name and columns. Each column needs column_name and data.
• is_primary_key: true columns cannot use null_percentage.
• data: auto only works when config.infer_entity_attrs_by_name is true.
• Community providers use the format module(ClassName).
• Optional export_file_name field controls exported filename (without extension); when chunked exports, files are named {export_file_name}_1.ext, {export_file_name}_2.ext, etc.
• Optional parquet_type column attribute sets the explicit Parquet/Arrow type when exporting to parquet. Silently ignored for other export formats. Supported values: int8, int16, int32, int64, uint8–uint64, float16/float32/float64, double, string/utf8, large_string, binary, large_binary, bool/boolean, date32, date64, timestamp[s/ms/us/ns], time32[s/ms], time64[us/ns], decimal128(precision, scale). Can coexist with type (which controls the pandas dtype); they are independent.

Schema Cheat Sheet

version: 1
config:
  locale: en_US
  seed: 123
  infer_entity_attrs_by_name: true
  python_import:
    - some_module
  community_providers:
    - faker_education(SchoolProvider)

tables:
  - table_name: example
    row_count: 100
    start_row_id: 1
    export_file_count: 1
    export_file_row_count: 100
    export_file_name: custom_output
    columns:
      - column_name: id
        data: row_id
        is_primary_key: true
      - column_name: name
        data: fake.name()
        type: string
      - column_name: salary
        data: random.uniform(40000, 120000)
        parquet_type: decimal128(10, 2)   # only applied when exporting to parquet
      - column_name: age
        data: random.randint(18, 65)
        parquet_type: int32
      - column_name: created_at
        data: datetime.today().strftime('%Y-%m-%d')

Patterns and Examples

Basic table with faker fields

tables:
  - table_name: person
    row_count: 10
    columns:
      - column_name: id
        data: row_id
        is_primary_key: true
      - column_name: first_name
        data: fake.first_name()
      - column_name: last_name
        data: fake.last_name()
      - column_name: full_name
        data: first_name + " " + last_name

Foreign key relationship

tables:
  - table_name: customers
    row_count: 10
    columns:
      - column_name: customer_id
        data: row_id
        is_primary_key: true
      - column_name: email
        data: fake.email()
  - table_name: orders
    row_count: 50
    columns:
      - column_name: order_id
        data: row_id
        is_primary_key: true
      - column_name: customer_id
        data: foreign_key("customers", "customer_id")
      - column_name: customer_email
        data: copy_from_fk("customers", "customer_id", "email")

Foreign key distributions

  - table_name: orders_zipf
    row_count: 1000
    columns:
      - column_name: order_id
        data: row_id
        is_primary_key: true
      - column_name: customer_id
        data: foreign_key("customers", "customer_id", distribution="zipf", param=1.1)

  - table_name: orders_weighted
    row_count: 3000
    columns:
      - column_name: order_id
        data: row_id
        is_primary_key: true
      - column_name: customer_id
        data: foreign_key(
          "customers",
          "customer_id",
          distribution="weighted_parent",
          parent_attr="rating",
          weights={"5": 3, "4": 2, "3": 1}
        )

Unique foreign key (one-to-one relationship)

  - table_name: managers
    row_count: 20
    columns:
      - column_name: manager_id
        data: row_id
        is_primary_key: true
      - column_name: dept_id
        data: foreign_key("departments", "dept_id", is_unique=True)

When is_unique=True, each parent key value is selected at most once per child table, enforcing a one-to-one relationship. The child table's row_count must not exceed the parent table's row count.

Automatic attribute inference (data: auto)

config:
  infer_entity_attrs_by_name: true

tables:
  - table_name: customers
    columns:
      - column_name: customer_id
        data: row_id
        is_primary_key: true
      - column_name: email
        data: fake.email()
  - table_name: orders
    columns:
      - column_name: customer_id
        data: foreign_key("customers", "customer_id")
      - column_name: customer_email
        data: auto

Plugins and python_import

If you need custom logic, expose functions in a module and import it.

config:
  python_import:
    - my_plugin

tables:
  - table_name: child
    row_count: 5
    columns:
      - column_name: parent_count
        data: my_plugin.get_parent_count(get_table)

Agent Guidance

• Prefer short, readable data expressions; use a block (|) only when needed.
• Keep naming consistent to enable data: auto inference.
• Validate that FK parent tables appear earlier in the YAML.
• For reproducibility, set config.seed.