Skip to main content
Version: v3.x (DDN)

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.

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
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

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> "*"

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.

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
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.