# Models 

## What is a model? 

A Model in Gadget represents a data structure that defines the shape of the data stored in the Gadget database (powered by Postgres). It consists of fields, relationships, and validations that can be used to build data models for your application.

Models in Gadget are similar to tables in traditional SQL-based relational databases.

## How models work 

Models operate within the database to define the structure and rules for storing data. Gadget's built-in database is relational, which means it stores data in rows within tables. In Gadget, rows are referred to as records, columns are fields, and tables are models.

## How to create models 

To create a model in the Gadget editor:

1.  Open the `api/models` directory in the file tree.
2.  Add a new model.
3.  Name your model.
4.  Define its fields, relationships, and validations.

If you prefer working locally, you can use [`ggt add`](https://docs.gadget.dev/reference/ggt#ggt-add) to create models from the command line.

### Anatomy of a model 

Fields and relationships can take validations and configurations that define how your model behaves.

[Fields](https://docs.gadget.dev/guides/models/fields) are the individual components within a model that define the attributes or properties of the data being stored. These fields can represent various types of data, such as strings, numbers, dates, or booleans, allowing for flexibility in data representation.

[Validations](https://docs.gadget.dev/guides/models/fields#extending-fields-with-validations-and-configurations) add rules and constraints to fields to ensure the integrity and correctness of your data. You can use them to enforce criteria such as data type, length, presence, uniqueness, or custom conditions.

[Relationships](https://docs.gadget.dev/guides/models/relationships) can then be used to establish connections between different models, enabling the representation of complex associations and dependencies. These relationships can be defined as belongs to, has one, has many, and has many through, providing a structured way to navigate and query related data. By combining fields, validations, and relationships, developers can create robust and organized models that accurately represent and manipulate data within their applications.

### Automatic API generation 

Gadget auto-generates an API for each of your models that enables you to read and write data from the database performantly and securely. Your generated API is a high-level, feature-rich CRUD API that can sort, filter, search, and paginate data from the database. API requests can also easily retrieve related data from other models without having to implement manual joins or use multiple calls.

### Model namespaces 

You can organize related models with [namespaces](https://docs.gadget.dev/guides/models/namespaces). Namespaces are folder-based, so when you place a model inside a folder in `api/models`, Gadget adds that folder name to the matching namespace in your generated API.

## Relationships 

In Gadget, relationships establish connections between models, allowing the representation of complex associations and dependencies. These relationships—belongs to, has one, has many, and has many through—provide a structured way to navigate and query related data, ensuring organized and robust models.

Each model has its own database table, with relationships being **directional**, meaning one model holds a reference to another. The **cardinality** of relationships includes:

*   **One-to-One**: A single record in one model links to a single record in another.
*   **One-to-Many**: A single record in one model relates to multiple records in another.
*   **Many-to-Many**: Multiple records in one model relate to multiple records in another.

Relationships are implemented using belongs to fields, which store the ID of the related record. In a **one-to-many** relationship, the ID of the "one" is stored on the "many" side. For example, in a **Project-Todo** relationship, each **Todo** stores a `project`, referencing its associated **Project**, while the **Project** retrieves its related **Todos** dynamically via the has many, relationship. **Many-to-many** relationships are implemented with a has many through, relationship, where a new model is created to store ids on both sides of the relation.

### Data retrieval 

When fetching data, belongs to fields return full related records instead of just IDs, performing database lookups for related records at read time. The has one or has many fields in the parent model allow dynamic querying of related records.

### Foreign key enforcement 

For performance reasons, Gadget does not enforce foreign key constraints, meaning a belongs to field may reference a record that no longer exists.

This approach ensures **efficient and flexible** model relationships in Gadget.

## Search 

Gadget includes support for an optional full-text search index for each model. If enabled, you can issue [full text search queries](https://docs.gadget.dev/api/example-app/development/sorting-and-filtering#searching) over all your model data using the `search` parameter. This search index is powered by Elasticsearch and automatically maintained by Gadget under the hood.