Hasura DDN Glossary
Hasura v3
Hasura v3 represents a major version change for the main underlying component of Hasura Cloud.
There are significant enhancements to the engine, including:
- A new architecture
- A switch to the Rust programming language
- A new specification to work with the engine.
Because of the new specification, the engine is now decoupled from the API protocol, such as GraphQL, and as a result in
the coming years the graphql-engine will evolve to become the graphql-api-engine and finally the api-engine.
Apart from the enhancements to the graphql-engine, Hasura v3 also introduced the rollout of the new Native Data
Connector Specification and the associated connectors.
Hasura Data Delivery Network (DDN)
Hasura DDN is a brand-new offering that is powered by the innovations in Hasura v3. While Hasura v3 data plane is open source, DDN represents a managed service for that data plane with the promise of operationally excellent APIs and replaces the application/API server infrastructure requirement for organizations.
On top of that, Hasura DDN is a globally distributed, and always available cloud for APIs and data connectivity, which enables blazingly-fast and secure delivery of real-time data. The new runtime engine in Hasura DDN accesses metadata on a per-request basis, enabling improved isolation and scalability.
Apart from the managed data plane, DDN also includes a brand-new control plane which comprises metadata authoring, CI/CD, cloud infrastructure components, and collaboration features. In v2, we bundled the control plane and data plane together. In v3, we have separated the control plane and data plane. The control plane is closed source and commercial only.
Control plane
The control plane manages the configuration, orchestration, and coordination of the data plane elements along with providing tools to author metadata. It is responsible for setting up and managing the behavior, policies, and rules that govern how data is processed and forwarded in the data plane. It also oversees the overall behavior of the system, manages the API endpoints, maintains the API configurations, handles authentication and access control mechanisms, and gathers analytics or metrics related to API usage.
Data Plane
The data plane manages the actual handling of API requests and responses. It deals with the execution of API operations, the transmission of data between clients and the API endpoints, and the processing of data payloads. The following are the main components of a data plane:
Hasura v3 GraphQL Engine: The engine takes in an API request (a GraphQL query for example), converts it into an intermediate representation that the connectors can handle, and creates a plan for the query execution across various data sources.
Hasura connectors: These handle the actual API execution. They accept the intermediate representation from the engine and use the most efficient mechanism to execute the query and fetch/mutate data from the underlying data source.
Both the components mentioned above are open sourced.
Supergraph
A supergraph is an architecture and operating model to build and scale multiple data domains (or subgraphs) as a single graph of data entities and operations.
Supergraphs help us to benefit from a centralized monolithic approach (high cohesion and easy governance) on a federated microservices execution model (loose coupling and scaling ownership).
Today, supergraphs are more critical than ever because accelerating data and microservice sprawl are making the complexity of data and API consumption untenable – showing up in slower time-to-market, harder to address tech-debt and complex team communication. Learn more.
Subgraphs
A subgraph represents a self-contained module of metadata and its accompanying data connector(s) which encapsulates a specific data domain. Subgraphs have a permission model, and an independent software development life cycle, and can be developed, tested, and built independently. The supergraph guarantees the integrity of subgraph composition.
Subgraphs can be managed in their own isolated repositories and built completely independently of each other. Fields exposed to the full supergraph can be prefixed to prevent schema conflicts. Data can be interlinked between subgraphs using relationships, even between subgraphs in separate repositories.
A subgraph is analogous to a microservice owned by a particular team.
Globals subgraph
When running the ddn supergraph init command, a globals subgraph is created by default for your convenience. This
subgraph is intended to hold global configuration objects for the supergraph, such as API configuration and auth
settings.
These configuration objects are AuthConfig, CompatibilityConfig and GraphqlConfig as well as the subgraph.yaml
configuration file which defines the globals subgraph itself.
These objects are located by default in the globals subgraph, but can be moved to any other subgraph if needed.
Hasura Metadata
Hasura metadata models a supergraph and specifies the API for the supergraph. It is the configuration that is provided
declaratively to help connect to the data source and provide a working API. It introduces key supergraph modeling
constructs such as Types, Models, Commands, Permissions, and Relationships, which help in understanding and
implementing systems that align closely with the real-world domain they are meant to represent. Apart from modeling
constructs, the metadata also defines key configuration around API security, caching, deployment, and CI/CD, that helps
explain the entire API system for the organization. Learn more.
.hml (Hasura Metadata Language)
The file extension for the files that conform to the Hasura metadata specification for the supergraph. It is a
derivative of .yaml extension (and shares the same syntax) and provides the same benefits such as 1) readability, 2)
data structures, 3) comments, and 4) portability, to author, reason, and share metadata.
Supergraph modeling
The act of writing information to conform to the Hasura metadata specification and the process of identifying, defining, and structuring the distinct sets of the supergraph elements or attributes.
Immutable-Build Runtime System
The new runtime engine in Hasura DDN, which accesses metadata on a per-request basis, enables improved isolation and scalability. This independent build system allows a runtime that eliminates shared state and cold start issues for enhanced performance.
Data Sources
Any external data source, database, or service that can be connected to Hasura DDN using a Data Connector agent. Every data source must have connector URL and schema. Learn more.
Native Data Connector Specification (NDC Spec)
A standardized specification that allows you to extend the functionality of the Hasura server by providing web services
that resolve new sources of data and business logic and help define the metadata structure for APIs in Hasura DDN. The
specification defines types such as collections, functions, and procedures that help in describing the behavior of
agents or connectors that connect to the underlying data source. It provides a framework and guidelines on the types of
web service endpoints that a connector needs to implement.
Learn more.
Native Data Connectors
Data connectors are specialized agents that connect subgraphs to data sources, enabling communication in the data source's native language.
They integrate Hasura with various external data sources and services based on the native data connector specification.
Each subgraph can have multiple data connectors, and the same data source can be connected to different subgraphs via separate connector instances - allowing teams to work with the same source from different domain perspectives.
Data connectors are available for a wide variety of sources including databases, business logic functions, REST APIs, and GraphQL APIs. They can be official Hasura-verified connectors or custom-built connectors to integrate with other data sources. Learn more.
Push-Down Capabilities
The ability in Hasura DDN to delegate certain query operations including Authorization to the underlying data source. This can improve query optimization and performance and is the reason why data connectors in Hasura DDN are called 'native'.
Connector Hub
Refers to the public site where all Native Data Connectors for Hasura DDN are listed. Users can discover connectors, get more information about their specific features and find documentation on how to use each connector with Hasura DDN. Learn more.
Model
A metadata object that is fundamental to API design in Hasura DDN. The model is the entity that has a direct mapping to the underlying native data connector object or collection.
A model includes reference to the data type and includes configuration details related to API configuration, arguments and global ids.
It supports select, insert, update and delete operations. Within the select operation the different query operations include filtering, aggregating, paginating and limiting. Learn more.
Command
The Hasura entity that helps encapsulate business logic and represents an action that can be performed which returns back some type of result. It directly maps to the native data connector object's functions and procedures. Learn more.
Relationships
A metadata object in Hasura DDN that defines the relationship between two models or between a model and a command.
Defining a relationship allows you to make queries across linked information within and between subgraphs.
When working with relationships across subgraphs in other repositories, there are some differences to be aware of. Find out more about cross-repo relationships here.
As always when authoring metadata, the Hasura VS Code extension can assist with auto-complete and validation.
Authorization Permissions
Authentication is managed at the supergraph level in Hasura DDN as defined by the AuthConfig object and cannot be
customized at the subgraph level.
Authorization however, which is a metadata object in Hasura DDN that defines the access control or authorization rules on models and commands. Learn more, is managed at the subgraph level in Hasura DDN. This means that the permissions for models and commands are defined within the context of those objects in their respective subgraphs, and do not affect other subgraphs.
Authorization rules in one subgraph can also be defined to reference data in a foreign subgraph even if that subgraph is in another repository.
Global ID
Refers to the Relay global ID that encodes the type and ID of an object in a single string. In Hasura this is defined per model and enables fetching any object directly, regardless of what kind of object it is. A result of this is that you get the node root field in the GraphQL API schema to use with a Relay client. Learn more.
Collection
A collection is a Native Data Connector Spec object, which encapsulates part of a data source, providing standard querying capabilities.
Each collection is defined by its name, any collection arguments (need to parametrize the collections), the object type (a collection of fields) of its rows, and some additional metadata related to constraints.
Tracking a collection results in the creation of a 'model' object in Hasura metadata. Learn more.
Function
A function is a Native Data Connector Specification object that can be invoked with arguments to get a result, and which doesn't have side-effects and is thus "read only". Unlike collections, functions do not describe constraints and do not have object types.
Tracking a function results in the creation of a Command Supergraph object in Hasura metadata.
Learn more.
Procedure
A procedure is a native data connector specification object, and it defines an action that the data connector implements and can mutate data and have other side-effects. Each procedure has arguments and a return type.
Tracking a procedure results in the creation of a Command object in Hasura metadata.
Learn more.
Builds
Each metadata change in Hasura DDN represents an immutable build. Every build has a unique GraphQL Endpoint that can be tested independently. Builds exist in in projects and there is a one-to-many mapping between projects and builds. [Learn more](/project/configuration/overview.mdx
Supergraph config
Supergraph config tells Hasura DDN how to construct your supergraph. A config will contain information such as which subgraphs to include and which resources to use for the build. [Learn more](/project/configuration/overview.mdx
Connector config
Connector config tells Hasura DDN how to build your connector. It will contain information such as the type of connector and the location to the context files needed to build the connector. [Learn more](/project/configuration/overview.mdx
DDN CLI (Command-Line Interface)
A tool in Hasura DDN that enables developers to interact with DDN from the command line. It supports various commands for creating builds, tracking objects, and deploying projects. Learn more.
VS Code Extension
The Hasura VS Code extension enables features like inline validation of Hasura DDN metadata without having to create builds, code scaffolding snippets which can be used to quickly scaffold DDN metadata objects, intelligent autocomplete which shows autocomplete suggestions based on the current state of the DDN project, and other features like go-to-definition for inter-related DDN metadata objects, documentation on hover of any DDN metadata object, a project tree on sidebar which shows all DDN projects and metadata objects present in the currently opened folder.
It is strongly recommended to download the VS code extension while working with DDN projects, it can be downloaded from VS Code extension marketplace.
Metadata build service
Creates builds from the metadata and makes it available to Hasura v3 GraphQL Engine at the edge for it to serve the API request. Provides essential error handling for fast debugging and troubleshooting.
Control plane cloud API
This component is the underlying cloud service, which enables creating builds, applying builds and testing your API. We consider this the brain of DDN Console and CLI – the component that drives most of the DX functionalities.
DDN Console
An interface in Hasura DDN that provides tools for metadata visualizing, API testing and deployment, team collaboration, documentation, traces, and analytics.
Cloud PAT
This refers to a personal authentication token that Hasura Cloud creates automatically for you on every new project
creation. This ensures that your GraphQL API always has a security mechanism. The auto-generated PAT is included in the
API header cloud_pat.
