はじめに

Shopify AI ToolkitやSidekickの情報を調べていると、「GraphQL」という言葉がやたら出てきます。

  • GraphQLって何？SQLの仲間？
  • REST APIとの違いがわからない
  • なんでShopifyはGraphQLを使っているの？
  • 自分には関係ない技術だと思っていたけど、最近よく見る

このような方のための記事です。

この記事では、GraphQLの基本概念をShopifyの文脈に沿って、プログラミング経験がなくても理解できるレベルで解説します。

GraphQLとは？ 一言で言うと

GraphQL（グラフキューエル）は、「欲しいデータだけを、欲しい形で取得できる仕組み」 です。

2015年にFacebook（現Meta）が公開した技術で、APIの新しい設計方法として世界中で普及しています。

Shopify、GitHub、Twitter（現X）、Netflixなど、大手テック企業がこぞって採用しています。

外部記事GraphQL | The query language for modern APIsGraphQL | The query language for modern APIs

名前に「SQL」が入っていますが、データベースを直接操作するSQLとは別物です。

「API（アプリ同士のやりとり）のためのクエリ言語」と覚えてください。

レストランで理解するGraphQL

GraphQLを理解するために、レストランの注文に例えて説明します。

REST API = セットメニューのレストラン

従来のREST APIは、セットメニューしかないレストランのようなものです。

「商品の情報がほしい」とお店（サーバー）に伝えると、商品名、説明文、価格、在庫数、画像URL、SEO情報、作成日、更新日......と、メニューに載っている全部の情報がドンと返ってきます。

本当は商品名と価格だけでよかったのに、大量のデータが付いてくる。これが 「オーバーフェッチ（取りすぎ）」 と呼ばれる問題です。

さらに、商品情報と一緒に注文情報もほしい場合、REST APIではそれぞれ別のカウンター（エンドポイント）に行って注文する必要があります。2回並ぶわけです。

オーバーフェッチ問題
オーバーフェッチ問題

GraphQL = 個別オーダーのレストラン

GraphQLは、メニューから好きなものだけ選べるレストランです。

「商品名と価格だけちょうだい」と伝えれば、商品名と価格だけが返ってきます。余計なデータはなし。

しかも、「ついでに最新の注文3件の合計金額もちょうだい」と1回の注文で複数のデータを同時にリクエストできます。カウンターは1つ。並ぶのも1回だけ。

GraphQLの個別オーダー
GraphQLの個別オーダー

REST APIとGraphQLの違い（まとめ）

項目

REST API

GraphQL

エンドポイント

リソースごとに複数

1つだけ

取得データ

サーバーが決めた固定セット

クライアントが指定

データの過不足

オーバーフェッチが起きやすい

必要なものだけ取得

複数データの取得

複数回のリクエストが必要

1回のリクエストで完結

学習コスト

低い（URLベースで直感的）

やや高い（クエリ言語を覚える）

採用企業

広く普及

Shopify, GitHub, Meta等

REST vs GraphQL の比較図
REST vs GraphQL の比較図

GraphQLの3つの操作

GraphQLでできる操作は、大きく分けて3つです。

1. Query（クエリ） — データを「読む」

データを取得するための操作です。REST APIでいう「GET」に相当します。

例えば、Shopifyストアの商品一覧を取得する場合:

