# dbgen Compatibility Notes

## General Rules

- Prefer synthetic anchors over user example literals
- Keep phone numbers and channels realistic in natural mode
- Preserve join keys exactly

## dbgen 0.8.0 Notes

These notes were validated on a remote bench host using `dbgen 0.8.0`.

### Avoid `BETWEEN`

Use:

- `x >= a AND x <= b`

instead of:

- `x BETWEEN a AND b`

### Avoid `--files-count` with `--total-count`

`dbgen 0.8.0` rejects this combination.

Use either:

- `-N` and `-R`

or:

- explicit file count without total count

### Multi-root templates may not fully materialize

If a single template contains two independent root chains, some environments may only emit one family correctly.

When this happens, split templates by root family, for example:

- `public` chain
- `whatsapp_message`

For very large jobs, go one step further:

- prefer one table per template if a chain-generated template distorts child-table file layout
- reconstruct joinability through shared deterministic formulas instead of nested generation only

### Validate small before large

Always run a small smoke generation first:

- check files created
- check schema files
- inspect first few rows
- inspect row counts per shard

### Protect representative predicates

If the workload includes:

- `LIKE '%094%'`
- `LIKE '%keyword%'`
- exact phone equality

then reserve a small intentional hit slice and avoid accidental overmatching in the rest of the data.

### IMPORT INTO path handling

On the validated TiDB playground workflow here:

- wildcard paths such as `'/data2/ycloud/public.contacts.*.csv'` were more reliable than expanding long explicit file lists in SQL

When many shards exist, prefer wildcard-based import statements unless the environment proves otherwise.

## Modeling Advice

### Natural mode

- hot tenant + medium tenant + tail
- partial inbox reuse
- partial queue history
- sparse but not fixed search hits

### Reproduction-oriented mode

- tighter hit counts
- tighter hot partitioning
- smaller number of hot inboxes
- stronger coupling between query predicate and hit slice