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 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.

Querying for 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 .

Adding objects

All object types have an addObjectType node, e.g. addUser, addAccount, etc. The node accepts a single argument: the object to add. When an object is added through GraphiQL, related objects will also be added, e.g. specifying accounts in the addUser input will add the account objects.

Updating objects

Objects with primary key defined have an updateObjectType node, e.g. updateUser, updateRealmFile. It accepts a single argument: the object to update. Partial updates are allowed as long as the primary key value is specified.

Deleting an object

Objects with primary key defined have a deleteObjectType node, e.g. deleteUser, deleteRealmFile. It accepts a single argument that is the primary key of the object to delete. The return will be true if the object was deleted successfullly, and false if it was not.

Deleting Multiple Objects

All object types have a deleteObjectTypes node, e.g. deleteUsers, deleteAccounts, etc. It accepts a single optional argument - query that will be used to filter objects to be deleted. If no query argument is supplied, all objects of the type will be deleted.

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
      }
    }
  }
}