GraphQL Queries

Available GraphQL queries in the EverShop application

Introduction

GraphQL queries allow you to fetch data from your EverShop application. This page documents all available queries across the application’s extensions.

Query Structure

Queries in EverShop follow the standard GraphQL query syntax:

query QueryName {
  fieldName(argument: value) {
    field1
    field2
    nestedObject {
      nestedField
    }
  }
}

Sample Extension Queries

The sample extension demonstrates basic query patterns with the Foo type.

Query: foo

Fetch a single Foo object by ID.

id · ID! · required

The unique identifier of the Foo object

foo · Foo

Returns a Foo object or null if not found

Show Foo fields

id · ID!

Unique identifier

name · String!

Name of the Foo object

description · String

Optional description

Query

query GetFoo {
  foo(id: "1") {
    id
    name
    description
  }
}

{
  "data": {
    "foo": {
      "id": "1",
      "name": "Foo",
      "description": "This is a Foo object"
    }
  }
}

Query: {
  foo: (root, { id }) => {
    return fooList.find((foo) => foo.id === id);
  }
}

Query: foos

Fetch all Foo objects.

foos · [Foo!]!

Returns an array of all Foo objects (never null)

Show Foo fields

id · ID!

Unique identifier

name · String!

Name of the Foo object

description · String

Optional description

Query

query GetAllFoos {
  foos {
    id
    name
    description
  }
}

{
  "data": {
    "foos": [
      {
        "id": "1",
        "name": "Foo",
        "description": "This is a Foo object"
      },
      {
        "id": "2",
        "name": "Bar",
        "description": "This is a Bar object"
      },
      {
        "id": "3",
        "name": "Baz",
        "description": "This is a Baz object"
      }
    ]
  }
}

Query: {
  foos: () => {
    return fooList;
  }
}

Product Extension Queries

The productCatalog extension extends the core Product type with supplement-specific data.

Extended Type: Product

When querying products, you can access supplement information through the extension field.

extension · ProductExtension

Additional product data extensions

Show ProductExtension fields

supplement · Supplement

Supplement-specific information

Show Supplement fields

ingredients · String

List of ingredients in the supplement

benefits · [String]

Array of health benefits

presentation · String

Product presentation format (capsules, powder, etc.)

dosage · String

Recommended dosage instructions

warnings · String

Usage warnings and contraindications

storage · String

Storage instructions

Query

query GetProductWithExtensions {
  product(id: "123") {
    id
    name
    price
    extension {
      supplement {
        ingredients
        benefits
        presentation
        dosage
        warnings
        storage
      }
    }
  }
}

{
  "data": {
    "product": {
      "id": "123",
      "name": "Vitamin D3 5000 IU",
      "price": 24.99,
      "extension": {
        "supplement": {
          "ingredients": "Vitamin D3 (as cholecalciferol), Extra virgin olive oil, Gelatin capsule",
          "benefits": [
            "Supports bone health",
            "Immune system support",
            "Maintains healthy calcium levels"
          ],
          "presentation": "Softgel capsules",
          "dosage": "Take 1 capsule daily with a meal",
          "warnings": "Consult your healthcare provider before use if pregnant or nursing",
          "storage": "Store in a cool, dry place away from direct sunlight"
        }
      }
    }
  }
}

Product: {
  extension: (product) => {
    return {
      supplement: {
        ingredients: product.ingredients || null,
        benefits: product.benefits ? JSON.parse(product.benefits) : null,
        presentation: product.presentation || null,
        dosage: product.dosage || null,
        warnings: product.warnings || null,
        storage: product.storage || null
      }
    };
  }
}

Query Examples in Components

Here’s how to use GraphQL queries in page components:

Basic Query Example

extensions/sample/src/pages/frontStore/fooList/FooList.tsx

import React from 'react';

type Foo = {
  id: string;
  name: string;
  description?: string;
};

type FooListProps = {
  foos?: Foo[];
};

export default function FooList({ foos = [] }: FooListProps) {
  return (
    <div className="foo-list">
      <h1>All Foos</h1>
      {foos.map((foo) => (
        <div key={foo.id} className="foo-item">
          <h2>{foo.name}</h2>
          {foo.description && <p>{foo.description}</p>}
        </div>
      ))}
    </div>
  );
}

export const layout = {
  areaId: 'content',
  sortOrder: 30
};

export const query = `
  query {
    foos {
      id
      name
      description
    }
  }
`;

Query with Arguments

export const query = `
  query GetFoo($fooId: ID!) {
    foo(id: $fooId) {
      id
      name
      description
    }
  }
`;

Query Best Practices

Request Only What You Need

Only query the fields you actually need to reduce data transfer and improve performance.

Use Fragments

Use GraphQL fragments to reuse common field selections across multiple queries.

Handle Null Values

Always check for null values in your components when fields are nullable.

Use Variables

Use query variables instead of string interpolation for dynamic values.

Error Handling

Queries can return errors in the response:

{
  "data": {
    "foo": null
  },
  "errors": [
    {
      "message": "Foo with id 999 not found",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["foo"]
    }
  ]
}

Always check both the data and errors fields in the GraphQL response.

Creating Custom Queries

To add a new query to your extension:

1. Define the query in your GraphQL schema:

   type Query {
     myCustomQuery(arg: String!): CustomType
   }
   

2. Implement the resolver:

   export default {
     Query: {
       myCustomQuery: (root, { arg }, context) => {
         // Implementation
         return customData;
       }
     }
   };
   

3. Use it in your components:

   export const query = `
     query {
       myCustomQuery(arg: "value") {
         field1
         field2
       }
     }
   `;
   

Next Steps

GraphQL Mutations

Learn how to modify data with mutations

GraphQL Overview

Review GraphQL architecture and concepts