Models Read Data

Introduction

Models represent the entities — such as tables, views, or collections — in your data source, defining the structure and how the data can be accessed.

Lifecycle

New to Hasura DDN?

If you haven't already, have a run through our Quickstart guide to set up your Hasura DDN instance. In the sections below, we'll guide you through how to interact with your metadata and shape your API to your liking!

Creating a model

To query data from your API, you'll first need to create a model that represents that data.

PostgreSQL

Via a new table or view

Create a new table or view in your PostgreSQL database:

CREATE TABLE public.users (
  id serial PRIMARY KEY,
  name text NOT NULL
);

INSERT INTO public.users (name)
VALUES
  ('Alice Johnson'),
  ('Bob Smith'),
  ('Charlie Davis');

Use the DDN CLI to introspect your PostgreSQL instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

Via an existing table or view

If you already have a table present, you can add it by introspecting your data source and referencing it by name.

Use the DDN CLI to introspect your PostgreSQL instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

MongoDB

Via a new collection or view

Create a new table or view in your MongoDB database, and populate it with data:

db.createCollection("users");
db.users.insertMany([{ name: "Alice" }, { name: "Bob" }, { name: "Eve" }]);

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

Via an existing collection or view

If you already have a collection with data present, you can add it by introspecting your data source and referencing it by name.

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

ClickHouse

Via a new table or view

Create a new table or view in your ClickHouse database:

CREATE TABLE users (
    id UInt32,
    name String
)
ENGINE = MergeTree()
ORDER BY id;

INSERT INTO users (id, name) VALUES
    (1, 'Alice Johnson'),
    (2, 'Bob Smith'),
    (3, 'Charlie Davis');

Use the DDN CLI to introspect your ClickHouse instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

Via an existing table or view

If you already have a table present, you can add it by introspecting your data source and referencing it by name.

Use the DDN CLI to introspect your ClickHouse instance:

ddn connector introspect <connector_name>

Then, add your model:

ddn model add <connector_name> users

Create a new build:

ddn supergraph build local

Start your services:

ddn run docker-start

Open your development console:

ddn console --local

You can now query your table:

query {
  users {
    id
    name
  }
}

With a response like this:

{
  "data": {
    "users": [
      {
        "id": 1,
        "screamedName": "Alice Johnson"
      },
      {
        "id": 2,
        "screamedName": "Bob Smith"
      },
      {
        "id": 3,
        "screamedName": "Charlie Davis"
      }
    ]
  }
}

Extending a model

Models can be extended, allowing for transformation and enrichment of the data.

Via a native query

PostgreSQL

Within your connector's directory, you can add a new file with a .sql extension to define a native query.

Create a new directory to store your native queries:

mkdir -p <my_subgraph>/connector/<connector_name>/native_operations/queries/

Create a new file in your connector's directory:

-- native_operations/queries/user_by_name_between.sql
SELECT *
FROM users
WHERE name LIKE '%' || {{name}} || '%'
  AND name > {{lower_bound}}
  AND name < {{upper_bound}}

Then, use the PostgreSQL connector's plugin to add the native query to your connector's configuration:

ddn connector plugin --connector <my_subgraph>/connector/<my_connector>/connector.yaml -- \
  native-operation create --operation-path native_operations/queries/user_by_name_between.sql --kind query

Introspect your PostgreSQL instance:

ddn connector introspect <connector_name>

Then, update your models:

ddn model update <connector_name> "*"

MongoDB

Within your connector's directory, you can add a new JSON configuration file to define a native query.

Create a new directory to store your native queries:

mkdir -p <my_subgraph>/connector/<connector_name>/native_queries/

Create a new file in your connector's directory:

// native_queries/user_by_name_between.json
{
  "name": "userByName",
  "representation": "collection",
  "description": "Look up a user by a regular expression match on name",

  "inputCollection": "users",

  "arguments": {
    "name": { "type": { "scalar": "string" } },
    "lower_bound": { "type": { "scalar": "string" } },
    "upper_bound": { "type": { "scalar": "string" } }
  },

  "resultDocumentType": "UserByName",
  "objectTypes": {
    "UserByName": {
      "fields": {
        "_id": { "type": { "scalar": "objectId" } },
        "name": { "type": { "scalar": "string" } }
      }
    }
  },

  "pipeline": [
    {
      "$match": {
        "$and": [
          { "name": { "$regex": "{{ name }}" } },
          { "name": { "$gt": "{{ lower_bound }}" } },
          { "name": { "$lt": "{{ upper_bound }}" } }
        ]
      }
    }
  ]
}

