Glossary 

Action 

An Action in Gadget is a unit of work that your application can perform, defining the behavior of the application. Actions are triggered by events such as user interactions, API calls, or webhooks from external systems. They can be either model-specific (Model Actions) or global (Global Actions). Each Action consists of a sequence of Effects that perform the actual work, such as validating inputs, updating records, or interacting with third-party APIs.

Read more about Actions in the Actions guide.

API identifier 

An API identifier in Gadget refers to a unique and distinguishable key assigned to a model or action within a Gadget application's API, allowing for precise invocation and interaction with the application's functionalities. API identifiers can be associated with a model, model-specific actions (which operate within the context of individual records), or global actions (which execute independently of any particular record). These identifiers facilitate seamless integration with external systems, triggers, and third-party services.

Background action 

A background action in Gadget is a model or global action that is enqueued to run at some in the future instead of right away and operates independently of the main application logic. Background actions are useful for long-running tasks that don't need to happen immediately.

Read more about background actions and how to use them in our guide here.

Connection 

A Connection in Gadget is a built-in integration that allows you to retrieve and manipulate data from third-party systems without writing any code. It provides a real-time data sync between your Gadget app's database and the external system, enabling seamless communication and efficient data handling.

Gadget supports a rich connection to Shopify with more to come.

Data Aggregation 

Data aggregation refers to the process of collecting and summarizing data from a dataset to obtain aggregated values, such as counts or sums. In Gadget, there are two strategies for data aggregation: pagination and pre-aggregation. Pagination involves iterating through all records at read time, while pre-aggregation calculates values at write time, improving read performance. Both methods have their advantages and challenges, depending on the specific requirements of your app.

Database 

A database is a structured system for storing, managing, and retrieving data. In Gadget, the built-in database is powered by Postgres and is relational, meaning it stores data in rows within tables. Gadget refers to rows as records and tables as models. You can create models to define the shape of your data and then create records of that model using the API.

Read more about storing data in the Models guide.

Deployment 

Deployment refers to the process of pushing the changes made in the Development environment of your Gadget application to the Production environment, making them available to end users. In Gadget, deploying is done by clicking the Deploy button in the footer of the Gadget editor. This ensures that the finalized and tested changes are shipped to users who access the Production environment.

Read more about deploys in the deployment guide.

Development 

The term Development in Gadget refers to the environment where you make changes, test, and experiment with your application before pushing it to the Production environment. In Gadget, all changes you make in the editor happen in the Development environment by default. This ensures that users won't immediately experience these changes until they are finalized, tested, and deployed to Production. The Development environment has its own domain with the --development suffix in the subdomain, for example: https://example-app--development.gadget.app/api/graphql.

Read more about the Development environment in the deployment guide.

File 

In Gadget, a File refers to any type of data, such as images, audio, PDFs, binary blobs, etc., that can be uploaded and stored within a Gadget application. Files are stored as file fields on a Gadget model and can be accessed using your app's GraphQL API. Gadget securely hosts and stores files in the cloud, with access permissions based on the file's owner records.

Read more about Files in the storing files guide.

Gadget CLI (ggt) 

The Gadget CLI (Command Line Interface), also known as ggt, is a tool that provides additional functionality for working with your Gadget applications using your existing tools on your local machine. It allows you to sync files between your local environment and the Gadget editor, enabling you to use your preferred code editor and implement version control for your Gadget projects.

Read more about the Gadget CLI in the ggt guide.

Gelly 

Gelly is the data access language used in Gadget for advanced features like Filtered Model Permissions. It is a superset of GraphQL, following the same principles of declarative queries returning predictable results. Gelly allows relationship traversal, fragments, and more ergonomic expressions, making it easier to work with than plain SQL. Gadget compiles Gelly into high-performance SQL to execute inside the database with a custom caching layer, ensuring fast and consistent results.

Read more about Gelly in the Gelly guide.

Generated API 

Gadget automatically generates a GraphQL API for each app. As you create models and add fields in Gadget, the platform generates a CRUD (Create, Read, Update, Delete) API for your application, allowing you to quickly test and consume the API immediately after making changes to your models. Gadget also creates API documentation and a type-safe JavaScript client for you to use, all in the background as you work.

The Generated API can be customized and extended to your liking -- you can add and remove fields, change permissions, and change the available queries and mutations to make your API exactly as you like it.

Read more about your generated API in the API Reference.

