Connect to the Explorer

The GraphiQL Explorer is a web-based IDE that is a useful tool for exploring GraphQL operations and their responses while developing. It is built into Realm Studio 3.5.0 and later, but can also be accessed from a standard web browser.

From Studio

Connecting to the GraphiQL explorer that is packaged with Studio is the easiest way to get started because it will automatically construct the correct URL and send the correct authorization headers. To connect via Studio, click on a Realm in the Realms tab, then press the Open with GraphiQL button:

From a web browser

To connect to the explorer via a web browser, navigate to https://ROS-URL:ROS-PORT/graphql/explore/__admin

This will open the GraphiQL explorer for the /__admin Realm. To navigate to a different Realm, just replace the __admin segment with the desired relative path. GraphiQL Explorer endpoints are subject to the same authentication rules as regular GraphQL endpoints, so unless you've disabled authentication, you'll need to include authorization headers in your requests. If you're using Chrome, you can use an extension, such as ModHeader to inject the header into your requests.

Example URLs

It should be fairly simple to construct your URL, but there are a few common gotchas:

• Our cloud does not require a port number

• Our cloud uses secure https

• If you are just getting started with self-hosted Realm Object Server, it is likely that you have not secured your server and are therefore using the http protocol over port 9080

Example self-hosted URL:http://localhost:9080/graphql/explore/__admin

Example cloud URL: https://your-cloud-url/graphql/explore/__admin

Querying

To query, start with a query node. All possible query nodes should be suggested by the auto-completion engine. The query must explicitly specify all object properties/relationships you want included in the return.

Query for all objects of a certain type

All object types have a pluralized node, e.g. users, accounts, etc. Pluralized node requests accept the following optional arguments:

• query: a verbatim realm.js query that will be used to filter the returned dataset.

• sortBy: the property to sort all returned objects by.

• descending: sorting direction (default is false).

• skip: offset to start taking objects from.

• take: maximum number of items to return.

Query for a specific object by primary key

Object types that have a primary key defined will have a singularized node, e.g. user, realmFile, etc. A singularized node accepts a single argument: the primary key of the object.

Mutating

To mutate an object, start with a mutation node. All possible mutation methods should be suggested by the autocompletion engine. The returned values are objects themselves, so again, you should explicitly specify the requested properties .

Add an Object

To add an object to a realm, use the create<ObjectType> mutation for the object type and specify the object in the input parameter with the appropriate<ObjectType>Inputinput type.

mutation CreateNewUser($user: UserInput!) {
  createUser(input: $user) {
    name
  }
}

To add multiple instances of an object type, use the create<ObjectType>s mutation for the object type and specify the objects in the input parameter as an array of the appropriate <ObjectType>Input input type.

mutation CreateNewUsers($users: [UserInput]!) {
  createUsers(input: $users) {
    name
  }
}

Realm automatically adds any related objects that you include in the input, e.g. if you specify threeaccounts in the addUserinput, Realm will also add the account objects.

Update an Object

To update an object, use the create<ObjectType> mutation for the object type with a value set for the updatePolicy parameter. Specify the object in the input parameter with the appropriate<ObjectType>Inputinput type.

mutation UpdateExistingUser($user: UserInput!) {
  createUser(input: $user, updatePolicy: MODIFIED) {
    name
  }
}

To update multiple instances of an object type, use the create<ObjectType>s mutation for the object type with a value set for the updatePolicy parameter. Specify the objects in the input parameter as an array of the appropriate <ObjectType>Input input type.

mutation UpdateExistingUsers($users: [UserInput]!) {
  createUsers(input: $users, updatePolicy: MODIFIED) {
    name
  }
}

The value of updatePolicy determines how Realm handles the update operation. You may choose any of the following update policies:

Delete an Object

If an object type has a primary key, use the delete<ObjectType> mutation for the object type and specify the object's primary key value in the id parameter. The mutation returns true if the object was deleted, and false if it was not.

mutation DeleteUser($userId: String!) {
  deleteUser(id: $userId)
}

To delete one or more objects of an object type, use the delete<ObjectType>s mutation for the object type and specify a realm-js query in the query parameter. The mutation deletes all objects that match the specified query. If you omit the query parameter, then the mutation deletes all objects of the specified type. The mutation returns true if the objects were deleted, and false if they were not.

mutation DeleteUsers($query: String!) {
  deleteUsers(query: $query)
}

Subscribing

You can subscribe to change notifications by starting a subscription node at the endpoint ws://ROS-URL:ROS-PORT/graphql/:path.

Subscribing to Query Notifications

All object types have a pluralized node, e.g. users, accounts, etc. Start a pluralized node to subscribe to notification about all objects of that type. Every time an item is added, deleted, or modified in the dataset, the updated state will be pushed via the subscription socket. The node accepts the following optional arguments:

• query: a verbatim realm.js query that will be used to filter the returned dataset.

• sortBy: a property on the object to sort by.

• descending: sorting direction (default is false).

• skip: offset to start taking objects from.

• take: maximum number of items to return.

Using GraphiQL with subscriptions

When you navigate to http://localhost:9080/graphql/explore/:path, you can subscribe by creating a subscription node. The initial (current) dataset will be sent immediately. upon subscribing. Subsequently, whenever the Realm changes, an update containing the matching dataset will be pushed.

Inspecting the schema

You can see a Realm's schema Realm querying the __schema node (it will also include some built-in GraphQL types):

{
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}