Use the DDN CLI to introspect your MongoDB instance:

ddn connector introspect <connector_name>

Then, update your models:

ddn model update <connector_name> "*"

ClickHouse

Within your connector's directory, you can add a new SQL configuration file to define a native query.

Create a new directory to store your native queries:

mkdir -p <my_subgraph>/connector/<connector_name>/queries/

Create a new file in your connector's directory:

// queries/UsersByName.sql
SELECT *
FROM "default"."users"
WHERE "users"."name" = {name: String}

Note this uses the ClickHouse parameter syntax

Update your the queries section in your configuration.json file:

// configuration.json
{
  "tables": {},
  "queries": {
    "UserByName": {
      "exposed_as": "collection",
      "file": "queries/UserByName.sql",
      "return_type": {
        "kind": "definition",
        "columns": {
          "id": "Int32",
          "name": "String"
        }
      }
    }
  }
}

Use the DDN CLI to introspect your ClickHouse instance:

ddn connector introspect <connector_name>

Then, update your models:

ddn model add <connector_name> UserByName

Via a lambda connector

Lambda connectors allow you to expose custom business logic via your API. You can also create relationships between an existing model and this business logic to expand the data a model can return.

We support lambda connectors for TypeScript, Python, and Go.

TypeScript

Initalize a new connector and select hasura/nodejs from the list:

ddn connector init my_ts -i

Replace the functions.ts contents with the following:

/**
* @readonly
*/
export function nameToUpperCase(name: string): string {
  return name.toUpperCase();
}

Introspect the connector:

ddn connector introspect my_ts

Track the function:

ddn command add my_ts nameToUpperCase

Python

Initalize a new connector and select hasura/python from the list:

ddn connector init my_python -i

Replace the functions.py contents with the following:

from hasura_ndc import start
from hasura_ndc.function_connector import FunctionConnector

connector = FunctionConnector()

@connector.register_query
def name_to_upper_case(name: str) -> str:
  return name.upper()

if __name__ == "__main__":
  start(connector)

Introspect the connector:

ddn connector introspect my_python

Track the function:

ddn command add my_python name_to_upper_case

Go

Initalize a new connector and select hasura/go from the list:

ddn connector init my_go -i

Rename hello.go to nameToUpperCase.go:

package functions

import (
  "context"
  "fmt"
  "hasura-ndc.dev/ndc-go/types"
  "strings"
)

// NameArguments defines the input arguments for the function
type NameArguments struct {
  Name string `json:"name"` // required argument
}

// NameResult defines the output result for the function
type NameResult string

// FunctionNameToUpperCase converts a name string to uppercase
func FunctionNameToUpperCase(ctx context.Context, state *types.State, arguments *NameArguments) (*NameResult, error) {
  if arguments.Name == "" {
    return nil, fmt.Errorf("name cannot be empty")
  }

  upperCaseName := NameResult(strings.ToUpper(arguments.Name))
  return &upperCaseName, nil
}

Introspect the connector:

ddn connector introspect my_go

Track the function:

ddn command add my_go nameToUpperCase

You can now create a relationship between this function and the model we created earlier:

---
# e.g., inside users.hml
kind: Relationship
version: v1
definition:
  name: screamedName
  sourceType: Users
  target:
    command:
      name: NameToUpperCase
      subgraph: app
  mapping:
    - source:
        fieldPath:
          - fieldName: name
      target:
        argument:
          argumentName: name
  description: The user's name returned in all caps.

Create a new build:

ddn supergraph build local

Start your services:

ddn run docker-start

Open your development console:

ddn console --local

You can now query your expanded table with the transformed name:

query {
  users {
    id
    screamedName
  }
}

With a response like this:

{
  "data": {
    "users": [
      {
        "id": 1,
        "screamedName": "ALICE JOHNSON"
      },
      {
        "id": 2,
        "screamedName": "BOB SMITH"
      },
      {
        "id": 3,
        "screamedName": "CHARLIE DAVIS"
      }
    ]
  }
}

Updating a model

Your underlying data source may change over time. You can update your model to reflect these changes.

You'll need to update the mapping of your model to the data source by updating the DataConnectorLink object.

Update your DataConnectorLink:

ddn connector-link update <connector_name> --subgraph <path_to_subgraph.yaml>

Then, update your model:

ddn model update <connector_name> users

Deleting a model

If you no longer need a model, you can delete it:

ddn model remove users

Reference

You can learn more about models in the metadata reference docs.