search

hasura / ddn-sample-app

MIT License
8 stars 3 forks source link

readme

Table of Contents

Ecommerce Application Demo using Data Delivery Network

This demo repo provides a practical example of building an Ecommerce App (read-heavy)using Hasura's Data Delivery Network (DDN) with a supergraph architecture. Please note that a new release for the repo is out. Make sure to try the workflow again if you are a returning user.

Pre Requisites

Disclaimer

This repository has credentials for databases, which are intentionally published by Hasura for demo purposes. These credentials allows for read-only access to synthetic datasets, which do not contain any user or customer sensitive data.

This example supergraph is composed of three subgraphs - users, experience, and sales, each backed by one or more data connectors. These subgraphs integrate various data sources to provide a comprehensive Ecommerce solution as follows.

flowchart TD
    %% Module 1
    M1[Experience Subgraph]
    M1 --> D1A[Postgres]
    M1 --> D1B[Mongo]

    D1A --> T1A[• Products
             • Manufacturers
             • Categories
             • Carts
             • CartItems
             • ProductVectorDistance]

    D1B --> T1B[• ProductDetails]

    %% Module 2
    M2[Users Subgraph]
    M2 --> D2A[Postgres]
    M2 --> D2B[Clickhouse]

    D2A --> T2A[• Notifications
             • Reviews 
             • Users]

    D2B --> T2B[• Browsing History
             • Recently Viewed Products
             • Session History]

    %% Module 3
    M3[Sales Subgraph]
    M3 --> D3A[Postgres]
    M3 --> D3B[Typescript]

    D3A --> T3A[• Coupons
             • Orders]

    D3B --> T3B[• ToCurrencyString
             • ToDateString]



Subgraphs and Data Sources

Local Development

  1. Git Clone this repo: https://github.com/hasura/ddn-sample-app.git and cd into it

  2. Build the supergraph locally using the following command 

    ddn supergraph build local

  3. Run Docker. For local development, Hasura runs several services (engine, connectors, auth, etc.), which use the following ports: 3000, 4317 and so on. Please ensure these ports are available. If not, modify the published ports in the Docker Compose files from this repository accordingly.

    ddn run docker-start

  4. Check out the console to discover and test the GraphQL API 

    ddn console --local

    4a. DDN also supports JSON API as output. The feature is out in experimental phase. Run the following command to fetch the openapi JSON file. An example of the swagger file is shown here.

    curl http://localhost:3000/v1/rest/__schema > ddn_openapi.json

Test using GraphQL API queries from the Composability folder.

alt text

  1. To rebuild after any changes, you may run the following command to get the changes reflected.

    ddn supergraph build local

Deploy to DDN Cloud

  1. Initiate a new DDN Project
ddn project init

This will create a new project and shows the project name output in the terminal. You get an output such as below - 

+-----------+--------------------------------+
| Project   | sincere-turtle-2027            |
+-----------+--------------------------------+
| Subgraphs | globals,experience,sales,users |
+-----------+--------------------------------+
  1. Make sure your own project name shows up in .hasura/context.yaml. Run the following just in case.
ddn context set project <Project Name>

# ddn context set project vast-buzzard-0000
# 5:36PM INF Key "project" set to "vast-buzzard-0000" in the context successfully
  1. Create a Supergraph Build. This will also create the connector builds automatically.
ddn supergraph build create

⚠️ First Time Build can take 8 to 10 mins. Subsequent builds will be faster because of caching. Recommend

If you want to just make metadata changes and quickly see changes without rebuilding the connectors, run the following command:

ddn run build-supergraph
or
ddn supergraph build create --no-build-connectors

This is a script which passes the flag --no-build-connectors

Note: Once deployed to your new project, if you don't have any connector changes, you can only rebuild supergraph alone, ie. connectors are only need to be deployed when there is change (data schema changes, functions etc.)

  1. Go to console and test using GraphQL API queries from the Composability folder.

API Features (Both GraphQL and REST API)

  1. Filtering and Sorting Operations

    • Basic field filtering eg. (countryOfOrigin: {_eq: "US"})
    • Category filtering using UUID
    • Rating filtering eg. (_gt operator)
    • Ascending order by distance eg. (order_by: { distance: Asc })

  2. Remote Relationships in Predicates

    • Reviews relationship used in filtering conditions
