Hello, welcome back to another edition of Source Network Concept Explainers. This time, we'll go deep into another critical element of the Source Network and DefraDB stack — querying — and how DefraDB uses a web-composable query interface, GraphQL, as a seamless API layer that enables smart contracts from any chain to connect to our database.

An intro to GraphQL

So you’ve read about how DefraDB leverages NoSQL technology for dynamic (content-addressable & conflict-free) data management, where anyone can access the database via peer-to-peer networking structures. Now, let’s learn how DefraDB handles client requests to and from the database, unlocking new abilities for APIs.

DefraDB ships with a native query language called GraphQL, a query language for APIs, and a runtime for fulfilling those queries with your existing data. GraphQL provides DefraDB clients (i.e., users and developers) a complete and decipherable description of the data in their API, giving developers the power to ask for exactly what they need — and nothing more.

This function makes it easier for APIs to evolve, unlocking more possibilities and streamlined, developer-friendly tools for devs, eliminating the need for developers and their applications to create custom APIs. Our database, rather, utilizes GraphQL as an alternative to REST, an application programming interface (API) that conforms to the constraints of REST architecture.

GraphQL defines an API as a collection of resources available for querying instead of a collection of endpoints. This is the main difference between GQL and REST-based APIs and means in a single GraphQL request, a client can request all the necessary resources and data for a given action. This can be done instead of calling several different endpoints defined by the developer and combining them unexpectedly on the front end, which can lead to unexpected risks compared to building in the backend.

REST vs GraphQL

Why is GraphQL such an ideal fit as a querying language for DefraDB? Let’s remember our intro article on how DefraDB leverages NoSQL database structures for flexible, dynamic data management and infinite scale. There, we learned that unlike SQL databases, which require developers to store data in clucky and constrained associated tables, NoSQL provides more flexible and dynamic data models and schema options: key-value, graph-based, wide-column, column-based, and document-based.

GraphQL schemas and requests closely match the existing structure found in Document databases like DefraDB, unlike a SQL database (which uses rows, columns, and relational algebra). As a result, GraphQL is designed specifically for composing resources and accessing them in a graph-like nature, and thus, a direct correspondence naturally exists between the Query Language and the Data Model within the GraphQL ecosystem.

Overall, GraphQL works seamlessly with DefraDBs' document structure and semantic schemas, which were designed with an interface popularized by JSON objects.

While GraphQL has a single downside (a strictly typed language), it’s a net-benefit to the client and helps construct accurate and enforced queries in a traditional database environment. While this can be a roadblock for global databases, where anyone can define any scheme at any time (making it impossible to be constantly updating schemes), DefraDB automatically scaffolds the required typed GraphQL Schemas whenever a new Schema is registered with a given database node.

Each schema only needs to be scaffolded once, and thanks to DefraDB and GraphQL, it gains the ingenuity of content-addressable data. Each GraphQL schema also correlates to exactly one content-addressed Semantic Schema, meaning that any change to a DB Schema creates an entirely new, content-addressed schema, which can generate a new GraphQL schema with no downtime.

How DefraDB uses GraphQL to query database nodes

GraphQL works seamlessly with DefraDB as a result of its organizational and schema structures, making it easy for developers to query our database nodes.

Any client on any device can query any DefraDB node, regardless of ownership, as long as they can connect to it locally or over the internet. This is a drastically different approach to the tight control applications placed on traditional, centralized database architectures, where you can never directly access the database and only get your data via the application and its associated interfaces.

This kind of centralized architecture type (pictured above) is directly conflicting with a user-centric database model like DefraDB. The main reason user-centric databases are safe to expose directly to clients is that all the data is fully protected. DefraDB’s design, protection, security, and privacy are guaranteed via Public Key cryptography, powerful access control, and policy enforcement mechanisms — otherwise known as SourceHub, our trust layer.

Querying Merkle CRDTs in DefraDB

All data objects stored within DefraDB are MerkleCRDTs, a technology we learned enables conflict-free data and offers developers the advantages of safety, predictability, collaboration, and the maintenance of historical data structures. DefraDB’s MerkleCRDTs are represented as a series of small updates connected in a MerkleDAG: a Merklized version of a DAG (Directed Acyclical Graph), which means that each node in the DAG references a parent node through some kind of Content Identifier (CID).

An example structure of a MerkleDAG.

Let’s see how querying works on DefraDB:

The Head CID represents the "current" or "latest" state of a MerkleDAG.

DefraDB allows you to query, traverse, and validate the DAG structure, allowing for self-verifying data structures.

In the DefraDB Database API, DAG nodes are represented as Commit, CommitLink, and Delta types. They are defined as shown below:

To query the latest commit of an object (with id: '123'):

To query a specific commit:

In addition to using Commits specific queries, include commit version sub-fields in object queries.

The above example shows how to query for the additional _ version field that is generated automatically for each added schema type. The _ version has the same execution as latestCommits.

Both _ version and latestCommits return an array of Commits types because the HEAD of the MerkleDAG can point to more than one DAG node. This is caused by two concurrent updates to the DAG at the same height. The DAG usually has a single head. However, it can also have multiple heads.

Commits queries also work with aggregates, grouping, limit, offset, order, dockey, cid, and depth There is __ typename introspection keyword that works on all queries that do not appear to be documented anywhere, for example:

Querying DefraDB from smart contracts

Last but not least, there is the ability to query DefraDB directly from any chain’s smart contracts!

This is where the real smart contract magic happens beneath the hood, enabling smart contracts from any chain to seamlessly connect to our database, ultimately enabling developers to manage data across various applications. Using ERC-3668, a token standard interface for secure off-chain data retrieval, as an example, DefraDB can allow for off-chain lookups of data in a way that is transparent to clients. For the off-chain metadata native to NFTs and financial data used in DeFi, the ability to easily query DefraDB directly from smart contracts is foundational to the data management capabilities of our database. Check out the example in further detail on our GitHub.

GraphQL and querying: reimagining the API for a decentralized future

Through the power of GraphQL, developers using only an internet connection can call DefraDB to connect — and manage — off-chain data from any smart contact. As a result of DefraDB's design, MerkleCRDTs, and the cryptographic guarantees of our trust layer, SourceHub, clients can remain confident that their data is fully protected, secure, and private.

Altogether, these features enable data to be more accessible and reduce the reliance on APIs as a centralized intermediary between applications and developers that often require a custom architecture that can prove detrimental to scaling products.

These features are another example of how DefraDB enables the next generation of web3 developers — and users — to gain control over where their data resides, who gets to access it, and how it's secured.

If you’re ready to connect DefraDB to your application to manage your application’s data — and scale your product — contact us on our website.

Explore our GitHub and developer portal for additional documentation on our technology.

Thanks for reading!

— Source Network