Advanced Queries with GraphQL+- - Slash graphql

Documentation
1

It is now possible to embed GraphQL+- queries inside your GraphQL schema, which is recommended for most use cases. The rest of this document covers how to connect to connect to your Slash GraphQL backend with existing Dgraph clients.

Slash GraphQL also supports running advanced queries with GraphQL+-, a query language that is unique to Dgraph. GraphQL+- should be used by advanced users who wish to make queries and mutations using existing Dgraph client libraries, either via the HTTP or gRPC endpoints. You can learn more about existing client libraries by following this documentation.

If you are getting started with Slash GraphQL, you might want to consider using our GraphQL APIs instead. It will get you quickly started on the basics of using Slash GraphQL before you go into advanced topics.

Please note that Slash GraphQL does not allow you to alter the schema or create new predicates via GraphQL+-. You will also not be able ta access the /alter endpoint or it’s gRPC equivalent. Please add your schema through the GraphQL endpoint (either via the UI or via the Admin API), before accessing the data with GraphQL+-.

Authentication

All the APIs documented here require an API token for access. Please see Authentication if you would like to create a new API token.

HTTP

You can query your backend with GraphQL+- using the /query endpoint of your cluster. As an example, if your graphql endpoint is https://frozen-mango-42.us-west-2.aws.cloud.dgraph.io/graphql, then the admin endpoint for schema will be at https://frozen-mango.us-west-2.aws.cloud.dgraph.io/query.

This endpoint works identically to to the /query endpoint of Dgraph, with the additional constraint of requiring authentication, as described in the Authentication section above.

You may also access the /mutate and /commit endpoints.

For the given GraphQL Schema:

type Person {
 name: String! @search(by: [fulltext])
 age: Int
 country: String
}

Here is an example of a cURL for /mutate endpoint:

curl -H "Content-Type: application/rdf" -H "x-auth-token: <api-key>" -X POST "<graphql-endpoint>/mutate?commitNow=true" -d $'
{
 set {
    _:x <Person.name> "John" .
    _:x <Person.age> "30" .
    _:x <Person.country> "US" .
 }
}'

Here is an example of a cURL for /query endpoint:

curl -H "Content-Type: application/graphql+-" -H "x-auth-token: <api-key>" -XPOST "<graphql-endpoint>/query" -d '{
   queryPerson(func: type(Person))  {
     Person.name
     Person.age
     Person.country
  }
}'

gRPC

The gRPC endpoint works identically to Dgraph’s gRPC endpoint, with the additional constraint of requiring authentication on every gRPC call. The Slash API token must be passed in the “Authorization” metadata to every gRPC call. This may be achieved by using Metadata Call Credentials or the equivalent in your language.

For example, if your GraphQL Endpoint is https://frozen-mango-42.eu-central-1.aws.cloud.dgraph.io/graphql, your gRPC endpoint will be frozen-mango-42.grpc.eu-central-1.aws.cloud.dgraph.io:443.

Here is an example which uses the pydgraph client to make gRPC requests.

For initial setup, make sure you import the right packages and setup your HOST and PORT correctly.

import grpc
import sys
import json
from operator import itemgetter
import pydgraph
GRPC_HOST = "frozen-mango-42.grpc.eu-central-1.aws.cloud.dgraph.io"
GRPC_PORT = "443"

You will then need to pass your API key as follows:

creds = grpc.ssl_channel_credentials()
call_credentials = grpc.metadata_call_credentials(lambda context, callback: callback((("Authorization", "<api-key>"),), None))
composite_credentials = grpc.composite_channel_credentials(creds, call_credentials)
client_stub = pydgraph.DgraphClientStub('{host}:{port}'.format(host=GRPC_HOST, port=GRPC_PORT), composite_credentials)
client = pydgraph.DgraphClient(client_stub)

For mutations, you can use the following example:

mut = {
  "Person.name": "John Doe",
  "Person.age": "32",
  "Person.country": "US"
}
txn = client.txn()
try:
  res = txn.mutate(set_obj=mut)
  print(ppl)
finally:
  txn.discard()

And for a query you can use the following example:

query = """
{
   queryPerson(func: type(Person))  {
     Person.name
     Person.age
     Person.country
  }
}"""
txn = client.txn()
try:
  res = txn.query(query)
  ppl = json.loads(res.json)
  print(ppl)
finally:
  txn.discard()

Limitations

It should be possible to use most GRPC based libraries to access your Slash GraphQL backend.

We will be adding support to ratel and dgraph-js-http soon. Please join our community for release announcements.

This is a companion discussion topic for the original entry at https://dgraph.io/docs/slash-graphql/advanced-queries/
2

I think this article is out-of-date as it conflicts with this page, which states

provides users access to advanced Dgraph features like directly altering the schema with the /alter HTTP and GRPC endpoints

This page says

Note Slash GraphQL does not allow you to alter the schema or create new predicates using DQL. You also can’t access the /alter endpoint or it’s gRPC equivalent.

5

Hi @freb! Thanks for noting that outdated statement in our docs. This is now fixed.

1 Like