Generated API Client 

The generated API client is an auto-generated, type-safe JavaScript library provided by Gadget for each application. It simplifies connecting to your app's GraphQL API from a frontend, such as a React app. The API client handles authentication, connectivity, and makes it easy to perform queries and mutations using your app's GraphQL API. To install and use the generated API client, follow the instructions provided in your Gadget app's documentation.

Read more about installing your API client in the API Reference.

Global Action 

Global Actions are Actions that do not operate in the context of a specific record or model. They execute independently of any particular record and are more suitable for tasks that don't involve reading or writing data to or from a specific central record.

Read more about Model Actions in the Actions guide.

HTTP route 

An HTTP route is a combination of a URL pattern and a handler function that gets executed when someone accesses the specified URL on your app's domain. It allows you to run code and perform actions like rendering HTML, sending a JSON response, calling external APIs, or redirecting users based on certain conditions. HTTP Routes are defined as files in the routes folder, with the file name prefixed with the HTTP verb it should handle (e.g., GET-data.js).

Read more about HTTP routes in the HTTP Routes guide.

Internal API 

The Internal API in Gadget is a low-level interface that allows you to make direct changes to the Gadget database without running the Effects of any Action. It can be used safely within Effects by running api.internal.someModel.<action name>. The Internal API is faster and often used for high-volume scripts that need to import data or touch many records quickly. However, it's generally not recommended for use unless you have an explicit reason, as it skips important logic for Actions. Note that the Internal API can only be invoked from the backend.

You can invoke the Internal API in JavaScript with the api.internal object in your backend or frontend:

// uses the internal API to create a post record without running actions
// requires special permissions granted in the Roles and Permissions section
await api.internal.post.create({ title: "Hello World!" });

// uses the internal API to create a post record without running actions
// requires special permissions granted in the Roles and Permissions section
await api.internal.post.create({ title: "Hello World!" });

Read more about the Internal API Internal API Reference.

Logs 

Logs are records of events and messages generated by your application during its execution. They provide valuable information about the application's behavior, performance, and potential issues. Each Gadget app has a built-in logs store, and logs can be viewed and searched in the built-in Log Viewer.

You can emit your own logs using the provided logger object in Effect files or the request.logger object in HTTP routes. Logs help developers monitor, debug, and maintain their applications more effectively.

Read more about Gadget's Logs in the Logging guide.

Model 

A Model in Gadget represents a data structure that defines the shape of the data stored in the database. 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.

Read more about Models in the Models guide.

Model Action 

Model Actions are Actions that run in the context of specific records within a Gadget Model. They are ideal for operations that involve particular record associated with a specific model. Model actions are different than Global Actions as they run on records and Global Actions do not.

Read more about Model Actions in the Actions guide.

Problems 

In Gadget, problems refer to issues or errors that are detected by Gadget in your application during development. Examples include syntax errors in code, type errors, and missing fields that should be present on models.

These problems are displayed in the Problems Drawer within the Gadget editor, providing you with information on the specific issue and its location in your code. By addressing these problems, you can ensure a smoother deployment and a more stable application.

Production 

In Gadget, Production refers to the environment where your application is live and accessible to end-users. It is separate from the Development environment, where you make changes and test your application before deploying them to Production. To deploy changes from Development to Production, you click the "Deploy" button in the Gadget editor.

When interacting with your application's API, you'll use different URLs for each environment. For example,

Development: https://example-app--development.gadget.app/api/graphql
Production: https://example-app.gadget.app/api/graphql

In the Gadget editor, Production views are emphasized with a purple border to help you quickly distinguish which environment you're observing.

Read more about the Production environment in the deployment guide.

Public API 

The Public API in Gadget refers to the automatically generated GraphQL API for your application, which allows you to access and manipulate your data. It invokes Model Actions and Global Actions with all their Effects, ensuring that your business logic is executed when interacting with your data.

You can invoke the Public API in JavaScript with the api object in your backend or frontend:

// runs the create action on the post model with the given params
await api.post.create({ title: "Hello World!" });

// runs the create action on the post model with the given params
await api.post.create({ title: "Hello World!" });

The Public API is the interface to the backend that frontends call. If you're deploying a React frontend to Gadget or to another hosting platform, the Public API is the best way to get data in and out of Gadget.

Read more about your app's API in the API Reference.

Realtime query 

