2. Basic Query Syntax.md

Part 2: Basic Query syntax

GraphQL queries look a lot like JSON objects without data. I'm glad they did it this way.

Consider this JSON object:

// A JSON object
{
  "user": {
    "name": "Lee Byron"
  }
}

A similar GraphQL query would be:

// Request:
{
  user {
    name
  }
}

When the server responds it just pours data into those empty properties.

// Response:
{
  data: {
    user: {
      name: "Lee Byron"
    }
  }
}

Could it be any simpler than that!

Parameters

You can also use parameters in GraphQL queries:

//Request:
query fetchUser {
  user(id: "1") {
    name
  }
}

Now wait a minute! That looks more than the promised simple JSON object without data. What are those query and fetchUser things doing here? I hope you aren't trying to sell me OData disguised as graphshit! Are you?

I'm not. And I'm glad that you are paying attention. In my opinion, GraphQL's approach is much more elegant than that initiative of Microsoft.

Anatomy of a GraphQL Query:

Looking back again:

//Request:
query fetchUser {
  user(id: "1") {
    name
  }
}

• query is an GraphQL Operation. It, as you might guess, fetches the data from server. This query operation is read-only, you cannot modify data with it.

The other valid value for GraphQL operation is mutation, which we can use to create, update or delete data and fetch the updated result (doing CRUD, remember? Need to be able to do them all!). We'll discuss more on mutations later.

• fetchUser is just an arbitrary name of your query. You'll write whatever you feel right here. A meaningful name will make sense later to other developers about what the query does in short. Yeah, that's one of the hardest things to do in computer science :( )!

• user is called a field. And name is a sub-field, you might say.

• id: "1" is the argument on the user field. Arguments are unordered, by the way. picture(width: 200, height: 100) and picture(height: 100, width: 200) means the same to a GraphQL server.

• And this whole darn thing is called a document.

---

However, if a query has no arguments or directives (we will discuss directives later, for now just assume it's another piece of the whole puzzle) or name, the query keyword can be omitted. GraphQL server will default to that. We used that shortcut with our first example above:

// Request:
{
  user {
    name
  }
}

Previous - What is GraphQL

Next - Querying with Field Aliases and Fragments