Skip to content
Get packs

Guide · Open source

How to use graphql-go/graphql in Go: install and run a query

Updated · written with AI from the project's own documentation and checked against our catalogue data

graphql-go/graphql is an implementation of GraphQL for Go, and it follows the official graphql-js reference implementation. This guide shows Go developers how to install it, define a small schema in Go code, and run a query against that schema. By the end you will have a working program that prints a JSON response.

graphql-gographql-go/graphql · ★ 10.1k · MIT

Quick start

  1. 1Install Go. Make sure the Go toolchain is installed, because this is a Go library.
  2. 2Install the library. Run go get github.com/graphql-go/graphql in your project.
  3. 3Create a root query object. Use graphql.ObjectConfig and graphql.Fields to define the fields your API exposes.
  4. 4Build the schema. Pass the root query to graphql.SchemaConfig and call graphql.NewSchema, checking the error.
  5. 5Run a query. Create a graphql.Params with the schema and query string, then call graphql.Do.
  6. 6Read the result. Check r.Errors and marshal the result with encoding/json to see the data.

What is graphql-go/graphql?

GraphQL is a way for clients to ask an API for exactly the fields they need. graphql-go/graphql is a Go library that lets you define a GraphQL schema and run GraphQL queries against it from your own Go code.

The README says the library supports queries, mutations and subscriptions. It is a library, not a finished server, so you write the program that holds the schema and runs the queries.

Install graphql-go/graphql with go get

You need the Go toolchain installed, since this is a Go library. Install the library by running the command from the README in your project.

  • Prerequisite: Go
  • Install command: go get github.com/graphql-go/graphql
go get github.com/graphql-go/graphql

Define a schema with a field and a Resolve function

A schema is built in Go code. The README example defines a root query object with one field named hello. Its type is graphql.String, and its Resolve function returns the string world.

The schema is created from a graphql.SchemaConfig, which takes the root query object. graphql.NewSchema returns an error you should check.

  • graphql.Fields holds the fields of the root query object.
  • graphql.ObjectConfig gives the object a name, here RootQuery.
  • graphql.NewObject creates the object from that config.

Run a query and print the JSON result

To run a query, pass a graphql.Params value with the schema and a query string to graphql.Do. Check the Errors field of the result, then marshal the result to JSON.

The README notes that this program prints {"data":{"hello":"world"}}.

  • Params fields used in the example: Schema and RequestString.
  • graphql.Do returns a result with Errors and Data.
query := ` { hello } ` params := graphql.Params{Schema: schema, RequestString: query} r := graphql.Do(params)

Where to look for more complex examples

The README points to an examples/ directory and a graphql_test.go file in the repository for more complex usage. The full API reference is on pkg.go.dev, which the README links as the godoc documentation.

  • Repository examples: examples/ directory
  • Tests: graphql_test.go
  • API reference: pkg.go.dev/github.com/graphql-go/graphql

What people use it for

  • Expose a GraphQL API from a Go service so clients can request only the fields they need.
  • Build a schema in Go code instead of maintaining a separate schema file.
  • Match graphql-js behavior in a Go backend, since the library follows the graphql-js reference implementation.
  • Add GraphQL mutations and subscriptions to a Go service, as the README lists these as supported.

Frequently asked questions

How do I install graphql-go/graphql?

Run go get github.com/graphql-go/graphql from your Go project. The README lists Go as the prerequisite, so you need the Go toolchain installed first.

Is graphql-go/graphql free to use?

The project is licensed under the MIT licence, as listed on its page. Check the LICENSE file in the repository for the full terms.

Do I need Go to use graphql-go/graphql?

Yes. It is a Go library and needs a Go toolchain. People who do not write Go will not be able to use it directly.

Is graphql-go/graphql a ready-made GraphQL server?

No. The README describes a library, not a finished server or hosted app. You write the program that defines the schema and runs queries. For HTTP handling, the README lists graphql-go-handler as a third-party middleware.

How does graphql-go/graphql compare to gqlgen?

gqlgen is listed as a comparable project in our analysis, but the README does not compare the two. Check each project's documentation to decide which fits your schema style.

Why does my query return an error?

The README shows that graphql.Do returns errors in the result's Errors field, and the example logs them when present. Check the query string and the schema field names first, since the README example query asks for the hello field.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Go developers who want to expose a GraphQL API and define the schema in Go code will find this library a direct fit. People who do not write Go, or who want a ready-made server, should pick a different tool, such as one of the comparable projects listed here.

Install options & downloads