# dataset-generator: LLM written specs, Faker filled rows, Metabase one click away

> The Metabase AI Dataset Generator turns a business type into a data specification with a language model and then fills unlimited rows locally with Faker, so CSV and SQL exports cost nothing after a single preview. It is a demo and learning tool, not a data pipeline, and it needs an API key to produce its first schema.

**metabase/dataset-generator** — AI Dataset Generator – Create realistic datasets for demos, learning, and dashboards

- Repository: https://github.com/metabase/dataset-generator
- Website: https://www.metabase.com/ai-data-generator
- Stars: 765 · Forks: 48
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/metabase-dataset-generator

## The problem is a believable dataset, not a random table

Demos, tutorials and dashboard exercises all need the same thing: data that looks like a business, with columns that relate to each other, values that fall in plausible ranges and a shape that a chart can be built on. Random rows of names and numbers do not do this. A table where the order date precedes the shipping date, where the price scales with the product tier and where the event stream has a sensible frequency does.

That is what this project, published by Metabase as dataset-generator, tries to produce. The README states the goal plainly: generate realistic datasets for demos, learning and dashboards, preview them in the browser, export them as CSV or SQL, and explore them with Metabase. The audience is anyone who has to show a chart before the real database exists, and the hosted version at metabase.com/ai-data-generator exists so you can try it before setting anything up.

The scope is worth stating early. There is no ingestion, no scheduling and no connection to a production source. This is a data generator with a web front end, and its output is a file you download and load somewhere else, most often into Metabase.

## Two stages: a model writes the spec, Faker writes the rows

The design decision that makes the tool affordable is that the language model is used once, not once per row. The first stage asks the model for a detailed data specification based on the chosen business type and parameters, and that spec contains the schema, the business rules and the event logic. The second stage takes that spec and generates the actual rows locally with Faker, the JavaScript data generation library.

The cost table in the documentation makes the split visible. A preview calls the model, costs roughly 0.05 dollars with GPT-4o, and produces ten rows. A CSV download makes no model call, costs nothing, and produces a hundred rows or more. A SQL download behaves the same way. The note under the table says those figures come from testing with OpenAI GPT-4o and that costs and token usage vary with other providers and models, so the number is a scale marker rather than a promise.

The practical consequence is that you pay once per distinct dataset shape and then generate volume for free. If you need a thousand rows of the same schema, the second thousand cost nothing and take no time, which is the opposite of the naive approach of asking a model for rows directly.

## The spec is cached, so the second preview of the same shape is free

Because the expensive artefact is the specification and not the rows, the app remembers it. After the first preview the data structure is stored, and previewing the same business type with the same settings reuses that structure instead of calling the model again. The documentation says you see a Using cached spec message in the terminal when this happens, which is a nice touch, since it tells you the request was not billed rather than leaving you to guess.

The cache is inspectable and clearable over HTTP, with two endpoints documented: `curl http://localhost:3000/api/cache/stats` returns the cache statistics, and `curl -X DELETE http://localhost:3000/api/cache/clear` empties it. These are local development endpoints on the app's own port, which is worth keeping in mind before exposing the app on a network, and the project does not describe any authentication in front of them.

The repository also ships a set of script based checks that target exactly this machinery, since the npm scripts include test:cache, test:schemas, test:api-cache and test:rate-limit, with test:all chaining all four together. That the cache and the rate limit have dedicated tests says something about where the author expected trouble.

## Running it locally: an API key, two npm commands and a browser

The prerequisites are Node.js 18 or later, an OpenAI API key, and optionally Docker for the Metabase and LiteLLM pieces. The setup is short. Copy the environment file into place and fill in the key.

```env
LITELLM_MASTER_KEY=sk-1234
LITELLM_SALT_KEY=sk-1234
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_GENAI_API_KEY=
AZURE_API_BASE=
LLM_ENDPOINT=http://localhost:4000
LLM_MODEL=gpt-4o
```

Then install the dependencies and start the Next.js development server.

```bash
   npm install
   npm run dev
```

The app is at http://localhost:3000. From there the flow is: describe the dataset in the prompt builder, click Preview Data to get the ten row sample, then download the CSV or SQL export, or start Metabase to look at it. The Dockerfile is minimal in the same way, a node:20-alpine image that installs dependencies, exposes port 3000 and runs the dev script, so the app is straightforward to containerise on its own if you want it somewhere other than a laptop.

The package manifest marks the project private at version 0.1.0, so this is an application to clone and run rather than a library to depend on.

## One click Metabase means two Postgres instances and a container you start on demand

The interesting part of the local setup is that the Start Metabase button orchestrates Docker from inside the app, with API routes for starting, stopping and checking the status of the Metabase container. The compose file carries more than Metabase itself, since there are two Postgres 15 services, one named db_metabase on host port 5434 and another named db_litellm on port 5433, each with its own healthcheck that runs pg_isready and its own named volume.

Metabase runs from the metabase/metabase:latest image on port 3001, configured against db_metabase with the standard MB_DB_TYPE, MB_DB_DBNAME, MB_DB_PORT, MB_DB_USER, MB_DB_PASS and MB_DB_HOST variables, and it waits for the database to report healthy before starting. When you are finished, the Stop Metabase button shuts the containers down and cleans them up.

Two details deserve a second look. The image is tagged latest, so a compose pull can change what you run without any change in your files, and the databases are started with the postgres user and the postgres password, which is fine for a laptop and not something to carry further. The exported data itself is not loaded by this arrangement: the documentation points you at the Metabase upload feature for the CSV files, or at connecting to your own database, and the compose file mentions an Upload Data feature link and a database connection link for exactly that.