A realtime query refers to a client-side query which continually fetches the most up-to-date data from the backend, giving users a great experience by showing them the most recent data in the system.

Realtime queries use the live: true option to the @gadgetinc/react hooks, for example:

const [{ data, fetching, error }] = useFindMany(api.widget, { live: true });

const [{ data, fetching, error }] = useFindMany(api.widget, { live: true });

Relationship 

A relationship in Gadget is a connection between two Models that allows you to link records of one model with the other. Relationships are created using fields like belongs to, has one, has many, and has many through. They enable easy data fetching in the API and help in organizing data in a normalized fashion.

For example, in a blog application, we might have two models: Post and Comment. Each blog post can have multiple comments, and each comment belongs to a specific blog post. To represent this in Gadget, we can create a has many relationship on the Post model and a belongs to relationship on the Comment model. In the API, you can then fetch a post's comments easily, and each comment will have a reference to its parent post.

Read more about Relationships in the Models guide.

Belongs To Relationship 

A belongs to relationship in Gadget is a connection between one record of a model to one record of another model. It's used when one record is directly owned or categorized by a record of another model, and you want to quickly access the related record. For example, if you have a User model and a Post model, a post "belongs to" a user if each post is created by a specific user. Here's an example schema:

1. User model:

   • id id
   • name string

2. Post model:

   • id id
   • title string
   • content string
   • user belongs to referencing the User model

In this case, a Post "belongs to" a User, as each post has the user field referencing a particular user as the author of that post.

Has Many Relationship 

In Gadget, has many is a term used to describe a one-to-many relationship between two models. It means that one record of a model can be associated with multiple records of another model. For example, if you have a User model and a Post model, a user "has many" posts if each user can create multiple posts. Here's an example schema:

1. User model:

   • id id
   • name string
   • posts has many

2. Post model:

   • id id
   • title string
   • content string
   • user belongs to

In this case, a User "has many" Posts, as each user can have multiple posts belonging to it.

Has Many Through Relationship 

has many through is a type of relationship in Gadget used to connect two models in a many-to-many relationship. It uses a third, intermediate model to represent each pair of related records in the first two models. This allows both sides of the relationship to have multiple related records on the other side.

For example, in a school registration system with a Student model and a Course model, a Registration model would be the intermediate model connecting them. Each Registration record represents one instance of a student enrolling in a course.

For more information on has many through relationships, see the Models guide.

Has One Relationship 

has one is a type of relationship in Gadget used to connect two models in a one-to-one relationship. It's used when you have two different models that need to be related, but neither model can be related to more than one record of the other model.

For example, you might have a User model that has an Avatar Image record related to it. Users can only have one avatar, and may not have one at all. In this case, you can create a belongs to relationship from User to Avatar, and a has one relationship from Avatar back to User.

reader role 

The reader role is designed for users and API keys requiring read-only access. Readers are unable to execute actions. By default, Gadget assigns read permissions to the reader role for all new models.

Read more about the role of a reader in the access control guide.

Semantic Search 

When users type inputs into a search box, they often don't use the exact words contained in the content they are looking for. For example, a user might search "how do i stay dry in the rain", and be looking for a page that only contains the word "umbrella". Semantic search is a technique for finding the document that best match a search query using an understanding of the meaning behind the words. This is an alternative to the normal style of keyword search which matches using characters contained in the documents and query.

Gadget supports semantic search with the vector field type in tandem with a vector embedding API like OpenAI's.

Read more about building semantic search with Gadget in the building AI apps guide.

Shopify App 

A Shopify App is a custom application that extends the functionality of a Shopify store. It can be built using Gadget, which connects to a Shopify store via the Shopify connection, allowing access to store data and enabling the creation of engaging buying experiences for shoppers. Gadget supports hosting Shopify app backends, facilitating OAuth, data sync, webhooks, and API calls, as well as a Shopify app frontend, using Polaris and Shopify's react libraries.

Read more about Gadget's Shopify Connection.

Shopify CLI 

The Shopify CLI (Command Line Interface) is a powerful tool that automatically generates a template for an application that will be embedded in the Shopify Admin. It helps developers create and manage Shopify apps more efficiently by providing a set of commands and utilities.

To use the Shopify CLI with a Gadget backend, you can follow Gadget's Shopify CLI Connection tutorial.

Trace ID 

