Getting Started

Getting Started

Start with generate_from_schema when you already know the expected table structure.

from great_generator import generate_from_schema

schema = "customer_id int, customer_name string, email string"
df = generate_from_schema(schema, rows=1000)

Optional: using an advisor

Advisors are opt-in. The default is advisor="none", which makes no model calls.

from great_generator import generate_from_schema, infer_generation_plan

plan = infer_generation_plan("customer_id int, customer_name string", advisor="none")
df = generate_from_schema("customer_id int, customer_name string", rows=100, plan=plan)

Use advisors to create editable plans or column tags before generation. Generation remains deterministic because it consumes the saved plan.

Optional: query-aware generation

By default, Great Generator generates data using the existing schema-based behavior. Query-aware options are only used when you provide them.

Use query-aware generation when your SQL query expects specific filter values or partition dates.

from great_generator import generate_from_schema

schema = """
member_id string,
business_date date,
region string,
product_type string,
member_status string,
interaction_count int,
balance double
"""

df = generate_from_schema(
    schema=schema,
    rows=1_000_000,
    required_values={
        "region": ["SOUTH"],
        "product_type": ["CHECKING", "SAVINGS"],
        "member_status": ["ACTIVE"],
    },
    partition_by={
        "column": "business_date",
        "values": ["2026-01-01", "2026-01-02", "2026-01-03"],
        "distribution": "balanced",
    },
    seed=42,
)

This ensures that the generated data includes the values SOUTH, CHECKING, SAVINGS, and ACTIVE, and that rows are generated for each listed business_date.

Other generated values can still appear. The purpose is not to restrict the column to only those values. The purpose is to make sure the values needed by your query exist in the generated data.