query {
  products(first: 3) {
    edges {
      node {
        title
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

このクエリは「最初の3件の商品について、タイトルと最低価格だけ教えて」という意味です。必要な情報だけを波括弧 {} の中に書くことで、返ってくるデータを完全にコントロールできます。

2. Mutation（ミューテーション） — データを「書き換える」

データの作成・更新・削除を行う操作です。REST APIでいう「POST」「PUT」「DELETE」に相当します。

例えば、商品の価格を更新する場合:

mutation {
  productUpdate(
    input: {
      id: "gid://shopify/Product/12345"
      title: "新しい商品名"
    }
  ) {
    product {
      title
    }
    userErrors {
      field
      message
    }
  }
}

「この商品のタイトルを変更して、結果としてタイトルを返して。エラーがあればそれも教えて」という意味です。

3. Subscription（サブスクリプション） — データの「変更を監視する」

データが変更されたときにリアルタイムで通知を受ける仕組みです。

Shopifyでは Webhook がこの役割を担っているため、Subscriptionを直接使う場面は少ないですが、GraphQLの基本機能として覚えておくと全体像が掴めます。

3つの主要操作
3つの主要操作

ShopifyがGraphQLを採用した理由

ShopifyはもともとREST APIを提供していましたが、2018年頃からGraphQL APIへの移行を進めています。その理由は下記のようなものです。

1. ECデータは関連が複雑

ECサイトのデータは、商品→バリアント→在庫→注文→顧客→配送......と、データ同士が複雑に関連し合っています。

REST APIだと、これらを取得するために何度もリクエストを送る必要がありました。

GraphQLなら1回のリクエストで関連データを一気に取得できます。

2. モバイル・アプリの増加

Shopifyのモバイルアプリや、サードパーティアプリが増えたことで、「必要なデータだけ効率的に取る」ニーズが高まりました。

モバイル回線では、無駄なデータ転送はパフォーマンスに直結します。

3. REST APIの限界

ShopifyのREST APIはバージョンが上がるたびに新しいエンドポイントが増え続け、管理が複雑になっていました。

GraphQLなら単一のエンドポイントでスキーマを拡張するだけなので、APIの進化がシンプルになります。

現在、Shopifyの新機能はGraphQL API優先で提供されています。一部の機能はGraphQLでしか使えません。

REST APIも引き続き利用可能ですが、将来的にはGraphQLが主流になることは間違いありません。

外部記事GraphQLを始めよう - Shopify 日本GraphQLを始めよう - Shopify 日本

ShopifyのどこでGraphQLが使われている？

ShopifyでGraphQLが関わっている主な領域を整理します。

GraphQL Admin API

ストアの管理操作（商品管理、注文処理、顧客管理など）に使うAPIです。

Shopifyアプリ開発者が最も頻繁に使います。

Storefront API

オンラインストアのフロントエンド（お客さんが見る側）向けのAPIです。

ヘッドレスコマースやカスタムストアフロントの構築に使われます。

Shopify Flow

ストア運営の自動化ツールです。

内部的にGraphQL Admin APIを使っており、2026年にはAPI 2026-01バージョンに移行しました。

Flowのカスタムアクションを作る際にGraphQLの知識が役立ちます。

AI Toolkit / Dev MCP

AI Toolkitは、Dev MCPサーバー、agent skills、Shopify CLIを束ねた開発者向けプラグインです。

Dev MCPサーバー単体はドキュメント検索とスキーマ検証を担当し、ストア操作の実行はAI Toolkitプラグインに含まれる`shopify-admin-execution`スキルが、Shopify CLIの`store execute`機能を経由して行います。

Claude CodeやCursorで「商品一覧を取得して」と頼むと、裏側ではGraphQLクエリが走っています。

AI Toolkitについて詳しくは下記の記事で解説しています。

外部記事Shopify AI Toolkitとは？Claude Codeでの導入手順とサードパーティスキルからの移行体験Shopify AI Toolkitとは？Claude Codeでの導入手順とサードパーティスキルからの移行体験

ShopifyQL

Shopify独自の分析クエリ言語です。

名前が似ていますが、GraphQLとは別物です。

ただし、ShopifyQLのクエリはGraphQL Admin API経由で実行できます（shopifyqlQuery）。

ShopifyエコシステムによるGraphQL
ShopifyエコシステムによるGraphQL

実際にGraphQLを触ってみよう

「概念はわかったけど、実際に動かしてみたい」という方のために、最も簡単な方法を紹介します。

Shopify GraphiQL App を使う

Shopifyが公式に提供しているGraphiQLアプリを使えば、ブラウザ上でGraphQLクエリを書いて即座に実行できます。

外部記事Shopify GraphiQL App — Install

手順:

  1. 開発ストアを作成する
  2. GraphiQL アプリをインストールする
  3. 左側のエディタにクエリを入力
  4. 再生ボタンを押して実行
  5. 右側に結果が表示される
GraphiQL Appの画面
GraphiQL Appの画面

最初に試すクエリ

まずはストア情報を取得するシンプルなクエリから試してみてください。

query {
  shop {
    name
    email
    myshopifyDomain
    plan {
      displayName
    }
  }
}

これは「ストアの名前、メールアドレス、ドメイン、プラン名を教えて」という意味です。実行すると、以下のようなレスポンスが返ってきます。

{
  "data": {
    "shop": {
      "name": "My Store",
      "email": "owner@example.com",
      "myshopifyDomain": "my-store.myshopify.com",
      "plan": {
        "displayName": "Development"
      }
    }
  }
}

リクエストした項目だけが返ってきていることがわかります。これがGraphQLの基本です。

次に試すクエリ

慣れてきたら、商品データの取得も試してみてください。

query {
  products(first: 5) {
    edges {
      node {
        title
        status
        totalInventory
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

edges と node が出てきますが、これはGraphQLの「ページネーション」の書き方です。最初は「こういうものか」くらいの理解で大丈夫です。

実務で体感したGraphQLの進化 — ストア構築の3段階

ここからは、実際にクライアント案件でShopifyストアを構築している中で体感した「GraphQLとの付き合い方の変化」を共有します。

Shopifyストアの構築作業は、この数年で大きく3段階に進化しています。

実務で体感したGraphQLの進化 — ストア構築の3段階
実務で体感したGraphQLの進化 — ストア構築の3段階

第1段階: 管理画面でポチポチ入力

最も基本的な方法です。

Shopifyの管理画面から、商品名・説明文・価格・画像......を1つずつ手入力していきます。

正直に言うと、これがとにかくしんどい。

商品を1つ登録するだけでも、基本情報を入力して保存を待って、次にバリアントを設定して保存を待って、画像をアップロードして保存を待って、メタフィールドを入力して保存を待って......という具合に、ページ移動と保存の待ち時間が積み重なります。

10商品くらいなら我慢できますが、50商品、100商品となると作業量が膨れ上がります。

クライアントからもらった商品データを1件ずつコピペしていく作業は、率直に言って「人間がやるべき仕事ではない」と感じていました。

第2段階: Claude CodeでGraphQLを書いて実行

管理画面の入力が限界だと感じて辿り着いたのが、GraphQLを使った一括処理です。

やり方はシンプルです。Claude Code（AIコーディングアシスタント）に「この商品データをShopifyに登録するGraphQLミューテーションを書いて」と指示します。

すると、商品登録用のGraphQLクエリが生成されます。

それをShopify GraphiQL Appにコピペして実行する。

これだけで、管理画面で10分かかっていた商品登録が数秒で終わります。

実際にやっていたこと:

  • テスト商品の一括登録
  • クライアントからもらった商品データ（CSV等）をGraphQLミューテーションに変換して一括投入
  • 記事やページコンテンツの一括登録
  • メタフィールドの一括更新

管理画面のポチポチ作業から解放されたのは本当に大きかった。

ただし、この方法には1つ面倒な点がありました。Claude Codeでクエリを生成した後、GraphiQL Appに切り替えてコピペして実行するという手動の中継作業が毎回発生することです。

第3段階: AI Toolkit で直接実行

2026年4月にShopify AI Toolkitがリリースされて、この中継作業が消えました。

AI Toolkitプラグインに含まれる`shopify-admin-execution`スキルが、Shopify CLIの`store execute`機能を呼び出して、Claude Codeから直接GraphQLをストアに実行できます。

つまり、「この商品を登録して」と指示するだけで、クエリの生成から実行まで一気通貫で完了します。

GraphiQL Appにコピペする必要も、ブラウザを切り替える必要もない。Claude Codeのターミナル上で全て完結します。

これがAI Toolkitの一番大きな価値だと感じています。

ドキュメント検索やスキーマ検証も便利ですが、実務の作業時間を劇的に短縮してくれるのは「GraphQL直接実行」の部分です。

なお、初回のみ`shopify store auth`コマンドでストアとの認証を通しておく必要があります。

shopify store auth --store your-store.myshopify.com --scopes read_products,write_products

--storeには対象ストアのmyshopify.comドメイン、`--scopes`にはアプリで使いたいAdmin APIスコープをカンマ区切りで指定します。トークンはローカルに保存され、スコープが足りなくなったり期限切れになったら同じコマンドを再実行すればOKです。

一度認証すれば、以降はClaude Codeからシームレスに操作できます。

GraphQLを理解する意味

「AI Toolkitが全部やってくれるなら、GraphQLを理解する必要ないのでは？」と思うかもしれません。

確かに、AI Toolkitを使えばGraphQLを一行も書かずにストア操作ができます。

ただ、AIが生成したクエリが意図通りに動いているかを確認したり、エラーが出たときにどこが問題かを判断したりするには、GraphQLの基本を知っている必要があります。

完璧に書ける必要はありません。「このクエリは何をやっているのか」が読めるだけで、AI Toolkitとの協業の質が大きく変わります。

さいごに

GraphQLは「欲しいデータだけを、欲しい形で、1回のリクエストで取得できる仕組み」です。

ShopifyがREST APIからGraphQLへ軸足を移しているのは、ECデータの複雑さを効率的に扱えるからです。

AI Toolkit、Shopify Flow、アプリ開発......今後Shopifyに関わるあらゆる場面でGraphQLは登場します。

まずはGraphiQL Appでシンプルなクエリを1つ実行してみてください。

Shopify開発に関するご相談は、お問い合わせからお気軽にどうぞ。