Getting Started with ElasticGraph
+ +Welcome to ElasticGraph! This guide will help you set up ElasticGraph locally, run queries using GraphiQL, and verify the datastore using the OpenSearch Dashboard. By the end of this tutorial, you’ll have a working ElasticGraph instance running on your machine.
+ +Estimated Time to Complete: Approximately 2 hours
+ +Prerequisites
+ +Before you begin, ensure you have the following installed on your system:
+ +-
+
- Git: For cloning repositories. +
- Docker: For running services locally. +
- Ruby (version 3.2 or higher) and Bundler: For running ElasticGraph scripts. +
- OpenSearch and Kibana: Included in the Docker setup. +
Step 1: Clone the ElasticGraph Repository
+ +Begin by cloning the ElasticGraph project template from GitHub:
+ +git clone <COMING SOON>!
+cd elasticgraph-project-template
+Step 2: Run the Initialization Script
+ +We have an initialization script that sets up your ElasticGraph project with necessary configurations.
+ +Run the following command in your terminal:
+ +curl -sL https://raw.githubusercontent.com/<COMING-SOON>/elasticgraph-project-template/main/script/init_eg | bash -s
+This script will prompt you for some inputs:
+ +-
+
- Application Name: Choose a name for your ElasticGraph application. +
- Dataset Name: Decide on a name for your dataset (e.g.,
customers).
+
The script will:
+ +-
+
- Set up directory structures. +
- Copy templated files. +
- Install necessary dependencies. +
Step 3: Define Your Schema
+ +ElasticGraph uses schemas to define the structure of your data.
+ +You can skip this part for now if you want to play with the sample schema. Otherwise, follow these steps to define your own schema:
+ +-
+
-
+
Remove Sample Schema:
+ +Delete the sample schema file:
+ ++rm config/schema/people.rb +
+ -
+
Create Your Schema:
+ +Create a new file in
+ +config/schema/named after your dataset, for example,config/schema/customers.rb.Define your schema in this file. Here’s a basic example:
+ ++module Schema + module Customers + extend ElasticGraph::Schema + + type :customer do + field :id, :string + field :name, :string + field :email, :string + end + end +end +
+ -
+
Update Configuration:
+ +Ensure that your dataset is correctly referenced in your configuration files.
+ +-
+
-
+
config/settings/lambda.yaml:
+ +Update or add your dataset name under the
+datasetssection.
+
+ -
+
Step 4: Build and Test Your Project
+ +-
+
-
+
Install Dependencies:
+ ++bundle install +
+ -
+
Run Rake Tasks:
+ +Test your setup by running:
+ ++ +bundle exec rake +This command runs all the default tasks to ensure everything is configured correctly.
+
+ -
+
Fix Any Issues:
+ +If you encounter errors, follow the error message prompts to fix anything that isn’t set up correctly.
+
+
Step 5: Start ElasticGraph Locally
+ +With Docker running, start your local ElasticGraph instance:
+ +bundle exec rake boot_locally
+This command will:
+ +-
+
- Build Docker images for ElasticGraph and OpenSearch. +
- Start the services using Docker Compose. +
- Populate your dataset with fake data. +
- Launch GraphiQL in your default web browser. +
Step 6: Use GraphiQL to Run Queries
+ +GraphiQL is a graphical interactive in-browser GraphQL IDE.
+ +Once GraphiQL opens in your browser, you can start running queries against your local ElasticGraph instance.
+ +Example Query
+ +Replace customers and fields with those relevant to your schema.
query Test {
+ customers {
+ totalEdgeCount
+ nodes {
+ id
+ name
+ email
+ }
+ }
+}
+Explanation:
+ +-
+
- customers: The dataset you defined. +
- totalEdgeCount: Returns the total number of records. +
- nodes: An array of data nodes. +
- fields inside nodes: The fields you’ve defined in your schema. +
Learn more about ElasticGraph queries in the Query API documentation.
+ +Step 7: Access the OpenSearch Dashboard (aka Elasticsearch Kibana)
+ +With bundle exec rake boot_locally still running:
-
+
-
+
Open Dashboard:
+ +Navigate to http://localhost:5601 in your web browser.
+
+ -
+
Explore Your Data:
+ +-
+
- Click on “Dev Tools” in the Kibana sidebar. +
-
+
Run the following commands to explore your indices:
+ +
+GET /_cat/indices?v +GET /_cat/shards?v +GET /_cat/templates?v +
+
+ -
+
Search Your Data:
+ +Replace
+ +your-index-namewith the name of your index (usually your dataset name).
+ +GET /your-index-name/_search +This will return all documents in your index. Normally you’ll query via GraphiQL, but this is useful for debugging.
+
+
Troubleshooting
+ +-
+
-
+
Docker Issues:
+ +-
+
- Ensure Docker is running. +
- If ports are already in use, stop other services or adjust the port settings in
docker-compose.yml.
+
+ -
+
GraphiQL Not Loading:
+ +-
+
- Verify that the local server is running. +
- Check for errors in the terminal where
boot_locallyis running.
+
+ -
+
Schema Errors:
+ +-
+
- Ensure your schema files are correctly formatted. +
- Check for typos in field names and types. +
+ -
+
Kibana Not Accessible:
+ +-
+
- Confirm that Kibana is running (
docker psto see running containers).
+ - Check if another service is using port
5601.
+
+ - Confirm that Kibana is running (
Next Steps
+ +Congratulations! You’ve set up ElasticGraph locally and run your first queries.
+ +-
+
-
+
Explore Advanced Features:
+ +-
+
- Learn about custom resolvers. +
- Implement complex queries and mutations. +
+ -
+
Connect to Real Data Sources:
+ +-
+
- Replace fake data with real data ingestion pipelines. +
- Integrate with databases or APIs. +
+ -
+
Contribute to ElasticGraph:
+ +-
+
- Report issues or suggest features on GitHub. +
- Submit pull requests to improve the project. +
+
Resources
+ +-
+
- ElasticGraph Documentation: /elasticgraph/docs/main +
- GraphQL Introduction: https://graphql.org/learn/ +
- OpenSearch Documentation: https://opensearch.org/docs/latest/ +
Feedback
+ +We’d love to hear your feedback. If you encounter any issues or have suggestions, please open an issue on our GitHub repository.
+ ++ +
Happy coding with ElasticGraph!
+ +