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 enables a team to bring the data domain they own into the supergraph. 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. A subgraph is analogous to a microservice owned by a particular team.
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 connector agents that integrate Hasura with various external data sources and services and are based on the native data connector specification. Native data connectors can be either official Hasura connectors, verified by Hasura or a non-verified connector. 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. This facilitates data interconnection. Learn more.
Permissions
A metadata object in Hasura DDN that defines the access control or authorization rules on models and commands. Learn more.
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.
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.
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.
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.
