Seed data and sample files¶

PyCharter can populate the SQL contract store (and related tables) from YAML files in a seed directory.

Default bundled seed¶

After pycharter db init, run:

pycharter db seed

With no arguments, the CLI loads YAML from the data/seed directory inside the installed pycharter package. In a source checkout, that directory is:

src/pycharter/data/seed/

It includes reference entities (owners, domains, systems, environments, data feeds, compliance frameworks, tags), contract artifacts, pipeline configs, and semantic-layer seed files (contracts.yaml, json_schemas.yaml, ontologies.yaml, etc.), in dependency order.

Seeded examples¶

Each example lives in its own directory under data/seed/examples/<name>/ with a manifest.yaml that declares every file the loader processes for that example (reference data, contracts, a concept_scheme.yaml, optional pipeline/streaming configs). Examples are auto-discovered — any directory containing a manifest.yaml is picked up by pycharter db seed, in sorted-by-name order. Shipped examples include ecommerce, trading_domain, the streaming-* set, and support_desk (a minimal support-desk knowledge base: a concept scheme plus one ticket contract whose fields bind to those concepts).

A minimal example needs only:

data/seed/examples/<name>/
  manifest.yaml          # name, description, extraction.scheme_id, sources.contracts, concept_scheme
  concept_scheme.yaml    # kind: ConceptScheme, metadata.name == extraction.scheme_id
  contracts/<x>.yaml     # >= 1 contract with a json_schema block

How seeded data is designated¶

Seeded example rows are attributable via the audit field created_by = "seed:<example>" (e.g. seed:ecommerce, seed:support_desk):

Concepts and concept schemes — stamped by the vocabulary loader (ingest_vocabulary(author="seed:<name>")).
Contracts — stamped by the contract seed loader (created_by / updated_by on the data_contracts row).

This makes seeded example data queryable across the concept and contract tables, e.g. SELECT * FROM concepts WHERE created_by LIKE 'seed:%'. Shared reference/lookup rows (owners, domains, systems, environments, data feeds, tags, compliance frameworks) have no created_by column and are therefore not marked — they are shared across examples rather than owned by one. Contracts are additionally segregated by metadata.namespace (set to the example name).

Standalone example scripts (not part of `pycharter db seed`)¶

examples/ at the repository root holds self-contained, runnable scripts that build their own throwaway database rather than seeding a shared one — useful for demos and walkthroughs. See Flywheel walkthrough for examples/flywheel_demo/, which runs the discover → suggest → accept → bake contribution flywheel end to end.

Custom seed directory¶

Point at any directory that follows the same layout (see files under src/pycharter/data/seed/ for examples):

pycharter db seed /path/to/my_seed
pycharter db seed /path/to/my_seed postgresql://user:pass@localhost/pycharter

If the first positional argument looks like a database URL, the CLI treats it as the connection string and uses the default seed path (see pycharter.db.seed.cmd_seed).

`data/aviation_examples/` (repository samples)¶

The data/aviation_examples/ folder at the repository root holds additional on-disk sample contracts and related artifacts used in tutorials and demos. They are not part of pycharter db seed and are not copied into the PyPI wheel.

Load them through the Web UI (contract import) or the REST API when you want those scenarios in your database.

pycharter db init — create or migrate schema (Alembic)
pycharter db truncate --force — clear data (use with care)