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.
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.
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 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.
Read more about data aggregation in the Data Aggregation guide.
A database is a structured system for storing, managing, and retrieving data. In Gadget, the built-in database is powered by PostgreSQL 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 Building Models guide.
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 Deploying to Production guide.
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:
In Gadget, software development happens in the cloud using the Gadget web editor. Developers don't run Gadget locally and deal with the complexities of setting up a local development environment. Instead, developers use the same infrastructure for development and production.
Read more about the Development environment in the Deploying to Production guide.
Read more about Effects in the Actions guide.
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.
Filesync is a feature in Gadget that allows you to clone your app's files into a local directory and sync any changes between your local directory and the Gadget editor in real time. This enables you to use your favorite code editor, set up lint rules, write and run unit tests, use your local command line to add npm modules, and implement version control for your Gadget projects. While your files are synced locally, your Gadget app still runs in the cloud, and changes made locally are immediately reflected remotely.
Read more about Filesync in the ggt guide.
Gadget CLI (
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 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.
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
Read more about installing your API client in the API Reference.
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.
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.
api.internal object in your backend or frontend:
Read more about the Internal API Internal API Reference.
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.
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 Building Models guide.
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.
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,
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 Deploying to Production guide.
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.
api object in your backend or frontend:
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.
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:
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 Building 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:
userbelongs 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:
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 Building 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.
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.
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.
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.
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.
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 Buiding Models guide.
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.
Read more about building frontends with Gadget in the Building Frontends guide.
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 Usage and Billing guide.
App Installations and
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 Usage and Billing guide for more information on app installation billing.
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 Usage and Billing guide for more information on file storage and database storage.
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.
The total number of rows read from your application's database during a billing period.
The total number of rows added or updated in your application's database during a billing period.
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.
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.
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
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