Queries
{ user { id name } }Shorthand query - implicit query operationquery GetUser { user { id name } }Named query operationquery { user(id: 1) { name email } }Query with field argumentquery { user { name address { city country } } }Nested field selectionquery { user { name createdAt: created_at } }Field alias - rename in responsequery { a: user(id: 1) { name } b: user(id: 2) { name } }Multiple aliased fields of same typequery { users { id } posts { id } }Multiple root fields in one queryquery { user { friends { name } } }Nested object fieldsVariables
query GetUser($id: ID!) { user(id: $id) { name } }Declare variable with ! = requiredquery Search($q: String, $limit: Int = 10) { ... }Optional variable with default value{ "id": "123" }Pass variables as JSON alongside the queryquery ($ids: [ID!]!) { users(ids: $ids) { name } }List variablemutation CreateUser($input: UserInput!) { createUser(input: $input) { id } }Input object variableMutations
mutation { createUser(name: "Alice") { id name } }Basic mutationmutation AddUser($name: String!) { createUser(name: $name) { id } }Mutation with variablemutation { updateUser(id: 1, input: { name: "Bob" }) { id name } }Mutation with inline inputmutation { deleteUser(id: 1) }Mutation returning scalarmutation { a: createUser(name: "A") { id } b: createUser(name: "B") { id } }Multiple mutations - execute sequentiallyFragments
fragment UserFields on User { id name email }Define a named fragment on a typequery { user { ...UserFields } }Spread fragment into a selection setquery { user { ...UserFields } post { author { ...UserFields } } }Reuse fragment across multiple places... on User { name }Inline fragment - apply fields if type matches{ search { ... on User { name } ... on Post { title } } }Inline fragments for union/interface typesfragment F on User { friends { ...F } }Recursive fragment (use with caution)Directives
field @include(if: $show)Include field only if $show is truefield @skip(if: $hide)Skip field if $hide is truequery GetUser($withEmail: Boolean!) { user { name email @include(if: $withEmail) } }@include with variable@deprecated(reason: "Use newField instead")Schema directive - mark field as deprecated@specifiedBy(url: "...")Schema directive - custom scalar specification URLdirective @auth(role: String!) on FIELD_DEFINITIONCustom directive definition in schemaSchema & Types
type User { id: ID! name: String! email: String age: Int }Object type - ! means non-nulltype Query { user(id: ID!): User users: [User!]! }Root Query typetype Mutation { createUser(name: String!): User }Root Mutation typetype Subscription { userCreated: User }Root Subscription typescalar DateCustom scalar typeenum Role { ADMIN USER GUEST }Enum typeinterface Node { id: ID! }Interface - shared fields across typestype User implements Node { id: ID! name: String! }Type implementing an interfaceunion SearchResult = User | Post | CommentUnion type - one of multiple typesinput CreateUserInput { name: String! email: String! }Input object type - for mutation arguments[String]Nullable list of nullable strings[String!]!Non-null list of non-null stringstype User { posts(limit: Int = 10): [Post!]! }Field with argument and defaultschema { query: Query mutation: Mutation subscription: Subscription }Explicit schema definition (optional if using default names)Subscriptions
subscription { userCreated { id name } }Basic subscriptionsubscription OnMessage($roomId: ID!) { messageAdded(roomId: $roomId) { text author } }Subscription with variabletype Subscription { userCreated: User! }Subscription type in schemaIntrospection
{ __schema { types { name } } }List all types in schema{ __schema { queryType { name } mutationType { name } } }Show root operation types{ __type(name: "User") { fields { name type { name } } } }Inspect fields of a specific type{ __type(name: "User") { kind name description } }Inspect type kind and description{ __schema { directives { name args { name } } } }List all directives{ field { __typename } }__typename - returns the type name of the object{ __typename }Query root type nameHTTP Transport
POST /graphql Content-Type: application/jsonStandard HTTP transport{ "query": "{ user { name } }", "variables": {}, "operationName": "GetUser" }Request body shape{ "data": { "user": { "name": "Alice" } } }Success response body{ "data": null, "errors": [{ "message": "Not found", "locations": [...], "path": [...] }] }Error response bodyGET /graphql?query={user{name}}GET request for queries (not mutations)Authorization: Bearer tokenAuth header - same as RESTmultipart/form-data + map + operationsFile upload via GraphQL multipart spec