A trace ID is a unique identifier assigned to each request made to the Gadget platform. It helps you find all the logs for a specific request in your Logger. Gadget includes the trace ID in the x-trace-id header of the response. This makes it easy to locate logs related to a particular request and troubleshoot issues.

Read more about trace IDs in the Logging guide.

Triggers 

Triggers in Gadget are events or conditions that initiate an Action within an application. They parse external events, such as incoming webhooks or API calls, and transmit them to the rest of the Action. Default triggers are already established in many Actions, such as the GraphQL API trigger for integrating the Action into your app's API or the Shopify Webhook trigger that executes Actions in response to Shopify webhooks.

Read more about triggers in the Actions guide.

unauthenticated role 

The unauthenticated role in Gadget controls the access permissions for unauthenticated sessions or API keys. By default, an unauthenticated session is restricted from reading or writing any data except for its own session data. Gadget does not assign any additional permissions to this role automatically.

Read more about the role unauthenticated role in the access control guide.

urql 

urql is a highly extensible and customizable GraphQL client library that works with a variety of JavaScript frameworks. Within Gadget, it provides React bindings that utilize the API client generated for your app, offering all of the same features from the urql library (Ex. useQuery hook). Gadget uses 'urql' under the hood to generate its own hooks (Ex. useFindOne, useFindMany, useFindFirst, etc).

Read more about the urql library capabilities here.

Usage-based billing 

Usage-based billing refers to the pricing model of Gadget, where applications are charged based on their consumption of resources within a given billing period. App usage is measured by various metrics such as data storage, database reads and writes, request time, outbound bandwidth, file storage, and app installations. Users are charged a fee for additional resources when their applications exceed the included amount of any resource metric provided by their plan.

Read more about Gadget's usage model in the account and billing guide.

App Installations and inst-mnth 

The unit of measurement for the number of installations your app has in the current billing month. Gadget charges a fixed fee per installation per month, prorated for the duration the app was actually installed that month.

See the account and billing guide for more information on app installation billing.

GB-mnth 

The unit of measurement for the number of gigabytes stored by your app in the current billing month in either the database or cloud file storage. Gadget charges fixed fees per GB per month, prorated for the duration the GB was stored that month.

See the account and billing guide for more information on file storage and database storage.

Billing month 

Gadget charges for usage once a month. If your first bill arrives on the 5th day of the month, Gadget will issue a bill for your current usage on the 5th of the next month.

Request time 

The total amount of time your applications have spent executing your code during a billing period. Request time includes time spent serving API requests, processing webhook, running global actions and syncing data from your connections.

Outbound bandwidth 

The count of GBs of data served by your applications to clients. Outbound bandwidth includes GraphQL responses served by your API, HTML responses served by routes, and raw file data served from File storage.

File storage 

The total size of the files stored in the cloud by your applications. File storage is charged a price per gigabyte per month, and is prorated down to the hour. Measured in GB-mnths.

Database storage 

The total size of the data stored in your application's database. Data storage is charged a price per gigabyte per month, and prorated down to the hour. Measured in GB-mnths.

Validation 

A Validation is an element of a Model that allows you to prevent misshaped or incoherent data from entering your system. When changing records, Gadget ensures that any new data passes the validations for each field. If an Action tries to write invalid data, it will fail, and the invalid data won't be saved. API calls that try to write invalid data get structured error messages about what was invalid, which can be shown right to users to guide them toward correcting the data.

Gadget offers a selection of common validations for each field type, as well as custom validation options using Run Code Snippet and RegExp Pattern.

Read more about Validations in the building models guide.

Vector 

A vector is a list of numbers that represents a point in a vector space. In Gadget, the vector field can be used to store and retrieve vectors, as well as for sorting and filtering by distance between vectors. Vector similarity is most often used to implement semantic search in a database powering an AI application.

See the building AI apps guide for instructions on using the vector, and see the Vector Sorting and Vector Filtering sections of the API Reference for more information.

Vite 

Vite is the next-generation JavaScript build tool Gadget uses for powering frontend development. Gadget's hosted frontends use Vite in development to offer great support for React development, including fast module reloading. Gadget manages the Vite build process to produce production JavaScript artifacts when deploying to Production as well.

Read more about building frontends with Gadget in the building frontends guide.

writer role 

The writer role in Gadget is designed for users and API keys requiring read and write access. By default, writers are granted read and action permissions for all public API endpoints.

Read more about the role of a writer in the access control guide.