Skip to main content
Version: v3.x

Build your API & Make Queries

What's about to happen?​

After connecting a data source and exposing a model, we'll create a new local build of our API.

A build is a compiled, immutable state of your metadata which the Hasura Engine uses to run your API.

When you execute the command below, the CLI will create a new build for your supergraph. You'll then be able to execute a GraphQL query on your API using any models you've added.

Build your API

Steps​

Required

Step 1. Create a supergraph build​

Pass the local subcommand along with specifying the output directory as engine in the root of the project. This directory is used by the docker-compose file to serve the engine locally:

From the root of your project, run:
ddn supergraph build local \
  --output-dir engine \
  --subgraph-env-file my_subgraph:my_subgraph/.env.my_subgraph.local

This will create a build of your supergraph.

With this command we're specifying the supergraph we want to use to build locally with --supergraph, the output directory name for the engine with --output-dir, and the environment variables needed for each subgraph to build with --subgraph-env-file.

Environment variables

Note that when building a supergraph there can be multiple subgraphs, and we can add environment variables needed for each. We can either specify the environment file with the subgraph as a prefix as we're doing above with --subgraph-env-file or we can use the --subgraph-env flag to specify individual environment variables in the command itself eg: --subgraph-env my_subgraph:key=val.

You should repeat --subgraph-env-file or --subgraph-env flags to specify multiple environment files — such as when working with multiple subgraphs — or variables.

Start your engines!

Want to test your supergraph? Make sure that your services are still up and running with the following command.

From the root of your project, run:
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose up --build --watch

If you haven't included your connector(s) in your compose.yaml, don't forget to start it as well.

You can now navigate to https://console.hasura.io/local/graphql?url=http://localhost:3000 and interact with your API using the Hasura Console.

Privacy settings in some browsers

Your browser settings or privacy tools may prevent the Console from accessing your local Hasura instance. This could be due to features designed to protect your privacy and security. Should you encounter one of these issues, we recommend disabling these settings for the console.hasura.io domain.

Chrome and Firefox are the recommended browsers for the best experience with the Hasura Console including for local development.

Step 2. Write your first query​

Use the GraphiQL explorer to either write a query or construct it using the menu on the left-hand side of the console. When you're ready, hit the run button to execute your query.

For example, if we have a Carts model, we can run the following query:
query MyFirstQuery {
  mySubgraph_carts {
    id
    isComplete
    userId
  }
}

All types are namespaced with the subgraph to which they belong. Here, you can see that carts belongs to a subgraph named my_subgraph. Thus, the query above will return a response that looks like this:

Simple query with carts

Query names

In GraphQL, you can provide a name for your query, which in this example is MyFirstQuery. This name is customizable by you at query time and just helps with logging and debugging.

What did this do?​

When you executed the command above, the CLI used the Hasura metadata in your directory - generated based on your data source(s) — to create a local build of your supergraph. This local build is immutable and can be used to test the changes to your API before either making more changes or, eventually, creating a build on Hasura DDN.

Next, we recommend learning how easy it is to add authorization rules, which limit a user's access to data, using permissions.

Next steps​

Now that you have a build of your supergraph you can do a lot more with it. Here are some suggestions to allow you to jump around the Getting Started section according to your interests:

Loading...