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.
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:
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.
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
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.
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.
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.
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 .
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>Input
input 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 addUser
input, Realm will also add the account objects.
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>Input
input 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:
Policy | Description |
NONE | Realm should not update the specified object. |
MODIFIED | Realm should update only those properties that are different between the input and the specified object. |
ALL | Realm should fully replace the specified object with the input . |
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)}
You can subscribe to change notifications by starting a subscription node at the endpoint ws://ROS-URL:ROS-PORT/graphql/:path
.
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.
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.
You can see a Realm's schema Realm querying the __schema
node (it will also include some built-in GraphQL types):
{__schema {types {namefields {name}}}}