Relational Generation

Relational Generation

Use generate_relational when you need several generated tables with valid primary-key and foreign-key relationships.

from great_generator import generate_relational

data = generate_relational(
    tables={
        "customers": {
            "schema": "customer_id int primary key, customer_name string",
            "rows": 1000,
        },
        "orders": {
            "schema": "order_id int primary key, customer_id int references customers.customer_id",
            "rows": 10000,
        },
    },
    engine="pandas",
)

Query-aware relational generation

For relational data, query-aware generation can ensure required values appear in the correct tables and that fact rows exist for matching dimension values.

This is useful when testing queries that join fact and dimension tables.

from great_generator import generate_relational

tables = {
    "dim_member": {
        "schema": "member_id int primary key, region string, member_status string",
        "rows": 100_000,
    },
    "dim_product": {
        "schema": "product_id int primary key, product_type string",
        "rows": 1_000,
    },
    "fact_interaction": {
        "schema": (
            "interaction_id int primary key, "
            "member_id int references dim_member.member_id, "
            "product_id int references dim_product.product_id, "
            "business_date date, interaction_count int"
        ),
        "rows": 5_000_000,
    },
}

data = generate_relational(
    tables=tables,
    required_values={
        "dim_member.region": ["SOUTH"],
        "dim_product.product_type": ["CHECKING", "SAVINGS"],
        "dim_member.member_status": ["ACTIVE"],
    },
    partition_by={
        "table": "fact_interaction",
        "column": "business_date",
        "values": ["2026-01-01", "2026-01-02", "2026-01-03"],
        "distribution": "balanced",
    },
    ensure_join_coverage=True,
    seed=42,
)

In this example:

• dim_member contains members from the SOUTH region.
• dim_product contains CHECKING and SAVINGS products.
• fact_interaction contains rows for the requested business_date values.
• When ensure_join_coverage=True, matching fact rows are generated for the required dimension values.

This helps test SQL joins and aggregations with synthetic data that actually matches the query filters.

SELECT d.region, p.product_type, SUM(f.interaction_count)
FROM fact_interaction f
JOIN dim_member d ON f.member_id = d.member_id
JOIN dim_product p ON f.product_id = p.product_id
WHERE f.business_date BETWEEN '2026-01-01' AND '2026-01-31'
  AND d.region = 'SOUTH'
  AND p.product_type IN ('CHECKING', 'SAVINGS')
GROUP BY d.region, p.product_type;

Random synthetic data may not contain the values or join paths needed by this query. Query-aware generation lets you specify those values directly.

Default behavior

All query-aware options are optional. Existing generation behavior is unchanged unless you provide required_values, partition_by, target_selectivity, ensure_join_coverage, or query_profile.