kind: BooleanExpressionType
version: v1
definition:
  name: ProductsBoolExp
  operand:
    object:
      type: Products
      comparableFields:
        - fieldName: categoryId
          booleanExpressionType: UuidBoolExp
        - fieldName: countryOfOrigin
          booleanExpressionType: TextBoolExp
        - fieldName: createdAt
          booleanExpressionType: TimestamptzBoolExp
      comparableRelationships:
        - relationshipName: reviews
          booleanExpressionType: ReviewsBoolExp
  logicalOperators:
    enable: true
  isNull:
    enable: true
  graphql:
    typeName: ProductsBoolExp

  1. Pagination

    • Using offset parameter
    • Using limit parameter

  2. Same Database Join

    • Manufacturers table join with aliasing such as (manufacturedBy)

  3. Cross-Database Operations

    • Integration with Clickhouse and MongoDb databases
      • With Custom (Native Queries)
    • Session history tracking and Product Details
kind: Relationship
version: v1
definition:
  name: recentlyViewedProducts
  source: Users
  target:
    model:
      name: RecentlyViewedProducts
      subgraph: users
      relationshipType: Array
  mapping:
    - source:
        fieldPath:
          - fieldName: id
      target:
        modelField:
          - fieldName: userId

  1. Multi-Level Nested Joins

    • Two-level: Products → Orders
    • Three-level: Products → Orders → Users

  2. Nested Filtering

    • Filtering within reviews section

  3. Nested Sorting

    • Sorting by category name in ascending order
    • Sorting reviews by rating in descending order

  4. Nested Pagination

    • Top N reviews selection (limit: 3)
    • Filtering by date in nested query
    • Sorting in nested query

  5. Field Selection

    • Basic fields (id, name, price, description)
    • Nested fields (createdAt, lastSeen)
    • Custom field aliases

  6. Data Transformations

    • Date and Currency formatting transformations
    • TypeScript function integrations for formatting
kind: Command
version: v1
definition:
  name: ToCurrencyString
  outputType: String!
  arguments:
    - name: amount
      type: Float
      description: The number to format into currency.
  source:
    dataConnectorName: salests
    dataConnectorCommand:
      function: toCurrencyString
  graphql:
    rootFieldName: toCurrencyString
    rootFieldKind: Query
  description: Formats a number into a currency string.
export function toDateString(date?: string): string {
  console.log("date", date);
  if (!date) {
    return "Invalid date";
  }
  try {
    return new Date(date).toDateString();
  } catch (error) {
    console.error("Error formatting date:", error);
    return "Invalid date";
  }
}

  1. Vector Search Operations

    • Main query named SearchProductsVector
    • Vector distance calculation based on query vector
    • 50-dimensional vector input
    • Similarity-based ranking

  2. Query Arguments

    • Vector argument passing using args parameter
    • Query vector as a string of floating-point numbers
    • Pre-computed embedding vector input

Configure PromptQL

  1. Enable PromptQL by going to the console

alt text

  1. Start asking questions about the data

alt text

Get round-the-clock support on our Discord Server here.


DDN Advanced

Two Main Features

alt text

See more details on DDN Advanced here.

Switch to this branch to start the DDN Advanced Workflow - https://github.com/hasura/ddn-sample-app/tree/multirepo/team1admin



Core Concepts

The following section outlines the core concepts of Hasura DDN, providing a deeper understanding of its architecture and functionality.

Subgraph

For a multi-team organization working on a Hasura project, it can make sense for any one team to not have access to all metadata objects. Subgraphs introduces the notion of a module system for your Hasura metadata. Think of it is as an independent domain consisting of one or more data sources. Read More

Models

Models are the link between your data connectors and the API Hasura generates. A model may be backed by a database table, an ad-hoc SQL query, a pre-materialized view, a custom REST or GraphQL API server, etc. Read More

Commands

Commands are backed by functions or procedures declared in a DataConnectorLink allowing you to execute business logic directly from your GraphQL API. You can use them to validate, process or enrich data, call another API, or even log a user in.

Read More

Build Process

A build is a fully-functional, immutable supergraph API which is built based on your project's configuration.

During the build process, Hasura builds and deploys all the data connectors and supergraph builds. This includes connector configurations, models, functions, and all other related components, which are integrated into the deployments.

Considering the size of the supergraph and separate deployments, it may initially take some time to complete. Once deployed, the supergraph provides a unified GraphQL API that leverages the capabilities of all subgraphs to offer a comprehensive Ecommerce solution.