Getting Started with ElasticGraph

Welcome to ElasticGraph! This guide will help you set up ElasticGraph locally, run queries using GraphiQL, and evolve an example schema. By the end of this tutorial, you’ll have a working ElasticGraph instance running on your machine.

Estimated Time to Complete: 10 minutes

Prerequisites

Before you begin, ensure you have the following installed on your system:

  • Docker and Docker Compose
  • Ruby (version 3.3 or higher)
  • Git

Confirm these are installed using your terminal:

$ ruby -v
ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24]
$ docker compose version
Docker Compose version v2.32.4-desktop.1
$ git -v
git version 2.46.0

Note You don’t need these exact versions (these are just examples). Your Ruby version does need to be 3.3.x or greater, though.

Step 1: Bootstrap a new ElasticGraph Project

Run one of the following commands in your terminal:

$ gem exec elasticgraph new path/to/project --datastore elasticsearch

$ gem exec elasticgraph new path/to/project --datastore opensearch

Note Not sure whether to use Elasticsearch or OpenSearch? We recommend using whichever has better support in your organization. ElasticGraph works identically with both, and the choice makes no difference in the tutorial that follows.

This will:

  • Generate a project skeleton with an example schema
  • Install dependencies including the latest version of ElasticGraph itself
  • Dump schema artifacts
  • Run the build tasks (including your new project’s test suite)
  • Initialize the project as a git repository
  • Commit the initial setup

Step 2: Boot Locally

The initial project skeleton comes with everything you need to run ElasticGraph locally. Confirm it works by running the following:

$ cd path/to/project && bundle exec rake boot_locally

This will:

  • Boot the datastore (Elasticsearch or OpenSearch) using Docker
  • Configure the datastore using the dumped datastore_config.yaml schema artifact
  • Index some randomly generated artists/albums/tours/shows/venues data
  • Boot ElasticGraph and a GraphiQL UI
  • Open the local GraphiQL UI in your browser

Run some example queries in GraphiQL to confirm it’s working. Here’s an example query to get you started:

query FindArtistsFormedIn90s {
  artists(filter: {
    bio: {yearFormed: {gte: 1990, lt: 2000}}
  }) {
    nodes {
      name
      bio {
        yearFormed
      }
      albums {
        name
      }
    }
  }
}

Visit the Query API docs for other example queries that work against the example schema.

Step 3: Add a new field to the Schema

If this is your first ElasticGraph project, we recommend you add a new field to the example schema to get a feel for how it works. (Feel free to skip this step if you’ve worked in an ElasticGraph project before).

Let’s add a Venue.yearOpened field to our schema. Here’s a git diff showing what to change:

diff --git a/config/schema/artists.rb b/config/schema/artists.rb
index 77e63de..7999fe4 100644
--- a/config/schema/artists.rb
+++ b/config/schema/artists.rb
@@ -56,6 +56,9 @@ ElasticGraph.define_schema do |schema|
   schema.object_type "Venue" do |t|
     t.field "id", "ID"
     t.field "name", "String"
+    t.field "yearOpened", "Int" do |f|
+      f.json_schema minimum: 1900, maximum: 2100
+    end
     t.field "location", "GeoLocation"
     t.field "capacity", "Int"
     t.relates_to_many "featuredArtists", "Artist", via: "tours.shows.venueId", dir: :in, singular: "featuredArtist"

Next, rebuild the project:

$ bundle exec rake build

This will re-generate the schema artifacts, run the test suite, and fail. The failing test will indicate that the :venue factory is missing the new field. To fix it, define yearOpened on the :venue factory in the factories.rb file under lib:

diff --git a/lib/my_eg_project/factories.rb b/lib/my_eg_project/factories.rb
index 0d8659c..509f274 100644
--- a/lib/my_eg_project/factories.rb
+++ b/lib/my_eg_project/factories.rb
@@ -95,6 +95,7 @@ FactoryBot.define do
       "#{city_name} #{venue_type}"
     end

+    yearOpened { Faker::Number.between(from: 1900, to: 2025) }
     location { build(:geo_location) }
     capacity { Faker::Number.between(from: 200, to: 100_000) }
   end

Re-run bundle exec rake build and everything should pass. You can also run bundle exec rake boot_locally and query your new field to confirm the fake values being generated for it.

Next Steps

Congratulations! You’ve set up ElasticGraph locally and run your first queries. Here are some next steps you can take.

Replace the Example Schema

Delete the artist schema definition:

$ rm config/schema/artists.rb

Then define your own schema in a Ruby file under config/schema.

  • Use the schema definition API docs as a reference.
  • Use our AI Tools together with an LLM such as Goose to translate a schema from an existing format such as protocol buffers, JSON schema, or SQL.
  • Run bundle exec rake build and deal with any errors that are reported.
  • Hint: search the project codebase for TODO comments to find things that need updating.

Setup a CI Build

Your ElasticGraph project includes a command that’s designed to be run on CI:

$ bundle exec rake check

This should be run on every commit (ideally before merging a pull request) using a CI system such as Buildkite, Circle CI, GitHub Actions, or Jenkins.

Deploy

ElasticGraph can be deployed in two different ways:

Connect a Real Data Source

Finally, you’ll want to publish into your deployed ElasticGraph project from a real data source. The generated json_schemas.yaml artifact can be used in your publishing system to validate the indexing payloads or for code generation (using a project like json-kotlin-schema-codegen).

Resources

Feedback

We’d love to hear your feedback. If you encounter any issues or have suggestions, please start a discussion in our discord channel or on GitHub.

Happy coding with ElasticGraph!