## LiteLLM turns one OpenAI key into a choice of providers

Out of the box the app talks to OpenAI directly. The optional path is a LiteLLM gateway running in Docker, which the documentation describes as the multi-provider route for Anthropic, Google and others, with the compose file pulling ghcr.io/berriai/litellm:main-stable on port 4000 and mounting a litellm-config.yaml as its config, started with a config path, a port and a worker count of 8.

You bring it up with the two services it needs.

```bash
   docker compose up litellm db_litellm
```

The keys for the extra providers go in the same environment file, alongside a master key and a salt key for the gateway, and the model is selected with LLM_MODEL, with the documented example naming a Claude model. Once the gateway is up, the app detects it and routes its requests through it instead of going straight to OpenAI, so the code path is the same for the user either way.

That detection is automatic rather than configured, which is convenient and slightly opaque. It also means the local and hosted versions behave differently: the documentation states that on the web the app defaults to OpenAI and redirects to Metabase Cloud for exploration, while locally you can bring up Metabase in Docker yourself.

## Adding a business type means editing four files by hand

The extension path is the part that tells you how this project is built, and it is not a plugin system. Adding a business type means updating several places. The first is lib/spec-prompts.ts, where entries are added to the businessTypeInstructions object with the business model requirements and pricing structure, the required fields and business logic, and the event types with their frequencies.

The second is the constants file, where realistic numeric ranges and default values are registered.

```typescript
   // Add to NUMERIC_FIELD_RANGES array
   { field: "your_field", min: 100, max: 1000 },

   // Add to DEFAULT_VALUES object
   your_field: ["option1", "option2", "option3"],

   // Add to REQUIRED_FIELDS_BY_BUSINESS_TYPE
   "Your Business Type": ["required_field1", "required_field2", "event_type"],
```

The third is the enforcer, where business specific validation is added so the generated records obey the rules the model described.

```typescript
   public enforceYourBusinessRules(record: DataRecord): void {
     // Add validation logic for your business type
     // e.g., ensure realistic pricing, date relationships, etc.
   }
```

The fourth is the data factory, which has to call the new enforcer. The enforcer step is the one that makes the difference between a table that looks right and a table that is right, since it is where the model written rules are turned into something the generator actually obeys. It is also a lot of work per new business type, which is the practical limit on how many scenarios this tool covers out of the box.

## MIT licensed, no tagged releases, and a dependency on a provider being reachable

The licence is MIT and the project is not archived, with the last push on 2026-10-19. It has no GitHub releases, so there is no versioned artefact to download and no changelog to read before an update. The package is private, so the working copy is the distribution, which is consistent with a tool meant to be cloned and run against your own key.

Two operational realities bound what this tool can do. The first is that the first step of every new dataset shape needs a model provider, so an offline machine can generate rows for a specification it already has but cannot invent a new schema, and the LiteLLM route still needs keys for whichever provider you point it at. The second is the cost of that first call, which the documentation puts at roughly 0.05 dollars per preview with GPT-4o.

There is also a rate limit dependency in the manifest, listed alongside a limit package, and a dedicated test script for it, which suggests the app throttles its own calls to the model. The application code is split the way you would expect from the file list: the prompt builder and page live in app/page.tsx, the generator is app/api/generate/route.ts, the export logic is in lib/export, the Docker orchestration routes live under app/api/metabase, and the shared compose file covers both Metabase and LiteLLM.

## Conclusion

Adopt dataset-generator when you need a believable dataset for a demo, a tutorial or a dashboard exercise and you want the schema to come from a model rather than from a hand written spec, since the export step is free and instant once a preview has been cached. Do not adopt it as a data pipeline component, because every new business type needs the spec prompt, the constants and the validation rules edited by hand, and the first preview still depends on an LLM provider being reachable. Before you build on it, run the four npm test scripts, since the project ships checks for the cache, the schemas, the cache API and the rate limit, and pin the Metabase image tag in docker-compose.yml rather than tracking latest.

## FAQ

### How does the Metabase dataset generator produce realistic data?

It works in two stages. A language model writes a detailed data specification, including schema, business rules and event logic, for the business type you picked, and then the rows themselves are generated locally with Faker. The model is only used for the specification, so the export step costs nothing.

### How much does generating a dataset cost?

The documentation table puts the preview, which produces ten rows, at roughly 0.05 dollars with OpenAI GPT-4o, and both CSV and SQL downloads at no cost for a hundred rows or more. The note adds that costs and token usage vary with other providers and models.

### How do I run the dataset generator locally?

You need Node.js 18 or later and an OpenAI API key, and Docker if you want the local Metabase and LiteLLM services. Put the key in a .env file in the project root, then run npm install and npm run dev, and open http://localhost:3000.

### Can I use another LLM provider instead of OpenAI?

Yes. Start the LiteLLM gateway with docker compose up litellm db_litellm, add the provider keys to your .env file, and set LLM_MODEL to the model you want. When LiteLLM is running, the app detects it and routes requests through the gateway instead of calling OpenAI directly.

### How do I add a new business type to the dataset generator?

You edit four places: the businessTypeInstructions entries in lib/spec-prompts.ts, the numeric ranges and default values in the business constants file, a validation method in lib/enforcers/data-enforcer.ts, and lib/data-factory.ts so the new enforcer is called.

## Sources

- [Issues](https://github.com/metabase/dataset-generator/issues)
- [License: MIT](https://github.com/metabase/dataset-generator/blob/main/LICENSE)
- [metabase/dataset-generator on GitHub](https://github.com/metabase/dataset-generator)
- [Project website](https://www.metabase.com/ai-data-generator)
- [README](https://github.com/metabase/dataset-generator/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/metabase-dataset-generator