# Federation intro

> Your domain model lives in your workspace and your data stays in the systems that hold it. Folio reads each source through a mapping when a query asks, and nothing is copied.

Source: https://semvia.io/docs/federation/intro

Folio keeps your domain model in your workspace and leaves your data where it lives. A mapping dictates which records in a source become which entities in your domain model, and each query reads those records from the source when it runs. Reading data in place like this is federation.

## Your domain model and your data

A knowledge graph can be broadly broken down into two parts:

- **The domain model** defines the things your domain has and how they relate: the classes, such as a power plant and its subclass solar installation, their properties, such as capacity and operator, and the taxonomies you file them under.
- **The data** states what is true of each individual thing: that the Desert Ridge plant is a solar installation, that its capacity is 240 MW, that a given company operates it.

The domain model is relatively small and changes when your understanding of the domain changes. The data is large, changes every day, and already lives in the systems your organization runs on: databases, APIs and data lakes.

Folio is where you and your agents build the domain model together, as files in your workspace, and connect it to the systems that hold the data. A question, from you or an agent, is asked of the domain model. Folio passes it on to the systems that hold the records it needs and answers from what they return, so one query can join records across many sources. Nothing is copied into the workspace, so an answer is never older than its source.

## The components of federation

Federation has three components: classes, sources and mappings.

- **Classes** are the kinds of things in your domain model, with the properties each one has. They live in your workspace. `PowerPlant` is a class with a name, a capacity and a grid region, among other properties.
- **Sources** are where the records live, such as a database table, an API response or a CSV file. A source defines where its records are and how to read them, and a source that signs in also needs a credential. `asset-register.csv` and `grid-connections.csv` are two sources.
- **Mappings** dictate which records become which entities: the class each record becomes and the property each field fills. They're written in [RML](https://rml.io/specs/rml/). `AssetMap` turns each row of the asset register into a `PowerPlant` with its name and capacity, and `ConnectionMap` adds the grid region to the same plant, because both identify a plant by its `plant_id`.

Figure: mappings.ttl in Graph View. Two CSV files, data/grid-connections.csv and data/asset-register.csv, each have an edge from a logical source, connections and assets. ConnectionMap reads connections and maps grid_region to gridRegion. AssetMap reads assets and maps capacity_mw to capacityMW and plant_name to name. Both maps build each row's subject from its plant_id as a Power plant, and the Power plant node, marked Class Schema, lists its instance properties, from capacity (MW) to point of interconnection.

`mappings.ttl` in Graph View: two CSV files, each read through its own mapping into the `PowerPlant` class.

## Connecting a source

- [Query a JSON API](https://semvia.io/docs/federation/query-a-json-api) describes a web API and maps its JSON responses.
- [Query CSV, Parquet and Excel files](https://semvia.io/docs/federation/query-data-files) maps the rows of CSV, Parquet and Excel files, in your workspace or at a URL.
- [Query a database](https://semvia.io/docs/federation/query-a-database) maps the tables of a database.
- [Add credentials](https://semvia.io/docs/federation/credentials) signs a source in without writing a secret into a file.
