# Core concepts

## The graph

```
Species ──< Card >── Set ── Series
              │
              └──< Printing ── prices, marketplace IDs, links
```

- **Species**: a Pokémon, by National Pokédex number (`nationalDex: 6`) or slug (`charizard`). It has **forms** (regional, Mega, Gigantamax) with types, stats and abilities, an **evolution line**, and its **cards**.
- **Set**: an expansion or promo set. `code` is our ID, e.g. `sv03.5` (151) or `me03` (Perfect Order).
- **Card**: a card as printed in one set: attacks, HP, rarity, illustrator, rules text. `code` is `<set code>-<number>`, e.g. `sv03.5-006`. Each card links to the species on it (`species`); tag-team cards link several, and `cameo: true` marks Pokémon that only appear in the artwork.
- **Printing**: one collectible variant of a card (normal, reverse holo, holo, 1st Edition, stamped, Poké Ball pattern…). Prices and marketplace IDs live here, because that's the unit people buy and sell.

## Regions and languages

- `region: INTERNATIONAL` sets are printed in English and European languages, and share one card list across those languages. `localizedNames` and `name(locale: "fr")` give the translations.
- `region: ASIA` sets are the Japanese, Korean, Chinese, Indonesian and Thai releases, which have their own set lists. Their codes start with `asia:`, e.g. `asia:SV2a` and `asia:SV2a-006`.
- `Set.digital` is `true` for Pokémon TCG Pocket (app-only cards with no physical printing or price).

## Lists and pagination

List fields (`cards`, `sets`, `speciesList`, `sealedProducts`, `Set.cards`, `Species.cards`) are cursor-paginated connections: ask for `first` (default 25, at most 100), and pass `pageInfo.endCursor` back as `after`:

```graphql
{
  cards(filter: { nationalDex: 25, region: INTERNATIONAL }, first: 50) {
    nodes { code name set { name } }
    pageInfo { hasNextPage endCursor }
  }
}
```

`cards(filter:)` accepts `name`, `setCode`, `region`, `supertype` (POKEMON, TRAINER, ENERGY), `nationalDex`, `type`, `rarity`, `illustrator`, `regulationMark`, `standardLegal` and `digital`; all given filters must match. `orderBy` is `RELEASE_DATE_DESC` (default), `RELEASE_DATE_ASC` or `NAME`.

## Global IDs

Every Card, Set, Species, Printing and SealedProduct also has an opaque `id` you can fetch with `node(id:)`. Prefer `code` / `nationalDex` in your own data: they're readable and stable.